Files

T

funman300 f2f30c8002 docs: adopt unified-3.0 Claude rule set + trim duplications

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>

2026-05-06 04:42:24 +00:00

4.5 KiB

Raw Blame History

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

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:

intent:
  feature: "<name>"
  crates_touched: []
  systems_affected: []
  risk_level: low|medium|high

Step 2 — Plan

plan:
  - step: "..."
  - step: "..."

Step 3 — Implementation

Only modify declared crates
Follow ownership rules
Use events for cross-system communication

Step 4 — Output

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

status: APPROVED

notes:
  - "no violations"

REJECTED

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

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:

Builder → Guardian → cargo check → clippy → tests

Guardian runs BEFORE compilation to catch structural issues early.

10. Example Interaction

Builder

intent:
  feature: "undo stack limit fix"
  crates_touched: [solitaire_core]
  risk_level: low

change_summary: "limit undo stack to 64 entries"

files_modified:
  - solitaire_core/src/game_state.rs

notes: "prevents unbounded memory growth"

Guardian

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

4.5 KiB Raw Blame History