| name | spec-driven-development |
| description | 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. |
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: <ISO 8601 UTC with Z>, depends_on: [.forge/idea-brief.md] if it exists else [] — paths only, never hashes, generated_from: {.forge/idea-brief.md: <upstream content_hash AT generation time>} if idea-brief exists else {}, content_hash: <sha256 first 8 of THIS file's body>) — see forge-dependency-graph. Then write using the template below.
PRD Template
<!-- forge:meta
generated_by: spec-driven-development
generated_at: 2026-05-13T12:00:00Z
depends_on: [.forge/idea-brief.md]
generated_from:
.forge/idea-brief.md: <idea-brief.md's content_hash at this moment>
content_hash: <first 8 chars of sha256 over this PRD's body>
-->
# 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:
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.
