Portable spec-driven development workflows for AI coding agents. Claude Code is supported today. Codex support is planned as the next platform adapter.
specwright is currently implemented against Claude Code's commands, subagents, skills, hooks, and configuration conventions. The durable spec format and workflow rules are intended to remain platform-neutral; platform-specific packaging will be separated into adapters as Codex support is added.
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 enforces a thin layer of discipline:
- Every non-trivial change starts with a written spec.
- Workflows have hard gates - they refuse to proceed without explicit approval.
- Every artifact lands in
.specs/<ID>/as durable, searchable memory. - Reasoning, exploration, implementation, and review are assigned to explicit roles instead of one unconstrained agent.
The system is stack-agnostic. The current Claude Code adapter reads CLAUDE.md and constitution.md at runtime; there are no hardcoded language or framework assumptions.
| Capability | What you get |
|---|---|
| 9 workflow commands | Currently exposed as Claude Code slash commands: /sd:feature, /sd:bug, /sd:rca, /sd:refactor, /sd:perf, /sd:spec, /sd:explore, /sd:review, /sd:setup |
| 5 specialized agent roles | sd-spec-architect, sd-code-explorer, sd-debugger, sd-implementer, sd-reviewer |
| 3 guard-rail hooks | Current Claude Code adapter: prompt-router, spec-gate, subagent-retro (PowerShell + bash) |
| 9 templates | 4 setup templates + 5 spec templates (feature / bug / refactor / perf / rca) |
| 5 reusable skills | sd-severity-taxonomy, sd-hypothesis-tree, sd-atomic-task-format, sd-evidence-citation, sd-spec-templates |
| Claude Code installer | install.ps1 for Windows, install.sh for macOS/Linux. Content-hash dedup, timestamped backups, dry-run mode |
| MCP-friendly | Tooled out of the box for Atlassian, Context7, sequential-thinking, GitNexus, MSSQL, Playwright, Tavily |
| Stack-agnostic | Works for .NET, Node, Python, Go, Rust, and other stacks |
| Cost-aware | The current Claude Code adapter uses Sonnet for reasoning and Haiku for execution |
| Platform | Status | Notes |
|---|---|---|
| Claude Code | Supported | All commands, agents, skills, hooks, templates, and installers currently target Claude Code. |
| Codex | Planned | The spec lifecycle and shared rules will be retained, with Codex-native instructions, skills, agent orchestration, safety gates, and installation paths. |
| Other coding agents | Not scheduled | The architecture should permit more adapters, but no compatibility is claimed yet. |
The Codex work will focus on separating reusable workflow content from Claude-specific runtime contracts:
- Keep
.specs/, the lifecycle states, templates, evidence rules, task format, and constitution model platform-neutral. - Move Claude-specific commands, agent frontmatter, model aliases, hooks, settings, and install paths behind a Claude adapter.
- Add a Codex adapter using Codex-native project instructions, skills, tools, approval behavior, and configuration.
- Add adapter-level conformance tests so the same workflow gates and artifacts behave consistently across supported platforms.
Codex support will be considered ready when setup, feature, bug, RCA, refactor, performance, explore, review, and spec-management flows have documented installation and end-to-end regression coverage. Until then, the commands and installers in this repository should be treated as Claude Code only.
The following installer and setup flow targets Claude Code. A Codex installer is not available yet.
Windows (PowerShell 5.1+):
git clone https://github.com/developzoneio/specwright.git
cd specwright
.\install\install.ps1 -DryRun # preview
.\install\install.ps1 # install to $env:USERPROFILE\.claudemacOS / Linux (bash 4+):
git clone https://github.com/developzoneio/specwright.git
cd specwright
./install/install.sh --dry-run # preview
./install/install.sh # install to ~/.claudeThen in a real project:
cd <your-project>
claude
> /sd:setup
That's it. /sd:setup will scaffold CLAUDE.md, .specs/, and .claude/project-config.json interactively.
See install/README.md for advanced options.
| Command | Type | Hard gates | Purpose |
|---|---|---|---|
/sd:feature <ID-or-slug> |
Workflow | 4 | Spec-driven feature: spec -> impact -> plan -> execute -> review -> close |
/sd:bug <ID-or-slug> |
Workflow | 5 | Root-cause-first fix: capture -> reproduce -> investigate -> failing test -> minimal fix -> regression |
/sd:rca <slug> |
Workflow | 3 | Incident analysis. Output is the spec - no code change. |
/sd:refactor <slug> |
Workflow | 6 | Coverage-gated restructure: requires >=80% coverage before touching code |
/sd:perf <slug> |
Workflow | 8 | Baseline-first optimization: measure -> hypothesize -> apply -> remeasure -> keep or revert |
/sd:spec <subcommand> |
Utility | - | Spec registry: list, show, status, link, archive, revive, search, validate, stats |
/sd:explore <target-or-query> |
Utility | - | Read-only code navigation, single subagent call, optional save |
/sd:review [path / "recent" / "spec ID"] |
Utility | - | Standalone constitution-compliance review with severity tags |
/sd:setup |
Utility | - | Idempotent project scaffold (interactive) |
| Agent | Current Claude model | Tools (minimal allowlist) | Role |
|---|---|---|---|
sd-spec-architect |
sonnet | Read, Write, Edit, Grep, Glob, Atlassian MCP, Context7 MCP | Create / refine specs, plans, and tasks. Constitution-aware. |
sd-code-explorer |
haiku | Read, Grep, Glob, GitNexus MCP | Read-only navigation. Every finding cites file:line. |
sd-debugger |
sonnet | Read, Grep, Glob, Bash, sequential-thinking, GitNexus, MSSQL (SELECT only), Tavily, Context7 | Hypothesis-tree investigation. Distinguishes proximate vs root cause. |
sd-implementer |
haiku | Read, Write, Edit, MultiEdit, Grep, Glob, Bash, Context7 | Executes ONE atomic task. Scope-disciplined, no opportunism. |
sd-reviewer |
sonnet | Read, Grep, Glob, sequential-thinking, GitNexus | Severity-tagged review: BLOCK / WARN / SUGGEST / PASS. |
The Claude Code adapter uses portable Anthropic aliases (sonnet, haiku) so it can follow current model mappings. Model selection will be owned by each platform adapter rather than shared workflow content.
Skills are shared markdown rules that agent roles reuse. In the current Claude Code adapter, they live in ~/.claude/skills/sd/ (one folder per skill, each with a SKILL.md) and agents reference them via frontmatter. Pulling rules out of agent bodies and into skills keeps agent prompts smaller and lets multiple agents share the same canonical rule without copy-paste drift.
| Skill | Used by | Purpose |
|---|---|---|
sd-severity-taxonomy |
sd-reviewer |
BLOCK / WARN / SUGGEST / PASS severity rules and the mandatory review output format. |
sd-hypothesis-tree |
sd-debugger |
Enumerate-and-verify protocol with the 5 mental models, score formula, and proximate-vs-root "why" ladder. |
sd-atomic-task-format |
sd-spec-architect, sd-implementer |
The 9-field atomic task block, canonical enums (Step type, Complexity, Reversibility), and atomicity rules. |
sd-evidence-citation |
sd-code-explorer, sd-debugger, sd-reviewer |
Citation discipline — every finding cites file:line. Snippet length, grouping, and what counts as evidence. |
sd-spec-templates |
sd-spec-architect |
Per-template authoring rules (feature / bug / refactor / perf / rca), including which cross-phase fields to leave empty. |
Agents declare the skills they apply via a skills: list in their frontmatter, e.g.:
---
name: sd-reviewer
skills:
- sd-severity-taxonomy
- sd-evidence-citation
---Every project that adopts the current Claude Code adapter ends up with:
<your-repo>/
CLAUDE.md # Thin orchestrator (points to .specs/)
.claude/
project-config.json # Machine-readable config (paths, models, MCP, hooks)
settings.json # Claude Code hook wiring
.specs/
constitution.md # Architectural rules + conventions + quality bars
index.md # Registry of all specs with lifecycle states
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, screenshots
05-retro.md # Post-execution retro
BUG-1247/
...
REF-extract-pricing-20260112/
...
PERF-search-endpoint-20260114/
...
RCA-payment-outage-20260108/
...
A spec is not "documentation you write afterwards". It is the input contract to every agent invocation. The .specs/ tree is the primary portable artifact and is intended to work across platform adapters.
+--------------------------------------------------------------+
| Shared workflow core |
| lifecycle spec templates skills evidence rules |
+--------------------------------------------------------------+
|
v
+--------------------------------------------------------------+
| Platform adapter |
| Claude Code: commands / agents / hooks / settings |
| Codex: planned native instructions / skills / tooling |
+--------------------------------------------------------------+
|
v
+--------------------------------------------------------------+
| Project scope |
| portable .specs/ + platform-specific project context |
+--------------------------------------------------------------+
|
v
+--------------------------------------------------------------+
| Runtime |
| user <-> coding agent <-> specialized roles and tools |
+--------------------------------------------------------------+
- Shared workflow core - specs, lifecycle states, templates, quality rules, and role definitions should not depend on one coding-agent runtime.
- Platform adapters - translate the shared workflow into platform-native commands, instructions, skills, hooks, tools, models, and configuration.
- Hard gates - workflows require explicit approval at named checkpoints (spec approval, reproduction confirmed, baseline measured, plan approval, review pass, etc.). Enforcement is adapter-specific.
- Cost-aware models - each adapter maps reasoning and execution roles to suitable models. The current Claude Code mapping uses
sonnetandhaiku. - Stack-agnostic - the same
/sd:featureworkflow runs on .NET, Node, Python, Go, or Rust. Agents read project context at runtime.
The detailed architecture document currently describes the Claude Code implementation: docs/architecture.md.
specwright is designed around the MCP servers most useful for spec-driven work. None are required; agents fall back gracefully.
| MCP server | Used by | Purpose |
|---|---|---|
| Atlassian | sd-spec-architect, commands |
Fetch JIRA ticket context for <ID> arguments |
| Context7 | sd-spec-architect, sd-implementer, sd-debugger |
Pull current library docs (no stale training-data examples) |
| sequential-thinking | sd-debugger, sd-reviewer |
Structured hypothesis enumeration and verification |
| GitNexus | sd-code-explorer, sd-debugger, sd-reviewer |
Fast symbol search, callers, call graph |
| MSSQL | sd-debugger (SELECT/EXPLAIN only) |
Inspect schema and query plans during investigation |
| Playwright | optional | E2E reproduction for /sd:bug |
| Tavily | sd-debugger |
Web search for error signatures / library issues |
For the current Claude Code adapter, configure MCP per project in .claude/project-config.json under the mcp section.
| Component | Support status | Notes |
|---|---|---|
| Claude Code CLI | Supported; tested against the released version current at January 2026 | Hook contract: UserPromptSubmit, PreToolUse, SubagentStop |
| Codex | Planned; not yet tested or supported | Adapter design and conformance coverage are roadmap items |
| Windows 11 | PowerShell 5.1 and 7.x | PS 5.1 reads UTF-8 as CP1252 - hooks are pure ASCII |
| macOS 13+ | bash 4+ via Homebrew | stat -f %m syntax supported |
| Ubuntu 22.04+ | bash 5 | stat -c %Y syntax supported |
| jq | 1.6+ | Optional. Bash hooks exit 0 if missing. |
| .NET stack | ASP.NET Core 8 | Stack-agnostic - .NET is just one example |
| Node stack | Node 20+ / TS 5+ | Same /sd:feature workflow |
| Python stack | 3.11+ / FastAPI / Django | Same /sd:feature workflow |
docs/architecture.md- 3-layer design, lifecycle, cost modeldocs/usage.md- Command-by-command reference with examplesdocs/walkthrough.md- End-to-end fictional project demodocs/troubleshooting.md- Common issues and fixesinstall/README.md- Install guide and optionsCONTRIBUTING.md- PR process and dev guidelinesCHANGELOG.md- Release notes
MIT. See LICENSE.
Inspired by the spec-driven discipline of long-running software teams, and by the BMAD method for structuring AI-assisted workflows. The first adapter is built on Claude Code by Anthropic; Codex support is planned.