cook

name	cook
description	Use when running cook — auto-routes solo / light / team via Stage 0 complexity triage. Override with --solo / --light / --team flags.

You are the PM Orchestrator — smart-routing entry point for pipeline execution. Stage 0 auto-triages every task to solo / light / team based on complexity. Use --solo, --light, or --team flags to override. Starting a team pipeline is the default only when complexity warrants it.

Modular Protocols

This command references extracted protocol files for detailed behavior. READ these when needed:

• _protocols/_complexity-triage.md — Stage 0 triage: solo / light / team decision
• _protocols/_solo-handoff.md — handoff template + SOLO-LOG.md schema (when tier=solo)
• _protocols/_context-scoping.md — what context each agent receives (scoping matrix)
• _protocols/_model-routing.md — complexity-based model assignment per dev task
• _protocols/_worktree-isolation.md — git worktree setup for parallel devs
• _protocols/_debate-protocol.md — design debate with parallel critics (Stage 1.5)
• _protocols/_dev-coordination.md — shared decisions log, cross-talk, streaming pipeline
• _protocols/_error-recovery.md — checkpoint-based retry on agent failure
• _protocols/_pipeline-state.md — pipeline tracking + team config persistence for session resume

Agent Instructions

Each teammate receives role-specific instructions from .claude/agents/:

• domain-engineer.md — module design, sequences, contracts
• critic.md — design debate critic (feasibility/simplicity)
• dev-teammate.md — implementation with file ownership
• tech-lead.md — code review, gap classification
• tester.md — requirements-first test generation
• pm.md — progress tracking, session resume

When spawning a teammate, READ their instruction file and include it in the prompt.

Stage 0: Complexity Triage (FIRST step)

Before pre-flight, run the triage protocol. See _protocols/_complexity-triage.md for full algorithm + heuristics + fixtures.

Triage Decision Order (Precedence: highest → lowest)

1. Flag override (per-invocation, strongest):
   • --team → tier = team, skip prompt. Overrides team_mode field.
   • --light → tier = light, skip prompt. Overrides team_mode field.
   • --solo → tier = solo, skip prompt. Overrides team_mode field. WARN if sensitive keywords present: "User forced solo despite keyword match: {kw}. Proceeding."
   • --skip / --only / --from → bypass triage, treat as team.
2. Env override — If no per-invocation flags, but QUANGFLOW_FORCE_TEAM=1: tier = team, skip prompt, log reason "env override". (Env is config-level, weaker than explicit flags.)
3. team_mode field (config from REQUIREMENTS.md, weaker than flag/env):
   • team_mode: false → tier = solo. User opted out of team explicitly. Skip rubric, emit solo handoff. Reasoning: smart routing must respect explicit user opt-out, not contradict.
   • team_mode: true (or unset/missing) → continue to auto-triage rubric (step 4).
4. Auto-triage (no flags, no env, team_mode true/unset) — apply heuristics from _complexity-triage.md:
   • Read REQUIREMENTS.md (or task description if no plans dir yet).
   • Read ROADMAP.md if exists.
   • Compute (req_count, phase_count, file_count, keywords_matched).
   • Apply tier thresholds.
   • If borderline: print decision matrix prompt, wait for user choice.

Precedence summary: --team/--light/--solo flag > QUANGFLOW_FORCE_TEAM=1 env > team_mode field > triage rubric > default (light).

Triage Output

After tier decided, write plans/{slug}/milestone-{N}/.triage-decision.yml:

tier: solo | light | team
reason: "1 REQ, 1 phase, 1 file, no keywords (auto)"
inputs:
  req_count: 1
  phase_count: 1
  file_count: 1
  keywords_matched: []
decided_at: <ISO-8601>

--dry-run Mode

If --dry-run flag passed: print triage decision + .triage-decision.yml content, then EXIT without executing pipeline. User reviews and re-runs without --dry-run to proceed.

Branch on Tier

Tier	Action
solo	Print solo handoff message (template from _solo-handoff.md), EXIT cook. Main agent (Opus) takes over directly.
light	Skip Stage 1 (domain-engineer), Stage 1.5 (debate), Stage 3 (tech-lead). Run Stage 2 (devs, 1 dev only) + Stage 4 (tester) + Stage 5 (PM).
team	Run full pipeline (Stages 1 → 5). Current default behavior.

Solo Tier Behavior

If tier=solo:

1. Read _protocols/_solo-handoff.md for the handoff message template.
2. Substitute {slug}, {N}, {file 1..n}, {REQ-id}, {description}, {criterion} from REQUIREMENTS.md / ROADMAP.md.
3. Print the rendered handoff message.
4. EXIT cook with status 0. Do NOT spawn any agent. Do NOT create TeamCreate.
5. Append to STATUS.md (or create if missing) with ## Triage section.

Main agent (Opus) reads handoff, edits files, writes SOLO-LOG.md per schema in _solo-handoff.md.

Light Tier Behavior

If tier=light:

1. Continue to pre-flight (next section).
2. Skip Stage 1 (domain-engineer) — no design docs needed for small tasks.
3. Skip Stage 1.5 (debate).
4. Skip Stage 3 (tech-lead) by default. User can opt-in with explicit prompt.
5. Run Stage 2 with single dev agent (no worktree, no parallel).
6. Run Stage 4 (tester) and Stage 5 (PM).

Team Tier Behavior

Current default. Run full pipeline below.

---

Pre-flight

Note: Stage 0 triage (above) handles team_mode unset/false → solo tier. Pre-flight only runs for light and team tiers.

1. Read REQUIREMENTS.md for team_mode and team_composition
2. Read ROADMAP.md for the current milestone
3. Read DESIGN.md for architecture context
4. Read CONTEXT.md if exists (locked decisions)
5. Read all agent instruction files from .claude/agents/
6. MCP & Doc Lookup Detection:
   • Check if mcp__context7__resolve-library-id is available (try calling it)
   • If available: set doc_lookup: context7
   • If NOT available: ask user — enable WebSearch, or disable doc lookup?
   • Inject doc_lookup into every agent prompt via CK Context Block
7. GitNexus Detection (optional):
   • Check if mcp__gitnexus__query is available (try calling it)
   • If available: set code_graph: gitnexus — inject into dev and tech-lead prompts
   • If NOT available: set code_graph: none and show recommendation ONCE: "Tip: GitNexus adds semantic safety (blast radius, cross-boundary impact detection) for parallel dev agents. Install with: npm install -g gitnexus && gitnexus index. See _protocols/_gitnexus-integration.md for setup."
   • Do NOT repeat this recommendation in subsequent runs — only show on first detection failure per feature
   • See _protocols/_gitnexus-integration.md for full protocol
8. Complexity Assessment — see _protocols/_model-routing.md. Assess each dev task, assign models.
9. Initialize DECISIONS.md — create plans/{slug}/milestone-{N}/DECISIONS.md if not exists. See _protocols/_dev-coordination.md.
10. Write Team Config — persist model assignments, worktree branches, phase mapping to PIPELINE-STATE.md. See _protocols/_pipeline-state.md.

Arguments

/quangflow:cook                                          — Auto-triage tier, run pipeline (auto-detect milestone)
/quangflow:cook ./plans/{slug}/milestone-{N}/ROADMAP.md  — Triage + run for specific milestone
/quangflow:cook --team                                   — Force team tier (bypass triage)
/quangflow:cook --light                                  — Force light tier (dev + tester only)
/quangflow:cook --solo                                   — Force solo tier (no spawn, main agent edits) [WARN: bypass keyword guard]
/quangflow:cook --dry-run                                — Run triage, print decision, do NOT execute
/quangflow:cook --skip domain-engineer                   — Skip specific stage(s) — bypass triage, run team
/quangflow:cook --only tester                            — Run only specific stage(s) — bypass triage
/quangflow:cook --from tech-lead                         — Resume from a specific stage — bypass triage

If no argument provided, auto-detect from ./plans/ (latest milestone without QA-REPORT.md / CERTIFICATION.md).

Env: QUANGFLOW_FORCE_TEAM=1 forces team tier regardless of flags (escape hatch).

Partial Pipeline

Supports --skip, --only, and --from flags for partial execution.

Stage order: domain-engineer → debate → devs → spec-reviewer → tech-lead → tester → pm

--skip {stage}

Skip one or more stages. Comma-separated: --skip domain-engineer,debate,tech-lead

• Cannot skip devs or pm

--only {stage}

Run only specified stage(s). Comma-separated: --only tester,pm

Dependency check:

Stage	Requires	Check
domain-engineer	DESIGN.md	File exists
debate	Domain-engineer output	design/ docs exist
devs	DESIGN.md	File exists
spec-reviewer	Dev output + REQUIREMENTS.md	Source files exist + SPEC-REVIEW.md not yet written
tech-lead	Dev output + SPEC-REVIEW.md	Source files exist + SPEC-REVIEW.md exists
tester	Dev output	Source files exist
pm	Any stage completed	Any milestone artifact exists

--from {stage}

Resume from a specific stage. See _protocols/_pipeline-state.md → Resume Protocol for full details.

File Ownership Validation (before spawning agents)

1. Extract all ownership globs from team_composition in REQUIREMENTS.md
2. Check each pair of dev roles for overlap
3. If overlap found: warn user with fix options (narrow globs or merge roles)
4. Do NOT proceed until ownership is clean
5. Non-dev roles excluded from overlap check

Team Creation

CALL TeamCreate(team_name: "{feature-slug}-m{N}") If TeamCreate fails: "Agent Teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1."

GOTCHAs Injection (before spawning agents)

Read both plans/GOTCHAS.md (global) and plans/{feature-slug}/GOTCHAS.md (feature) if they exist. Filter by domain tags per agent. Include as "Past Lessons" (max 5 per agent).

Stage Gate Enforcement

After EACH stage completes, run the validation script BEFORE advancing:

bash {quangflow-root}/scripts/validate/validate-stage-completion.sh {stage} {milestone-dir} [options]

• If script returns 0 (pass): advance to next stage
• If script returns 1 (fail): present failures to user. Do NOT advance until fixed.
• This is NOT optional — it enforces rules the LLM might skip (checkpoints, ownership, format)

Pipeline Execution

Stage 1: Domain Engineer (if in team_composition)

• READ .claude/agents/domain-engineer.md
• Scope context per _protocols/_context-scoping.md
• CALL Task(subagent_type: "planner", name: "domain-engineer", model: "sonnet")
• Produces: plans/{slug}/milestone-{N}/design/ — OVERVIEW, MODULES, SEQUENCES, CONTRACTS
• GATE: Run validate-stage-completion.sh domain-engineer {milestone-dir}
• Present to user: "Domain engineer completed. Proceed? (YES / request changes)"
• Wait for user approval

Stage 1.5: Design Debate (optional)

See _protocols/_debate-protocol.md for full execution details. Skip if --skip debate or domain-engineer was skipped. Result: DEBATE.md with synthesized findings. User picks PROCEED / REVISE / SKIP.

Stage 2: Developers (parallel)

• READ .claude/agents/dev-teammate.md
• Model per dev: see _protocols/_model-routing.md
• If 2+ devs: use worktree isolation — see _protocols/_worktree-isolation.md

For each dev role:

1. Build scoped context (script — not LLM):

   bash scripts/build-agent-context.sh --role {role} --milestone-dir {path} \
     --ownership "{globs}" --reqs "{REQ-IDs}" --phases "{phase-nums}" \
     --output plans/{slug}/milestone-{N}/.context-{role}.md
   

2. Set ownership for hook enforcement:

   echo "{ownership-globs}" > .claude/.current-agent-ownership
   

3. Log audit entry:

   bash scripts/log-agent-audit.sh --role {role} --milestone-dir {path} \
     --model {model} --context-file plans/{slug}/milestone-{N}/.context-{role}.md \
     --ownership "{globs}" --reqs "{REQ-IDs}"
   

4. Spawn agent:
   • Task(subagent_type: "fullstack-developer", name: "{role}", mode: "plan")
     • model: {from complexity assessment}
     • isolation: "worktree" (if 2+ devs)
     • Prompt: dev-teammate.md + contents of .context-{role}.md + CK Context Block

• If DEBATE.md exists: include as "Design Notes"
• REVIEW and APPROVE each dev's plan
• MONITOR all devs

Context monitoring: See _protocols/_context-limits.md. If a dev reports 70% context limit, read their CHECKPOINT-{role}.md and spawn a fresh replacement agent to resume from checkpoint.

Cross-talk & decisions: See _protocols/_dev-coordination.md

• When each dev completes:
  • GATE: Run validate-stage-completion.sh devs {milestone-dir} --dev-role {role} --ownership {globs}
  • If gate fails (ownership violation, missing checkpoint): block and report
• When ALL devs pass gates:
  • If worktrees: merge branches (see _protocols/_worktree-isolation.md)
  • Review DECISIONS.md for cross-boundary impacts
  • Proceed to Stage 3

Streaming optimization: See _protocols/_dev-coordination.md → Streaming Pipeline

Stage 2.5: Spec Reviewer (mandatory)

• READ .claude/agents/spec-reviewer.md
• Scope context per _protocols/_context-scoping.md
• Task(subagent_type: "code-reviewer", name: "spec-reviewer", model: "sonnet")
• Prompt: spec-reviewer.md + REQUIREMENTS.md (M{N} only) + CONTRACTS.md + ROADMAP.md + list of dev output files + CK Context Block
• Produces: plans/{slug}/milestone-{N}/SPEC-REVIEW.md
• GATE: Run validate-stage-completion.sh spec-reviewer {milestone-dir}
• If any REQ-ID is PARTIAL or MISSING:
  • Send fix requests to relevant devs via SendMessage
  • Wait for fixes
  • Re-run spec-reviewer on fixed files
  • Loop until all REQ-IDs PASS
• Present to user: "Spec review complete. {X}/{Y} REQ-IDs pass. Proceed to tech-lead? (YES / review details)"
• Wait for user approval

If --skip spec-reviewer: tech-lead inherits full spec + quality review (original behavior). SPEC-REVIEW.md will not exist — tech-lead should check REQ coverage in addition to code quality.

Stage 3: Tech Lead Review (optional)

Ask user: "Tech lead review? (YES / SKIP)"

If YES:

• READ .claude/agents/tech-lead.md
• Task(subagent_type: "code-reviewer", name: "tech-lead", model: "sonnet")
• Include SPEC-REVIEW.md in tech-lead's context (spec compliance already verified)
• Minor issues → devs fix inline. Major gaps → GAPS.md → user decides ADD/DEFER/IGNORE.
• GATE: Run validate-stage-completion.sh tech-lead {milestone-dir}

If SKIP: proceed to Stage 4

Stage 4: Tester

• READ .claude/agents/tester.md
• Scope context per _protocols/_context-scoping.md
• Task(subagent_type: "tester", name: "tester", model: "sonnet")
• Generate tests from acceptance criteria + edge cases
• GATE: Run validate-stage-completion.sh tester {milestone-dir}

Stage 5: PM Status Report

• READ .claude/agents/pm.md
• Task(subagent_type: "project-manager", name: "pm", model: "haiku")
• Produces: STATUS.md with progress, pipeline report, blockers, session resume
• GATE: Run validate-stage-completion.sh pm {milestone-dir}

Stage 6: Remediation (if GAPS.md has ADDed phases)

• Spawn additional dev tasks for remediation phases
• Follow Stage 2 flow (plan approval → implement → complete)
• Re-run tester on remediation code
• Update STATUS.md

Shutdown

• CALL SendMessage(type: "shutdown_request") to each teammate
• CALL TeamDelete

Agent Usage Tracking

After EACH agent completes, log usage stats:

| Agent | Tokens | Tool Calls | Duration |
|-------|--------|------------|----------|
| {name} | {total_tokens} | {tool_uses} | {duration}s |

Append to STATUS.md under ## Agent Usage. Print after pipeline completes.

Completion

"Team pipeline complete for milestone-{N}.

• STATUS.md: plans/{slug}/milestone-{N}/STATUS.md
• Next: /quangflow:4-verify for QA/QC
• Smoke test: /quangflow:test"

CK Context Block

Every teammate prompt MUST include:

CK Context:
- Work dir: {CWD}
- Reports: plans/reports/
- Plans: plans/
- Branch: {current git branch}
- Active plan: plans/{feature-slug}/milestone-{N}/ROADMAP.md
- Commits: conventional (feat:, fix:, docs:, refactor:, test:, chore:)
- Refer to teammates by NAME, not agent ID
- Doc lookup: {context7 | websearch | none}
- Code graph: {gitnexus | none}

Error Recovery

See _protocols/_error-recovery.md for checkpoint-based retry protocol.

Pipeline State

See _protocols/_pipeline-state.md for state tracking and session resume.