mk:plan-creator

What This Skill Does

The planning engine. Creates a complete implementation plan before any code is written. Uses a step-file architecture (one step loaded at a time to save context): scope challenge → (conditional Plan Intake Packet) → research → codebase analysis → draft → semantic checks → red-team → validation interview → Gate 1 → hydrate.

When to Use

• Gate 1 requirement: any non-trivial task (>2 files or >30 min) REQUIRES an approved plan before code
• Explicit invocation: /mk:plan or called by mk:cook / mk:workflow-orchestrator
• NOT for: trivial single-file changes, quick fixes with --quick flag, tasks that have an existing approved plan

Core Capabilities

• Scope detection: auto-detects product-level intent via regex patterns (feature requests, greenfield builds, spec documents) and presents scope mode (EXPANSION / HOLD / REDUCTION)
• Complexity routing: 5 signals determine scope depth — file count, domain keywords, cross-cutting concerns, security surface, data model changes
• Plan Intake Packet (conditional): when ≥2 pre-existing upstream artifacts are supplied, consolidates them into one traceable brief before drafting; 0–1 sources → clean skip, no behavior change
• Step-file loading: 10 sequential step files loaded one at a time, each producing checkpointed output
• Research spawning: up to 2 researcher agents with max 5 calls and ≤150 lines of context each
• Codebase analysis: scout + project docs + existing plan scan for cross-plan dependency detection
• Bounded deep mode: adds a compact scope map and per-phase Deep Phase Map (file inventory, test gaps, interfaces, dependencies) without repo-wide scans
• Two-approach mode: for COMPLEX tasks, produces two alternative approaches with trade-off analysis
• Semantic checks: validates plan against 6 dimensions (goal clarity, AC completeness, constraint realism, risk coverage, line count, product-level specifics)
• Red-teaming: 4 adversarial personas selected by phase count, subagent-dispatched with anti-sycophancy IGNORE instruction
• Validation interview: 5 question categories with detection keywords, 2-4 options each, recommended option marked
• Bead decomposition: for tasks with 5+ files, breaks into atomic work units with dependency chains (beads → strands → ropes)
• Vertical-slice default: decomposes feature-shaped tasks into end-to-end working slices (one runnable path per phase) instead of horizontal layers, with horizontal phases reserved for foundation layers and break-down triggers for oversized phases
• Conditional autonomy boundaries: emits an advisory three-tier (Always / Ask-first / Never) autonomy block in plan.md for long-horizon plans only, tunable at Gate 1 and read mode-aware by mk:cook
• Hydration: creates TaskCreate entries with dependency chains, parallelism groups, .plan-state.json checkpoint

Requirements Capture Contract

Before producing a plan, plan-creator MUST 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). Abstract options ("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.

Plan Intake Packet (conditional)

When two or more upstream artifacts already exist — mk:office-hours design docs, mk:brainstorming reports, mk:planning-engine assessments, mk:confluence-spec-analyst specs, mk:intake triage output, mk:jira-analyst findings, or spec documents you supply directly — a conditional step (0.5) consolidates them into ONE Plan Intake Packet before drafting, so the plan reads one traceable brief instead of N scattered reports.

• Activation: ≥2 external artifact paths in the invocation → build the packet. 0–1 sources → skip entirely, no planning behavior change (only an activation-log line is written).
• Adapter, not generator: only for artifacts that exist before plan-creator runs. Its own step-01 research and step-02 scout output are consumed directly by the draft step, never routed through the packet. One lone ticket is single-ticket triage — that is mk:intake, not a packet.
• Six blocks, under 120 lines: Request · Routing · Requirements · Evidence · Scope Shape · Handoff. Every load-bearing claim carries from: <path> or an [ASSUMPTION] tag; user-confirmed upstream decisions are LOCKED (red-team may challenge but must escalate, never silently cut).
• Output: drafted to .claude/session-state/plan-creator-intake-packet.md, then moved to {plan_dir}/research/plan-intake-packet.md and cited like any research report. Its path flows to steps 01–03 via the intake_packet_path variable (none when fewer than 2 artifacts).
• NOT for: single ticket/PRD triage (→ mk:intake), ticket complexity + dependency scoring (→ mk:planning-engine), or choosing an approach (→ mk:brainstorming). Route those; the packet only consolidates what those skills or you already produced.

Arguments

Spike mode (Agile context)

Governed by .claude/rules-conditional/agile-feedback-cycle.md Section 2 (loaded only when Agile context active).

• Requires --timebox <duration> (e.g., --timebox 2d, --timebox 4h); rejected without it
• Sets plan frontmatter spike: true, timebox:, findings_doc: (default tasks/plans/{slug}/findings.md)
• Two phases only: investigate + document findings — NO test phase, NO ship phase
• Story-points cap (advisory): warn if story_points > 5
• INCOMPATIBLE with mk:autobuild FULL density (autobuild gate breaks); use mk:cook or mk:plan-creator --fast
• At spike completion: prompt to convert findings to delivery story / close as research-only / defer

DoR advisory at Phase 1 entry (Agile context)

If the plan frontmatter has non-empty jira_tickets:, mk:plan-creator runs the DoR advisory checklist (5 mechanical checks per ticket) BEFORE generating phase files. Advisory only — never blocks. Skip silently when jira_tickets: absent or rule not loaded. Governed by agile-story-gates.md Section 1.

Workflow (step files)

Branching: product-level mode uses step-03a instead of step-03. Fast mode and product-level mode skip steps 05-06 and the 4d Verification Roles sub-step.

Gates W1 / W2 stage edits before applying (read-only Pass 1 stages ### Pending Sweep Edits; decision check blocks on unresolved contradictions via AskUserQuestion; Pass 2 applies and logs). Algorithm: references/whole-plan-sweep.md. Verification Roles algorithm + dispatch brief: references/verification-roles.md.

Usage

/mk:plan "add two-factor authentication to login"
/mk:plan --product-level "build a kanban board app"
/mk:plan --bugfix "fix race condition in payment processing"
/mk:plan --deep --two-approach "migrate from REST to GraphQL"
/mk:plan --tdd "implement rate limiting middleware"
/mk:plan --deep --tdd "refactor search indexing without changing ranking"

Example Prompt

Plan the implementation of real-time collaborative editing for our document editor. Support up to 50 concurrent editors, operational transform for conflict resolution, and WebSocket-based sync. Must work with existing React frontend and Node.js backend.

Common Use Cases

• Feature implementation planning (most common)
• Greenfield product builds (product-level mode)
• Bug fix planning for complex issues (multi-file, race conditions)
• Architecture migration planning (two-approach mode useful)
• Security-focused planning with TDD enforcement
• Multi-agent parallel build planning (bead decomposition + ownership matrix)

Pro Tips

• Product-level mode auto-detects. The regex patterns catch phrases like "build a", "create an app", "from scratch" — you rarely need the --product-level flag explicitly.
• Step-05 and 06 are skipped in fast mode. If you need adversarial review, don't use fast mode.
• Plan state persists. .plan-state.json enables resumption if context is lost mid-planning.
• CEO review after Gate 1. Consider running mk:plan-ceo-review on the approved plan for an additional quality layer.
• Deep maps known scope; it does not choose architecture. If the approach is undecided, run mk:brainstorming before planning.
• TDD survives handoff. Plans generated with --tdd print /mk:cook ... --tdd; cook warns if a TDD plan is run without the flag.
• Variables flow between steps. 10 variables (planning_mode, task_complexity, workflow_model, scope_mode, research_reports, codebase_findings, plan_dir, red_team_findings, selected_approach, tdd_mode) pass between step files.

Canonical source: .claude/skills/plan-creator/SKILL.md