funman300
f2f30c8002
Adopts the four-file rule set the player added to the working tree:
- CLAUDE.md grows from a 114-line pointer doc to the 571-line
`unified-3.0` rulebook: hard global constraints (§2), engine
rules (§3), asset rules (§4), code standards (§5), build +
verification (§6), git workflow (§7), the change-control
ASK BEFORE list (§8), and the Context Injection System (§14).
- CLAUDE_SPEC.md — formal architecture spec: crate dependency
graph with forbidden_deps, data ownership map, state-machine
invariants ("52 cards always exist", "no duplicate IDs",
"all cards belong to exactly one pile"), sync merge contract,
server contract, validation checklist.
- CLAUDE_WORKFLOW.md — two-agent Builder/Guardian pipeline with
hard-fail patterns that auto-reject (core uses IO/Bevy/network,
GameState mutated outside GameLogicSystem, blocking async on
main thread, duplicate logic, merge altered incorrectly).
- CLAUDE_PROMPT_PACK.md — task-type templates.
Three duplicate rule passages removed:
- CLAUDE_SPEC.md §0 dropped no_panics_in_core / core_is_pure /
event_driven_engine — already canonical in CLAUDE.md §2.1, §2.3,
§3.1. Kept single_source_of_truth and sync_is_additive (those
describe data flow, not in CLAUDE.md).
- CLAUDE_SPEC.md §11 Prohibited Patterns now references CLAUDE.md
§11 instead of restating the same five forbidden items.
- ARCHITECTURE.md Design Principles dropped the pure-core /
no-panics / UI-first bullets — those are enforcement constraints
living in CLAUDE.md §2.1, §2.3, §3.3; this file describes the
design that motivates them. Kept the offline-first, one-language,
and plugin-based-Bevy bullets (those are descriptive, not
enforcement).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
336 lines
4.5 KiB
Markdown
336 lines
4.5 KiB
Markdown
# CLAUDE_WORKFLOW.md
|
|
|
|
version: 1.0
|
|
|
|
---
|
|
|
|
## 0. Overview
|
|
|
|
This workflow defines a **two-agent system**:
|
|
|
|
* **Builder Agent** → writes and modifies code
|
|
* **Guardian Agent** → enforces architecture + rejects invalid changes
|
|
|
|
No code is considered valid unless it passes Guardian validation.
|
|
|
|
---
|
|
|
|
## 1. Agent Roles
|
|
|
|
### 1.1 Builder Agent
|
|
|
|
role: "code_generation"
|
|
|
|
responsibilities:
|
|
|
|
* implement features
|
|
* refactor code
|
|
* generate tests (only when justified)
|
|
* follow CLAUDE_SPEC.md
|
|
|
|
constraints:
|
|
|
|
* cannot bypass validation
|
|
* must declare intent before writing code
|
|
|
|
output_contract:
|
|
must_produce:
|
|
- change_summary
|
|
- files_modified
|
|
- reasoning (short)
|
|
- code_diff
|
|
|
|
---
|
|
|
|
### 1.2 Guardian Agent
|
|
|
|
role: "architecture_enforcement"
|
|
|
|
responsibilities:
|
|
|
|
* validate against CLAUDE_SPEC.md
|
|
* detect violations
|
|
* reject or approve changes
|
|
* suggest minimal fixes (not full rewrites)
|
|
|
|
constraints:
|
|
|
|
* no feature implementation
|
|
* no large rewrites
|
|
* must be deterministic
|
|
|
|
output_contract:
|
|
must_produce:
|
|
- status: APPROVED | REJECTED
|
|
- violations[]
|
|
- required_fixes[]
|
|
- optional_improvements[]
|
|
|
|
---
|
|
|
|
## 2. Workflow Pipeline
|
|
|
|
```text
|
|
User Request
|
|
↓
|
|
Builder Agent (proposal + code)
|
|
↓
|
|
Guardian Agent (validation)
|
|
↓
|
|
IF approved → commit
|
|
IF rejected → feedback → Builder retry
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Builder Protocol
|
|
|
|
### Step 1 — Intent Declaration
|
|
|
|
Builder MUST start with:
|
|
|
|
```yaml
|
|
intent:
|
|
feature: "<name>"
|
|
crates_touched: []
|
|
systems_affected: []
|
|
risk_level: low|medium|high
|
|
```
|
|
|
|
---
|
|
|
|
### Step 2 — Plan
|
|
|
|
```yaml
|
|
plan:
|
|
- step: "..."
|
|
- step: "..."
|
|
```
|
|
|
|
---
|
|
|
|
### Step 3 — Implementation
|
|
|
|
* Only modify declared crates
|
|
* Follow ownership rules
|
|
* Use events for cross-system communication
|
|
|
|
---
|
|
|
|
### Step 4 — Output
|
|
|
|
```yaml
|
|
change_summary: "..."
|
|
|
|
files_modified:
|
|
- path: ...
|
|
change: "..."
|
|
|
|
violations_self_check:
|
|
- none | list
|
|
|
|
notes: "short reasoning"
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Guardian Protocol
|
|
|
|
### Step 1 — Spec Validation
|
|
|
|
Check against:
|
|
|
|
* crate boundaries
|
|
* mutation rules
|
|
* event system usage
|
|
* sync guarantees
|
|
* forbidden patterns
|
|
|
|
---
|
|
|
|
### Step 2 — Invariant Validation
|
|
|
|
Must verify:
|
|
|
|
* GameState invariants preserved
|
|
* no new panic paths
|
|
* no blocking calls in engine
|
|
* merge properties unchanged
|
|
|
|
---
|
|
|
|
### Step 3 — Output Decision
|
|
|
|
#### APPROVED
|
|
|
|
```yaml
|
|
status: APPROVED
|
|
|
|
notes:
|
|
- "no violations"
|
|
```
|
|
|
|
---
|
|
|
|
#### REJECTED
|
|
|
|
```yaml
|
|
status: REJECTED
|
|
|
|
violations:
|
|
- id: core_purity_violation
|
|
file: "solitaire_core/src/..."
|
|
reason: "uses std::fs"
|
|
|
|
required_fixes:
|
|
- "move IO to solitaire_data"
|
|
|
|
optional_improvements:
|
|
- "simplify event naming"
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Enforcement Rules
|
|
|
|
### Hard Fail (automatic rejection)
|
|
|
|
* core crate uses IO / Bevy / network
|
|
* GameState mutated outside GameLogicSystem
|
|
* blocking async on main thread
|
|
* duplicate logic across crates
|
|
* merge function altered incorrectly
|
|
|
|
---
|
|
|
|
### Soft Fail (allowed but flagged)
|
|
|
|
* unnecessary complexity
|
|
* redundant tests
|
|
* minor architectural drift
|
|
|
|
---
|
|
|
|
## 6. Iteration Loop
|
|
|
|
Max attempts per task: **3**
|
|
|
|
```text
|
|
Attempt 1 → Reject → Fix
|
|
Attempt 2 → Reject → Fix
|
|
Attempt 3 → Final decision
|
|
```
|
|
|
|
If still failing:
|
|
→ escalate to user
|
|
|
|
---
|
|
|
|
## 7. Diff Strategy
|
|
|
|
Builder MUST produce:
|
|
|
|
* minimal diffs
|
|
* no unrelated refactors
|
|
* no formatting-only changes
|
|
|
|
---
|
|
|
|
## 8. Test Strategy Integration
|
|
|
|
Builder rules:
|
|
|
|
* only add tests if:
|
|
|
|
* fixing a bug
|
|
* protecting complex logic
|
|
* validating invariants
|
|
|
|
Guardian rejects:
|
|
|
|
* redundant tests
|
|
* no-op tests
|
|
|
|
---
|
|
|
|
## 9. Optional Extensions
|
|
|
|
### 9.1 Third Agent (Optimizer)
|
|
|
|
role: performance + cleanup
|
|
|
|
runs AFTER approval:
|
|
|
|
* reduce allocations
|
|
* simplify logic
|
|
* improve ECS scheduling
|
|
|
|
---
|
|
|
|
### 9.2 CI Integration
|
|
|
|
Pipeline:
|
|
|
|
```text
|
|
Builder → Guardian → cargo check → clippy → tests
|
|
```
|
|
|
|
Guardian runs BEFORE compilation to catch structural issues early.
|
|
|
|
---
|
|
|
|
## 10. Example Interaction
|
|
|
|
### Builder
|
|
|
|
```yaml
|
|
intent:
|
|
feature: "undo stack limit fix"
|
|
crates_touched: [solitaire_core]
|
|
risk_level: low
|
|
```
|
|
|
|
```yaml
|
|
change_summary: "limit undo stack to 64 entries"
|
|
|
|
files_modified:
|
|
- solitaire_core/src/game_state.rs
|
|
|
|
notes: "prevents unbounded memory growth"
|
|
```
|
|
|
|
---
|
|
|
|
### Guardian
|
|
|
|
```yaml
|
|
status: APPROVED
|
|
|
|
notes:
|
|
- "respects core constraints"
|
|
- "no invariant violations"
|
|
```
|
|
|
|
---
|
|
|
|
## 11. Mental Model
|
|
|
|
* Builder = **creative**
|
|
* Guardian = **strict**
|
|
|
|
Builder explores
|
|
Guardian enforces
|
|
|
|
Neither replaces the other.
|
|
|
|
---
|
|
|
|
## 12. Success Criteria
|
|
|
|
System is working if:
|
|
|
|
* architectural violations go to ~0
|
|
* code stays consistent across features
|
|
* refactors become safe
|
|
* complexity grows sub-linearly
|