plan

name	plan
description	Planning & Execution - create structured implementation plans, check progress, execute in batches, manage lifecycle. Use when the user says 'plan this', asks to break down a feature into steps, or needs a phased implementation strategy before coding.
argument-hint	[feature-name]
version	1.0.0
status	active
packages	["all"]
dependencies	[]
last_updated	2026-03-12
last_verified	2026-03-12

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>/.

.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.

---
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:

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

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

# Plan Header
**GitHub Issue**: #123
**Closes**: #123

Update Progress

gh issue comment [NUMBER] --body "## Progress: Steps 1-3 complete"

On Completion

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:

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

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