@pmelab/gtd 6.14.0 → 7.1.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
@@ -32,14 +32,15 @@ Commands:
   validate         Format and validate the steering file the resolved rest
                    declares, with its mode's commands (its file:/mode:);
                    exits non-zero with the findings when it is invalid
-  mermaid          Print the active workflow's shape as Mermaid
-                   stateDiagram-v2 source (no mutation)
   lsp              Start the LSP server for .gtd/ steering files (stdio)
+  visualize        Serve an interactive diagram of the active workflow locally
   version          Print version and exit
   help             Print this help and exit
 
 Options:
   --json           Output structured JSON instead of plain text
+  --port=<n>       (gtd visualize only) port to serve on (default: a free port)
+  --no-open        (gtd visualize only) do not open the browser
   --cost=<n>       (gtd step only) record the invocation's token cost
   --model=<name>   (gtd step only, with --cost) tag that cost's model
   --version, -v    Print version and exit
@@ -65,15 +66,17 @@ 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 (planning → building → checking), creating
@@ -81,15 +84,16 @@ that runs the suite before starting — into one shared review/squash tail (see
 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>]`
@@ -391,46 +395,6 @@ agent or human:
 
 `gtd validate` takes no arguments.
 
-## `gtd mermaid`
-
-Pure emitter of the active workflow's **shape** — not the resolved rest — as
-Mermaid [`stateDiagram-v2`](https://mermaid.js.org/syntax/stateDiagram.html)
-source (see `src/Mermaid.ts`): one node per declared state, the `[*] -->`
-initial-state marker, one edge per declared `on` row labeled with its raw
-pattern string (same declaration order the engine itself evaluates), a `--> [*]`
-edge for every commit state (final, no outgoing edges — see
-[STATES.md §8](../STATES.md#8-the-squash-lifecycle)), and one `note right of`
-per rest naming its actor, content kind, and retry cap (e.g.
-`agent · prompt · retry 3→escalate`). No git, no HEAD resolution, no template
-rendering — purely a function of the compiled `WorkflowDefinition`, so its
-output is identical regardless of the current process/branch state.
-
-```
-$ gtd mermaid
-stateDiagram-v2
-    state "idle" as idle
-    state "planning" as planning
-    ...
-    [*] --> idle
-    idle --> planning : * **
-    ...
-    note right of idle : human · message
-    ...
-```
-
-Pipe it straight into a `.md`/`.mmd` file, a GitHub issue/PR description, or any
-Mermaid-aware renderer (GitHub, GitLab, VS Code, Obsidian, the
-[Mermaid Live Editor](https://mermaid.live)) to get a diagram of a custom
-`.gtdrc` `workflow:` with no hand-maintained docs required.
-
-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 `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
-are rejected).
-
 ## `gtd lsp`
 
 Starts an LSP server over stdio for `.gtd/` steering files — document symbols
@@ -460,11 +424,44 @@ 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.
+
+## `gtd visualize [--port=<n>] [--no-open] [--json]`
+
+Serve an interactive diagram of the ACTIVE workflow on a local web server: the
+main flow as a graph (one box per sub-machine), and a click-through inspector
+with each state's actor, content kind, model/memory, steering file+mode, retry,
+flags, and outgoing/incoming edges. This is the replacement for the removed
+`gtd mermaid` — a live viewer instead of a static diagram dump.
+
+```
+$ gtd visualize
+gtd visualize running at http://127.0.0.1:53017 — Ctrl-C to stop
+```
+
+The server serves two routes: `/` (the self-contained HTML page) and
+`/workflow.json` (the model the page renders). It runs until interrupted
+(Ctrl-C), then closes cleanly. Options (orthogonal, `gtd visualize` only):
+
+- `--port=<n>` (or `--port <n>`) — serve on a specific port (0–65535); the
+  default is a free ephemeral port, printed on start.
+- `--no-open` — do not open the default browser (the URL is always printed).
+- `--json` — print the workflow model to stdout and exit WITHOUT starting a
+  server. The model is `{ states, initial, groups, vars }`; each state carries
+  its `actor`/`kind`/`model`/`memory`/`file`/`mode`/`retry`/`flags`, its `on`
+  edges, its computed `incoming` edges, and its sub-machine `group`. `groups`
+  lists each sub-machine invocation and the concrete states it produced.
+
+Dispatched before the repository-root guard and the config-reading path's review
+window — it reads the active workflow (the built-in default when none is
+configured) but touches no git/HEAD/review-window state. The diagram is rendered
+with Mermaid loaded from a CDN, so the graph needs network access the first time
+a browser loads the page; the inspector works offline regardless. Rejects
+unknown options and unexpected positional arguments.
 
 ## Error envelope
 
@@ -493,8 +490,8 @@ the plain-text one.
   green run, and the check's `"C"` pattern never fires. Gitignore every path
   your scripts write before wiring gtd into a repo.
 - **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` (and the `help`/`version` subcommands),
-  `format`, and `lsp` skip this guard entirely (and any git/`.gtdrc` dependency
-  along with it).
+  `next`/`status`) must run from the git repository root — the workflow, pending
+  changes, and process history are resolved against the process cwd.
+  `--help`/`--version` (and the `help`/`version` subcommands), `lsp`, and
+  `visualize` skip this guard entirely (`visualize` still reads the `.gtdrc`
+  workflow, but needs no git state).

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:
@@ -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 %>" },
@@ -582,6 +588,71 @@ done:
 command), and gtd never interprets the number's unit (tokens, cents, whatever
 the driver records) or the model name — it only records, sums, and groups them.
 
+## Sub-machines (`submachines:` / `use:`)
+
+Two OPTIONAL top-level keys let you factor repeated or complex clusters of
+states into reusable **sub-machines** that are expanded into ordinary concrete
+states at load time (see [STATES.md §13](../STATES.md) and
+`src/Submachines.ts`). They add NO runtime behavior — the engine only ever sees
+the expanded states — so a workflow authored with them is exactly a workflow
+written flat.
+
+```yaml
+workflow:
+  submachines:
+    gate: # authored once
+      params: [onGreen] # names referenced as `$onGreen` below
+      states:
+        check:
+          actor: check
+          script: <%~ it.vars.testCommand %>
+          on:
+            "A .gtd/FEEDBACK.md": blocked # a local state -> renamed by `as:`
+            "C": "$onGreen" # a param -> bound by `with:`
+        blocked:
+          actor: human
+          file: <%= it.vars.feedbackFile %>
+          message: "fix the baseline"
+          on: { "* **": check }
+  use:
+    - submachine: gate
+      as: { check: start-check, blocked: start-blocked } # local -> concrete (omit for identity)
+      with: { onGreen: planning } # bind each `$param`
+      set: { check: { reviewEntry: true } } # optional extra fields on a renamed state
+  states:
+    idle:
+      { actor: human, initial: true, message: "…", on: { "* **": start-check } }
+    planning: { actor: agent, prompt: "…", on: { "* **": start-check } }
+```
+
+Rules:
+
+- **`submachines: { <name>: { params, states } }`** — `states` are ordinary
+  state definitions, except an `on`/`retry.otherwise` target or any whole field
+  value may be a `$param` placeholder.
+- **`use:`** is an ordered list. Each entry names a `submachine:` and may set:
+  - **`as:`** — a `local -> concreteName` rename map. Omit it (or a given local)
+    for identity. Alias to the names a flat workflow would use to keep history
+    and `git log` unchanged.
+  - **`with:`** — bindings for the sub-machine's `$param`s.
+  - **`set:`** — extra fields merged onto a renamed state (e.g. `reviewEntry`).
+- **Substitution is WHOLE-VALUE only.** `$name` resolves only when it is the
+  entire value of a field or target — never a substring — so bash `$x`/`${x}`
+  and Eta `<%= it.vars.x %>` inside content are untouched. Pass per-instance
+  text (a whole message/prompt/`describe`) as a whole `$name` binding.
+- A target naming one of the sub-machine's own locals is rewritten via `as:`;
+  any other target passes through verbatim (a concrete top-level state). `on`
+  PATTERN keys are never substituted.
+- Expansion strips `submachines:`/`use:`; the merged `states` are then compiled
+  and `validateDefinition`'d normally. Unknown sub-machine, unbound `$param`,
+  and generated-name collisions are load-time errors, aggregated with the rest.
+
+`gtd init` scaffolds the EXPANDED flat config, so a fresh project never sees
+`submachines:`/`use:` unless it adds them itself. The bundled template is
+authored with them (dedup: `assertGreen`/`makeGreen`/`qaLoop`; comprehension:
+`planLoop`/`humanReview`/`specGate`/`packageLoop`) and its golden test pins that
+expansion is byte-identical to the flat form.
+
 ## Variables
 
 Every template — `script`/`prompt`/`message`/`commit`, and `model`/`memory`/
@@ -702,24 +773,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 +799,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,8 +816,8 @@ 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 → planning ⇄
@@ -763,20 +831,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

@@ -80,8 +80,14 @@ upgrading.
   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). The current command
-  surface is `init` / `step` / `next` / `status` / `validate` / `mermaid` /
-  `review` / `lsp`.
+  surface is `init` / `step` / `next` / `status` / `validate` / `review` /
+  `lsp`.
+
+- **`gtd mermaid` → `gtd visualize`.** The static Mermaid emitter has been
+  replaced by `gtd visualize`, which serves an interactive diagram of the active
+  workflow (main flow, sub-machines, per-state details) on a local web server —
+  see [CLI reference](cli.md#gtd-visualize---portn---no-open---json). Both are
+  read-only views of the active workflow; nothing in the machine changes.
 
 - **`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:`
@@ -122,29 +128,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 `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)). 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.14.0",
+  "version": "7.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": {