dev-plan

---
name: "dev-plan"
description: "Use $HOME instead of the literal home directory (e.g., bash \"$HOME/code/…/discover.sh\", not bash \"/Users/name/…/discover.sh\")."
license: "MIT"
---

## Step 0: Discover Project Root

Run the [discovery script](scripts/discover.sh):

```bash
bash "$DISCOVER" root
```

Where `$DISCOVER` is the absolute path to `scripts/discover.sh` within this skill's directory.

**Path safety** — shell state does not persist between tool calls, so you must provide full script paths on each call:
- **Use `$HOME`** instead of the literal home directory (e.g., `bash "$HOME/code/…/discover.sh"`, not `bash "/Users/name/…/discover.sh"`). This prevents username hallucination.
- **Copy values from tool output.** When reusing a value returned by a previous command (like `$PROJECT_ROOT`), copy it verbatim from that command's output. Never retype a path from memory.
- **Verify on first call**: if a script call fails with "No such file", the path is wrong — STOP and re-derive from the skill-loading context.
- **Never ignore a non-zero exit.** If any script in this skill fails, stop and report the error before continuing.

Store the output as `$PROJECT_ROOT`. If the command fails, inform the user and stop.

## PRIMARY DIRECTIVE

The sole deliverable is PRD files written to `$PROJECT_ROOT/.dev/$FEATURE_NAME/`.
Produce documentation, not code. Every session must end with files on disk.

This is part of a 3-skill system (`/dev-plan` → `/dev-checkpoint` → `/dev-resume`). The other skills parse PRD files using status markers (`⬜` pending; `✅`/`⏭️`/`⛔`/`⏹️` resolved), phase gates, file changes summary, and sub-PRD links. Write steps with `⬜` — any other emoji marker parses as an unrecognized status: the step still counts toward the total, but it reads as not done and `status-update` will refuse to write over it.

## AGENTS

This skill uses specialized agents for research and planning:

- **prd-researcher** (cyan) — Researches codebase for patterns, dependencies, and reference implementations
- **prd-planner** (green) — Designs implementation phases and file changes

Agent definitions are in `agents/` within this skill's directory.

## PHASE 1: UNDERSTAND

$ARGUMENTS

The 3 key questions for this phase:
1. **What feature do you want to build?** (Brief description)
2. **What problem does it solve?** (User need or business requirement)
3. **Is there a reference implementation?** (Existing code, similar feature)

### Path A — Arguments were provided above

If `$ARGUMENTS` above is non-empty (the user provided a feature description):
1. Extrapolate answers to all 3 questions from the provided text.
2. Present a 2-3 sentence summary of your understanding.
3. **Proceed directly to Phase 2.** Do not ask for confirmation.

### Path B — No arguments provided

If `$ARGUMENTS` above is empty (the user ran `/dev-plan` with no arguments):
1. Ask the 3 questions above.
2. **STOP. Do not output anything else. Do not proceed until the user responds with their answers.**
3. After receiving answers, summarize your understanding in 2-3 sentences.
4. Ask: "Does this capture your intent? Confirm and I'll start researching."
5. Do NOT move to Phase 2 until the user explicitly confirms.

> **Guardrail**: Once confirmed (Path B) or summarized (Path A), move to research. Don't linger here.

### Step 1.5: Derive and Validate `$FEATURE_NAME`

Before creating any directories or files, set a safe feature slug in `$FEATURE_NAME`.

Normalize and validate with the [validation script](scripts/validate.sh):

```bash
bash "$VALIDATE" normalize "<candidate-name>"
```

Where `$VALIDATE` is the absolute path to `scripts/validate.sh` within this skill's directory. Apply the path safety rules from Step 0 (`$HOME`, copy from output). Outputs `$FEATURE_NAME` on success; on failure, **STOP immediately** — do not continue with an unvalidated path.

Rules:
- Never use raw `$ARGUMENTS` directly in file paths.
- Use `$FEATURE_NAME` for all `.dev/` path references.

## PHASE 1.8: WIKI CONSULTATION (optional)

Before researching, check the cross-project wiki for prior art:

```bash
cat "$HOME/.dev-wiki/index.md" 2>/dev/null
```

- If the file exists, scan it for features related to the current task — similar names, overlapping domains, reusable patterns. Mention any relevant prior art when briefing the research agents.
- If the file does not exist, skip silently and proceed to Phase 2.

This step is informational only. Do not block on wiki absence.

## PHASE 2: RESEARCH

Launch **2-3 prd-researcher agents in parallel** using the Task tool with different focuses:

```
Agent 1: "Find similar implementations and patterns to reuse for [feature]. Include file:line references."
Agent 2: "Identify architecture constraints, dependencies, and integration points for [feature]."
Agent 3: "List all files that will need modification for [feature] and what changes are needed."
```

Use `subagent_type=dev-workflow:prd-researcher` for each agent.

### After Agents Return

1. **Synthesize findings** — Combine agent outputs into a unified Research Summary
2. **Present summary** using this format:
   - **Patterns to reuse** — existing code/architecture to leverage (with `file:line` refs)
   - **Files to modify** — list of paths with 1-line descriptions
   - **Key decisions** — 2-3 architectural choices needing confirmation
   - **Open questions** — anything unclear (if any)

Keep it to ~10-15 lines.

**STOP. Do not proceed to Phase 3 until the user confirms the research findings or provides corrections.**

> **Guardrail**: Research serves the PRD. Move to writing after one research round. If deeper investigation is requested, do one more round — then write.

## PHASE 3: WRITE THE PRD

Launch **1 prd-planner agent** to design the implementation structure:

```
"Design implementation phases for [feature].
Research findings: [summarize key patterns and files from Phase 2].
Determine if this needs sub-PRDs (complex) or a single PRD (simple)."
```

Use `subagent_type=dev-workflow:prd-planner`.

### After Agent Returns

1. **Review agent output** — Verify phases are logical and complete
2. **Propose architecture approach** — Present the recommended structure to the user

**STOP. Do not create any files until the user confirms the architecture approach or requests adjustments.**

3. **Create files** under `$PROJECT_ROOT/.dev/$FEATURE_NAME/`:
   - Always create `00-master-plan.md` — use the Master Plan template in [prd-templates.md](references/prd-templates.md)
   - For complex features, create `01-sub-prd-[name].md` etc. — use the Sub-PRD template in [prd-templates.md](references/prd-templates.md)
     - **Track each phase's steps in ONE place, never both.** Either the master plan's Implementation Order carries the numbered ⬜ steps (and the sub-PRD is a step-less narrative), OR the master plan collapses phases into step-less range headers and the sub-PRD `## Implementation Progress` table carries the steps. Listing the same steps in both makes the sub-PRD counters a dead duplicate — `status-update` only writes one file, so the other freezes and the dashboard shows a misleading `0/N`.
   - Incorporate research findings (Phase 2) and implementation plan (agent output) into the PRD
4. **Verify PRD structure** — Run the CLI to confirm the PRD is parseable:

   ```bash
   node "$CLI" feature-show --json --dir "$PROJECT_ROOT/.dev/$FEATURE_NAME"
   ```

   Where `$CLI` is the absolute path to `scripts/dev-workflow.cjs` within this skill's directory. Apply the path safety rules from Step 0 (`$HOME`, copy from output).

   If the command fails or returns unexpected data, fix the PRD files before continuing.

5. **State what was created** — list every file path written.
6. **Suggest running `/dev-checkpoint`** to save a continuation prompt.

> **Guardrail**: Files MUST be created. If this phase is reached without writing, stop everything else and write the PRD.

## RULES

- One round of research, then write — do NOT research endlessly
- Fold research findings into the master plan's "Research Findings" section (no separate `findings.md`)

## PRIVACY RULES

**NEVER include in PRD files** — use safe alternatives:
- Absolute paths with usernames → use relative paths from project root
- Secrets, API keys, tokens, credentials → use placeholders (`<API_KEY>`, `$ENV_VAR`)
- Personal information (names, emails) → use generic references