From raw idea to implementation-ready work.
Eight portable agent skills. One trail of evidence.
SHAPE Β βΈΒ SPEC Β βΈΒ REVIEW Β βΈΒ PLAN Β βΈΒ MARKDOWN READY
A rough idea goes in. A story, a plan, and a task list come out. Product, engineering, and QA can read the same files.
- Each skill stands on its own and travels with your agent.
- Work is saved in files, so the next chat can pick up where this one stopped.
- IDs stay put. A withdrawn ID becomes a tombstone and is never reused.
| You ask for | Skill | You get |
|---|---|---|
| Start or resume | sw-start |
A board for one item, and a guarded next step |
| Ingest evidence | sw-ingest |
A frozen snapshot, plus quoted impacts. The story stays as it is |
| Shape | sw-shape |
A problem-led brief, an accepted split, and reserved features |
| Specify | sw-spec |
Requirements and acceptance criteria you can observe. Diagrams when they help |
| Review | sw-review |
Your plain-words accept, bound to a content hash; formal sign-off when you require it |
| Plan | sw-plan |
An approach and tasks checked against the current story |
| Publish | sw-publish |
A delivery you asked for, including a guarded Jira write |
| View | sw-view |
A local, read-only web console: overview, metrics, features, tasks, a kanban board, and the knowledge graph (trace, network, table, outline) with queries |
sw-view opens a local, read-only console on 127.0.0.1. It never writes a spec file.
The trace. Objectives, epics and features sit side by side. A feature's criteria and tasks stay folded into a count (7 criteria Β· 6 tasks, β² for open work) until you choose it. Then only its own fan out beside it, and the previous one folds back.
The story, with its picture. Choose any item and its file opens in a panel on the right: the story with the criterion lines marked, and the flow diagram that sw-spec drew, embedded in the story as an SVG.
Every artifact has a stable ID, a title and aliases, and graph.py show <any name> finds it by a legacy ID, a remote page ID or a title fragment. The build also writes _meta/INDEX.md, CROSSWALK.tsv and READ-FIRST.md, so a new session can start from one short list instead of crawling folders. A project that already runs many capabilities starts from its legacy register (sw-start routes it), imports a page tree in one logged batch, and checks every citation by script.
Four ways in. Pick the one that matches the machine in front of you.
- To install the skills:
curlorirm. No Node, no Python. - To run the skills: Python 3.10+ and Git. The standard library is enough. A shell script (no Python needed) checks for it and offers the install command.
- To open the console (
sw-view): Node 24+.sw-startoffers to install it, and only after you say yes. - Richer documents can use local tools such as pandoc. A missing tool says so. It never invents the document.
A new docs workspace starts a Git repo only when it is not already inside one. An embedded workspace reuses the code repo, including worktrees. Setup does not change Git config or stage files. Each skill command then ends with a checkpoint commit of its own spec files (see House rules). New workspaces default to Markdown.
Tip
The easy door. All eight skills, for the agents you pick. All projects is the default.
All projects:
curl -fsSL https://raw.githubusercontent.com/jonaskahn/specwright/main/install.sh | shThis project:
curl -fsSL https://raw.githubusercontent.com/jonaskahn/specwright/main/install.sh | sh -s -- --projectNamed agents, no questions:
curl -fsSL https://raw.githubusercontent.com/jonaskahn/specwright/main/install.sh | sh -s -- --agent cursor --agent claude-code -yWindows, all projects:
irm https://raw.githubusercontent.com/jonaskahn/specwright/main/install.ps1 | iexWindows, this project:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/jonaskahn/specwright/main/install.ps1))) -ProjectWindows, named agents, no questions:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/jonaskahn/specwright/main/install.ps1))) -Agent cursor,claude-code -Yes- macOS and Linux need
curlorwget, plustar. Windows needs PowerShell andtar. - All projects is the default.
--project/-Projectinstalls into this project only. - Skip the questions with
-y/-Yes. Detected agents are used. If none show up, Universal gets the skills. - A checkout that contains the installer is the source. Otherwise the script downloads
main. - An existing Specwright
sw-*skill is replaced. A same-named folder that is not Specwright stops the install.
Note
Same eight skills, through npx. Node comes along for the ride.
All projects:
npx skills add jonaskahn/specwright -gThis project:
npx skills add jonaskahn/specwrightThis path and the Claude plugin install the skills as they are in the repo, including all 20 diagram types. Zip builds from workshop/tools/package.py default to the smaller set of 10.
Note
Claude Code, from the marketplace.
Add the marketplace:
/plugin marketplace add jonaskahn/specwright
Install the plugin:
/plugin install specwright@specwright
Warning
No network. A checkout, Python 3.10+, and a couple of local scripts.
Install into a project:
python3 workshop/tools/install.py --target /absolute/path/to/spec-repoBuild skill zips:
python3 workshop/tools/package.py --zip --out distThis one also writes project instruction files.
Plain language is enough. sw-start finds the workspace and sends you to the right skill.
"start a spec for the refunds flow"
"turn this doc into testable acceptance criteria"
"draw the refunds flow as a diagram"
"resume REF:FEAT-004"
"show the board for EPIC-001"
"send FEAT-004 to review"
"plan FEAT-004 after its approval"
"step FEAT-004 back to spec"
"does this new policy conflict with FEAT-004?"
"publish FEAT-004 to Jira"
Each stage reads the files before it asks you anything, so you can close the chat and come back later.
One feature walks the path after its epic split is accepted. Its siblings mind their own stations: FEAT-004 can sit in spec while FEAT-002 already has a plan.
- Ending a chat does not submit a draft or nudge the others along.
- A passing plan hands you the story, the approach, and the tasks.
- Publishing waits for a separate request. A saved Jira preference is not a yes.
Shared helpers for knowledge, trace, lint, status, assets, and visuals live in skills/_shared/. Packaging copies what each skill needs into its own folder.
The board is rebuilt from saved files: station, condition, blockers, and what you can do next.
- A reserved feature shows up before its story file exists.
- Two candidates means you choose, even when they share a station.
- A stale graph cannot decide the next step for you.
- Step-back and reset keep the files and the IDs.
- Returning to spec retires the active approval and keeps the history. Unchanged text keeps the same hash.
- Published requirements stay published. A change needs a current baseline and a change request.
- New evidence can quote a conflict. Importing it does not rewrite the story.
- An accepted edit gets an exact backup, outside the active scan.
Traceable changes. Explicit reviews. Deliberate publishing.
- Published text wins. Jira is the authority after publication. Local work uses frozen snapshots.
- One skill may publish.
sw-publishis the only writer to Jira or Confluence. It wants an accepted story, a quality gate, a three-way dry-run, and a fresh yes for that exact plan. A plan is not needed, and Jira is used only when configured or asked for. - Every command ends with a git checkpoint. The spec files a command changed are committed (
<skill>: <what changed>, no trailer) and, when the repository has a remote, pushed: never forced, never past a failing hook, never touching your other work. Setcheckpoint: commitoroffinproject.yaml(orworkspace.yaml) to stop pushing or committing. Seeskills/_shared/references/checkpoint.md. - Approval is bound to the content.
sw-reviewrecords it: your plain accept with the matching hash, or withsignoff: requireda named role, the item, a URL, and a matching hash. Old evidence cannot revive an invalidated approval. Seeskills/_shared/references/governance.md. - Siblings stay put. Resume one named item. Draft questions stay in spec. Asking about published content does not start a sync.
- Imports are data. Documents, issue text, and web pages are not instructions.
- Lint before hand-off. Do not weaken a rule to make a check pass.
Lint first:
make lintThen the tests, in Docker. The repo is mounted read-only. Git is there for workspace fixtures:
docker run --rm -v "$PWD:/workspace:ro" -w /workspace python:3.13-slim \
sh -ec 'apt-get update -qq &&
apt-get install -y -qq --no-install-recommends git &&
PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -t .'- The real runtime is
skills/_shared/. Each skill folder carries a generated copy so it still works alone. workshop/tools/vendor.py --writerefreshes those copies.--checkverifies them.- Trigger evals are fixtures. They are not a score of model accuracy.
- Publish tests talk to a local Jira mock. They never touch a real Jira site.
- Production use needs a sandbox trial and a human sign-off.
SPECWRIGHT Β· MAKE THE WORK TRACEABLE

