plan

# Plan Skill Planning lifecycle for Coop: create plans, check progress, execute in batches. **References**: See `CLAUDE.md` for entry points, agent routing, and Coop conventions. --- ## Activation | Trigger | Action | |---------|--------| | `/plan` | Create new implementation plan | | `/plan --mode check` | Audit progress against plan | | `/plan --mode execute` | Execute plan in batches | | `/plan --mode cleanup` | Audit `.plans/` — archive implemented, flag stale | | `/plan --mode teams*` | Team-lane orchestration modes | | `/teams*` | Legacy alias routed to `/plan --mode teams*` | | Starting new feature | Create plan before coding | ## Progress Tracking (REQUIRED) Use **TodoWrite** for visibility when available. If unavailable, keep a Markdown checklist in the response. See `CLAUDE.md` -> Session Continuity. --- ## Part 1: Create Plan ### Phase 1: Understanding & Validation 1. **Extract ALL requirements** from issue/task 2. **Map each requirement** to planned steps 3. **Audit codebase** — search for existing patterns 4. **Review CLAUDE.md** for compliance rules ### Phase 2: Plan Structure For new feature work, use a feature pack under `.plans/features/<feature-slug>/`. ```text .plans/features/<feature-slug>/ spec.md context.md lanes/ ui.claude.todo.md state.codex.todo.md api.codex.todo.md contracts.codex.todo.md docs.claude.todo.md docs.codex.todo.md qa/ qa-codex.todo.md qa-claude.todo.md eval/ implementation-notes.md qa-report.md ``` Use: - `spec.md` for the canonical feature brief - `context.md` for relevant docs/codepaths/constraints - `lanes/*.todo.md` for agent-owned implementation work - `lanes/docs.*.todo.md` for recurring doc-drift maintenance when needed - `qa/*.todo.md` for sequential QA passes - `eval/*.md` for implementation notes and final QA results Legacy flat `.plans/*.todo.md` files are tolerated for old work, but new features should not use the flat layout. Each lane file should include frontmatter so automations can filter by agent, lane, status, handoff branch, and stale-lane evidence metadata. ```markdown --- feature: receiver-shell-polish title: Receiver shell polish state lane lane: state agent: codex status: ready source_branch: feature/receiver-shell-polish work_branch: codex/state/receiver-shell-polish depends_on: - ../spec.md owned_paths: - packages/shared/src/modules/receiver done_when: - reconcileReceiverCapture( skills: - state-logic - shared updated: 2026-03-26 --- ``` For implementation lanes (`state`, `api`, `contracts`): - `owned_paths` should point to the lane's primary code surface. - `done_when` should use concrete, searchable symbols or file names that will exist under `owned_paths` when the lane is actually complete. - Automations should run `bun run plans reconcile --agent codex --json` before implementing a queued Codex lane so stale `ready` work can be reconciled safely. Sequential QA uses handoff branches: - `handoff/qa-codex/<feature-slug>` starts QA pass 1 - `handoff/qa-claude/<feature-slug>` starts QA pass 2 Scaffold a new feature pack with: ```bash bun run plans scaffold <feature-slug> --title "<Feature Title>" ``` ### Task Decomposition Rules Implementation steps must be granular enough for agents to execute reliably. Follow these heuristics: **Step sizing**: - Each step should be completable in a single agent session (~15-25 tool calls) - Each step should touch at most 3-4 files - If a step has more than 3 sub-bullets of changes, it's probably two steps - If you can't describe verification for a step in one sentence, it's too big **Independence**: - Each step should be independently verifiable (can run tests after just that step) - Each step should produce a committable checkpoint (no half-finished states) - Steps should have clear input/output boundaries — what exists before, what exists after - Each step should stay within one ownership surface or the lane's `owned_paths` when those exist **Ordering**: - Follow dependency order: shared -> app -> extension - Within a package: types/interfaces first, then implementation, then tests, then wiring - Infrastructure steps (new files, new exports) before behavior steps (logic, handlers) **When to decompose further**: - A step requires changes across 3+ packages -> split into per-package steps - A step has both "create new thing" and "integrate into existing thing" -> split those apart - A plan exceeds 15 steps -> consider splitting into multiple PRs or incremental plans - A step predictably crosses multiple owned surfaces without clear need -> split or route to migration **When NOT to decompose**: - A step is a single-file edit with clear intent -> keep it atomic - Splitting would create steps that can't be independently tested -> keep them together - The decomposition adds overhead without improving clarity **Judgment-heavy steps**: - Steps involving dependencies, migrations or persisted state, auth/session/permit/policy, public contracts, or runtime/toolchain boundaries should explicitly call out expected human judgment in handoff notes and later review. --- ## Part 2: Check Progress 1. **Load plan** from `.plans/` 2. **Gather git context**: `git status`, `git diff --stat` 3. **File-by-file status**: DONE / PARTIAL / NOT DONE 4. **Requirements coverage table** 5. **Run validation**: `bun format && bun lint && bun run test && bun run build` --- ## Part 3: Execute Plan ### Batch Execution **Default batch size**: 3 tasks ``` LOAD -> EXECUTE BATCH -> REPORT -> PAUSE -> CONTINUE/FINISH ``` ### Batch Report ```markdown ## Batch [N] Complete ### Tasks Completed 1. Step 1: [Description] - Files: `path/to/file.ts` ### Next Batch Preview - Steps 4, 5, 6 **Awaiting feedback before continuing...** ``` ### Safety Rules - **Stop when blocked** — Don't guess - **No forcing through** — Never skip failing tests - **Pause between batches** — Wait for feedback --- ## Part 4: GitHub Integration ### Link Issue to Plan ```markdown # Plan Header **GitHub Issue**: #123 **Closes**: #123 ``` ### Update Progress ```bash gh issue comment [NUMBER] --body "## Progress: Steps 1-3 complete" ``` ### On Completion ```bash gh issue close [NUMBER] --comment "All steps complete, PR ready" ``` --- ## Part 5: Plan Lifecycle Management Plans are living documents, not write-once artifacts. Unmanaged plans accumulate and create confusion about what's current. ### Status Transitions ``` ACTIVE -> IMPLEMENTED (code shipped, plan is historical) ACTIVE -> SUPERSEDED (new plan replaces this one) ACTIVE -> BLOCKED (waiting on external dependency) BLOCKED -> ACTIVE (dependency resolved) ``` ### Lifecycle Rules 1. **Supersedes header**: When a new plan replaces an old one, the new plan MUST include `**Supersedes**: [old-plan-name.md]` in its header. Delete the old plan immediately. 2. **One canonical plan per feature**: Never have 2+ active plans for the same feature area. If you're writing a v2 plan, delete or archive v1 first. 3. **Status updates on implementation**: When work ships that partially or fully implements a plan, update the plan's `**Status**` and `**Last Updated**` headers. If fully implemented, delete the plan. 4. **Divergence notes**: If implementation diverges from the plan (different approach, dropped scope), add a `## Implementation Notes` section explaining what changed and why. Don't leave the plan as-if it was followed when it wasn't. 5. **Stale plan cleanup** (`/plan cleanup`): Periodically audit `.plans/` — any plan untouched for 14+ days should be reviewed. Either update its status, confirm it's still active, or delete it. 6. **No meeting notes in `.plans/`**: Raw transcripts and meeting notes go in `notes/` or issue comments, not `.plans/`. Plans must be actionable specs. 7. **No audit reports in `.plans/`**: Point-in-time audit findings go in issue comments or a separate `audits/` directory if needed for record-keeping, not mixed with implementation plans. ### Scope Discipline Plans with >15 locked decisions likely need splitting. Separate **vision/architecture** documents (what and why) from **implementation plans** (how, in what order, with what tests). | Document Type | Decision Count | Location | |---------------|---------------|----------| | Architecture spec | Unlimited | `docs/reference/` or issue | | Feature brief | 5-15 decisions | `.plans/features/<feature-slug>/spec.md` | | Lane checklist | 0 decisions | `.plans/features/<feature-slug>/lanes/*.todo.md` | ### Decision Log Best Practice The numbered decision table with rationale is the most effective planning pattern in this repo. Every plan SHOULD include one: ```markdown ## Decision Log | # | Decision | Rationale | |---|----------|-----------| | 1 | Direct Dexie persistence | Local-first principle; no server roundtrip | | 2 | Yjs CRDT for sync | Conflict-free multi-peer collaboration | ``` This gives Claude and future contributors unambiguous constraints without reading 200 lines of prose. --- ## Part 6: When NOT to Plan ### Skip Planning For | Scenario | Do Instead | |----------|------------| | Single-file bug fix with clear root cause | `/debug` -> fix -> test | | Typo or copy changes | Direct edit | | Config change (env var, build flag) | Direct edit -> verify build | | Adding a test for existing behavior | `testing` skill directly | | Formatting or lint fix | `bun format && bun lint` | ### Signs a Plan is Needed | Signal | Why | |--------|-----| | Touches 3+ packages | Cross-package coordination needed | | Changes shared modules | Downstream app/extension implications | | Changes data model | Dexie schema migration + sync implications | | New user-facing feature | UX decisions + offline behavior | | Breaking change | Blast radius analysis + migration path | ### Planning Traps to Avoid - **Over-planning polish work** — Small UI tweaks don't need 10-step plans - **Planning without reading code first** — Always audit existing patterns before writing a plan - **Planning what you don't understand** — Use `/debug` to investigate first - **Stale plans** — If a plan sits untouched for 14+ days, reassess before executing - **Vision creep** — Keep architecture exploration separate from implementation plans; a plan with 60 decisions is a spec, not a plan --- ## Anti-Patterns - **Planning without requirements** — Every plan step must trace to a requirement; if you can't articulate the requirement, you're not ready to plan - **Plans with vague steps** — "Update the component" is not a plan step; "Add publish handler to `ReviewPanel` that calls `publishToFeed()`" is - **Skipping impact analysis** — A plan without "Files to Modify" will surprise you during execution - **Infinite planning** — If the plan exceeds 15 steps, split into multiple plans or incremental PRs - **Planning alone when blocked** — If you need information to plan, ask the user directly instead of guessing - **Ignoring CLAUDE.md compliance** — Plans that skip the compliance checklist produce non-conforming code - **Plan proliferation** — Never have 2+ active plans for the same feature. When a new plan supersedes an old one, delete the old one immediately - **Missing test strategy** — Every feature plan needs a "Test Strategy" section - **Write-only plans** — Plans that are never updated after creation become misleading. Update status or add divergence notes as work progresses - **Mixed content in `.plans/`** — Meeting notes, audit snapshots, and team prompts are not plans. Keep `.plans/` for actionable specs, lane plans, QA, and evaluation files only ## Validation Commands ```bash bun format && bun lint && bun run test && bun run build ``` ## Key Principles - **100% requirement coverage** — Every requirement mapped - **Evidence before claims** — Verify before marking done - **Batch execution** — Pause for feedback - **Right-size the plan** — Match planning depth to task complexity ## Related Skills - `architecture` — Architectural patterns considered during planning - `testing` — TDD strategy included in implementation plans - `debug` — Investigate root cause before planning a fix