Mk Plan Creator

Plan Creator

Public surface: classify → inspect → capture missing decisions → draft → validate → Gate 1. Produces plan.md overview + phase-XX detail files; execution, existing-plan audits, visual rendering, archive, and durable-memory capture stay with their existing owners.

When to Use

Activate when:

• User runs the plan skill [task] or the cook skill [task]
• Non-trivial task (> 2 files OR > 1h OR architectural decisions)
• User supplies ≥2 upstream reports/specs (office-hours, brainstorming, planning-engine, confluence-spec, intake output…) → step-00.5 consolidates them into a Plan Intake Packet before planning (see references/plan-intake-packet.md)
• User supplies a design evidence packet (e.g. from mk:figma) → plan consumes it (viewport/state ACs, critical-action validation matrix, phase blocked_on: for high-risk flow ambiguity), never re-analyzes the design source (see references/design-evidence-consumption.md)
• 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
• Existing-plan audit → mk:validate-plan; archive → lifecycle CLI; visual rendering → mk:visual-plan.
• Hard/deep plan creation still runs its built-in red-team and validation interview before Gate 1. These are design-quality gates, not standalone subcommands, and must never be routed away.
• Compatibility aliases: the plan skill archive → archive workflow; the plan skill red-team {path} → standalone red-team workflow; the plan skill validate {path} → standalone validation workflow.

Standalone aliases route to their compatibility references; they do not replace hard/deep red-team or validation. --html routes to mk:visual-plan.

Skip when:

• the fix skill 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.
• Visual work belongs to mk:visual-plan. Plan-creator emits only the handoff metadata needed for that skill; Markdown plan files remain source of truth.

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 .cursor/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 0.5: Intake Packet (conditional: ≥2 external artifacts) → consolidate upstream artifacts, else clean skip
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 + stop and ask the user in chat (Approve | Modify | Reject)
Step 8: Hydrate Tasks → phase checkboxes → session tasks
Step 9: Post-Plan Handoff → mode-pruned stop and ask the user in chat (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 stop and ask the user in chat; 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".
• Re-analyzing a design source that already has a packet duplicates interpretation: when a design evidence packet path is present, cite the packet — do NOT call the design source's tools or re-parse its raw JSON. See references/design-evidence-consumption.md.

--advice (composable, off by default)

Opt-in strategic supervision for one planning run, capped at 4 calls: GUIDE after the scope challenge, RESCUE on an unresolved red-team contradiction, REVIEW before the gate step, RECHECK after a correction.

Athena reads the plan and can return it to the planner. It never writes the plan and never approves Gate 1.

Without the flag there are zero calls and no state is written.

Checkpoints: references/advice-checkpoints.md. Contract: .cursor/rules/domain-advice-supervision.mdc (load only when the flag is present).

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

• AGENTS.md (Gates) — Gate 1 hard-stop conditions this skill enforces (plan approval before Phase 3)
• AGENTS.md (Delegation & subagents) — boundary contract; verification sub-task stay READ-ONLY; sweep stays in planner context (never delegated)

Start

Read and follow workflow.md.