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 (skipping the PO phase), then runs architect → dev → test → review → doc for each story in dependency order.
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
/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
The pipeline pauses and surfaces the review issues. Fix the problems, then re-run /squad-spec (or restart /loop or /goal) to continue.
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.
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.