From idea to shipped spec — grounded in real code.
Turn a blank directory or an existing repo into specs your engineers won't have to redo.
The problem · How it helps · Quick start · Commands · Philosophy
The codebase knows things the team doesn't. PMs writing a spec spend hours on detective work — clicking through the app, pinging engineers, reading PRs — just to figure out how a feature actually works today. Skip the detective work and the spec gets rewritten in code review.
New PMs fly blind for months. Old specs don't match the code. Engineers are busy. Weeks pass before there's a working mental model — and every spec written in that time is shaky.
Engineers redo the work. A generic spec arrives. Engineers redraft it in their head against the real code. Half of what ships isn't what was specced. Six months later, the next PM repeats the loop.
Draftwise meets you where the project is — blank directory or existing repo.
You have an idea but no code yet. draftwise init hands the idea to your coding agent, which walks you through clarifying questions and proposes 2-3 stack options (rationale, pros, cons, directory structure, setup commands). Pick one and start coding. Optional: draftwise scaffold --yes creates the initial files.
New job, new team, new repo. draftwise scan reads the codebase and writes a structured overview — flows, API surface, data model, components, integrations. Your first week becomes productive instead of theoretical.
Before specifying a change, ask draftwise explain <flow>. The CLI walks the actual code — routes hit, services called, data written, edge cases handled. Avoid proposing things that already exist or changes that conflict with how the system actually behaves.
draftwise new "<idea>" walks the conversation through clarifying questions and accept/decline opportunities, then writes a product spec grounded in real files, endpoints, and schemas — not generic placeholders. draftwise tech and draftwise tasks follow with the engineering counterparts. New code paths get a (new) marker so reviewers can tell intent from existing state at a glance.
Draftwise runs inside your AI coding agent (Claude Code, Cursor, Gemini CLI, Antigravity, Copilot, etc.). The CLI scans your repo and prints an instruction; the agent does the drafting.
npm install -g draftwise
cd your-project # existing repo, or an empty directory
draftwise initdraftwise init checks the directory for source files and routes accordingly:
- New project (no code yet): prints clarifying questions for your agent. The agent walks you through stack selection (2-3 options) and writes the chosen plan + setup commands to
.draftwise/overview.md. Rundraftwise scaffold --yesnext to create the initial files. - Existing codebase: scans the repo, writes an
overview.mdplaceholder, and tells you to rundraftwise scannext.
Detection is automatic; pass --mode=greenfield|brownfield to override. Either way, .draftwise/ ends up with overview.md and config.yaml. From there:
draftwise scan # refresh codebase overview (brownfield only)
draftwise explain checkout # trace a specific flow (brownfield only)
draftwise new "your feature idea" # draft a product spec
draftwise tech # technical spec from the product spec
draftwise tasks # ordered work breakdown from the tech specdraftwise skills install # auto-detects ~/.claude, ~/.cursor, ~/.gemini
draftwise skills install --provider=all # write to every known dir
draftwise skills help # see what's installed whereThe slash form is bare /draftwise init, /draftwise new "<idea>", etc. — matches the CLI binary.
Or via the Claude Code plugin marketplace
/plugin marketplace add 4nkur/draftwise
/plugin install draftwise
Claude Code namespaces plugin skills as <plugin>:<skill>, so the slash form is /draftwise:draftwise <verb>. Both paths are independent and may coexist.
| Command | What it does |
|---|---|
draftwise init |
Set up .draftwise/. Auto-detects greenfield vs brownfield (override with --mode). |
draftwise scan |
Refresh the codebase overview (brownfield). |
draftwise explain <flow> |
Trace a specific flow through the code (brownfield). |
draftwise new "<idea>" |
Draft a product spec — clarifying questions plus grounded synthesis. |
draftwise clarify [<feature>] |
Audit a product spec for ambiguities, untested assumptions, and missing edge cases; rewrite in place. |
draftwise tech [<feature>] |
Technical spec from the product spec, grounded in real files. |
draftwise tasks [<feature>] |
Implementation tasks from the tech spec, dependency-ordered. |
draftwise refine [<feature>] [--type=...] |
Re-ground an existing spec (product / tech / tasks) while preserving PM hand-edits — only weak sections get rewritten. |
draftwise scaffold --yes |
Create initial files from a greenfield plan. |
draftwise list |
List all specs in .draftwise/specs/. |
draftwise show <feature> [type] |
Show a spec (product, tech, or tasks; default: product). |
draftwise skills <install|uninstall|help> |
Manage standalone slash-command skills. |
Run draftwise <command> --help for the per-command flag list.
.draftwise/
├── .gitignore # written by init; keeps the cache out of version control
├── constitution.md # voice + spec-quality rules — edit to suit your project
├── overview.md # codebase summary (brownfield) or greenfield plan
├── scaffold.json # greenfield only; structured stack data for `draftwise scaffold`
├── specs/
│ └── <feature-slug>/
│ ├── product-spec.md # what & why
│ ├── technical-spec.md # how — grounded in real code (or "(new)" for greenfield)
│ └── tasks.md # ordered work breakdown
└── config.yaml
Markdown. Version-controlled. Travels with your repo. (Draftwise also writes a .cache/ folder that's gitignored automatically — fingerprint-based scan cache, invalidates on any code change.)
Product spec sections
Optional YAML frontmatter at the top of product-spec.md declares cross-spec relationships, surfaced in draftwise list's DEPENDS ON column:
---
depends_on: [auth, billing] # specs that must ship before this one
related: [profile-page] # same area; not a hard dependency
---Problem → what's broken, with evidence
User stories → who wants what and why
Acceptance criteria → given / when / then
Flows & touchpoints → UI/UX, screen copy, interactions
Edge cases → what happens when things go wrong
Test cases → product-level scenarios
Scope: covered → what this includes
Scope: assumed → what we're taking as given
Scope: hypothesized → what we believe but haven't proven
Scope: out of scope → what this explicitly excludes
Core metrics → what success looks like
Counter metrics → what could go wrong if we succeed
Technical spec sections
Summary → what & why, references the product spec
Data model changes → tables, columns, migrations
API changes → new & modified endpoints
Component changes → new & modified files
Migration notes → deployment considerations
Test plan → unit, integration, E2E
Draftwise is host-agnostic — the CLI prints scanner data and an instruction; the host's model handles the reasoning and writes the spec. In principle that works with any agentic IDE: Claude Code, Cursor, Gemini CLI, Codex CLI, Antigravity, Copilot, Windsurf, Amp, Roo Code, Kilo Code, OpenCode, Qoder. In practice only the plain terminal has been smoke-tested — open an issue if you hit something.
Flags-driven, never blocks. Every command takes its input via flags or positional args; missing required input errors with a usage hint instead of waiting on stdin. A slash-command wrapper (or any host agent) collects answers in chat and re-invokes draftwise <command> with the right flags. draftwise init greenfield without --idea prints a structured handoff for the agent — copy it into your AI assistant if you're not already inside one.
→ the codebase is the source of truth — not the docs
→ for brand-new projects, the conversation is the source of truth — not boilerplate
→ understand what exists before deciding what to change
→ ask the right questions, don't hand over a blank template
→ propose options with rationale; let the human pick
→ product specs are jargon-free; tech specs are codebase-grounded
→ specs live with the code, not in someone's Drive
→ AI is a thought partner first, document generator second
→ push back on weak ideas; don't validate them — better outputs come from real friction
→ flag bad assumptions before drafting; mark uncertain claims; offer the counter-case on big decisions
→ extend what exists before adding new files / routes / components
Early days. Issues, ideas, and PRs welcome. If you've ever inherited a product you didn't build, or written a spec that didn't match the code — open a discussion.
MIT