plan

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