---
name: plan
description: "Breaks features/goals into phased plans with task lists, agent assignments, dependencies. Triggers: plan feature, implementation roadmap, break down task, project phases."
user-invocable: true
effort: high
argument-hint: "[goal]"
allowed-tools: Read, Grep, Glob
---

# Project Planning

$ARGUMENTS

## Workflow

1. **Analyze scope**: read the goal, scan relevant source files to understand current state
2. **Detect project type**: match keywords to determine stack and primary agents (see table below)
3. **Break into phases**: group tasks by dependency order (foundation, core, polish)
4. **Assign agents**: map each task to the best-fit agent with explicit dependencies
5. **Write plan file**: create `{project-slug}.md` in project root using [templates/plan-template.md](templates/plan-template.md)
6. **Validate**: confirm every requirement maps to at least one task, no circular dependencies exist, and success criteria are measurable

## Project Type Detection

| Keywords | Type | Primary Agents |
|----------|------|----------------|
| landing, website | Static Site | frontend-specialist |
| dashboard, admin | Web App | frontend + backend |
| api, rest, graphql | API Only | backend-specialist |
| mobile, ios, android | Mobile | mobile-developer |
| cli, terminal | CLI Tool | backend-specialist |

## Planning Constraints

- Create plan documents only, NO code writing, NO file creation (except the plan)
- Each task must name affected file(s) and a single owning agent
- Phases must have explicit dependency edges (`Phase 1 -> Phase 2`)
- Success criteria must be verifiable (command to run, expected output, or observable behavior)

## KB Integration

Before planning:

```python
smart_query("project template: {type}")
hybrid_search_kb("architecture {pattern}")
```

## Estimation & Templates

### T-shirt sizing (use for >1 day work)

| Size | Effort | Example |
|------|--------|---------|
| XS | <2h | typo, add field |
| S | 2-4h | simple component, basic API |
| M | 1-2 days | feature with tests |
| L | 3-5 days | complex feature |
| XL | 1-2 weeks | major subsystem |

Avoid hour-precise estimates beyond a week — they are false confidence (cone of uncertainty: 4× variance at idea, 1.5× at design).

### SMART tasks vs phase outcomes

Plan-level tasks should be **phase-aligned outcomes** ("authentication ships behind a feature flag"), not SMART implementation steps ("add JWT middleware"). The latter belongs in the issue tracker after `/prd-to-issues`.

### Pre-mortem (mandatory for >1 day plans)

List ≥5 named failure modes with mitigation. A 2-bullet pre-mortem is theater. Risk register cap: 10 entries ranked by (probability × impact); below line 10 is noise.

## Related Skills

- Plan approved? -> `/orchestrate` or `/workflow` to execute with agents
- Need requirements first? -> `/write-a-prd` for structured product requirements
- Want to stress-test the plan? -> `/grill-me` for Socratic questioning
- Ready to break into issues? -> `/prd-to-plan` -> `/triage-issue`

## Rules

- **MUST** break work into phases where each phase is independently shippable (tracer-bullet discipline) — waterfall phases defer all risk to the end
- **MUST** define measurable success criteria per phase before proposing tasks — "the user is happy" is not a criterion
- **NEVER** write code in this skill — the output is a plan document, not a patch
- **NEVER** invent an agent; every task lists a real agent from `app/agents/` or a real skill from `app/skills/` with a reason for the choice
- **CRITICAL**: every phase has an explicit rollback or scope-cut option. A plan with no way to stop mid-project is a sunk-cost trap.
- **MANDATORY**: dependencies between phases are explicit edges (`Phase 1 → Phase 2`). Circular dependencies are always a planning bug, not a valid state.

## Gotchas

- "SMART" tasks are often too small to be strategic and too vague to be tactical. Tasks at the plan level should be phase-aligned outcomes ("authentication ships behind a feature flag"), not implementation steps ("add JWT middleware").
- Agent assignment drifts during execution — the agent named in the plan may be unavailable or wrong when the work starts. Document the **role** (`backend-specialist`) alongside the assigned agent, so a substitute is unambiguous.
- Plans that start with a Research phase often consume 80% of the timeline without producing shippable output. If research is truly needed, cap it with a timebox and a concrete artifact (ADR, spike doc).
- Dependency graphs with diamond patterns (A→B, A→C, B→D, C→D) silently serialize D. If parallel phases feel slow, check for an unintended diamond.
- Success criteria based on code metrics (coverage, lint count) incentivize gaming them. Prefer user-facing criteria (p95 latency, first-time-success rate on the happy path).

## When NOT to Use

- For writing a **PRD** (product requirements) first — use `/write-a-prd`
- For breaking a PRD into phases — use `/prd-to-plan`
- For filing issues against a plan — use `/prd-to-issues`
- For stress-testing an existing plan — use `/grill-me`
- For executing a plan with agents — use `/orchestrate` or `/workflow`
- For a refactor with incremental commits — use `/refactor-plan`