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 <duration>] [--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
---

# 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:harness` FULL density (harness gate breaks). Reject combination "spike incompatible with harness 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, harness, 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

| File                                               | Purpose                                                                                                                                                                                                              |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow.md`                                      | Step sequence, variable table, flow diagram (hard mode)                                                                                                                                                              |
| `workflow-fast.md`                                 | Compact step sequence for `--fast` mode (00→03→04→07→08)                                                                                                                                                             |
| `step-03a-product-spec.md`                         | Product-level spec drafter: user stories, features, design language. Replaces step-03 when `planning_mode = product-level`.                                                                                          |
| `assets/product-spec-template.md`                  | Product spec template (Vision, Features, Design Language, AI Integration, Out-of-Scope)                                                                                                                              |
| `assets/spike-plan-template.md`                    | Spike plan template (used when `planning_mode = spike`). Two phases: investigate + findings. Required frontmatter: `spike: true`, `timebox:`, `findings_doc:`. NOT compatible with `mk:harness` FULL.                |
| `references/anthropic-example-plan.md`             | RetroForge few-shot calibration example for product-level mode (ambition + feature density reference)                                                                                                                |
| `step-05-red-team.md`                              | Red team review: persona scaling, subagent dispatch, adjudication                                                                                                                                                    |
| `step-06-validation-interview.md`                  | Critical question generation and answer propagation                                                                                                                                                                  |
| `step-07-gate.md`                                  | Self-check and Gate 1 AskUserQuestion presentation                                                                                                                                                                   |
| `step-09-post-plan-handoff.md`                     | Deterministic post-Gate-1 handoff: mode-pruned `AskUserQuestion` (cook \| validate \| red-team \| harness \| end), live risk re-scan, writes `handoff.next` to plan.md frontmatter, prints command + STOPs.        |
| `references/whole-plan-sweep.md`                   | Whole-Plan Consistency Sweep algorithm (Gates W1 + W2). Stage-then-apply: read-only Pass 1 stages Pending Sweep Edits; decision check blocks on unresolved contradictions; write Pass 2 applies edits and logs.   |
| `references/deep-mode.md`                          | Deep mode contract: when to use/avoid, scout budgets, phase-map appendix, context rules.                                                                                                                             |
| `references/tdd-mode.md`                           | TDD flag contract: phase sections, optional frontmatter, cook handoff propagation, RED-task hydration.                                                                                                                |
| `references/verification-roles.md`                 | Verification Roles for step-04 sub-step 4d (Fact Checker / Flow Tracer / Scope Auditor / Contract Verifier) with tier selection by phase count. Subagents are READ-ONLY; orchestrator writes the `## Verification Log`. |
| `prompts/personas/plan-assumption-destroyer.md`    | Plan-specific assumption skeptic persona                                                                                                                                                                             |
| `prompts/personas/plan-scope-complexity-critic.md` | Plan-specific YAGNI/scope minimalist persona                                                                                                                                                                         |
| `prompts/personas/plan-security-adversary.md`      | Plan-specific security adversary (auth bypass, injection, data exposure). Used at 4+ phases.                                                                                                                         |
| `prompts/personas/plan-failure-mode-analyst.md`    | Plan-specific failure mode analyst (race conditions, cascading failures, recovery). Used at 6+ phases.                                                                                                               |
| `references/phase-template.md`                     | 12-section phase file template                                                                                                                                                                                       |
| `references/ops-metrics-design.md`                 | If task involves metrics/KPIs/dashboards, load for metric philosophy, templates, and domain fallbacks                                                                                                                |
| `references/cold-start-context-brief.md`           | When writing phase files, follow this template for self-contained, cold-start-safe phase files                                                                                                                       |
| `references/plan-mutation-protocol.md`             | When modifying an existing plan (split/insert/skip/reorder/abandon), follow this protocol                                                                                                                            |
| `references/worked-example-stripe-billing.md`      | For plan detail level reference, see this complete worked example (the 7-phase model)                                                                                                                                |
| `references/scope-challenge.md`                    | Scope modes (HOLD/EXPANSION/REDUCTION)                                                                                                                                                                               |
| `references/research-phase.md`                     | Researcher spawning protocol                                                                                                                                                                                         |
| `references/plan-organization.md`                  | Directory structure, naming, size rules                                                                                                                                                                              |
| `references/output-standards.md`                   | YAML frontmatter, required sections                                                                                                                                                                                  |
| `references/validation-questions.md`               | Critical question categories for interview                                                                                                                                                                           |
| `references/gate-1-approval.md`                    | AskUserQuestion gate + Context Reminder                                                                                                                                                                              |
| `references/task-management.md`                    | Hydration, cross-session resume, sync-back                                                                                                                                                                           |
| `references/solution-evaluation.md`                | Trade-off scoring criteria                                                                                                                                                                                           |
| `references/gotchas.md`                            | Full gotchas list                                                                                                                                                                                                    |
| `references/solution-design-checklist.md`          | Trade-off analysis checklist for Architecture/Risk/Security sections (5 dimensions)                                                                                                                                  |
| `references/archive-workflow.md`                   | Archive subcommand: scan completed plans, journal, archive/delete                                                                                                                                                    |
| `references/red-team-standalone.md`                | Red-team standalone subcommand: adversarial review on existing plan                                                                                                                                                  |
| `references/validate-standalone.md`                | Validate standalone subcommand: critical question interview on existing plan                                                                                                                                         |
| `references/adr-generation.md`                     | Architecture Decision Record generation                                                                                                                                                                              |
| `references/parallel-mode.md`                      | Ownership matrix template, parallel group rules                                                                                                                                                                      |
| `references/two-approach-mode.md`                  | Approach file template, trade-off matrix, selection flow                                                                                                                                                             |
| `scripts/validate-plan.py`                         | Plan completeness validator. **Depends on PyYAML** (installed via `.claude/scripts/bin/setup-workflow` into `.claude/skills/.venv/`). Run via `.claude/skills/.venv/bin/python3 scripts/validate-plan.py <plan.md>`. |
| `scripts/check-product-spec.sh`                    | Product-spec structural validator (POSIX bash). Enforces feature count, user stories, forbidden patterns. Used by step-03a and step-04 for `--product-level` mode.                                                   |
| `references/workflow-models/feature-model.md`      | Workflow template for feature tasks (loaded JIT by step-00)                                                                                                                                                          |
| `references/workflow-models/bugfix-model.md`       | Workflow template for bug fix tasks (loaded JIT by step-00)                                                                                                                                                          |
| `references/workflow-models/refactor-model.md`     | Workflow template for refactor tasks (loaded JIT by step-00)                                                                                                                                                         |
| `references/workflow-models/security-model.md`     | Workflow template for security tasks (loaded JIT by step-00)                                                                                                                                                         |

## 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`.