Claude Code · spec-driven development

From a rough idea to an open, evidence-backed PR.

A small set of Claude Code plugins that give a change a paper trail: you frame the idea, split it into buildable specs, and hand each one to an agent that implements it, tests it, proves it runs, and stops at a pull request for you to review.

idea→ concern→ specs→ ship→ open PRs

Install

One command to add it, one to install

The repo is a plugin marketplace. Installing spec-workflow pulls in live-verify automatically (it depends on it).

claude code

# 1 · register the marketplace (once)
/plugin marketplace add moacyrricardo/skills

# 2 · install — spec-workflow pulls live-verify with it
/plugin install spec-workflow@moacyr-skills

# 3 · activate in the current session
/reload-plugins

Once installed, the commands are namespaced by their plugin — /spec-workflow:new, /spec-workflow:ship, and so on. They're written in full below.

The model

Two kinds of document, one lifecycle

Every decision lives in a specs/ directory — the catalog. A file is named NNN-status-slug.md, and its status is its filename. The whole plugin set shares this model (the spec-conventions skill), so the commands never disagree about what a spec is.

Umbrella

Concern

Exploratory. Frames a problem, lays out hypotheses and trade-offs, keeps options open. Not a decision yet. One concern usually spawns several specs.

Buildable

Spec

A decision made — technically detailed and prescriptive, ready to hand to a builder. Each spec is one bounded, shippable slice of the concern.

todo→ doing→ done — a spec advances by being renamed (each step its own commit).

The flow

One idea fans out; each spec ships on its own

The shape of the work: a single concern becomes a handful of specs, and each spec becomes its own pull request. Nothing merges automatically — you stay the reviewer.

idea

spark

💡 a change

you

frame

concern · 002

☂ umbrella

todo

/new

decide

spec · 003

slice A

spec · 004

slice B

spec · 005

slice C

/new ×N

ship

✓ 003

✓ 004

✓ 005

/ship each

review

on GitHub

merge 🔀

you

the concern is retired with a pointer to the specs that resolved it — it stays in the catalog as history

Step by step

Idea → PR, in four moves

Frame the idea as a concern

Start wide. Run new and choose concern. Capture the problem, the options you're weighing, and the open questions. You're not committing to an approach yet — you're giving the idea a home in the catalog.

/spec-workflow:new → concern

Split it into a few specs

As the decisions firm up, break the concern into bounded, buildable slices — one spec each, via new. Then mark the concern resolved with a note pointing at the specs that settled it. You now have a small stack of todo specs.

/spec-workflow:new → spec (repeat)

Ship each spec

Hand a spec to ship. An agent builds it in the background: it flips todo → doing as the first commit (so the PR opens on that flip), implements the change, and leaves an open PR — stacked when specs depend on each other. It never merges. Run it once per spec.

/spec-workflow:ship 003

Review, then merge

Each PR arrives with its evidence attached (below). You review and merge on GitHub. When specs were stacked, utils' stacked-merge squash-merges the chain in order and handles the rebase bookkeeping between them.

/utils:stacked-merge 3 5 6

What ship leaves behind

Every PR shows its work

The point of shipping through the agent isn't speed — it's that each pull request carries proof, so review is fast and grounded.

comment 1

Tests

New tests named and explained, plus the actual pass/fail run.

comment 2

Eval

A read-only judgement of the branch against the spec's decision — gaps, in-scope fixes, and what was deferred to fresh specs.

comment 3

Finish

The final commit that moves the spec done and records how the build differed from the plan.

comment 4

Live evidence

Proof it actually runs — a GIF of the flow, or a captured request/response — via the live-verify plugin.

What's in the box

Three plugins, one marketplace

spec-workflow

depends on · live-verify

The catalog lifecycle: new, start, build, eval, finish, ship, plan, the autopilot agent, and the spec-conventions skill.

live-verify

standalone

Prove a feature works against a running app: start the dev server, then drive it — a real browser or curl — to capture a screenshot / GIF / text verdict. No spec or tracker coupling.

utils

standalone

General-purpose helpers. Currently stacked-merge — squash-merge a PR or a chain of stacked PRs into main, rebasing between each.

Tracker-agnostic. Nothing project-specific is hard-coded. Per-project values — your issue tracker's team key, the dev-server command — are read from the target repo's CLAUDE.md. Don't use an issue tracker? The Linear steps simply drop out.