Workflow Wiring Guide

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.

How They Interact

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)

Step 2: Add to roster (team.md)

Add a row to the ## Members table:

Step 3: Add routing entry (routing.md)

Add a row to the routing table:

Step 4: Add issue routing (if applicable)

Add to the Issue Routing table in routing.md:

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:

Example — reviewer for all PRs:

Example — design review gate:

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:

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

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:

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:

• Not done: Clean session test: Start a new session (no memory). Give a task. Does the coordinator follow the new rule?
• Not done: File completeness: Is the rule/gate/workflow encoded in a file the coordinator reads? (routing.md, ceremonies.md, issue-lifecycle.md, charter.md)
• Not done: 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.
• Not done: 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.”
• Not done: 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 — 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.