specwright (sw) is a plugin for Claude Code and Codex. It gives a repository
a ladder you climb one command at a time:
/sw:propose → /sw:plan → /sw:implement → /sw:review
proposal.md tasks.md code lgtm
design.md
Each step produces its artifact, stops, and names the next command. Nothing runs until you ask for it — the model may suggest a step, never dispatch the whole flow on its own.
Once you merge, /sw:archive closes the change out: it confirms the merge
from git alone and files the folder under changes/archive/. Opening the pull
request is yours, in whatever shape your repository's conventions ask for —
specwright deliberately has no opinion about it.
Two wrappers cover the cases where you do not want to climb:
/sw:shipruns the whole ladder without stopping, deciding every open question itself and recording each decision inproposal.md./sw:deliverytakes an outcome too large for one PR — often a PRD or a design document — decomposes it into changes, and conducts them in parallel, one owner and one PR each.
A trivial change needs none of this. Edit the code.
The implementation of every workflow lives once under
plugins/sw/skills/. Claude Code exposes thin /sw:*
command adapters; Codex discovers the same skills as $sw:*.
Because the state lives in files, not in the conversation. Two things follow.
You can change model between steps. Each step stops, so switching is just
/model before the next command — a stronger model where judgment pays off
(propose, plan, review), a cheaper one for the bulk of the execution
(implement).
You can hand a plan to an agent that has no context at all. tasks.md is
written for a stranger: exact paths, runnable commands, real code in every code
step, and no open questions. A fresh session — another model, another host, next
week — implements it with one command:
/sw:implement 2026-07-31-cursor-pagination/sw:plan checks that before it finishes. If the plan is not self-sufficient,
you find out while you can still fix it.
claude plugin marketplace add ribeirogab/specwright
claude plugin install sw@specwrightReload plugins or restart Claude Code afterwards.
codex plugin marketplace add ribeirogab/specwright
codex plugin add sw@specwrightCodex ships subagents disabled, so enable them once:
codex features enable multi_agent_v2It also reads subagent roles from its own home rather than from a plugin, so
those install once per machine too. $sw:init checks for them and prints the
exact command for your install path — it never writes outside a project unless
you ask it to.
Neither step is required: without them $sw:delivery and $sw:review run their
passes inline instead of spawning.
Both hosts install the same eight skills, and neither writes anything into your repositories at install time.
Claude Code: /sw:init
Codex: $sw:init
sw:init asks for a mode, then creates only what is missing. It is idempotent:
re-running it is the upgrade path, and a second run writes nothing.
- shared — specwright state is versioned with the project:
.specwright/andAGENTS.mdwith itsCLAUDE.md -> AGENTS.mdsymlink. Only.specwright/worktrees/is ignored. - local — specwright state stays private to the checkout:
AGENTS.override.md,CLAUDE.local.md -> AGENTS.override.md, and the vault and both instruction paths are git-ignored.
Either way that is the whole footprint: a vault, one instruction file, its symlink, and the ignore lines. Role profiles are not project state — both hosts resolve them outside the repository.
The AGENTS* file is always canonical; the CLAUDE* path is only a
compatibility symlink. Init appends one ## specwright section to the canonical
file and never touches it again — no digest, no drift check, no managed block.
The text is yours to edit from the moment it lands.
Init never installs a plugin, edits personal host configuration, copies skill
bodies, or creates .claude/settings.json. A path that exists in a shape it
cannot use — a CLAUDE.md that is a regular file, say — is reported as a
conflict, and nothing is written at all.
| Command | Claude Code | Codex | Produces |
|---|---|---|---|
| Set up | /sw:init |
$sw:init |
the vault and project instructions |
| Ticket | /sw:propose |
$sw:propose |
proposal.md — purpose, boundaries, AC-N |
| Plan | /sw:plan |
$sw:plan |
tasks.md, plus design.md above low scope |
| Build | /sw:implement |
$sw:implement |
code, quality gate, runtime verification |
| Review | /sw:review |
$sw:review |
one verdict, to lgtm |
| Close out | /sw:archive |
$sw:archive |
the merged change, filed |
| Autonomous | /sw:ship |
$sw:ship |
the four ladder steps, no stops |
| Large outcome | /sw:delivery |
$sw:delivery |
many changes, conducted in parallel |
/sw:propose absorbs the design conversation. After a discussion it harvests what
was settled and asks only about what is still open; from a cold start it opens
the exploration itself. Either way it writes the ticket at the end.
Two files per change, or three when the work has an architecture:
.specwright/
├── changes/2026-07-31-<slug>/
│ ├── proposal.md why, AC-N, decisions and discoveries
│ ├── design.md architecture; absent at scope: low
│ └── tasks.md the checklist and the execution state
├── changes/archive/ merged changes, filed by /sw:archive
├── deliveries/2026-07-31-<slug>/
│ └── delivery.md why + change table + dispatch log + blockers
└── worktrees/ ignored; one per change during a delivery
proposal.md carries the acceptance criteria — binary, observable checks someone
else can verify in under a minute — plus a Decisions and discoveries section:
the choices the ticket did not settle and the non-obvious facts the work found.
That section is what makes an autonomous /sw:ship run auditable after the fact.
tasks.md carries the checklist. Each task names the criteria it satisfies, the
files it touches, and one command that proves it. The checkboxes are the resume
state — /sw:implement continues at the first unticked box, which is what lets a
run stop and be picked up elsewhere.
design.md carries the architecture, and only exists when tasks.md declares a
scope: above low. Splitting it from the checklist keeps the write-once half
still: while a run churns checkboxes, an edit to the architecture shows up as
exactly what it is.
The handoff gate enforces the pair:
plugins/sw/scripts/validate-change.sh .specwright/changes/<folder>Seven checks: frontmatter and status enum, a named branch, no surviving
placeholders, no vague criteria verbs, AC-N traceability in both directions,
task metadata, and the design.md that any scope above low promises. Any of
them failing means an agent with no context could not run the plan.
Two rules survive from every earlier version, because they are what make the workflow worth its overhead:
Every AC-N is verified by observed behavior before the review. Run the
CLI, call the endpoint, execute the script. Reading the code is not verification.
A criterion that cannot be checked — no browser, no reachable environment — is
marked needs-human-verification with its reason, never silently ticked.
Verification happens at a known step, not on every edit. The quality gate
runs at implement or ship, or when you ask for it. After a direct edit
outside the workflow, the agent reports what changed and what it did not verify,
and leaves the decision to you.
/sw:delivery handles the case a single PR cannot: a PRD, a design document, a
body of requirements that clearly contains many pieces. It decomposes the
document into changes — shallow on purpose, since each change's own plan is
written later with the benefit of what shipped before it — and dispatches one
sw-change-owner per ready change, in parallel, each in its own worktree and
branch.
Owners report shipped with a branch, or blocked with a paste-ready Why /
Tried / Needs. A blocked change never blocks the loop. The delivery is resumable
from a fresh session: all state lives in delivery.md and the changes'
frontmatter.
Two, shared by both hosts:
| Role | Dispatched by | Codex sandbox |
|---|---|---|
sw-change-owner |
/sw:delivery, one per change |
workspace write |
sw-reviewer |
/sw:review |
read-only |
Neither pins a model. They inherit the session's, so the model you pick with
/model before dispatching is the one that runs — the same choice you make
between ladder steps, applied to the roles. The Codex sandbox is pinned, because
that is a permission boundary rather than a preference: the reviewer must not be
able to write, whatever model runs it.
Both hosts resolve the roles outside your repository — Claude Code from the
installed plugin, Codex from ${CODEX_HOME:-~/.codex}/agents/ after the one-time
install above. Nothing role-related is ever written into a project.
The reviewer covers three dimensions in one pass — rubric and conventions, change
conformance against the AC-N and their verification evidence, and documentation
consistency. A branch reaches lgtm only when no dimension has an open blocker.
specwright/
├── .agents/plugins/ Codex marketplace
├── .claude-plugin/ Claude marketplace
├── plugins/sw/
│ ├── .claude-plugin/ Claude package manifest
│ ├── .codex-plugin/ Codex package manifest + calendar version
│ ├── agents/ Claude role manifests
│ ├── commands/ eight thin Claude redirects
│ ├── skills/ the single workflow implementation
│ ├── templates/ proposal, design, tasks, delivery, Codex roles
│ ├── scripts/ scaffolder and validators
│ └── references/
├── tests/
└── .specwright/ dogfooded vault
Project-specific review rules live wherever your repository keeps them; list them
under a ## Conventions heading in the canonical AGENTS instructions and the
reviewer follows the links. Shared workflow behavior goes in the relevant
plugins/sw/skills/<name>/SKILL.md; never add host-specific behavior to a
command redirect.
See CONTRIBUTING.md for the validation matrix and release
gates. Security reports follow SECURITY.md.
Original work is licensed under the MIT License. Vendored Apache-2.0
scripts are documented in NOTICE.md.