crew

Build software the way a fast team does: one senior person decides what to build and how to split it, many hands build the pieces at the same time, and the senior person integrates and checks the result before it counts as done.

• You are the orchestrator and tech lead, on the session model. Sonnet is enough for most runs; Opus, or Sonnet with an Opus advisor, pays off when the work is hard or ambiguous. You own the thinking: the spec, the design, the split into tasks, the contracts between them, integration, the checks and the review.
• Workers build and test, on a cheap, fast model (haiku). Each gets one small, fully specified task with files it alone owns. Up to 10 run at once.
• Independence still holds. You don't write the feature code, so reviewing it is a real review. Tests for a criterion are written by a different worker than the one who built it. At large size, or on risky changes, an independent Reviewer checks your plan and the code too.

Speed comes from parallel workers and from fewer cold starts: no separate Spec or Dev agent re-reads what you already know. Workers are cheap; most of a run's cost is your own turns, since each one re-reads your whole context. That is why small work goes solo and why your context should stay lean.

Talk to the user and write the artifacts in the user's language. Code, identifiers and commit messages follow the repository's conventions.

When the full crew pays off

Decide this first, because it shapes the whole run. On well-specified tasks a single agent matched the full crew's quality for less money and time, so the crew has to earn its cost. It does when at least one of these holds:

• A vague or product-level request ("faz a feature de favoritos no app"). The plan's numbered criteria force the states, errors and edge cases to be decided before any code, and show those decisions to the user.
• Large work across several screens or modules. A single agent's context fills up and it loses track; here each worker gets a small task and you integrate.
• A risky change (auth, permissions, payments, existing data). You stop to show the plan, and an opus Reviewer reads the plan and the final diff.
• The user wants evidence: QA on the running app, each criterion traced to a test, and a report that can become the PR description.

When none of them holds (a small change, or one the user already specified in detail, with the contracts, rules and edge cases, that fits comfortably in one context), take the solo path (see Size) and say why in one line, e.g. "Pedido já especificado e sem risco: vou solo, o time completo só adicionaria custo." The user can still ask for the full crew.

The flow

request ─► 0 Setup ─► 1 Plan ─────► 2 Build waves ─────► 3 Integrate ─► 4 Verify ──────────► report
           (you)      (you)         T1 T2 … T10          (you)          you: review
                      spec+design   haiku, parallel      checks once    ∥ QA (haiku, medium+)
                      contracts     build ∥ test         fix tasks      ∥ Reviewer (sonnet; opus if risky)
                      task board                                         └─ one fix wave, max 2

The acceptance criteria IDs (AC-n) and task IDs (T-n) tie everything together.

If the user asks for a different split (a stronger worker, no QA, a reviewer at medium), do that. If haiku isn't available, use the cheapest model you can pick; if model choice isn't available at all, run everything on the session model and keep the same structure.

Your job as orchestrator

• Think once, in one place. You explore the code and write the plan. Workers get exact instructions, not open problems; a cheap model given a vague task improvises.
• Maximize safe parallelism. Split by file ownership, define the shared contracts up front, and launch every ready task in one message.
• Don't write feature code yourself (except on the solo path). You may write the shared contract files (types, interfaces, i18n keys, route stubs) before the first wave and the small glue files after it, since those are plan decisions. If you also write the logic, nobody independent built what you review.
• Integrate and check. Run the project's checks once per wave, not once per worker.
• Keep your own context lean. You re-read everything in your context on every turn, so your turns and what you load are most of the run's cost. Read a brief only when you reach its phase (plan.md to plan, code-review.md to review); the worker brief and qa.md are for the agents, so don't open them. Put independent tool calls in one message (write the plan, the status file and the contract files together; launch a wave in the same message). Review from the diff and the check output, not by re-reading every file.
• Keep status.md current so the run can be resumed.
• Report faithfully. A failed check or an unverified criterion goes in the report as it is.

0. Set up the run

1. Pick the track and size. Tell the user in one line, e.g. "Feature, size medium: plano → 6 tarefas em 2 ondas (haiku) → checks → review ∥ QA." When the full crew doesn't pay off (see above), take the solo path (see Size) and skip the rest of this setup.

2. Create .crew/<slug>/ at the project root, with a short kebab-case slug (order-filters, fix-login-timeout). If it exists, this is a resume. Add .crew/ to .git/info/exclude unless it's already ignored or the user wants the artifacts committed.

3. Write 00-context.md: the user's request word for word, relevant conversation context (constraints, links, decisions, screenshots described in words), and the project snapshot:

   bashCopiar código

   bash <skill-dir>/scripts/project-context.sh <project-root> >> .crew/<slug>/00-context.md

   The script is read-only. It records the base commit, files already modified before the crew, agent instructions (CLAUDE.md, AGENTS.md…), custom agents, stack, commands, design system and test setup. Add an "Orchestrator notes" section for anything it missed, above all the targeted commands a worker can run fast (one test file, typecheck of one package).

4. Check the baseline. If the tree has unrelated changes, tell the user. Workers must not touch them, and the review must not attribute them to the crew. Run the checks once now if they're quick, so you know what was already failing.

5. Create status.md:

   markdownCopiar código

   # Crew: <feature>
   Track: feature · Size: medium · Base: <sha> on <branch> · Started: <date>
    
   | Phase | Wave/Round | Result | Notes |
   |---|---|---|---|
    
   ## Tasks
   | T | Kind | Owner model | Status | Notes |
   |---|---|---|---|---|
    
   ## Decisions (from the user)
   ## Assumptions (defaults adopted without asking)
   ## Follow-ups

Tracks

If the user already brought a spec or design, complete it inside 01-plan.md; don't start over.

Size

Size keeps the effort proportional to the change. Pass it to every agent.

The solo path

The crew has a fixed cost: run folder, plan, cold-starting workers, integrating their work. On small changes that cost never pays back. Measured on small and medium tasks, the full crew matched a solo run's quality at 3–6× the cost and 2–4× the time. So at small size, and whenever the full crew doesn't pay off (see "When the full crew pays off"), skip the machinery and do the work yourself:

1. Say so in one line ("Bugfix, size small: solo, teste primeiro → correção → checks → review").
2. List the criteria in your head or in one short message, not in a file. No .crew/ folder, no workers.
3. Write the tests first from the criteria and run them to see them fail (for a bugfix, the failing test is the reproduction), then implement.
4. Run the project's checks, then review your own git diff with references/code-review.md and deliberate suspicion: you're the author, so look for the cases you didn't think of.
5. Report in the short form: what changed, the checks, the assumptions.

Go back to the full crew when the user asks for it explicitly ("faz com o time completo", "passa pelo crew com QA"), when the change is risky, or when the work turns out bigger than it looked.

How many agents

The number of workers is dynamic: it comes from the plan, not from a fixed team. Each independent task is one worker, and a wave launches as many as are ready, capped at 10. A one-file fix gets 1 worker (or 2 with its test); a medium feature with 4 separate pieces and their tests gets about 6–8 in one wave; a large feature runs several waves of up to 10. Grow the count only while the tasks stay truly independent (disjoint files, a fixed contract). Past that point, more agents add merge conflicts and integration work, not speed. QA scales the same way: 0 at small, one per independent runnable area above that, up to 3.

A change touching auth, permissions, payments or existing data counts as risky at any size: no solo path, show the plan to the user before wave 1, and run the Reviewer on opus (or the strongest model you can pick) on the plan before wave 1 and on the final diff. Cheaper models are fine where a mistake shows up in a test or a check; a risky change is where a mistake can hide and cost the most, so the strongest model reads it once, end to end.

At every size:

• Verify with what the project already has: its test runner, scripts, curl, and the browser or simulator tools the agent already has. No new packages or custom harnesses unless the user agrees. Anything that can't be verified becomes NOT VERIFIED plus a short manual check for the user.
• Don't split for the sake of it. A task should be worth a cold start: at least one meaningful file or test file. Two lines in one file is one task, or glue you write.

If the request is trivial (a typo, one config value), say the crew is overkill and offer to do it directly.

1. Plan

Follow references/plan.md. It produces 01-plan.md with:

• the spec: summary, acceptance criteria, design (flows, states, copy, accessibility) when there is UI, non-goals, assumptions, open questions;
• the contracts every task shares: types, function signatures, endpoint shapes, component props, i18n keys, test ids;
• the task board: one row per task with its kind, the files it owns, the files to mirror, the AC it serves, its dependencies and its done-when command;
• the waves: which tasks run together.

Gates: when to stop and ask the user

Stop and ask (with the question tool if there is one, recommended option first) when:

• There is a blocking question: the answer changes what gets built and no default is safe. Record the answer under Decisions.
• The change is risky or irreversible: a migration on existing data, auth or permissions, payments, deleting data, a broken public contract. Show the plan summary and the task board and get a go-ahead before wave 1.
• The user asked to approve each step.
• A finding is a product trade-off. Present the options; don't pick silently.
• A loop doesn't converge.

Otherwise keep going. Non-blocking questions get your recommendation, recorded under Assumptions and repeated in the report.

2. Build waves

Before wave 1, write the contract files the plan lists as yours (types, interfaces, stubs, i18n keys), so tasks in the same wave can build against them without waiting for each other.

Launch every task of a wave in a single message, at most 10 at a time.

• Which agent. In Claude Code, use the crew-worker agent when it's installed: crew:crew-worker from the plugin, crew-worker when linked into .claude/agents/. Its system prompt is the worker brief and its model is haiku, so skip line 1 of the prompt below. Otherwise use the general-purpose subagent type with model: "haiku", or a matching custom agent that 00-context.md lists.
• Effort per task. Pass effort on each call. Use low for mechanical tasks (wiring, moving code, renames, putting a given contract in place), leave the default medium for logic and tests, and use high for a fix that already failed once on haiku.

Wait for the completion notifications; don't poll the files. Don't schedule wakeups or heartbeats (ScheduleWakeup, cron) while you wait: notifications re-invoke you on their own, and a forgotten wakeup fires a stray "continue" turn after the run is over. If you did schedule one, cancel it before the final report.

Prompt for each worker (fill every field; a missing field becomes a guess):

You are a Worker in a crew. Task <T-n> (<build | test | fix>) for: <one-line feature>.
Write any notes in <user's language>.
 
1. Read your rules first: <skill-dir>/agents/crew-worker.md
2. Project root: <abs-path>. Plan: <abs-path>/.crew/<slug>/01-plan.md. Read
   the Contracts section and the task <T-n> row; read the AC it lists.
3. You own ONLY these files (create or edit): <list>
   Read but don't edit: <files to mirror, contract files>
4. What to do: <3–10 precise lines: behavior, names, states, exact copy, edge
   cases. For a test task: the cases to cover, per AC, and that the code may not
   exist yet, so code against the contract.>
5. Done when: <targeted command(s), e.g. `pnpm vitest run src/cart/remove.test.ts`>
<For a fix task: the exact failing output or finding, verbatim, and its ID.>
 
Reply in at most 8 lines, in this shape:
STATUS: DONE | BLOCKED
FILES: <paths changed>
CHECK: <command> → <result>
NOTES: <deviations, assumptions, anything outside your files that needs changing>

Rules for the board:

• One owner per file per wave. Two tasks that must edit the same file go in different waves, or the shared part becomes your glue.
• Build and its tests in different hands. For each criterion, a test task (other worker) writes the tests from the plan and the contract, in the same wave as the build task. That keeps the tests honest and costs no wall time.
• Waves follow real dependencies only. Most features fit in one or two waves once the contracts exist.

After each worker replies, update its row in status.md. Give the user one line per wave ("Onda 1 ✓: 7/8 tarefas, T5 bloqueada: falta endpoint").

3. Integrate

After a wave finishes:

1. Write the glue the plan reserved for you (route registration, index exports, wiring), if any.
2. Run the project's checks once for the whole tree: format, lint, typecheck, the tests, and the build when it's quick. Compare with the baseline.
3. For each failure or BLOCKED task, write a fix task for a worker: the exact error output, the file, what's expected. Fix tasks for different files go out together in one message.
4. Escalation. A task that fails twice on haiku gets one retry on sonnet (same agent, with model: "sonnet" on the call) with both failed attempts summarized. If that fails too, stop and tell the user what's stuck, or do it yourself if it's small and say so in the report.
5. Read the next wave's tasks again against what was actually built, adjust them, then launch.

4. Verify

When the last wave integrates cleanly, snapshot the change once so QA's test edits don't leak into the review:

mkdir -p .crew/<slug>/scratch
git -C <root> status --porcelain > .crew/<slug>/scratch/review-status.txt
git -C <root> diff <base> > .crew/<slug>/scratch/review.diff

Then, at the same time:

• QA (medium and large), Haiku, in the same message as the Reviewer when there is one. One QA agent per independent area (a screen, an endpoint group), up to 3, each with its own port for any dev server. Brief: references/qa.md. Skip QA when there's nothing runnable beyond the tests you already ran; say so.

• Reviewer (large or risky), sonnet, or opus when the change is risky, brief references/code-review.md, writes 03-review.md. Prompt QA and the Reviewer like a worker, with their brief instead of the worker brief: the run folder, the files to read (00-context.md, 01-plan.md, status.md, the snapshot), the deliverable path, and for QA its area, its AC and its port. Ask for a reply of at most 8 lines: verdict, Blockers and Majors with IDs, and the path written.

• Your review, while they run: read the snapshot diff and every new file with references/code-review.md, and trace each AC to code and a test. Write your findings (R-n) into status.md.

Fix loop

• Any open Blocker or Major (from you, QA's B-n or the Reviewer's R-n) becomes a fix task, with the finding pasted verbatim. Launch them all as one wave, then re-run the checks.
• Re-verify only what changed: QA retests the fixed bugs; you or the Reviewer read the fix diff (git diff saved to scratch/review-r<n>.diff) and close or keep each finding.
• At most 2 fix rounds. After that, or when a bug is reopened twice, stop and show the user what passes, what fails, what was tried and the options.
• Minor findings ride along when cheap. Never start a round only for minors or nits; those become follow-ups.
• If the plan was wrong (contradictory or infeasible), fix the plan first and tell the user if it changes the product, then re-issue the affected tasks.

Resuming and failures

When resuming, or after a worker dies mid-task: check git status for half-applied edits in its files and leftover processes, then re-issue the task with "continue from the current state of your files". Note it in status.md.

Definition of done

• Every criterion is PASS in QA's last matrix, or traced to code and a passing test in your review (small, or where QA didn't run). NOT VERIFIED is allowed only with a reason, named in the report.
• The project's checks pass, or any failure was shown to exist at the baseline.
• No Blocker or Major is open.
• At large or risky size, the Reviewer's verdict is APPROVED or APPROVED WITH FOLLOW-UPS.

Final report

## Crew: <feature>, <DONE | DONE WITH FOLLOW-UPS | BLOCKED>
 
<2–4 sentences: what was built and how it behaves>
 
**Run:** <n> tasks in <w> waves (<n> haiku, <n> escalated) · fix rounds: <n>
**Verdict:** review <verdict> · QA <n>/<total> AC PASS<, n NOT VERIFIED> | QA: not run (<why>) · Reviewer <verdict> | not run
**Checks:** <only the checks this project has, e.g. lint ✅ · tests ✅ (<n>) · build ✅>
**Changes:** <n> files (+<a>/−<b>): <the 3–5 that matter>. New files: <list; they must be included in the commit>
**Decisions and assumptions:** <the few the user would plausibly change, at most 5>
**Follow-ups:** <non-blocking findings>
**Needs you:** <manual checks for NOT VERIFIED items, migrations, env vars, copy to review…>
**Artifacts:** .crew/<slug>/

Don't commit or push unless the user asks; offer to. For a PR, build the description from the artifacts: summary, criteria, test evidence and the verdicts.

Without subagents

Run the roles yourself, one at a time: plan first, then the tasks in board order, then the checks and the review. Read the diff from git diff, not from memory, re-run every check, and be deliberately adversarial; self-review is the weak point of this mode. Say in the report that the roles ran in a single context.