@pmelab/gtd 6.13.0 → 7.0.0

package/docs/cli.md

@@ -4,12 +4,12 @@
 Usage: gtd [command] [options]
 
 Commands:
-  init             Scaffold a .gtdrc.json for this repo with the bundled
-                   unified workflow; its agent prompts are written as editable
-                   Markdown under gtd-prompts/ and referenced from the config.
-                   Takes no argument. Run once per repo; refuses if a gtd
-                   config already exists. Leaves the files uncommitted for you
-                   to review and commit
+  init             Scaffold a minimal .gtdrc.json for this repo, seeding a
+                   testCommand var (npm test) and a ready-to-edit Prettier
+                   formatting suggestion under modes:. Writes no workflow — gtd
+                   runs the bundled unified workflow as its built-in default.
+                   Takes no argument. Refuses if a gtd config already exists.
+                   Leaves the file uncommitted for you to review and commit
   step <actor>     Authenticate as <actor>, match the resolved rest's
                    declared patterns against the pending changes, and commit
                    (or squash) the one resulting transition. Pass
@@ -65,31 +65,34 @@ mistyped flag can never degrade a JSON caller to plain-text mode. A bare
 
 ## `gtd init`
 
-Scaffolds a `.gtdrc.json` at the repository root with the bundled **unified**
-workflow template inline under a `workflow:` key, plus a `$schema` link. It
-takes **no argument** — passing one is a usage error
-(`gtd init: too many arguments — init takes no argument`). gtd ships **no**
-default workflow, so this is the one-time setup step for a repo; a state command
-run before it fails with `gtd: no workflow configured — run \`gtd init\` to
-create .gtdrc.json`.
-
-The unified template has four entry points — each behind a green-baseline gate
+Scaffolds a **minimal** `.gtdrc.json` at the repository root, plus a `$schema`
+link. It writes **no** `workflow:` key — gtd runs the bundled **unified**
+workflow as its built-in default, so a state command works out of the box with
+no config and no init at all. What `gtd init` seeds is the two things most
+projects tune: a `vars: { "testCommand": "npm test" }` entry (the var the
+bundled workflow's check script reads) and a ready-to-edit `modes:` block
+suggesting a Prettier `format:` for each built-in steering-file mode
+(`qa`/`review`). It takes **no argument** — passing one is a usage error
+(`gtd init: too many arguments — init takes no argument`).
+
+The bundled default has four entry points — each behind a green-baseline gate
 that runs the suite before starting — into one shared review/squash tail (see
 [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)): creating
-`.gtd/TODO.md` starts the simple flow (grilling → building → checking), creating
+`.gtd/TODO.md` starts the simple flow (planning → building → checking), creating
 `.gtd/REQUIREMENTS.md` starts the advanced flow (two-phase Q&A planning,
 per-package parallel build, agentic spec-review), `gtd review <commitish>`
 enters review directly, and `gtd fix` goes straight into repairing failing
 tests. A red baseline halts at a `*-start-blocked` gate rather than starting new
-work.
+work. To CUSTOMIZE that machine, add your own `workflow:` key (a full definition
+— there is no `extends`/merge); see
+[Configuration](configuration.md#the-workflow-key).
 
 The file is written **uncommitted**; review and commit it before your first
 `gtd step` (an uncommitted `.gtdrc.json` is a pending change the initial state
 would otherwise capture). `gtd init` refuses if the repo root already has its
-own gtd config (a global/ancestor config, e.g. `~/.gtdrc`, does not count),
-requires the repository root, and — with `gtd lsp` — is one of the two commands
-that run with no workflow configured. `--json` prints
-`{"written":".gtdrc.json","workflow":"unified","prompts":[…]}`. See
+own gtd config (a global/ancestor config, e.g. `~/.gtdrc`, does not count) and
+requires the repository root (or a directory outside any repo). `--json` prints
+`{"written":".gtdrc.json","inRepo":true}`. See
 [Configuration](configuration.md#gtd-init).
 
 ## `gtd step <actor> [--cost=<n>] [--model=<name>]`
@@ -126,7 +129,7 @@ to `--json`.
 Plain-mode output is one line:
 
 ```
-committed: gtd(human): idle → grilling
+committed: gtd(human): idle → planning
 ```
 
 or, at a no-op:
@@ -142,7 +145,7 @@ not passed):
 ```json
 {
   "state": "idle",
-  "subject": "gtd(human): idle → grilling",
+  "subject": "gtd(human): idle → planning",
   "cost": 1450,
   "model": "claude-opus-4-8"
 }
@@ -385,7 +388,7 @@ agent or human:
   declares `file:`+`mode:` formats that file in place and validates it first
   (with the very same mode commands), and **refuses the step** (committing
   nothing) when it is invalid — so a human's edit at a gate (answering at
-  `grilling-answer`, reviewing at `await-review`) is formatted and checked
+  `adv-grilling-answer`, reviewing at `await-review`) is formatted and checked
   exactly like an agent's draft, and a malformed steering file is never
   committed.
 
@@ -409,10 +412,10 @@ output is identical regardless of the current process/branch state.
 $ gtd mermaid
 stateDiagram-v2
     state "idle" as idle
-    state "grilling" as grilling
+    state "planning" as planning
     ...
     [*] --> idle
-    idle --> grilling : * **
+    idle --> planning : * **
     ...
     note right of idle : human · message
     ...
@@ -425,7 +428,7 @@ Mermaid-aware renderer (GitHub, GitLab, VS Code, Obsidian, the
 
 State names are aliased to Mermaid-safe identifiers (non-word characters fold to
 `_`; a digit-led name gets an `s_` prefix) via a `state "<name>" as <alias>`
-declaration up front, so a hyphenated name like `grilling-answer` still displays
+declaration up front, so a hyphenated name like `plan-review` still displays
 with its exact declared spelling. Rejects `--json` (exit 1,
 `gtd mermaid does not accept --json`) — there is no structured shape to emit
 beyond the Mermaid source itself — and takes no arguments (extra positional args
@@ -460,11 +463,11 @@ naming the state instead — bind it to an editor keybinding for a "jump to the
 active steering file" command.
 
 Dispatched before the repository-root guard and the config-reading path — the
-server needs no git/workflow state of its own (like `gtd init`, it runs with no
-workflow configured). Rejects `--json` (exit 1,
-`gtd lsp does not accept --json`) and extra positional arguments — it's a
-long-running server, not a state command. Runs until the client disconnects (the
-LSP `exit` notification), then exits cleanly.
+server needs no git/workflow state of its own (like `gtd init`, it needs no
+config to run). Rejects `--json` (exit 1, `gtd lsp does not accept --json`) and
+extra positional arguments — it's a long-running server, not a state command.
+Runs until the client disconnects (the LSP `exit` notification), then exits
+cleanly.
 
 ## Error envelope
 

package/docs/configuration.md

@@ -1,12 +1,15 @@
 # Configuration
 
-gtd reads a required `.gtdrc` config file via
-[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). gtd ships **no**
-default workflow: scaffold one for the repo with [`gtd init`](#gtd-init) (once),
-which writes a `.gtdrc.json` for a bundled workflow template (with its agent
-prompts as editable Markdown under `gtd-prompts/`). A state command run with no
-`workflow:` configured fails, pointing you at `gtd init`. Supported filenames
-(searched in this order):
+gtd reads an optional `.gtdrc` config file via
+[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). gtd ships the bundled
+**unified** workflow as its **built-in default**: with no `workflow:` configured
+anywhere in the cwd→home config chain, that default is used automatically, so a
+state command works out of the box with no config at all.
+[`gtd init`](#gtd-init) is optional — it seeds a minimal `.gtdrc.json` with the
+two things most projects tune (a `testCommand` var and a Prettier formatting
+suggestion), not the workflow. To CUSTOMIZE the machine itself, add your own
+[`workflow:`](#the-workflow-key) key. Supported filenames (searched in this
+order):
 
 - `.gtdrc`
 - `.gtdrc.json`
@@ -19,10 +22,11 @@ prompts as editable Markdown under `gtd-prompts/`). A state command run with no
 
 v3's `.gtdrc` has exactly three blessed top-level keys:
 
-- **`workflow`** (object, **required**) — the whole machine definition (its
-  states, plus its own `vars:` defaults and `modes:`), compiled by
-  `src/PatternConfig.ts`. Absent = a hard error pointing at
-  [`gtd init`](#gtd-init); there is no bundled default. See
+- **`workflow`** (object, optional) — the whole machine definition (its states,
+  plus its own `vars:` defaults and `modes:`), compiled by
+  `src/PatternConfig.ts`. Absent = gtd's built-in default (the bundled unified
+  workflow) is used. Declare it to fully REPLACE that default with your own
+  machine (there is no `extends`/merge). See
   ["The `workflow:` key" below](#the-workflow-key) for its schema.
 - **`vars`** (object, optional) — a flat `name -> scalar` map, one layer of the
   merged `it.vars` every template sees — see ["Variables"](#variables) below.
@@ -52,11 +56,12 @@ interprets.
 > verify a change compiles. This section is the exhaustive schema reference
 > behind it.
 
-The `workflow:` key is the **only** definition source — there is no `extends`,
-no merge-over-a-built-in. The bundled template `gtd init` scaffolds is itself a
-YAML asset (`src/workflows/unified.yaml`) compiled through the exact same
-compiler (`compileWorkflowConfig`); `gtd init` just writes it, inline, under
-this key. Its shape:
+A declared `workflow:` key fully REPLACES gtd's built-in default — there is no
+`extends`, no merge-over-a-built-in. The built-in default is itself a YAML asset
+(`src/workflows/unified.yaml`) compiled through the exact same compiler
+(`compileWorkflowConfig`) your own `workflow:` value goes through — no
+privileged code path — so you can materialize it into config form as a starting
+point to edit (`renderInitConfig` in `src/workflows/templates.ts`). Its shape:
 
 ```yaml
 workflow:
@@ -107,8 +112,8 @@ root, discovers the parent `.gtdrc` by walking up the directory chain (see
 level's `./`-relative references against that level's own directory. When
 workflows are layered across levels, every reference resolves against the file
 that wrote it, so a parent's `./gtd-prompts/x.md` and a child's never collide.
-You can scaffold such a shared config by running [`gtd init`](#gtd-init) from
-that parent directory — it need not be a git repository.
+(This is a capability of a `.gtdrc` you write yourself — `gtd init` seeds only
+`vars:`/`modes:`, not a `workflow:` with file references.)
 
 ```yaml
 workflow:
@@ -156,7 +161,7 @@ workflow:
             "Delete `.gtd/REVIEW.md` to approve the whole cycle and rest at
             idle."
         "* **":
-          to: grilling
+          to: planning
           describe:
             "Change any source file to leave feedback and start another round."
 ```
@@ -214,18 +219,18 @@ Forbidden on a commit state (never at rest):
 ```yaml
 workflow:
   states:
-    grilling:
+    planning:
       actor: agent
       memory: plan
-      prompt: develop the plan; ask open questions
+      prompt: develop the sketch into a concrete plan
       on:
-        "* **": grilling-answer
-    grilling-answer:
+        "* **": plan-review
+    plan-review:
       actor: human
-      message: answer the open questions
+      message: accept the plan, or edit it to iterate
       on:
         "C": building
-        "* **": grilling
+        "* **": planning
     building:
       actor: agent
       memory: build # a different scope — implementation starts fresh
@@ -236,7 +241,7 @@ workflow:
       commit: "feat: done"
 ```
 
-Because `grilling` re-enters itself around the answer loop, every lap emits
+Because `planning` re-enters itself around the review loop, every lap emits
 `memory: plan` and the planner keeps its accumulated exploration; the move to
 `building` emits a different label (`build`), which is where the driver clears
 memory for a fresh implementation turn. A loop of same-labelled turns retains; a
@@ -282,10 +287,10 @@ workflow:
 **steering-file mode**. Two names are BUILT IN, each carrying a VALIDATOR gtd
 implements itself:
 
-| `mode`   | Format                                                                                                                                                                                                  |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `qa`     | The open-questions format (`## Open Questions` near the top and `## Answered Questions` at the bottom, one `###` sub-heading per question with a free-form body; status is positional, no marker line). |
-| `review` | The checkbox review format (`# Review: <hash>` header, `<!-- base: <hash> -->` comment, `##` chunks, `- [ ]` pointers).                                                                                 |
+| `mode`   | Format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `qa`     | The open-questions format (`## Open Questions` near the top and `## Answered Questions` at the bottom, one `###` sub-heading per question with a free-form body; status is positional, no marker line). The bundled advanced flow additionally writes each open question as a checkbox list (candidate answers + a `- [ ] _your answer_` slot) and gates the human's answer step with `answerGate` (exactly one tick per question) — but that convention + gate live in the workflow/edge, not in this validator, which only checks the structure above. |
+| `review` | The checkbox review format (`# Review: <hash>` header, `<!-- base: <hash> -->` comment, `##` chunks, `- [ ]` pointers).                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 Any other name must be declared in a `modes:` map (next section) — as must a
 `format:` command for these two, since gtd ships no formatter. A `mode:` naming
@@ -380,16 +385,17 @@ So for a state declaring `mode: qa`:
 | both                             | its `format:` | its `validate:`             |
 
 That is what makes the built-in modes extensible rather than all-or-nothing —
-and the top-level key means a project can plug its formatter into the workflow
-it scaffolded (`gtd init`) without re-declaring a `modes:` block on the workflow
-itself. **`gtd init` seeds exactly this block by default** (the Prettier
-suggestion below), so a fresh repo already formats its steering files — edit or
-drop it to taste. It sits alongside the `workflow:` key in your `.gtdrc.json`:
+and the top-level key means a project can plug its formatter into the built-in
+default workflow (or its own) without re-declaring a `modes:` block on the
+workflow itself. **`gtd init` seeds exactly this block by default** (the
+Prettier suggestion below), so a fresh repo already formats its steering files —
+edit or drop it to taste. It is what a scaffolded `.gtdrc.json` contains
+(`gtd init` writes no `workflow:` key — the built-in default is used):
 
 ```jsonc
-// .gtdrc.json — the workflow from `gtd init`, plus your own markdown formatter
+// .gtdrc.json — as scaffolded by `gtd init`: a testCommand var and the markdown formatter
 {
-  "workflow": { "...": "..." },
+  "vars": { "testCommand": "npm test" },
   "modes": {
     "qa": { "format": "npx prettier --write <%= it.file %>" },
     "review": { "format": "npx prettier --write <%= it.file %>" },
@@ -702,24 +708,21 @@ can still override with its own `.gtdrc`.
 
 ## `gtd init`
 
-gtd ships **no** default workflow, so a repo must scaffold one before any state
-command works:
+gtd ships the bundled unified workflow as its **built-in default**, so a state
+command works out of the box with **no** config and no init at all. `gtd init`
+is therefore optional — it just seeds the two things most projects tune:
 
 ```bash
 gtd init      # takes no argument
 ```
 
-`gtd init` writes a `.gtdrc.json` at the repository root with the bundled
-unified template's workflow under a `workflow:` key, plus a `$schema` link (so
-editors pick up completion/validation). It takes **no argument** — passing one
-is a usage error (`gtd init: too many arguments — init takes no argument`). Each
-**agent state's prompt** is written as a standalone Markdown file under
-`gtd-prompts/<state>.md` and the config references it via a
-`./gtd-prompts/<state>.md`
-[file reference](#content-values-inline-or-a-file-reference) — gtd inlines it at
-load time, so a prompt is editable Markdown and editing it changes the workflow
-with no config edit. Human `message:` blocks and check `script:` bodies stay
-inline in the config (they are workflow mechanics, not prompts).
+`gtd init` writes a **minimal** `.gtdrc.json` at the repository root — a
+`$schema` link (so editors pick up completion/validation), a
+`vars: { "testCommand": "npm test" }` entry (the var the built-in workflow's
+check script reads), and a ready-to-edit `modes:` formatting suggestion (below).
+It writes **no** `workflow:` key — the built-in default is used until you
+declare your own. It takes **no argument** — passing one is a usage error
+(`gtd init: too many arguments — init takes no argument`).
 
 `gtd init` writes only config — it derives no git state — so it need not run in
 a git repository. It runs at a **repository root** or in a directory **outside
@@ -731,9 +734,9 @@ only to write into a repository **subdirectory**, where the upward config walk
 would never find the file. Either way, it will not overwrite an existing config
 at that directory (remove it first to re-scaffold).
 
-It also seeds a top-level [`modes:`](#modes--pluggable-steering-file-modes)
-block as a ready-to-edit suggestion — a Prettier `format:` for each built-in
-steering-file mode the template uses:
+The [`modes:`](#modes--pluggable-steering-file-modes) block it seeds is a
+ready-to-edit suggestion — a Prettier `format:` for each built-in steering-file
+mode the default workflow uses:
 
 ```jsonc
 "modes": {
@@ -748,12 +751,12 @@ this is the one default it suggests: a fresh repo auto-formats its steering
 files out of the box, and you edit or drop the block freely (swap Prettier for
 dprint, point at a script, or delete the key).
 
-The one bundled template has three entry points into a shared review/squash tail
-(all walked through in
+The built-in default workflow has three entry points into a shared review/squash
+tail (all walked through in
 [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)):
 
-- **the simple flow** — creating `.gtd/TODO.md` starts idle → grilling ⇄
-  grilling-answer → building → checking ⇄ fixing (→ escalate) → reviewing →
+- **the simple flow** — creating `.gtd/TODO.md` starts idle → planning ⇄
+  plan-review → building → checking ⇄ fixing (→ escalate) → reviewing →
   await-review.
 - **the advanced flow** — creating `.gtd/REQUIREMENTS.md` starts the fuller
   machine: two-phase Q&A planning (product then architecture), package
@@ -763,20 +766,15 @@ The one bundled template has three entry points into a shared review/squash tail
   review a foreign branch.
 
 Both file-created flows converge on `reviewing` → `await-review`, and a full
-sign-off squashes the whole cycle into one commit.
-
-The files are written **uncommitted** — review them, then commit `.gtdrc.json`
-and `gtd-prompts/` before your first `gtd step` (an uncommitted file is a
-pending change the initial state's `* **` edge would otherwise capture).
-`gtd init` refuses if the repo root already has its OWN gtd config (remove it
-first to re-init; a global/ancestor config such as `~/.gtdrc` does not count),
-requires the repository root, and is one of the two commands (with `gtd lsp`)
-that run with no workflow configured. A state command run before `gtd init`
-fails with:
-
-```
-gtd: no workflow configured — run `gtd init` to create .gtdrc.json
-```
+sign-off squashes the whole cycle into one commit. To CUSTOMIZE any of this, add
+a [`workflow:`](#the-workflow-key) key that fully replaces the default.
+
+The file is written **uncommitted** — review it, then commit `.gtdrc.json`
+before your first `gtd step` (an uncommitted file is a pending change the
+initial state's `* **` edge would otherwise capture). `gtd init` refuses if the
+repo root already has its OWN gtd config (remove it first to re-init; a
+global/ancestor config such as `~/.gtdrc` does not count) and requires the
+repository root (or a directory outside any repo).
 
 ## A complete example
 

package/docs/development.md

@@ -31,7 +31,8 @@ registry to keep in sync: a workflow's content strings are either inline in its
 YAML/`.gtdrc` or a `./`-relative file reference auto-inlined at config load
 (`src/PatternConfig.ts`) — see
 [Configuration](configuration.md#content-values-inline-or-a-file-reference). The
-bundled workflow template (`src/workflows/unified.yaml`) `gtd init` scaffolds is
+bundled workflow template (`src/workflows/unified.yaml`) gtd runs as its
+built-in default (and materializes into config form via `renderInitConfig`) is
 imported as raw text via tsdown's `.yaml`-as-text loader (`tsdown.config.ts`)
 and compiled through the same path a `.gtdrc` `workflow:` key goes through
 (`src/workflows/templates.ts`) — no privileged code path.

package/docs/upgrading.md

@@ -122,29 +122,25 @@ upgrading.
 
 ## How to adopt
 
-`workflow:` is now **required** — gtd ships no default workflow, so after
-upgrading each repo must scaffold one **once**:
+`workflow:` is **optional** — gtd ships the bundled **unified** workflow as its
+built-in default, so after upgrading a repo works with **no** config and no init
+at all. The default forks on which steering file you create: `.gtd/TODO.md`
+starts the **simple flow** (a `planning` ⇄ `plan-review` plan-iteration loop,
+direct `building`, a `checking`/`fixing` loop), while `.gtd/REQUIREMENTS.md`
+starts the **advanced flow** (two-phase grilling ⇄ grilling-answer /
+architecting ⇄ architecting-answer / decompose / picking / per-package build
+with an agentic spec-review gate). Both converge on the same `reviewing` →
+`await-review` tail, and a full sign-off squashes the whole cycle into one
+commit (see [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
+
+`gtd init` is now optional and no longer writes a workflow — it seeds only a
+minimal `.gtdrc.json` (a `testCommand` var and a Prettier formatting
+suggestion). Run it if you want to tune those; otherwise nothing is required:
 
 ```bash
-gtd init      # takes no argument
+gtd init      # optional — seeds testCommand + a formatting suggestion
 ```
 
-`gtd init` (no argument) writes a `.gtdrc.json` for the single bundled
-**unified** template (its agent prompts extracted to editable `gtd-prompts/*.md`
-files the config references). The template forks on which steering file you
-create: `.gtd/TODO.md` starts the **simple flow** (a single-shot `grilling`
-plan, direct `building`, a `checking`/`fixing` loop), while
-`.gtd/REQUIREMENTS.md` starts the **advanced flow** (two-phase grilling ⇄
-grilling-answer / architecting ⇄ architecting-answer / decompose / picking /
-per-package build with an agentic spec-review gate). Both converge on the same
-`reviewing` → `await-review` tail, and a full sign-off squashes the whole cycle
-into one commit (see
-[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)). Review and
-commit the generated `.gtdrc.json` (and its `gtd-prompts/` directory), then
-continue from a settled `idle` boundary. **Note:** a repo relying on earlier
-gtd's auto-created `.gtdrc.json` `$schema` stub (which carried no `workflow:`)
-will now fail until you `gtd init` — the stub alone is no longer enough.
-
 A repo that customized v2's `workflow:` key (actors, gates, guard vocabulary,
 ladders) needs to rewrite it from scratch in the v3 schema — see
 [Configuration](configuration.md) for the schema and a complete worked example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "6.13.0",
+  "version": "7.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {