create-plan

Files (3)

• SKILL.md
• explorer-prompts.md · references/
• plan-template.md · references/

SKILL.md (first lines)

# Create Implementation Plan

> Relies on BDK foundation (STARTUP_INSTRUCTIONS.md) for project context.

!`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject-rules.py engineering-judgment`

Transform requirements into detailed, TDD-driven implementation plans via structured exploration and analysis.

**Core Principle:** Explore → Design → Outline+Verify → Write

**Optimize for parallel execution.** The plan is consumed by `/bdk:subagent-execute-plan`, which fans out as many implementer subagents as it can run concurrently. The single biggest lever on end-to-end speed is **how the plan decomposes work**: tasks that touch disjoint files and declare honest dependencies let the executor run a wide wave instead of a long serial chain. A plan that is correct but accidentally serial is a slow plan. Design the task graph to be **wide and shallow**, not deep.

**Announce at start:** "Using create-plan to build an implementation plan."

**Hard rules:**
- Do NOT implement code — plan is the only deliverable.
- Do NOT hardcode language tools (`pytest`, `npm`, `cargo`) — use injected values or fall back to "run the project's test suite".
- Every task MUST declare its `Files:` and its `Depends on:` (or `Depends on: none`). The executor uses both to compute parallel waves — omitting them forces conservative serial fallback.

---

## Workflow

### Phase 1: Parse & Setup

1. **Validate input**
   - `$ARGUMENTS` empty/blank → ask user to describe feature, **stop**.
   - Vague (< 10 words OR generic like "make it better") → suggest `/bdk:design`, **stop**.

2. **Derive slug deterministically**
   - Lowercase `$ARGUMENTS`, strip punctuation, drop stop-words `{the, a, an, for, to, of, in, on, with, and, or}`.
   - Keep first 3-5 remaining content words, join with `-`.
   - On collision in `.bdk/plans/`, append `-v2`, `-v3`, … (lowest free integer).

3. **Generate timestamp deterministically**
   - Use !`date +%Y-%m-%d-%H%M` — do not invent.

4. **Set plan path:** `.bdk/plans/<timestamp>-<slug>.md`

   > Directory `.bdk/plans/` is pre-created by the skill's `UserPromptSubmit` hook — no runtime mkdir needed.

5. **Existing-plan handling** — if file exists, `AskUserQuestion`:
   - Overwrite (keep same path)
   - Create v2 (append `-v2` per slug rule above)
   - Stop

6. **Check design docs** — scan `.bdk/design/` for slug keywords; if found, print `[create-plan] Found related design doc: {filename}` and read it.

Print: `[create-plan] Setup complete. Plan: <path>`

**GATE:** valid input + plan path required before Phase 2.

---

### Phase 2: Exploration (always via subagents)

Exploration runs in subagents — never in the orchestrator. Subagent context is throwaway, orchestrator context is precious. A "small" feature can still need many tool calls; agent count tracks **question dimensions**, not feature size.

**Pick agents by question** (see `references/explorer-prompts.md` for full prompts and shared output contract):

| Agent | Question it answers | Always launch? |
|---|---|---|
| Agent 1 — Existing Code | What can be reused? | **Yes, always** |
| Agent 2 — Architecture & Dependencies | What does it touch, what depends on it? | If feature modifies existing components or crosses module boundaries |
| Agent 3 — Similar Features | How have comparable features been built before? | If a similar pattern likely exists in the codebase |

These dimensions are orthogonal — choosing one doesn't imply the others.

Print: `[create-plan] Launching {N} explorer(s): {list of agent names}`

**Failure handling:** on agent error or malformed JSON, retry once via `SendMessage(to: "<agentId>", ...)` with a narrowed prompt — cheaper than a fresh spawn (see STARTUP "Continuing a Spawned Agent"). On second failure, record `[create-plan] Agent {N}: no results` and proceed; note the gap in the plan's Risks section.

**Aggregation:** merge agent JSON outputs by `path`+`name` dedup. Keep the merged result in conversation context — do **not** persist a snapshot file. The plan's Context section will capture what's needed.

Print:
```
[create-plan] Exploration complete:
  - Utilities: {N}
  - Affected files: {N}
  - Similar features: {N}
  - Degraded agents: {list or "none"}
```

**GATE:** at least Agent 1 must succeed before Phase 3.

---

### Phase 3: Design & Decisions

Before generating approaches, write a **3-line Hypothesis**:
1. Problem essence (one sentence).
2. Primary constraint (perf / compat / scope / risk).
3. Success criterion (observable, testable).

Generate **2-3 implementation approaches.** Per approach:
- Name, Description (2-3 sentences)
- Design pattern, OO principles
- Pros (2-3), Cons (1-2)
- Complexity: LOW | MEDIUM | HIGH (informational only - per engineering-judgment rules, do not let this drive the recommendation; weight quality, robustness, and long-term maintainability instead)
- Risk: LOW | MEDIUM | HIGH
- Files to change
- **Structural impact** — if this approach extends an existing conditional / switch / handler chain (if-elif, switch, type-dispatch, registry):
  - Branches before: `N`
  - Branches after: `N+1`
  - At what `N` does this structure stop being the right shape? Name the refactor (Strategy map, polymorphism, dispatch table, state machine, etc.).
  - If `N+1` crosses that threshold, **propose the refactor as a separate approach** — do not silently add another branch.

**Parallelism is a first-class design axis.** When comparing approaches, prefer the one that decomposes into more independent units of work — all else roughly equal, an approach that yields 6 file-disjoint tasks beats one that yields 3 tasks chained by shared-file edits. Note each approach's **parallel width** (how many tasks could run at once) alongside its complexity/risk. A lower-complexity approach that is fully serial may lose to a slightly more complex approach that fans out.

**Decision resolution** — bundle every open decision into ONE `AskUserQuestion` call (multi-question form supports up to 4). Mark recommended approach as first option. Do not split into multiple sequential prompts.

!`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject.py --if features.lavish --if tool.lavish-axi --then ${CLAUDE_PLUGIN_ROOT}/fragments/decision-tier/lavish.md`

**Decision gates rejected inside tasks.** A task body must describe a single committed action. If a task would contain "Option A or B — user picks" or any unresolved decision, split it: move the decision into the bundled `AskUserQuestion` call above, then write the chosen action as the task. Tasks describe what *will* happen, not what *might* happen.

Print: `[create-plan] Design complete: {selected approach name}`

**GATE:** selected approach required before Phase 4.

From broneq/bdk, MIT.

More from broneq/bdk