Plan

Plan — Unified Planning Command

Delegation — REQUIRED

This skill MUST run via the epost-planner agent, not inline.

When /plan or planning intent is detected:

1. Use the Agent tool to spawn epost-planner
2. Pass the full user request + active context (branch, plan dir, CWD)
3. Do NOT execute planning steps inline in the main conversation

Create implementation plans with automatic complexity detection.

Step 0 — Flag Override

If $ARGUMENTS starts with --fast: skip auto-detection, load references/fast-mode.md and execute. Remaining args are the task description. If $ARGUMENTS starts with --deep: skip auto-detection, load references/deep-mode.md and execute. If $ARGUMENTS starts with --parallel: skip auto-detection, load references/parallel-mode.md and execute. If $ARGUMENTS starts with --validate: skip auto-detection, load references/validate-mode.md and execute. Otherwise: continue to Complexity Auto-Detection.

Aspect Files

Plan Output Contract

Every plan is a directory with a plan.md overview and one phase file per phase:

plans/{YYMMDD-HHMM-slug}/
  plan.md                    — overview, phases table with file links, success criteria
  phase-{N}-{slug}.md        — tasks, files to change, validation per phase

plan.md frontmatter (required fields):

---
title: "Short description"
status: draft | active | completed | archived
created: YYYY-MM-DD
updated: YYYY-MM-DD
effort: Xh
phases: N
platforms: [all | ios | android | web | backend]
breaking: true | false
---

phase file frontmatter (required fields):

---
phase: N
title: "Phase title"
effort: Xh
depends: []   # phase numbers this phase depends on
---

Phases table in plan.md must link to phase files:

| # | Phase | Effort | Status | File |
|---|-------|--------|--------|------|
| 1 | Name | 2h | pending | [phase-1](./phase-1-slug.md) |

Plan Lifecycle

draft → active → completed → archived

MANDATORY final step — after writing all plan files, run:

node .claude/scripts/set-active-plan.cjs plans/{slug}

This stamps status: active in plan.md and registers the plan in session state so /cook picks it up automatically. Do NOT skip this step.

Complexity Auto-Detection

1. Simple (1 module, clear scope, < 5 files) → load references/fast-mode.md
2. Moderate (multiple files, some research needed) → load references/deep-mode.md
3. Complex (multi-module, cross-platform, needs dependency mapping) → load references/parallel-mode.md

Platform Detection

Detect platform per skill-discovery protocol. Pass detected platform as context to the selected variant.

Heuristics

• Single sentence request → :fast
• Request mentions "research" or "investigate" → :deep
• Request mentions multiple platforms or modules → :parallel
• Request mentions "dependencies" or "phases" → :parallel
• If unsure → default to :fast, escalate if needed

Planning Expertise

Planning Framework

1. Understand — Clarify requirements
2. Decompose — Break into smaller tasks
3. Sequence — Order by dependency
4. Estimate — Time/complexity per task
5. Identify — Potential blockers
6. Document — Create structured plan

State Machine Modeling

When feature involves stateful behavior (UI flows, protocols, async state, workflows), generate ASCII state diagram BEFORE coding:

1. List all states (including error, timeout, edge states)
2. Map every transition (trigger + guard conditions)
3. Identify terminal states and dead ends
4. Mark states where data is mutated

[INITIAL] ──(event)──▸ [STATE_A]
    │                      │
    │                  (condition)
    │                      ▼
    │               [STATE_B] ──(error)──▸ [ERROR]
    │                      │
    │                  (success)
    │                      ▼
    └──────────────▸ ◉ [DONE]

Use when: auth flows, checkout/payment, form wizards, real-time sync, connection management, retry logic. Skip for: simple CRUD, stateless utilities, pure transforms. See references/state-machine-guide.md for notation, patterns, and validation checklist.

Mental Models

Best Practices

• Be specific about files to create/modify
• Include database migrations if needed
• Note breaking changes
• Consider testing strategy
• Estimate conservatively, track actuals
• Mark file ownership for parallel execution safety (parallel mode)
• Use knowledge-retrieval before planning, knowledge-capture after

Mode Reference

$ARGUMENTS {{detected_platform or "none"}}

IMPORTANT: Analyze the skills catalog and activate needed skills.