Cook - Smart Feature Implementation

End-to-end implementation with automatic workflow detection.

Principles: YAGNI, KISS, DRY | Token efficiency | Concise reports

Usage

/cook <natural language task OR plan path>

IMPORTANT: If no flag is provided, the skill will use the interactive mode by default for the workflow.

Optional flags to select the workflow mode:

• --interactive: Full workflow with user input (default)
• --fast: Skip research, scout→plan→code
• --parallel: Multi-agent execution
• --no-test: Skip testing step
• --auto: Auto-approve low-risk steps; high-risk changes stop for human approval before finalize/commit/ship

Composable flags (combine with any mode):

• --tdd: Tests-first per phase — write tests for current behavior before

refactoring, then verify they still pass after the implementation step

Example:

/cook "Add user authentication to the app" --fast
/cook path/to/plan.md --auto
/cook "Refactor auth middleware" --tdd

<HARD-GATE> Do NOT write implementation code until a plan exists and has been reviewed. This applies regardless of task simplicity. "Simple" tasks are where unexamined assumptions waste the most time. Exception: --fast mode skips research but still requires a plan step. User override: If user explicitly says "just code it" or "skip planning", respect their instruction. </HARD-GATE>

<HARD-GATE-SCOUT-FIRST> Before planning OR asking clarifying questions, scan the codebase. Mandatory scout outputs:

1. Project type, language(s), framework(s)
2. Existing modules/files relevant to the task
3. Current patterns/conventions for similar features (so the implementation matches them)
4. Existing docs in ./docs/ and any in-flight plans in ./plans/ covering this area
5. Public APIs, schemas, contracts that the task could affect

State a 3-6 bullet codebase-context summary to the user before asking questions. Skip ONLY when input is a plan.md/phase-*.md path (the plan already encodes scout output). </HARD-GATE-SCOUT-FIRST>

<HARD-GATE-EXACT-REQUIREMENTS> Before producing a plan, you MUST be able to answer ALL of these in one concrete sentence each (use AskUserQuestion to pin them down — do NOT proceed on vague intent):

1. Expected output: the concrete artifact(s) the user will see at the end (file paths, feature behavior, UI screen, API endpoint + payload, CLI command + flags).
2. Acceptance criteria: specific behaviors / inputs → outputs / edge cases that MUST work to call it "done".
3. Scope boundary: what is explicitly OUT of scope this round.
4. Non-negotiable constraints: stack, file locations, naming, backward compatibility, deadlines, performance.
5. Touchpoints: which existing files/modules (from scout) will be modified or extended; which contracts must stay stable.

Ground every AskUserQuestion option in scout findings (e.g., "Add to src/api/users.ts (matches existing pattern) or new src/api/profile.ts?"). Skip ONLY when input is a plan.md/phase-*.md path. </HARD-GATE-EXACT-REQUIREMENTS>

<HARD-GATE-NO-SIDE-EFFECTS> Implementation is NOT done until verified to be side-effect-free. Code-review and test gates MUST prove:

1. New behavior matches every acceptance criterion above.
2. All tests pass — including tests in modules that share files/contracts with the change.
3. No existing business logic / workflow regression: explicitly walk each touchpoint and any caller of changed functions.
4. No new lint/type/build errors anywhere in the repo.
5. Public contracts unchanged unless intentional and called out (function signatures, exported types, API responses, DB schemas, env vars, config keys).

User override: If user invoked --no-test, item 2 is downgraded to a warning. Surface the unverified-tests risk in the finalize AskUserQuestion so the user accepts the trade-off rather than having it silently chosen. Items 1, 3, 4, 5 remain enforceable via the mandatory code-reviewer subagent.

If review/testing reveals a side effect, regression, or broken workflow, STOP. Use AskUserQuestion to present:

• What broke (file, test, workflow, user-facing behavior)
• Why this implementation caused it (1-line cause)
• 2-4 concrete options for the user to choose, e.g.:
• "Revert this slice and re-plan with stricter scope"
• "Keep the implementation and update <dependents> to match the new contract"
• "Add a compatibility shim at <boundary> so old callers keep working"
• "Accept the regression — old behavior was unintended/buggy"

Let the user decide. Do not silently patch around regressions. </HARD-GATE-NO-SIDE-EFFECTS>

Anti-Rationalization

Smart Intent Detection

See references/intent-detection.md for detection logic.

Process Flow (Authoritative)

flowchart TD
    A[Intent Detection] --> B{Has plan path?}
    B -->|Yes| F[Load Plan]
    B -->|No| C{Mode?}
    C -->|fast| D[Scout → Plan → Code]
    C -->|interactive/auto| SC[Scout Codebase MANDATORY]
    SC --> SR[Summarize Findings to User]
    SR --> RQ{Exact requirements captured?<br/>output, acceptance, scope, constraints, touchpoints}
    RQ -->|No| SR
    RQ -->|Yes| E[Research → Review → Plan]
    E --> F
    D --> F
    F --> G[Review Gate]
    G -->|approved| H[Implement]
    G -->|rejected| E
    H --> H1{Simplify signal?}
    H1 -->|Yes| H2[Conditional Simplify]
    H1 -->|No| I[Review Gate]
    H2 --> I
    I -->|approved| J{--no-test?}
    J -->|No| K[Test]
    J -->|Yes| L[Finalize]
    K --> L
    L --> M[Report + Journal]

This diagram is the authoritative workflow. Prose sections below provide detail for each node. If prose conflicts with this flow, follow the diagram.

Workflow Overview

[Intent Detection] → [Research?] → [Review] → [Plan] → [Review] → [Implement] → [Conditional Simplify?] → [Review] → [Test?] → [Review] → [Finalize]

Default (non-auto): Stops at [Review] gates for human approval before each major step. Auto mode (`--auto`): Skips human review gates only for low-risk work. High-risk changes stop for human approval before finalize/commit/ship. Claude Tasks: Utilize TaskCreate, TaskUpdate, TaskGet, TaskList during implementation step. Fallback: These are CLI-only tools — unavailable in VSCode extension. If they error, use TodoWrite for progress tracking instead.

Step Output Format

✓ Step [N]: [Brief status] - [Key metrics]

Blocking Gates (Non-Auto Mode)

Human review required at these checkpoints (skipped with --auto):

• Post-Research: Review findings before planning
• Post-Plan: Approve plan before implementation
• Post-Implementation: Approve code before testing
• Post-Testing: 100% pass + approve before finalize

Always enforced (all modes):

• Testing: 100% pass required (unless no-test mode)
• Code Review (MANDATORY): Spawn code-reviewer subagent with explicit checks:

(a) every acceptance criterion met, (b) no regression to business logic in touchpoints/blast-radius, (c) no breaking changes to public contracts (signatures, schemas, APIs, env vars) unless called out, (d) follows existing patterns from scout, (e) no new lint/type/build errors anywhere. Pass scout summary + acceptance criteria as context. If reviewer flags side effects → trigger HARD-GATE-NO-SIDE-EFFECTS (AskUserQuestion with 2-4 options). Then: User approval OR artifact-gated auto approval. Score is advisory; it never approves by itself.

• Finalize (MANDATORY - never skip):

1. Activate `/project-management` skill (MANDATORY) → run full plan sync-back across ALL phase-XX-*.md (not only current phase), update plan.md status/progress, hydrate Claude Tasks, generate progress report
2. docs-manager subagent → update ./docs if changes warrant
3. TaskUpdate → mark all Claude Tasks complete after sync-back verification (skip if Task tools unavailable)
4. Ask user if they want to commit via git-manager subagent
5. Run /journal to write a concise technical journal entry upon completion

Required Subagents (MANDATORY)

CRITICAL ENFORCEMENT:

• Steps 4, 5, 6 MUST use Task tool to spawn subagents
• DO NOT implement testing, review, or finalization yourself - DELEGATE
• If workflow ends with 0 Task tool calls, it is INCOMPLETE
• Pattern: Task(subagent_type="[type]", prompt="[task]", description="[brief]")

References

• references/intent-detection.md - Detection rules and routing logic
• references/workflow-steps.md - Detailed step definitions for all modes
• references/review-cycle.md - Interactive and auto review processes
• references/subagent-patterns.md - Subagent invocation patterns
• ../_shared/references/workflow-artifacts.md - Review artifact schema and validator contract

Workflow Position

Typically follows: /plan (execute a plan), /brainstorm (implement agreed solution) Typically precedes: /code-review (review after implementation), /test (validate changes) Related: /fix (alternative for bug fixes), /plan (create plan before cooking)