mk:plan-creator

Plan Creator

Scope-aware planning with step-file workflow. Produces plan.md overview + phase-XX detail files.

When to Use

Activate when:

• User runs /mk:plan [task] or /mk:cook [task]
• Non-trivial task (> 2 files OR > 1h OR architectural decisions)
• Gate 1 requires a plan before Phase 3
• Green-field product build ("build a kanban app", "create a SaaS dashboard", "make a retro game maker") → step-00 auto-detects and offers --product-level
• User runs /mk:plan archive → route to references/archive-workflow.md (skip planning pipeline)
• User runs /mk:plan red-team {path} → route to references/red-team-standalone.md (skip planning pipeline)
• User runs /mk:plan validate {path} → route to references/validate-standalone.md (skip planning pipeline)

Skip when:

• /mk:fix with complexity=simple (Gate 1 exception)
• mk:scale-routing returns workflow=one-shot + zero blast radius

Arguments

| Flag | Mode | Research | Phase Files | Validation | | ----------------- | ------------------------ | ----------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | (default) | Auto-detect from scope | Follows mode | Follows mode | Follows mode | | --fast | Fast | Skip | plan.md only | Semantic checks only | | --hard | Hard | 2 researchers | plan.md + phases | Full interview | | --deep | Deep | 2-3 researchers | plan.md + phases + bounded phase map: file inventory, test gaps, interfaces, dependencies | Full interview | | --parallel | Parallel | 2 researchers | plan.md + phases + ownership matrix | Full interview | | --two | Two approaches | 2 researchers | 2 approach files + trade-off matrix | After selection | | --product-level | Product spec | 2 researchers (broader) | plan.md only (user stories + features + design language; NO phase files) | Semantic + check-product-spec.sh (no red-team, no validation interview — v1) | | --spike | Time-boxed investigation | Skip | spike plan from assets/spike-plan-template.md (investigate + findings phases; NO test/ship) | Semantic only |

--spike constraints (Agile context only — gated by agile-feedback-cycle.md 2 when loaded):

• Requires --timebox <duration> (e.g., --timebox 2d, --timebox 4h); reject with "spike requires --timebox" if absent
• Sets plan frontmatter spike: true, timebox:, and findings_doc: (default tasks/plans/{slug}/findings.md)
• INCOMPATIBLE with --product-level and mk:autobuild FULL density (autobuild gate breaks). Reject combination "spike incompatible with autobuild FULL — use --fast or mk:cook"
• Advisory cap: warn if story_points > 5 — likely two spikes, or spike + story

Composable flags:

• --tdd — add tests-first phase sections and preserve strict TDD in the cook handoff. See references/tdd-mode.md.

Requirements Capture Contract

Before producing a plan, plan-creator MUST be able to answer all 5 dimensions in concrete sentences (cook's exact-requirements contract — see .claude/skills/cook/SKILL.md "Exact-Requirements Contract (Phase 1)"):

1. Expected output — 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.

Every clarifying question MUST cite scout findings (file paths) in its options. Abstract options like "Add the feature" without a file path are a failure mode — replace with options of the form "Add to src/api/users.ts (matches existing pattern)" or "Create new src/api/profile.ts".

Skip when input is an existing plan path (plan.md / phase-*.md) — the plan already encodes scout output and the 5 dimensions.

Workflow

Before starting, read references/failure-catalog.md for common planning failure modes to avoid.

Execute via workflow.md. Step-file architecture — load one step at a time. Fast mode (--fast) uses workflow-fast.md (steps 00→03→04→07→08).

Agile DoR advisory (Phase 1 entry, conditional): if the parsed plan frontmatter contains a non-empty jira_tickets: list AND agile-story-gates.md is loaded (Agile context active per mk:agent-detector Step 0b), run 1 of agile-story-gates.md for each ticket BEFORE generating phase files. Render the advisory checklist; never block — let the user decide. Skip silently when jira_tickets: is absent or the rule is not loaded.

Step 0: Scope Challenge → trivial (exit) | simple (fast) | complex (hard/deep)
Step 1: Research (hard/deep/parallel/two only) → 2-3 researchers, max 5 calls each
Step 2: Codebase Analysis (hard/deep/parallel/two only) → scout + docs (deep: bounded scope map)
Step 3: Draft Plan → plan.md (≤80 lines) + phase-XX files (12-section template; deep: + phase map; tdd: + regression sections)
Step 4: Semantic Checks → goal/ACs/constraints + structural validation
Step 5: Red Team (hard/deep/parallel/two only) → 4-persona scaling, red-team-findings.md, adjudication
Step 6: Validation Interview (hard/deep/parallel/two only) → 3-5 critical questions with detection keywords, propagate answers
Step 7: Gate 1 → self-check + AskUserQuestion (Approve | Modify | Reject)
Step 8: Hydrate Tasks → phase checkboxes → session tasks
Step 9: Post-Plan Handoff → mode-pruned AskUserQuestion (cook|validate|red-team|end) → write `handoff.next` to plan.md → STOP

Output Structure

Fast mode: Single plan.md (goal, context, scope, approach, ACs) Hard mode: Directory with plan.md + phase files:

tasks/plans/YYMMDD-name/
├── plan.md              ← overview (≤80 lines)
├── research/            ← researcher reports (hard mode)
├── phase-01-name.md     ← 12-section detail (≤150 lines)
├── phase-02-name.md
└── ...

Gotchas

• Wrong workflow model: feature-model on a bug fix skips investigation → confirm type at Step 0
• Goal describes activity: "Implement OAuth" vs "Users can log in with OAuth" → rewrite as outcome
• ACs can't be verified: "code is clean" blocks Gate 2 → every AC must reference a command/file check
• Monolithic plan: plan.md over 80 lines → move detail to phase files or research reports
• Research disconnected: findings archived but not cited in plan → Step 3 MUST integrate research into Key Insights
• **Over-planni