SpecWright

AI-Powered Specification Engine

Transform ideas into implementation-ready specifications using an AI squad of specialists.

Installation • Quick Start • Features • Documentation • Contributing

🎯 What is SpecWright?

SpecWright implements Specification-Driven Development (SDD), a methodology where AI specialists collaborate to transform your project ideas into detailed, structured specifications before you write a single line of code.

The Problem

Starting a new project or feature often means:

• ❌ Writing code before understanding requirements
• ❌ Missing edge cases and user needs
• ❌ Inconsistent documentation
• ❌ Technical debt from rushed decisions

The Solution

SpecWright is a Web UI for Specification-Driven Development that automates the spec workflow for AI coding tools.

You can download the CLI here: https://www.npmjs.com/package/specwright

How it works:

• 🌐 Web interface for browsing and managing specifications
• 🤖 Automated prompts injected into your AI coding tool (Cursor, Windsurf, GitHub Copilot)
• 📋 Context-aware - automatically provides the right context at every step
• 🔄 Seamless handoff - specs flow directly into implementation

The AI Squad works through each phase:

📋 Product Manager → 🎨 Designer → 🔧 Engineer → 📊 Issue Breakdown

Each specialist creates structured outputs that feed into your AI coding assistant with the right prompts and context, ready for implementation.

📸 Interface Highlights

✨ Features

🚀 Installation

Prerequisites

• Node.js 18 or higher
• npm 9 or higher

Global Installation (Recommended)

# Install globally
npm install -g specwright

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

Local Development

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

⚡ Quick Start

1. Scope Your Work

specwright new

The AI analyzes your request and determines if you need:

• A full project specification, or
• Just implement directly (no spec needed)

2. Generate Specifications (For Projects)

specwright spec

The AI squad works through each phase:

1. Product Manager - Creates PRD with job stories
2. Designer - Designs screens and wireframes
3. Engineer - Selects technologies and architecture
4. Issue Breakdown - Breaks down into implementation tasks

3. Browse Your Projects

specwright view

Visual dashboard showing:

• All projects and their status
• Implementation tasks (issues)
• Progress tracking

📖 Documentation

🎨 Example Output

SpecWright generates structured, version-controllable specifications:

outputs/
├── project_plan.json              # Overall scope
└── 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

🛠️ Technology Stack

📊 Workflow

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]

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

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

# Run in development
npm run dev          # CLI
npm run dev:ui       # Web UI
npm run type-check   # Type checking

📝 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with ❤️ for Specification-Driven Development

Inspired By

SpecWright builds upon proven methodologies and tools:

• Jobs-to-be-Done Framework - Using job stories to capture user needs and context, focusing on the "why" behind features rather than just "what" users want.

• Shape Up - 37signals' approach to product development emphasizing:

  • Shaping work before committing to it
  • Making trade-offs explicit
  • Clear boundaries on No-Gos when writing specs

• Linear - The gold standard for issue tracking, inspiring our Project and Issues hierarchy of information:

  • Clean, fast interface design
  • Vertical slice organization

These frameworks inform SpecWright's AI-powered approach to specification-driven development.

📬 Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: julien@argil.io