Skip to content

t1k:cook

FieldValue
Modulet1k-base
Version5.15.36
Efforthigh
ToolsAgent, AskUserQuestion, Bash, Edit, Glob, Grep, MultiEdit, Read, Skill, Task, TodoWrite, WebFetch, WebSearch, Write

Keywords: add, build, create, develop, end-to-end, feature, implement

/t1k:cook
[task|plan-path] [--interactive|--fast|--parallel|--auto|--yolo|--no-test|--tdd] [--advice|--no-advice]

End-to-end feature implementation. Routes to the registered implementer agent for the current kit. Plan before code; harness over hope.

Kit-wide discipline: features and changes that touch kit-owned content (anything under .claude/) ship via the owning kit source repo per rules/kit-wide-fix-discipline.md. Local-only edits regress on next t1k modules update — implement in the kit, release picks it up.

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

Pre-flight Step 0 — Fuzzy plan/path arg resolution (MANDATORY)

Section titled “Pre-flight Step 0 — Fuzzy plan/path arg resolution (MANDATORY)”

If the user’s arg is not an exact existing path (e.g. chaosforge-demo, plans/chaosforge-demo, phase-3, empty / “active plan”), run the Fuzzy Plan / Path Resolution Protocol at references/fuzzy-plan-resolution.md BEFORE intent detection or bail.

The skill MUST NOT emit “no plan matching” / “exact path required” until the protocol has been applied and its Step 6 reached. The protocol uses only Bash + Glob, which are always available.

Tool guard — AskUserQuestion is deferred

Section titled “Tool guard — AskUserQuestion is deferred”

AskUserQuestion is deferred (name in the system-reminder, schema NOT loaded; direct call → InputValidationError). Before drafting any structured multi-option question, if it’s not in the loaded tool list run ToolSearch(query="select:AskUserQuestion", max_results=1) THEN invoke it. Drafting prose option-bullets first (instead of loading the schema) is a violation. Full rule: rules/always-ask-on-unresolved.md “Forbidden prose” table.

Pick by intent; keep loading minimal.

IntentPath
Ship a feature end-to-end with research + testsDefault --interactive workflow below
Plan exists already; execute itPass plan path; mode auto-detects to code
Skip research; you trust the spec--fast (still requires plan step)
Multiple unrelated features at once--parallel (sub-agents on disjoint files)
Test-driven: tests first, then code--tdd (incompatible with --parallel / --no-test)
Maximum autonomy — run fully automated, never stop to ask--yolo (auto + defer every question to one end-of-run batch; never bypasses test/artifact gates)
Run the whole implementation under advisory supervision--advice (composes with every mode above)
/t1k:cook <natural language task OR plan path>

Runs at advisorySupervision.level (default forks); --advice raises it to full, --no-advice turns it off. Full contract (invocation, forward-carry, PR gate, “never bypasses a gate”): references/advisory-supervision.md. Composes with every mode; changes no execution shape.

Cook-specific checkpoints (after each phase at level full, before the artifact gate, on the 3+-failed-attempt gate): references/advisory-supervision.md § “Cook-specific checkpoints”.

Forward-carry --advice into t1k:test, t1k:review, and any t1k:ship handoff so supervision survives the handoff.

Optional flags (no flag → interactive): --interactive (default) | --fast (skip research) | --parallel (multi-agent) | --no-test | --auto (auto-approve LOW-RISK steps only) | --yolo (maximum autonomy — auto + defer every question to the end) | --tdd (test-driven: write tests first, implement, verify)

Auto/yolo contracts: --auto needs artifact-gate evidence and a low-risk verdict (high-risk always stops for approval); --yolo defers every policy question to one end-of-run batch. Neither bypasses a correctness gate. Full rules: references/artifact-gate-rules.md, references/yolo-mode.md.

Follow protocol: skills/t1k-cook/references/routing-protocol.md — role: implementer

Follow protocol: skills/t1k-cook/references/activation-protocol.md

Game-engine module installed (unity-*/cocos-*) + task touches game logic (combat, inventory, quest, shop, UI-bound rules)? Activate t1k-game-arch alongside the engine skill — the logic/presentation split is an implementation decision, not an afterthought. Unity DOTS ISystem code is exempt (already the tested logic layer); see t1k-game-arch’s DOTS/ECS carve-out.

Fires BEFORE the first implementation edit, so the board is truthful while the work runs. Full contract — do not restate or reimplement it here: skills/t1k-plane/references/workflow-enforcement.md (../t1k-plane/references/workflow-enforcement.md) § Stage 0 + Stage 2. Governing rule: modules/t1k-plane/rules/plane-workitem-workflow.md.

  1. Pre-flight — mode, MCP availability, repo binding, session binding.
  2. Session binding already holds this work → reuse it. Empty → run the match/create flow (§ Stage 1); a cook with no bound work item is the case this gate exists to prevent. Match first; no match: auto-create a work item only if features.autonomousPlanning is true (§ Stage 1), else offer match existing / create new.
  3. t1k-plane-binding.cjs session stage --identifier <IDENT> --stage in_progress. changed:false: already In Progress, skip the write.
  4. changed:true → advance to In Progress (started state group — resolve by group, never by name) and comment the plan path plus branch name.

Done is NOT set here. It fires later from /t1k:git push or PR merge (§ Stage 4).

Plane enforcement blocks on an unbound repo or absent plane server — see the cited Stage 0 contract. Escapes: T1K_PLANE_MODE=advisory|off, --no-plane, recorded optout.

HARD-GATE contract: see skills/t1k-cook/references/workflow-gates.md.

Decision line for the plan, scout and exact-requirements gates: plan|scout|exact-requirements: ran|skipped (<reason>); skipped only for opus-tier or above (sonnet-tier, haiku-tier and unknown models run every step) when the request names exact files or behavior. Never skippable, whatever the tier: anything irreversible, destructive, credential- or consent-related, cross-repo, or a change to a Core Requirement or to a class A gate (docs/gate-decision-contract.md). HARD-GATE-NO-SIDE-EFFECTS is never skipped.

Full enforceable detail for all four gates: references/hard-gates.md. Markers below are the machine-readable contract; the one-line summaries are authoritative-by-reference.

No implementation code until a plan exists and has been reviewed — regardless of task simplicity. Exception: `--fast` skips research but still requires a plan. Override: user says "just code it"/"skip planning". Detail: `references/hard-gates.md` § HARD-GATE. Before planning OR questions, scan the codebase; emit the 5 mandatory scout outputs (project type, relevant modules, conventions, docs/plans, affected contracts) + a 3–6 bullet context summary. Skip only when input is a `plan.md`/`phase-*.md` path. Detail: `references/hard-gates.md` § Scout-First. Before a plan, answer all 5 in one concrete sentence each (via `AskUserQuestion`, scout-grounded — never on vague intent): expected output, acceptance criteria, scope boundary, non-negotiable constraints, touchpoints. Skip only when input is a plan path. Detail: `references/hard-gates.md` § Exact-Requirements. Not done until the test and artifact gates prove all 5 (no default review: `docs/no-unrequested-review.md`): matches acceptance, all (incl. shared-contract) tests pass, no touchpoint regression, no new lint/type/build errors, public contracts unchanged (or intentional+noted). `--no-test` downgrades item 2 to a surfaced warning. Side effect → STOP, `AskUserQuestion` with options. Detail: `references/hard-gates.md` § No-Side-Effects.

Anti-rationalization discipline: see rules/agent-anti-rationalization.md .

Before the first implementation phase, run the reuse search: references/workflow-steps.md § “Prior Art Sweep” (corpus first, grep second). Extend what ships; clone nothing.

Adopt step. If .claude/skills/*/scripts/adopt-from-index.cjs + adopt-profile.json ship, run it BEFORE the first implementation phase with --install (references/adopt-step.md). Exit 3 (capability index not found) is never a silent NEW.

Before implementing a plan, read its ## Human steps (do first): ask every now step in ONE batch and finish them before phase 1, so the run never stops half way; later: steps wait for their phase. Missing section on a plan: add it (t1k-plan/references/human-steps.md). Never start a phase while a now step is open.

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/yolo| SC[Scout Codebase — HARD-GATE-SCOUT-FIRST]
    SC --> SR[Summarize Findings to User]
    SR --> RQ{Exact requirements captured?<br/>output, acceptance, scope, constraints, touchpoints<br/>HARD-GATE-EXACT-REQUIREMENTS}
    RQ -->|No| SR
    RQ -->|Yes| E[Research → Plan]
    E --> F
    D --> F
    F --> H[Implement]
    H --> I{HARD-GATE-NO-SIDE-EFFECTS + artifact gate}
    I -->|proven| J{Test? — model decides}
    J -->|ran| K[Test]
    J -->|skipped| L{Review? — only if the user asked}
    K --> L
    L -->|ran or skipped| N[Finalize — model decides project-manager/docs-manager, always commits]
    N --> M[Report + Journal]

This diagram is authoritative. If prose in this skill or its references conflicts with this flow, follow the diagram.

Mode from input: plan.md/phase-*.md path → code · “fast”/“quick” → fast · “trust me”/“auto” → auto (low-risk auto-approve, stop on high-risk) · “yolo” → yolo (full autonomy, defer every question to one end-of-run batch) · 3+ features/“parallel” → parallel · “no test”/“skip test” → no-test · “tdd”/“test first” → tdd · default → interactive. Full detection logic: references/intent-detection.md.

[Intent Detection] -> [Drift Check] -> [Scout HARD-GATE] -> [Requirements HARD-GATE] -> [Research?] -> [Plan] -> [Implement] -> [No-Side-Effects + Artifact Gate] -> [Test? — model decides] -> [Review? — only if the user asked] -> [Finalize — model decides project-manager/docs-manager; always commits]

Drift Check (Step 0.5, MANDATORY): before any research/plan/code, run a quick git fetch + scan of recent merges (default branch, last ~24h) to confirm a teammate hasn’t already shipped this fix or partially addressed it. Applies in ANY repo where cook runs — kit source, consumer game project, library, anywhere. Skips silently for non-git or no-remote directories. Procedure + decision tree: references/workflow-steps.md § “Step 0.5”.

Tree decision (Plan step, whenever features.mergeUpTree is on): after any plan, run bun .claude/scripts/t1k-tree.cjs trigger plans/<slug> (references/merge-up-tree-execution.md § “Tree decision (Plan step)” has the rest); the tree-decision-gate hook blocks mutations outside plans/** and every implementer spawn until it runs.

Issue Claim (when routing a fix/issue-driven workflow): cook defers to the same Step 0.5 claim gate defined in t1k:fix — enforced via the shared .claude/scripts/t1k-issue-claim.cjs and skills/t1k-git/references/issue-claim-discipline.md. No separate gate logic here.

Per-mode research, testing, review and pausing: references/workflow-steps.md § “Mode Table”.

Full step definitions: references/workflow-steps.md TDD sub-step details: references/workflow-steps.md → ## --tdd Flag Behavior Review processes: references/review-cycle.md

  • --tdd + --parallel: REFUSE with error: “TDD requires strict ordering (tests → implement → verify); parallel execution cannot preserve this. Use --tdd alone, or --parallel without --tdd. For a fast sequential path, consider --tdd --fast.”
  • --tdd + --no-test: REFUSE with error: “TDD mode inherently requires the test suite; --no-test is contradictory. Remove one of the flags.”
  • --auto + --interactive: ALLOWED (as t1k:plan): --interactive wins.
  • --yolo + --interactive: REFUSE with error: “Yolo defers every pause to the end of the run and interactive asks immediately — they are contradictory. Pick one.”
  • --yolo implies --auto (it is a strict superset); if both are passed, treat as --yolo. --yolo + --tdd and --yolo + --parallel are ALLOWED (yolo governs pause-deferral, not execution ordering); --tdd + --parallel stays refused regardless of --yolo.
  • --parallel contract-first gate: define the integration contract before spawning parallel implementers whose outputs meet at a shared boundary (references/subagent-patterns.md § “Contract-first gate (--parallel)”).

Merge-Up Tree (flag-gated — features.mergeUpTree)

Section titled “Merge-Up Tree (flag-gated — features.mergeUpTree)”

Only when the plan’s root node carries "mergeUpTree": true: the Implement step runs references/merge-up-tree-execution.md instead of one implementer spawn. Otherwise unaffected.

Artifact Gate (harness for the review + finalize stages)

Section titled “Artifact Gate (harness for the review + finalize stages)”

After implementing, write the 5 required artifacts and validate via the workflow-artifact-gate hook. Full rules and kill switch: references/artifact-gate-rules.md. SSOT shared with t1k:fix. A phase’s Accept: command is recorded by bun .claude/scripts/t1k-record-verification.cjs --artifact-dir <dir> --phase <phase-file> (it runs it and writes exit code and commit; declare the phases with --declare-phases <phase-file...>, which sets planDir and planPhases), never typed by hand: references/accept-gate.md.

Subagent Delegation — when a phase runs, it delegates

Section titled “Subagent Delegation — when a phase runs, it delegates”

Whether Testing and Finalize’s steps run is the model’s call (references/workflow-steps.md § “Step Decision Format”). Review runs only when the user asked (docs/no-unrequested-review.md); otherwise it is skipped with a one-line reason. A step that runs goes via the Task tool, never inline (the implementer is not the reviewer, the planner is not the coder). Phase → agent: Research→t1k-researcher · Plan→t1k-planner · Implement→implementer (kit-resolved) · UI→ui-developer (kit-resolved) · Test→t1k-tester/t1k-debugger · Review (only when asked)→/t1k:review (falls back to t1k-code-reviewer if a lane agent is unavailable) · Finalize→t1k-project-manager+t1k-docs-manager+t1k-git-manager. Any plan, inline or not, then runs the Workflow section’s Tree decision step. Full table + per-agent rationale + injection protocol: references/subagent-patterns.md.

Finalize: t1k-git-manager always runs (committing is how the work lands, not a review checkpoint). t1k-project-manager (plan sync-back) and t1k-docs-manager (update ./docs) run only when their trigger holds: references/workflow-steps.md § “Step 6: Finalize”.

  • When you discover a non-obvious gotcha while implementing, emit a [t1k:lesson kit="..." skill="..." fragment="..." reason="..."] marker in your final message. The lesson-collector hook queues it for follow-up sync-back automatically.

Correctness Gates (every mode, unconditional)

Section titled “Correctness Gates (every mode, unconditional)”

These are never the model’s call, whether or not Testing/Review ran: artifact-gate validation, and (when tests ran) 100% test pass (--no-test downgrades it to a surfaced warning per HARD-GATE-NO-SIDE-EFFECTS). A review’s score is advisory; only artifact validation approves. Pausing for human input on any of Post-Research, Post-Plan, Post-Implementation, Post-Testing is no longer a fixed checkpoint: references/workflow-steps.md § “Pausing for the user”.

Pre-flight runs bun .claude/skills/t1k-plan/scripts/validate-plan.cjs <plan-dir> on the plan about to execute: exit 0 and LEGACY proceed, exit 1 blocks until the plan is fixed, exit 2 is printed with its row and cook proceeds. Each phase’s Accept: is the done check: references/accept-gate.md.

At the start of cook <plan> also run bun .claude/scripts/t1k-spawn-eta.cjs plan-eta <plan-dir> --auto (no project copy → bun ~/.claude/scripts/t1k-spawn-eta.cjs) (read-only, no --record, zero tokens, silent when disabled), print its first line and continue; it never blocks.

When implementation goes wrong — recovery via rollback

Section titled “When implementation goes wrong — recovery via rollback”

Corrupted ~/.claude/ state → t1k rollback to a snapshot, or t1k install --reset (takes its own backup). NEVER rm -rf ~/.claude/ — the gate forbids it. Procedure: references/rollback-recovery.md.

T1K resolves env vars in priority order — never hardcode values. Details: references/env-hierarchy.md

Artifact gate: T1K_WORKFLOW_ARTIFACT_DIR pins the active artifact dir (overrides the pointer file); T1K_WORKFLOW_ARTIFACT_GATE_DISABLED=1 is the kill switch (debugging the hook only).

  • references/intent-detection.md, yolo-mode.md, workflow-steps.md, review-cycle.md, subagent-patterns.md, env-hierarchy.md — detection and routing, yolo doctrine, step definitions, review processes, subagent patterns, .env resolution.
  • references/god-prefab-extraction-risk.md, runtime-smoke-gate.md, command-chaining.md — prefab-move audit, Step 3 Play Mode smoke gate, multi-command chains and task orchestration.
  • .claude/hooks/workflow-artifact-gate/artifact-schema.cjs — the 5 artifact shape validators the gate runs (JSON Schemas under .claude/schemas/ are a source-repo authoring reference, not shipped — #785).

If Finalize opens a PR, invoke t1k:contribution-score with type=sync-back-pr + PR URL/title/body. Fire-and-forget; SSOT gates non-T1K repos. See .claude/skills/t1k-contribution-score/SKILL.md.

Sub-agent forking: see skills/t1k-architecture/references/fork-hygiene.md.