Documentation
The Specification Workflow
Overview

The Specification Workflow

SpecWright implements Specification-Driven Development through five sequential phases. Each phase is powered by a specialized AI agent that asks you focused questions, then generates structured output that feeds into the next phase.

The five phases

PhaseAI AgentWhat it produces
1. ScopingAI ClassifierDetermines if you need a full spec or can code directly
2. Product ManagerPM AgentPRD with job stories and acceptance criteria
3. DesignerUX AgentScreen inventory, wireframes, and user flows
4. EngineerEngineering AgentTechnical architecture and technology choices
5. Issue BreakdownBreakdown AgentImplementation tasks organized by vertical slice

Each phase builds on the previous one. The Product Manager's PRD informs the Designer's screens. The Designer's wireframes inform the Engineer's architecture. The Engineer's tech choices inform the Issue Breakdown.

How each phase works

Every phase (except Scoping) follows the same pattern:

  1. Questions — The AI agent generates focused questions tailored to your project. Each agent references your project description, your existing codebase, and outputs from previous phases to avoid generic or duplicate questions. The number of questions depends on your question depth setting (light: 2-3, standard: 3-4, thorough: 4-6 per agent).
  2. Your answers — You answer each question. The AI provides 2-3 suggested options, but you can write your own response. Your selection is recorded alongside the alternatives you rejected — both feed into the specification.
  3. Generation — The agent generates structured specification documents, with real-time streaming progress visible in the Web UI.
  4. Review — You review the output and can: approve (move to next phase), edit inline (Ctrl+Enter to save), or refine with AI (provide feedback text and reference images).

The question-and-answer approach ensures that specifications are grounded in your actual requirements — not generic templates. Each agent also analyzes your codebase, so questions and outputs reflect what you already have, not assumptions.

What you get at the end

After completing all five phases, you have a complete specification package:

specwright/outputs/projects/001-your-project/
├── project_request.md              # Your original description
├── documents/
│   ├── prd.md                      # Product Requirements Document
│   ├── acceptance_criteria.json    # Testable acceptance criteria
│   ├── design_brief.md             # UX specification
│   ├── screens.json                # Screen inventory
│   ├── technical_specification.md  # Architecture document
│   └── technology_choices.json     # Tech stack with rationale
└── issues/
    ├── issues.json                 # All implementation tasks
    ├── ENG-001.md                  # Individual issue files
    ├── ENG-002.md
    └── ...

These files are plain Markdown and JSON — version-controllable, human-readable, and designed to feed directly into AI coding tools.

Dive into each phase

Getting StartedSmart Scoping