Code Commits Issues Pulls Sessions CI/CD

main

md 13.9 KB

View source Raw

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:

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:

## 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:

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

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}."
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.
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.
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.
Not creating issue-lifecycle.md. The framework references it but doesn't create it. If your project uses GitHub Issues Mode, create this template.
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:

Search for phrases like "always", "never", "must", "every", "required"
For each match, ask: "Is this enforced by a numbered rule in routing.md?"
If no → either add a rule, or accept that it's advisory-only
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 — 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 — 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.

#Squad Workflow Wiring Guide

#Why This Guide Exists

#Why Existing Patterns Aren't Enough

#Configuration Surface Area

#How They Interact

#How to Wire Up a New Team Member

#Step 1: Create the member (files)

#Step 2: Add to roster (team.md)

#Step 3: Add routing entry (routing.md)

#Step 4: Add issue routing (if applicable)

#Step 5: Add to casting registry

#Step 6: Wire any gates (if this member is a reviewer/gate)

#How to Wire Up a Reviewer Gate

#Option A: Routing Rule (recommended for simple gates)

#Option B: Ceremony (recommended for multi-participant gates)

#Option A vs Option B

#How to Wire Up an Issue Lifecycle (Git Workflow)

#Step 1: Create templates/issue-lifecycle.md

#Step 2: Add enforcement rules to routing.md

#Step 3: Verify your wiring

#How to Wire Up a Custom Workflow Step

#If it's a behavioral rule the coordinator should always follow:

#If it should trigger automatically before/after specific work:

#If it's something agents should do as part of their work:

#If it's something that applies only to issue-linked work:

#If it's a team-wide constraint that should be visible to all agents:

#Verification Checklist

#Common Mistakes

#Decisions Audit

#Appendices