Spec-Driven Development

Overview

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

This skill owns the lean product/spec merge. Capture product intent, MVP scope, stories, acceptance criteria, useful metrics, technical constraints, and any AI-agent runtime contract in one pass. Do not create separate PM or agent phases. The required outputs are .dev-agent/product/PRD.md and .dev-agent/specs/SPEC.md.

Keep the split crisp: PRD.md owns users, scope, flows, product rules, acceptance, metrics, and non-goals. SPEC.md owns architecture, data, interfaces, commands, tests, privacy/security boundaries, risks, and open technical decisions.

In Dev Agent projects, this skill owns <project-name>/.dev-agent/specs/SPEC.md. Do not create implementation artifacts from this skill; hand off to design-flow for customer-facing UI and then incremental-implementation.

When to Use

• Starting a new project or feature
• Requirements are ambiguous or incomplete
• The change touches multiple files or modules
• You're about to make an architectural decision
• The task would take more than 30 minutes to implement

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.

Lifecycle Boundary

Spec work has one gate here: produce and validate .dev-agent/product/PRD.md and .dev-agent/specs/SPEC.md. The broader Dev Agent lifecycle continues through design, build, optional QA, and optional ship.

IDEA INPUTS ──→ PRD + SPEC ──→ design when UI applies ──→ build

Phase 1: Specify

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.

If product artifacts already exist, reuse them. Otherwise write the minimum PRD: objective, target user, MVP scope, acceptance criteria, non-goals, and metrics only when they affect build or QA decisions. Flag conflicts instead of silently changing product scope.

If external references are provided, absorb them structurally:

• Extract reusable decisions into PRD/SPEC sections.
• Reject or flag unsafe anti-patterns, such as floating-point money, overlarge

P0 scope, silent financial deletion, automatic posting without confirmation, or paywalling platform-provided system capability as if it were proprietary.

• Record conflicts and source differences instead of pasting long reference

text into the spec.

Surface assumptions immediately. Before writing any spec content, list what you're assuming:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding. If the workspace instructions explicitly delegate defaults, record those assumptions in the spec and continue unless the issue is a named human review gate.

Write a PRD and spec covering these core areas:

1. Objective — What are we building and why? Who is the user? What does success look like?

1. Commands — Full executable commands with flags, not just tool names.

   Build: npm run build
   Test: npm test -- --coverage
   Lint: npm run lint --fix
   Dev: npm run dev

1. Project Structure — Where source code lives, where tests go, where docs belong.

   <project-name>/           → Project root for code and stack manifests
   <project-name>/src/       → Simple source root when a monorepo is unnecessary
   <project-name>/apps/      → Runnable app packages when the stack needs them
   <project-name>/packages/  → Shared packages when the project needs them
   <project-name>/.dev-agent/ → Dev Agent process artifacts
   <project-name>/.dev-agent/specs/     → Product and technical specs
   <project-name>/.dev-agent/tasks/     → Plans and task lists
   apps/web/src/           → Application source code
   apps/web/src/components → React components
   apps/web/src/lib        → Shared utilities
   apps/web/tests/         → Unit and integration tests
   apps/web/e2e/           → End-to-end tests
   docs/                   → Project documentation

1. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.

1. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.

1. Agent Runtime Contract — Only when agent automation is in scope. Define

the agent job, non-goals, tools, permissions, approval points, prompts, skills/context, memory/checkpoints, evals, observability, and failure recovery/escalation. If a tool, permission, or recovery path is unclear, raise it instead of inventing a workaround.

1. Boundaries — Three-tier system:

• Always do: Run tests before commits or checkpoints, follow naming conventions, validate inputs
• Ask first: Database schema changes, adding dependencies, changing CI config, high-risk architecture, security/payment/permission/data-deletion behavior, production launch approval
• Never do: Commit secrets, edit vendor directories, remove failing tests without approval

For customer-facing products, also cover product-domain depth where applicable: information architecture, onboarding, default data, feature field matrices, states/errors, permissions/privacy copy, monetization/paywall rules, analytics events, non-functional requirements, and version boundaries. Keep it lean, but make design/build-ready decisions visible.

Also decide design applicability. If the work touches UI, visual direction, brand/KV, screen states, or motion, mark design as required and hand off to design-flow. If the work has no user-facing UI or design is already complete and build-ready, record why design can be skipped or considered complete. When the decision changes lifecycle behavior, update .dev-agent/state/applicability.env instead of leaving build to guess.

Minimum PRD template:

# PRD: [Project/Feature Name]

## Objective

## Users And Jobs

## MVP Scope

## Core Flows / Information Architecture

## Acceptance Criteria

## Non-Goals

## Metrics / Guardrails

Spec template:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Data / Domain Model
[Entities, fields, invariants, persistence and sync-sensitive states]

## Interfaces / Integrations
[Public APIs, SDKs, permissions, auth providers, payments, background jobs]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## UI / Design Applicability
[Whether UI/design applies, whether formal HTML/CSS design packages are
required, and whether existing design resources are build-ready.]

## Privacy / Security
[Data handling, permissions, deletion, secrets, compliance-sensitive choices]

## Agent Runtime Contract
[Only when agent automation is in scope: job, tools/permissions, approval
points, prompts/skills/context, memory/checkpoints, evals, operations, and
failure recovery/escalation.]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.

Downstream: Design

For user-facing products, run design-flow before build. The design package should define information architecture, interaction model, platform/HCI requirements, and visual direction under <project-name>/.dev-agent/design/.

Skip this phase only for non-UI work or tiny changes with no user-facing behavior.

Do not write design files from this skill; hand off once SPEC.md is clear.

Downstream: Implement

Execute one build slice at a time with incremental-implementation. A separate tasks/PLAN.md is optional; use it only when the slice cannot be held clearly inside the spec and status ledger.

Keeping the Spec Alive

The spec is a living document, not a one-time artifact:

• Update when decisions change — If you discover the data model needs to change, update the spec first, then implement.
• Update when scope changes — Features added or cut should be reflected in the spec.
• Commit the spec — The spec belongs in version control alongside the code.
• Reference the spec in PRs — Link back to the spec section that each PR implements.

Common Rationalizations

Red Flags

• Starting to write code without any written requirements
• Asking "should I just start building?" before clarifying what "done" means
• Implementing features not mentioned in any spec or task list
• Making architectural decisions without documenting them
• Skipping the spec because "it's obvious what to build"

Verification

Before proceeding to implementation, confirm:

• [ ] product/PRD.md exists with MVP scope and acceptance criteria
• [ ] UI/customer-facing PRDs cover core flows or IA, acceptance criteria, and non-goals
• [ ] specs/SPEC.md covers all core technical areas
• [ ] UI/customer-facing specs cover stack, commands, data/domain model, testing, privacy/security, and open questions
• [ ] Specs decide whether UI/design applies and whether design assets/packages are required or already build-ready
• [ ] External references were converted into structured decisions and unsafe reference patterns were flagged
• [ ] The human has reviewed and approved the spec, or workspace instructions explicitly delegate defaults and no human review gate is open
• [ ] Success criteria are specific and testable
• [ ] Boundaries (Always/Ask First/Never) are defined
• [ ] The spec is saved under <project-name>/.dev-agent/specs/
• [ ] Project-specific app or source directories are under <project-name>/, not beside it