Open source · MIT · by Bluewaves
Craftsman Build with agents without lowering the bar. The machine says pass — or it doesn't.
For the ones who won't lower the bar
Here's to the ones who let the agent do the work — and never let it grade its own homework.
Your own toolchain — the tests, the linter, the type checker, the build — becomes the verdict machine. Every check returns an exit code. Not a vibe. Not a language model's opinion. A verdict a machine can stand behind.
The contract
The human owns the vision.
The agent does the work.
The machine says pass.
One sentence the whole system serves. Everything else is detail.
Green means exit 0 — shown, not claimed. What it is
The Constitution
A hundred lines, read every turn.
AGENTS.md — vision, stack, one example per convention, the gate commands. Human-owned, never compacted, never over a hundred lines. One file routes every turn of work.
Machine Verdicts
The exit code is the verdict.
The model never judges whether its own code works — gates do. And the gates are your project's own commands: test, lint, types, build. Green means exit 0, with the evidence pasted.
Nine Skills
Sharp, not heavy.
Brainstorm, specify, plan, implement, verify, fix, review, finish — and one to set it all up. Each is seventy lines or less: it shows the shape of good work, then stops.
The Flow
Routed by state, never by hand.
A table in the constitution routes every turn. The spec freezes at approval; the plan adapts at every batch boundary; invisible changes may skip ceremony — never the gates.
The Ledgers
Everything durable is on disk.
SPEC.md holds the frozen criteria, PLAN.md the living batches, ADR.md the decisions and dead ends, the git log the narrative — typed commits a human can audit. Work survives compaction.
The flow
Nine sharp skills. Nobody names them — the work routes itself.
craftsman-mode — observes your codebase and writes the constitution from commands it actually ran.
brainstorm — opens the space — what should this even be?
specify — turns intent into frozen, checkable criteria. Yours to approve.
plan — slices the spec into batches, adapts at every boundary, waits for your go.
implement — one task, test first, docs open — red before green.
verify — every gate, fresh evidence, exit codes — never self-assessment.
fix — diagnoses to the root cause before a single line of repair.
review — fresh eyes judge whether the work is good, not just green.
finish — full QA, consolidated decisions, documentation true on a clean machine.
You make the product decisions; exit codes judge the code. That's the whole job.
Twelve messages from the human — one prompt, product decisions, approvals. Everything else, the flow routed on its own: a shipped product, on a mid-tier model, without a single subagent.
16/16 criteria · 53/53 tests · 44 typed commits · $7.07
Measured, not promised.
How it's built
Markdown, not machinery
A constitution and three ledgers — SPEC, PLAN, ADR — plus your git log. Plain files, human-owned, no state anywhere else. No CLI, no dependencies, no daemon: markdown and bash, nothing to break.
One command to install
Bash only, idempotent, user or project level. The skills land in the open-standard store, your agent discovers them, and your existing AGENTS.md is never touched. Uninstall is documented in the script.
The Skills
Nine skills in the Agent Skills open standard — readable by Claude Code, Codex, Cursor, whatever comes next. Each shows the shape of good work in seventy lines, then gets out of the way.
The machine speaks
The flow has one voice for status: evidence. It never flatters, and it never guesses.
Not for everyone
Craftsman isn't chasing the leaderboard, the demo, or the model of the week. It's a gift — MIT-licensed, no strings — for the people who ship real software and refuse to let an agent grade its own work. If that's you, it's yours.
Lineage
Two ancestors and a bet — each ancestor kept for the one thing it got right.
Craftsman v1 — machine-enforced: its insight is that verdicts must be exit codes. Kept — minus the 22,000-line CLI.
Superpowers — behavior-engineered: its insight is progressive disclosure — keep almost nothing always resident. Kept — minus the ceremony.
The LLM-judge research — models recognize correct code barely better than a coin toss; mechanical feedback beats “please do TDD”.
Agent Skills — one skill format every harness can read — process, not lock-in.
The bet on top of both: frontier models follow shape better than rules. Show one good example and they generalize; write ten paragraphs of prohibition and they rationalize.
The human owns the vision. The agent does the work. The machine says pass.
Guide and show, don't tell and control.
Take it. It's yours.
Read the pilot reportMIT-licensed · from Bluewaves