# Spec Driven Development > Use when user wants to write a spec, create a PRD, or plan a new feature before implementation begins, when .forge/idea-brief.md exists and is ready to formalize, when requirements need to be captured before architecture or planning, or when a feature's scope and acceptance criteria need to be documented. - Skill: `aneja5/spec-driven-development` (Agent Skill) - Install (CLI): `npx skillmds@latest add aneja5/spec-driven-development` - Raw SKILL.md: https://api.skillmd.com/api/skills/aneja5/spec-driven-development/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: aneja5 (https://skillmd.com/u/aneja5) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/aneja5/spec-driven-development --- # Spec-Driven Development ## Overview Turn a feature idea into a structured PRD at `.forge/prd.md` through interview, codebase exploration, and module design. Reads `.forge/idea-brief.md` if it exists to skip already-answered questions. Output feeds `architecture-and-contracts` and `planning-and-task-breakdown`. ## When to Use - User wants to write a spec, PRD, or product requirements document - User wants to plan a new feature before touching code - `.forge/idea-brief.md` exists and is ready to formalize ## When NOT to Use - `.forge/prd.md` already exists and is current — skip ahead to `architecture-and-contracts` - Idea hasn't been pressure-tested — run `idea-griller` first - Change is trivial (config tweak, single function) — just implement with `tdd` ## Context-Loaded Mode If a comprehensive context document exists (e.g., `context/CONTEXT.md` or similar file with >500 lines of structured research, interviews, or domain analysis), skip the interview steps (Steps 1-3). The context document replaces the user interview — read it in full, extract requirements, and proceed directly to Step 4 (module design). Note in the PRD's Open Assumptions which sections were derived from context document vs. user confirmation. ## Common Rationalizations | Thought | Reality | |---------|---------| | "The feature is simple, skip the spec" | Simple features grow. Write the scope down. | | "I already know what to build" | The interview surfaces what you don't know you don't know | | "Codebase exploration is optional" | PRDs written without it have wrong module assumptions | | "User stories take too long" | Thin story list = thin acceptance criteria = broken scope | | "We can define NFRs later" | NFRs defined late become hard constraints you can't meet | | "Out of Scope can be empty" | Empty = everything is in scope = infinite scope | ## Red Flags - Problem statement written from engineer's perspective, not user's - User stories use passive voice ("system shall") instead of Given/When/Then or actor/want/benefit - Out of Scope section is empty - No non-functional requirements recorded - Module list names files/functions instead of behavioral units - Release phases not defined — everything is "phase 1" ## Core Process ### Step 0: Read the brief Check for `.forge/idea-brief.md`. If it exists, read it. Skip questions already answered. Focus on gaps and open assumptions listed in the brief. ### Step 1: Understand the problem If no brief: ask the user for a detailed description of the problem and solutions they've considered. Let them speak fully before asking follow-up questions. ### Step 2: Explore the codebase (greenfield-aware) **Conditional.** Before dispatching the Explore agent, check whether a codebase exists: - If the repo has source files (any `src/`, `lib/`, `app/`, language-specific entry points, or >5 source files at root), dispatch the Agent tool with `subagent_type=Explore`. Understand current architecture, patterns, and where new modules would attach. Verify the user's assertions against the actual code. - If the repo is **empty or near-empty** (only `README.md`, `package.json`-shaped manifest, `.gitignore`, or no source files at all), **skip the Explore step**. Note in the PRD under "Codebase context": *"Greenfield — no existing code explored."* Do not dispatch Explore against an empty tree; the agent has nothing to find and the wasted turn obscures the actual state. ### Step 3: Interview to shared understanding Walk down each branch of the design tree, resolving dependencies one at a time. Do not proceed while ambiguities exist. Ask about: edge cases, error paths, personas, NFRs, data lifecycle. ### Step 4: Design the modules Identify major modules to build or modify. Prefer deep modules — small interface, large implementation, independently testable. Confirm with user. Ask which modules need tests. ### Step 5: Write .forge/prd.md Create `.forge/` if it doesn't exist. Prepend a `forge:meta` dependency header (`generated_by: spec-driven-development`, `generated_at: `, `depends_on: [.forge/idea-brief.md]` if it exists else `[]` — paths only, never hashes, `generated_from: {.forge/idea-brief.md: }` if idea-brief exists else `{}`, `content_hash: `) — see [forge-dependency-graph](../../references/forge-dependency-graph.md). Then write using the template below. ## PRD Template ```markdown # PRD: [Feature Name] ## Problem Statement [From the user's perspective — not the engineer's] ## Personas [Named actor types with goals and context] ## Functional Requirements ### [Requirement group] - Given [context], When [action], Then [outcome] ## Non-Functional Requirements - Performance: [specific target] - Security: [specific requirement] - Reliability: [uptime / error rate target] ## Data Model [Key entities, relationships, constraints — no file paths or code] ## Module Design [Behavioral units to build or modify. Each: name, responsibility, interface shape] ## Release Phases - **Phase 1 (MVP):** [scope] - **Phase 2:** [scope] ## Out of Scope [Explicit list. Non-empty required.] ## Open Assumptions [Unresolved questions. Empty = suspicious.] ``` ## Verification Before marking complete, confirm: - [ ] `.forge/idea-brief.md` read if it existed; gaps identified - [ ] Codebase explored — user's assertions verified against real code - [ ] All open assumptions from brief addressed or re-noted - [ ] Problem statement from user's perspective - [ ] Given/When/Then covers happy path AND error paths - [ ] Out of Scope non-empty - [ ] NFRs specific (no "fast" — give numbers) - [ ] Module list confirmed with user - [ ] Release phases defined - [ ] `.forge/prd.md` written and readable ## Fit-Check Before declaring done, emit one of: - A short list of specific fit issues observed during this invocation (e.g., "Feature turned out to be a single config tweak — PRD is overscoped for the work; recommend `incremental-implementation` directly next time" / "PRD section on multi-tenancy doesn't apply — this is a single-tenant tool, see #40"). - The explicit line: **"No fit issues observed for this use case."** Silence is not allowed. See [docs/skill-anatomy.md#fit-check](../../docs/skill-anatomy.md#fit-check-the-meta-honesty-step).