Plan

Create Implementation Plan

Create an implementation plan for $ARGUMENTS.

A plan is a file, not a transcript. The plan produced here is written to a resolved path, validated against a document contract, reviewed by Codex, and approved by the user — in that order, and all four. A plan that lives only in the conversation cannot be handed to /team-execute, cannot survive a /checkpointing compaction, and cannot be re-read next session.

Planning Process

0. Resolve the Workspace (always first)

Resolve this plan's slug and output path once. The title becomes the file name, so give it a short English descriptor — not the user's raw wording, which the Language Protocol keeps out of paths:

python3 .claude/skills/_shared/workspace.py \
  --skill plan --title "<short English title>" --create

The JSON on stdout carries slug and paths.plan_doc (.claude/docs/plans/{slug}.md). Every {slug} and every output path below — and the /team-execute handoff in step 6 — MUST come from this JSON verbatim, never be re-derived by hand: two hand-derived slugs are exactly how a plan and its executor's work logs drift apart. Exit codes: 0 resolved (and created); 1 bad arguments.

If .claude/docs/plans/{slug}.md already exists, the plan is a revision of that document — read it first and say so, rather than silently overwriting it.

1. Requirements Analysis

First clarify with the user:

• Purpose: What to achieve
• Scope: What to include, what to exclude
• Constraints: Technical, time, dependencies

Ask, do not assume. Unresolved items belong in ### Open Questions, not in a guessed step.

2. Current State Investigation

Reading the codebase for a plan is broad-context work: delegate it rather than consuming orchestrator context.

Task tool:
  subagent_type: "general-purpose-opus"
  prompt: |
    Investigate this codebase for a planned change: {purpose from step 1}

    Report, with file:line evidence for every claim:
    1. Related existing code — which modules already do something similar
    2. Files that will need to change, and why each one
    3. Libraries and patterns the change should reuse (project conventions)
    4. Existing tests that cover the affected area, and gaps in that coverage
    5. Constraints or invariants the change must not break

    Use Glob, Grep, and Read. Do not implement anything.
    Return the findings; do not summarize away the file paths.

The returned findings are the source of ### Scope and ### Risks & Considerations in the plan document. A plan whose Scope names no concrete file paths is a plan written without reading the code — send the investigation back rather than proceeding.

3. Break Down Implementation Steps

.claude/rules/codex-delegation.md names "you need a step-by-step implementation plan" and "design/architecture decisions are involved" as explicit Codex triggers, so step decomposition is a MANDATORY Codex consult — the same rule /feature follows for the same artifact class.

Write the prompt body to a file, then invoke the shared wrapper (the directory is not created by the wrapper before it reads the prompt, so create it first):

mkdir -p .claude/logs/codex
# write the prompt body to .claude/logs/codex/prompt-plan-{slug}-steps.md, then:
python3 .claude/skills/_shared/codex_consult.py \
  --prompt-file .claude/logs/codex/prompt-plan-{slug}-steps.md \
  --label plan-{slug}-steps --sandbox read-only

Prompt body:

Objective: Decompose this change into an ordered, independently testable implementation plan.
Context:
- Purpose: {purpose from step 1}
- Scope in / out: {from step 1}
- Constraints: {from step 1}
- Current state: {findings from step 2, with file paths}
Constraints:
- Order steps by dependency (what must exist before what)
- Each step is independently testable; name its verification
- Put high-risk and high-uncertainty steps first
- Keep steps small; do not over-detail work that will be re-decided during implementation
Output format:
## Implementation Steps (ordered by dependency)
## Verification per Step
## Risks and Mitigations
## Open Questions

Read the answer from the JSON output's response_file. Exit codes: 0 the call succeeded — read response_file; 1 bad args; 2 codex CLI not on PATH; 3 codex exited non-zero or timed out — inspect error and stderr_file before retrying or escalating. Codex proposes the decomposition; deciding which steps are the right steps stays yours.

4. Output Format

Write the plan to the plan_doc path from step 0 (.claude/docs/plans/{slug}.md) using this shape. The five ### sections are the plan-doc document contract — renaming or dropping one is a validation failure in step 5:

## Implementation Plan: {Title}

### Purpose
{1-2 sentences}

### Scope
- New files: {list}
- Modified files: {list}
- Dependencies: {list}

### Implementation Steps

#### Step 1: {Title}
- [ ] {Specific task}
- [ ] {Specific task}
**Verification**: {Completion criteria for this step}

#### Step 2: {Title}
...

### Risks & Considerations
- {Potential issues and mitigations}

### Open Questions
- {Items to clarify before implementation}