Planning — Brainstorm + Execution-Ready Plans

TL;DR

• Use before any feature, behavior change, or task needing 3+ actions.
• Brainstorm intent, 2–3 approaches, recommendation, scope, and interfaces.
• Write openspec/changes/<name>/{design.md,tasks.md}.
• Emit .cm/handoff/plan.json with complete task_specs; first_tasks-only handoffs remain readable for backward compatibility.
• Next: cm-tdd or cm-execution.

Phase A: Decide What to Build

1. Ask only questions that change scope or architecture. State assumptions and mark each verified or needs confirmation.
2. Present 2–3 approaches with concrete tradeoffs and recommend one.
3. Separate must-have, optional, handled edges, and explicit non-goals.
4. Map data flow, file responsibilities, public interfaces, and dependencies. UI work also uses cm-design-system.

Stop if intent, ownership, or an interface is ambiguous. Do not silently choose an interpretation.

Phase B: Write the Plan

Create design.md with context, chosen architecture, file map, interfaces, risks, and verification strategy. Create tasks.md using the template below.

Task boundary

A task is the smallest independently testable deliverable that a reviewer can approve or reject without deciding another task. Each task owns a complete red–green cycle and ends at a commit boundary. Fold setup, configuration, migrations, and documentation into the deliverable that needs them; never create empty setup-only or docs-only tasks.

Each step is exactly one 2–5 minute action: write one failing test, run it and observe the expected failure, add minimal implementation, run it and observe the pass, then commit. Never use 15–30 minute checklist items.

Required task template

### Task 1: Validate rich plan handoffs

**Goal:** Reject incomplete task specs while preserving legacy `plan@1` payloads.
**Deliverable:** A validator and focused tests that can pass review independently.
**Files:**
- Modify: `src/handoff/io.ts`
- Test: `test/handoff.test.ts`
**Dependencies:** Existing `validateHandoff(obj: unknown)` behavior.
**Interfaces:** Produces optional `PlanHandoff.data.task_specs`; consumes `PlanTaskSpec`.
**Acceptance criteria:** A complete rich handoff round-trips; a missing `deliverable` is rejected; a legacy handoff remains valid.

- [ ] **Step 1 — Write the failing validation test** in `test/handoff.test.ts` with `expect(() => validateHandoff(fixture)).toThrow(/missing key: deliverable/)`.
- [ ] **Step 2 — Prove RED.** Run `npx vitest run test/handoff.test.ts`. Expected: FAIL at `rejects incomplete rich plan task specs` because no error is thrown.
- [ ] **Step 3 — Implement the minimum validation** in `src/handoff/io.ts` for required rich-task fields without changing legacy required keys.
- [ ] **Step 4 — Prove GREEN.** Run `npx vitest run test/handoff.test.ts`. Expected: PASS, all handoff tests and zero failures.
- [ ] **Step 5 — Commit boundary.** Run `git add src/handoff/io.ts test/handoff.test.ts && git commit -m "feat: validate rich plan handoffs"`.

Every task must specify: goal, independently reviewable deliverable, exact create/modify/test paths, dependencies, consumed/produced interfaces with exact names and types, literal acceptance criteria, step-level test phase, exact command and expected result, and commit boundary. Repeat context needed by a fresh agent; never require it to reread the full plan.

No Placeholders

Never write TODO, TBD, “add tests,” “handle edge cases,” “appropriate error handling,” “similar to Task N,” or an undefined type/function. Code steps include the concrete code or signature; verification steps include the exact command and observable evidence.

Self-Review Before Handoff

1. Coverage: map every requirement and non-goal to a task; add any missing coverage.
2. Placeholder scan: search tasks.md for every banned phrase above and replace vague instructions.
3. Interface/type consistency: compare all produced and consumed names, signatures, field names, and task dependencies.
4. Boundaries: confirm every task has its own deliverable, test cycle, review decision, and commit; merge setup/docs fragments into their owning task.

Fix findings inline before emitting the handoff.

Emit Handoff + Continuity

Write .cm/handoff/plan.json:

{
  "schema": "plan@1",
  "emitted_at": "2026-08-04T00:00:00.000Z",
  "emitted_by": "cm-planning",
  "data": {
    "goal": "Validate execution-ready plan handoffs",
    "decisions": ["Keep task_specs optional for plan@1 compatibility"],
    "first_tasks": ["1.1"],
    "openspec_path": "openspec/changes/rich-plan-handoff/",
    "task_specs": [{
      "id": "1.1",
      "goal": "Validate complete task specifications",
      "deliverable": "A backward-compatible validator with focused coverage",
      "files": [
        { "path": "src/handoff/io.ts", "action": "modify" },
        { "path": "test/handoff.test.ts", "action": "modify" }
      ],
      "dependencies": ["validateHandoff(obj: unknown)"],
      "interfaces": {
        "consumes": ["PlanTaskSpec from src/handoff/contracts.ts"],
        "produces": ["PlanHandoff.data.task_specs?: PlanTaskSpec[]"]
      },
      "acceptance_criteria": ["Rich handoffs round-trip and legacy handoffs remain valid"],
      "steps": [
        {
          "id": "1.1.1",
          "action": "Add the failing incomplete-task validation test",
          "files": ["test/handoff.test.ts"],
          "test_cycle": {
            "phase": "red",
            "command": "npx vitest run test/handoff.test.ts",
            "expected_result": "FAIL because incomplete task_specs are accepted"
          }
        },
        {
          "id": "1.1.2",
          "action": "Implement required-field validation and rerun the focused test",
          "files": ["src/handoff/io.ts"],
          "test_cycle": {
            "phase": "green",
            "command": "npx vitest run test/handoff.test.ts",
            "expected_result": "PASS with all handoff tests and zero failures"
          }
        }
      ],
      "verification": {
        "command": "npx vitest run test/handoff.test.ts",
        "expected_result": "All handoff tests pass with zero failures"
      },
      "commit_boundary": "Commit the contract, validator, and focused tests together"
    }]
  }
}

Update .cm/CONTINUITY.md: Active Goal, first three Next Actions, Current Phase planning, and key decisions. Downstream execution reads each task_specs entry directly; it must not need the full plan to start that task.