Skip to content

t1k:plan

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

Keywords: approach, architecture, breakdown, design, implementation plan, phased plan, phases, plan the, plan this, roadmap

/t1k:plan
[task] OR archive|red-team|validate [--auto|--fast|--hard|--deep|--parallel|--two|--tdd|--team|--no-validate|--interactive] [--advice|--no-advice] [--team-devs N|--team-reviewers N|--team-researchers N|--team-debuggers N]

TheOneKit Plan — Implementation Planning

Section titled “TheOneKit Plan — Implementation Planning”

Create phased implementation plans. Routes to registered t1k-planner agent via routing protocol.

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

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

If the arg is not an exact existing path (partial plan name, phase-3, empty / “active plan” for resume), run the Fuzzy Plan / Path Resolution Protocol at skills/t1k-cook/references/fuzzy-plan-resolution.md BEFORE bail. Never emit “no plan matching” until its Step 6 is reached.

Tool guard — AskUserQuestion (interactive mode only)

Section titled “Tool guard — AskUserQuestion (interactive mode only)”

Inert under the autonomous default. Under --interactive (or features.autonomousPlanning: false) call AskUserQuestion directly, ToolSearch first when only deferred, and STOP if neither. Full decision tree, forbidden-prose clause and failure mode: references/interactive-mode.md.

Use for: new feature plans, system architecture, requirement breakdown, roadmaps with testing and review gates.

Do not ask the user at design forks. Take the Conservative-Pick where a step would ask, record a row in the plan README’s ## Deferred decisions, and surface the list ONCE at the end. Doctrine: references/autonomous-mode.md; the Conservative-Pick rule is SSOT in skills/t1k-cook/references/yolo-mode.md.

Opt-outs: --interactive (per-run, wins) or features.autonomousPlanning: false; either restores ask-at-each-fork.

Still asked even autonomously (irreversible/destructive): deletions, repo or package creation, publishing, force-push, secrets/credentials, permission or config changes to the consumer’s machine. Such a phase is written BLOCKED and listed in ## Human steps (do first).

Dispatch t1k-planner with run_in_background: true (main session stays free). Pass false only under --interactive or when the user asked to watch. The deliverable is the plan files on disk plus the deferred-decisions list in its final message.

FlagResearchRed TeamValidationCook Handoff
--autoAuto-detectFollows modeAuto (unless --no-validate)/t1k:cook
--fastSkipSkipSkip/t1k:cook --auto
--hard2 researchersYesAuto (unless --no-validate)—
--deep3 researchersYesAuto + mandatory cook-time gate—
--parallel2 researchersYesAuto (unless --no-validate)/t1k:cook --parallel
--tddComposable with any mode——Annotates phase cards with 3.T/3.I/3.V sub-steps
--teamComposable with any mode——Emits explicit teammate roster per phase; cook handoff → /t1k:team cook
--adviceComposable with any mode——Runs the plan under advisory supervision; forward-carried into the cook handoff

Mode comparison, --deep vs --hard, and --team details: references/workflow-modes.md. Team-shape output contract: references/team-shape-template.md.

  • --hard + --deep: REFUSE. --deep is a strict superset of --hard.
  • --fast + --deep: REFUSE. Fast mode skips rigor; --deep mandates it.
  • --tdd + --parallel: REFUSE. TDD requires strict T→I→V ordering.
  • --fast + --hard: ALLOWED but discouraged; document the reason in the plan.
  • --no-validate: suppresses ONLY the post-creation validation interview (see “Auto-Validation After Plan Creation”); the runner (validate-plan.cjs) still runs. No-op under --fast. Under --deep the cook-time /t1k:review gate runs only when the user asked for a review (docs/no-unrequested-review.md).
  • --team sub-flags (--team-devs, --team-reviewers, --team-researchers, --team-debuggers): IGNORED unless --team is also present; warn if set without it.
  • --advice: composes with every mode and sub-flag. Never REFUSE it; it adds a supervisor, not an execution shape.
  • --interactive: composes with every mode and sub-flag. Never REFUSE it; it changes only the question channel. Wins over features.autonomousPlanning: false. Plan has no --yolo flag, so cook’s refusal of --yolo + --interactive concerns cook’s own flags and does not conflict. Detail: references/workflow-modes.md.

Runs at advisorySupervision.level (default forks) without being asked. --advice raises it to full; --no-advice turns it off and forward-carries the opt-out. Before presenting a plan with a real decision fork as final, consider spawning t1k-kongming and emit [t1k:advice-outcome checkpoint=plan-final verdict=...] (the plan-final report gate; forward-carry the level into the cook handoff). Contract: skills/t1k-cook/references/advisory-supervision.md; references/advisory-checkpoints.md, references/plan-final-report-gate.md.

SubcommandPurpose
/t1k:plan archiveArchive plans + journal (procedure: references/archive-subcommand.md)
/t1k:plan red-teamAdversarial plan review
/t1k:plan validateCritical questions interview

After plan creation, output the cook handoff line: default /t1k:cook {plan-path} (single-agent execution). When --team was set, /t1k:team cook {plan-path}. NEVER suggest /t1k:cook for a --team plan: single-agent execution silently downgrades the parallelism the plan was built around.

In autonomous mode this gate is satisfied by the ## Deferred decisions section: write the decision down, take the Conservative-Pick, move on. The rule below applies in full only under --interactive / features.autonomousPlanning: false.

If the t1k-planner needs to confirm 2-4 design decisions before finalizing, it MUST invoke AskUserQuestion (batch up to 4 per call). NEVER list open questions as numbered prose, checkbox alternatives, default tables or “override before /t1k:cook” tables, whatever the disclaimer. This applies at every step where decisions remain.

Autonomous equivalent. A ## Deferred decisions row states a choice already taken, never a still-open choice with a recommended branch. Full text: references/open-questions-autonomous-equivalent.md.

Self-check before writing the plan file: scan the draft for ANY section pairing an unresolved decision with a recommended default or a table of alternatives, whatever its heading (Open decisions, OD-N, a bare | Option | Consequence | table). If found: delete it, invoke AskUserQuestion (autonomous: append a ## Deferred decisions row), and rewrite it as resolved. Also substring-scan for the forbidden phrases in the Tool guard’s clause. Full text: references/open-questions-self-check.md; pattern to avoid: docs/decision-discipline-examples.md “Failure mode — post-design open questions”.

Before a phase specifies new work, the plan must record what already exists. Any claim that something is absent carries the scope searched (zero across <paths>, never a bare “does not exist” / “greenfield”). Read-only vendored code is in scope for discovery; consult indexes (skills, docs, manifests) before grepping. Why wide, the corpus-sweep-first technique, and the unverified rule: references/prior-art-gate.md. Every verdict lands as a row in ## Reuse Ledger.

No override: every phase's Reuse Ledger row must be filled before that phase's work is specified, and before any option set is proposed. One row per capability:
#CapabilityVerdictEvidence

Verdicts — exactly four: REUSE (Type @ file:line) · EXTEND (primitive plus the specific field/parameter added) · REPLACE (what it replaces and why) · NEW (nothing covers it).

A NEW row is invalid without a recorded search verdict, byte-exact on two separate lines, never merged:

reuse-search: not-found-after-corpus-and-grep
scope: <paths> | swept: <YYYY-MM-DD>

Search by content words, not the plan’s name for it. Search wide before declaring absence: the project’s capability index and duplicate-shape census (if any), then the studio corpus (mcp__knowledge-retrieval__doc_search, technique in t1k-knowledge-retrieval), then grep to ground the hit. The verdict token is the canonical cross-kit token (rules/search-before-you-build.md); only the scope:/swept: values are project-specific. Zero REUSE/EXTEND rows on a non-trivial feature is a red flag. Full text: references/reuse-ledger-detail.md.

Engine projects: run the scripted adopt step first. When an installed engine kit ships .claude/skills/*/scripts/adopt-from-index.cjs (with adopt-profile.json), run it over the phase’s capabilities (--from-file, no --install while planning) and take its REUSE/EXTEND/NEW lines as starting rows, Evidence = the package. exit 3 (capability index not found) is a failed search, never a NEW. The ledger hook checks only that reuse-search: text exists; the script run is what makes the row true.

plan.md/README.md carries ## Self-improvement loop: Signal (emitted when wrong), Loop (the EXISTING loop consuming it, never a new pipeline), Fix (artifact it lands in), Guard (what stops regression), or None, because <reason>; silence fails. references/self-improvement-loop.md.

Auto-Validation After Plan Creation (MANDATORY)

Section titled “Auto-Validation After Plan Creation (MANDATORY)”

Once the plan file(s) are on disk and the Open Questions Gate is satisfied, automatically run the critical-questions interview (the /t1k:plan validate interview). Do NOT wait for the user. Order: auto-validation → finish ETA → Plane gate → cook handoff.

Fires for: every invocation. Interview skipped for: --fast and --no-validate. The runner is never skipped: --no-validate suppresses only the interview, and the planner always runs the runner (exit 1 blocks the handoff).

What it does: the planner always runs bun .claude/skills/t1k-plan/scripts/validate-plan.cjs <plan-dir> (exit 1 blocks the handoff; exit 2 is printed with its row). The interview is skipped when the runner exits 0 and prints open-decisions: 0; otherwise it batches every open decision into AskUserQuestion (≤4 per call; autonomous mode: ## Deferred decisions rows), writes answers back as decided facts, and emits the cook handoff only after validation resolves clean. Steps: references/auto-validation-steps.md.

--deep keeps its separate inter-phase /t1k:review gate at cook time (only when the user asked for a review); --no-validate does not suppress it.

Every plan.md has ## Human steps (do first): EVERY step only a human can do across all phases, each with the phase it unblocks, the prefilled page or command, and why an agent cannot (None. if none); each Gate: human phase must appear or validate-plan-deps FAILs. At approval, ask ALL now steps in one batch; later: <reason> steps wait for their phase. Detail: references/human-steps.md.

plan.md opens with ## Forecast BEFORE the phase table (confidence, success rate, effect, uncertainties, kill criteria, BASIS-tagged numbers); show it at approval, re-score when data lands. Size rule: <= 1 phase, effort S, 0 NEW ledger rows and 0 human gates may write Forecast: skipped (<reason of >= 4 words>). Fields, caps, template: references/confidence-forecast.md.

After the runner passes and BEFORE the Plane gate the planner runs bun .claude/scripts/t1k-spawn-eta.cjs plan-eta <plan-dir> --auto --record (no project copy → bun ~/.claude/scripts/t1k-spawn-eta.cjs) (CLI only, zero LLM tokens) and prints one done by HH:MM <tz> line. --no-validate and --fast do not skip it; features.spawnEta:false or planEta.autoShow:false silences it; a failure is one line, never a block. Every phase file carries a Depends-on: line (required for plans dated 261008 or later). Line fields and by-hand use: references/finish-eta.md; skills/t1k-estimate/SKILL.md.

Runs AFTER the plan file exists and auto-validation has resolved clean (so the phase breakdown can be estimated), and BEFORE the cook handoff. Full contract, not restated here: skills/t1k-plane/references/workflow-enforcement.md (../t1k-plane/references/workflow-enforcement.md) § Stage 0 + Stage 1. Governing rule: modules/t1k-plane/rules/plane-workitem-workflow.md. Steps (pre-flight, match, bind or create, estimate, advance): references/plane-work-item-gate-steps.md.

  • Interactive: never auto-create. No confident match → AskUserQuestion (bind candidate · bind typed identifier · create new · proceed unbound).
  • Autonomous (default): auto-create the work item in the bound project and bind it. Work item only, never a project, module or estimate. references/plane-autonomous-clause.md.

Set the estimated time in hours, summed from the per-phase estimates (confirmed with the user before writing under --interactive; autonomous: write it and record a ## Deferred decisions row, a control value). Then advance the work item to Todo (resolve the unstarted group by group, never by name). Plane enforcement blocks, not warns, on an unbound repo or absent plane server. Escapes: T1K_PLANE_MODE=advisory|off, --no-plane, recorded optout.

Follow protocol: skills/t1k-cook/references/routing-protocol.md. Runs in role t1k-planner, which also runs the mechanical scripts/cochange-seams.cjs before it publishes a multi-lane wave (advisory, references/seam-check.md) and the runner in its validation step. scripts/plan-lead-time.cjs is a measurement tool, not a planner step; research goes to t1k-researcher.

Spawn briefs that cite plans/<dir>/... get a planId on their telemetry rows: references/plan-id-join.md.

Multi-round plan-review fan-out (named-agent routing)

Section titled “Multi-round plan-review fan-out (named-agent routing)”

Default review is ONE fresh-context reviewer (Review: 1 reviewer). The 4-round review runs only with --deep (Review: 4-round, named in Flags:); --hard, /t1k:plan validate and /t1k:plan red-team use one reviewer unless the user asks for rounds. Every reviewer is an explicitly-named specialist; general-purpose is NEVER acceptable. Round table and spawn contract: references/plan-review-rounds.md.

Planning waves: Group A (the t1k-corpus-scout spawn) first, skipped only as skipped (no-existing-code: <reason>) when every ledger row is NEW and no path resolves; B and C as one post-draft wave; B skipped only at <= 2 lanes and 0 NEW ledger rows; the plan states ## Planning waves, a Lane: per phase and Fan-out: (rules: references/planning-waves.md; copyable plan: references/plan-worked-example.md).

State the plan’s Hardness: phases=P new=K modules=M lanes=L header line (recorded to telemetry; the planner is pinned opus): references/plan-hardness.md.

Skill Inventory Injection (if installedModules present in metadata.json)

Section titled “Skill Inventory Injection (if installedModules present in metadata.json)”

Before spawning t1k-planner, inject the installed-skill inventory (names and modules, never full activation): references/skill-inventory-and-pipeline.md.

Game-Engine Architecture Gate (if a unity-* or cocos-* module is installed)

Section titled “Game-Engine Architecture Gate (if a unity-* or cocos-* module is installed)”

Any phase adding or refactoring game logic decides its logic/presentation split during planning, pointing t1k-planner at t1k-game-arch, including the Unity DOTS ISystem exception: references/game-engine-gate.md.

--team makes the planner emit ## Team Layout in plan.md, a ### Team Shape roster per phase-N.md and a tail ## Plan-Fit Assessment (--team). Two invariants bind: every phase-N.md is pointer-addressable, and every roster entry carries an explicit model: (default sonnet, #268). Full contract: references/team-shape-template.md § “Invariants and output contract”.

Parallel-Safe Decomposition (when fanning implementation out to multiple agents)

Section titled “Parallel-Safe Decomposition (when fanning implementation out to multiple agents)”

Default: coupled or sequential work is ONE sequential phase, regardless of file count. Fan out only when ≥2 units share no hidden decisions AND each has its own test command: serial contract phase, then lanes from the DAG ready set, then serial integration. No fixed lane ceiling. Run the co-change seam check first (references/seam-check.md, advisory). Any --team roster or multi-agent phase MUST emit the seven-point contract in references/parallel-safe-decomposition.md (SSOT; the cross-lane decision register and tier sizing are there too, § “Moved from SKILL.md”).

Lane size is information from sourced data, never a cap; a tier with no data is UNMEASURED: references/lane-sizing.md.

Lane labels, ## Contract, ## Decision register and ONE-command Accept: per phase (plans with 2+ lanes): references/lane-contract-and-accept.md. A phase that creates a CLI, hook, script, skill, agent or MCP tool also carries one AX: line (same file, ## AX line).

Multi-Agent Planning Pipeline (if 2+ modules matched)

Section titled “Multi-Agent Planning Pipeline (if 2+ modules matched)”

0-1 matched modules: one t1k-planner. 2+: domain design, parallel per-module planning, then integration; the merge-up tree step is flag-gated (t1k-planner.md § “Tree step”) and for large fan-out only: a plan under the thresholds, or with <= 2 lanes, stays FLAT. Detail and the optional Execution Trace: references/skill-inventory-and-pipeline.md.

Every plan phase must include a risk table and effort estimate: references/workflow-modes.md § “Risk Assessment (Mandatory Output)”.

Only when planning TheOneKit’s own infrastructure (core, release-action, CLI, kit registry/lifecycle): references/architecture-references.md.

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