t1k:cook
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | high |
| Tools | Agent, AskUserQuestion, Bash, Edit, Glob, Grep, MultiEdit, Read, Skill, Task, TodoWrite, WebFetch, WebSearch, Write |
Keywords: add, build, create, develop, end-to-end, feature, implement
How to invoke
Section titled “How to invoke”/t1k:cook[task|plan-path] [--interactive|--fast|--parallel|--auto|--yolo|--no-test|--tdd] [--advice|--no-advice]TheOneKit Cook — Feature Implementation
Section titled “TheOneKit Cook — Feature Implementation”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 perrules/kit-wide-fix-discipline.md. Local-only edits regress on nextt1k 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.
Decision tree — which path do I take?
Section titled “Decision tree — which path do I take?”Pick by intent; keep loading minimal.
| Intent | Path |
|---|---|
| Ship a feature end-to-end with research + tests | Default --interactive workflow below |
| Plan exists already; execute it | Pass 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>Advisory supervision (ON by default)
Section titled “Advisory supervision (ON by default)”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.
Agent Routing
Section titled “Agent Routing”Follow protocol: skills/t1k-cook/references/routing-protocol.md — role: implementer
Skill Activation
Section titled “Skill Activation”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.
Plane Work-Item Gate (MANDATORY)
Section titled “Plane Work-Item Gate (MANDATORY)”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.
- Pre-flight — mode, MCP availability, repo binding, session binding.
- 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.autonomousPlanningis true (§ Stage 1), else offer match existing / create new. t1k-plane-binding.cjs session stage --identifier <IDENT> --stage in_progress.changed:false: already In Progress, skip the write.changed:true→ advance to In Progress (startedstate 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.
Anti-rationalization discipline: see rules/agent-anti-rationalization.md .
Prior art — sweep before you build
Section titled “Prior art — sweep before you build”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.
Human steps first
Section titled “Human steps first”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.
Process Flow (Authoritative)
Section titled “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/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.
Smart Intent Detection
Section titled “Smart Intent Detection”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.
Workflow
Section titled “Workflow”[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
Guards
Section titled “Guards”--tdd + --parallel: REFUSE with error: “TDD requires strict ordering (tests → implement → verify); parallel execution cannot preserve this. Use--tddalone, or--parallelwithout--tdd. For a fast sequential path, consider--tdd --fast.”--tdd + --no-test: REFUSE with error: “TDD mode inherently requires the test suite;--no-testis contradictory. Remove one of the flags.”--auto + --interactive: ALLOWED (ast1k:plan):--interactivewins.--yolo + --interactive: REFUSE with error: “Yolo defers every pause to the end of the run and interactive asks immediately — they are contradictory. Pick one.”--yoloimplies--auto(it is a strict superset); if both are passed, treat as--yolo.--yolo + --tddand--yolo + --parallelare ALLOWED (yolo governs pause-deferral, not execution ordering);--tdd + --parallelstays refused regardless of--yolo.--parallelcontract-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.
Environment Variables
Section titled “Environment Variables”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
Section titled “References”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).
Contribution Scoring
Section titled “Contribution Scoring”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 Fork Hygiene
Section titled “Sub-Agent Fork Hygiene”Sub-agent forking: see skills/t1k-architecture/references/fork-hygiene.md.