@bradygaster/squad-sdk 0.9.6-insider.2 → 0.10.0

package/templates/workflow-wiring-appendix-a-code-reviewer.md

@@ -0,0 +1,131 @@
+# Appendix A: Wiring a Code Reviewer — Complete Walkthrough
+
+> End-to-end example of adding a code reviewer to your squad and wiring their gate so it actually gets enforced. This walkthrough addresses a common failure: a reviewer is on the roster but never reviews a single PR because the gate wasn't wired.
+
+## The Problem This Solves
+
+Adding a reviewer to `team.md` gives them an identity. It does NOT:
+- Tell the coordinator to route PRs to them
+- Prevent PRs from being merged without their approval
+- Prevent issues from being closed before review happens
+
+**What goes wrong without enforcement:** A reviewer can be on the roster as "Reviewer" from day one. Their charter says they review PRs. The routing table says "PR code review → {ReviewerName}." But PRs get merged and issues get closed without them ever being spawned. Why?
+
+Because the routing table says WHO handles what — it's for incoming requests ("review PR #42"). It does NOT say "after every agent completes work, route their output to {ReviewerName}." The coordinator routes work TO agents, but nothing tells it to route COMPLETED work to a reviewer. The "After Agent Work" flow in `squad.agent.md` says: collect results → present → spawn Scribe. No review step.
+
+**The fix has three layers:**
+
+| Layer | What it does | Where it lives |
+|-------|-------------|----------------|
+| Identity | Reviewer exists and knows how to review | `team.md` roster + `charter.md` |
+| Routing | User can explicitly request "review this" | `routing.md` routing table |
+| **Enforcement** | Coordinator MUST route every PR to reviewer before merge | `routing.md` Rules section + `issue-lifecycle.md` post-work steps |
+
+Most squads get layers 1 and 2 right. Layer 3 — enforcement — is what's usually missing.
+
+## Step-by-Step Walkthrough
+
+### Step 1: Create the reviewer's identity
+
+Create `.squad/agents/{name}/charter.md`:
+
+```markdown
+# {Name} — Code Reviewer
+
+## Identity
+- **Name:** {Name}
+- **Role:** Code Reviewer
+- **Expertise:** Code quality, correctness, test coverage, security, patterns
+- **Style:** Thorough, fair, specific. Provides actionable feedback.
+
+## What I Own
+- Reviewing PRs for code quality, correctness, and test coverage
+- Identifying bugs, security issues, and design problems
+- Providing specific, actionable feedback (not vague suggestions)
+
+## How I Review
+1. Read the PR diff completely
+2. Check: does it do what the issue asked for?
+3. Check: are there tests? Do they cover the important cases?
+4. Check: are there bugs, edge cases, or security issues?
+5. Check: does it follow project patterns and conventions?
+6. Verdict: APPROVE or REJECT with specific feedback
+
+## Boundaries
+**I handle:** Code review, PR review, quality gates
+**I don't handle:** Implementation, design, research, documentation
+
+## On REJECT
+I provide specific feedback: what's wrong, why, and what to do instead.
+The original author fixes their work. I re-review after fixes.
+```
+
+Create `.squad/agents/{name}/history.md` seeded with project context.
+
+### Step 2: Add to team.md roster
+
+```markdown
+| 👑 {Name} | Code Reviewer | `.squad/agents/{name}/charter.md` | ✅ Active |
+```
+
+### Step 3: Add routing table entry
+
+In `routing.md` → routing table:
+
+```markdown
+| PR code review | 👑 {Name} | — | "Review PR #42", code quality, finding reports |
+```
+
+**⚠️ This is necessary but NOT sufficient.** This only handles explicit review requests. It does NOT enforce automatic review of every PR.
+
+### Step 4: Add enforcement rule (THIS IS THE CRITICAL STEP)
+
+In `routing.md` → `## Rules` section, add a numbered rule:
+
+```markdown
+N. **{Name} PR Gate** — every PR created by any agent MUST be reviewed by {Name}
+   before merge. The coordinator spawns {Name} (sync) with the PR diff after
+   the author pushes and creates the PR. On REJECT, the original author addresses
+   feedback. On APPROVE, the coordinator merges via `gh pr merge`. No PR merges
+   without {Name}'s approval.
+```
+
+**Why this works when the routing table alone didn't:** The routing table is for matching incoming work to agents. Rules are behavioral constraints the coordinator must follow AFTER work completes. The rule says "after a PR exists, you MUST do X before proceeding." The routing table says "if someone asks for a review, route to X."
+
+### Step 5: Wire into issue-lifecycle.md
+
+In `.squad/templates/issue-lifecycle.md`, the "Coordinator Post-Work Steps" section should reference your reviewer by name:
+
+```markdown
+4. **Route to reviewer.** Spawn {Name} (sync) with the PR diff for code review.
+```
+
+This is the operational detail — the step-by-step instructions the coordinator follows after an agent completes issue work. The routing rule (Step 4) is the mandate; the lifecycle template is the procedure.
+
+### Step 6: Add to casting registry
+
+Update `.squad/casting/registry.json` with the new entry.
+
+### Step 7: Verify
+
+Ask yourself these questions:
+
+- [ ] If a clean session coordinator reads `routing.md` Rules, will it know to route PRs to this reviewer? → Check rule N exists.
+- [ ] If an agent completes work and pushes a PR, does the coordinator's post-work flow include a review step? → Check `issue-lifecycle.md` step 4.
+- [ ] Can the coordinator merge a PR without the reviewer's approval? → The rule should say "No PR merges without {Name}'s approval."
+- [ ] Can the coordinator close an issue without a merged PR? → Check the issue closure rule exists.
+
+If any answer is wrong, you have a gap.
+
+## What Each File Controls (Summary)
+
+| File | What it contributes to the reviewer gate |
+|------|----------------------------------------|
+| `charter.md` | WHO the reviewer is and HOW they review |
+| `team.md` | That the reviewer EXISTS on the team |
+| `routing.md` routing table | That explicit review requests go to this reviewer |
+| `routing.md` Rules section | That the coordinator MUST route EVERY PR to this reviewer (enforcement) |
+| `issue-lifecycle.md` | The step-by-step procedure for the post-work review flow |
+| `casting/registry.json` | Persistent name tracking |
+
+**Remove any one of these and the gate has a hole.** The most commonly missed piece is the Rules section entry (Step 4).

package/templates/workflow-wiring-appendix-b-documenter.md

@@ -0,0 +1,140 @@
+# Appendix B: Wiring a Documenter/Librarian — Complete Walkthrough
+
+> End-to-end example of adding a documenter role that ensures significant changes are documented. This is a FOLLOW-UP TRIGGER pattern — not a gate (which blocks), but an automatic downstream task that fires after work completes.
+
+## The Problem This Solves
+
+Your project has agents building features, fixing bugs, and writing tools. But nobody documents what was built, how to use it, or what changed. Documentation happens only when someone explicitly asks — and by then, the context is lost.
+
+A documenter/librarian role solves this by automatically evaluating whether completed work needs documentation and producing it if so.
+
+## Gate vs Follow-Up Trigger
+
+| Pattern | Blocks work? | When it runs | Example |
+|---------|-------------|-------------|---------|
+| **Gate** (Appendix A) | Yes — work cannot proceed without approval | Before merge | Code reviewer must approve PR |
+| **Follow-up trigger** | No — work proceeds, documentation happens in parallel | After merge | Documenter evaluates if docs are needed |
+
+A documenter is typically a follow-up trigger, not a gate. You don't want documentation review to block a hotfix from merging. But you DO want documentation to happen automatically after significant changes.
+
+## Step-by-Step Walkthrough
+
+### Step 1: Create the documenter's identity
+
+Create `.squad/agents/{name}/charter.md`:
+
+```markdown
+# {Name} — Documenter
+
+## Identity
+- **Name:** {Name}
+- **Role:** Documenter / Librarian
+- **Expertise:** Documentation, guides, READMEs, changelogs, knowledge management
+- **Style:** Clear, thorough, user-focused. Makes complex things understandable.
+
+## What I Own
+- Evaluating whether completed work needs documentation
+- Writing/updating READMEs, guides, and runbooks
+- Maintaining a docs index so nothing gets lost
+- Summarizing design decisions and architectural changes
+
+## How I Work
+1. Read the PR diff or agent output
+2. Assess: does this change user-facing behavior? Add a new feature? Change configuration?
+3. If yes: write or update the relevant documentation
+4. If no: report "no docs needed" with brief justification
+
+## Boundaries
+**I handle:** Documentation, guides, READMEs, summaries, knowledge management
+**I don't handle:** Code implementation, code review, research, operations
+```
+
+Create `.squad/agents/{name}/history.md` seeded with project context.
+
+### Step 2: Add to team.md roster
+
+```markdown
+| 📝 {Name} | Documenter | `.squad/agents/{name}/charter.md` | ✅ Active |
+```
+
+### Step 3: Add routing table entry
+
+In `routing.md` → routing table:
+
+```markdown
+| Documentation, reports, summaries | 📝 {Name} | `docs/` | "Write docs for X", "Summarize this", guides, READMEs |
+```
+
+### Step 4: Add follow-up trigger rule
+
+In `routing.md` → `## Rules` section, add a numbered rule:
+
+```markdown
+N. **Documentation follow-up** — after any PR is merged that adds or modifies
+   user-facing features, scripts, tools, or configuration, the coordinator
+   spawns {Name} (background) to evaluate whether documentation is needed.
+   {Name} reads the merged PR diff and either writes/updates docs or reports
+   "no docs needed." This is a follow-up, not a gate — it does not block
+   the merge.
+```
+
+**Why a rule and not a ceremony:** Ceremonies are structured multi-participant meetings. This is a single-agent follow-up task. A routing rule is simpler and more appropriate.
+
+**Why background, not sync:** Documentation doesn't block other work. The documenter runs in parallel with whatever comes next.
+
+### Step 5: Wire into the coordinator's post-merge flow
+
+This is the trickiest part. The coordinator's After Agent Work flow doesn't currently have a "post-merge" hook. You wire this through the issue-lifecycle template.
+
+In `.squad/templates/issue-lifecycle.md`, after the merge step, add:
+
+```markdown
+8. **Documentation follow-up.** After merge, check routing.md Rules for
+   documentation follow-up rule. If present, spawn the documenter (background)
+   with the merged PR diff to evaluate whether docs are needed.
+```
+
+Alternatively, you can wire this as an `after` ceremony in `ceremonies.md`:
+
+```yaml
+- name: "Documentation Check"
+  when: "after"
+  condition: "PR merged that adds features, scripts, tools, or config changes"
+  facilitator: "{DocumenterName}"
+  participants: ["{DocumenterName}"]
+  output: "Docs written/updated, or 'no docs needed' with justification"
+```
+
+### Step 6: Worktree for doc changes
+
+If the documenter produces files, they need a worktree — docs are files too. The coordinator should:
+1. Create a worktree for the doc update (e.g., `squad/{issue}-docs`)
+2. The documenter commits and pushes
+3. A PR is created for the docs
+4. The docs PR goes through the normal review flow (including the code reviewer if you have one)
+
+This means doc changes also get reviewed. The documenter is not exempt from the review gate.
+
+### Step 7: Add to casting registry
+
+Update `.squad/casting/registry.json` with the new entry.
+
+### Step 8: Verify
+
+- [ ] After a feature PR merges, does the coordinator spawn the documenter? → Check the routing rule exists.
+- [ ] Does the documenter get a worktree for their work? → Check the worktree rule covers docs.
+- [ ] Do doc changes go through the review gate? → They should — docs are files, files need PRs, PRs need review.
+- [ ] Is the follow-up non-blocking? → The documenter should be background, not sync.
+
+## What Each File Controls (Summary)
+
+| File | What it contributes |
+|------|-------------------|
+| `charter.md` | WHO the documenter is and HOW they evaluate |
+| `team.md` | That the documenter EXISTS |
+| `routing.md` routing table | That explicit doc requests go to this member |
+| `routing.md` Rules section | That the coordinator MUST spawn docs evaluation after merges (enforcement) |
+| `issue-lifecycle.md` or `ceremonies.md` | The procedural hook: when exactly the follow-up fires |
+| `casting/registry.json` | Persistent name tracking |
+
+**The most commonly missed piece:** The Rules section entry (Step 4). Without it, the documenter only runs when someone explicitly says "write docs for X." The whole point is that it runs automatically.

package/templates/workflow-wiring-guide.md

@@ -0,0 +1,276 @@
+# Squad Workflow Wiring Guide
+
+> How to wire up new team members, reviewer gates, and custom workflows so they actually get enforced by the coordinator — even in a clean session with no prior memory.
+
+## Why This Guide Exists
+
+The Squad framework (`squad.agent.md`) provides generic orchestration primitives. **It does not prescribe a specific workflow.** Your project's workflow — whether that's "all code goes through PRs and reviews" or "just commit to main" — must be wired into project-level configuration files.
+
+If a workflow rule exists only in someone's memory, in a chat transcript, or in `decisions.md` but NOT in a configuration file the coordinator reads at decision time — **it will not be followed in a clean session.**
+
+### Why Existing Patterns Aren't Enough
+
+The Squad framework already has concepts for routing tables, reviewer roles, and ceremonies. But having these concepts does NOT mean they work automatically:
+
+- **Adding a reviewer to the roster ≠ enforcing reviews.** A reviewer can be on the roster with "Reviewer" as their role and never review a single PR — because no RULE in `routing.md` tells the coordinator to route PRs to them. The roster says WHO exists. Rules say WHAT they enforce.
+
+- **Capturing a decision ≠ enforcing it.** `decisions.md` may contain "every change must go through a PR" and "only {ReviewerName} closes PRs." These can get buried in a large file that the coordinator reads for context but doesn't treat as enforcement rules. A decision is a historical record. A routing rule is an enforceable constraint.
+
+- **Describing a lifecycle ≠ wiring it.** `squad.agent.md` describes issue→branch→PR→review→merge. But if the After Agent Work section (the flow the coordinator actually follows after every agent completes) has no push/PR/review step, the lifecycle is described conceptually but never connected to the coordinator's actual decision flow.
+
+**The pattern that works:** A numbered rule in `routing.md` → Rules section. The coordinator reads this section, treats each rule as a constraint, and follows them. If your workflow isn't a numbered rule, it's a suggestion.
+
+---
+
+## Configuration Surface Area
+
+The coordinator reads these files to decide how to behave. If your workflow isn't encoded in one of these, it doesn't exist.
+
+| File | What It Controls | Read When |
+|------|-----------------|-----------|
+| `routing.md` | WHO handles what, behavioral RULES, reviewer GATES | Every session start, before every routing decision |
+| `ceremonies.md` | Auto-triggered ceremonies (before/after work batches) | Before spawning work batches, after completion |
+| `templates/issue-lifecycle.md` | Git workflow: push, PR, review, merge, issue closure | When spawning agents for issue-linked work |
+| Agent `charter.md` | Per-agent identity, boundaries, behavior | Inlined into every spawn prompt |
+| `team.md` | Roster, member capabilities | Session start |
+| `decisions.md` | Captured decisions and directives | Read by agents at spawn time |
+
+### How They Interact
+
+```
+User request arrives
+  → Coordinator reads routing.md (WHO handles this?)
+  → Coordinator checks ceremonies.md (any auto-triggered "before" ceremony?)
+  → Coordinator reads agent charter.md (inline into spawn prompt)
+  → If issue-linked: coordinator reads issue-lifecycle.md (add ISSUE CONTEXT to spawn prompt)
+  → Agent works
+  → Coordinator follows After Agent Work flow
+  → Coordinator checks ceremonies.md (any auto-triggered "after" ceremony?)
+  → Coordinator checks routing.md Rules section (any post-work rules to enforce?)
+```
+
+**The critical insight:** `routing.md` Rules section and `ceremonies.md` are the two enforcement mechanisms. If a rule isn't in one of these, the coordinator has no way to know about it.
+
+---
+
+## How to Wire Up a New Team Member
+
+### Step 1: Create the member (files)
+
+```
+.squad/agents/{name}/
+  charter.md    ← Identity, role, boundaries, what they own
+  history.md    ← Seeded with project context from team.md
+```
+
+### Step 2: Add to roster (`team.md`)
+
+Add a row to the `## Members` table:
+```
+| {emoji} {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+```
+
+### Step 3: Add routing entry (`routing.md`)
+
+Add a row to the routing table:
+```
+| {Work Type} | {emoji} {Name} | {Output Location} | {Examples} |
+```
+
+### Step 4: Add issue routing (if applicable)
+
+Add to the Issue Routing table in `routing.md`:
+```
+| squad:{name} | {Description of work} | {emoji} {Name} |
+```
+
+### Step 5: Add to casting registry
+
+Update `.squad/casting/registry.json` with the new entry.
+
+### Step 6: Wire any gates (if this member is a reviewer/gate)
+
+**This is the step most people miss.** If the new member should review or gate other members' work, you need to wire enforcement. See "How to Wire Up a Reviewer Gate" below.
+
+---
+
+## How to Wire Up a Reviewer Gate
+
+A reviewer gate means: "Agent X must review Agent Y's output before it proceeds." The framework supports this but does NOT automatically enforce it. You must wire it.
+
+### Option A: Routing Rule (recommended for simple gates)
+
+Add to `routing.md` → `## Rules` section:
+
+```markdown
+N. **{GateName} Gate** — Every {output type} from {Author} MUST be reviewed by {ReviewerName} before {next step}. The coordinator routes {Author}'s output to {ReviewerName} (sync spawn), collects the verdict, and only proceeds if approved. On rejection, {Author} revises based on {ReviewerName}'s feedback.
+```
+
+**Example — reviewer for all PRs:**
+```markdown
+9. **{ReviewerName} PR Gate** — Every PR created by any agent MUST be reviewed by {ReviewerName} before merge. The coordinator spawns {ReviewerName} (sync) with the PR diff, collects APPROVE/REJECT verdict. On rejection, the original author addresses feedback.
+```
+
+**Example — design review gate:**
+```markdown
+10. **{DesignReviewer} Design Gate** — Every design doc produced by the architect MUST be reviewed by {DesignReviewer} before implementation begins. {DesignReviewer} always rejects the first draft on concept/approach. Implementation is BLOCKED until {DesignReviewer} approves.
+```
+
+**Why this works:** The coordinator reads the Rules section before and after every work batch. Rules are behavioral constraints the coordinator must follow.
+
+### Option B: Ceremony (recommended for multi-participant gates)
+
+Add to `ceremonies.md` using the Markdown table format the file uses:
+
+```markdown
+## Design Review
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | before |
+| **Condition** | task involves implementing a design doc |
+| **Facilitator** | {DesignReviewer} |
+| **Participants** | Architect, {DesignReviewer} |
+| **Time budget** | focused |
+| **Enabled** | ✅ yes |
+
+**Agenda:**
+1. Read the design doc
+2. Challenge the premise and approach
+3. Demand alternatives and evidence
+4. Verdict: APPROVE or REJECT
+```
+
+**Why this works:** The coordinator checks ceremonies.md for `before` ceremonies whose condition matches the current task. If matched, the ceremony runs before work begins.
+
+### Option A vs Option B
+
+| Use Case | Use Routing Rule | Use Ceremony |
+|----------|-----------------|--------------|
+| Simple 1-on-1 review (reviewer → author) | ✅ | Overkill |
+| Multi-participant alignment (3+ agents) | Too simple | ✅ |
+| Needs structured facilitation | No | ✅ |
+| Must run automatically before specific work | Either works | ✅ |
+| One-line behavioral constraint | ✅ | Overkill |
+
+---
+
+## How to Wire Up an Issue Lifecycle (Git Workflow)
+
+This is where you define what happens after an agent completes work on a GitHub issue. The framework references `.squad/templates/issue-lifecycle.md` but does NOT create it — you must create it yourself.
+
+> **⚠️ This file is required if your project uses GitHub Issues Mode.** Without it, the coordinator has no post-work steps for push/PR/review and will treat agent commit as "done."
+
+See `.squad/templates/issue-lifecycle.md` for the full template if your project already has one. If not, create it following the pattern below.
+
+### Step 1: Create `templates/issue-lifecycle.md`
+
+Create `.squad/templates/issue-lifecycle.md` with your project's git workflow. At minimum it should include:
+
+- An ISSUE CONTEXT block template (for spawn prompts)
+- Coordinator post-work steps (verify push → verify PR → route to reviewer → merge on approval)
+- Issue closure rules (PR merge auto-close vs manual close)
+- Worktree requirements (if applicable)
+
+### Step 2: Add enforcement rules to `routing.md`
+
+Add numbered rules to the `## Rules` section that reference the lifecycle:
+
+```markdown
+N.  **Issue lifecycle enforcement** — all issue-linked work follows the lifecycle
+    in `.squad/templates/issue-lifecycle.md`. The coordinator adds the ISSUE CONTEXT
+    block to spawn prompts and follows the post-work steps (verify push → verify PR
+    → route to reviewer → merge on approval). Read `issue-lifecycle.md` before
+    spawning any agent for issue work.
+
+N+1. **{ReviewerName} PR Gate** — every PR created by any agent MUST be reviewed
+    by {ReviewerName} before merge. The coordinator spawns {ReviewerName} (sync)
+    with the PR diff. On REJECT, the original author addresses feedback. On APPROVE,
+    the coordinator merges. No PR merges without {ReviewerName}'s approval.
+
+N+2. **Issue closure restriction** — issues that produced files (code, docs, scripts,
+    designs, tests) close ONLY via PR merge auto-close ("Closes #N" in PR body).
+    Never use `gh issue close` for file-producing work. Exception: tracking/strategic
+    issues and superseded issues may be closed with a comment.
+
+N+3. **Worktree for all file-producing work** — every task that creates or modifies
+    files (including documentation) requires a worktree. Exceptions: read-only queries,
+    Scribe (.squad/ state), pure analysis producing no files.
+```
+
+### Step 3: Verify your wiring
+
+After creating both files, run the verification checklist (below) to confirm a clean session coordinator would follow the lifecycle.
+
+---
+
+## How to Wire Up a Custom Workflow Step
+
+If you need something that isn't a reviewer gate or issue lifecycle — for example, "always run tests before pushing" or "docs must be reviewed by the author before merge" — here's where to put it:
+
+### If it's a behavioral rule the coordinator should always follow:
+→ Add to `routing.md` → `## Rules` section
+
+### If it should trigger automatically before/after specific work:
+→ Add to `ceremonies.md` as a `before` or `after` ceremony
+
+### If it's something agents should do as part of their work:
+→ Add to the agent's `charter.md` under a new section
+
+### If it's something that applies only to issue-linked work:
+→ Add to `templates/issue-lifecycle.md`
+
+### If it's a team-wide constraint that should be visible to all agents:
+→ Capture as a decision in `decisions.md` (via directive or decision inbox)
+
+---
+
+## Verification Checklist
+
+After wiring any new member, gate, or workflow, verify:
+
+- [ ] **Clean session test:** Start a new session (no memory). Give a task. Does the coordinator follow the new rule?
+- [ ] **File completeness:** Is the rule/gate/workflow encoded in a file the coordinator reads? (routing.md, ceremonies.md, issue-lifecycle.md, charter.md)
+- [ ] **No verbal-only rules:** Is there anything the coordinator should do that's only in chat history or your memory? If yes, it will be lost on session restart.
+- [ ] **Gate enforcement:** If you added a reviewer gate, does the routing.md Rules section or ceremonies.md explicitly say the coordinator must route to the reviewer? "Having a reviewer on the roster" is not the same as "enforcing that they review."
+- [ ] **Issue lifecycle:** If your project uses PRs, does `templates/issue-lifecycle.md` exist? Does routing.md reference it?
+
+---
+
+## Common Mistakes
+
+1. **Adding a reviewer to the roster but not wiring a gate.** Having a reviewer on the team doesn't mean they review anything. You must add a rule in routing.md that says "route PRs to {ReviewerName}."
+
+2. **Closing issues via `gh issue close` instead of PR merge.** If your project uses PRs, issue closure should happen via "Closes #N" in the PR body. Wire this in issue-lifecycle.md.
+
+3. **Writing docs/scripts directly on main.** If your project requires branches for all changes, the worktree gate must apply to ALL file-producing work — including docs. Make this explicit in routing.md Rules.
+
+4. **Assuming the coordinator remembers verbal instructions.** Each session starts fresh. If you told the coordinator "always use opus" in session 1, session 2 won't know unless it's in decisions.md or routing.md.
+
+5. **Not creating `issue-lifecycle.md`.** The framework references it but doesn't create it. If your project uses GitHub Issues Mode, create this template.
+
+6. **Capturing a decision but never encoding it as a rule.** `decisions.md` is a historical record. The coordinator reads it for context but doesn't treat entries as enforceable constraints. If a decision should be enforced, it must become a numbered rule in `routing.md` Rules section.
+
+---
+
+## Decisions Audit
+
+Periodically scan `decisions.md` for directives that should be routing rules but aren't:
+
+1. Search for phrases like "always", "never", "must", "every", "required"
+2. For each match, ask: "Is this enforced by a numbered rule in routing.md?"
+3. If no → either add a rule, or accept that it's advisory-only
+4. If yes → verify the rule text matches the decision
+
+This prevents `decisions.md` from becoming a graveyard of good intentions that the coordinator reads but doesn't act on.
+
+---
+
+## Appendices
+
+For detailed end-to-end walkthroughs of specific wiring scenarios, see:
+
+- **[Appendix A: Wiring a Code Reviewer](workflow-wiring-appendix-a-code-reviewer.md)** — Full walkthrough of adding a code reviewer member and wiring their gate so it actually gets enforced. Includes every file that needs modification with exact content.
+
+- **[Appendix B: Wiring a Documenter/Librarian](workflow-wiring-appendix-b-documenter.md)** — Full walkthrough of adding a documenter role that ensures all significant changes are documented. Shows a follow-up trigger pattern rather than a gate pattern.