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).
Scanned 5/29/2026
Install via CLI
Skills Directoryopenskills install ngocsangyem/MeowKit---
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`.
No comments yet. Be the first to comment!
