From c5ae688ce7f8e1758aa27481050980d57a6611a6 Mon Sep 17 00:00:00 2001 From: AmElmo Date: Thu, 26 Feb 2026 13:11:19 +0700 Subject: [PATCH 1/2] docs(website): add concepts, troubleshooting, and changelog pages Add 4 new documentation pages: - Concepts: Specification-Driven Development (SDD methodology explanation) - Concepts: Vertical Slices (task structure explanation) - Troubleshooting (common issues and fixes) - Changelog (release history with links to GitHub) Update docs homepage and sidebar navigation to include the new sections. --- website/pages/docs/_meta.json | 5 +- website/pages/docs/changelog.mdx | 51 +++++++ website/pages/docs/concepts/_meta.json | 4 + .../specification-driven-development.mdx | 56 +++++++ .../pages/docs/concepts/vertical-slices.mdx | 59 ++++++++ website/pages/docs/index.mdx | 10 ++ website/pages/docs/troubleshooting.mdx | 139 ++++++++++++++++++ 7 files changed, 323 insertions(+), 1 deletion(-) create mode 100644 website/pages/docs/changelog.mdx create mode 100644 website/pages/docs/concepts/_meta.json create mode 100644 website/pages/docs/concepts/specification-driven-development.mdx create mode 100644 website/pages/docs/concepts/vertical-slices.mdx create mode 100644 website/pages/docs/troubleshooting.mdx diff --git a/website/pages/docs/_meta.json b/website/pages/docs/_meta.json index dc96deb..956ccc8 100644 --- a/website/pages/docs/_meta.json +++ b/website/pages/docs/_meta.json @@ -3,6 +3,9 @@ "getting-started": "Getting Started", "workflow": "The Specification Workflow", "guides": "Guides", + "concepts": "Concepts", "reference": "Reference", - "faq": "FAQ" + "troubleshooting": "Troubleshooting", + "faq": "FAQ", + "changelog": "Changelog" } diff --git a/website/pages/docs/changelog.mdx b/website/pages/docs/changelog.mdx new file mode 100644 index 0000000..44cff7e --- /dev/null +++ b/website/pages/docs/changelog.mdx @@ -0,0 +1,51 @@ +# Changelog + +Track what's new, fixed, and changed in each SpecWright release. + +import { Callout } from 'nextra/components' + +SpecWright uses [semantic versioning](https://semver.org/). Releases are published automatically when changes merge to `main`. + + +For the full release history with commit details, see the [GitHub Releases page](https://github.com/amelmo/specwright/releases) or the [CHANGELOG.md](https://github.com/amelmo/specwright/blob/main/CHANGELOG.md) file in the repository. + + +## 3.6.3 — February 25, 2026 + +- **Fix:** Enable demo fixture loading in dev mode + +## 3.6.0 — February 23, 2026 + +- **Feature:** Add analytics integration for the docs website +- **Fix:** Mobile horizontal overflow on the landing page + +## 3.5.0 — February 23, 2026 + +- **Feature:** Restructure workflow with unified questions and document-level approval — a major UX improvement to how you answer agent questions and review generated documents + +## 3.4.0 — February 16, 2026 + +- **Feature:** Add resizable sidebar and enhanced document review workflow in the Web UI + +## 3.3.0 — February 11, 2026 + +- **Feature:** Multi-AI tool routing — SpecWright now supports shipping to multiple AI coding tools from one setup + +## 3.2.0 — February 10, 2026 + +- **Feature:** Manual issue status changes with drag-and-drop on the issues board + +## 3.0.0 — December 11, 2024 + +Major release — complete TypeScript rewrite. + +- Complete TypeScript rewrite from JavaScript v2.0 +- Modern Web UI for scoping and browsing projects +- Project playbook generation and auditing +- Smart Scoping to classify work before specifying +- Linear integration for syncing projects and issues +- Five-phase specification workflow with specialized AI agents + +--- + +Want to stay up to date? Watch the [GitHub repository](https://github.com/amelmo/specwright) for release notifications. diff --git a/website/pages/docs/concepts/_meta.json b/website/pages/docs/concepts/_meta.json new file mode 100644 index 0000000..7fb27bd --- /dev/null +++ b/website/pages/docs/concepts/_meta.json @@ -0,0 +1,4 @@ +{ + "specification-driven-development": "Specification-Driven Development", + "vertical-slices": "Vertical Slices" +} diff --git a/website/pages/docs/concepts/specification-driven-development.mdx b/website/pages/docs/concepts/specification-driven-development.mdx new file mode 100644 index 0000000..3ff2350 --- /dev/null +++ b/website/pages/docs/concepts/specification-driven-development.mdx @@ -0,0 +1,56 @@ +# Specification-Driven Development + +Specification-Driven Development (SDD) is the methodology behind SpecWright. The idea is simple: describe what you want to build, generate a structured specification, then implement from the spec — not from a vague idea. + +## The problem SDD solves + +Most software projects start the same way: someone has an idea, writes a brief description, and developers start coding. Somewhere between the idea and the code, requirements get lost. Edge cases are discovered mid-sprint. Architecture decisions are made on the fly. Features ship incomplete because nobody wrote down what "complete" looks like. + +This problem gets worse with AI coding tools. Tools like Cursor, Claude Code, and Copilot are powerful — but they're only as good as the context you give them. A vague prompt produces vague code. A detailed, structured specification produces focused, correct implementation. + +## How SDD works + +SDD adds a structured thinking step between "I have an idea" and "Let's start coding": + +1. **Describe** — You state what you want to build in plain language +2. **Specify** — AI agents ask you targeted questions and generate structured documents: requirements, screen designs, architecture, and implementation tasks +3. **Implement** — You (or your AI coding tool) build from the spec, with clear acceptance criteria and technical context for every task + +The specification isn't a formality. It's the artifact that prevents the problems listed above. When a developer picks up an issue, they know exactly what to build, how it should behave, what screens it touches, and what technology to use. + +## Why AI agents ask you questions + +SpecWright doesn't generate specs from your description alone. Each AI agent — Product Manager, Designer, Engineer — asks 5-8 focused questions before producing output. This matters for two reasons: + +**You have context the AI doesn't.** You know your users, your business constraints, your technical environment, and your preferences. The questions extract this context so the specification reflects reality, not assumptions. + +**Questions force clarity.** When you're asked "What happens when a user tries to access a project they don't own?", you have to decide. That decision happens now, in the spec — not later, in a code review, when changing it costs more. + +## How SDD relates to existing methodologies + +SDD draws from established practices: + +- **Jobs-to-be-Done** — SpecWright uses job stories ("When [situation], I want [action], so [outcome]") instead of user stories. Job stories focus on the context and motivation behind a feature, which produces more specific requirements. +- **Shape Up** — The scoping phase determines whether work is small enough to just do, or large enough to need a full spec. This mirrors Shape Up's concept of shaping work before building it. +- **Vertical Slicing** — Issues are broken down as [vertical slices](/docs/concepts/vertical-slices) — self-contained pieces that deliver user-visible value through all layers of the stack. + +## When SDD is (and isn't) useful + +**SDD works well for:** +- New features with multiple moving parts (UI, API, database, integrations) +- Projects where multiple people need to understand the plan +- Work that will be handed to AI coding tools — structured specs produce dramatically better AI output +- Teams that want to version-control their decisions alongside their code + +**SDD is overkill for:** +- Bug fixes and one-line changes +- Simple configuration tweaks +- Work where the implementation is obvious + +SpecWright handles this distinction automatically through [Smart Scoping](/docs/workflow/scoping). If your request is too small for a full spec, it tells you to just start coding. + +## Learn more + +- [The Specification Workflow](/docs/workflow) — How the five phases work in practice +- [Vertical Slices](/docs/concepts/vertical-slices) — Why SpecWright structures tasks this way +- [Getting Started](/docs/getting-started) — Try SDD on your own project diff --git a/website/pages/docs/concepts/vertical-slices.mdx b/website/pages/docs/concepts/vertical-slices.mdx new file mode 100644 index 0000000..722400d --- /dev/null +++ b/website/pages/docs/concepts/vertical-slices.mdx @@ -0,0 +1,59 @@ +# Vertical Slices + +SpecWright breaks implementation work into vertical slices — self-contained tasks that deliver user-visible value through every layer of the stack. This page explains what that means and why it produces better results than the alternatives. + +## What a vertical slice is + +A vertical slice is a piece of work that cuts through all the layers needed to deliver a working feature — UI, API, database, business logic. When a developer finishes a vertical slice, something new works end-to-end. A user can see it, interact with it, or benefit from it. + +**Example — "Add a task to a project board":** + +A vertical slice for this feature includes: +- The UI button and form for adding a task +- The API endpoint that creates the task +- The database schema for storing tasks +- Validation logic for task fields +- The board updating to show the new task + +After this slice is done, users can add tasks. It's incomplete — they can't edit or delete tasks yet — but it works. + +## Vertical vs. horizontal slicing + +The alternative is horizontal slicing — dividing work by technical layer: + +| Horizontal (layer-by-layer) | Vertical (feature-by-feature) | +|---------------------------|-------------------------------| +| "Set up the database schema for tasks" | "Users can create a task on the board" | +| "Build the task API endpoints" | "Users can edit a task's title and status" | +| "Create the task UI components" | "Users can delete a task with confirmation" | +| "Wire up the frontend to the API" | "Users can drag tasks between columns" | + +With horizontal slicing, nothing works until every layer is connected. The database exists but nothing uses it. The API works but there's no UI. Bugs hide at the layer boundaries and surface late. + +With vertical slicing, each completed task is a working feature. Integration bugs surface immediately because every slice goes through all layers. Progress is visible — stakeholders can see and test what's done. + +## Why SpecWright uses vertical slices + +SpecWright generates issues as vertical slices because they're the best format for AI coding tools: + +**Clear scope.** Each issue describes a complete user-facing behavior. The AI tool knows exactly what "done" looks like — not just "build an API endpoint" but "users can create tasks, which appear on the board." + +**Testable in isolation.** Because each slice produces working functionality, you can verify it works before moving to the next slice. This catches problems early. + +**Ordered by dependency.** SpecWright sequences slices so each one builds on what came before. Slice 1 might be "users can view the board." Slice 2 is "users can add a task." The dependency chain is explicit. + +**Better AI output.** When you [ship an issue](/docs/guides/ship-to-ai-tools) to Cursor or Claude Code, the AI receives the full context for that slice: what to build, how it should behave, what screens it touches, and what technology to use. A well-scoped vertical slice produces focused, correct implementation. + +## How SpecWright structures slices + +During the [Issue Breakdown](/docs/workflow/issue-breakdown) phase, the Breakdown agent analyzes all previous specification documents — PRD, design brief, technical spec — and produces issues that are: + +- **Self-contained** — Each issue includes its own description, acceptance criteria, dependencies, and relevant specification context +- **Sequenced** — Issues are ordered by dependency so you work through them in the right order +- **Context-rich** — Each issue file (ENG-001.md, ENG-002.md, etc.) includes excerpts from the PRD, design brief, and tech spec relevant to that specific slice + +## Learn more + +- [Issue Breakdown](/docs/workflow/issue-breakdown) — How SpecWright generates vertical slices +- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — How slices become AI coding prompts +- [Specification-Driven Development](/docs/concepts/specification-driven-development) — The methodology behind the approach diff --git a/website/pages/docs/index.mdx b/website/pages/docs/index.mdx index f88bf60..15b21aa 100644 --- a/website/pages/docs/index.mdx +++ b/website/pages/docs/index.mdx @@ -21,3 +21,13 @@ import { Cards, Card } from 'nextra/components' - [The Specification Workflow](/docs/workflow) — Understand the 5-phase process from idea to tasks - [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send implementation tasks directly to Cursor, Claude Code, and more - [Output Files](/docs/reference/output-files) — What files SpecWright produces and where they live + +## Understand the approach + +- [Specification-Driven Development](/docs/concepts/specification-driven-development) — Why specs before code, and how SDD works +- [Vertical Slices](/docs/concepts/vertical-slices) — How SpecWright structures tasks for better implementation + +## Help & updates + +- [Troubleshooting](/docs/troubleshooting) — Common issues and how to fix them +- [Changelog](/docs/changelog) — What's new in each release diff --git a/website/pages/docs/troubleshooting.mdx b/website/pages/docs/troubleshooting.mdx new file mode 100644 index 0000000..113ee6e --- /dev/null +++ b/website/pages/docs/troubleshooting.mdx @@ -0,0 +1,139 @@ +# Troubleshooting + +Common issues and how to fix them. + +import { Callout } from 'nextra/components' + +## Installation + +**`npx specwright` fails with "command not found" or a module error** + +Make sure you're running Node.js 18 or later: + +```bash +node --version +``` + +If the version is below 18, upgrade Node.js. If you're using `nvm`: + +```bash +nvm install 18 +nvm use 18 +``` + +Then try again: + +```bash +npx specwright@latest +``` + +**`npm install -g specwright` fails with permission errors** + +On macOS and Linux, global installs sometimes need elevated permissions. Either fix your npm prefix: + +```bash +mkdir -p ~/.npm-global +npm config set prefix '~/.npm-global' +``` + +Then add `~/.npm-global/bin` to your PATH. Or use `npx specwright` instead of installing globally. + +## Web UI + +**Web UI doesn't open in the browser** + +SpecWright runs its web server on port 5174. If the browser doesn't open automatically: + +1. Check the terminal output for the URL — it should say something like `Server running at http://localhost:5174` +2. Open that URL manually in your browser +3. If the port is taken, check for other processes using it: + +```bash +lsof -i :5174 +``` + +**Web UI shows a blank page or loading spinner that never resolves** + +Try a hard refresh (`Cmd+Shift+R` on macOS, `Ctrl+Shift+R` on Windows/Linux) to clear cached assets. If that doesn't help, stop SpecWright and restart: + +```bash +specwright --ui +``` + +## Specification Generation + +**An AI agent phase is stuck or producing errors** + +If a phase fails during generation: + +1. Check that SpecWright can reach the AI service — make sure you're connected to the internet +2. Try regenerating the phase from the Web UI by clicking the regenerate button +3. If the error persists, enable debug logging to see more detail: + +```bash +SPECWRIGHT_DEBUG=true specwright --ui +``` + +**Phase output seems wrong or incomplete** + +The quality of generated specs depends heavily on your answers to the agent's questions. If output doesn't match your expectations: + +1. Review your answers — vague or short answers produce vague specs +2. Revisit the phase and provide more detailed answers +3. Regenerate the phase output + + +You can also edit the generated files directly. All outputs are plain Markdown and JSON in `specwright/outputs/`. The Web UI will reflect your changes on the next page load. + + +## File & Project Issues + +**"Project not found" when opening a project** + +This usually means the project's output files were moved or deleted. Check that the project directory still exists: + +```bash +ls specwright/outputs/projects/ +``` + +If you moved or renamed project directories, SpecWright won't find them. The project directory names must match the format `001-project-name/`. + +**Spec files are empty or corrupted** + +SpecWright uses atomic writes (temp file + rename) to prevent corruption. If a file is empty, the generation likely failed mid-write. Regenerate the affected phase from the Web UI. + +## Linear Integration + +**"Failed to connect" when setting up Linear** + +1. Verify your Linear API key is correct in Settings +2. Make sure the API key has the right scopes — SpecWright needs read/write access to issues and projects +3. Check that your network allows connections to `api.linear.app` + +**Issues don't appear in Linear after pushing** + +After pushing, give Linear a few seconds to process. If issues still don't appear: + +1. Check the terminal output for error messages +2. Verify you selected the correct Linear team and project in Settings +3. Try pushing a single issue to isolate the problem + +## Debug Mode + +For any issue not covered above, enable debug logging for detailed output: + +```bash +SPECWRIGHT_DEBUG=true specwright --ui +``` + +For even more detail (including trace-level logs): + +```bash +SPECWRIGHT_TRACE=true specwright --ui +``` + +The debug output will show API calls, file operations, and agent interactions — which helps narrow down where things go wrong. + +--- + +Still stuck? [Open an issue on GitHub](https://github.com/amelmo/specwright/issues) with the error message and debug output. From 861514aaac7d9a560ad4d6a010224c45eaeb80bd Mon Sep 17 00:00:00 2001 From: AmElmo Date: Thu, 26 Feb 2026 13:31:07 +0700 Subject: [PATCH 2/2] docs(website): comprehensive documentation rewrite from source-level analysis Rewrote nearly every documentation page based on deep analysis of the actual source code (CLI, Web UI, AI agents, API/integrations). Key changes: - CLI reference: added approve, finalize-scope, break commands, --trace flag - Output files: added full JSON schemas for all file formats - Settings reference: new page covering all configurable options - All 5 workflow pages: rewritten with actual agent behavior, question depth settings, decision tracking, review options - Web UI guide: rewritten covering every screen and interaction - Ship to AI Tools: added headless vs keyboard automation, prompt structure - Linear integration: added 6-step sync flow, estimation mapping - Concepts pages: enhanced with complexity scoring, testing philosophy - Troubleshooting: rewritten with actual error messages and solutions - Playbooks & customizing-agents: enhanced with specific details - Getting started: updated with init details, playbook prompt, review options 20 files changed (+1,499 / -425 lines), website builds successfully (24 pages). --- .../specification-driven-development.mdx | 6 +- .../pages/docs/concepts/vertical-slices.mdx | 3 +- website/pages/docs/faq.mdx | 6 +- website/pages/docs/getting-started.mdx | 67 ++- .../pages/docs/guides/customizing-agents.mdx | 95 ++-- .../pages/docs/guides/linear-integration.mdx | 86 +++- website/pages/docs/guides/playbooks.mdx | 69 ++- .../pages/docs/guides/ship-to-ai-tools.mdx | 101 ++-- website/pages/docs/guides/web-ui.mdx | 180 +++++-- website/pages/docs/reference/_meta.json | 3 +- website/pages/docs/reference/cli.mdx | 159 ++++-- website/pages/docs/reference/output-files.mdx | 459 ++++++++++++++++-- website/pages/docs/reference/settings.mdx | 100 ++++ website/pages/docs/troubleshooting.mdx | 135 ++++-- website/pages/docs/workflow/designer.mdx | 111 ++++- website/pages/docs/workflow/engineer.mdx | 113 +++-- website/pages/docs/workflow/index.mdx | 10 +- .../pages/docs/workflow/issue-breakdown.mdx | 123 ++++- .../pages/docs/workflow/product-manager.mdx | 127 +++-- website/pages/docs/workflow/scoping.mdx | 71 +-- 20 files changed, 1599 insertions(+), 425 deletions(-) create mode 100644 website/pages/docs/reference/settings.mdx diff --git a/website/pages/docs/concepts/specification-driven-development.mdx b/website/pages/docs/concepts/specification-driven-development.mdx index 3ff2350..d4a21f8 100644 --- a/website/pages/docs/concepts/specification-driven-development.mdx +++ b/website/pages/docs/concepts/specification-driven-development.mdx @@ -20,11 +20,11 @@ The specification isn't a formality. It's the artifact that prevents the problem ## Why AI agents ask you questions -SpecWright doesn't generate specs from your description alone. Each AI agent — Product Manager, Designer, Engineer — asks 5-8 focused questions before producing output. This matters for two reasons: +SpecWright doesn't generate specs from your description alone. Each AI agent — Product Manager, Designer, Engineer — asks focused questions before producing output. You control the depth: light (2-3 questions per agent), standard (3-4), or thorough (4-6). This matters for two reasons: -**You have context the AI doesn't.** You know your users, your business constraints, your technical environment, and your preferences. The questions extract this context so the specification reflects reality, not assumptions. +**You have context the AI doesn't.** You know your users, your business constraints, your technical environment, and your preferences. The questions extract this context so the specification reflects reality, not assumptions. Each agent also analyzes your existing codebase — so questions are grounded in what you already have, not generic templates. -**Questions force clarity.** When you're asked "What happens when a user tries to access a project they don't own?", you have to decide. That decision happens now, in the spec — not later, in a code review, when changing it costs more. +**Questions force clarity.** When you're asked "What authentication methods should be supported?", you have to decide. That decision is recorded along with the alternatives you rejected — and both feed into the specification. Your rejected alternatives become documented NoGos (scope exclusions), preventing scope creep later. The decision happens now, in the spec — not later, in a code review, when changing it costs more. ## How SDD relates to existing methodologies diff --git a/website/pages/docs/concepts/vertical-slices.mdx b/website/pages/docs/concepts/vertical-slices.mdx index 722400d..c519e52 100644 --- a/website/pages/docs/concepts/vertical-slices.mdx +++ b/website/pages/docs/concepts/vertical-slices.mdx @@ -50,7 +50,8 @@ During the [Issue Breakdown](/docs/workflow/issue-breakdown) phase, the Breakdow - **Self-contained** — Each issue includes its own description, acceptance criteria, dependencies, and relevant specification context - **Sequenced** — Issues are ordered by dependency so you work through them in the right order -- **Context-rich** — Each issue file (ENG-001.md, ENG-002.md, etc.) includes excerpts from the PRD, design brief, and tech spec relevant to that specific slice +- **Complexity-scored** — Each issue gets a 1-10 score mapped to estimated hours. Issues scoring 7+ are split into subtasks organized by technical layer within the vertical slice (backend, frontend, database, testing). +- **Tested by humans** — Every issue includes manual verification steps and human-in-the-loop checks, even when automated tests are skipped. The agent follows a critical-only testing philosophy: automated tests for payments, auth, and security; manual verification for everything else. ## Learn more diff --git a/website/pages/docs/faq.mdx b/website/pages/docs/faq.mdx index 683f76f..c7e137e 100644 --- a/website/pages/docs/faq.mdx +++ b/website/pages/docs/faq.mdx @@ -8,15 +8,15 @@ No. SpecWright works with whatever AI coding tool you already have installed — **What AI coding tools does SpecWright support?** -SpecWright works with Cursor, Claude Code, GitHub Copilot, Codex, Gemini CLI, and Windsurf. You select your preferred tool during onboarding, and can change it anytime in Settings. +SpecWright works with Cursor, Claude Code, GitHub Copilot, Codex, Gemini CLI, and Windsurf. Cursor, Claude Code, Codex, and Gemini support headless execution (direct CLI integration with real-time streaming). GitHub Copilot and Windsurf use keyboard automation. You select your preferred tool during onboarding, and can change it anytime in [Settings](/docs/reference/settings). **Can I use SpecWright without the Web UI?** -Yes. SpecWright has both a CLI and a Web UI. The CLI can run the full specification workflow interactively in your terminal with `specwright spec`. The Web UI provides a visual dashboard with `specwright --ui`. Both produce the same output files. +Yes. SpecWright has both a CLI and a Web UI. Most commands (like `specwright new`, `specwright ship`, `specwright view`) launch the Web UI for the visual workflow, but `specwright approve` works entirely in the terminal. The `specwright init` and `specwright finalize-scope` commands are also CLI-only. See [CLI Commands](/docs/reference/cli) for all available commands. **What does "Specification-Driven Development" mean?** -SDD is a methodology where you create a structured specification before writing any code. Instead of jumping straight from an idea to implementation, SpecWright walks you through requirements, design, architecture, and task breakdown — so you (and your AI coding tool) know exactly what to build. +SDD is a methodology where you create a structured specification before writing any code. Instead of jumping straight from an idea to implementation, SpecWright walks you through requirements, design, architecture, and task breakdown — so you (and your AI coding tool) know exactly what to build. See [Specification-Driven Development](/docs/concepts/specification-driven-development) for the full explanation. ## The Workflow diff --git a/website/pages/docs/getting-started.mdx b/website/pages/docs/getting-started.mdx index 4430ebb..96ba456 100644 --- a/website/pages/docs/getting-started.mdx +++ b/website/pages/docs/getting-started.mdx @@ -41,47 +41,80 @@ cd /path/to/your/project specwright init ``` -This creates the `specwright/` folder with templates, agent prompts, and an outputs directory. All your specifications will live here. +This creates the `specwright/` folder with: +- `agents/` — AI agent prompts (PM, Designer, Engineer, Breakdown) +- `templates/` — Output format templates +- `outputs/` — Where generated specifications live + +It also creates `.cursor/commands/` at your project root with custom Cursor commands. + +After creating files, SpecWright asks if you want to generate a [Playbook](/docs/guides/playbooks) — a set of standards from your existing codebase. ### Launch the Web UI ```bash -specwright --ui +specwright view ``` -This opens the SpecWright dashboard in your browser. You'll see the onboarding screen on your first run, which walks you through selecting your preferred AI coding tool. +This starts the server on port 5174 and opens the dashboard. On your first run, you'll see the onboarding screen, which walks you through: +1. Selecting your preferred AI coding tool (Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, or Windsurf) +2. A quick intro to the workflow and AI squad +3. Completing initialization + ### Create a new project -Click **New Project** and describe what you want to build in plain language. For example: +Click **New Project**. You have two options: + +**AI-assisted mode (default)** — Describe what you want to build in plain language: > "Build a task management app with user authentication, project boards, and real-time collaboration" -SpecWright's AI will analyze your request and determine if it needs a full specification or is small enough to implement directly. This is called [Smart Scoping](/docs/workflow/scoping). +SpecWright classifies your request via [Smart Scoping](/docs/workflow/scoping) — it determines if this needs a full spec, is small enough to implement directly, or should be split into multiple projects. + +**Manual mode** — Enter a project name and description directly if you already know the scope. ### Walk through the specification phases If your request needs a full spec, SpecWright guides you through four phases — each powered by a specialized AI agent: 1. **Product Manager** — Asks questions about requirements, then generates a PRD with job stories and acceptance criteria -2. **Designer** — Asks about UX needs, then produces screen definitions and user flows -3. **Engineer** — Asks about technical constraints, then creates architecture docs and technology choices -4. **Issue Breakdown** — Analyzes all specs and breaks the work into implementation tasks - -At each phase, you answer a set of focused questions. The AI uses your answers to generate structured specification documents. +2. **Designer** — Asks about UX needs, then produces screen definitions, wireframes, and user flows +3. **Engineer** — Asks about technical constraints, then creates architecture docs and technology choices for you to select from +4. **Issue Breakdown** — Analyzes all specs and breaks the work into vertical-slice implementation tasks -### Review your outputs +At each phase, you answer focused questions (the number depends on your [question depth](/docs/reference/settings) setting). The AI uses your answers to generate structured specification documents. You review each document — approve it, edit inline, or refine with AI feedback. -Once all phases are complete, you'll have a full set of specifications in your `specwright/outputs/` directory: +### Ship to your AI tool -- A PRD with job stories and acceptance criteria -- Screen designs and user flows -- Technical architecture and technology choices -- Implementation tasks ready for your AI coding tool +Once issues are generated, click **Ship** on any issue. SpecWright sends a prompt to your AI coding tool with the full specification context — requirements, design decisions, architecture, acceptance criteria, and testing strategy. See [Ship to AI Tools](/docs/guides/ship-to-ai-tools). +## Your outputs + +After completing the workflow, your `specwright/outputs/` directory contains: + +``` +specwright/outputs/projects/001-your-project/ +├── project_request.md # Your original description +├── project_status.json # Phase tracking +├── questions/ # Agent questions & your answers +├── documents/ +│ ├── prd.md # Product Requirements Document +│ ├── acceptance_criteria.json # Testable criteria (Given/When/Then) +│ ├── design_brief.md # UX specification +│ ├── screens.json # Screen inventory with components +│ ├── technical_specification.md # Architecture document +│ └── technology_choices.json # Tech decisions with trade-offs +└── issues/ + └── issues.json # Implementation tasks +``` + +All files are plain Markdown and JSON — commit them to Git alongside your source code. + ## What's next? - [The Specification Workflow](/docs/workflow) — Understand each phase in detail -- [Using the Web UI](/docs/guides/web-ui) — Navigate the dashboard +- [Using the Web UI](/docs/guides/web-ui) — Navigate every screen in the dashboard - [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send tasks directly to Cursor, Claude Code, or other tools +- [Settings Reference](/docs/reference/settings) — Configure question depth, document length, and more diff --git a/website/pages/docs/guides/customizing-agents.mdx b/website/pages/docs/guides/customizing-agents.mdx index 26b09b2..321417f 100644 --- a/website/pages/docs/guides/customizing-agents.mdx +++ b/website/pages/docs/guides/customizing-agents.mdx @@ -1,59 +1,100 @@ # Customizing AI Agents -SpecWright's AI agents (Product Manager, Designer, Engineer) are driven by prompt templates stored in your project's `specwright/agents/` directory. You can customize these prompts to change how the agents ask questions and generate specifications. +SpecWright's AI agents are driven by prompt templates stored in your project's `specwright/agents/` directory. You can customize these prompts to change how agents ask questions, generate documents, and structure their output. + +import { Callout } from 'nextra/components' + + +Editing agent prompts is advanced customization. The default prompts work well for most projects. Only modify them if you have specific requirements the defaults don't cover. + ## Agent prompt structure -Each agent has several prompt files: +Each agent has specialized prompt files that control different behaviors: ``` specwright/agents/ ├── product_manager/ -│ ├── system_prompt.md # Agent identity and role -│ ├── questioning_prompt.md # How to generate questions -│ └── analysis_prompt.md # How to generate the PRD +│ ├── system_prompt.md # Agent persona and role definition +│ ├── questioning_prompt.md # How to generate strategic questions +│ └── analysis_prompt.md # How to generate the PRD and acceptance criteria ├── ux_designer/ -│ ├── system_prompt.md -│ ├── questioning_prompt.md -│ └── analysis_prompt.md +│ ├── system_prompt.md # Designer persona and design principles +│ ├── questioning_prompt.md # How to generate UX-focused questions +│ └── analysis_prompt.md # How to generate design brief and screens.json ├── engineer/ -│ ├── system_prompt.md -│ ├── questioning_prompt.md -│ ├── choice_selection_prompt.md # Technology selection logic -│ └── analysis_prompt.md +│ ├── system_prompt.md # Engineer persona and architecture expertise +│ ├── questioning_prompt.md # How to generate constraint questions +│ ├── choice_selection_prompt.md # Technology evaluation and selection logic +│ └── analysis_prompt.md # How to generate tech spec and technology_choices.json └── breakdown/ - ├── system_prompt.md - └── issue_breakdown_prompt.md + ├── system_prompt.md # Tech Lead persona and vertical slicing principles + └── issue_breakdown_prompt.md # How to create implementation tasks ``` +### What each prompt type does + +**System prompts** define the agent's identity — its role, expertise, years of experience, and core principles. The PM agent defaults to a "Senior Product Manager with 10+ years experience." The Engineer defaults to "15+ years." These shape the agent's perspective on everything it generates. + +**Questioning prompts** control how questions are generated. They specify what categories to cover, how many questions to ask, and how to structure answer options. They also tell the agent to reference previous phase outputs to avoid duplicate questions. + +**Analysis prompts** control document generation. They define what sections to include, output format (Markdown vs JSON), quality standards, and length constraints. They also specify what context to read (project request, answered questions, previous documents). + +**Templates** in `specwright/templates/` define the JSON structure for output files like `issues.json`, `screens.json`, and `technology_choices.json`. The AI pre-creates these templates, then fills them in. + ## What you can customize -- **System prompts** — Change the agent's persona, expertise areas, or focus -- **Questioning prompts** — Adjust what kinds of questions the agent asks -- **Analysis prompts** — Modify how the agent generates specification documents -- **Templates** — Edit output templates in `specwright/templates/` to change document structure +### Agent personas -import { Callout } from 'nextra/components' +Change who the agent pretends to be. For example, making the PM agent focus on B2B enterprise software: - -Editing agent prompts is advanced customization. The default prompts work well for most projects. Only modify them if you have specific requirements the defaults don't cover. - +```markdown +# In product_manager/system_prompt.md +You are a Senior Enterprise Product Manager specializing in B2B SaaS platforms +with expertise in compliance, security, and multi-tenant architectures... +``` + +### Question focus + +Adjust what kinds of questions each agent asks. For a healthcare project, you might add compliance-focused question categories to the PM's questioning prompt. + +### Output structure + +Modify analysis prompts to change what sections appear in generated documents. Add sections, remove irrelevant ones, or change the expected format. + +### Breakdown behavior + +The breakdown agent's `issue_breakdown_prompt.md` controls how issues are structured — vertical slice definitions, complexity scoring, testing philosophy. You could adjust the complexity thresholds or change how dependencies are assigned. ## Example: adding industry context -If you're building for a specific industry (healthcare, fintech, etc.), you can add domain context to the system prompts. For example, adding compliance requirements to the PM agent's system prompt ensures the PRD includes regulatory considerations. +If you're building for a regulated industry, add domain context to the system prompts: + +```markdown +# In product_manager/system_prompt.md (append to existing) + +## Industry Context +This project operates in the healthcare sector. All specifications must account for: +- HIPAA compliance requirements +- PHI (Protected Health Information) handling +- Audit logging for data access +- BAA (Business Associate Agreement) implications +``` + +This ensures every document generated by the PM agent considers healthcare regulations. ## Resetting to defaults -If your customizations cause issues, you can regenerate the default prompts by running: +If your customizations cause issues, restore the original prompts: ```bash specwright init ``` -This restores the original agent prompts without affecting your existing outputs. +This copies the default agent prompts back to `specwright/agents/` without affecting your existing outputs in `specwright/outputs/`. ## What's next? -- [Playbooks](/docs/guides/playbooks) — Let SpecWright learn your project conventions automatically -- [The Specification Workflow](/docs/workflow) — Understand how agents work at each phase +- [Playbooks](/docs/guides/playbooks) — Automatic codebase-aware context (no manual customization needed) +- [The Specification Workflow](/docs/workflow) — How agents work at each phase +- [Output Files](/docs/reference/output-files) — File formats that agents produce diff --git a/website/pages/docs/guides/linear-integration.mdx b/website/pages/docs/guides/linear-integration.mdx index 6bebe36..c5da678 100644 --- a/website/pages/docs/guides/linear-integration.mdx +++ b/website/pages/docs/guides/linear-integration.mdx @@ -2,41 +2,93 @@ SpecWright integrates with [Linear](https://linear.app) to sync your projects and issues. Push specification-backed tasks directly to your Linear workspace so your team can track implementation alongside your existing workflow. -## What the integration does +import { Callout, Steps } from 'nextra/components' -- **Push projects** — Create a Linear project from your SpecWright project -- **Push issues** — Send implementation tasks to Linear with full context -- **Attach specifications** — Link SpecWright documents (PRD, tech spec, etc.) to Linear issues +## What gets synced -## Setting up the connection +When you push a SpecWright project to Linear, the full specification package is synced: -import { Steps } from 'nextra/components' +- **Project** — Created in your Linear team with name and description +- **Specification documents** — PRD, Design Brief, and Technical Specification attached as Linear documents +- **Issues** — All implementation tasks created as Linear issues with full context +- **Dependencies** — Blocking relationships between issues are set up in Linear +- **External links** — A "SpecWright Resources" document with links to Screen Designs, Technology Choices, Acceptance Criteria, and the full project overview + +## Setting up ### Open Settings -Launch the Web UI (`specwright --ui`) and navigate to **Settings** from the sidebar. +Launch the Web UI (`specwright view`) and navigate to **Settings** from the sidebar. + +### Enter your Linear API key -### Connect Linear +In the Linear section, enter your personal API key. You can generate one from [Linear Settings → API](https://linear.app/settings/api). -In the **Integrations** section, click **Connect Linear**. You'll be asked to provide your Linear API key. + +SpecWright validates your API key before saving. The key needs read/write access to issues, projects, and documents. + -### Select your workspace and team +### Select your team -Choose which Linear workspace and team should receive your SpecWright projects and issues. +After validation, SpecWright fetches your available Linear teams. Select the team that should receive your projects and issues. -## Pushing projects and issues -Once connected, you'll see Linear sync options on each project: +## The sync process + +When you click "Sync to Linear" on a project, SpecWright executes a 6-step sync: + +1. **Create Linear project** — A project in your selected team with the SpecWright project name and description +2. **Sync PRD** — Attaches the Product Requirements Document as a Linear document +3. **Sync Design Brief** — Attaches the design specification as a Linear document +4. **Sync Technical Specification** — Attaches the architecture document as a Linear document +5. **Create issues** — Creates a Linear issue for each SpecWright issue with full context +6. **Set up dependencies** — Creates blocking relationships between issues that match SpecWright's dependency chain + +### What issues look like in Linear + +Each synced issue includes: + +- **Title** — The issue title from SpecWright +- **Description** — Rich Markdown with all fields: key decisions, acceptance criteria, technical details, testing strategy, dependencies +- **Priority** — Mapped from estimated hours (default: Normal) +- **Estimate** — Fibonacci story points derived from estimated hours: + +| Estimated hours | Story points | +|----------------|-------------| +| 1-2h | 1 | +| 2-4h | 2 | +| 4-6h | 3 | +| 6-10h | 5 | +| 10-16h | 8 | +| 16-24h | 13 | +| 24h+ | 21 | + +### External links + +SpecWright creates a "SpecWright Resources" attachment on the Linear project with links to: + +- Screen Designs (visual wireframes in the Web UI) +- Technology Choices (decision matrix in the Web UI) +- Acceptance Criteria (testable criteria viewer) +- Full Project Overview (complete project in the Web UI) + +These are localhost links (`http://localhost:5174/...`) — they work when SpecWright is running locally. + +## Sync state tracking + +After syncing, SpecWright saves a `linear_sync.json` file in the project directory. This tracks: -- **Push Project** — Creates a project in Linear matching your SpecWright project -- **Push Issues** — Sends individual implementation tasks to Linear with their descriptions, acceptance criteria, and spec context +- When the sync happened +- The Linear project ID and URL +- Mappings between SpecWright issue IDs and Linear issue IDs +- Mappings between SpecWright documents and Linear document IDs -Issues pushed to Linear include all the context from your specification workflow, so your team has full visibility into requirements and technical decisions. +This prevents duplicate syncs and enables future re-sync capabilities. ## What's next? - [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send issues to your AI coding tool -- [Output Files](/docs/reference/output-files) — Understand what files SpecWright produces +- [Output Files](/docs/reference/output-files) — Understand the `linear_sync.json` format diff --git a/website/pages/docs/guides/playbooks.mdx b/website/pages/docs/guides/playbooks.mdx index 3fcd370..b8769b9 100644 --- a/website/pages/docs/guides/playbooks.mdx +++ b/website/pages/docs/guides/playbooks.mdx @@ -2,23 +2,25 @@ A Playbook is a set of project standards and conventions that SpecWright generates by analyzing your existing codebase. Once created, the AI agents reference it during specification generation — so your specs follow your team's actual patterns, not generic defaults. +import { Callout, Steps } from 'nextra/components' + ## What a Playbook contains -The generated `PLAYBOOK.md` typically includes: +The generated `PLAYBOOK.md` captures: -- **Project structure** — How your codebase is organized (folder structure, naming conventions) -- **Code patterns** — Common patterns used in your project (state management, error handling, etc.) -- **Technology stack** — What frameworks and libraries are already in use -- **Development standards** — Formatting, linting, testing conventions -- **Architecture decisions** — Key patterns like API structure, data flow, etc. +- **Project structure** — Folder organization, naming conventions, file patterns +- **Code patterns** — State management approach, error handling patterns, component structure +- **Technology stack** — Frameworks, libraries, and versions already in use +- **Development standards** — Formatting rules, linting configuration, testing conventions +- **Architecture decisions** — API structure, data flow, authentication patterns, deployment setup -## Generating a Playbook +The Playbook includes version information and a last-amended date so you can track when it was generated or updated. -import { Steps } from 'nextra/components' +## Generating a Playbook -### Open the Playbook section +### Open the Playbook page In the Web UI, navigate to **Playbook** from the sidebar. Or from the CLI: @@ -28,27 +30,56 @@ specwright playbook ### Generate from your codebase -Click **Generate Playbook**. SpecWright analyzes your project's file structure, dependencies, and code patterns to produce a `PLAYBOOK.md` tailored to your project. +Click **Generate Playbook**. SpecWright sends a codebase analysis prompt to your AI tool, which scans your project's file structure, dependencies, configuration files, and code patterns. A streaming progress log shows the analysis in real time. -### Review and refine +### Review and edit -The generated Playbook is a Markdown file you can review and edit. Remove anything that doesn't apply, and add any standards the AI may have missed. +The generated Playbook is rendered as Markdown in the Web UI. Review the output and edit inline if anything is inaccurate or missing. ## How Playbooks improve specifications -When a Playbook exists, the AI agents use it as additional context during specification generation. For example: +When a Playbook exists, the AI agents use it as additional context during specification generation: + +- **PM agent** — Understands existing capabilities and patterns to ask better questions +- **Engineer agent** — Recommends technologies consistent with your existing stack, avoids suggesting tools that conflict with what you already use +- **Issue Breakdown** — References your folder structure and naming conventions in task descriptions, accounts for existing components and patterns +- **Shipped prompts** — Playbook standards are included when you [ship to AI tools](/docs/guides/ship-to-ai-tools), so the implementing AI follows your conventions + +## Updating a Playbook -- The **Engineer** agent will recommend technologies consistent with your existing stack -- The **Issue Breakdown** will reference your folder structure and naming conventions in task descriptions -- Shipped prompts will include Playbook standards, so your AI coding tool follows your conventions +Your codebase evolves. To keep the Playbook in sync: + +1. Navigate to the Playbook page +2. Click **Update Playbook** +3. SpecWright re-analyzes your codebase and regenerates the Playbook + +Or from the CLI: + +```bash +specwright playbook --update +``` + +The update captures new patterns, dependencies, and structural changes since the last generation. ## Auditing against your Playbook -SpecWright can also audit generated specifications against your Playbook to check for inconsistencies — for example, if the tech spec recommends a state management library that conflicts with your existing setup. +SpecWright can audit generated specifications against your Playbook to check for inconsistencies. For example: + +- The tech spec recommends a state management library that conflicts with your existing setup +- The design brief uses component patterns that don't match your component library +- Issues reference folder structures that don't exist in your project + +To run an audit, click **Audit** on the Playbook page, or: + +```bash +specwright playbook --audit +``` + +The audit output highlights any conflicts between your specifications and your established standards. ## What's next? -- [Customizing AI Agents](/docs/guides/customizing-agents) — Fine-tune how the AI agents behave -- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send tasks to your AI coding tool with Playbook context included +- [Customizing AI Agents](/docs/guides/customizing-agents) — Fine-tune agent behavior beyond Playbooks +- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — See how Playbook context is included in prompts diff --git a/website/pages/docs/guides/ship-to-ai-tools.mdx b/website/pages/docs/guides/ship-to-ai-tools.mdx index 9da0269..74783e5 100644 --- a/website/pages/docs/guides/ship-to-ai-tools.mdx +++ b/website/pages/docs/guides/ship-to-ai-tools.mdx @@ -1,19 +1,6 @@ # Ship to AI Tools -Once SpecWright generates your implementation tasks, you can send them directly to your AI coding tool with a single click. No manual copy-pasting, no context switching. - -## Supported AI tools - -SpecWright works with these AI coding tools: - -| Tool | How shipping works | -|------|-------------------| -| **Cursor** | Opens Cursor, creates a new chat, and pastes the issue prompt | -| **Claude Code** | Opens a terminal session with the full issue context | -| **GitHub Copilot** | Opens Copilot chat with the issue prompt | -| **Codex** | Runs headless in the CLI with the issue context | -| **Gemini CLI** | Runs headless in the CLI with the issue context | -| **Windsurf** | Opens Windsurf with the issue prompt | +Once SpecWright generates your implementation tasks, you can send them directly to your AI coding tool. Each shipped prompt includes the full specification context — requirements, design decisions, architecture, acceptance criteria — so the AI tool knows exactly what to build. import { Callout } from 'nextra/components' @@ -21,46 +8,90 @@ import { Callout } from 'nextra/components' **No API keys required.** SpecWright doesn't call AI APIs directly. It works with whatever AI tool you already have installed and licensed. -## How it works +## Supported tools + +| Tool | Execution mode | How it works | +|------|---------------|-------------| +| **Cursor** | Headless | Runs via CLI — streams progress in real time | +| **Claude Code** | Headless | Runs via CLI with session resumption — can continue where it left off | +| **Codex CLI** | Headless | CLI-only execution, no IDE needed | +| **Gemini CLI** | Headless | CLI-only execution, no IDE needed | +| **GitHub Copilot** | Keyboard automation | Opens VS Code chat, pastes the prompt | +| **Windsurf** | Keyboard automation | Opens Windsurf chat, pastes the prompt | -1. Open a project in the Web UI and navigate to the **Issues** view -2. Click the **Ship** button on any issue -3. SpecWright automatically: - - Opens your selected AI coding tool - - Creates a new chat or session - - Pastes a prompt with the full issue context — including relevant excerpts from the PRD, design brief, and tech spec -The prompt includes everything the AI coding tool needs to implement the task: what to build, how it should behave, what technology to use, and what "done" looks like. +**Headless mode** is the preferred execution method. SpecWright runs the AI tool's CLI directly, streams progress logs to the Web UI in real time, and captures results automatically. The process has a 5-minute timeout for safety. -## Selecting your AI tool +**Keyboard automation** is the fallback for tools without CLI/headless support. SpecWright copies the prompt to your clipboard, activates the tool's window, opens a new chat, and pastes. The tool needs to be running already. -Set your preferred tool during onboarding, or change it anytime: +## How to ship an issue -1. Open the Web UI (`specwright --ui`) -2. Go to **Settings** -3. Under **AI Tool**, select your preferred tool +1. Open a project and navigate to the **Issues** view (or the global Issues board) +2. Click an issue to open its detail modal +3. Click **Ship** +4. The Ship Modal opens and: + - Generates the full implementation prompt + - Sends it to your selected AI tool + - Shows streaming progress logs (for headless tools) + - Reports success or failure -## What makes the prompts effective +You can override the AI tool for a single ship action using the dropdown in the Ship Modal — useful if you want to try a different tool for one specific issue. + +## What the prompt contains Each shipped prompt includes: -- **Issue description** — What to build -- **Acceptance criteria** — What "done" looks like -- **Relevant spec excerpts** — Architecture decisions, screen definitions, and requirements from earlier phases -- **Project context** — Playbook standards and conventions if configured +**Issue context:** +- Title and description +- Screens affected (from `screens.json`) +- Key architecture decisions (from technology choices) +- Acceptance criteria with IDs and descriptions +- Technical implementation details +- Testing strategy (automated tests + manual verification steps) +- Human-in-the-loop verification steps +- Dependencies on other issues + +**Specification references:** +- Links to the PRD (`@path/to/prd.md`) +- Links to the technical specification +- Links to technology choices +- Links to the design brief and wireframes + +**Git workflow (if enabled):** +- Branch creation instructions based on your [git strategy](/docs/reference/settings) +- Commit message format +- Merge instructions -This means your AI coding tool doesn't start from scratch. It has the full context of your project's requirements, design decisions, and technical architecture. +**Status update instructions:** +- Tells the AI tool to update the issue status from "pending" to "in-review" in `issues.json` when work begins + +## Refinement + +After shipping, if the result isn't right, you can refine the AI's output using the Refinement Panel: + +1. Open the document or issue in the Web UI +2. Click the refinement panel +3. Type feedback explaining what to change +4. Optionally upload up to 5 reference images (mockups, screenshots, design examples) +5. Submit — the AI revises based on your feedback with streaming progress + +For Claude Code, SpecWright supports **session resumption** — it can continue the same session rather than starting fresh, which preserves context from the previous generation. ## CLI shipping -You can also ship issues from the command line: +You can also ship from the command line: ```bash specwright ship ``` -This is especially useful for headless tools like Codex and Gemini CLI. +This opens the issues board in the Web UI where you can ship any issue. For headless tools (Codex, Gemini CLI), this is the primary workflow. + +## Playbook context + +If you've generated a [Playbook](/docs/guides/playbooks), its standards are automatically included in shipped prompts. This means the AI tool follows your project's naming conventions, folder structure, code patterns, and architectural decisions. ## What's next? - [Using the Web UI](/docs/guides/web-ui) — Navigate the full dashboard +- [Settings Reference](/docs/reference/settings) — Configure your preferred AI tool - [Playbooks](/docs/guides/playbooks) — Add project standards to your prompts diff --git a/website/pages/docs/guides/web-ui.mdx b/website/pages/docs/guides/web-ui.mdx index 7de65b4..0f69918 100644 --- a/website/pages/docs/guides/web-ui.mdx +++ b/website/pages/docs/guides/web-ui.mdx @@ -1,76 +1,170 @@ # Using the Web UI -SpecWright includes a built-in web dashboard for managing projects, reviewing specifications, and shipping issues to AI coding tools. This guide walks you through the main screens. +SpecWright's web dashboard is where you create projects, walk through the specification workflow, review documents, manage issues, and ship to AI tools. This guide covers every screen. + +import { Callout } from 'nextra/components' ## Launching the Web UI ```bash -specwright --ui +specwright view # Opens dashboard +specwright new # Opens project creation +specwright ship # Opens issues board ``` -This starts the SpecWright server and opens the dashboard in your browser at `http://localhost:1337`. +The server runs on **port 5174**. If it's already running from another command, SpecWright reuses the existing server. -import { Callout } from 'nextra/components' +## Dashboard + +The dashboard shows all your projects with their status and progress. + +**Sidebar** (resizable — drag the right edge): +- SpecWright logo and repository name +- "New Project" button +- Navigation: Projects, Issues, Playbook +- Settings (bottom) + +Sidebar width is saved in your browser and persists across sessions. + +**Project list:** +- Responsive grid of project cards +- Each card shows: project name, description, phase progress, issue count +- Status filter dropdown at the top: All Projects, Backlog, PM Complete, UX in Progress, Engineer in Progress, Ready to Break, Ready to Ship, Implementing, Completed +- Click any project to open its detail view + +**Empty state:** Shows "No projects yet" with buttons to create a project or generate an example project. The example project loads demo fixtures so you can explore the UI. + +## Create project + +Two modes for starting a new project: + +**AI-assisted mode (default)** — Describe what you want to build in the text area. The AI classifier determines the scope ([Smart Scoping](/docs/workflow/scoping)), generates the project request, and starts the specification workflow. + +**Manual mode** — Enter a project name and description directly. Creates the project without scoping and drops you into the dashboard. + +## Specification workflow + +The specification page guides you through three agent phases: PM → Designer → Engineer. + +Each phase follows the same pattern: + +1. **Question answering** — The AI agent generates focused questions. For each question, you see the question text, suggested answer options (click to select), and a text field for custom answers. + +2. **Document generation** — After answering, the AI generates specification documents. A streaming progress log shows real-time updates during generation. + +3. **Document review** — You review the generated output with three options: + - **Approve** — Mark the document as complete and move to the next phase + - **Edit inline** — Click the edit button to modify Markdown directly in the browser. Ctrl+Enter saves, Esc cancels. + - **Refine with AI** — Open the refinement panel where you can type feedback and optionally upload up to 5 reference images (mockups, screenshots, design inspiration). The AI revises the document based on your feedback, with streaming progress. - -You can also access the Web UI by running `specwright view` or selecting **View** from the CLI menu. - +The left sidebar shows all documents for the project: Request, PRD, Design Brief, Screens, Tech Spec, Technology Choices, Acceptance Criteria. Completion indicators show which documents are approved. -## The dashboard +**Technology choices** have a special review flow — instead of editing Markdown, you review each decision category in a tab-based interface, select your preferred option per category, and approve once all selections are made. -The dashboard is your home screen. It shows all your projects with their current status — which phases are complete, how many issues have been generated, and what's ready to ship. +A cost estimate widget in the sidebar shows estimated token usage and hours. -![Project dashboard showing all projects and their status](/screenshots/project_page.png) +## Issue breakdown -Each project card shows: -- **Project name** and a short description -- **Phase progress** — Which specification phases have been completed -- **Issue count** — How many implementation tasks have been generated +After all three agent phases are complete, you trigger issue breakdown. Choose a detail level: -Click a project to open its detail view. +- **One-shot** — Fewer, larger issues +- **Few** — Basic breakdown +- **Moderate** — Recommended for most projects +- **Detailed** — Many smaller issues -## Project detail view +During generation, a streaming log shows progress in real time. After generation, a preview shows all issues with titles, statuses, and estimated hours. Click "Confirm Issues" to finalize. -Inside a project, you can navigate between the different specification outputs: +## Project detail -- **Overview** — Project description and scoping result -- **PRD** — The Product Requirements Document with job stories -- **Screens** — Screen inventory and wireframe definitions -- **Tech Spec** — Architecture document and technology choices -- **Issues** — All implementation tasks with their status +The project detail page is the main workspace for a project after specification is complete. -Each section shows the generated Markdown or structured data rendered in a readable format. You can review, refine, and regenerate any section. +**Routes:** +- `/project/:id/issues` — Issues board (default view) +- `/project/:id/docs` — Document browser +- `/project/:id/docs/:docType` — Specific document (PRD, Design Brief, Tech Spec, etc.) -## Answering questions +**Issues view** — A Kanban board with four columns: Blocked, Ready, In Review, Completed. Drag-and-drop issues between columns to change status. Click any issue to open its detail modal. Search and filter are available. -During the specification workflow, each phase presents you with a set of AI-generated questions. The question form shows: +**Documents view** — Tabs for each document type. Markdown documents render with a reading time estimate. Screens render as visual wireframes. Technology choices render in the selection interface. -- The question text -- Suggested answer options (click to select) -- A text field for custom answers -You work through each question, providing the context the AI needs to generate your specification documents. +## Issues board -## The issues board +The global issues board (`/issues`) shows issues across all projects. -Once all phases are complete and issues are generated, the issues board shows every implementation task: +- **Project filter** — Dropdown to filter by project or show all +- **View toggle** — Switch between Board (Kanban) and List (table) views +- **Board view** — Four columns (Blocked, Ready, In Review, Completed) with drag-and-drop +- **List view** — Table with sortable columns -![Issues board with implementation tasks](/screenshots/issues_page.png) +Each issue card shows: title, estimated hours, status badge, dependency count. -From here you can: -- Review individual issues and their acceptance criteria -- Ship issues directly to your AI coding tool (see [Ship to AI Tools](/docs/guides/ship-to-ai-tools)) -- Track which issues have been implemented +## Issue modal + +Click any issue to open a detail modal with: + +- Issue ID and title +- Project name badge +- Status dropdown (change status directly) +- Description +- Acceptance criteria (editable list) +- Technical details and key decisions +- Testing strategy (automated + manual verification steps) +- Dependencies (if any) +- Screens affected +- **Ship** button — Send this issue to your AI tool (opens the Ship Modal) + +## Ship modal + +When you click "Ship," a modal opens that: + +1. Generates the full implementation prompt +2. Sends it to your selected AI tool (or copies to clipboard) +3. Shows streaming progress logs with status indicators +4. Displays success/failure state + +You can override the AI tool for a single ship action via a dropdown. + +For tools with headless support (Cursor, Claude Code, Codex, Gemini), the prompt runs directly via CLI with real-time streaming. For others (Windsurf, GitHub Copilot), SpecWright uses keyboard automation. ## Settings -Access Settings from the sidebar to configure: +The Settings page has these sections: + +- **AI Tool** — Select your preferred tool. Shows headless availability status for each tool. +- **Git Workflow** — Choose branch strategy: none, branch per issue, or branch per project. +- **Cost Estimation** — Enable/disable cost tracking and select the model tier (budget, standard, premium). +- **Linear** — Connect your Linear workspace with an API key and select a default team. + +See [Settings Reference](/docs/reference/settings) for full details on each option. + +## Playbook + +The Playbook page lets you manage project standards: + +- **Generate** — Analyze your codebase and produce a `PLAYBOOK.md` +- **View** — Read the current playbook (rendered Markdown with version info) +- **Update** — Regenerate the playbook to sync with codebase changes +- **Audit** — Check specifications for consistency with playbook standards +- **Edit** — Modify the playbook Markdown inline + +## Onboarding + +First-time users see an onboarding wizard with steps: + +1. **Tool selection** — Pick your AI coding tool +2. **Projects & Issues** — Quick intro to the workflow +3. **AI Squad** — Meet the three agents +4. **Magic** — How specs are generated +5. **Initialize** — Complete setup + +Progress dots at the top let you navigate between steps. After completion, you're redirected to a success screen. + +## Real-time updates -- **AI Tool** — Choose your preferred AI coding tool (Cursor, Claude Code, GitHub Copilot, etc.) -- **Linear Integration** — Connect to your Linear workspace -- **Git Strategy** — Configure branch creation for issues -- **Agent Customization** — Adjust AI agent behavior +The Web UI uses WebSocket connections for live updates. When an AI agent is generating documents or when files change, the UI updates automatically — no manual refresh needed. Active generation indicators appear in the header when any AI process is running. ## What's next? -- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send issues to your AI coding tool -- [The Specification Workflow](/docs/workflow) — Understand each phase in detail +- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — How shipping works in detail +- [The Specification Workflow](/docs/workflow) — Understand each phase +- [Settings Reference](/docs/reference/settings) — All configuration options diff --git a/website/pages/docs/reference/_meta.json b/website/pages/docs/reference/_meta.json index 0ee0683..bad9384 100644 --- a/website/pages/docs/reference/_meta.json +++ b/website/pages/docs/reference/_meta.json @@ -1,4 +1,5 @@ { "cli": "CLI Commands", - "output-files": "Output Files" + "output-files": "Output Files", + "settings": "Settings" } diff --git a/website/pages/docs/reference/cli.mdx b/website/pages/docs/reference/cli.mdx index 06d7cd8..4496b3b 100644 --- a/website/pages/docs/reference/cli.mdx +++ b/website/pages/docs/reference/cli.mdx @@ -1,6 +1,8 @@ # CLI Commands -SpecWright provides a command-line interface for running the specification workflow, managing projects, and launching the Web UI. +SpecWright's command-line interface for creating specifications, managing issues, and launching the Web UI. + +import { Callout } from 'nextra/components' ## Installation @@ -8,88 +10,179 @@ SpecWright provides a command-line interface for running the specification workf npm install -g specwright ``` -## Commands +Requires Node.js 18+ and npm 9+. -### `specwright` +## Interactive menu -Launches the interactive CLI menu. From here you can select any available action: scope new work, generate specifications, view projects, or launch the Web UI. +Running `specwright` with no arguments shows the interactive menu: -```bash -specwright ``` +🚀 WHAT DO YOU WANT TO DO? + +✨ new - Create new feature (design + tasks) +🚀 ship - Work on and ship tasks +👁️ view - Browse all projects and issues +📜 playbook - Manage project standards +``` + +Use arrow keys to select, Enter to confirm. + +If SpecWright is not initialized in the current directory, you'll see a welcome screen with options to launch the Web UI for onboarding, learn more, or exit. + +## Commands ### `specwright init` -Initializes SpecWright in your project directory. Creates the `specwright/` folder with agent prompts, templates, and the outputs directory. +Initialize SpecWright in your project. Creates the `specwright/` directory with: + +- `agents/` — AI agent system prompts (Product Manager, Designer, Engineer, Breakdown) +- `templates/` — Specification templates for output files +- `outputs/projects/` — Where generated specifications live +- `outputs/issues/` — Issue output directory +- `.cursor/commands/` — Custom Cursor commands (created at project root) ```bash cd /path/to/your/project specwright init ``` -Run this once per project. Safe to re-run — it restores any missing default files without overwriting existing outputs. +After creating files, SpecWright asks if you want to generate a [Playbook](/docs/guides/playbooks) immediately. + +Safe to re-run — restores missing default files without overwriting existing outputs or customized agent prompts. ### `specwright new` -Scope a new project or feature. Opens the Web UI where you describe what you want to build and the AI classifies it (see [Smart Scoping](/docs/workflow/scoping)). +Create a new project or feature. Opens the Web UI at `/create-project` where you can: + +- **AI-assisted mode** — Describe what you want to build; the AI classifies it via [Smart Scoping](/docs/workflow/scoping) and generates the project request +- **Manual mode** — Enter a project name and description directly ```bash specwright new ``` -### `specwright spec` +### `specwright ship` -Run the full specification workflow in the CLI. Guides you through all four phases interactively: PM → Designer → Engineer → Issue Breakdown. +Open the issues board in the Web UI. From here you can review issues, change statuses, and ship tasks to your AI coding tool. ```bash -specwright spec +specwright ship ``` ### `specwright view` -Launch the Web UI dashboard to browse projects, review specifications, and manage issues. +Open the Web UI dashboard to browse all projects, review specifications, and manage issues. ```bash specwright view ``` -### `specwright ship` +### `specwright playbook` -Ship an issue to your AI coding tool from the command line. +Open the Playbook manager in the Web UI. From there you can generate, view, update, or audit your project standards. ```bash -specwright ship +specwright playbook +specwright playbook --update # Open with update mode +specwright playbook --audit # Open with audit mode ``` -### `specwright playbook` +### `specwright approve` + +Approve completed issues from the command line. Three modes: -Generate a Playbook from your codebase (see [Playbooks](/docs/guides/playbooks)). +**Interactive (no arguments)** — Multi-select from all in-review issues: ```bash -specwright playbook +specwright approve +``` + +Shows all in-review issues across all projects. Use Space to select, Enter to confirm. + +**Specific issues** — Approve one or more issues by ID: + +```bash +specwright approve ENG-001 +specwright approve ENG-001 ENG-002 ENG-003 +``` + +Validates that each issue exists and is in "in-review" status before approving. + +**All at once** — Approve every in-review issue: + +```bash +specwright approve --all ``` -## Options +Lists all in-review issues grouped by project and asks for confirmation (defaults to "no" for safety). + +### `specwright finalize-scope` + +Create project folders from a scoping plan. Used after an AI tool generates `outputs/scoping_plan.json`: + +```bash +specwright finalize-scope +``` -| Option | Description | -|--------|-------------| -| `--ui` | Launch the Web UI directly (shortcut for `specwright view`) | -| `--version` | Display the installed version | -| `--help` | Show help information | +If the scoping plan is a "project" type, prompts you for: + +- **Question depth** — light (3-5 questions per agent), standard (5-8), or thorough (8-12) +- **Document length** — brief (600-900 words), standard (1,500-2,100), or comprehensive (3,600-4,500) + +These settings control how many questions each AI agent asks and how detailed the generated documents are. See [Settings Reference](/docs/reference/settings) for details. + +### `specwright break` + +Open the specification page for issue breakdown. If you have one project, opens it directly. If multiple, opens the dashboard. + +```bash +specwright break +``` + + +This command is a shortcut to the Issue Breakdown phase. The full specification workflow happens in the Web UI. + + +### `specwright spec` + +Legacy command — opens the specification page for a project. Use `specwright new` for new projects or `specwright view` for existing ones. + +```bash +specwright spec # Opens dashboard +specwright spec PROJECT-1 # Opens specific project +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--version`, `-v` | Print the installed version and exit | +| `--help`, `-h` | Show usage information | +| `--trace`, `-t` | Enable function-level tracing (entry/exit logs for every function call). Works with any command. | + +The `--trace` flag provides extremely detailed output showing every function call. Useful for debugging SpecWright itself, not for normal usage. ## Environment variables -| Variable | Description | -|----------|-------------| -| `SPECWRIGHT_DEBUG` | Set to `true` to enable debug logging | -| `SPECWRIGHT_TRACE` | Set to `true` to enable verbose trace-level logging | +| Variable | Default | Description | +|----------|---------|-------------| +| `SPECWRIGHT_DEBUG` | `false` | Enable debug-level logging. When `false`, only `logger.print()` output is visible. When `true`, all log levels (`debug`, `info`, `warn`, `error`, `success`) are shown. | +| `SPECWRIGHT_TRACE` | `false` | Enable function call tracing. Same as the `--trace` flag. Shows entry/exit for all function calls with a magenta banner. | + +## Web server behavior + +Most commands (`new`, `ship`, `view`, `playbook`, `break`, `spec`) launch a web server on **port 5174** and open your browser. The server: + +- Checks if a server is already running on the port (via `/api/projects` health check) +- Reuses an existing server if found — multiple commands can share the same server +- Stays alive until you press Ctrl+C +- Opens the browser to the appropriate page for the command ## Development mode -When working on SpecWright itself, use the dev command: +The `specwright-dev` binary runs with `SPECWRIGHT_DEBUG=true` enabled by default, pointing to the local development build: ```bash -specwright-dev [options] +specwright-dev new +specwright-dev --trace ship ``` - -This runs with debug logging enabled and points to the local development build. diff --git a/website/pages/docs/reference/output-files.mdx b/website/pages/docs/reference/output-files.mdx index fb2d821..c297e02 100644 --- a/website/pages/docs/reference/output-files.mdx +++ b/website/pages/docs/reference/output-files.mdx @@ -2,71 +2,415 @@ All specifications SpecWright generates are saved as plain Markdown and JSON files in your project's `specwright/outputs/` directory. No database, no proprietary format — just files you can read, edit, version-control, and feed into AI coding tools. +import { Callout } from 'nextra/components' + ## Directory structure -After running a full specification workflow, your outputs look like this: +After running a full specification workflow: + +``` +specwright/ +├── agents/ # AI agent prompts (customizable) +│ ├── product_manager/ +│ │ ├── system_prompt.md +│ │ ├── questioning_prompt.md +│ │ └── analysis_prompt.md +│ ├── ux_designer/ +│ │ ├── system_prompt.md +│ │ ├── questioning_prompt.md +│ │ └── analysis_prompt.md +│ ├── engineer/ +│ │ ├── system_prompt.md +│ │ ├── questioning_prompt.md +│ │ ├── choice_selection_prompt.md +│ │ └── analysis_prompt.md +│ └── breakdown/ +│ ├── system_prompt.md +│ └── issue_breakdown_prompt.md +├── templates/ # Output format templates +└── outputs/ + ├── scoping_plan.json # Current scoping result + ├── settings.json # User preferences + └── projects/ + └── 001-user-authentication/ + ├── project_request.md # Your original description + ├── project_status.json # Phase tracking (atomic writes) + ├── linear_sync.json # Linear sync state (if synced) + ├── questions/ + │ ├── pm_questions.json + │ ├── ux_questions.json + │ └── engineer_questions.json + ├── documents/ + │ ├── prd.md + │ ├── acceptance_criteria.json + │ ├── design_brief.md + │ ├── screens.json + │ ├── technical_specification.md + │ └── technology_choices.json + └── issues/ + └── issues.json +``` + +## Global files + +### `settings.json` + +User preferences stored at `specwright/outputs/settings.json`: + +```json +{ + "aiTool": "cursor", + "git": { + "enabled": true, + "strategy": "branch-per-issue" + }, + "costEstimation": { + "enabled": true, + "tier": "standard" + }, + "linear": { + "apiKey": "lin_api_...", + "defaultTeamId": "team-uuid", + "defaultTeamName": "Engineering" + } +} +``` + +| Field | Values | Description | +|-------|--------|-------------| +| `aiTool` | `cursor`, `claude-code`, `codex`, `gemini`, `github-copilot`, `windsurf` | Preferred AI coding tool | +| `git.strategy` | `none`, `branch-per-issue`, `branch-per-project` | Git workflow for shipped issues | +| `costEstimation.tier` | `budget`, `standard`, `premium` | Cost estimation model tier | +| `linear` | object | Linear API key and default team (optional) | + +### `scoping_plan.json` + +Created during project scoping. Determines the project type: + +```json +{ + "type": "project", + "projects": [ + { + "name": "User Authentication", + "description": "Google OAuth sign-in with session management" + } + ] +} +``` + +The `type` field is `"direct"` (skip spec, just implement), `"project"` (needs full spec), or `"multi-project"` (split into multiple projects). + +## Project files + +### `project_request.md` + +Your original description of what to build, saved as plain Markdown. + +### `project_status.json` + +Tracks the full state of the specification workflow. Written atomically (temp file + rename) to prevent corruption: + +```json +{ + "version": "1.0.0", + "projectId": "001-user-authentication", + "currentAgent": "ux", + "currentPhase": "ux-design-brief-review", + "agents": { + "pm": { + "status": "complete", + "currentPhase": "prd-review", + "phases": { + "questions-generate": "complete", + "questions-answer": "complete", + "prd-generate": "complete", + "prd-review": "complete" + }, + "startedAt": "2026-02-20T10:00:00Z", + "completedAt": "2026-02-20T10:25:00Z" + }, + "ux": { + "status": "in-progress", + "currentPhase": "design-brief-review", + "phases": { } + }, + "engineer": { + "status": "not-started", + "currentPhase": null, + "phases": { } + } + }, + "settings": { + "question_depth": "standard", + "document_length": "standard" + }, + "icon": { + "type": "emoji", + "value": "🔐" + }, + "approvedDocuments": ["prd"], + "costTracking": { + "tier": "standard", + "totalInputTokens": 45000, + "cachedOutputTokens": 32000, + "outputCalculatedAt": "2026-02-20T10:25:00Z" + }, + "history": [ + { + "phase": "pm-questions-generate", + "startedAt": "2026-02-20T10:00:00Z", + "completedAt": "2026-02-20T10:02:00Z", + "status": "complete" + } + ], + "createdAt": "2026-02-20T10:00:00Z", + "lastUpdatedAt": "2026-02-20T10:30:00Z" +} +``` + +**Phase status values:** `not-started` → `ai-working` → `awaiting-user` → `user-reviewing` → `complete` + +**Agent status values:** `not-started` → `in-progress` → `complete` + +## Question files + +All three question files (`pm_questions.json`, `ux_questions.json`, `engineer_questions.json`) follow the same format: + +```json +{ + "questions": [ + { + "question": "What authentication methods should be supported?", + "options": [ + "Google OAuth only", + "Google + email/password", + "Full SSO (Google, GitHub, Microsoft)" + ], + "answer": "Google OAuth only" + } + ], + "status": "answered", + "generated_at": "2026-02-20T10:02:00Z" +} +``` + +After you answer, your selection is tracked as a `decision` with `rejected_alternatives` for context in downstream phases: +```json +{ + "question": "What authentication methods should be supported?", + "decision": "Google OAuth only", + "rejected_alternatives": [ + "Google + email/password", + "Full SSO (Google, GitHub, Microsoft)" + ] +} ``` -specwright/outputs/ -├── project_plan.json # Scoping result -└── projects/ - └── 001-user-authentication/ - ├── project_request.md # Your original description - ├── project_status.json # Phase progress tracking - ├── questions/ - │ ├── pm_questions.json # PM phase questions & answers - │ ├── ux_questions.json # Designer phase questions & answers - │ └── engineer_questions.json # Engineer phase questions & answers - ├── 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 decisions - └── issues/ - ├── issues.json # All tasks in structured format - ├── ENG-001.md # Individual issue: Login UI - ├── ENG-002.md # Individual issue: JWT Auth - ├── ENG-003.md # Individual issue: Password Reset - └── ... + +This gives later agents clear context on what you chose *and* what you explicitly decided against. + +## Specification documents + +### `prd.md` + +Markdown document generated by the PM agent. Sections: + +1. **Executive Summary** — Project name, problem statement, solution overview +2. **Job Stories** — Requirements in "When [situation], I want [action], so [outcome]" format +3. **Project Requirements** — Business and functional requirements +4. **Functional Requirements** — Detailed system capabilities +5. **NoGos** — What is *not* being built, with rationale. Includes strategic rejections from your question answers (the `rejected_alternatives`) + +### `acceptance_criteria.json` + +Testable acceptance criteria linked to job stories: + +```json +{ + "job_stories": [ + { + "job_story_id": "JS-001", + "title": "Quick authentication", + "situation": "When I need to access the app quickly", + "motivation": "I want to sign in with Google", + "outcome": "So that I can start using the app immediately", + "acceptance_criteria": [ + { + "id": "AC-001", + "given": "Given I am on the login page", + "when": "When I click 'Sign in with Google'", + "then": "Then I am redirected to the Google consent screen" + }, + { + "id": "AC-002", + "given": "Given I have granted Google permissions", + "when": "When Google redirects back", + "then": "Then I am signed in and see the dashboard" + } + ] + } + ] +} +``` + +### `design_brief.md` + +Markdown document from the UX agent. Covers design approach, user flows, screen descriptions, component reuse guidance, and responsive behavior. + +### `screens.json` + +Screen inventory with components and interactions: + +```json +{ + "screens": [ + { + "id": "screen-001", + "name": "Login Screen", + "description": "User authentication entry point", + "components": [ + { + "id": "component-001", + "name": "Google OAuth Button", + "type": "create", + "description": "Sign in with Google button with OAuth flow" + }, + { + "id": "component-002", + "name": "AppHeader", + "type": "reuse", + "description": "Existing app header component" + } + ], + "interactions": [ + "Click 'Sign in with Google' → redirect to consent", + "Successful auth → redirect to dashboard", + "Failed auth → show error message" + ] + } + ] +} +``` + +Components are marked `"type": "reuse"` (use existing codebase component) or `"type": "create"` (build new). This tells the breakdown agent which components require implementation work. + +### `technical_specification.md` + +Markdown document from the Engineer agent. Covers architecture overview, system components, data models, API design, security considerations, deployment strategy, and monitoring. + +### `technology_choices.json` + +Technology decisions with options, trade-offs, and recommendations: + +```json +{ + "technology_decisions": [ + { + "category": "Authentication Provider", + "decision_needed": true, + "options": [ + { + "name": "NextAuth.js", + "description": "Full-featured authentication for Next.js", + "version": "5.0+", + "recommended": true, + "recommendation_reason": "Best integration with Next.js App Router", + "pros": ["Built-in Google provider", "Session management included"], + "cons": ["Tightly coupled to Next.js"], + "trade_offs": ["Less flexibility for non-Next.js backends"], + "maturity": "stable", + "implementation_complexity": "low", + "documentation_url": "https://authjs.dev", + "github_url": "https://github.com/nextauthjs/next-auth" + } + ] + } + ] +} ``` -## File descriptions +In the Web UI, you review each decision category and select your preferred option. Maturity levels (`stable`, `emerging`, `beta`) and complexity (`low`, `medium`, `high`) are shown with color-coded indicators. -### Project-level files +## Issue files -| File | Format | Description | -|------|--------|-------------| -| `project_plan.json` | JSON | Scoping result — lists all projects and their classification | -| `project_request.md` | Markdown | The original description you provided | -| `project_status.json` | JSON | Tracks which phases are complete | +### `issues.json` -### Questions +The single source of truth for all implementation tasks: -| File | Format | Description | -|------|--------|-------------| -| `pm_questions.json` | JSON | PM agent's questions and your answers | -| `ux_questions.json` | JSON | Designer agent's questions and your answers | -| `engineer_questions.json` | JSON | Engineer agent's questions and your answers | +```json +{ + "project_name": "User Authentication", + "project_id": "001", + "total_estimated_hours": 24, + "total_issues": 4, + "generated_at": "2026-02-20T11:00:00Z", + "issues": [ + { + "issue_id": "ENG-001", + "title": "User can sign in with Google", + "status": "pending", + "estimated_hours": 6, + "dependencies": [], + "description": "Complete Google OAuth sign-in flow", + "screens_affected": ["screen-001"], + "key_decisions": ["Using NextAuth.js with Google provider"], + "acceptance_criteria": [ + { + "id": "ac_001", + "description": "Given user on login page, when clicks Google button, then redirects to consent" + } + ], + "technical_details": "Configure NextAuth with Google OAuth provider, create API route for callback", + "testing_strategy": { + "automated_tests": "Integration test for OAuth callback flow", + "manual_verification": "1. Visit localhost:3000/login\n2. Click 'Sign in with Google'\n3. Grant permissions\n4. Should redirect to dashboard" + }, + "human_in_the_loop": [ + "Verify OAuth flow works with real Google account", + "Check error handling for denied permissions", + "Verify session persists across page refreshes" + ] + } + ], + "definition_of_done": [ + "Code complete and tested", + "Acceptance criteria verified", + "Human-in-the-loop verification passed" + ] +} +``` -### Specification documents +**Issue statuses:** `pending` → `in-review` → `approved` -| File | Format | Description | -|------|--------|-------------| -| `prd.md` | Markdown | Product Requirements Document with job stories, scope, and NoGos | -| `acceptance_criteria.json` | JSON | Testable criteria in Given/When/Then format | -| `design_brief.md` | Markdown | UX specification with navigation and interaction patterns | -| `screens.json` | JSON | Screen inventory — every UI screen with components and behavior | -| `technical_specification.md` | Markdown | Architecture document with API design, data model, security | -| `technology_choices.json` | JSON | Selected technologies with rationale and trade-offs | +Each issue is a [vertical slice](/docs/concepts/vertical-slices) — a complete, testable piece of user-facing functionality that spans all technical layers. -### Issues +### `linear_sync.json` -| File | Format | Description | -|------|--------|-------------| -| `issues.json` | JSON | All implementation tasks in structured format | -| `ENG-XXX.md` | Markdown | Individual issue files with full context for AI coding tools | +Created when you push a project to Linear. Tracks the mapping between SpecWright and Linear: + +```json +{ + "syncedAt": "2026-02-20T12:00:00Z", + "linearProjectId": "proj-uuid", + "linearProjectUrl": "https://linear.app/team/project/...", + "linearTeamId": "team-uuid", + "linearTeamName": "Engineering", + "issueIdMap": { + "ENG-001": "LIN-123", + "ENG-002": "LIN-124" + }, + "documentIdMap": { + "prd.md": "doc-uuid-1", + "design_brief.md": "doc-uuid-2", + "technical_specification.md": "doc-uuid-3" + }, + "externalLinks": [ + { "resource": "Screen Designs", "url": "http://localhost:5174/..." }, + { "resource": "Technology Choices", "url": "http://localhost:5174/..." } + ] +} +``` ## Version control @@ -79,13 +423,22 @@ git commit -m "feat: add user authentication specification" This lets you review specs in pull requests, track changes over time, and maintain a clear history of what was specified before implementation began. -import { Callout } from 'nextra/components' - The `specwright/` directory is designed to live alongside your source code. Committing specs to your repo means the specification is always tied to the codebase it describes. +## Atomic writes + +SpecWright uses a temp file + rename pattern for all status and state files. This prevents corruption if the process is interrupted mid-write: + +1. Write to `project_status.json.tmp` +2. Atomic rename to `project_status.json` +3. Clean up temp file on error + +You should never see `.tmp` files — if you do, a write was interrupted and you can safely delete them. + ## What's next? - [The Specification Workflow](/docs/workflow) — Understand how each file is generated - [CLI Commands](/docs/reference/cli) — Run the workflow from the command line +- [Settings Reference](/docs/reference/settings) — All configuration options diff --git a/website/pages/docs/reference/settings.mdx b/website/pages/docs/reference/settings.mdx new file mode 100644 index 0000000..1192894 --- /dev/null +++ b/website/pages/docs/reference/settings.mdx @@ -0,0 +1,100 @@ +# Settings Reference + +All configuration options available in SpecWright, accessible from the Settings page in the Web UI or stored in `specwright/outputs/settings.json`. + +import { Callout } from 'nextra/components' + +## AI tool selection + +Choose which AI coding tool receives your issues when you click "Ship." This affects how prompts are delivered and which execution method is used. + +| Tool | Type | Headless support | +|------|------|-----------------| +| **Cursor** | Standalone IDE | Yes — runs prompts via CLI without manual paste | +| **Claude Code** | CLI / VS Code extension | Yes — headless CLI execution with session resumption | +| **Codex CLI** | Headless CLI | Yes — CLI-only, no IDE window | +| **Gemini CLI** | Headless CLI | Yes — CLI-only, no IDE window | +| **GitHub Copilot** | VS Code extension | No — uses keyboard automation (opens chat, pastes prompt) | +| **Windsurf** | Standalone IDE | No — uses keyboard automation | + +**Headless mode** means SpecWright runs the AI tool's CLI directly, streams progress in real time, and captures results automatically. This is faster and more reliable than keyboard automation. + +**Keyboard automation** is the fallback for tools without headless support. SpecWright copies the prompt to your clipboard, activates the tool's window, opens a new chat, and pastes. You may need the tool already running. + +Set during onboarding or change anytime in Settings. + +## Project settings + +These settings are configured per-project, either during `specwright finalize-scope` or in the project settings panel. + +### Question depth + +Controls how many questions each AI agent asks during the specification workflow. + +| Level | Questions per agent | Total across 3 agents | Best for | +|-------|--------------------|-----------------------|----------| +| **Light** | 2-3 | 5-8 | Small features, quick specs | +| **Standard** | 3-4 | 8-12 | Most projects (default) | +| **Thorough** | 4-6 | 12-18 | Complex features, high-stakes projects | + +More questions mean more context for the AI agents, which produces more detailed and accurate specifications. But it also means more time answering. + +### Document length + +Controls the target word count for generated specification documents (PRD, design brief, technical spec). + +| Level | Word count | Reading time | Best for | +|-------|-----------|-------------|----------| +| **Brief** | 600-900 words | 3-5 min | Simple features, lightweight specs | +| **Standard** | 1,500-2,100 words | 7-10 min | Most projects (default) | +| **Comprehensive** | 3,600-4,500 words | 15-20 min | Complex systems, detailed architecture | + +### Project icon + +Each project can have an emoji icon displayed on the dashboard and in project views. Set from the project detail page. + +## Git workflow + +Configure how SpecWright handles git branching when shipping issues to AI tools. The shipped prompt includes git instructions based on your selection. + +| Strategy | Behavior | +|----------|----------| +| **None** | No git instructions in shipped prompts | +| **Branch per issue** | Prompt instructs the AI tool to create a branch for each issue (e.g., `feat/ENG-001-google-signin`) | +| **Branch per project** | Prompt instructs the AI tool to use one branch for the entire project | + +## Cost estimation + +SpecWright tracks token usage per project to estimate AI generation costs. Token counts are computed using the `gpt-3-encoder` tokenizer. + +**Input tokens** are counted when prompts are generated. **Output tokens** are calculated by scanning all generated files (questions, documents, issues) and cached with file modification time checking — recalculated automatically when files change. + +| Tier | Description | +|------|-------------| +| **Budget** | Budget models (e.g., Claude Haiku) | +| **Standard** | Standard models (e.g., Claude Sonnet) | +| **Premium** | Premium models (e.g., Claude Opus) | + +Cost estimates appear in the project sidebar during the specification workflow. + +## Linear integration + +Connect SpecWright to your Linear workspace to sync projects and issues. See the full setup guide at [Linear Integration](/docs/guides/linear-integration). + +| Setting | Description | +|---------|-------------| +| **API key** | Your Linear personal API key. Stored in `settings.json`. | +| **Default team** | The Linear team to sync projects and issues to. | + +## Where settings are stored + +- **Global settings** (AI tool, git, cost, Linear): `specwright/outputs/settings.json` +- **Project settings** (question depth, document length, icon): `specwright/outputs/projects/{projectId}/project_status.json` → `settings` field + +Settings files are written atomically to prevent corruption. + +## What's next? + +- [CLI Commands](/docs/reference/cli) — Command-line options and flags +- [Output Files](/docs/reference/output-files) — Full file format reference +- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — How AI tool selection affects shipping diff --git a/website/pages/docs/troubleshooting.mdx b/website/pages/docs/troubleshooting.mdx index 113ee6e..282f1fc 100644 --- a/website/pages/docs/troubleshooting.mdx +++ b/website/pages/docs/troubleshooting.mdx @@ -38,101 +38,164 @@ npm config set prefix '~/.npm-global' Then add `~/.npm-global/bin` to your PATH. Or use `npx specwright` instead of installing globally. +## "No SpecWright folder detected" + +You'll see this when running any command before initialization. SpecWright needs a `specwright/` directory in your project: + +```bash +cd /path/to/your/project +specwright init +``` + +Or select "Launch Web UI for guided onboarding" from the welcome screen to run `specwright init` through the Web UI. + ## Web UI **Web UI doesn't open in the browser** SpecWright runs its web server on port 5174. If the browser doesn't open automatically: -1. Check the terminal output for the URL — it should say something like `Server running at http://localhost:5174` +1. Check the terminal output for the URL — it should say `Server running at http://localhost:5174` 2. Open that URL manually in your browser -3. If the port is taken, check for other processes using it: +3. If the port is in use by another process: ```bash lsof -i :5174 ``` -**Web UI shows a blank page or loading spinner that never resolves** +Kill the conflicting process, or wait — if another `specwright` command is already running, it's using that server. Multiple commands share the same server instance. -Try a hard refresh (`Cmd+Shift+R` on macOS, `Ctrl+Shift+R` on Windows/Linux) to clear cached assets. If that doesn't help, stop SpecWright and restart: +**Web UI shows a blank page or loading spinner** + +Try a hard refresh (`Cmd+Shift+R` on macOS, `Ctrl+Shift+R` on Windows/Linux) to clear cached assets. If that doesn't help, restart: ```bash -specwright --ui +# Stop with Ctrl+C, then: +specwright view ``` -## Specification Generation +**Real-time updates not appearing** + +The Web UI uses WebSocket connections for live updates. If documents or issues aren't updating in real time: -**An AI agent phase is stuck or producing errors** +1. Check your browser's developer console for WebSocket errors +2. The WebSocket auto-reconnects up to 5 times with a 2-second delay between attempts +3. Refresh the page to establish a fresh connection -If a phase fails during generation: +## Specification generation -1. Check that SpecWright can reach the AI service — make sure you're connected to the internet -2. Try regenerating the phase from the Web UI by clicking the regenerate button -3. If the error persists, enable debug logging to see more detail: +**"No projects found" when running a command** + +This means the `specwright/outputs/projects/` directory is empty. Create a project first: ```bash -SPECWRIGHT_DEBUG=true specwright --ui +specwright new ``` +**A phase is stuck in "ai-working" state** + +Headless AI tool executions have a 5-minute timeout. If a phase exceeds this: + +1. Check that your AI tool (Cursor, Claude Code, etc.) is installed and accessible from the command line +2. For headless tools, verify they're available: + - Claude Code: `claude --version` + - Codex: `codex --version` + - Gemini: `gemini --version` +3. Check the Settings page — the headless status indicator shows which tools are detected +4. Cancel the stuck generation from the Web UI and retry + **Phase output seems wrong or incomplete** -The quality of generated specs depends heavily on your answers to the agent's questions. If output doesn't match your expectations: +The quality of generated specs depends on your answers to the agent's questions. If output doesn't match expectations: 1. Review your answers — vague or short answers produce vague specs -2. Revisit the phase and provide more detailed answers -3. Regenerate the phase output +2. Try the "Refine with AI" option: open the document, click the refinement panel, type specific feedback about what's wrong, and optionally upload reference images +3. Or edit the generated files directly — all outputs are plain Markdown and JSON in `specwright/outputs/` - -You can also edit the generated files directly. All outputs are plain Markdown and JSON in `specwright/outputs/`. The Web UI will reflect your changes on the next page load. - +**Documents show as "placeholder" and won't advance the phase** -## File & Project Issues +SpecWright detects placeholder content in generated files. If a document file exists but contains only template structure without real content, the system won't mark the phase as complete. Regenerate the phase to get actual content. -**"Project not found" when opening a project** +## File & project issues -This usually means the project's output files were moved or deleted. Check that the project directory still exists: +**Project directory naming** + +Project directories must follow the format `{3-digit}-{slug}/` (e.g., `001-user-authentication/`). If you rename or move directories manually, SpecWright won't find them. ```bash ls specwright/outputs/projects/ ``` -If you moved or renamed project directories, SpecWright won't find them. The project directory names must match the format `001-project-name/`. +**`.tmp` files in the outputs directory** -**Spec files are empty or corrupted** +SpecWright uses atomic writes — it writes to a `.tmp` file first, then renames it. If you see `.tmp` files, a write was interrupted. You can safely delete them: -SpecWright uses atomic writes (temp file + rename) to prevent corruption. If a file is empty, the generation likely failed mid-write. Regenerate the affected phase from the Web UI. +```bash +rm specwright/outputs/projects/*/project_status.json.tmp +``` -## Linear Integration +**Spec files are empty** + +If a file exists but is empty, the generation failed mid-write. The atomic write pattern should prevent this, but if it happens, regenerate the affected phase from the Web UI. + +## Headless AI tools + +**"Command not found" when shipping to an AI tool** + +SpecWright needs the AI tool's CLI accessible from your terminal. Check: + +- **Claude Code**: `claude --version` +- **Codex**: `codex --version` +- **Gemini**: `gemini --version` +- **Cursor**: Cursor's headless mode runs via its built-in CLI + +For tools without headless support (Windsurf, GitHub Copilot), SpecWright falls back to keyboard automation — the tool must already be running. + +**Keyboard automation not working (Windsurf, GitHub Copilot)** + +The keyboard automation fallback copies the prompt to your clipboard, activates the tool's window, and pastes. If this fails: + +1. Make sure the AI tool window is open and not minimized +2. On macOS, grant accessibility permissions to your terminal app (System Settings → Privacy & Security → Accessibility) +3. Try shipping again — the automation needs the tool's window to be activatable + +## Linear integration **"Failed to connect" when setting up Linear** 1. Verify your Linear API key is correct in Settings -2. Make sure the API key has the right scopes — SpecWright needs read/write access to issues and projects +2. Make sure the API key has the right scopes — SpecWright needs read/write access to issues, projects, and documents 3. Check that your network allows connections to `api.linear.app` -**Issues don't appear in Linear after pushing** +**Issues don't appear in Linear after syncing** -After pushing, give Linear a few seconds to process. If issues still don't appear: +After syncing, give Linear a few seconds to process. If issues still don't appear: 1. Check the terminal output for error messages -2. Verify you selected the correct Linear team and project in Settings -3. Try pushing a single issue to isolate the problem +2. Verify you selected the correct Linear team in Settings +3. Check `specwright/outputs/projects/{projectId}/linear_sync.json` — this file tracks the sync state and issue ID mappings + +## Debug mode -## Debug Mode +For any issue not covered above, enable debug logging: + +```bash +SPECWRIGHT_DEBUG=true specwright view +``` -For any issue not covered above, enable debug logging for detailed output: +For function-level tracing (extremely verbose — shows entry/exit for every function call): ```bash -SPECWRIGHT_DEBUG=true specwright --ui +specwright --trace view ``` -For even more detail (including trace-level logs): +Or set the environment variable: ```bash -SPECWRIGHT_TRACE=true specwright --ui +SPECWRIGHT_TRACE=true specwright view ``` -The debug output will show API calls, file operations, and agent interactions — which helps narrow down where things go wrong. +The debug output shows file operations, phase transitions, WebSocket events, and AI tool interactions. --- diff --git a/website/pages/docs/workflow/designer.mdx b/website/pages/docs/workflow/designer.mdx index 0147906..bac7224 100644 --- a/website/pages/docs/workflow/designer.mdx +++ b/website/pages/docs/workflow/designer.mdx @@ -1,44 +1,107 @@ # Designer Phase -The Designer phase defines **how it looks and feels**. The AI Designer agent uses the PRD from the previous phase to ask UX-focused questions, then generates screen definitions, wireframes, and user flows. +The UX Designer agent creates screen specifications, component inventories, and user flows based on the PRD. It designs the user-facing experience before any architecture decisions are made. -## What the Designer agent asks +import { Callout } from 'nextra/components' -The Designer agent generates questions about the user experience, informed by the PRD. These typically cover: +## What the Designer agent does -- **Layout and navigation** — How should users move through the feature? -- **Key interactions** — What happens when users click, submit, or navigate? -- **Visual hierarchy** — What information is most important on each screen? -- **Edge cases** — What does the empty state look like? What about errors? -- **Responsiveness** — Does this need to work on mobile, tablet, or just desktop? +The Designer agent acts as a senior UX/UI designer. It reads the PRD and your PM answers, then: -## What you get +1. **Audits the current state** — If you have an existing codebase, identifies current screens, components, and design patterns +2. **Identifies screen requirements** — Determines what screens need creating, modifying, or removing based on the PRD +3. **Defines information hierarchy** — Prioritizes content and functionality per screen +4. **Creates wireframe specifications** — Defines layouts and component placement +5. **Gathers visual inspiration** — Notes design patterns and references -### Design brief +## The questions -A Markdown document describing the overall UX approach — navigation patterns, interaction models, and design constraints. +The Designer agent asks 2-4 questions focused on UX concerns that the PM phase didn't cover: -### Screen inventory +- **Layout & navigation** — How should users move through the feature? +- **Interactions** — What behaviors do components need (drag-drop, modals, real-time)? +- **Visual hierarchy** — What should draw attention first on each screen? +- **Edge cases** — Empty states, error states, loading states? +- **Responsiveness** — Mobile-first? Desktop-focused? Both? -A structured JSON file listing every screen your feature needs. Each screen includes: +Questions are intentionally different from PM questions — the agent references your PM answers to avoid asking about requirements that are already resolved. -- **Screen name** and purpose -- **Components** — What UI elements appear on the screen -- **Behavior** — What happens on user interaction -- **Data displayed** — What information the user sees +## Outputs -![Screen definitions in SpecWright](/screenshots/screens_page.png) +### Design brief (`design_brief.md`) -### User flows +A Markdown document covering: -Descriptions of how users navigate through the feature. For example, a sign-up flow might be: Landing Page → Sign-up Form → Email Verification → Dashboard. +- Design approach and UX philosophy for this feature +- User flow descriptions (how users navigate through the feature) +- Screen-by-screen descriptions with layout notes +- Component reuse guidance (which existing components to leverage) +- Responsive behavior patterns +- Edge state handling (empty, error, loading, no-permission) -## Why it matters +### Screen inventory (`screens.json`) -Screen definitions give the Engineer concrete UI requirements to build against. They also give the Issue Breakdown phase enough detail to scope individual implementation tasks ("Build the login screen" vs. "Build the settings modal"). +A structured inventory of every UI screen the feature requires: -Without design specs, AI coding tools tend to make arbitrary UI decisions that don't match your product vision. +```json +{ + "screens": [ + { + "id": "screen-001", + "name": "Login Screen", + "description": "User authentication entry point", + "components": [ + { + "id": "component-001", + "name": "Google OAuth Button", + "type": "create", + "description": "Sign in with Google button with OAuth flow" + }, + { + "id": "component-002", + "name": "AppHeader", + "type": "reuse", + "description": "Existing app header component" + } + ], + "interactions": [ + "Click 'Sign in with Google' → redirect to consent", + "Successful auth → redirect to dashboard", + "Failed auth → show error message with retry" + ] + } + ] +} +``` + +### Component marking + +Each component is marked as one of: + +- **`create`** — A new component that needs to be built. This creates implementation work during Issue Breakdown. +- **`reuse`** — An existing component from your codebase. The agent identified it during codebase analysis. No implementation work needed. + +This distinction feeds directly into the [Issue Breakdown](/docs/workflow/issue-breakdown) phase — issues only include work for components marked `create`. + +### Screen categories + +The Designer agent organizes screens into standard categories: authentication (login, signup), onboarding (welcome, setup), dashboards, content/list views, detail/form views, navigation (menus, tabs), feedback (success, error, empty states), and modals/overlays. + +### Wireframe rendering + +In the Web UI, `screens.json` is rendered as a visual wireframe. The renderer supports layout elements (stacks, grids, cards), content elements (text, buttons, inputs, images), and interactive elements (forms, modals, tabs). The wireframe uses a gray-toned aesthetic to focus on structure rather than visual design. + +You can switch between screens using a dropdown selector. Each screen displays its components, interactions, and user flow steps. + +## Review and refinement + +After generation, you review the design brief and screen inventory in the Web UI. You can: + +- **Approve** — Mark the design as complete and move to the Engineer phase +- **Edit inline** — Modify the design brief Markdown directly +- **Refine with AI** — Provide feedback text and upload reference images (up to 5) to guide revisions. Useful for showing mockups, screenshots of existing UI, or design inspiration. ## What's next? -- [Engineer Phase](/docs/workflow/engineer) — Technical architecture and technology choices +- [Engineer Phase](/docs/workflow/engineer) — Architecture and technology decisions built from the design +- [Output Files](/docs/reference/output-files) — Full file format for screens.json and design_brief.md diff --git a/website/pages/docs/workflow/engineer.mdx b/website/pages/docs/workflow/engineer.mdx index c4eaffc..20f0935 100644 --- a/website/pages/docs/workflow/engineer.mdx +++ b/website/pages/docs/workflow/engineer.mdx @@ -1,44 +1,103 @@ # Engineer Phase -The Engineer phase defines **how to build it**. The AI Engineer agent reviews the PRD and design brief, asks technical questions, then produces architecture documents and technology choices. +The Engineer agent designs the technical architecture and selects technologies based on the PRD and design specifications. It produces a technical specification and a structured set of technology decisions. -## What the Engineer agent asks +import { Callout } from 'nextra/components' -The Engineer agent generates questions focused on technical constraints and decisions. These typically cover: +## What the Engineer agent does -- **Technology preferences** — Do you have an existing tech stack? Any requirements? -- **Architecture patterns** — Monolith or microservices? Server-rendered or SPA? -- **Data storage** — What kind of database? Any caching needs? -- **Authentication** — How should users authenticate? OAuth, JWT, sessions? -- **Third-party services** — Any external APIs or services to integrate with? -- **Performance and scale** — Expected traffic? Real-time requirements? +The Engineer agent acts as a senior engineer with architecture experience. It reads all previous outputs (PRD, acceptance criteria, design brief, screens), then: -## What you get +1. **Scans the codebase** — A high-level scan (not deep analysis) to understand existing tech stack, frameworks, and patterns +2. **Asks constraint questions** — Focused on non-technical constraints that affect architecture +3. **Designs architecture** — System components, data models, API design, security +4. **Evaluates technologies** — For each decision category, presents options with trade-offs +5. **Produces recommendations** — Marks recommended options with rationale -### Technical specification +## The questions -A Markdown document covering: - -- **Architecture overview** — How the system is structured -- **API design** — Key endpoints, data contracts -- **Data model** — Database schema, relationships -- **Implementation approach** — Build order, key technical decisions -- **Security considerations** — Authentication, authorization, data protection +The Engineer agent asks 2-4 questions focused on constraints, not implementation details: -### Technology choices +- **Performance** — Expected traffic, latency requirements, concurrent users? +- **Security** — Compliance requirements, data sensitivity, auth patterns? +- **Cost** — Infrastructure budget, managed services vs self-hosted? +- **Scale** — Growth expectations, data volume, geographic distribution? +- **Reliability** — Uptime requirements, failover needs, backup strategy? -A structured file listing every technology selected, with: +Like the Designer phase, questions reference your previous answers to avoid repetition. -- **What** — The technology or library -- **Why** — Rationale for choosing it -- **Trade-offs** — What alternatives were considered and why they were rejected +## Outputs -![Technology choices with rationale in SpecWright](/screenshots/technology_choices.png) +### Technical specification (`technical_specification.md`) -## Why it matters +A Markdown document covering: -Technology decisions made upfront, with documented rationale, prevent mid-project pivots. When the Issue Breakdown phase creates implementation tasks, it uses the tech spec to scope work accurately — including the right frameworks, libraries, and patterns in each task. +- **Architecture overview** — System components and how they interact +- **Data models** — Entity relationships, storage approach +- **API design** — Endpoints, request/response formats, authentication +- **Security architecture** — Auth flow, data protection, threat mitigation +- **Performance considerations** — Caching strategy, query optimization +- **Deployment strategy** — Infrastructure, CI/CD, environments +- **Monitoring** — Logging, metrics, alerting approach + +### Technology choices (`technology_choices.json`) + +Structured technology decisions where each category presents multiple options: + +```json +{ + "technology_decisions": [ + { + "category": "Database", + "decision_needed": true, + "options": [ + { + "name": "PostgreSQL", + "description": "Relational database with JSON support", + "version": "14+", + "recommended": true, + "recommendation_reason": "Best fit for relational data with ACID guarantees", + "pros": ["ACID compliance", "Rich JSON support", "Proven at scale"], + "cons": ["Operational overhead vs managed options"], + "trade_offs": ["Higher memory usage", "Schema migrations required"], + "maturity": "stable", + "implementation_complexity": "medium", + "documentation_url": "https://www.postgresql.org/docs/", + "github_url": "https://github.com/postgres/postgres" + } + ] + } + ] +} +``` + +### Technology choices viewer + +In the Web UI, technology decisions are displayed in a tab-based interface. For each decision category: + +- All options are shown with their pros, cons, and trade-offs +- The **recommended** option is highlighted +- **Maturity level** is color-coded: stable (green), emerging (blue), beta (amber) +- **Implementation complexity** is color-coded: low (green), medium (amber), high (red) +- Documentation and GitHub links are provided where available +- A dropdown lets you select your preferred option + +You must make a selection for each category before the technology choices can be approved. Progress tracking shows how many decisions you've made out of the total. + +The Engineer agent evaluates options across: scalability, performance, reliability, security, maintainability, cost, complexity, team fit, time to market, and vendor lock-in risk. + +## Review and refinement + +After generation, you review the technical spec and technology choices in the Web UI: + +- **Technical specification** — Edit inline, refine with AI feedback and reference images, or approve +- **Technology choices** — Review each category, select your preferred option, then approve once all selections are made + + +You don't have to accept the AI's recommendation. The technology choices UI lets you select any option in each category. Your selections are what the Issue Breakdown phase uses when creating implementation tasks. + ## What's next? -- [Issue Breakdown](/docs/workflow/issue-breakdown) — Turn specs into implementation tasks +- [Issue Breakdown](/docs/workflow/issue-breakdown) — Implementation tasks built from all three specs +- [Output Files](/docs/reference/output-files) — Full file format for technology_choices.json diff --git a/website/pages/docs/workflow/index.mdx b/website/pages/docs/workflow/index.mdx index 34fde3b..1169dd5 100644 --- a/website/pages/docs/workflow/index.mdx +++ b/website/pages/docs/workflow/index.mdx @@ -20,13 +20,13 @@ Each phase builds on the previous one. The Product Manager's PRD informs the Des Every phase (except Scoping) follows the same pattern: -1. **Questions** — The AI agent generates a set of focused questions about your project. These aren't generic questions — they're tailored based on your project description and outputs from previous phases. -2. **Your answers** — You answer each question. The AI provides suggested answer options, but you can write your own response. -3. **Generation** — The agent takes your answers and generates structured specification documents. -4. **Review** — You review the output in the Web UI or in the generated files. You can refine or regenerate if needed. +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](/docs/reference/settings) 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. The AI asks what it needs to know, and you provide the context only you have. +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 diff --git a/website/pages/docs/workflow/issue-breakdown.mdx b/website/pages/docs/workflow/issue-breakdown.mdx index 0e53450..95e3d4a 100644 --- a/website/pages/docs/workflow/issue-breakdown.mdx +++ b/website/pages/docs/workflow/issue-breakdown.mdx @@ -1,41 +1,116 @@ # Issue Breakdown -The final phase takes everything from the previous three phases — PRD, design brief, and technical specification — and breaks it into implementation-ready tasks. +The Breakdown agent converts your complete specification — PRD, design brief, technical spec — into implementation tasks structured as vertical slices. Each task is a self-contained piece of user-facing functionality ready to ship to an AI coding tool. -## How it works +import { Callout } from 'nextra/components' -The AI Breakdown agent analyzes all your specification documents and produces a set of issues, each scoped as a **vertical slice** — a self-contained piece of work that delivers user-visible value. +## How breakdown works -Unlike horizontal slicing (build all the database first, then all the API, then all the UI), vertical slices cut through every layer. A single issue like "Build login screen with JWT authentication" includes the UI, the API endpoint, and the database changes — everything needed to make that feature work end-to-end. +The Breakdown agent acts as a senior Tech Lead. It reads all previous specification documents and produces issues that are: -## What you get +- **Vertical slices** — Each issue spans all technical layers (UI, API, database) to deliver a complete user capability. See [Vertical Slices](/docs/concepts/vertical-slices). +- **Sequenced by dependency** — Issues are ordered so each one builds on what came before +- **Self-contained** — Each issue includes everything an AI coding tool needs: description, acceptance criteria, technical context, testing strategy -Each issue includes: +## Breakdown detail levels -- **Title** — Clear, actionable description of the task -- **Description** — Full context explaining what needs to be built -- **Acceptance criteria** — What "done" looks like, inherited from the PRD -- **Dependencies** — Which issues need to be completed first -- **Specification context** — Relevant excerpts from the PRD, design brief, and tech spec +Before generating issues, you choose a detail level that controls how finely the work is broken down: -![Implementation tasks organized by vertical slice](/screenshots/issue_list_page.png) +| Level | Description | +|-------|-------------| +| **One-shot** | Lightweight — fewer, larger issues for simple features | +| **Few** | Basic breakdown — a handful of focused issues | +| **Moderate** | Recommended — balanced granularity for most projects | +| **Detailed** | Thorough — many smaller issues for complex features | -## Issue format +## Complexity scoring -Each issue is saved as an individual Markdown file (e.g., `ENG-001.md`) with all the context an AI coding tool needs to implement it. The full list is also available in `issues.json` for programmatic access. +Each issue receives a complexity score from 1-10, mapped to estimated hours: + +| Score | Difficulty | Estimated hours | Guidance | +|-------|-----------|----------------|----------| +| 1-2 | Trivial | 1-2h | Config changes, copy-paste, simple wiring | +| 3-4 | Easy | 2-4h | Straightforward implementation | +| 5-6 | Medium | 4-8h | Some unknowns, moderate scope | +| 7-8 | Hard | 8-16h | Significant unknowns — consider splitting into subtasks | +| 9-10 | Very hard | 16h+ | Must be broken into subtasks | + +Issues scoring 7+ are automatically split into subtasks organized by technical layer within the vertical slice: ``` -specwright/outputs/projects/001-your-project/issues/ -├── issues.json # All issues in structured format -├── ENG-001.md # Login screen UI -├── ENG-002.md # JWT authentication API -├── ENG-003.md # Password reset flow -└── ... +VERTICAL SLICE: "User can sign in with Google" + ├─ Backend: OAuth provider integration + ├─ Frontend: Sign-in button and flow + ├─ Database: User profile storage + └─ Testing: OAuth integration tests ``` -## What's next? +## Issue structure + +Each issue in `issues.json` includes: + +- **Title and description** — What the user can do after this issue is complete +- **Estimated hours** — Based on complexity scoring +- **Dependencies** — Other issue IDs that must be completed first +- **Screens affected** — IDs from `screens.json` that this issue touches +- **Key decisions** — Architecture and technology decisions relevant to this issue +- **Acceptance criteria** — Specific, testable criteria inherited from the PRD +- **Technical details** — Implementation guidance from the tech spec +- **Testing strategy** — Both automated tests and manual verification steps +- **Human-in-the-loop verification** — Specific steps for a person to verify the implementation + +## Testing philosophy + +The Breakdown agent follows a critical-only testing approach: + +**Write automated tests for critical logic:** +- Payment processing +- Authentication and authorization +- Security operations +- Critical user data operations +- Business-critical workflows + +**Skip automated tests for non-critical code:** +- UI components and styling +- Simple CRUD on non-critical data +- Form validation (non-security) +- Display logic + +**Every issue includes manual verification steps** — specific localhost testing instructions that a person follows to verify the implementation works correctly: -Once issues are generated, you're ready to start building: +```json +{ + "testing_strategy": { + "automated_tests": "Integration test for OAuth callback flow", + "manual_verification": "1. Visit localhost:3000/login\n2. Click 'Sign in with Google'\n3. Grant permissions\n4. Should redirect to dashboard" + }, + "human_in_the_loop": [ + "Verify OAuth flow works with a real Google account", + "Check error handling when user denies permissions", + "Verify session persists across page refreshes" + ] +} +``` + +## Codebase awareness + +If you've initialized SpecWright in an existing project, the Breakdown agent analyzes your codebase when creating issues. It accounts for: + +- Existing components that can be reused (from `screens.json` component marking) +- Current file structure and naming patterns +- Installed dependencies and frameworks +- Existing API patterns and data models + +## Review and confirmation + +After issues are generated, you see a preview with the issue count, titles, statuses, and estimated hours. Click "Confirm Issues" to finalize and open the issues board where you can: + +- Review each issue's full details +- Change issue status via drag-and-drop +- Ship any issue to your AI coding tool + +## What's next? -- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send issues directly to Cursor, Claude Code, or your preferred AI coding tool -- [Linear Integration](/docs/guides/linear-integration) — Sync issues to your Linear workspace +- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send issues to Cursor, Claude Code, and more +- [Vertical Slices](/docs/concepts/vertical-slices) — Why this task structure works +- [Output Files](/docs/reference/output-files) — Full `issues.json` format reference diff --git a/website/pages/docs/workflow/product-manager.mdx b/website/pages/docs/workflow/product-manager.mdx index ff9b52d..38d38ea 100644 --- a/website/pages/docs/workflow/product-manager.mdx +++ b/website/pages/docs/workflow/product-manager.mdx @@ -1,49 +1,116 @@ # Product Manager Phase -The PM phase defines **what** to build. The AI Product Manager agent asks you strategic questions about your project, then generates a Product Requirements Document (PRD) with job stories and acceptance criteria. +The PM agent gathers your requirements and produces a Product Requirements Document (PRD) with job stories and acceptance criteria. This is the foundation that all subsequent phases build on. -## What the PM agent asks +import { Callout } from 'nextra/components' -The PM agent generates 5–8 focused questions tailored to your project. These typically cover: +## What the PM agent does -- **Purpose and context** — What problem does this solve? Who is it for? -- **Users and scope** — Who are the primary users? What's in scope vs. out of scope? -- **Key requirements** — What must the feature do? What are the core behaviors? -- **Business logic** — What rules govern the feature? What edge cases matter? -- **Data and integrations** — What data does it need? Does it connect to external systems? -- **Constraints** — Are there performance, security, or compatibility requirements? +The PM agent acts as a senior Product Manager. It follows a discovery framework: -For each question, the AI suggests answer options based on common patterns. You can pick a suggested answer or write your own. -## What you get +1. **Examine context** — Analyzes your project description and (if available) your existing codebase to understand the starting point +2. **Ask strategic questions** — Generates focused questions based on what it needs to know +3. **Synthesize your answers** — Identifies patterns, priorities, and gaps in your responses +4. **Define requirements** — Produces a structured PRD +5. **Create job stories** — Writes user-centered scenarios with testable acceptance criteria +6. **Document NoGos** — Explicitly records what is *not* being built -After you answer the questions, the PM agent generates: +## The questions -### PRD (Product Requirements Document) +The PM agent generates questions covering six categories: -A structured Markdown document containing: -- **Problem statement** — What problem this project solves -- **Solution overview** — High-level approach -- **Job stories** — Requirements in "When [situation], I want to [action], so I can [outcome]" format -- **Core functionality** — The must-have features -- **Secondary functionality** — Nice-to-have features -- **NoGos** — What is explicitly **not** being built (prevents scope creep) +- **Purpose & Context** — Why is this needed? What problem does it solve? +- **Users & Scope** — Who will use this? How many users? What segments? +- **Key Requirements** — What are the most important functional requirements? +- **Business Logic** — What are the core rules and workflows? +- **Data & Integration** — What data is involved? What systems does it connect to? +- **Constraints** — Business timelines, technical limitations, user accessibility needs? -### Acceptance criteria +The number of questions depends on your [question depth](/docs/reference/settings) setting: -Testable criteria in "Given / When / Then" format: +| Depth | Questions | +|-------|-----------| +| Light | 2-3 | +| Standard | 3-4 | +| Thorough | 4-6 | -> **Given** a user is on the login page -> **When** they enter valid credentials and click "Sign In" -> **Then** they are redirected to the dashboard and see a welcome message +Each question comes with 2-3 suggested answer options. You can pick one or write your own response. -![Acceptance criteria view in SpecWright](/screenshots/acceptance_criteria.png) +### How your answers are tracked -## Why it matters +When you answer a question, SpecWright records not just your choice but also what you decided against: -The PRD is the foundation for every subsequent phase. The Designer uses it to know what screens to design. The Engineer uses it to make architecture decisions. The Issue Breakdown uses it to define what "done" looks like for each task. +```json +{ + "question": "What authentication methods should be supported?", + "decision": "Google OAuth only", + "rejected_alternatives": [ + "Google + email/password", + "Full SSO (Google, GitHub, Microsoft)" + ] +} +``` -Without a clear PRD, specifications drift, scope creeps, and AI coding tools generate code that doesn't match what you actually need. +This matters because downstream phases and the PRD's NoGos section use your rejected alternatives to document scope exclusions. If you chose "Google OAuth only," the PRD will explicitly note that email/password and multi-provider SSO were considered and rejected. + +## Outputs + +### PRD (`prd.md`) + +A Markdown document with these sections: + +1. **Executive Summary** — Project name, problem statement, solution overview +2. **Job Stories** — Requirements in the format: "When [situation], I want [action], so [outcome]." Job stories focus on context and motivation rather than user roles, producing more specific requirements than traditional user stories. +3. **Project Requirements** — Business and functional requirements derived from your answers +4. **Functional Requirements** — Detailed system capabilities and behaviors +5. **NoGos** — What is *not* being built and why. Includes: + - Strategic rejections (options you explicitly decided against in your answers) + - Scope exclusions (features users might expect but won't get) + - Future considerations (deferred capabilities) + +The document length depends on your [document length](/docs/reference/settings) setting (brief: 600-900 words, standard: 1,500-2,100, comprehensive: 3,600-4,500). + +### Acceptance criteria (`acceptance_criteria.json`) + +Testable criteria linked to each job story, in Given/When/Then format: + +```json +{ + "job_stories": [ + { + "job_story_id": "JS-001", + "title": "Quick authentication", + "situation": "When I need to access the app quickly", + "motivation": "I want to sign in with Google", + "outcome": "So that I can start using the app immediately", + "acceptance_criteria": [ + { + "id": "AC-001", + "given": "Given I am on the login page", + "when": "When I click 'Sign in with Google'", + "then": "Then I am redirected to the Google consent screen" + } + ] + } + ] +} +``` + +Every requirement is traceable to a business or user need. Every job story has comprehensive acceptance criteria. Edge cases and error scenarios are covered. + +## Review and refinement + +After generation, you review the PRD in the Web UI. You can: + +- **Approve** — Mark the document as complete and move to the Designer phase +- **Edit inline** — Modify the Markdown directly in the browser (Ctrl+Enter to save) +- **Refine with AI** — Provide text feedback (and optionally upload reference images) to have the AI revise specific parts + + +You can also edit the generated files directly in your editor. All outputs are plain Markdown and JSON at `specwright/outputs/projects/{projectId}/documents/`. The Web UI reflects changes on the next page load. + ## What's next? -- [Designer Phase](/docs/workflow/designer) — UX specifications and screen designs +- [Designer Phase](/docs/workflow/designer) — UX specifications built from the PRD +- [Output Files](/docs/reference/output-files) — Full file format reference for PRD and acceptance criteria diff --git a/website/pages/docs/workflow/scoping.mdx b/website/pages/docs/workflow/scoping.mdx index d0b5b3c..9817a14 100644 --- a/website/pages/docs/workflow/scoping.mdx +++ b/website/pages/docs/workflow/scoping.mdx @@ -1,45 +1,62 @@ # Smart Scoping -Not everything needs a full specification. Before generating any documents, SpecWright analyzes your request to determine the right level of effort. +Before generating a full specification, SpecWright analyzes your request to determine the right level of effort. Not every piece of work needs a spec — sometimes you should just start coding. -## How it works +import { Callout } from 'nextra/components' -When you describe what you want to build, the AI Scoping agent classifies your request into one of three categories: +## How scoping works -| Classification | What it means | Example | -|---------------|---------------|---------| -| **Work Directly** | Too small for a spec — just implement it | "Fix the login button color" | -| **Project** | Needs a full specification | "Add Google Sign-in to the app" | -| **Multi-Project** | Large enough to split into multiple projects | "Build a complete e-commerce platform" | +When you create a new project (via `specwright new` or the Web UI), you describe what you want to build in plain language. SpecWright's AI classifier reads your description and places it into one of three categories: -## Work Directly +### Work Directly -If your request is a small change — a bug fix, a UI tweak, a minor feature — SpecWright tells you to skip the spec and start coding. This prevents over-engineering simple tasks. +The request is small enough to implement without a specification. Bug fixes, config changes, single-component tweaks, copy updates. -Examples of "Work Directly" requests: -- "Change the validation message on the login form" -- "Add a loading spinner to the dashboard" -- "Fix the broken link in the footer" +**Examples:** +- "Fix the login button color to match the design system" +- "Add a loading spinner to the search results page" +- "Update the footer copyright year" -## Project +**What happens:** SpecWright tells you to skip the spec and just start coding. If you're using a headless AI tool, it can generate a prompt to implement the change directly. -If your request involves meaningful new functionality, SpecWright creates a project and guides you through the four specification phases (PM → Designer → Engineer → Breakdown). +### Project -Examples of "Project" requests: -- "Build user authentication with OAuth" -- "Create a real-time notification system" -- "Add a video upload feature with processing" +The request needs a full specification. It involves multiple screens, an API, data storage, or touches enough of the system that you'd regret winging it. -## Multi-Project +**Examples:** +- "Add Google Sign-in with session management" +- "Build a task management board with drag-and-drop" +- "Create an admin dashboard for managing users" -If your request is large and spans multiple distinct capabilities, SpecWright breaks it into separate projects. Each project gets its own specification flow, but they're organized together as related work. +**What happens:** SpecWright creates a project folder and starts the specification workflow — [PM](/docs/workflow/product-manager) → [Designer](/docs/workflow/designer) → [Engineer](/docs/workflow/engineer) → [Issue Breakdown](/docs/workflow/issue-breakdown). -For example, "Build a project management tool" might be split into: -- **Project 1:** User authentication and team management -- **Project 2:** Project boards with drag-and-drop -- **Project 3:** Real-time collaboration +### Multi-Project + +The request is large enough to split into multiple independent projects, each getting its own full spec. + +**Examples:** +- "Build an e-commerce platform with product catalog, shopping cart, checkout, and order management" +- "Create a SaaS application with authentication, billing, team management, and a dashboard" + +**What happens:** SpecWright splits the work into separate projects (e.g., "Product Catalog", "Shopping Cart", "Checkout"), each running its own specification workflow independently. + +## Creation modes + +The Web UI offers two ways to create a project: + +**AI-assisted mode (default)** — Describe what you want to build, and the AI classifier determines the scope. If it's a project, SpecWright generates the project request automatically and starts the specification workflow. + +**Manual mode** — Enter a project name and description directly. Skips the scoping classification and creates a project immediately. Useful when you already know the scope. + +## Project settings at scoping time + +When a request is classified as a project, you configure two settings that affect the entire specification workflow: + +- **Question depth** — How many questions each agent asks: light (2-3), standard (3-4), or thorough (4-6). See [Settings Reference](/docs/reference/settings). +- **Document length** — Target word count for generated documents: brief (600-900), standard (1,500-2,100), or comprehensive (3,600-4,500). + +These can also be set from the CLI via `specwright finalize-scope`. -Each project is then specced independently through the full workflow. ## What's next? Once scoping is complete: