pipeline

name

pipeline

description

Cradle-to-grave executor for the full squad workflow: brainstorm → grillme → tasks → next → implement → review. Auto-invokes each sub-skill in sequence and halts only at explicit user-decision gates. The user fires ONE command at the start and answers inline gate questions thereafter — no re-typing slash commands between phases. Triggers: "run the full squad pipeline", "take this feature cradle-to-grave", "walk me through from idea to merge", "whole feature flow", "guide me end-to-end", "/squad:pipeline". Pass --from <phase> to enter mid-sequence. Example: "/squad:pipeline new notifications system".

Skill: Pipeline

Objective

Take a feature from idea to verified change by chaining the six squad skills into one auto-executed sequence: brainstorm → grillme → tasks → next → implement → review.

The pipeline is an executor with explicit gates (v1.5+). It (1) reconstructs how far the feature has progressed from the conversation context, (2) auto-invokes the next sub-skill via the Skill tool, and (3) halts at each phase boundary to ask the user whether to proceed. The user fires ONE entry command and answers inline gate questions; no re-typing slash commands between phases.

Position in the workflow:

• The six skills run standalone when you want one step.
• /squad:pipeline runs them as an executed sequence for a feature going cradle-to-grave, so the user never has to copy-paste a slash command between phases.

Inviolable Rules

1. No telemetry of its own. The pipeline is an orchestration skill. It MUST NOT call record_run. Every sub-skill it invokes already records its own run; a "pipeline run" is not a tracked entity. /squad:stats aggregates the sub-runs — that is the pipeline's telemetry, by composition. (The thin .squad/pipeline-state.json resume cache from Rule 3 is NOT telemetry — it is per-feature state for resume only and never feeds /squad:stats.)
2. Auto-execution between explicit gates. Pre-v1.5 the pipeline only recommended commands and the user typed them. From v1.5 the pipeline invokes sub-skills directly via the Skill tool, but ONLY between explicit user-decision gates. Every phase boundary is a halt with an AskUserQuestion (proceed / adjust / skip / exit); sub-skills' own internal gates (e.g. /squad:implement Gate 1 plan approval, Gate 2 Blocker halt) keep firing as before. The pipeline never silently advances past a gate. The reserved interruption commands (see "Reserved commands" below) let the user break out at any point.
3. State persistence is a thin resume cache, not a journal. From v1.5+ the pipeline writes a minimal .squad/pipeline-state.json so the user can resume across context compaction or a closed session. The file carries phase status + 1-line outcomes only — NO full sub-skill outputs, NO secrets, NO conversation transcripts. File mode 0o600, single-writer (only the pipeline writes), gitignored. On every /squad:pipeline invocation the pipeline reads this file FIRST, then falls back to scanning conversation context for anything the file does not cover. See "State persistence" section below for schema + lifecycle.
4. No git commit, no git push. Read-only git for context is fine. Sub-skills own their own writes; the user owns commits.
5. Never edits source code directly. The pipeline only invokes sub-skills and prints inter-phase gate text. The sub-skills it invokes do the building.
6. No AI attribution in anything the pipeline prints. Consistent with the squad-wide commit-authorship rule.

Inputs

/squad:pipeline [--from <phase>] [--quick | --normal | --deep] <feature description>

Flag	Default	Description
--from <phase>	brainstorm	Enter the pipeline at a specific phase. Enumerated and validated — see below.
--quick	off	Forwarded to every invoked sub-skill. Smaller squads, tighter budgets.
--normal	default	Forwarded as-is. Full pipeline at each step.
--deep	off	Forwarded to every invoked sub-skill. Larger squads, deeper research.

--from accepts ONLY this closed set:

brainstorm | grillme | tasks | next | implement | review

Any other value → stop, print error: unknown phase '<value>' followed by the valid set, and do not guess. Default when omitted: brainstorm.

The free-form text after the flags is the feature description. Capped at 16 KB; truncate and surface note: feature description truncated at 16 KB.

Phases

#	Phase	Sub-skill invoked	Purpose	Skippable
1	brainstorm	squad:brainstorm	Explore what to build (outward)	yes
2	grillme	squad:grillme	Harden the plan vs MY codebase	yes
3	tasks	squad:tasks	Decompose the plan into a task backlog	no
4	next	squad:next	Pick the next task from the backlog	no
5	implement	squad:implement	Build it (full squad workflow)	no
6	review	squad:review	Verify the change	yes

Phases 4–6 (next → implement → review) form an inner loop that repeats once per task until the backlog is empty (see Phase 5 below).

Phase 0 — Parse and validate

1. Parse --from. Validate against the closed set above. Invalid → stop with the error + valid set. No fuzzy matching.
2. Parse the depth flag (--quick / --normal / --deep); hold it to forward.
3. Capture the feature description; apply the 16 KB cap.

Phase 1 — Reconstruct pipeline state

Source priority (v1.5+):

1. Read .squad/pipeline-state.json if it exists AND it carries an in-progress run (status ∈ {in_progress}). This is the authoritative source — it survives context compaction and closed sessions. Validate the file against the schema in "State persistence" below; on parse error fall back to step 2 and log a one-line warning.
2. Fall back to scanning the conversation context for evidence of completed sub-skill runs:
   • a brainstorm report (# Brainstorm — … heading) → phase 1 done
   • a grill summary (# Grill summary — …) → phase 2 done
   • tasks recorded (a record_tasks result / task backlog) → phase 3 done
   • an implement verdict (squad final verdict block) → phase 5 done for a task
   • a review verdict → phase 6 done for a task

Set current_phase:

• if --from was passed → current_phase = --from (explicit override wins, also overrides any value loaded from the state file)
• else if .squad/pipeline-state.json carried a valid current_phase → use it
• else → the first phase with no completed output found in context

If the state file is missing AND the conversation was compacted (prior outputs gone), the pipeline cannot reconstruct — see Edge Cases.

Cross-feature collision

If the state file exists with a feature whose name does NOT match the new invocation's feature description (Levenshtein ratio < 0.6 against the short feature name), HALT before resuming and ask the user:

in-progress pipeline found for: "{stored feature name}"
new invocation: "{new feature name}"

(A) resume the stored pipeline
(B) abandon the stored pipeline and start fresh on the new feature
(C) exit without changes

Never silently overwrite an in-progress state file with a different feature — that would orphan the user's prior work.

Phase 2 — Present the pipeline map

Print all six phases with a status marker, e.g.:

Pipeline — {short feature name}    depth: normal
  [x] 1 brainstorm   done
  [x] 2 grillme      done
  [>] 3 tasks        current — about to invoke
  [ ] 4 next
  [ ] 5 implement
  [ ] 6 review

Phase 3 — Auto-invoke the current phase

Invoke the sub-skill for current_phase via the Skill tool. Forward the depth flag and the relevant input (feature description, prior phase output, selected task, etc.). Examples:

• current_phase = brainstorm → Skill({ skill: "squad:brainstorm", args: "--normal <feature description>" })
• current_phase = grillme → Skill({ skill: "squad:grillme", args: "--normal <chosen approach from the brainstorm matrix>" })
• current_phase = tasks → Skill({ skill: "squad:tasks", args: "<hardened plan from the grill summary>" })
• current_phase = next → Skill({ skill: "squad:next" })
• current_phase = implement → Skill({ skill: "squad:implement", args: "--normal <current task title + acceptance criteria>" })
• current_phase = review → Skill({ skill: "squad:review" })

The invoked sub-skill executes its full body — including its own internal gates (e.g. /squad:implement will fire its Gate 1 plan approval and Gate 2 Blocker halt; /squad:brainstorm will ask its clarifying question if the topic is ambiguous). The pipeline does NOT intercept those — the user answers them as they fire. When the sub-skill completes, control returns to the pipeline.

Phase 4 — Inter-phase gate

After the sub-skill returns, surface its key output (verdict / option / backlog) in 1-3 lines, then fire an AskUserQuestion with the four decisions:

Decision	Meaning	Pipeline action
proceed	the phase output is good	advance current_phase to the next phase; loop back to Phase 3
adjust	re-run this phase with changes	re-invoke the SAME sub-skill, folding in the user's adjustment text
skip	this phase is not needed	advance without recording an output — only grillme / review
exit	stop the pipeline here	print the completion summary (Phase 6) and end

skip is rejected for tasks, next, and implement: skipping implement means nothing was built; skipping tasks / next means the inner loop has no backlog to walk. Say so plainly and offer proceed or exit instead.

Call out at the gate which sub-skill mutated state: brainstorm and grillme upstream are read-only-ish; tasks writes the backlog; implement writes code.

Phase 5 — The inner loop (tasks → next → implement → review)

Once tasks has produced a backlog, phases next → implement → review repeat once per task. The pipeline auto-loops:

1. Invoke Skill({ skill: "squad:next" }) → user picks/confirms a task at /squad:next's own confirmation prompt.
2. Invoke Skill({ skill: "squad:implement", args: "<task>" }) → user answers Gate 1 (plan approval) inside /squad:implement. Pipeline waits for the implementer + advisory + verdict to complete.
3. Invoke Skill({ skill: "squad:review" }) → user gets the review verdict.
4. Inter-phase gate (Phase 4 above) fires: proceed (next task) / adjust (re-run last task's review with notes) / skip (skip review on this task) / exit.
5. If proceed AND backlog has more tasks → loop back to step 1.
6. If backlog empty → go to Phase 6.

Track the remaining backlog from the conversation context. If it is unclear how many tasks are left, re-invoke Skill({ skill: "squad:next" }) — it is the source of truth and cheap to re-run.

Phase 6 — Completion

When review passes on the last task (or the user chooses exit), print:

# Pipeline complete — {short feature name}

## Phases run
- brainstorm — {1-line outcome}
- grillme — {1-line outcome}
- tasks — N tasks
- implement / review — N tasks built and verified

## Skipped
- {phase} — {why, if the user skipped it}

## Next step
- `git diff` then commit when you are ready — the pipeline never commits.

State persistence

The pipeline writes a single JSON file at .squad/pipeline-state.json (mode 0o600, gitignored) carrying the minimal state needed to resume across context compaction or a closed session. The file is overwritten atomically (write to .tmp, rename into place) on every phase transition. There is exactly one state file per workspace — multi-feature concurrent pipelines are NOT supported in v1.5.

Schema

{
  "schema_version": 1,
  "feature_short_name": "notifications-system",
  "feature_description": "<verbatim user input, truncated at 16 KB>",
  "depth": "normal",
  "started_at": "2026-05-26T20:00:00Z",
  "updated_at": "2026-05-26T22:15:00Z",
  "status": "in_progress",
  "current_phase": "implement",
  "phases": {
    "brainstorm": {
      "status": "done",
      "completed_at": "2026-05-26T20:30:00Z",
      "outcome": "Picked option B (job queue)"
    },
    "grillme": { "status": "skipped" },
    "tasks": { "status": "done", "completed_at": "2026-05-26T21:00:00Z", "task_count": 5 },
    "next": {
      "status": "done",
      "completed_at": "2026-05-26T21:10:00Z",
      "current_task_id": "task-abc-123",
      "task_index": 2,
      "task_total": 5
    },
    "implement": { "status": "in_progress" },
    "review": { "status": "pending" }
  }
}

Per-phase status ∈ {pending, in_progress, done, skipped}. Top-level status ∈ {in_progress, completed, exited, failed}.

What the file MUST NOT carry:

• Full sub-skill outputs (brainstorm reports, grill summaries, plans, diffs)
• Conversation transcripts
• Secrets, tokens, API keys, paths to credentials
• File contents from the working tree
• Anything beyond the 1-line outcome per phase

The state file is a resume cache, not a journal. The authoritative sub-skill outputs live in the conversation and in each sub-skill's own records (.squad/runs.jsonl, .squad/tasks.json, etc.). If the conversation is compacted, the user can re-invoke /squad:pipeline and the state file tells the pipeline where to pick up — the sub-skills' own state handles the rest.

Write points

The pipeline writes (atomically) at these moments:

1. On pipeline start — after Phase 0 parse + Phase 1 reconstruction, set status: "in_progress", write the initial file (or update an existing one if resuming).
2. After each Phase 4 gate decision — record the just-completed phase's status: "done" (or "skipped") + 1-line outcome, set current_phase to the next phase.
3. On Phase 6 completion — set top-level status: "completed", updated_at to now.
4. On exit or pipeline stop — set top-level status: "exited", updated_at to now.
5. On unrecoverable failure — set top-level status: "failed", include a one-line failure_reason field.

Lifecycle

• A status: "in_progress" file is the resume target — Phase 1 reads it and continues.
• A status: "completed" / "exited" / "failed" file is treated as history. The next /squad:pipeline invocation OVERWRITES it (after a one-line confirmation when the new feature description differs from the stored one — see Cross-feature collision in Phase 1).
• The file is NEVER deleted by the pipeline. Users who want to clear it manually: rm .squad/pipeline-state.json.
• The atomic-rewrite pattern uses a .prev sibling (same convention as the rest of squad-mcp's JSONL writers). The safeReadFile helper in src/util/safe-read.ts handles the mid-rename ENOENT fallback (v1.5+).

Failure modes

• Disk full / IO error on write → log a one-line warning, continue the pipeline. State persistence is best-effort; a failed write does not halt the run.
• Parse error on read → log a one-line warning, fall back to context-based reconstruction (Phase 1 step 2). Do NOT prompt the user.
• Schema-version mismatch (future v2 reading a v1 file, or vice versa) → log + fall back to context reconstruction. Migration is the next-revision's concern.

Reserved commands (interruption)

At ANY inter-phase gate (Phase 4) or sub-skill internal gate, the user may type one of the reserved commands to break the auto-flow:

Command	Effect
pipeline stop	Halt the pipeline immediately. Print the partial completion summary (Phase 6 shape).
pipeline skip	Skip the current phase if skip is allowed for it; else reject + re-ask the gate.
pipeline redo	Re-invoke the current sub-skill from scratch, ignoring its prior output.
pipeline back	Go back one phase. Re-invoke the previous sub-skill with the same input.

These commands are case-insensitive. If the user types something ambiguous (e.g. just "stop"), interpret as pipeline stop ONLY when spoken at a clear gate prompt; otherwise re-ask the gate with the four options.

Edge Cases

• No feature description and no --from → ask one clarifying question: "what feature should the pipeline take cradle-to-grave?"
• --from implement but no task backlog in context → warn: "no backlog found — recommend /squad:tasks first, or pass a free-form task." Offer to invoke /squad:tasks automatically or exit.
• User asks to skip implement → reject (Phase 4); implement is the only phase whose whole point is the change.
• Conversation compacted, prior outputs lost → check .squad/pipeline-state.json (v1.5+) FIRST — if it carries an in-progress run, resume from current_phase. Sub-skill outputs that the state file doesn't carry (full reports, plans) live in each sub-skill's own store (.squad/runs.jsonl, .squad/tasks.json, etc.) and the next sub-skill dispatch can re-read what it needs. Only when BOTH the state file is missing AND the conversation is compacted: ask the user which phase they are on, or have them re-run with --from <phase>.
• A sub-skill run failed (e.g. implement halted at Gate 2 on a Blocker; the user said exit inside the sub-skill) → the pipeline does NOT auto-advance. Surface the failure context and fire Phase 4 gate with adjust (re-run) / exit as the realistic options.
• User runs a sub-skill directly without the pipeline → fine; on the next /squad:pipeline invocation Phase 1 detects the output and the pipeline advances to the next phase.
• Sub-skill invocation fails to start (Skill tool rejects, skill name unknown) → surface the error verbatim, halt; do NOT silently fall back to the pre-v1.5 "recommend the command" behavior.

Boundaries

• The pipeline auto-invokes sub-skills via Skill between gates; it never bypasses a sub-skill's own internal gate.
• The pipeline never records telemetry and never writes .squad/ state.
• The pipeline writes .squad/pipeline-state.json as a thin resume cache (v1.5+, phase status + 1-line outcomes only, mode 0o600, gitignored). Sub-skill outputs are NEVER copied into it — those live in each sub-skill's own store.
• The pipeline never edits source code directly or runs mutating git.
• The pipeline never carries AI attribution into anything it prints.