Skip to content

About

πŸ§‘β€πŸ’» Turning ideas into testable specs and implementation-ready work for human and agents.

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

228 Commits

Folders and files

Repository files navigation

Specwright β€” interlocking geometric shapes in a ring, with a dot that travels once around its edge

SPEC-WRIGHT

From raw idea to implementation-ready work.
Eight portable agent skills. One trail of evidence.

SHAPE Β β–ΈΒ  SPEC Β β–ΈΒ  REVIEW Β β–ΈΒ  PLAN Β β–ΈΒ  MARKDOWN READY

Python 3.10+ No external dependencies License MIT


01 β€” What you get

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

See it

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 Specwright console on the Graph page: an outline on the left, coverage measures on top, and the trace from business objective to epic, feature, acceptance criteria and tasks, with the chosen feature open and the others folded

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.

The Features page with a preview panel open on a draft story, showing its Visuals list and an embedded swimlane diagram of the invite, activate and remind flow

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.

02 β€” Install

Four ways in. Pick the one that matches the machine in front of you.

  • To install the skills: curl or irm. 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-start offers 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.

Command-line installer

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 | sh

This project:

curl -fsSL https://raw.githubusercontent.com/jonaskahn/specwright/main/install.sh | sh -s -- --project

Named agents, no questions:

curl -fsSL https://raw.githubusercontent.com/jonaskahn/specwright/main/install.sh | sh -s -- --agent cursor --agent claude-code -y

Windows, all projects:

irm https://raw.githubusercontent.com/jonaskahn/specwright/main/install.ps1 | iex

Windows, this project:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/jonaskahn/specwright/main/install.ps1))) -Project

Windows, 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 curl or wget, plus tar. Windows needs PowerShell and tar.
  • All projects is the default. --project / -Project installs 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.

Skills CLI

Note

Same eight skills, through npx. Node comes along for the ride.

All projects:

npx skills add jonaskahn/specwright -g

This project:

npx skills add jonaskahn/specwright

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

Claude Code plugin

Note

Claude Code, from the marketplace.

Add the marketplace:

/plugin marketplace add jonaskahn/specwright

Install the plugin:

/plugin install specwright@specwright

Air-gapped installation

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-repo

Build skill zips:

python3 workshop/tools/package.py --zip --out dist

This one also writes project instruction files.

Talk to your agent

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.

03 β€” How a feature moves

Per-item lifecycle: Shape, Spec, Review and Plan; passing checks deliver Markdown, while publication requires a separate request and confirmation.

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.

Back from files, not from memory

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.

04 β€” House rules

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-publish is 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. Set checkpoint: commit or off in project.yaml (or workspace.yaml) to stop pushing or committing. See skills/_shared/references/checkpoint.md.
  • Approval is bound to the content. sw-review records it: your plain accept with the matching hash, or with signoff: required a named role, the item, a URL, and a matching hash. Old evidence cannot revive an invalidated approval. See skills/_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.

05 β€” More to read

06 β€” If you hack on this

Lint first:

make lint

Then 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 --write refreshes those copies. --check verifies 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.

07 β€” License

MIT. See LICENSE and NOTICE.


SPECWRIGHT Β· MAKE THE WORK TRACEABLE

About

πŸ§‘β€πŸ’» Turning ideas into testable specs and implementation-ready work for human and agents.

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages