Cook

cook

Overview

| Field | Contract | | --- | --- | | Purpose | Execute an approved plan through verified implementation phases. | | Primary input | plan plan.md, next incomplete phase file, or a concise requirement snapshot for small clear work. | | Primary output | Scoped code changes, phase evidence, review results, updated plan status, and git handoff. | | Boundary | Do not redesign the feature; pause or route back to plan when the Design Contract changes. | | Next handoff | ship plans/YYMMDD-{slug}/plan.md (readiness report) after verified completion. |

Cook executes a plan. The controller keeps context small by handing phase artifacts to subagents only when the phase benefits from isolated context, specialist review, or a durable worker report. Small phases may be executed inline, with evidence proportional to risk.

Use this as an implementation discipline, not a rigid workflow script. When invoked explicitly (/cook) with a plan, require the plan artifacts; when the skill is loaded for a clear small request, a concise requirement snapshot can be enough.

Resources

| Need | Read | | --- | --- | | Phase execution loop | references/phase-execution.md | | Evidence and status contract | references/evidence-contract.md | | Phase brief artifact shape | assets/phase-brief-template.md | | Phase evidence artifact shape | assets/phase-evidence-template.md |

Modes

| Mode | Behavior | | --- | --- | | --fast | Smallest safe loop: phase brief, inline implementation by default, focused verification, evidence; use sub-agents only when the heuristic triggers | | --auto | Default. Inline low-risk phases; dispatch implementer/tester/phase-scoped code-reviewer when thresholds or risk triggers apply; pause for blockers or contract changes | | --hard | High-assurance loop. Bias toward per-phase verification, phase-scoped code-review, final code-review, and pausing on unresolved warnings |

Default mode is --auto.

Flag:

• --tdd: tester writes failing tests from the phase contract before implementer

writes production code. This controls red-first sequencing; it does not make verification optional when omitted.

Support Skill Triggers

Before each phase, load only the support skills that match the phase brief or scout evidence:

| Trigger | Load | | --- | --- | | --tdd, behavior change, bug guard, flaky/failing tests | engineering-practices (references/testing.md) | | auth, user input, secrets, PII, webhooks, external integrations | engineering-practices (references/security.md) | | version-sensitive framework/library/API usage | source-grounding | | production critical path, job, dependency call, diagnosis gap | engineering-practices (references/observability.md) | | schema/data/API migration, deprecation, compatibility risk | engineering-practices (references/migration.md) | | public docs, setup, API, architecture rationale | engineering-practices (references/docs.md) |

Verification Discipline

Every mode must produce runnable verification and durable evidence before a phase is marked complete. --fast changes how much ceremony and delegation are used; it does not allow unverified edits, missing evidence, or silent skipped checks. This is a policy change from the older interpretation where --tdd could be read as the only verification discipline. The mandatory core is:

• state the behavior or contract being proven before editing
• run the smallest command, read, or manual check that can actually prove it
• record exact evidence and any skipped check with a reason
• install a regression/prevention guard when the phase fixes a bug or changes

behavior and such a guard is practical

--tdd remains opt-in for writing failing tests before production code. When it is off, still use engineering-practices (references/testing.md) for risky behavior changes, bug guards, or unclear proof requirements.

Sub-Agent Dispatch Heuristic

Before each phase, decide whether the main controller can safely execute inline or whether a sub-agent is justified.

Use inline execution when all are true:

• phase likely touches one or two local files
• no public contract, data, auth, migration, concurrency, or operational risk
• acceptance criteria are clear and verification is a focused command or read
• expected tool/log output is small enough to keep in the main context

Dispatch sub-agents when one or more are true:

• phase likely touches more than two files, more than one module, or multiple layers
• --tdd is active
• behavior, security, data, migration, API, auth, concurrency, or production risk exists
• verification output, test output, or repo reading would pollute the main context
• the phase needs an independent review lens before it can be trusted
• the first inline attempt is uncertain, blocked, or fails verification

Mode guidance:

• --fast: prefer inline; dispatch only when the heuristic triggers.
• --auto: apply the heuristic per phase; do not spawn sub-agents by habit.
• --hard: strongly prefer implementer, tester, and phase-scoped

code-reviewer for risky or multi-step phases; keep obvious low-risk mechanical edits inline when that is clearly cheaper and still verified.

Step 1 - Scout And Load

1. Use scout --repo with the plan path or selected phase scope when

touchpoints, stack signals, commands, or context trust are uncertain.

1. Locate the plan. If no plan path is provided, search plans/*/plan.md and ask before using one.
2. Read plan.md (its ## Context & Evidence section is the context source;

a separate context.md is a legacy artifact — read it only when present) and the next incomplete phase-XX-*.md.

1. Confirm whether a Design Contract or equivalent requirement snapshot exists.

If missing for non-trivial work, route to plan; for small clear work, write the missing snapshot before editing.

1. Check the current branch. If HEAD is on the default branch (main/master),

create or switch to a work branch before the first edit (load git-workflow references/worktrees.md when an isolated workspace is warranted). Only continue on the default branch with an explicit user override.

1. Report mode, --tdd state, branch, remaining phases, and resume state from

## Session Notes.

Step 2 - Preflight

Before implementing any phase:

• Check the next phase maps to the Design Contract.
• Confirm likely touchpoints are not contradicted by scout evidence.
• Surface contradictions between plan, code, and scout evidence.
• Load any support skill triggered by the phase risk and summarize its check in

the phase brief.

• Decide inline vs sub-agent using the Sub-Agent Dispatch Heuristic and record the

reason in the phase evidence.

• Ask one batched question only for blockers.

Do not ask "should I continue" between clean phases in --auto.

Step 3 - Phase Loop

For each remaining phase, read references/phase-execution.md and execute:

1. Sub-agent path only: write plans/{slug}/evidence/phase-NN-brief.md from

the phase file and Design Contract — the brief is the sub-agent's context unit. For inline execution the phase file itself is the brief; do not duplicate it into a brief file.

1. Record the current git base before implementation.
2. Choose execution path:

• Inline path: main controller edits the scoped files, runs focused verification,

and writes a short implementation note into phase evidence.

• Sub-agent path: if --tdd is active, load engineering-practices

(references/testing.md), then spawn tester first with the brief and expected failing-test report path; spawn implementer with the brief path, report path, constraints, and expected status enum; handle status from references/evidence-contract.md.

1. Run verification:

• Inline path: run the smallest command/read that proves the phase criteria.
• Sub-agent path: spawn tester with the brief, changed files, and test

expectations. When --tdd is active, this run re-executes the suite that contains the red-first tests to confirm they now pass — do not write a second test set.

1. If verification or the tester reports FAIL, spawn debugger with the

failure output, phase brief, changed files, and current attempt count. Re-run verification after the debugger report before continuing. After two failed verification/review cycles on the same phase, load problem-solving to reframe the approach before any third attempt.

1. Record evidence proportional to risk: for a low-risk inline phase, a dated

## Session Notes entry with the verification command and result is enough; write plans/{slug}/evidence/phase-NN-evidence.md when the phase was dispatched to a sub-agent, carried risk, or triggered a review. Also append any real decision or deviation to plans/{slug}/evidence/implementation-notes.md (append-only, created lazily on first write): what you decided, and where the implementation diverged from the plan and why. This is the trail a reviewer or a future session reads instead of trusting conversation memory.

1. Review:

• Inline path: run self-review; spawn code-reviewer (phase-scoped mode)

only if the dispatch heuristic triggers after seeing the diff or evidence.

• Sub-agent path: spawn code-reviewer (phase-scoped mode) with brief,

implementer report, evidence file, and diff/review package.

1. Fix and re-review critical/high findings before marking the phase complete.
2. Update plan.md checkbox and append a dated entry to ## Session Notes

(append-only — do not overwrite earlier phases' notes; the history is what lets a resumed session see what already happened).

On a small edge case the plan didn't cover, don't stop and don't silently guess: choose the conservative option, log the decision and its reason to implementation-notes.md, and continue. Reserve pausing for BLOCKED, unresolved NEEDS_CONTEXT, failed verification/review after a retry, or a decision that changes the Design Contract.

Step 4 - Final Review

After the planned phases have appropriate evidence and review for their risk:

1. Run fresh build/test evidence.
2. Spawn code-reviewer for the whole branch/diff when mode is --hard, when

any phase used inline execution without a phase-scoped review, or when the diff crosses contract/security/data/migration/module boundaries.

1. Resolve BLOCK findings with a single fix loop and re-review.
2. Record final review under plans/{slug}/reviews/final-review.md.

Step 5 - Finalize

Completion check:

• all planned phases checked complete
• per-phase reviews passed when triggered
• final code review is APPROVED or accepted WARNING when triggered
• fresh verification evidence exists

Then:

• run dead-code check and ask before removing orphaned symbols
• load engineering-practices (references/docs.md) when docs/contracts

changed, or in --hard

• spawn finalizer for the combined finalize pass: docs sync when

docs/contracts changed, plan status sync unless --fast, and commit with PUSH_PENDING handoff; if it returns NEEDS_BRANCH, create the work branch and re-invoke instead of overriding

• hand off ship plans/{slug}/plan.md

Agents

| Agent / Skill | Role | | --- | --- | | scout | Read-only setup and context trust | | context-scout | Scoped scout worker dispatched by scout when a subagent scan is useful | | implementer | Implements one phase from a brief and writes report | | tester | Writes/runs tests and reports evidence | | debugger | Fixes reproducible test/build failures | | code-reviewer | Phase-scoped review (one phase vs brief/evidence) and final whole-diff review | | problem-solving | Reframe after 2 failed verification/review cycles on the same phase | | finalizer | Docs sync, plan status sync, commit and PUSH_PENDING handoff |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: danielleit241
• Source: danielleit241/forge
• License: ISC

Install and usage instructions live in the source repository linked above.