mk-plan-creator

name: mk:plan-creator version: 1.6.2 preamble-tier: 3 description: 'Creates structured multi-file implementation plans before build. Scope-aware: trivial tasks exit early, simple tasks get fast plans, complex tasks get full research + phase files + validation. Enforces Gate 1. Activated by /mk:plan or /mk:cook. NOT for ticket complexity analysis against an existing codebase (see mk:planning-engine); NOT for CEO-level scope review of existing plans (see mk:plan-ceo-review).' argument-hint: '[task description] [--fast | --hard | --deep | --parallel | --two | --product-level [--no-design] [--no-scout] | --spike --timebox ] [--tdd] OR [archive | red-team {path} | validate {path}]' allowed-tools:

• Bash
• Read
• Edit
• Write
• Grep
• Glob
• Agent
• AskUserQuestion source: local keywords:
• plan-creator
• implementation-plan
• phase-files
• gate-1
• scope-adaptive when_to_use: Use when creating a structured multi-file implementation plan before build. NOT for ticket analysis (see mk:planning-engine) or scope review (see mk:plan-ceo-review). user-invocable: true meowkit: portability: provider-only providers: include:
  • claude-code requires: surfaces:
  • skills commands:
  • Agent
  • AskUserQuestion
  • Bash context_cost: high owner: lifecycle criticality: critical status: active runtime: claude-code context_cost: high

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

--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-planning trivial tasks: 2-file config change gets full research → Step 0 scope gate exits early
• Skipping scout on unfamiliar codebases: → always run mk:scout if codebase is new
• Using --deep to decide architecture: deep maps a chosen approach; if the approach is unclear, route to mk:brainstorming first.
• Dropping TDD at handoff: when tdd_mode=true, step-09 MUST print cook with --tdd; sentinel/env state alone is not a cross-session contract.
• Post-Plan Handoff is deterministic: step-09 fires AskUserQuestion; do NOT auto-invoke the chosen command. User must type it in a fresh session for clean context.
• handoff.next enum is validated: values outside {cook, validate, red-team, autobuild, end} fail validate-plan.py.
• Whole-Plan Consistency Gates W1 / W2 fire after red-team and validation interview: stage-then-apply algorithm — no edits land until the user resolves any unresolved contradictions. See references/whole-plan-sweep.md.
• consistency_sweeps frontmatter is optional: legacy plans without it still validate as PLAN_COMPLETE.
• Sweep recursion is bounded: "resolve now" caps at 2 attempts per gate; further unresolved items convert to Risk rows.
• .plan-state.json v1.2 schema is additive: consumers MUST treat unknown keys (verification_tier, consistency_sweeps_passed) as optional and default-empty. v1.1 readers ignore them silently.
• Post-hydration integrity-check failure is a hard stop: cycle / count-mismatch / missing-metadata failures print an explicit diff and STOP — do NOT auto-recover or silently continue. Human resolution required before step-09. See references/task-management.md "Post-Hydration Integrity Checks".

References

Known Exceptions

• references/anthropic-example-plan.md — filename retained as the source-provenance attribution for the few-shot calibration example. The file content is the appendix of a published harness-design article (Prithvi Rajasekaran, Labs); renaming would obscure the research origin. Future brand-prose audits skip this filename per this documented exception.

Related Rules

• .claude/rules/gate-rules.md — Gate 1 hard-stop conditions this skill enforces (plan approval before Phase 3)
• .claude/rules/orchestration-rules.md — boundary contract; verification subagents stay READ-ONLY; sweep stays in planner context (never delegated)

Start

Read and follow workflow.md.