cook

name	cook
description	Drive a feature from spec to production through hard-gated stages — plan, code, test, docs, deploy — with verification at each gate. Infrastructure-agnostic methodology.
category	Feature Delivery
status	active

Cook

Purpose

A feature lifecycle pipeline: take one feature from written spec to production by walking it through defined stages with mandatory verification at each handoff. Reduces "I thought you tested that" failures.

Distinct from:

• [[bootstrap]] — sets up a new project (one-time).
• /ck:cook <plan> --from-plan — implements code given an existing plan (one stage).
• [[team]] — multi-agent parallel fan-out across independent sessions.
• [[dynamic-workflow]] — gated, cost-previewed orchestration recipes (/ck:flow).

cook is sequential, single-feature, gated.

Skill vs /ck:cook command

The skill defines the methodology and gates. The /ck:cook command (.claude/commands/ck/cook.md) is the workflow trigger that walks an agent through them with mode flags (--fast, --auto, --from-plan, --no-test). The skill is the source of truth; the command is sugar.

Use /ck:cook <plan> --from-plan as the fast-path for "plan-already-exists".

When to Use

• A spec is approved and you need to ship it
• Junior contributor needs guardrails through their first feature
• After repeated incidents where a feature shipped without docs/tests/changelog
• Any time you catch yourself skipping verification "just this once"

Activation phrases: "cook this feature", "take this from spec to deploy", "feature pipeline for..."

The Stages

#	Stage	Gate to next
0	Exact-Requirements Gate — fill the 5 items below before planning	5 fields filled & confirmed (or [ASSUMED]-logged in --auto); scope boundary defended per the scope lock below
0.5	Verify-Plan Gate — falsify the plan's factual claims before implementing (mandatory with --from-plan)	verification table approved; no REFUTED load-bearing claim (see [[verify-plan]])
1	Plan — confirm spec; identify files to change; list risks	Spec linked + impact diff produced
2	Code — fresh implementer subagent per phase (see Implement below)	All new code under existing file-size limits; lint passes; per-phase exit gate green
3	Test — unit + integration tests written and green	[[scenario]]-derived test cases cover at least 1 happy + 1 negative + 1 recovery
4	Review — dispatch code-reviewer agent per [[code-review]] skill protocol	Severity buckets: Critical = 0 AND High = 0 (else fix → re-test → re-review loop)
5	Docs — update README / changelog / API docs	Reviewer can use the feature with docs alone
6	Deploy — merge, release, verify in prod	Smoke check passes; rollback path documented

Gating rule: a stage cannot start until the prior gate passes. Skipping is a feature, not a bug — but it must be logged with a reason.

Closing gate (whichever stage you stop at): before any completion claim, answer every Stage-0 acceptance criterion with its evidence — a table of criterion → the test output or command result that settles it. A criterion with no evidence row is not met, and the run is not complete. This is [[code-review]]'s Iron Law applied to the spec rather than to the diff: Stage 0 exists to make the criteria verifiable, and a pipeline that never verifies them has only made a promise. It is stated here rather than inside a stage because Deploy runs only in --auto and Docs can be skipped — the check must survive every path through the table. (It lived only in /ck:cook's Report section, so every other consumer of this skill collected acceptance criteria at Stage 0 and never looked at them again.)

Ledger (cross-cutting, not a stage): every gate transition appends one line to plans/<plan>/STATE.md per the [[run-state]] skill — phase <N>: gate <name> → PASS|FAIL (evidence: <cmd> → <result>). A killed run resumes from the ledger + gate re-runs alone; TodoWrite is a UI mirror, never the record.

Review stage protocol: follow [[code-review]] skill — get BASE_SHA/HEAD_SHA, optionally scout edge cases first, dispatch code-reviewer subagent with WHAT_WAS_IMPLEMENTED + PLAN_OR_REQUIREMENTS + DESCRIPTION. See code-review/references/requesting-code-review.md.

Stage 0 — Exact-Requirements Gate

Before any planning, derive these 5 items from the task. This is a hard gate: if any item cannot be derived, STOP and ask the user ONE clarifying question at a time — do NOT fill fields by probability. AI coding fails far more often from a vague spec the model silently guesses around than from model weakness.

1. Expected output — the concrete artifact the user will see/use (an endpoint, a screen, a CLI file — not "improve X").
2. Acceptance criteria — input→output pass/fail conditions that are verifiable.
3. Scope boundary — what is explicitly NOT done this round (anti scope-creep). Not merely recorded — defended, via the scope lock below.
4. Non-negotiable constraints — stack, file locations, naming, compatibility.
5. Touchpoints — which module/file/contract will be touched (blast radius).

Scope lock (item 3, defended)

Over-scoping is a distinct failure from a wrong root cause: the diagnosis can be right and the change still three times too large (measured: wrong_approach 10 + excessive_changes 4, each costing a full plan-write cycle). Whenever the task could span more than one repo or layer, three sub-gates apply before planning:

1. Two options, minimal first. Present (A) minimal-surface and (B) thorough. For each: which repos and layers are touched, and which existing codebase patterns/conventions it follows or breaks. Recommend one; wait for the pick before planning or coding. Default to the narrowest surface; justify any expansion. In --auto: pick A and [ASSUMED]-log it — never silently expand.
2. Convention check. Name the architectural patterns the change touches and assert compliance explicitly (a real fix registered a DB context in the wrong host, violating a host-separation pattern the codebase enforced but the plan never consulted).
3. No unrequested artifacts. Do not create files the user did not ask for — no backfill SQL, no scratch scripts, no helper docs — in a branch destined for a PR. Need one anyway → name it and ask first.

Mode behavior:

• Default / --fast: gate is mandatory. --fast only skips research, NOT this gate.
• --auto: fill all 5 best-effort from context; LOG each assumed field marked [ASSUMED] (inline in run output / plan file, same place waivers go) instead of stopping to ask.
• --from-plan: EXTRACT the 5 items from the plan file (don't ask the user); any item the plan doesn't settle → fill best-effort and [ASSUMED]-log it. A hand-written plan without acceptance criteria must not silently un-anchor the goal.

Gate passes only when all 5 are filled & user-confirmed (default / --fast) or all 5 are filled & [ASSUMED]-logged (--auto / --from-plan).

Closing the loop: the 5 items are not write-once — the final report re-verifies each acceptance criterion against fresh evidence (criterion → test output / command result), per [[code-review]] verification gates.

Stage 0.5 — Verify-Plan Gate

Treat the plan as a set of falsifiable hypotheses, per the [[verify-plan]] skill: extract every factual claim (root cause, affected rows, which code path runs, "already done" status) and prove or disprove each with git log/git blame/git show, read-only queries, and direct file reads. Output: the claim → verdict → evidence table to plans/<plan>/reports/plan-verification.md.

• Mandatory whenever --from-plan is active — a plan written in another session is exactly the case that shipped a wrong root cause through 3 merged PRs. Elsewhere: run it when the plan asserts ≥1 falsifiable claim about existing behaviour; a greenfield plan has nothing to falsify.
• No code until the table is approved. Any REFUTED load-bearing claim → back to planner. All-REFUTED is a legitimate outcome (one plan's migration proved to be a no-op — finding that early is the win).

Implement — fresh subagent per phase

Implementation runs in a fresh implementer subagent per phase (backend-developer / frontend-developer), never in the main session. The main session keeps only the loop, the gates, and the ledger — implementing inline accretes every file read, diff, and test output into one context that is re-sent on every later turn (measured dispatch pathology: 42k chars, 99% pasted history).

The dispatch contains exactly:

1. one line on where the phase fits;
2. the brief file path ("read this first — your requirements, exact values verbatim"; generate via .claude/scripts/ck/phase-brief.cjs);
3. interfaces/decisions from earlier phases the brief can't know;
4. resolutions of ambiguity you already spotted;
5. the report-file path + report contract.

Never the session's history. Keep dispatches <2k chars.

• Statuses: DONE · DONE_WITH_CONCERNS · NEEDS_CONTEXT · BLOCKED — never force the same model to retry unchanged.
• Never dispatch two implementers in parallel on the same tree — editing phases run sequentially. Agents that write only reports fan out — research, verify-plan, review. The criterion is what the agent writes, not which stage it sits in, so a later read-only stage inherits the permission instead of waiting on an edit here (this line read "(research, review)" while /ck:cook had already extended the fan-out to Verify-Plan — an enumeration drifts, a criterion doesn't). Mechanics — whole batch in one message, own report path per agent, STATE.md appended by the orchestrator alone — live in .claude/commands/ck/cook.md § Dispatch Tiers.
• After each phase: run the phase's declared exit gate, append the STATE.md line, and verify the agent actually changed something (git diff) before recording it complete — "agent reported success" is not evidence; a dead agent leaves no diff.

Worked Example (CI: GitHub Actions)

GitHub Actions is one execution substrate; the methodology is independent. Sample mapping:

Stage	Local check	CI check
1 Plan	Spec linked in PR description	pr-template action enforces fields
2 Code	lint + typecheck	Same in CI
3 Test	npm test	Test workflow, coverage report
4 Review	code-reviewer agent local	PR review bot / required reviewer
5 Docs	README diff checked	docs-drift linter
6 Deploy	Manual approval	Release workflow + smoke job

Same stages map cleanly to GitLab CI, Buildkite, CircleCI, or a Makefile — methodology stays.

Failure Recovery

• Gate fails → don't proceed; either fix or explicitly waive with a reason in the PR/plan (and a waiver line in STATE.md).
• Loop cap + breaker: max 3 fix cycles per gate (Test, Review), and ≤5 fix cycles total per feature — a Review fix that breaks a test hands control to the Test gate with its own fresh budget, so per-gate caps alone permit 9 cycles of ping-pong. Hitting either cap: halt, run [[retro]] on spec/scope, ask the user. (The feature cap lived only in /ck:cook for a while; every other consumer of this skill — /ck:fix, /ck:flow, a bare activation — therefore had the ping-pong hole open.) At the 3rd failed cycle, don't just ask the user — adjudicate each open finding and record the ruling in STATE.md ([[run-state]]):
  • reviewer wrong / contestable → parked — <finding> — ruling: <why the code stands>
  • real but nothing downstream depends on it → parked, marked deferred
  • real and load-bearing (a later phase builds on it, or it reveals a plan defect) → BLOCKED, stop, surface the finding + the plan text it collides with + the fix history A silent discard is forbidden; the final review reads the parked list and triages what must be fixed before merge. Then run [[retro]] and ask the user.
• Multiple gates fail → halt and run a [[retro]] on the spec or estimation; cook again on a refined scope.
• Production smoke fails → execute the documented rollback path before debugging.
• Interrupted run (spend limit, session kill, 529) → resume via the [[run-state]] protocol: read the ledger, re-derive true state from git + gate re-runs, emit the derived-state table, continue from the first unconfirmed phase. Zero re-implementation.

Anti-Patterns

• Stage 6 first: deploying then writing tests. Cook order is non-negotiable; if you must hot-fix, do it outside cook.
• All stages in one PR: huge diff, impossible review. Split per stage where reasonable, or at least segment commits by stage.
• No waiver log: skipping gates silently. Force the waiver to be visible (PR comment, plan checkbox).
• Planning on a vague spec: filling the 5 Stage-0 fields by probability instead of asking. If a field is unknowable from the task, ask ONE question — don't guess.

References

See references/:

• github-actions-deployment.md — sequential CI/CD task orchestration
• conventional-commits-semantic-release.md — automation from commit to release
• feature-flag-deploy-decoupling.md — separating deploy from release

Cross-links

[[bootstrap]], [[team]], [[dynamic-workflow]], [[planning]], [[scenario]], [[test-automation]], [[code-review]], [[retro]], [[run-state]], [[verify-plan]], [[tdd]]