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 |
| 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 | Writes and runs tests against acceptance criteria |
| 5 (optional) | Peer Reviewer | /squad-peer-review | Adversarial review of implementation and tests before the final verdict |
| 6 | Reviewer | /squad-review | Reviews everything and gives a PASS or NEEDS-WORK verdict |
Single-Task Flow
Run each command in sequence in the same AI session:
/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 # Optional: insert peer review before the final verdict /squad-peer-review # Adversarial check (between test and review)
Peer Review (Optional)
Run /squad-peer-review between /squad-test and /squad-review to get an adversarial read on the implementation and tests before the final verdict. The Reviewer will automatically incorporate any valid findings.
When to use it
— Large or complex features where the dev and tester may be too close to the work
— Security-sensitive changes (auth, payments, data access)
— Tasks where a NEEDS-WORK verdict would be costly to fix later
Skipping it is fine for simple bug fixes and small changes — the Reviewer already runs a thorough audit with escalation paths.
Batch Flow
For multiple tasks, use batch mode to spec them all up front, then run the full pipeline automatically:
/squad-batch "add dark mode" "fix login bug" "refactor checkout" # PO writes specs for all three tasks /squad-run # Runs Architect → Dev → Test → Review for each task
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.
Was this helpful?
Help us improve the documentation by sharing your feedback.