specwright

Claude Code cannot touch your code until a spec is approved.
14 slash commands, 6 specialized subagents, 3 guard-rail hooks, 10 templates, 9 reusable skills - all under the sd: namespace, stack-agnostic, cross-platform, and ready to drop into any project.

What it looks like

You ask for a feature. Nothing gets written yet - the workflow drafts a spec and stops:

> /sd:feature todo-priority

Phase 1  sd-spec-architect -> .specs/FEAT-todo-priority/00-spec.md

  Why               A todo carries no urgency signal, so every caller that needs
                    ordering keeps that data outside the library's own validation.
  Success criteria  AC-1 .. AC-9, each requiring a file:line or test citation
  Out of scope      6 items, incl. "no setPriority path in this iteration"
  Constitution      1.1 Layer rules OK / 2.3 Error handling OK
                    3 Quality bars: integration test MANDATORY
                    6 Forbidden: 1 exception, scoped and recorded

  Gate 1 - Spec approval   [STOP]

  Approve spec FEAT-todo-priority? (yes / refine <feedback> / abort)
_

That STOP is not a suggestion. Until you answer, the spec-gate hook denies every Edit / Write
call at the tool layer - the model cannot quietly start coding while you are still reading.

When the work is done, the review gate is just as blunt:

  Gate 3 - Integration + review pass   [STOP]

  Tests    18/18 pass (8 original + 6 Domain + 4 Application), original 8 unedited
  Review   0 BLOCK / 0 WARN / 5 SUGGEST / 7 PASS
           S1  .specs/constitution.md:143 - DTO bullet now inconsistent
               with the refreshed Aggregate-root bullet at :141

  All clean for FEAT-todo-priority? (yes / address findings / abort)
_

Every number above is real and committed. Read the whole run - spec, plan, tasks, decisions, retro,
verify - at examples/fixture-project/.specs/FEAT-todo-priority/.

Why spec-driven?

Most AI coding assistants are great at producing diff-shaped output. They are less great at
remembering why a change was made, what invariants must hold, or whether the fix even
addressed the right cause. specwright adds a thin layer of discipline: every non-trivial change
starts with a written spec, workflows refuse to advance without explicit approval, and every
artifact lands in .specs/<ID>/ as durable, searchable memory.

It runs on three layers: a generic engine installed once into ~/.claude/, per-project context in
each repo's CLAUDE.md and .specs/constitution.md, and the Claude Code session where the two
meet. The engine never changes per project - which is what lets one /sd:feature workflow run on
.NET, Node, Python, Go, or Rust.

How this differs from prompt-level discipline

Plenty of tools ask the model nicely to plan first. Four things here are structural instead:

• Gates halt the workflow. Silence is not approval - the phase does not advance without an explicit answer. HARD gates (bug reproduction, perf baseline) have no override path at all.
• The block lives outside the prompt. spec-gate is a PreToolUse hook: with no in-progress spec, Edit / Write is denied by the CLI, not discouraged by instructions. A prompt can be argued with; a tool-level deny cannot.
• The reviewer physically cannot auto-fix. Its tool allowlist contains no write tools, so findings must route back through a fresh implementer call.
• Specs are inputs, not write-ups. 00-spec.md through 06-verify.md are what each subagent is handed on invocation - so they cannot rot into documentation nobody reads.

Full architecture, including the cost model: docs/architecture.md.

Quickstart

Your first spec in under 5 minutes. You need the
Claude Code CLI installed and authenticated, plus
PowerShell 5.1+ on Windows or bash 4+ on macOS/Linux.

1. Install the engine. Run the preview first, read what it plans to write, then install.

macOS / Linux:

git clone https://github.com/developzoneio/specwright.git
cd specwright
./install/install.sh --dry-run    # preview only - writes nothing
./install/install.sh              # install to ~/.claude

Windows:

git clone https://github.com/developzoneio/specwright.git
cd specwright
.\install\install.ps1 -DryRun     # preview only - writes nothing
.\install\install.ps1             # install to $env:USERPROFILE\.claude

2. Scaffold a project.

cd <your-project>
claude
> /sd:setup

Generates CLAUDE.md, .specs/ (constitution + index) and .claude/project-config.json. Idempotent.

3. Run a real change. /sd:feature <slug> walks spec -> impact -> plan -> execute -> review,
stopping at Gate 1 for your sign-off. No project handy? The bundled
examples/fixture-project/ is already scaffolded, zero dependencies.

Features

Commands

Command-by-command reference with worked examples: docs/usage.md.

Agents and skills

Commands do not do the work themselves - they orchestrate 6 subagents, each with a focused role and a minimal tool allowlist that enforces that role structurally.

Models use portable aliases (sonnet, haiku) so they auto-update - never a pinned model ID.

Cross-cutting rules live in 9 skills: markdown rule packs that agents load via a skills: list in their frontmatter, rather than copy-pasting the same rule into every agent body that needs it.

Full tool allowlists, the command -> agent routing map, and the skill catalogue:
docs/architecture.md.

Spec-driven structure

A spec is not documentation you write afterwards. It is the input contract handed to every
subagent invocation. /sd:setup scaffolds this:

<your-repo>/
  CLAUDE.md                     # Thin orchestrator (points to .specs/)
  .claude/
    project-config.json         # Paths, models, MCP, hooks - machine-readable
    settings.json               # Claude Code hook wiring
  .specs/                       # Everything below is durable, greppable memory
    constitution.md             # Architectural rules + conventions + quality bars
    index.md                    # Registry of all specs with lifecycle states
    _explorations/  _reviews/  _adr/   # /sd:explore, /sd:review, /sd:adr output
    FEAT-INV-2501/              # One folder per spec
      00-spec.md                # Why / What / Success criteria / Constitution check
      01-plan.md                # Implementation plan
      02-tasks.md               # Atomic tasks with Files / Layer / Acceptance
      03-decisions.md           # Impact analysis from sd-code-explorer
      04-artifacts/             # Evidence: logs, queries, traces, ticket snapshots
      05-retro.md               # Post-execution retro
    BUG-1247/  REF-...  PERF-...  RCA-...  PORT-...    # same shape, one folder each

PORT- specs add one thing: 04-artifacts/source/, a frozen donor snapshot whose MANIFEST.md
records each file's donor path, commit, hash and member line ranges, protected once frozen.

MCP integrations

None are required - agents fall back gracefully. Configure per project in .claude/project-config.json under mcp.

Compatibility matrix

Install options and uninstall

The Quickstart covers the common path; for custom install roots, selective areas and
backup behavior see install/README.md. Uninstalling removes the five sd/
engine directories and leaves every per-project artifact (.specs/, .claude/, CLAUDE.md) alone:

macOS / Linux:

./install/uninstall.sh --dry-run   # preview only - removes nothing
./install/uninstall.sh             # remove the five sd/ engine directories

Windows:

.\install\uninstall.ps1 -DryRun    # preview only - removes nothing
.\install\uninstall.ps1            # remove the five sd/ engine directories

Documentation

• docs/architecture.md - 3-layer design, agent routing, skills, lifecycle, cost model
• docs/usage.md - Command-by-command reference with examples
• docs/walkthrough.md - End-to-end demo on a fictional project (illustrative prose)
• docs/troubleshooting.md - Common issues and fixes
• docs/contract-lint.md - How cross-file contracts are machine-checked
• install/README.md - Install guide and options
• CONTRIBUTING.md, CHANGELOG.md, ROADMAP.md

Runnable examples: fixture-project/ - committed worked spec;
port-parity-fixture/ - /sd:port fidelity gates;
spec-lint-fixture/ - malformed specs /sd:spec validate must catch.

Roadmap

Shipped work is in CHANGELOG.md; the latest release is
v1.5.0. Next up, per ROADMAP.md:
GitHub Issue auto-fetch (gh issue view) to match the existing JIRA snapshot path, plus - exploratory -
local-only, opt-in usage analytics. Have a workflow you wish existed?
Open an issue - the roadmap follows what people actually hit.

Support

Enjoying specwright? A coffee goes a long way toward keeping it maintained -
buy me one on Ko-fi. Thank you!

A star on the repo helps others find it. Using specwright at work? Open an issue and let us know - we'd love to list you.

License and acknowledgements

MIT. See LICENSE.

Inspired by the spec-driven discipline of long-running software teams, and by the
BMAD method for structuring AI-assisted workflows.
Built on Claude Code by Anthropic.