SpecWright

Generate structured, implementation-ready specifications from a project idea — before you write a single line of code.

Quick Start · How It Works · Documentation · Contributing

SpecWright is a CLI + Web UI that runs AI specialists through a structured workflow — Product Manager, Designer, Engineer, Issue Breakdown — to produce PRDs, wireframes, architecture docs, and implementation tasks. The output is file-based, version-controllable, and designed to feed directly into AI coding tools like Cursor, Windsurf, and GitHub Copilot.

Quick Start

Prerequisites: Node.js 18+, npm 9+

npm install -g specwright

# Initialize in your project directory
cd /path/to/your/project
specwright init

# Scope your work — the AI determines if you need a full spec or can code directly
specwright new

# Generate specifications (if a full spec is needed)
specwright spec

# Browse projects and specs in a visual dashboard
specwright view

How It Works

SpecWright implements Specification-Driven Development: AI specialists collaborate in sequence, each phase producing structured outputs that feed into the next.

Screenshots

Project Dashboard

Browse all projects, view progress, and track implementation status.

Specification Viewer

Rich viewing for PRDs, screen designs, and technical specs.

Issue Breakdown

Implementation tasks organized by vertical slice with acceptance criteria.

Technology Choices

Selected technologies with rationale, trade-offs, and alternatives.

graph TD
    A[User Request] --> B[Scope Analysis]
    B --> C[Product Manager]
    C --> D[UX Designer]
    D --> E[Engineer]
    E --> F[Issue Breakdown]
    F --> G[Implementation]

| Phase | Specialist | Output | |-------|-----------|--------| | 1. Scope | AI classifier | Determines if you need a full spec or can implement directly | | 2. Product | Product Manager | PRD with job stories and acceptance criteria | | 3. Design | UX Designer | Screen inventory, wireframes, user flows | | 4. Architecture | Engineer | Technology choices, technical architecture | | 5. Breakdown | Tech Lead | Implementation tasks organized by vertical slice |

Each phase's output is injected as context into your AI coding tool, giving it the right prompts and specifications at every step.

Output Structure

Specs are saved as version-controllable files in your project:

outputs/
├── project_plan.json
└── projects/
    └── 001-user-authentication/
        ├── project_request.md
        ├── pm/
        │   └── product_manager_output.md    # PRD with job stories
        ├── ux/
        │   ├── screen_inventory.json
        │   └── ux_designer_output.md        # Wireframes
        ├── architect/
        │   ├── engineer_output.md           # Architecture
        │   └── technology_choices.json      # Tech stack
        └── tech_lead/
            ├── project_summary.json         # Task breakdown
            └── issues/
                ├── ENG-001.md               # Login UI
                ├── ENG-002.md               # JWT Auth
                └── ENG-003.md               # Password Reset

Documentation

| Document | Description | |----------|-------------| | QUICKSTART.md | Get started in 5 minutes | | ARCHITECTURE.md | Technical architecture and tech stack | | CONTRIBUTING.md | How to contribute | | CHANGELOG.md | Version history | | SECURITY.md | Security policy |

Contributing

Contributions welcome — see CONTRIBUTING.md for full guidelines.

git clone https://github.com/amelmo/specwright.git
cd specwright
npm install

npm run dev          # CLI in debug mode
npm run dev:ui       # Web UI with Vite HMR
npm run type-check   # TypeScript checking

Acknowledgments

SpecWright builds on ideas from Jobs-to-be-Done (job stories over feature lists), Shape Up (shaping work before committing), and Linear (clean issue hierarchy and vertical slices).

License

MIT — see LICENSE for details.

View on npm · Report an Issue · Discussions