Guided, right-sized system design for AI coding agents.
Draftsman is a plugin for AI IDEs (Claude Code, Cursor, GitHub Copilot, and others) that turns a rough idea into a right-sized system design. It asks drill-down questions, recommends stacks and patterns with explained trade-offs, lets you decide, and produces requirements, ADRs, design docs, and diagrams. The result is neither over-engineered nor under-engineered.
- A single prompt rarely produces a design that fits your requirements.
- Adding more context doesn't fix it: agents drift toward designs that are too big or too small.
- Good results depend on expert prompt-writing that most developers don't have time to learn.
- Agents pick technologies silently, without saying why or what the alternatives were.
Draftsman replaces the one-shot prompt with a structured workflow and a scoring model that the agent has to follow.
flowchart LR
S["start<br/>brief + repo survey"] --> C["clarify<br/>questions → Scale Profile"]
C -->|lock| O["options<br/>trade-offs per decision"]
O --> D["decide<br/>ADR + budget"]
D --> O
D -->|all decided| G["doc<br/>design + diagrams"]
G --> R["review<br/>over / under / drift"]
R -->|fixes| D
| Step | Command | What you get |
|---|---|---|
| 1 | /draftsman:start <idea> |
A session folder, a repo survey, and a playback of what the agent understood |
| 2 | /draftsman:clarify |
Up to 4 rounds of focused questions, a scored Scale Profile, and locked requirements |
| 3 | /draftsman:options |
2–3 options per relevant decision, each with fit, cost, pros, cons, and a recommendation |
| 4 | /draftsman:decide |
An ADR for each choice, with the complexity budget updated |
| 5 | /draftsman:doc |
design.md with Mermaid diagrams, traceability, NFR mechanisms, and an evolution path |
| 6 | /draftsman:review |
A right-size verdict with concrete fixes |
| any | /draftsman:status |
Where the session stands and what to run next |
| — | /draftsman:evolve <change> |
The same flow for changing an existing system: it starts from the current profile and architecture, and marks every component Existing, Changed, or New |
/draftsman:start flows straight into clarify, and options records decisions as you go, so most sessions need only start, doc, and review. If your idea extends a system already in the repo, start hands off to evolve.
Draftsman scores 8 dimensions from 0 to 3: load, data, availability, consistency, compliance, team, integration, lifespan. The total maps to a tier:
| Tier | Score | Complexity budget |
|---|---|---|
| T0 Prototype | 0–4 | 3 |
| T1 Simple | 5–9 | 6 |
| T2 Standard | 10–14 | 10 |
| T3 Scaled | 15–19 | 16 |
| T4 Critical | 20–24 | 24 |
Three rules follow from the score:
- Complexity budget. Every pattern and technology has a cost (a modular monolith is 2, microservices are 6, event sourcing is 5). Going over budget needs an ADR that names the requirement forcing it.
- Unlock conditions. Some patterns are flagged unless the profile justifies them. For example, microservices need at least 2 teams and either real load or a wide integration surface.
- Baseline floor. The minimum a design must include: secrets management, CI/CD, observability, backups, idempotency, audit logging, and more, raised by tier and by individual scores. Floor items are never cut to save budget.
Two laws drive the review:
- Every component traces to a requirement. Otherwise it's over-engineering.
- Every requirement traces to a mechanism. Otherwise it's under-engineering.
No default stack. Draftsman never assumes a language or cloud. It uses what it finds in your repo or what you tell it, shows only the matching options, and compares across ecosystems when you have no preference. Every option states its license (open source, managed cloud, commercial, SaaS, or source-available), and Draftsman prefers tools your organization already licenses over new contracts.
Domain packs add industry-specific scoring hints and floor items. The insurance pack covers effective-dated policies, reproducible rating, consumer-report rules, claims deadlines, OFAC screening, and regulator notification. It loads automatically when the brief involves policies, claims, or premiums. It's a design checklist, not legal advice.
/plugin marketplace add senthil-sekar/draftsman
/plugin install draftsman@draftsman
Or from a terminal:
claude plugin marketplace add senthil-sekar/draftsman
claude plugin install draftsman@draftsmanClone this repo, then generate the files into your project (requires Node.js 18+, no packages to install):
node scripts/build-adapters.mjs --target cursor --out /path/to/your/project
node scripts/build-adapters.mjs --target copilot --out /path/to/your/project
node scripts/build-adapters.mjs --target generic --out /path/to/your/project| Target | Commands | Rules |
|---|---|---|
cursor |
.cursor/commands/draftsman-*.md → /draftsman-start … |
.cursor/rules/draftsman.mdc |
copilot |
.github/prompts/draftsman-*.prompt.md → /draftsman-start … |
.github/instructions/draftsman.instructions.md |
generic |
.draftsman/commands/*.md |
.draftsman/AGENTS.snippet.md (paste into AGENTS.md) |
See docs/adapters.md for what changes outside Claude Code.
examples/fnol-intake is a complete session for an auto insurance first-notice-of-loss service. It scored T2 Standard, turned down microservices because their unlock condition wasn't met, and finished at 8 of 10 budget points with a RIGHT-SIZED verdict.
.claude-plugin/ plugin.json, marketplace.json
skills/ start, clarify, options, decide, doc, review, status, evolve (commands)
rightsizing, design-catalog, domain-insurance (background knowledge)
agents/ surveyor (repo + org-tooling scan), researcher (live best-practice lookup),
drafter (design author), inspector (independent reviewer)
rules/ core-rules.md: workflow gates and anti-drift rules
templates/ requirements, options, ADR, design, review, current state, session state
scripts/ validate.mjs, build-adapters.mjs
evals/ right-sizing regression cases for `claude plugin eval`
examples/ fnol-intake
Session files are written to docs/design/<slug>/ in your project, so designs are reviewed and versioned like code.
If your repo has an AgentAtlas map (SYSTEM.md and .agentatlas/atlas.yaml), or the agentatlas MCP server is connected, the surveyor starts from it, so Draftsman designs against your real system instead of a blank slate.
Two things keep Draftsman from designing in a vacuum:
- Org tooling. Before proposing something new, the surveyor checks whether any connected MCP tool looks like an internal search, catalog, or wiki, and queries it for an existing solution. If none is connected, it asks once instead of assuming a build is needed.
- Live research.
design-catalogis a hand-curated, versioned reference — it can go stale. When/draftsman:optionshits a decision point the catalog doesn't cover, or the user asks to double-check current practice, theresearcheragent looks it up instead of guessing from training data. It uses only verified, trusted sources, listed intrusted-sources.md: official vendor and project documentation (for facts about their own products only), cloud architecture centers, standards bodies, and regulators. Every search is restricted withallowed_domains. Blogs, forums, listicles, and vendor "X vs Y" pages are excluded. If no trusted source covers a claim, the claim is dropped. Every researched option is marked estimated and cites its source and date. To add your organization's own trusted domains, create.draftsman/trusted-sources.mdin your project.
npm run validate # structural checks, including eval cases (no dependencies)
npm run build:adapters # generate all adapters into ./dist
npm run eval:quick # right-sizing evals: 1 run per case, plugin only
npm run eval # full evals: 3 runs per case, with and without the plugin
claude plugin validate . --strict
claude --plugin-dir . # try the plugin locallySee evals/README.md for what each eval case checks and how to read the scores.
See CONTRIBUTING.md and the roadmap.
MIT