@pmelab/gtd 6.13.0 → 7.0.0

package/README.md

@@ -49,28 +49,28 @@ Or run without installing:
 npx @pmelab/gtd
 ```
 
-Then scaffold the workflow for the repo — run once:
+That's it — gtd ships the **unified** workflow as its **built-in default**, so a
+state command works out of the box with no configuration at all.
+
+Optionally, seed the settings a project usually tunes — run once:
 
 ```bash
 gtd init
 ```
 
-This writes a `.gtdrc.json` for the bundled unified workflow, with each agent
-state's prompt saved as an editable Markdown file under `gtd-prompts/` and
-referenced from the config (review and commit both). Edit a prompt by editing
-its `gtd-prompts/*.md` file — no config edit needed. File references resolve
-relative to **the `.gtdrc` that declares them**, so a config and its
-`gtd-prompts/` can even live in a parent directory shared across repos while gtd
-runs from each repo root — run `gtd init` from that parent directory (it need
-not be a git repo) to scaffold it there (see
-[Configuration](docs/configuration.md#content-values-inline-or-a-file-reference)).
-It also seeds a top-level `modes:` block suggesting **Prettier** as the
-steering-file formatter (`npx prettier --write` for the built-in `qa`/`review`
-modes — format only, so gtd still validates); edit or drop it freely (swap in
-dprint, a script, or delete the key). `gtd init` takes no argument. gtd ships
-**no** default workflow: a state command run before `gtd init` fails, pointing
-you back here. See [Configuration](docs/configuration.md#gtd-init) for the
-template.
+This writes a minimal `.gtdrc.json` seeding the one variable most projects
+change — the test command (`vars.testCommand`, defaulting to `npm test`) — plus
+a top-level `modes:` block suggesting **Prettier** as the steering-file
+formatter (`npx prettier --write` for the built-in `qa`/`review` modes — format
+only, so gtd still validates); edit or drop either freely (point `testCommand`
+at your suite, swap Prettier for dprint or a script, delete a key). It writes
+**no** `workflow:` key — the machine is built in — so review and commit the file
+before your first `gtd step`. `gtd init` takes no argument and refuses to
+clobber an existing config; it may also run in a plain parent directory (not a
+git repo) to seed a shared config a nested repo picks up. To customize the
+machine itself, add a `workflow:` key (there is no default fallback to merge
+over — a `workflow:` is the whole definition). See
+[Configuration](docs/configuration.md#gtd-init) for the details.
 
 ## How it works
 
@@ -111,12 +111,15 @@ and tells you to repair it first (that's what `gtd fix` is for). The two
 steering-file entries are chosen by which file you create:
 
 - Create **`.gtd/TODO.md`** with a short sketch to start the **simple** flow: an
-  agent develops your sketch into a plan — asking any open question it can't
-  settle itself via a deterministic `.gtd/TODO.md` format, validated before it
-  ever reaches you — you answer inline, then it builds the plan in one turn and
+  agent develops your sketch into a concrete plan — deciding open points itself
+  rather than asking questions — and hands it back for you to accept as-is or
+  edit. Editing sends it round again; accepting builds the plan in one turn and
   runs your tests (looping on failures).
 - Create **`.gtd/REQUIREMENTS.md`** to start the **advanced** flow: two-phase
-  product then technical Q&A (`.gtd/REQUIREMENTS.md` → `.gtd/ARCHITECTURE.md`),
+  product then technical Q&A (`.gtd/REQUIREMENTS.md` → `.gtd/ARCHITECTURE.md`) —
+  each open question offers a couple of candidate answers plus a
+  `- [ ] _your answer_` slot, and you tick exactly one per question (the gate
+  won't let a phase advance while any question is unanswered) — then
   decomposition into work **packages** (each a set of independent tasks a single
   build turn fans out to parallel subagents), a per-package test loop, and a
   per-package **agentic review** that verifies the package against its spec.
@@ -168,8 +171,8 @@ points at (at its `#line`), symbols over a `qa`-mode file's open questions,
 diagnostics for both (live as you edit), and a `gtd.openSteeringFile` command
 that jumps to the current state's steering file. Config-driven via each state's
 `file:`/`mode:` (see [CLI reference](docs/cli.md#gtd-lsp)) — falls back to
-basename dispatch (`TODO.md`/`REVIEW.md`) with no config in sight. Those two
-formats are gtd's built-in steering-file MODES — validators, not formatters: a
+basename dispatch (`REVIEW.md` → `review`) with no config in sight. `qa` and
+`review` are gtd's built-in steering-file MODES — validators, not formatters: a
 mode's `format:` and `validate:` are shell commands a workflow (or a project's
 `.gtdrc`) declares for itself, so you bring your own formatter and your own
 checkers (see