ccc-plan git:20261013.fbe187dA

Immutable. This exact content never changes and is served at /api/v1/blob/cca26a104e643bc9.

---
name: ccc-plan
description: "Turn an idea, bug, refactor or Linear issue into a reviewed plan file with evals, via a short spec interview and a background planner agent that writes to the session plan path. Use when the user wants to plan a feature, scope work before coding, or types $ccc-plan."
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
  - EnterPlanMode
  - ExitPlanMode
  - TodoWrite
  - mcp__ccd_session__mark_chapter
  - mcp__linear__list_issues
argument-hint: "[new | bug | refactor | linear | \"idea in quotes\"]"
model: sonnet
effort: medium
---

# $ccc-plan — spec before any code

**CC Commander** · $ccc-plan · a plan file with success and failure evals, shown in the Desktop Plan pane before anything is built.

This is the evals-before-specs-before-code gate. Plan mode is entered here because the user asked for a plan; it is not the session's default posture.

## When to use / when not to

- Use for multi-step features, non-trivial bug fixes, refactors, or turning a tracker issue into scoped work.
- Use `$ccc-brainstorm` first when the approach itself is undecided. Use `$ccc-plan-exec` when the work is the same body repeated over many items. Skip planning for a one-line fix.

## What happens

### 1. Resolve `PLAN_PATH` (always first)

- If the system context contains a "Plan File Info" block, plan mode is already active: capture that path as `PLAN_PATH` and do not call `EnterPlanMode`.
- Otherwise call `EnterPlanMode` and capture the path it returns as `PLAN_PATH`.
- If `EnterPlanMode` is not available (Codex, or a context without plan mode), set `PLAN_PATH` to `~/.claude/plans/ccc-<YYYY-MM-DD>-<slug>.md` and tell the user the Desktop Plan pane may not pick it up.

`PLAN_PATH` is the only write target under `~/.claude/plans/`. The Plan pane reads only the session-bound path it created; a self-chosen fixed filename shows "no plan yet".

### 2. Mark the chapter

Call `mcp__ccd_session__mark_chapter` with `title: "Feature planning"` and a one-line `summary` inferred from the argument ("Structured feature plan" if none). Skip silently if the tool is not exposed.

### 3. Header and context strip

Read the version from `${CLAUDE_PLUGIN_ROOT}/.codex-plugin/plugin.json` (never hardcode it) and print:

```
**CC Commander** · v{VERSION} · Planner · spec-first, plan-before-code
```

Gather context in one Bash call:

```bash
ls ~/.claude/plans/ 2>/dev/null | wc -l
git rev-parse --abbrev-ref HEAD 2>/dev/null
ls tasks/todo.md 2>/dev/null
git log --oneline -5 2>/dev/null
```

Render one line: `🎯 Planner: branch <branch> · <N> prior plans · tasks/todo.md: <present|absent> · last commit: <age>`. Outside a repo: `🎯 No repo detected — the plan goes to the session plan path only.`

### 4. Pick the plan type

Skip this step when the argument is a quoted idea: treat it as a new feature and go to step 5. When the argument is `new`, `bug`, `refactor` or `linear`, take that path directly.

Otherwise ask with the picker under Decision points.

### 5. Run the interview

Ask the question set for the chosen path from [references/interview.md](references/interview.md): 3 to 5 `AskUserQuestion` calls, one at a time, at most 4 options each. Keep it tight; the planner fills in detail.

### 6. Delegate to the planner agent

Call the `Agent` tool with `subagent_type: "general-purpose"`, `model: "sonnet"`, `effort: "medium"`, and a prompt that contains:

1. The interview answers as a structured brief, and the exact `PLAN_PATH`.
2. Read the relevant files first (`CLAUDE.md`, `package.json`, the source the plan touches).
3. Write the plan in the shape of [references/plan-template.md](references/plan-template.md) to `PLAN_PATH` and nowhere else. First line: `<!-- generated by $ccc-plan · <ISO timestamp> -->`.
4. Plan execution workflow-first: substantive steps go to agents or workflows (`rules/workflow-first.md`), each phase checked by someone other than its worker.
5. Return only a one-line summary.

While it runs, say: `🔄 Planner agent drafting your plan — usually under a minute.` Do not draft the plan in the main thread.

### 7. Verify the file, then hand off to the Plan pane

Run the Done-when checks below. Then:

1. Call `mcp__ccd_session__mark_chapter` with `title: "Plan drafted — pending approval"` and the agent's summary.
2. Call `ExitPlanMode`. Writing the file alone does not activate the Plan pane; this call does. Call it even if the user dismisses early.
3. Reply:

```
✅ Plan written to the session plan path (open in the Desktop Plan pane)
   <one-line summary from the agent>

Approve, modify or reject it from the Plan pane.
```

### 8. Optional project copy

Ask with the "project copy" picker. On yes:

```bash
mkdir -p tasks/plans
cp "$PLAN_PATH" "tasks/plans/<slug>.md"
test -s "tasks/plans/<slug>.md" && echo copied
```

`<slug>` is a kebab-case summary of 6 to 8 words. Report `📝 Project copy saved to tasks/plans/<slug>.md`. The copy is for git history and sharing; `PLAN_PATH` stays the source the Plan pane reads.

### 9. Seed the todo list

Call `TodoWrite` with the plan's Phase 1 steps, all `pending`.

### 10. Next step

Ask with the "next step" picker.

## Decision points

Plan type (step 4). Put the recommended option first, marked 🟢:

- 🟢 when recent commits start with `fix:`/`bug:` or show test failures → "Plan a bug fix"; after `$ccc-review` findings → "Refactor existing code"; on a branch with an issue-key prefix and the Linear connector exposed → "Build from a Linear issue"; otherwise → "New feature from a description".

```
question: "What kind of plan are we writing?"
header: "Planner"
multiSelect: false
options:
  - label: "💡 New feature from a description"
    description: "You describe the idea; a 5-question interview, then a full implementation plan."
  - label: "🔧 Plan a bug fix"
    description: "Reproduction, root cause, fix scope, regression tests. No fix step before a confirmed cause."
  - label: "🏗️ Refactor existing code"
    description: "Reads the code first; before/after contracts, test-first safety net, incremental steps."
  - label: "📝 Build from a Linear issue"
    description: "Turns an issue's title and description into a scoped plan. Needs the opt-in Linear connector."
```

Project copy (step 8):

- 🟢 No — the session copy is enough
- Yes — copy to `tasks/plans/<slug>.md` for git history and team sharing

Next step (step 10), 🟢 first:

- 🟢 Start building — `$ccc-build <type>` (or `$ccc-plan-exec` when the plan is one body repeated per item)
- Show the plan here in chat
- File it as a Linear issue — hands off to `$ccc-linear`, which asks before writing
- Done for now

## Done when

- `head -1 "$PLAN_PATH"` prints the `<!-- generated by $ccc-plan` trace line.
- `grep -c '^## Evals' "$PLAN_PATH"` prints `2` (both success and failure evals present). If either check fails, send the planner one correction pass; if it still fails, report the gap instead of calling the plan done.
- `ExitPlanMode` was called, and the reply named the plan's one-line summary.
- If a project copy was requested, the `test -s` check printed `copied`.

## Guardrails

- Never write a plan to any path under `~/.claude/plans/` other than `PLAN_PATH`, and never paste the full spec into chat instead of writing the file.
- Never write or edit product code from this skill; it ends at an approved plan.
- Never ask questions as a numbered list for the user to type answers to; every choice is an `AskUserQuestion` picker (Codex: a plain-text question).
- Never skip the evals sections. "What does done look like" is required.
- Never write to Linear or another tracker from here. Filing an issue goes through `$ccc-linear`, which asks for authorization at that moment.
- Never treat Linear as present: it is an opt-in connector, absent by default; fall back to a pasted description.
- The planner runs on `sonnet`; the user's selected session model is preserved.

## See also

- `$ccc-brainstorm` — compare three approaches before planning
- `$ccc-plan-exec` — plan a repeated loop cheaply, execute it on a capable model
- `$ccc-build` — scaffold from the approved plan
- `$ccc-debate` — stress-test a high-stakes plan with adversarial lenses

---

> ⚙️ **Fable contract:** plan before build · verifier ≠ worker · prove before alarm · loops need gates · leave durable state — `rules/fable-method.md`

> (On Codex, present these options as a numbered list and ask the user to reply with a number — AskUserQuestion is Claude-only.)