| 1 | # Squad Workflow Wiring Guide |
| 2 | |
| 3 | > 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. |
| 4 | |
| 5 | ## Why This Guide Exists |
| 6 | |
| 7 | 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. |
| 8 | |
| 9 | 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.** |
| 10 | |
| 11 | ### Why Existing Patterns Aren't Enough |
| 12 | |
| 13 | The Squad framework already has concepts for routing tables, reviewer roles, and ceremonies. But having these concepts does NOT mean they work automatically: |
| 14 | |
| 15 | - **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. |
| 16 | |
| 17 | - **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. |
| 18 | |
| 19 | - **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. |
| 20 | |
| 21 | **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. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## Configuration Surface Area |
| 26 | |
| 27 | The coordinator reads these files to decide how to behave. If your workflow isn't encoded in one of these, it doesn't exist. |
| 28 | |
| 29 | | File | What It Controls | Read When | |
| 30 | |------|-----------------|-----------| |
| 31 | | `routing.md` | WHO handles what, behavioral RULES, reviewer GATES | Every session start, before every routing decision | |
| 32 | | `ceremonies.md` | Auto-triggered ceremonies (before/after work batches) | Before spawning work batches, after completion | |
| 33 | | `templates/issue-lifecycle.md` | Git workflow: push, PR, review, merge, issue closure | When spawning agents for issue-linked work | |
| 34 | | Agent `charter.md` | Per-agent identity, boundaries, behavior | Inlined into every spawn prompt | |
| 35 | | `team.md` | Roster, member capabilities | Session start | |
| 36 | | `decisions.md` | Captured decisions and directives | Read by agents at spawn time | |
| 37 | |
| 38 | ### How They Interact |
| 39 | |
| 40 | ``` |
| 41 | User request arrives |
| 42 | → Coordinator reads routing.md (WHO handles this?) |
| 43 | → Coordinator checks ceremonies.md (any auto-triggered "before" ceremony?) |
| 44 | → Coordinator reads agent charter.md (inline into spawn prompt) |
| 45 | → If issue-linked: coordinator reads issue-lifecycle.md (add ISSUE CONTEXT to spawn prompt) |
| 46 | → Agent works |
| 47 | → Coordinator follows After Agent Work flow |
| 48 | → Coordinator checks ceremonies.md (any auto-triggered "after" ceremony?) |
| 49 | → Coordinator checks routing.md Rules section (any post-work rules to enforce?) |
| 50 | ``` |
| 51 | |
| 52 | **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. |
| 53 | |
| 54 | --- |
| 55 | |
| 56 | ## How to Wire Up a New Team Member |
| 57 | |
| 58 | ### Step 1: Create the member (files) |
| 59 | |
| 60 | ``` |
| 61 | .squad/agents/{name}/ |
| 62 | charter.md ← Identity, role, boundaries, what they own |
| 63 | history.md ← Seeded with project context from team.md |
| 64 | ``` |
| 65 | |
| 66 | ### Step 2: Add to roster (`team.md`) |
| 67 | |
| 68 | Add a row to the `## Members` table: |
| 69 | ``` |
| 70 | | {emoji} {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active | |
| 71 | ``` |
| 72 | |
| 73 | ### Step 3: Add routing entry (`routing.md`) |
| 74 | |
| 75 | Add a row to the routing table: |
| 76 | ``` |
| 77 | | {Work Type} | {emoji} {Name} | {Output Location} | {Examples} | |
| 78 | ``` |
| 79 | |
| 80 | ### Step 4: Add issue routing (if applicable) |
| 81 | |
| 82 | Add to the Issue Routing table in `routing.md`: |
| 83 | ``` |
| 84 | | squad:{name} | {Description of work} | {emoji} {Name} | |
| 85 | ``` |
| 86 | |
| 87 | ### Step 5: Add to casting registry |
| 88 | |
| 89 | Update `.squad/casting/registry.json` with the new entry. |
| 90 | |
| 91 | ### Step 6: Wire any gates (if this member is a reviewer/gate) |
| 92 | |
| 93 | **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. |
| 94 | |
| 95 | --- |
| 96 | |
| 97 | ## How to Wire Up a Reviewer Gate |
| 98 | |
| 99 | 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. |
| 100 | |
| 101 | ### Option A: Routing Rule (recommended for simple gates) |
| 102 | |
| 103 | Add to `routing.md` → `## Rules` section: |
| 104 | |
| 105 | ```markdown |
| 106 | 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. |
| 107 | ``` |
| 108 | |
| 109 | **Example — reviewer for all PRs:** |
| 110 | ```markdown |
| 111 | 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. |
| 112 | ``` |
| 113 | |
| 114 | **Example — design review gate:** |
| 115 | ```markdown |
| 116 | 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. |
| 117 | ``` |
| 118 | |
| 119 | **Why this works:** The coordinator reads the Rules section before and after every work batch. Rules are behavioral constraints the coordinator must follow. |
| 120 | |
| 121 | ### Option B: Ceremony (recommended for multi-participant gates) |
| 122 | |
| 123 | Add to `ceremonies.md` using the Markdown table format the file uses: |
| 124 | |
| 125 | ```markdown |
| 126 | ## Design Review |
| 127 | |
| 128 | | Field | Value | |
| 129 | |-------|-------| |
| 130 | | **Trigger** | auto | |
| 131 | | **When** | before | |
| 132 | | **Condition** | task involves implementing a design doc | |
| 133 | | **Facilitator** | {DesignReviewer} | |
| 134 | | **Participants** | Architect, {DesignReviewer} | |
| 135 | | **Time budget** | focused | |
| 136 | | **Enabled** | ✅ yes | |
| 137 | |
| 138 | **Agenda:** |
| 139 | 1. Read the design doc |
| 140 | 2. Challenge the premise and approach |
| 141 | 3. Demand alternatives and evidence |
| 142 | 4. Verdict: APPROVE or REJECT |
| 143 | ``` |
| 144 | |
| 145 | **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. |
| 146 | |
| 147 | ### Option A vs Option B |
| 148 | |
| 149 | | Use Case | Use Routing Rule | Use Ceremony | |
| 150 | |----------|-----------------|--------------| |
| 151 | | Simple 1-on-1 review (reviewer → author) | ✅ | Overkill | |
| 152 | | Multi-participant alignment (3+ agents) | Too simple | ✅ | |
| 153 | | Needs structured facilitation | No | ✅ | |
| 154 | | Must run automatically before specific work | Either works | ✅ | |
| 155 | | One-line behavioral constraint | ✅ | Overkill | |
| 156 | |
| 157 | --- |
| 158 | |
| 159 | ## How to Wire Up an Issue Lifecycle (Git Workflow) |
| 160 | |
| 161 | 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. |
| 162 | |
| 163 | > **⚠️ 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." |
| 164 | |
| 165 | See `.squad/templates/issue-lifecycle.md` for the full template if your project already has one. If not, create it following the pattern below. |
| 166 | |
| 167 | ### Step 1: Create `templates/issue-lifecycle.md` |
| 168 | |
| 169 | Create `.squad/templates/issue-lifecycle.md` with your project's git workflow. At minimum it should include: |
| 170 | |
| 171 | - An ISSUE CONTEXT block template (for spawn prompts) |
| 172 | - Coordinator post-work steps (verify push → verify PR → route to reviewer → merge on approval) |
| 173 | - Issue closure rules (PR merge auto-close vs manual close) |
| 174 | - Worktree requirements (if applicable) |
| 175 | |
| 176 | ### Step 2: Add enforcement rules to `routing.md` |
| 177 | |
| 178 | Add numbered rules to the `## Rules` section that reference the lifecycle: |
| 179 | |
| 180 | ```markdown |
| 181 | N. **Issue lifecycle enforcement** — all issue-linked work follows the lifecycle |
| 182 | in `.squad/templates/issue-lifecycle.md`. The coordinator adds the ISSUE CONTEXT |
| 183 | block to spawn prompts and follows the post-work steps (verify push → verify PR |
| 184 | → route to reviewer → merge on approval). Read `issue-lifecycle.md` before |
| 185 | spawning any agent for issue work. |
| 186 | |
| 187 | N+1. **{ReviewerName} PR Gate** — every PR created by any agent MUST be reviewed |
| 188 | by {ReviewerName} before merge. The coordinator spawns {ReviewerName} (sync) |
| 189 | with the PR diff. On REJECT, the original author addresses feedback. On APPROVE, |
| 190 | the coordinator merges. No PR merges without {ReviewerName}'s approval. |
| 191 | |
| 192 | N+2. **Issue closure restriction** — issues that produced files (code, docs, scripts, |
| 193 | designs, tests) close ONLY via PR merge auto-close ("Closes #N" in PR body). |
| 194 | Never use `gh issue close` for file-producing work. Exception: tracking/strategic |
| 195 | issues and superseded issues may be closed with a comment. |
| 196 | |
| 197 | N+3. **Worktree for all file-producing work** — every task that creates or modifies |
| 198 | files (including documentation) requires a worktree. Exceptions: read-only queries, |
| 199 | Scribe (.squad/ state), pure analysis producing no files. |
| 200 | ``` |
| 201 | |
| 202 | ### Step 3: Verify your wiring |
| 203 | |
| 204 | After creating both files, run the verification checklist (below) to confirm a clean session coordinator would follow the lifecycle. |
| 205 | |
| 206 | --- |
| 207 | |
| 208 | ## How to Wire Up a Custom Workflow Step |
| 209 | |
| 210 | 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: |
| 211 | |
| 212 | ### If it's a behavioral rule the coordinator should always follow: |
| 213 | → Add to `routing.md` → `## Rules` section |
| 214 | |
| 215 | ### If it should trigger automatically before/after specific work: |
| 216 | → Add to `ceremonies.md` as a `before` or `after` ceremony |
| 217 | |
| 218 | ### If it's something agents should do as part of their work: |
| 219 | → Add to the agent's `charter.md` under a new section |
| 220 | |
| 221 | ### If it's something that applies only to issue-linked work: |
| 222 | → Add to `templates/issue-lifecycle.md` |
| 223 | |
| 224 | ### If it's a team-wide constraint that should be visible to all agents: |
| 225 | → Capture as a decision in `decisions.md` (via directive or decision inbox) |
| 226 | |
| 227 | --- |
| 228 | |
| 229 | ## Verification Checklist |
| 230 | |
| 231 | After wiring any new member, gate, or workflow, verify: |
| 232 | |
| 233 | - [ ] **Clean session test:** Start a new session (no memory). Give a task. Does the coordinator follow the new rule? |
| 234 | - [ ] **File completeness:** Is the rule/gate/workflow encoded in a file the coordinator reads? (routing.md, ceremonies.md, issue-lifecycle.md, charter.md) |
| 235 | - [ ] **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. |
| 236 | - [ ] **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." |
| 237 | - [ ] **Issue lifecycle:** If your project uses PRs, does `templates/issue-lifecycle.md` exist? Does routing.md reference it? |
| 238 | |
| 239 | --- |
| 240 | |
| 241 | ## Common Mistakes |
| 242 | |
| 243 | 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}." |
| 244 | |
| 245 | 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. |
| 246 | |
| 247 | 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. |
| 248 | |
| 249 | 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. |
| 250 | |
| 251 | 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. |
| 252 | |
| 253 | 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. |
| 254 | |
| 255 | --- |
| 256 | |
| 257 | ## Decisions Audit |
| 258 | |
| 259 | Periodically scan `decisions.md` for directives that should be routing rules but aren't: |
| 260 | |
| 261 | 1. Search for phrases like "always", "never", "must", "every", "required" |
| 262 | 2. For each match, ask: "Is this enforced by a numbered rule in routing.md?" |
| 263 | 3. If no → either add a rule, or accept that it's advisory-only |
| 264 | 4. If yes → verify the rule text matches the decision |
| 265 | |
| 266 | This prevents `decisions.md` from becoming a graveyard of good intentions that the coordinator reads but doesn't act on. |
| 267 | |
| 268 | --- |
| 269 | |
| 270 | ## Appendices |
| 271 | |
| 272 | For detailed end-to-end walkthroughs of specific wiring scenarios, see: |
| 273 | |
| 274 | - **[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. |
| 275 | |
| 276 | - **[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. |