Planning

BAD: "Set up the database" GOOD: "Create migration supabase/migrations/004_subscriptions.sql with RLS policies for the subscriptions table"

Quality degrades at 40-50% context (not 80%). Split phases into many small focused plans:

• 2-3 tasks per PLAN.md maximum
• Better 10 small high-quality plans than 3 large degraded ones
• Each plan independently executable and verifiable

Never design phases that require all phases to complete before anything works.

Types:

• checkpoint:human-verify — Human confirms automated work (visual check, UI test)
• checkpoint:decision — Human makes architectural choice
• checkpoint:human-action — Only for truly manual tasks (email verification links)

NEVER ask the human to do what a CLI can do.

Only rule 4 requires user input. Everything else flows automatically.

Required sub-items in the QA section:

1. Skills to invoke — list the relevant skills (e.g., testing, pr-review, security, verification-loop, debugging). Plans that touch test code should ALWAYS list testing. Plans that ship to production should ALWAYS list security and pr-review.
2. Subagent fan-out — for any plan with ≥3 independent modules, list the parallel subagent invocations (e.g., tester per module, reviewer on the diff, security audit, web-research on idioms). Default to spawning these in one message so they run concurrently.
3. Per-module unit tests — one line per new module/script: test file path + key behaviors covered. "Module exists" doesn't satisfy this; "what does it do?" → "test it."
4. Smoke run — the exact command that proves end-to-end wiring (e.g., make load-test ENV=local, pytest tests/ -q, docker compose --profile X up). If no such command exists, propose adding one.
5. Pre-commit gates — what runs locally before commit (pytest, flake8, the project's pr-review skill, etc.).
6. CI-coverage check — for every new test file: confirm it actually runs in CI. If the service Dockerfile --ignores it, the plan must add a compensating GHA step.

Before declaring the plan "complete" or marking phase-tasks done, the plan author re-reads the QA section and only marks complete what was actually executed. Subagents are part of the plan's execution surface, not an afterthought.

1. Always update .planning/ before/during related work. When a phase ships, when a decision lands, when scope changes — reflect it in the relevant PLAN.md / ROADMAP.md / SUMMARY.md before the conversation ends. The user (or future-you in a new session) expects to come back later and find an accurate picture.

2. Prune done phases — but only after verifying done. When a phase's deliverable has merged (or rolled into a later phase), it's fine to delete or archive that phase folder. NEVER delete based on assumption — verify via git log / PR status / on-disk artifacts. Don't prune just because something LOOKS old. If unsure, archive to .planning/archive/ instead of deleting.

.planning/ is usually gitignored. That's intentional — it's local-only context, not a deliverable. Code that needs to be tracked lives outside .planning/. Don't put committable code there.

git rev-parse --git-dir 2>/dev/null || echo "NO_GIT_REPO"
ls -la .planning/ 2>/dev/null
find . -name ".continue-here*.md" -type f 2>/dev/null
[ -f .planning/BRIEF.md ] && echo "BRIEF: exists"
[ -f .planning/ROADMAP.md ] && echo "ROADMAP: exists"

If no git repo: offer to initialize. Present findings before intake.

If handoff found:

Found handoff: [path]
[Summary from handoff]
1. Resume from handoff
2. Discard handoff, start fresh

If planning structure exists:

Project: [name]
Brief: [exists/missing] | Roadmap: [X phases] | Current: [phase status]

1. Plan next phase
2. Create handoff (stopping for now)
3. View/update roadmap
4. Create PRD / spec

If no planning structure:

No planning structure found.

1. Start new project (create brief + roadmap)
2. Plan a specific feature (no full roadmap needed)
3. Create implementation plan for current task
4. Get guidance on approach

Wait for response before proceeding.

After reading the workflow, follow it exactly.

BRIEF.md          → Human vision (you read this)
    ↓
ROADMAP.md        → Phase structure
    ↓
[RESEARCH.md]     → Research prompt (optional)
    ↓
PLAN.md           → THE PROMPT (agent executes this)
    ↓
SUMMARY.md        → Outcome (existence = phase complete)

Output structure:

.planning/
├── BRIEF.md
├── ROADMAP.md
├── MILESTONES.md           (after first release)
└── phases/
    ├── 01-foundation/
    │   ├── 01-01-PLAN.md
    │   ├── 01-01-SUMMARY.md
    │   └── 01-02-PLAN.md
    └── 02-auth/
        ├── 02-01-RESEARCH.md
        ├── 02-01-FINDINGS.md
        └── 02-02-PLAN.md

Naming: {phase}-{plan}-PLAN.md e.g. 01-03-PLAN.md