fsabuhi/draftsman

Strict, agent-ready specs for spec-driven development. Draftsman is an Agent Skill for Claude Code, Codex, Copilot, Gemini CLI, Cursor and any other agent that reads skills.
Coding agents build exactly what the spec says, and they do it confidently. Every gap in the spec turns into a guess, and the guess ships. Draftsman writes a spec with no room for guesses: every fact has one home, nothing is left vague, and every unknown is a recorded decision that names the work it blocks. It also installs a checker that fails the commit whenever any of that stops being true.
It's strict about gaps, not about length. A small MVP gets a small spec.
## What it does
| You have | Draftsman |
| An idea, or a starter template whose spec is partly filled | Creates the spec. It interviews you a few questions at a time, always with a recommendation, and drafts the vision, phases, features, decisions and a build order agents can follow step by step. |
| Docs in some other shape: a PRD, a README, notes | Migrates them into the strict layout without losing a fact. A ledger shows where every line went, and contradictions come back to you as questions instead of being settled quietly. |
| A draftsman spec | Audits it for what the checker can't see: undefined rules, vague limits, contradictions, blocked steps and missing human work. Then it closes each gap. |
Every gap is closed one of three ways: Draftsman derives it from your docs or code and cites the source, asks you, or records an open decision with its recommendation and the step it blocks. It never writes down an answer nobody gave it. If you're away, it turns every question into an open decision, finishes everything else, and leaves you the list.
## What you get
AGENTS.md how agents build: pick a step, build it, review it, merge it, tick it
CLAUDE.md @AGENTS.md, so Claude Code reads the same guide
.githooks/pre-commit runs the checker before every commit
.agents/skills/ review-step, audit-milestone and debt-ledger for the build workflow
THIRD-PARTY-NOTICES.md the licence of the work those skills adapt
scripts/check_spec.py the checker
docs/
AGENTS.md the rules and formats for everything below
README.md entry point, with a generated feature index
product.md vision, phases and gates, and the build order
decisions.md accepted, proposed, open and superseded decisions
features/ .md Behavior (with Done when) and Implementation
shared/ .md facts two or more features use
data/ .yaml numbers the code reads, referenced by key
never.md what will never be built, and why
ideas.md parked ideas
risks.md risks and their guardrails
AGENTS.md is the standard file every major agent reads, so one spec works whichever agent you use. Several agents can work in parallel too: each takes one build-order list, and git branches show which steps are taken.
The guide also carries a build workflow that runs without someone watching every step: one worktree per step, a review by a fresh agent before each merge, pull requests merged once CI passes (or fast-forwards without a remote), and a consolidation pass at the end of each milestone that audits the code and resolves the NOTE: comments marking deliberate simplifications. Agents never decide: a step that an open decision names waits for the answer, and nothing is stubbed. Each milestone ends with a team step that confirms its done-when, and agents start the next milestone only once it's ticked.