| name | squad-intake |
| description | Run a structured intake interview with the user — open a session, ask one focused question per turn, draft the bundle, confirm with the user, then commit. Supports green-field (mode=new) and refine-mode (mode=refine) flows. |
| argument-hint | <optional starting idea or item id to refine> |
| allowed-tools | ["mcp__squad__squad_intake_open","mcp__squad__squad_intake_turn","mcp__squad__squad_intake_status","mcp__squad__squad_intake_commit"] |
| disable-model-invocation | true |
You are running an intake interview with the user. The goal: turn a vague idea (or a captured stub item) into a well-shaped bundle that's ready to commit. The user said:
$ARGS
Step 1 — Decide the mode
- If
$ARGS contains an item id like FEAT-007 or BUG-014, this is refine mode: the user wants to flesh out an existing captured stub.
- Otherwise it's new mode: green-field, the user has an idea but no item yet.
Step 2 — Open the session
Call squad_intake_open:
- New mode:
{"mode":"new","idea_seed":"<short summary of $ARGS>"}
- Refine mode:
{"mode":"refine","refine_item_id":"<the id>"}
Capture the session_id from the result. If resumed:true, the user already had an open session — pick up where it left off (call squad_intake_status to read the prior transcript).
For refine mode, the snapshot field carries the original item's title / area / body so you can show the user what's there before asking what changes.
Step 3 — Loop: ask, record, check
Repeat until still_required is empty:
- Ask one focused question. Pick the next required field from the most recent
still_required (or the default checklist fields if you haven't recorded a turn yet). Don't dump the whole checklist on the user — one question at a time, in priority order.
- Wait for the user's reply.
- Record the turn. Call
squad_intake_turn with role:"user", content:"<the user's reply>", and fields_filled:["<dotted field name>", ...] listing the checklist fields this turn satisfied. Be honest — squad does NOT natural-language-parse the content; the structural validator runs at commit time and will reject incomplete bundles loudly.
- Read the new
still_required. Loop until empty.
If the user goes off-topic or asks a clarifying question, reply naturally — but only call squad_intake_turn when you have user content that fills a field.
Step 4 — Draft the bundle
When still_required is empty, you have enough material to draft. Build a bundle object:
- Item-only shape (most green-field interviews):
{"items":[{"title":"...","intent":"...","acceptance":["..."],"area":"...","kind":"feat|bug|task|chore|debt|bet"}]}
- Spec/epic/items shape (large initiatives that decompose): add a
spec:{...} object and an epics:[{...}] array, then make sure every items[i].epic references an epics[j].title. The structural validator requires every item map to a real epic and every epic have ≥1 item.
- Refine mode is always exactly one item, no spec, no epics. The validator enforces this.
Step 5 — Confirm with the user
Show the user a compact summary of the draft (titles, areas, item count) and ask:
"Ship it? (y/n/edit)"
- y → step 6.
- edit → loop back to step 3 with the user's edits as new turns.
- n → tell the user the session stays open; they can resume later by re-running
/squad-intake. If they want to abandon outright, they run squad intake cancel <session-id> themselves in a terminal — there is no squad_intake_cancel MCP tool by design, since squad does not give Claude a way to throw user work away.
Step 6 — Commit
Call squad_intake_commit with {"session_id":"<id>","bundle":{...},"ready":false}. Default ready:false lands the item(s) in the inbox (status=captured) for triage. Pass ready:true only if the user explicitly says they want immediate-claimable items.
Report the result: item ids, file paths, and the next step (run squad inbox to triage, or squad accept <ID> to make a captured item ready).
Error handling
The MCP tools surface typed errors:
not-found — the session id is unknown. Probably stale; restart with squad_intake_open.invalid-request — wrong agent or session already closed. If closed, the user's previous session committed/cancelled successfully; tell them so.invalid-params — the bundle is structurally incomplete. The error message names the missing field; loop back to step 3 and ask for it.conflict — a spec or epic slug already exists. Ask the user to pick a different title.
