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: <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:

• .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.