Full reference for all four agents and all protocol step diagrams.
┌──────────────────────────────────────────────┐
│ ARCHITECT │
│ │
│ Role: Design, planning, roadmap │
│ │
│ Reads: PLAN.md · BACKLOG.md · MEMO.md │
│ GOLDEN_RULES.md │
│ Writes: PLAN.md · BACKLOG.md · MEMO.md │
│ LEDGER.md · INDEX.md (SHA only) │
│ │
│ Protocols: │
│ · roadmap-formalization │
│ · task-completion │
│ · codebase-audit │
└──────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│ PROGRAMMER │
│ │
│ Role: Implementation, execution │
│ │
│ Reads: PLAN.md · MEMO.md │
│ GOLDEN_RULES.md · CONVENTIONS.md │
│ REVIEW_CHECKLIST.md │
│ Writes: src/ (code) · MEMO.md │
│ │
│ Protocols: │
│ · feature-implementation │
│ · bug-fix │
└──────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│ INSPECTOR │
│ │
│ Role: Audit, quality gating │
│ │
│ Reads: MEMO.md · PLAN.md │
│ GOLDEN_RULES.md │
│ REVIEW_CHECKLIST.md · src/ files │
│ Writes: MEMO.md (verdict + reports only) │
│ │
│ Protocols: │
│ · task-audit │
└──────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│ CLERK │
│ │
│ Role: Meta-questions, documentation │
│ │
│ Reads: Any doc file as needed │
│ Writes: IDENTITY.md files · INDEX.md │
│ GEMINI.md · shared docs │
│ │
│ Protocols: │
│ · index-update │
└──────────────────────────────────────────────┘
architect.roadmap-formalization Promotes an item from BACKLOG.md (or a fresh user description) into a fully specified PLANNED entry in PLAN.md.
Item from BACKLOG.md or user description
│
▼
┌──────────────────────────────┐
│ 1. MIRROR & INTERPRET │ confirm source · restate intent · clarify scope
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 2. GOLDEN RULE ANALYSIS │ identify which rules the task touches
└───────────────┬──────────────┘ flag implications (transactions · disk ops · IPC)
│
▼
┌──────────────────────────────┐
│ 3. SUB-STEP BREAKDOWN │ decompose into atomic, individually testable steps
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 4. HANDOFF SPECIFICATION │ target files · constraints · Golden Rule touchpoints
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 5. PROPOSE & WRITE │ add task to PLAN.md (standalone or under Epic)
└──────────────────────────────┘ remove item from BACKLOG.md if sourced there
architect.task-completion Closes a completed task after INSPECTOR PASS. Archives and resets pipeline state.
INSPECTOR issues PASS
│
▼
┌──────────────────────────────┐
│ 1. MIRROR & INTERPRET │ confirm which task and step are being closed
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 2. DRIFT CHECK │ verify implementation matches design intent
└───────────────┬──────────────┘
│
├── DRIFT FOUND ──▶ flag to user before proceeding
│
└── CLEAR
│
▼
┌──────────────────────────────┐
│ 3. UPDATE PLAN.md │ mark step complete
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 4. ARCHIVE TO LEDGER.md │ log completed task permanently
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 5. RESET MEMO.md │ clear with blank template
└──────────────────────────────┘ pipeline ready for next task
Periodic sweep of src/ for Golden Rule violations and structural risks.
USER triggers audit
│
▼
┌──────────────────────────────┐
│ 1. MIRROR & INTERPRET │ confirm scope (full or targeted)
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 2. RULE EXPOSURE MAP │ read GOLDEN_RULES.md · identify most exposed files
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 3. FILE AUDIT │ detect brittle logic:
└───────────────┬──────────────┘ unguarded assumptions · non-atomic ops
│ silent wrong results · order-dependent logic
▼
┌──────────────────────────────┐
│ 4. LOG FINDINGS │ append to BUGS.md
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 5. UPDATE INDEX.md │ record Last Codebase Audit commit SHA
└──────────────────────────────┘
programmer.feature-implementation Implements an assigned task step from PLAN.md.
USER assigns task step
│
▼
┌──────────────────────────────┐
│ 1. MIRROR & INTERPRET │ confirm target files and approach from PLAN.md
└───────────────┬──────────────┘ stop and report if plan conflicts with code
│
▼
┌──────────────────────────────┐
│ 2. PRE-FLIGHT │ read target files in full
└───────────────┬──────────────┘ verify code matches plan assumptions
│
▼
┌──────────────────────────────┐
│ BLAST RADIUS CHECK │
└───────────────┬──────────────┘
│
├── RED ──▶ Technical Blocker Report ──▶ MEMO.md ──▶ STOP
│
└── GREEN / YELLOW
│
▼
┌──────────────────────────────┐
│ 3. IMPLEMENT │ GOLDEN_RULES.md + CONVENTIONS.md
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 4. SELF-AUDIT │ REVIEW_CHECKLIST.md · all items pass
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 5. LOG & HAND-OFF │ append to MEMO.md Hand-off Notes
└──────────────────────────────┘ files changed · testing steps
Root-cause investigation and targeted repair for a known or reported bug.
Bug from BUGS.md or user description
│
▼
┌──────────────────────────────┐
│ 1. MIRROR & INTERPRET │ restate bug · suspected cause · likely files
└───────────────┬──────────────┘ ask if unclear before investigating
│
▼
┌──────────────────────────────┐
│ 2. ROOT CAUSE INVESTIGATION │ read codebase · find exact cause
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ BLAST RADIUS CHECK │
└───────────────┬──────────────┘
│
├── RED ──▶ Technical Blocker Report ──▶ MEMO.md ──▶ STOP
│
└── GREEN / YELLOW
│
▼
┌──────────────────────────────┐
│ 3. FIX │ targeted repair · no collateral changes
└───────────────┬──────────────┘ GOLDEN_RULES.md + CONVENTIONS.md
│
▼
┌──────────────────────────────┐
│ 4. SELF-AUDIT │ REVIEW_CHECKLIST.md · no new issues
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 5. LOG & HAND-OFF │ append to MEMO.md Hand-off Notes
└──────────────────────────────┘ root cause · fix · testing steps
mark resolved in BUGS.md if applicable
Validates a completed implementation against the plan, Golden Rules, and checklist.
PROGRAMMER signals completion
│
▼
┌──────────────────────────────┐
│ 1. MIRROR & INTERPRET │ read MEMO.md + PLAN.md
└───────────────┬──────────────┘ confirm target files and audit scope
│
▼
┌──────────────────────────────┐
│ 2. PLAN FIDELITY │ compare implementation against PLAN.md steps
└───────────────┬──────────────┘ all sub-steps satisfied?
│
▼
┌──────────────────────────────┐
│ 3. GOLDEN RULES + CHECKLIST │ zero-tolerance audit
└───────────────┬──────────────┘ GOLDEN_RULES.md + REVIEW_CHECKLIST.md
│ any violation = automatic FAIL
▼
┌──────────────────────────────┐
│ 4. VERDICT │
└───────────────┬──────────────┘
│
├── FAIL ──▶ Rectification Report (file · function · line · rule · reasoning)
│ └──▶ append to MEMO.md ──▶ PROGRAMMER fixes ──▶ re-audit
│
└── PASS
│
▼
┌──────────────────────────────┐
│ 5. LOG & HAND-OFF │ append verdict to MEMO.md Hand-off Notes
└──────────────────────────────┘ signal ARCHITECT for task-completion
Regenerates the Directory Tree and Quick Links sections of INDEX.md.
USER requests index update
│
▼
┌──────────────────────────────┐
│ 1. MIRROR & INTERPRET │ full refresh or targeted update?
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 2. GENERATE TREE │ eza --tree --git-ignore from project root
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 3. REVIEW QUICK LINKS │ update changed paths · add new files · remove dead links
└───────────────┬──────────────┘
│
▼
┌──────────────────────────────┐
│ 4. PROPOSE │ present full proposed INDEX.md for user review
└───────────────┬──────────────┘ do NOT write until explicitly approved
│
▼
┌──────────────────────────────┐
│ 5. WRITE │ Directory Tree + Quick Links only
└──────────────────────────────┘ Standard Tooling section is never modified
