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
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 |
Single-Task Flow
After kickoff, run /squad-auto to let the pipeline run hands-free, or step through manually if you want to review each stage:
/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
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.