@pmelab/gtd 5.1.0 → 6.1.0

package/docs/cli.md

@@ -4,6 +4,10 @@
 Usage: gtd [command] [options]
 
 Commands:
+  init <workflow>  Scaffold a .gtdrc.json for this repo with the chosen
+                   bundled workflow inline (one of: simple, advanced). Run
+                   once per repo; 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
@@ -17,8 +21,6 @@ Commands:
                    a clean tree resting at the workflow's initial state
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
-  run              Execute the resolved rest's emitted script, then step its
-                   actor (the built-in script driver)
   status           Print the resolved rest's state/actor and which declared
                    pattern (if any) each pending change matches (no mutation)
   validate         Format and validate the steering file the resolved rest
@@ -27,6 +29,8 @@ Commands:
   mermaid          Print the active workflow's shape as Mermaid
                    stateDiagram-v2 source (no mutation)
   lsp              Start the LSP server for .gtd/ steering files (stdio)
+  version          Print version and exit
+  help             Print this help and exit
 
 Options:
   --json           Output structured JSON instead of plain text
@@ -36,11 +40,12 @@ Options:
   --help, -h       Print this help and exit
 ```
 
-`--version` (`-v`) and `--help` (`-h`) short-circuit before any git or
-repository-state work — they run outside a repo and in any repo state. Bare
-`gtd` (no subcommand) is a usage error: it prints the help text and exits 1
-without touching the repository. Every other command must be run from the
-**repository root** — gtd derives the workflow, pending changes, and process
+`--version` (`-v`) / `gtd version` and `--help` (`-h`) / `gtd help`
+short-circuit before any git or repository-state work — they run outside a repo
+and in any repo state (the bare subcommands are exact equivalents of their flag
+forms). Bare `gtd` (no subcommand) is a usage error: it prints the help text and
+exits 1 without touching the repository. Every other command must be run from
+the **repository root** — gtd derives the workflow, pending changes, and process
 history relative to cwd, so it refuses with a clear error if invoked from a
 subdirectory.
 
@@ -52,6 +57,28 @@ mistyped flag can never degrade a JSON caller to plain-text mode. A bare
 `--model`, `--model` without `--cost`, or either flag on any command other than
 `gtd step` are all usage errors.
 
+## `gtd init <workflow>`
+
+Scaffolds a `.gtdrc.json` at the repository root with one of the bundled
+workflow templates inline under a `workflow:` key, plus a `$schema` link.
+`<workflow>` is required and must be `simple` or `advanced` (a missing or
+unknown name is a usage error listing both). 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 <simple|advanced>\` …`.
+
+- `simple` — the 10-state machine (see
+  [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
+- `advanced` — the fuller machine (see
+  [advanced-workflow.md](examples/advanced-workflow.md)).
+
+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 any gtd config already exists,
+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":"<name>"}`. See
+[Configuration](configuration.md#gtd-init).
+
 ## `gtd step <actor> [--cost=<n>] [--model=<name>]`
 
 Authenticates `<actor>` against the resolved rest and performs the ONE resulting
@@ -295,9 +322,9 @@ Then:
   approve), has nothing to validate and exits `0`
   (`nothing to validate at "<state>"`). Nothing is formatted in that case.
 
-This is how the bundled default keeps its steering files well-formed without an
-in-machine validation state — and the check runs whoever last touched the file,
-agent or human:
+This is how the `simple` template keeps its steering files well-formed without
+an in-machine validation state — and the check runs whoever last touched the
+file, agent or human:
 
 - **The producing agent self-validates.** Plain `gtd next` appends a "run
   `gtd validate` and fix all violations" instruction to a `prompt` rest that
@@ -378,8 +405,9 @@ with no `.gtdrc` in sight. Also registers an `executeCommand`,
 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 auto-init — the server needs no
-git/workflow state of its own. Rejects `--json` (exit 1,
+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.
@@ -413,5 +441,6 @@ the plain-text one.
 - **Repository root invocation.** Every state subcommand (`step`/`review`/
   `next`/`status`/`mermaid`) must run from the git repository root — the
   workflow, pending changes, and process history are resolved against the
-  process cwd. `--help`/`--version`, `format`, and `lsp` skip this guard
-  entirely (and any git/`.gtdrc` dependency along with it).
+  process cwd. `--help`/`--version` (and the `help`/`version` subcommands),
+  `format`, and `lsp` skip this guard entirely (and any git/`.gtdrc` dependency
+  along with it).

package/docs/configuration.md

@@ -1,10 +1,11 @@
 # Configuration
 
-gtd reads an optional `.gtdrc` config file via
-[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). With no config, the
-bundled default workflow applies (see
-[STATES.md](../STATES.md#10-the-bundled-default-workflow)). Supported filenames
-(searched in this order):
+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` carrying a bundled workflow template inline. A
+state command run with no `workflow:` configured fails, pointing you at
+`gtd init`. Supported filenames (searched in this order):
 
 - `.gtdrc`
 - `.gtdrc.json`
@@ -17,16 +18,17 @@ bundled default workflow applies (see
 
 v3's `.gtdrc` has exactly three blessed top-level keys:
 
-- **`workflow`** (object, optional) — the whole machine definition (its states,
-  plus its own `vars:` defaults and `modes:`), compiled by
-  `src/PatternConfig.ts`. Absent = the bundled default workflow. See
+- **`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
   ["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.
 - **`modes`** (object, optional) — steering-file modes (`format:`/`validate:`
   shell commands), layered over the active workflow's own `modes:` and gtd's
   built-in validators, so a project can plug its formatter or linter into the
-  BUNDLED default without re-declaring a workflow. See
+  configured workflow without re-declaring that mode on the workflow itself. See
   ["`modes:`"](#modes--pluggable-steering-file-modes) below.
 - **`$schema`** (string, optional) — stripped before validation, so it never
   counts as an unknown key. Point it at the published schema for editor-backed
@@ -37,16 +39,18 @@ Any other top-level key is **rejected** (`onExcessProperty: "error"`) — v3 has
 no `testCommand`, `fixAttemptCap`, `reviewThreshold`, `agenticReview`, `squash`,
 `learning`, `decisionLog`, or `models` keys; all of that machinery is gone (see
 [Upgrading](upgrading.md)). The engine blesses no VARIABLE NAMES either —
-`testCommand` (the bundled default workflow's own var, see
-["Variables"](#variables)) is workflow-authored data like any other `it.vars`
-entry, not a special key gtd interprets.
+`testCommand` (the bundled templates' own var, see ["Variables"](#variables)) is
+workflow-authored data like any other `it.vars` entry, not a special key gtd
+interprets.
 
 ## The `workflow:` key
 
 The `workflow:` key is the **only** definition source — there is no `extends`,
-no merge-over-a-built-in; the bundled default workflow is itself a YAML asset
-compiled through the exact same compiler (`src/workflows/default.yaml` →
-`compileWorkflowConfig`). Its shape:
+no merge-over-a-built-in. The bundled templates `gtd init` scaffolds are
+themselves YAML assets (`src/workflows/simple.yaml`,
+`src/workflows/advanced.yaml`) compiled through the exact same compiler
+(`compileWorkflowConfig`); `gtd init` just writes one of them, inline, under
+this key. Its shape:
 
 ```yaml
 workflow:
@@ -219,9 +223,9 @@ Because `grilling` re-enters itself around the answer loop, every lap emits
 `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
 differently-labelled state at a phase boundary clears. This is exactly how the
-bundled default scopes its four agent states (`plan`/`build`/`fix`/`review` —
-see [STATES.md §10](../STATES.md#10-the-bundled-default-workflow)), and how the
-loop driver reads it is spelled out in `skills/loop/SKILL.md`.
+`simple` template scopes its four agent states (`plan`/`build`/`fix`/`review` —
+see [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)), and how
+the loop driver reads it is spelled out in `skills/loop/SKILL.md`.
 
 Like `model`, `memory:` is rendered as an Eta template through the same context
 as the state's content — a plain label (`plan`) passes through unchanged, while
@@ -239,7 +243,8 @@ A state may additionally declare `file:` — an Eta template naming THE steering
 file this state is about: the file a human/editor should look at while the
 machine rests here (rendered through the same `it.vars`-carrying context as
 content/`model`; must render non-empty). Forbidden on a commit state (never at
-rest). Multiple states may share one `file:` (and, in the bundled default, do):
+rest). Multiple states may share one `file:` (and, in the `simple` template,
+do):
 
 ```yaml
 workflow:
@@ -357,16 +362,20 @@ 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 on the BUNDLED default workflow can plug
-in its formatter without copying a single state:
-
-```yaml
-# .gtdrc — keep the bundled default workflow, add your own markdown formatter
-modes:
-  qa:
-    format: "npx prettier --write <%= it.file %>"
-  review:
-    format: "npx prettier --write <%= it.file %>"
+and the top-level key means a project can plug its formatter into whichever
+workflow it scaffolded (`gtd init simple`/`advanced`) without re-declaring a
+`modes:` block on the workflow itself. Add it alongside the `workflow:` key in
+your `.gtdrc.json`:
+
+```jsonc
+// .gtdrc.json — the workflow from `gtd init`, plus your own markdown formatter
+{
+  "workflow": { "...": "..." },
+  "modes": {
+    "qa": { "format": "npx prettier --write <%= it.file %>" },
+    "review": { "format": "npx prettier --write <%= it.file %>" },
+  },
+}
 ```
 
 **Known limitation — no live editor support for a custom mode.** `gtd lsp`
@@ -411,7 +420,7 @@ workflow:
         "* **": building
 ```
 
-The bundled default enables `reviewWindow: true` on `await-review` (no
+The `simple` template enables `reviewWindow: true` on `await-review` (no
 `reviewBase` state, so the base is the whole cycle). The pure engine never
 observes an open window — it is opened/closed entirely at the edge; the real
 head is preserved under `refs/gtd/review-head` (the base under
@@ -528,10 +537,10 @@ Every template — `script`/`prompt`/`message`/`commit`, and `model`/`memory`/
 layers, **later wins**:
 
 1. **The workflow's own `vars:` key** (sibling to `states:`, shown above) — the
-   workflow author's declared defaults. The bundled default workflow declares
+   workflow author's declared defaults. The `simple` template declares
    `vars: { testCommand: "npm test" }`, read by `checking`'s script as
    `<%~ it.vars.testCommand %>` (see
-   [STATES.md §10](../STATES.md#10-the-bundled-default-workflow)).
+   [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
 2. **A top-level `.gtdrc` `vars:` key** (a sibling of `workflow:`, NOT nested
    inside it) — per-repo tuning without redefining the whole workflow. Subject
    to the same cwd→home deep merge as everything else in `.gtdrc` (innermost
@@ -549,7 +558,7 @@ alongside every other config-shape finding (see
 already strings.
 
 ```yaml
-# .gtdrc — overriding the bundled default's testCommand
+# .gtdrc — overriding the `simple` template's testCommand
 vars:
   testCommand: npm run test:ci
 ```
@@ -635,19 +644,38 @@ finds along the way. All found levels are **deep-merged**, with the **innermost
 directory cascades to every checkout beneath it, while any individual checkout
 can still override with its own `.gtdrc`.
 
-## Auto-init
+## `gtd init`
+
+gtd ships **no** default workflow, so a repo must scaffold one before any state
+command works:
 
-On every **state command** (`step`, `next`, `run`, `status`) that has passed the
-repo-root guard, if the cwd→root walk finds **no** config anywhere, gtd creates
-and commits a starter `.gtdrc.json` at the repository root containing only a
-`$schema` link. Auto-init never runs for `--version`/`--help`, `format`,
-bare/unknown commands, or an invocation refused by the repo-root guard — those
-perform no repository mutation of any kind. On a repo with no commits yet, or
-whose HEAD isn't a `gtd(actor): state` commit, the stub is committed as its own
-`chore: add .gtdrc.json`. If HEAD is already a `gtd(actor): state` commit
-(mid-process), the stub is instead **amended into HEAD** — stacking a fresh
-boundary commit there would produce an unrecognized HEAD that resolves back to
-the workflow's initial state.
+```bash
+gtd init simple      # or: gtd init advanced
+```
+
+`gtd init <workflow>` writes a `.gtdrc.json` at the repository root with the
+chosen bundled template's whole workflow inline under a `workflow:` key, plus a
+`$schema` link (so editors pick up completion/validation). The two templates:
+
+- **`simple`** — the 10-state machine walked through in
+  [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates): idle →
+  grilling ⇄ grilling-answer → building → checking ⇄ fixing (→ escalate) →
+  reviewing → await-review, resting back at idle on approval (no squash).
+- **`advanced`** — the fuller machine (two-phase Q&A planning, an architecture
+  phase, task decomposition, a per-task build queue, and a squash finale),
+  walked through at
+  [docs/examples/advanced-workflow.md](examples/advanced-workflow.md).
+
+The file is written **uncommitted** — review it, then commit it before your
+first `gtd step` (an uncommitted `.gtdrc.json` is a pending change the initial
+state's `* **` edge would otherwise capture). `gtd init` refuses if any gtd
+config already exists (remove it first to re-init), 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 <simple|advanced>` to create .gtdrc.json
+```
 
 ## A complete example
 
@@ -720,8 +748,8 @@ agent-encoded verdict") for the worked example.
 
 ## A fuller example: two-phase planning, task decomposition, agent-prepared review
 
-The bundled default above is deliberately small. For a heavier machine — Q&A
-planning loops, an architecture phase, task decomposition, the deterministic
-per-task `picking` arbiter, and agent-prepared `.gtd/REVIEW.md` review — see
-[docs/examples/advanced-workflow.md](examples/advanced-workflow.md), a
-copy-paste-ready `.gtdrc` recipe.
+The example above is deliberately small (it is close to the `simple` template).
+For a heavier machine — Q&A planning loops, an architecture phase, task
+decomposition, the deterministic per-task `picking` arbiter, and agent-prepared
+`.gtd/REVIEW.md` review — run `gtd init advanced`, walked through at
+[docs/examples/advanced-workflow.md](examples/advanced-workflow.md).

package/docs/development.md

@@ -31,16 +31,18 @@ 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 default workflow (`src/workflows/default.yaml`) 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/default.ts`) — no privileged code path.
+bundled workflow templates (`src/workflows/simple.yaml`,
+`src/workflows/advanced.yaml`) `gtd init` scaffolds are 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.
 
 `npm run dev` runs `src/main.ts` directly via Node's native TypeScript
 type-stripping (requires Node 22.6+). It registers `dev/hooks.mjs`, which
 resolves `./Foo.js` specifiers to the on-disk `./Foo.ts` and imports `*.yaml`
 files as raw text, mirroring tsdown's `.yaml`-as-text loader — this is what lets
-`src/workflows/default.yaml` resolve when running from source.
+`src/workflows/simple.yaml` and `src/workflows/advanced.yaml` resolve when
+running from source.
 
 The decision core is pure and IO-free: the pattern machine's shape (states,
 patterns, retry) is a plain-data `WorkflowDefinition` (`src/PatternMachine.ts`),

package/docs/examples/advanced-workflow.md

@@ -1,15 +1,17 @@
-# Example: the full grilling → architecting → decompose → picking → review machine
+# The `advanced` template: the full grilling → architecting → decompose → picking → review machine
 
-This is the fuller machine gtd shipped as its bundled default before the bundled
-default was drastically simplified (see
-[STATES.md §10](../../STATES.md#10-the-bundled-default-workflow) for what ships
-today — including the two steering-file validation loops the current default
-carries over `.gtd/TODO.md` and `.gtd/REVIEW.md`, which this example's own
-`grilling`/`reviewing` phases predate and don't validate). It is preserved here
-as a copy-paste-ready `.gtdrc` recipe for anyone who wants the heavier shape
-back.
+This walks through the **`advanced`** bundled workflow template — the fuller
+machine `gtd init advanced` scaffolds (`src/workflows/advanced.yaml`). The other
+bundled template, **`simple`** (`gtd init simple`), is the smaller 10-state
+machine walked through in
+[STATES.md §10](../../STATES.md#10-the-bundled-workflow-templates) — including
+the two steering-file validation loops it carries over `.gtd/TODO.md` and
+`.gtd/REVIEW.md`, which this machine's own `grilling`/`reviewing` phases predate
+and don't validate. `gtd init advanced` writes the block below directly, so you
+normally don't paste it by hand; it's reproduced here as the annotated
+reference.
 
-Compared to the simplified bundled default, this machine adds:
+Compared to the `simple` template, this machine adds:
 
 - **Two-phase human-in-the-loop planning with Q&A loops** — `grilling` ⇄
   `grilling-answer` develops a product-level plan from `.gtd/TODO.md` one open
@@ -29,9 +31,9 @@ Compared to the simplified bundled default, this machine adds:
   [STATES.md §11](../../STATES.md#11-the-review-checkout-window).
 - **A squash finale** — approval at `await-review` moves to `squashing` (the
   agent authors `.gtd/COMMIT_MSG.md`) and then `done`, a `commit:` state that
-  squashes the whole cycle into one commit. The simplified bundled default drops
-  this: it rests at `idle` on approval instead and leaves every turn commit in
-  history for the human to squash (or not) however they choose.
+  squashes the whole cycle into one commit. The `simple` template drops this: it
+  rests at `idle` on approval instead and leaves every turn commit in history
+  for the human to squash (or not) however they choose.
 
 This example also carries `file:`/`mode:` annotations on every state that rests
 on a steering file (see the state table below and
@@ -44,11 +46,12 @@ actions/diagnostics off those declarations rather than a hardcoded basename:
 `review`-format (`vars.reviewFile`), and `fixing`/`escalate` declare `file:`
 alone (`vars.feedbackFile` is plain text, no LSP format).
 
-Paste the block below under a top-level `workflow:` key in your own `.gtdrc` (or
-`.gtdrc.yaml`) — it's the complete definition, unmodified in content from the
-version this example is frozen from, only re-indented to nest under `workflow:`.
-See [Configuration](../configuration.md) for the `.gtdrc` schema this slots
-into.
+Running `gtd init advanced` writes this whole definition into `.gtdrc.json`
+under a `workflow:` key for you. The block below is the same definition in YAML
+form (the source is `src/workflows/advanced.yaml`), nested under `workflow:` —
+paste it into your own `.gtdrc`/`.gtdrc.yaml` if you'd rather hand-author or
+tweak it. See [Configuration](../configuration.md) for the `.gtdrc` schema this
+slots into.
 
 ## State table
 
@@ -225,7 +228,7 @@ workflow:
       actor: check
       script: |
         #!/usr/bin/env bash
-        # gtd check turn (the queue arbiter) — the driver (`gtd run`) executes
+        # gtd check turn (the queue arbiter) — the loop driver executes
         # this verbatim, then steps the check actor. Mechanics only: take the
         # first task file (by name) under .gtd/tasks/ into .gtd/NEXT.md, or
         # remove .gtd/NEXT.md when the queue is empty. What NEXT.md's
@@ -268,7 +271,7 @@ workflow:
       actor: check
       script: |
         #!/usr/bin/env bash
-        # gtd check turn — the driver (`gtd run`) executes this verbatim, then
+        # gtd check turn — the loop driver executes this verbatim, then
         # steps the check actor. Mechanics only: run the test suite and record a
         # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another
         # fix round vs escalation) is decided by the workflow's own `on`/`retry`
@@ -436,8 +439,8 @@ event) accepts the current phase's draft and moves on; any other pending change
 loops back for another round. `picking` is a `script` state whose only job is to
 inspect `.gtd/tasks/` (a tree property patterns can't see directly) and turn it
 into a diff patterns CAN see — see the walkthrough in
-[STATES.md §10](../../STATES.md#10-the-bundled-default-workflow) (the version of
-that section frozen alongside this example) for the full state-by-state
+[STATES.md §10](../../STATES.md#10-the-bundled-workflow-templates) (the version
+of that section frozen alongside this example) for the full state-by-state
 narrative, including the `on`-declaration-order subtlety at `picking` and the
 `fixing` retry-cap pooling caveat.
 

package/docs/upgrading.md

@@ -15,8 +15,8 @@ design — v1 and v2 subjects alike.** v3's `resolveState`
 subject naming a state and an actor the active workflow currently declares;
 everything else — a v1 `gtd: grilling`, a v2 `gtd(agent): building`, a plain
 `chore: …` commit, anything from a foreign repo — parses as unrecognized and
-lands at the workflow's initial state (`idle` in the bundled default). There is
-no special-casing for "this looks like an old gtd commit": the mechanism is
+lands at the workflow's initial state (`idle` in the `simple` template). There
+is no special-casing for "this looks like an old gtd commit": the mechanism is
 exactly the same one that already made v1 history inert to v2, and v2 history
 inert to a differently-configured workflow — v3 just applies it uniformly to all
 prior history instead of drawing a v1/v2 line.
@@ -41,8 +41,8 @@ upgrading.
   all gone — `workflow:` and `vars:` are the only two blessed keys (see
   [Configuration](configuration.md)). A check's command now lives inline in its
   own `script:` content, reading a workflow-declared `it.vars` entry (the
-  bundled default's `testCommand`, overridable via the top-level `vars:` key or
-  a `GTD_VAR_testCommand` environment variable — see
+  `simple` template's `testCommand`, overridable via the top-level `vars:` key
+  or a `GTD_VAR_testCommand` environment variable — see
   [Configuration's "Variables"](configuration.md#variables)) rather than a
   blessed `testCommand` config key; squashing is a `commit:` state instead of a
   boolean flag; there is no learning phase, no decision log, and no model
@@ -53,17 +53,17 @@ upgrading.
   v3.0 rewrite, then RE-INTRODUCED as the explicit state property it was always
   meant to become: a state declaring `reviewWindow: true` opens the window while
   the machine rests there (base = the process start, or a state marked
-  `reviewBase: true`). The bundled default enables it on `await-review`. Unlike
-  v2's hardwired gate, it is pure workflow DATA and the engine stays oblivious —
-  see [STATES.md §11](../STATES.md) and the `file:`/`mode:` neighbours in
-  [configuration.md](configuration.md).
+  `reviewBase: true`). The `simple` template enables it on `await-review`.
+  Unlike v2's hardwired gate, it is pure workflow DATA and the engine stays
+  oblivious — see [STATES.md §11](../STATES.md) and the `file:`/`mode:`
+  neighbours in [configuration.md](configuration.md).
 - **`forceApprove`, content-inspection verdicts.** FEEDBACK.md emptiness,
   checkbox-only REVIEW.md diffs, and doc-structure validation are gone as ENGINE
   mechanisms — verdicts are now expressed purely by which file a turn writes or
-  deletes, matched by an ordinary `on` pattern. The bundled default workflow's
-  own checkbox-review verdict (`review-deciding`) is ordinary WORKFLOW data (an
-  `on` pattern), not an engine hook: `D REVIEW.md` = approve, `M REVIEW.md` =
-  route to the deterministic decider, in the bundled default. Deterministic
+  deletes, matched by an ordinary `on` pattern. The `simple` template's own
+  checkbox-review verdict (`review-deciding`) is ordinary WORKFLOW data (an `on`
+  pattern), not an engine hook: `D REVIEW.md` = approve, `M REVIEW.md` = route
+  to the deterministic decider, in the `simple` template. Deterministic
   format-checking of the steering files is likewise no longer a pair of
   in-machine `check`/`script` states — the old `todo-validating`/
   `review-validating` states and their `.gtd/FORMAT.md` steering file are gone,
@@ -71,21 +71,23 @@ upgrading.
   (see
   [docs/design/steering-file-validation-command.md](design/steering-file-validation-command.md)
   and [STATES.md §12](../STATES.md)).
-- **`gtd review <target>`.** Gone in the initial v3 rewrite (the command surface
-  was `step` / `next` / `run` / `status` / `validate` / `mermaid` / `lsp`), then
-  RETURNED in this version with different, narrower semantics: it no longer
-  inspects an arbitrary target the way v2 did — it starts a brand NEW review
-  process at a workflow-declared `reviewEntry: true` state, reviewing
-  `<target>..HEAD` (e.g. a colleague's PR branch with no gtd process of its own)
-  by writing one empty entry commit with a `Gtd-Review-Base:` trailer and
-  reusing the workflow's existing review/feedback machinery unmodified — see
+- **`gtd review <target>`.** Gone in the initial v3 rewrite, then RETURNED in
+  this version with different, narrower semantics: it no longer inspects an
+  arbitrary target the way v2 did — it starts a brand NEW review process at a
+  workflow-declared `reviewEntry: true` state, reviewing `<target>..HEAD` (e.g.
+  a colleague's PR branch with no gtd process of its own) by writing one empty
+  entry commit with a `Gtd-Review-Base:` trailer and reusing the workflow's
+  existing review/feedback machinery unmodified — see
   [STATES.md §11](../STATES.md#11-the-review-checkout-window) and
-  [CLI reference](cli.md#gtd-review-commitish---json).
+  [CLI reference](cli.md#gtd-review-commitish---json). The current command
+  surface is `init` / `step` / `next` / `status` / `validate` / `mermaid` /
+  `review` / `lsp`.
+
 - **`gtd format <file>`, and the bundled prettier with it.** gtd no longer
   formats anything on its own: a steering-file mode declares its own `format:`
   SHELL COMMAND, so a project brings whatever formatter it already uses. Adding
   four lines to `.gtdrc` restores (and improves on) the old auto-formatting for
-  the bundled default workflow:
+  the `simple` template:
 
   ```yaml
   modes:
@@ -114,25 +116,33 @@ upgrading.
   itself only understands the two built-ins), the LSP reads that same config the
   CLI does to build its path→mode dispatch, and `gtd.openSteeringFile` resolves
   the current state and shows its `file:`. No mapping declared at all (the
-  bundled default's predecessor shape, or any workflow with no `file:`/`mode:`)
-  falls back to basename dispatch (`TODO.md`/`REVIEW.md`), same as before this
-  addition.
+  `simple` template's predecessor shape, or any workflow with no
+  `file:`/`mode:`) falls back to basename dispatch (`TODO.md`/`REVIEW.md`), same
+  as before this addition.
 
 ## How to adopt
 
-`workflow:` is optional — with no config at all, the bundled default workflow
-applies: a single-shot `grilling` plan, direct `building`, a `checking`/`fixing`
-loop, and a direct-diff `await-review` that rests the cycle back at `idle` on
-approval — no squash; every turn commit stays in history for you to squash
-however you like, or not at all (see
-[STATES.md §10](../STATES.md#10-the-bundled-default-workflow)) — expressed as
-data rather than baked into the engine. The fuller grilling ⇄ grilling-answer /
-architecting ⇄ architecting-answer / decompose / picking / reviewing shape v2
-shipped — including a squash finale — is preserved as a copy-paste `.gtdrc`
-example at [docs/examples/advanced-workflow.md](examples/advanced-workflow.md)
-rather than the bundled default. Nothing to do for a repo that's happy with the
-default shape beyond a normal `npm install -g @pmelab/gtd` upgrade, from a
-settled `idle` boundary.
+`workflow:` is now **required** — gtd ships no default workflow, so after
+upgrading each repo must scaffold one **once**:
+
+```bash
+gtd init simple      # or: gtd init advanced
+```
+
+`gtd init simple` writes a `.gtdrc.json` with the `simple` template inline: a
+single-shot `grilling` plan, direct `building`, a `checking`/`fixing` loop, and
+a direct-diff `await-review` that rests the cycle back at `idle` on approval —
+no squash; every turn commit stays in history for you to squash however you
+like, or not at all (see
+[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)).
+`gtd init advanced` writes the fuller grilling ⇄ grilling-answer / architecting
+⇄ architecting-answer / decompose / picking / reviewing machine — including a
+squash finale — walked through at
+[docs/examples/advanced-workflow.md](examples/advanced-workflow.md). Review and
+commit the generated `.gtdrc.json`, 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

package/package.json

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