Squad Workflow
Squad turns a single AI session into a structured multi-role pipeline — Product Owner, Architect, Developer, Tester, and Reviewer — each handing off to the next through a shared file.
Overview
Each role has its own slash command that reads and writes to a shared handoff file (.contextkit/squad/handoff.md). This simulates a team of specialists working in sequence, catching gaps that a single-role prompt would miss.
How it works
1. Each command reads the handoff file left by the previous role
2. It does its work and appends its output to the handoff file
3. The next role picks up from there — full context, no re-prompting
Because pipeline state lives in plain markdown on disk instead of an in-memory session, handoff files survive closing the terminal, context compaction, even switching tools mid-pipeline — start a task in Claude Code, pick it up in Codex or Cursor tomorrow.
Pipeline Roles
| Step | Role | Command | What it does |
|---|---|---|---|
| 1 | Product Owner | /squad | Writes user story, acceptance criteria, edge cases, and scope. Optionally captures screenshots or images as visual assets. |
| 2 | Architect | /squad-architect | Designs technical approach, files to change, and implementation steps |
| 3 | Developer | /squad-dev | Implements code following the architect's plan |
| 4 | Tester | /squad-test | Classifies test levels, writes and runs tests against acceptance criteria |
| 5 | Reviewer | /squad-review | Reviews everything and gives a PASS or NEEDS-WORK verdict |
| 6 | Doc Writer | /squad-doc | Creates companion .md files for every new or significantly modified code file |
Conversation-First Flow
After a planning conversation, /squad can extract the agreed tasks automatically — no need to retype them. Directive phrases like "let's do it", "go ahead", or "let's go" trigger extraction rather than being treated as task descriptions.
/squad # scans conversation, shows extracted tasks, confirms before writing specs /squad "let's do this" # directive phrase — same behaviour, not treated as a task
Use /squad-go to do the same thing and immediately run the full pipeline after — no second command needed:
/squad-go # Reads tasks from the current conversation, confirms the list, # writes PO specs, then immediately runs architect → dev → test → review → doc
squad vs squad-go
/squad stops after writing PO specs so you can review before the pipeline runs. /squad-go skips that pause and runs everything in one shot. Both extract tasks from the conversation the same way.
Single-Task Flow
Pass an explicit task description to skip extraction and go straight to the PO spec. After kickoff, run /squad-auto hands-free or step through manually:
/squad "add dark mode support" # PO writes the spec /squad-auto # Runs architect → dev → test → review → doc hands-free
/squad "add dark mode support" # PO writes the spec /squad-architect # Architect designs the plan /squad-dev # Dev implements the code /squad-test # Tester writes and runs tests /squad-review # Reviewer gives the verdict /squad-doc # Doc Writer creates companion .md files
Visual Assets (Optional)
If you have a screenshot, mockup, or design image relevant to the task, paste or attach it when running /squad. The PO agent will save it to .contextkit/squad/assets/ and reference the path in the handoff under a ### Visual Assets section.
How downstream agents use it
— Architect reads the images before writing the technical plan
— Developer reads the images before implementing
— If no images are provided, the section is left empty and the pipeline runs unchanged
Batch Flow
For multiple tasks, use batch mode to spec them all up front, then run the full pipeline automatically:
/squad "add dark mode" "fix login bug" "refactor checkout" # PO writes specs for all three tasks (batch mode auto-detected) /squad-auto # Runs Architect → Dev → Test → Review → Doc for each task
Need to add more tasks after the batch is already running? Just run /squad again with the new tasks — it detects the existing manifest and appends automatically:
# Batch already running with 3 tasks... /squad "add export to CSV" "fix mobile layout" # Detects existing manifest → appends as handoff-4.md and handoff-5.md # Writes PO specs for the new tasks only /squad-auto # Picks up all pending tasks and continues the pipeline
From Spec — /squad-spec
If you've run /spec to generate a scope, use /squad-spec to implement every story in that scope automatically — no manual handoff needed between stories.
/squad-spec reads the scope's SPEC.md, creates handoff files with the PO spec pre-filled from the spec's EARS-format acceptance criteria (skipping the PO phase), then runs architect → dev → test → review → doc for each story in dependency order — with an automatic retry and peer-review pass if review finds issues, and a full-suite regression check once per scope.
Recommended: drive it with /loop (Claude Code) or /goal (Codex)
Each story adds implementation detail, tests, and review output to the context. By story 4 or 5, the context window is large. Claude Code's /loop /clear and Codex's /goal both clear context between stories so each one starts fresh — they just get there differently: /loop re-invokes on an interval, /goal keeps working autonomously until its condition holds, then stops itself.
# Claude Code /loop /clear /squad-spec 01-identity-auth # Codex /goal complete every story in scope 01-identity-auth via /squad-spec # Both: process one story per iteration # Context cleared between each — never bloats # Stop automatically when all stories are done
Each phase runs as its own subagent (Claude Code)
Architect, Dev, Test, Peer Review, Review, and Doc each dispatch as a fresh Task-tool subagent, reading only the handoff file — not the reasoning trail from earlier phases. This keeps Review from anchoring on Dev's own account of its work. Review and Peer Review default to claude-haiku-4-5-20251001, since both are checking the EARS-format acceptance criteria already written in SPEC.md line by line, not designing anything. Architect and Dev stay on your primary model. Codex runs every phase inline in the current context — no subagent isolation there yet.
/squad-spec 01-identity-auth # Picks up the next pending story and runs it to completion # Run again to continue with the next story
If a story gets needs-work
/squad-spec retries automatically when review finds a problem — up to 2 attempts, with an independent peer-review pass added on the retry. Only if both retries fail does the pipeline pause and surface the issues for you to fix by hand. Fix the problems, then re-run /squad-spec (or restart /loop or /goal) to continue.
The full-suite gate runs in the foreground, on purpose
Every story's own Test phase only runs tests scoped to its changes. Once per scope, after all stories are done, /squad-spec runs the complete test suite in the foreground with serial or low parallelism (not backgrounded at max workers) — this gate doesn't need to be fast, it needs your machine to stay usable while it confirms the scope is clean before the next one starts.
Each story is committed on its own
Right after a story's Doc phase passes, /squad-spec stages exactly the files that story's Changes Made/Tests Written/Doc Notes name — never a blanket git add -A — and commits in Conventional Commits format before moving to the next story. History stays bisectable and revertable per story instead of landing as one commit for the whole scope. Skips cleanly if nothing changed or the project isn't a git repo; if the commit itself fails, it stops rather than continuing with uncommitted work.
Open questions get resolved, not skipped
/squad-spec runs unattended, so there's no human mid-run to escalate a spec's open questions to. If a story's spec flags one as blocking, Architect resolves it directly and records the assumption plus its rationale under Open Question Resolutions in the handoff — auditable after the fact instead of buried in prose.
Configuration
When you run /squad, a .contextkit/squad/config.md file is created automatically. You can edit it to control pipeline behavior:
checkpoint: po # pause after PO specs (or: architect) model_routing: false # set true to use Haiku for dev + test phases
checkpoint
Controls when /squad-auto pauses for review. po pauses after all PO specs are written (default). architect also pauses after all architect plans.
model_routing Claude Code only
When true, /squad-auto automatically spawns Claude Haiku for Dev and Test phases. Architect and Review always run on your primary model. Saves ~35% tokens — the standards files and Review gate maintain output quality. Default is false.
/squad-spec takes the opposite split and isn't configurable: Review and Peer Review always run on Haiku (they're checking already-written criteria), Architect and Dev always run on your primary model (the judgment-heavy work). There's no model_routing flag for it.
Per-task commits
/squad-auto commits each task individually right after its Doc phase, before moving to the next task — same staged-files-only, Conventional Commits approach as /squad-spec's per-story commits above.
Resetting Squad State
If your squad folder gets into a stuck or mixed state, use /squad-reset to clear it and start fresh.
/squad-reset # reports what's removed, then deletes .contextkit/squad/
Inline reset
If you run /squad with a task and the folder is in a mixed state, the PO will offer to reset and continue in one step — no need to run /squad-reset separately.
/squad-reset is a hard delete with no backup. If you need to recover, check git history.
Feedback Loop
Any downstream role can raise questions for an upstream role. When this happens, the pipeline pauses and directs you to the right command to provide clarifications. After clarifications are added, re-run the asking role's command to continue.
Example escalations
Reviewer has questions for Dev → run /squad-dev to clarify
Tester has questions for Architect → run /squad-architect to clarify
Architect has questions for PO → run /squad to clarify
This prevents misunderstandings from compounding through the pipeline. The handoff file tracks all questions and answers for full traceability.
Want squad to run automatically from GitHub Issues?
CI Squad lets you label any issue squad-ready and have the full pipeline run in GitHub Actions — no local setup required. A draft PR is opened when it's done.
Was this helpful?
Help us improve the documentation by sharing your feedback.