specwright

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:ship` runs the whole ladder without stopping, deciding every open

question itself and recording each decision in proposal.md.

• `/sw:delivery` takes 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:*.

Why the steps are separate commands

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.

Install

Claude Code

claude plugin marketplace add ribeirogab/specwright
claude plugin install sw@specwright

Reload plugins or restart Claude Code afterwards.

Codex

codex plugin marketplace add ribeirogab/specwright
codex plugin add sw@specwright

Codex ships subagents disabled, so enable them once:

codex features enable multi_agent_v2

It 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.

Set up a repository

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/ and

AGENTS.md with its CLAUDE.md -> AGENTS.md symlink. 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.

Commands

/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.

Artifacts

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.

Verification

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.

Delivery

/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.

Roles

Two, shared by both hosts:

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.

Repository layout

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

Customize and contribute

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.

License

Original work is licensed under the MIT License. Vendored Apache-2.0 scripts are documented in NOTICE.md.