/cm-planning

name: cm-planning
description: "You MUST use this before any creative work or multi-step task. Explores intent and writes execution-ready plans before coding."
token_budget: 1500
compressed: true
deprecated: false

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

```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": "Impleme