From e0a145405bd1904966be6f3acef031d4d112a168 Mon Sep 17 00:00:00 2001 From: Ankur <04.ankur@gmail.com> Date: Wed, 29 Apr 2026 22:17:28 +0530 Subject: [PATCH] =?UTF-8?q?Tighten=20README=20=E2=80=94=20cut=20redundant?= =?UTF-8?q?=20sections,=20fix=20stale=20copy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README had three structural redundancies and a couple of stale claims that snuck through the api / inquirer drops. This pass tightens it from ~287 lines to ~204 (-29%) without losing substance. Structural cleanup: the "Four things you'll actually use this for" section restated "How Draftwise helps" in different words β€” merged into one JTBD-flavored section that names the moment AND the concrete command. The "What you get from each command" bullet section restated the Commands table β€” dropped. The Roadmap section's "v1 commands shipped on npm as of 0.0.1; next published release will be 0.1.0 after end-to-end smoke testing" claim was stale (we're on 0.2.1) and the checked-box list added no signal β€” dropped entirely. Killed a duplicated "πŸ—ΊοΈ Explains" heading at the top of "How Draftwise helps" (one had a body, one was an empty stub). Copy fixes: scaffold.json provenance was "written by init in greenfield mode" β€” that's wrong post-api-drop; init prints a handoff and the host coding agent writes scaffold.json. Updated to "structured stack data for draftwise scaffold" without attributing the writer. The `draftwise scaffold` command line in the table also drops the now-stale "confirms before writing" wording β€” `--yes` is required upfront. The slash-commands install paragraph was a dense block; collapsed the marketplace alternative under a `
` and led with the recommended `skills install` snippet. Tone: kept the empathetic "The problem" framing but compressed six emoji-headed sections to three tight paragraphs that say the same thing without padding. Philosophy block, spec template details, and shields row stayed verbatim. --- README.md | 228 +++++++++++++++++------------------------------------- 1 file changed, 73 insertions(+), 155 deletions(-) diff --git a/README.md b/README.md index af8c254..9e8acbb 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,15 @@

From idea to shipped spec β€” grounded in real code.
-Draftwise helps PMs and product builders go from a blank directory or an existing repo to a thought-through plan, then to specs that fit. +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 +The problem Β· +How it helps Β· +Quick start Β· +Commands Β· +Philosophy

@@ -21,124 +22,97 @@ Draftwise helps PMs and product builders go from a blank directory or an existin ## The problem -Every product team hits the same wall: **the codebase knows things the team doesn't.** +**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. -#### πŸ“œ Old specs are stale -PMs writing a new spec end up doing detective work β€” clicking through the app, pinging engineers, reading PRs β€” just to figure out how the feature actually works today. Hours of work before any writing starts. +**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. -#### πŸ” Skipping the detective work backfires -Specs based on outdated assumptions trigger back-and-forth the moment dev picks them up. *"This isn't how it works anymore."* *"That endpoint was deprecated."* The spec gets rewritten during code review. - -#### 🧭 New PMs fly blind for months -Joining a team means inheriting a product you didn't build. Old specs don't match the code. Engineers are busy. Weeks pass before you have a working mental model β€” and every spec written in that time is shaky. - -#### πŸ«₯ Specs get written in a vacuum -Without deep knowledge of the codebase, PMs reach for generic language. They miss components that already exist, propose duplicates of shipped features, or specify changes to systems they don't understand. - -#### πŸ”§ Engineers redo the work -A generic spec arrives. Engineers redraft it in their head against the real code β€” figuring out which components exist, working out data model implications, catching missed edge cases. Half the time, what ships isn't what was specced. - -#### πŸ”„ Six months later, the cycle repeats -Knowledge about how the product is actually built lives only in code and in people's heads. The next PM starts the same loop. Same stale docs, same detective work, same drift. +**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. --- ## How Draftwise helps -Draftwise meets you where your project is β€” whether you're staring at a blank directory or trying to make sense of a repo someone else built. - -#### 🌱 Starts you on the right stack (greenfield) -`draftwise init` in a fresh directory walks you through clarifying questions, then proposes 2-3 stack options with rationale, pros, cons, a directory structure, and the exact setup commands to run. No more "should I use Next or Remix?" tab-shopping. - -#### πŸ—ΊοΈ Explains an existing product back to you (brownfield) - -#### πŸ—ΊοΈ Explains your product back to you -`draftwise scan` gives you a structured overview of what's in your codebase: major flows, API surface, data model, components, how they connect. New PMs catch up in an afternoon, not three weeks. - -#### πŸ”Ž Traces the current behavior of any feature -Ask Draftwise *"how does checkout work today?"* and it walks the actual code β€” routes hit, services called, data written, side effects triggered. No more pinging engineers to verify how something works. - -#### 🧩 Reads your repo before drafting anything -Every spec Draftwise generates references real entities from your codebase β€” actual file paths, real endpoints, real schema names β€” not generic placeholders. - -#### πŸ’¬ Guides you through a structured brainstorm -No blank template. Draftwise walks you through what matters β€” problem, users, acceptance criteria, scope, edge cases, metrics β€” while keeping codebase context in view. You answer in plain language. It does the structuring. +Draftwise meets you where the project is β€” blank directory or existing repo. -#### βœ‚οΈ Separates product specs from technical specs -Product spec: what & why, readable by anyone. Technical spec: how, grounded in your real code. Same feature, two lenses, two audiences. +#### 🌱 Starting a new project from scratch +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. -#### πŸ“ Saves everything in your repo -Specs and codebase summaries live as markdown files in `.draftwise/`. Version-controlled, searchable, alongside the code. No Drive folders. No drift. +#### πŸ—ΊοΈ Catching up on a product you didn't build +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. ---- - -## Four things you'll actually use this for - -**Starting a new project from scratch.** You have an idea but no code yet. `draftwise init` walks you through what you want to build, asks the questions a sharp engineer would ask, and proposes 2-3 stack options with rationale, pros, cons, directory structure, and setup commands. Pick one and start coding. - -**Catching up on a product you didn't build.** New job, new team, new repo. `draftwise scan` gives you a structured tour of the product as it actually exists β€” flows, surfaces, data, components. Your first week becomes productive instead of theoretical. - -**Understanding the current state before drafting.** Before you write a spec for a change, ask Draftwise how the existing flow works. Get the truth from the code, not from a six-month-old PRD. Avoid proposing things that already exist or changes that conflict with how the system actually behaves. +#### πŸ”Ž Understanding the current state before drafting +Before specifying a change, ask `draftwise explain `. 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. -**Drafting specs that engineers don't have to redo.** When you write a new feature spec, Draftwise grounds it in real components, real endpoints, real schemas. The handoff to engineering is faster because the spec already speaks the codebase's language. +#### 🧩 Drafting specs engineers don't have to redo +`draftwise new ""` 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. --- ## Quick start -Draftwise runs inside your AI coding agent (Claude Code, Cursor, Gemini CLI, Antigravity, Copilot, etc.). The CLI scans the codebase and prints an instruction; your agent does the spec drafting. +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. ```bash npm install -g draftwise -cd your-project # existing repo, or an empty directory for a new project +cd your-project # existing repo, or an empty directory draftwise init ``` -**Optional β€” slash commands inside your AI harness.** Two install paths, same skill, different slash-command shape: +`draftwise init` checks the directory for source files and routes accordingly: -- **Bare `/draftwise ` (recommended β€” matches the CLI binary).** After `npm install -g draftwise`, run: - ``` - draftwise skills install - ``` - Auto-detects which harnesses you have on this machine (by checking for `~/.claude/`, `~/.cursor/`, `~/.gemini/`) and installs the standalone skill only to those β€” slash form `/draftwise init`, `/draftwise new ""`, etc. Pass `--provider=all` to install everywhere regardless of detection, `--provider=claude|cursor|gemini` to target one explicitly, or `--scope=project` to write at `/./skills/draftwise/` instead of the user-level dir. `draftwise skills help` shows what's installed where (and which harnesses auto-detect would target); `draftwise skills uninstall` removes it. -- **`/draftwise:draftwise ` via the Claude Code plugin marketplace.** If you prefer Claude Code's `/plugin` workflow: - ``` - /plugin marketplace add 4nkur/draftwise - /plugin install draftwise - ``` - Claude Code namespaces all plugin skills as `:`, so the chat form is `/draftwise:draftwise ` regardless of install scope. (Claude Code only β€” Cursor / Gemini users want the standalone path above.) +- **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`. Run `draftwise scaffold --yes` next to create the initial files. +- **Existing codebase:** scans the repo, writes an `overview.md` placeholder, and tells you to run `draftwise scan` next. -Both paths shell out to the same `draftwise` CLI β€” install Draftwise via npm first. The two paths are independent and may coexist. +Detection is automatic; pass `--mode=greenfield|brownfield` to override. Either way, `.draftwise/` ends up with `overview.md` and `config.yaml`. From there: -`draftwise init` checks the directory for source files and picks the right path: - -- **New project (no code yet):** describe the idea β†’ answer 4-6 clarifying questions β†’ pick from 2-3 stack options β†’ get a plan with directory structure and setup commands. Optional: `draftwise scaffold` to create the user-written initial files automatically. -- **Existing codebase:** scans the repo and writes an overview of flows, routes, components, and models. +```bash +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 spec +``` -The detection is automatic; pass `--mode=greenfield` or `--mode=brownfield` to override (these stay as the canonical flag values). Either way, you end up in `.draftwise/` with `overview.md` and `config.yaml`. From there: +### Slash commands inside your AI harness ```bash -draftwise scan # refresh the codebase overview (brownfield only) -draftwise explain checkout # walk a specific flow (brownfield only) -draftwise new "your feature idea" # draft a new spec +draftwise skills install # auto-detects ~/.claude, ~/.cursor, ~/.gemini +draftwise skills install --provider=all # write to every known dir +draftwise skills help # see what's installed where +``` + +The slash form is bare `/draftwise init`, `/draftwise new ""`, 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 `:`, so the slash form is `/draftwise:draftwise `. Both paths are independent and may coexist. +
--- ## Commands | Command | What it does | -|---------|-------------| -| `draftwise init` | Set up `.draftwise/`. Asks whether the project is greenfield or brownfield and routes accordingly β€” either a stack-recommendation conversation or a codebase scan. | -| `draftwise scaffold` | Create the user-written initial files from a greenfield plan. Reads `.draftwise/scaffold.json` (written by `init` in greenfield mode), confirms before writing, and skips existing files. | -| `draftwise scan` | Refresh the structured codebase overview (brownfield). | -| `draftwise explain ` | Walk through how a specific flow works today, traced from the actual code (brownfield). | -| `draftwise new ""` | Conversational drafting β€” generates a product spec grounded in the codebase or the greenfield plan. | -| `draftwise tech []` | Drafts a technical spec from the product spec, referencing real files and endpoints. | -| `draftwise tasks []` | Generates implementation tasks from the tech spec, ordered by dependency. | +|---------|--------------| +| `draftwise init` | Set up `.draftwise/`. Auto-detects greenfield vs brownfield (override with `--mode`). | +| `draftwise scan` | Refresh the codebase overview (brownfield). | +| `draftwise explain ` | Trace a specific flow through the code (brownfield). | +| `draftwise new ""` | Draft a product spec β€” clarifying questions plus grounded synthesis. | +| `draftwise tech []` | Technical spec from the product spec, grounded in real files. | +| `draftwise tasks []` | Implementation tasks from the tech spec, dependency-ordered. | +| `draftwise scaffold --yes` | Create initial files from a greenfield plan. | | `draftwise list` | List all specs in `.draftwise/specs/`. | -| `draftwise show [type]` | Show a specific spec (type: `product`, `tech`, or `tasks`; default: `product`). | +| `draftwise show [type]` | Show a spec (`product`, `tech`, or `tasks`; default: `product`). | +| `draftwise skills ` | Manage standalone slash-command skills. | + +Run `draftwise --help` for the per-command flag list. --- @@ -146,54 +120,21 @@ draftwise new "your feature idea" # draft a new spec ``` .draftwise/ -β”œβ”€β”€ .gitignore # written by init; keeps the cache out of version control -β”œβ”€β”€ overview.md # codebase summary (brownfield) or greenfield plan -β”œβ”€β”€ scaffold.json # greenfield only: structured stack data for `draftwise scaffold` +β”œβ”€β”€ .gitignore # written by init; keeps the cache out of version control +β”œβ”€β”€ overview.md # codebase summary (brownfield) or greenfield plan +β”œβ”€β”€ scaffold.json # greenfield only; structured stack data for `draftwise scaffold` β”œβ”€β”€ specs/ -β”‚ └── add-collaborative-albums/ -β”‚ β”œβ”€β”€ product-spec.md # what & why -β”‚ β”œβ”€β”€ technical-spec.md # how β€” grounded in your code (or "(new)" for greenfield) -β”‚ └── tasks.md # ordered breakdown +β”‚ └── / +β”‚ β”œβ”€β”€ 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 that invalidates on any code change.) - ---- - -## What you get from each command - -**`draftwise scan`** β€” a structured codebase overview: -- Major flows in the product (signup, checkout, sharing, etc.) -- API surface (endpoints, methods, what they do) -- Data model (key tables, key relationships) -- Component map (what's in your UI, how it's organized) -- Integrations and external dependencies - -**`draftwise explain `** β€” a traced walkthrough: -- The entry points (routes, UI events, scheduled jobs) -- The services and functions involved -- The data read and written -- Side effects (emails, webhooks, async jobs) -- Edge cases the code actually handles - -**`draftwise new`** β€” a product spec with: -- Problem with evidence -- User stories & acceptance criteria -- Flows, touchpoints, edge cases -- Scope: covered, assumed, hypothesized, out of scope -- Core metrics & counter metrics - -**`draftwise tech`** β€” a technical spec grounded in real code: -- Data model changes (your actual schema) -- API changes (your actual conventions) -- Component changes (your actual files) -- Migration notes & test plan +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.) --- -## Spec templates -
Product spec sections @@ -230,25 +171,21 @@ Test plan β†’ unit, integration, E2E ## Agent compatibility -Draftwise is designed to be host-agnostic β€” the CLI prints structured scanner data and an instruction string; the host's model handles the reasoning and writes the spec. In principle that works with any agentic IDE or CLI: - -Claude Code Β· GitHub Copilot Β· Cursor Β· Gemini CLI Β· Codex CLI Β· Antigravity Β· Windsurf Β· Amp Β· Roo Code Β· Kilo Code Β· OpenCode Β· Qoder - -In practice it has only been smoke-tested in a plain terminal so far. If you run it inside one of these and something breaks, please open an issue. +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. That's what makes the agent integration possible: a slash-command wrapper (or any host agent) collects answers in chat and re-invokes `draftwise ` with `--mode=...`, `--idea="..."`, `--yes`, etc. Run `draftwise --help` for the per-command flag list. `draftwise init` greenfield without `--idea` is the one case that prints a structured handoff instead of erroring β€” copy it into your AI assistant if you're not already inside one. +**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 ` 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. --- ## Philosophy ``` -β†’ the codebase is the source of truth β€” not the docs (when there is 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 +β†’ 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 @@ -258,28 +195,9 @@ In practice it has only been smoke-tested in a plain terminal so far. If you run --- -## Roadmap - -v1 commands are all shipped on `npm` as of `0.0.1`. The next published release will be `0.1.0` after end-to-end smoke testing on a sample repo. - -- [x] `init` β€” `.draftwise/` setup, with greenfield (stack recommendation) and brownfield (codebase scan) routing -- [x] `scan` β€” structured product overview (brownfield); friendly short-circuit in greenfield -- [x] `explain` β€” traced walkthroughs of specific flows (brownfield); friendly short-circuit in greenfield -- [x] `new` β€” conversational spec drafting, greenfield-aware (drops affected_flows / adjacent_opportunities when there's no code yet) -- [x] `tech` β€” technical spec, greenfield-aware (every file marked `(new)`, follows the planned directory structure) -- [x] `tasks` β€” dependency-ordered breakdown, greenfield-aware (first 1-3 tasks are project setup before feature work) -- [x] `list` and `show` β€” spec browsing utilities -- [x] optional file scaffolding from `init`'s greenfield plan via `draftwise scaffold` - -**Next:** scanner framework support beyond JS/TS and Python (Go, Rust, mobile codebases), and richer flow tracing for very large repos. - ---- - ## Contributing -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 β€” we'd love your perspective. Open a discussion. +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. ## License