plan

<objective>

Analysis-only. Produces structured plan, no code. Use to understand scope, risks, effort before /develop:feature, /develop:fix, /develop:refactor.

NOT for: code/tests (use develop mode); .claude/ config (use /foundry:manage (requires foundry plugin)).

• non-Python-only projects (JS/TS/Go/Rust with no Python source) — downstream develop skills assume pytest; planning analysis itself is language-agnostic but downstream implementation will require a language-native toolchain
• mixed refactor+feature tasks — run /develop:refactor first, then /develop:feature

</objective>

<workflow>

<!-- Agent resolution: see _DEV_SHARED/agent-resolution.md (mounted by develop plugin init) -->

Agent Resolution

_DEV_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/develop}/bin/dev_shared_resolve.py" 2>/dev/null)  # timeout: 5000

Read $_DEV_SHARED/agent-resolution.md. Contains: foundry check + fallback table. If foundry not installed: use table to substitute each foundry:X with general-purpose. Agents this skill uses: foundry:sw-engineer, foundry:qa-specialist, foundry:linting-expert, foundry:challenger.

Checkpoint: plan is single-pass — .plans/active/<slug> file existence = implicit resume signal. No .developments/ checkpoint needed; if interrupted, re-run /develop:plan to regenerate (no code changes made).

Read $_DEV_SHARED/task-hygiene.md.

Anti-Rationalizations

| Temptation | Reality | | --- | --- | | "The plan is obvious — no need for agent feasibility review" | Feasibility review catches domain-specific blockers (missing test infrastructure, incompatible library constraints, API changes) that seem obvious in hindsight. | | "Codex design review is optional for small tasks" | Small tasks regularly reveal large hidden dependencies. Codex catches architectural anti-patterns before they are baked into an implementation plan. | | "I can scope this during implementation — no need to plan first" | Scope discovered during implementation inflates PRs and obscures intent. Plan mode exists to prevent exactly this. |

Flag parsing

Parse flags into actual shell variables (not prose) so downstream blocks see correct values. Persist to temp files for cross-block access (bash state lost between Bash() calls):

# timeout: 5000
CHALLENGE_ENABLED=true
CODEMAP_ENABLED=false
SEMBLE_ENABLED=false
[[ " $ARGUMENTS " == *" --no-challenge "* ]] && CHALLENGE_ENABLED=false
[[ " $ARGUMENTS " == *" --codemap "* ]] && CODEMAP_ENABLED=true
[[ " $ARGUMENTS " == *" --semble "* ]] && SEMBLE_ENABLED=true
MAX_DEPTH=$(echo "$ARGUMENTS" | grep -oP '(?<=--max-depth )\d+' || echo "3")
echo "$CHALLENGE_ENABLED" > ${TMPDIR:-/tmp}/dev-challenge-enabled
echo "$CODEMAP_ENABLED"   > ${TMPDIR:-/tmp}/dev-codemap-enabled
echo "$SEMBLE_ENABLED"    > ${TMPDIR:-/tmp}/dev-semble-enabled
echo "$MAX_DEPTH"         > ${TMPDIR:-/tmp}/dev-max-depth

Downstream blocks read back, e.g. CODEMAP_ENABLED=$(cat ${TMPDIR:-/tmp}/dev-codemap-enabled 2>/dev/null || echo false).

Unsupported flag check — after all supported flags extracted, scan $ARGUMENTS for remaining --<token> tokens. If found: print ! Unknown flag(s): \--<token>\. Supported: \--no-challenge\, \--codemap\, \--semble\, \--max-depth\. then invoke AskUserQuestion — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

Preflight — if CODEMAP_ENABLED=true:

Read $_DEV_SHARED/preflight-helpers.md — execute codemap + semble preflight if respective flags set.

Step 1: Classify and scope

Determine task type and affected surface.

If CODEMAP_ENABLED=true or SEMBLE_ENABLED=true: read $_DEV_SHARED/codemap-context.md and follow enabled sections (codemap block if CODEMAP_ENABLED, semble companion if SEMBLE_ENABLED). Skip if both flags false.

Spawn foundry:sw-engineer agent with full goal text from $ARGUMENTS. Agent should:

• Classify task as feature, fix, refactor, or debug
• debug: root cause unknown — symptoms present but cause unclear, investigation needed before a fix can be scoped; when classified debug, recommend running /develop:debug first, then re-run /develop:plan once root cause identified to produce a fix plan
• WARNING: debug classification triggers /develop:debug which can re-invoke /develop:plan — caller tracks dispatch depth to prevent infinite loop via --max-depth flag. Max depth = $MAX_DEPTH (default 3, CLAUDE.md safety break). At limit (--max-depth 0): stop, report current plan state, invoke AskUserQuestion — (a) Accept plan as-is · (b) Re-scope with reduced depth requirement. Pass --max-depth $((MAX_DEPTH - 1)) when invoking /develop:debug to decrement counter.
• Identify affected files and modules (search codebase — no guessing)
• Assess complexity: small (1-3 files, self-contained), medium (4-8 files or 1-2 modules), large (cross-module, API changes, or 3+ modules)
• List risks: breaking changes, missing tests, unclear requirements, external dependencies
• Note complexity smells: ambiguous goal, scope creep risk, missing reproduction case, directory-wide refactor without explicit goal

Agent returns findings inline (no file handoff — output short).

Breaking change gate: if agent lists any breaking change in risks — stop before writing plan. Call AskUserQuestion per breaking change (group only when logically one atomic change). State: what worked before, what breaks, why needed. Proceed only on explicit user confirmation. Prose question in response body does NOT count — AskUserQuestion mandatory per communication.md. If user selects No/Abort/Decline: stop immediately — do not proceed to Step 2 or subsequent steps.

Breaking change criteria — a change is breaking when any of these apply: removed public API (function, class, method, or module), changed function signatures (parameter names, types, order, or defaults), changed config key names or schema, changed output format (return type, serialization structure, CLI output shape).

Step 2: Structured plan

Derive filename slug from goal: first 4-5 meaningful words, lowercase, hyphen-separated (e.g. "improve caching in data loader" -> plan_improve-caching-data-loader.md). If .plans/active/<slug> already exists, append counter suffix (-2, -3, etc.) before writing — never silently overwrite. Store full path as PLAN_FILE — used in Steps 3 and Final output.

# Plan: <goal>

## Brief

*[Generated after agent review — see below]*

---

## Full Plan

**Classification**: feature | fix | refactor
**Complexity**: small | medium | large
**Date**: <YYYY-MM-DD>

### Goal

<One-paragraph restatement of the goal in concrete terms — what changes, what doesn't.>

### Affected files

- `path/to/file.py` — reason
- `path/to/other.py` — reason

### Risks

- <risk 1>
- <risk 2>

### Suggested approach

1. <Step 1>
2. <Step 2>
3. <Step 3>
...

Step 3: Agent feasibility review

Spawn execution agents by classification in parallel. Each reads <PLAN_FILE>, returns only compact JSON — no prose, no analysis:

• feature: foundry:sw-engineer, foundry:qa-specialist, foundry:linting-expert
• fix: foundry:sw-engineer, foundry:qa-specialist, foundry:linting-expert
• refactor: foundry:sw-engineer, foundry:linting-expert, foundry:qa-specialist
• debug: skip feasibility review — no implementation plan to review; proceed directly to Final output with debug recommendation

Each agent receives only plan file path and role — no conversation history, no unrelated context. Prompt (substitute <ROLE> and <PLAN_FILE>):

"Read <PLAN_FILE>. Review the plan from your perspective as <ROLE>. Flag any domain-specific concerns, risks, or blockers you see. Can you execute your part autonomously without further user input? Return only: `{\"a\":\"<ROLE>\",\"ok\":true|false,\"blockers\":[\"...\"],\"q\":[\"...\"],\"concerns\":[\"...\"]}