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

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

The Solution

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

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

Project Dashboard

[Screenshot: Project overview with status cards]

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

Specification Viewer

[Screenshot: Specification document view]

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

Issue Breakdown

[Screenshot: Issue list with vertical slices]

Implementation tasks organized by vertical slice with clear acceptance criteria.

Technology Choices

[Screenshot: Technology selection interface]

Visual display of selected technologies with rationale and trade-offs.

✨ Features

🤖 AI Squad of Specialists

• Product Manager: Requirements, job stories, acceptance criteria
• UX Designer: Screen inventory, wireframes, user flows
• Engineer: Technical architecture, technology choices
• Issue Breakdown: Task breakdown using vertical slicing

🎯 Smart Scoping

Automatically classifies work:

• Work Directly: Small changes (just code it!)
• Single Project: One cohesive capability
• Multiple Projects: Break down large initiatives

🖥️ Dual Interface

• Terminal CLI: Fast, keyboard-driven workflow
• Web UI: Visual exploration and browsing
• Cursor Integration: Built-in commands

📚 Project Playbook

• Generate technical standards
• Audit compliance
• Track architectural evolution
• Version-controlled principles

🚀 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

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

🎨 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

| Category | Technologies | |----------|-------------| | Language | TypeScript 5.x | | Runtime | Node.js 18+ | | CLI | Inquirer, Chalk, Consola | | Web UI | React 18, Vite, TailwindCSS, Radix UI | | Build | TypeScript Compiler, Vite |

📊 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: [email protected]

⭐ Star us on GitHub • 📦 View on npm