dev-plan

name	dev-plan
description	Plan a new feature with structured PRD documentation. Researches codebase patterns, designs implementation phases, and writes PRD files to .dev/. Use when starting a new feature, spike, or major task.
argument-hint	<feature description>
allowed-tools	Bash(bash:*) Bash(node:*) Read

Step 0: Discover Project Root

Run the discovery script:

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:

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:

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
   • For complex features, create 01-sub-prd-[name].md etc. — use the Sub-PRD template in 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:

   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