@pmelab/gtd 6.7.0 → 6.9.0

package/docs/cli.md

@@ -4,12 +4,12 @@
 Usage: gtd [command] [options]
 
 Commands:
-  init <workflow>  Scaffold a .gtdrc.json for this repo with the chosen
-                   bundled workflow (one of: simple, advanced); its agent
-                   prompts are written as editable Markdown under gtd-prompts/
-                   and referenced from the config. Run once per repo; refuses
-                   if a gtd config already exists. Leaves the files uncommitted
-                   for you to review and commit
+  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
   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
@@ -59,19 +59,22 @@ 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>`
+## `gtd init`
 
-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>\` …`.
+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`.
 
-- `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 unified template has three entry points 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/REQUIREMENTS.md` starts the advanced flow (two-phase Q&A planning,
+per-package parallel build, agentic spec-review), and `gtd review <commitish>`
+enters review directly.
 
 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
@@ -79,7 +82,7 @@ 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":"<name>"}`. See
+`{"written":".gtdrc.json","workflow":"unified","prompts":[…]}`. See
 [Configuration](configuration.md#gtd-init).
 
 ## `gtd step <actor> [--cost=<n>] [--model=<name>]`
@@ -325,9 +328,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 `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:
+This is how the unified 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

package/docs/configuration.md

@@ -40,7 +40,7 @@ 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 templates' own var, see ["Variables"](#variables)) is
+`testCommand` (the bundled template's own var, see ["Variables"](#variables)) is
 workflow-authored data like any other `it.vars` entry, not a special key gtd
 interprets.
 
@@ -53,10 +53,9 @@ interprets.
 > behind it.
 
 The `workflow:` key is the **only** definition source — there is no `extends`,
-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
+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:
 
 ```yaml
@@ -93,11 +92,23 @@ engine, and [§3](../STATES.md#3-pattern-grammar) for the pattern grammar.
 ### Content values: inline or a file reference
 
 A `script`/`prompt`/`message`/`commit` value starting with `./` or `../` is a
-**file reference** — resolved relative to the config file's own directory and
-read at load time. A missing or unreadable file reference is a **load error**,
-collected and thrown with every other config problem — never silently treated as
-inline text. Any other string (including one that merely contains a `/`, or an
-absolute path) is inline Eta template source, used verbatim.
+**file reference** — resolved relative to **the directory of the `.gtdrc` that
+declared it** (not the directory `gtd` runs from) and read at load time. A
+missing or unreadable file reference is a **load error**, collected and thrown
+with every other config problem — never silently treated as inline text. Any
+other string (including one that merely contains a `/`, or an absolute path) is
+inline Eta template source, used verbatim.
+
+Because references anchor to the declaring file, a `.gtdrc` and its
+`gtd-prompts/` (or `prompts/`) directory can live **outside** the repo — e.g. in
+a parent directory shared across several repos. gtd still runs from the repo
+root, discovers the parent `.gtdrc` by walking up the directory chain (see
+["Lookup and precedence"](#lookup-and-precedence) — cwd→home), and inlines each
+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.
 
 ```yaml
 workflow:
@@ -230,9 +241,10 @@ 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
-`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`.
+unified template scopes its agent states across the four `plan`/`build`/`fix`/
+`review` memory tiers (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
@@ -250,8 +262,7 @@ 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 `simple` template,
-do):
+rest). Multiple states may share one `file:` (and, in the unified template, do):
 
 ```yaml
 workflow:
@@ -369,12 +380,11 @@ 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 whichever
-workflow it scaffolded (`gtd init simple`/`advanced`) 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 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`:
 
 ```jsonc
 // .gtdrc.json — the workflow from `gtd init`, plus your own markdown formatter
@@ -429,10 +439,11 @@ workflow:
         "* **": building
 ```
 
-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
+The unified template enables `reviewWindow: true` on `await-review` and marks
+`review-deciding` `reviewBase: true`, so the first review covers the whole cycle
+but each subsequent feedback round's window narrows to `last-review..HEAD`. 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
 `refs/gtd/review-base`) for the window's lifetime. See
 [STATES.md §11](../STATES.md) for the full lifecycle.
 
@@ -546,15 +557,14 @@ 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 `simple` template declares
+   workflow author's declared defaults. The unified template declares
    `vars: { testCommand: "npm test" }`, read by `checking`'s script as
    `<%~ it.vars.testCommand %>` (see
-   [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)). Both
-   bundled templates also declare two model-tier vars — `plannerModel` (default
-   `smart`) and `coderModel` (default `base`) — that every agent state's
-   `model:` resolves through (`model: <%= it.vars.plannerModel %>`), so
-   repointing one var here (or via layer 2/3 below) changes every state on that
-   tier at once.
+   [STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)). The bundled
+   template also declares two model-tier vars — `plannerModel` (default `smart`)
+   and `coderModel` (default `base`) — that every agent state's `model:`
+   resolves through (`model: <%= it.vars.plannerModel %>`), so repointing one
+   var here (or via layer 2/3 below) changes every state on that tier at once.
 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
@@ -572,7 +582,7 @@ alongside every other config-shape finding (see
 already strings.
 
 ```yaml
-# .gtdrc — overriding the `simple` template's testCommand
+# .gtdrc — overriding the unified template's testCommand
 vars:
   testCommand: npm run test:ci
 ```
@@ -664,22 +674,34 @@ gtd ships **no** default workflow, so a repo must scaffold one before any state
 command works:
 
 ```bash
-gtd init simple      # or: gtd init advanced
+gtd init      # takes no argument
 ```
 
-`gtd init <workflow>` writes a `.gtdrc.json` at the repository root with the
-chosen bundled template's workflow under a `workflow:` key, plus a `$schema`
-link (so editors pick up completion/validation). 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`
+`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 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
+any repository** (scaffolding a shared config a nested repo picks up by walking
+up — see the parent-dir note under
+[file references](#content-values-inline-or-a-file-reference)); its guidance
+adjusts to say there is nothing to commit when it is not in a repo. It refuses
+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 templates use:
+steering-file mode the template uses:
 
 ```jsonc
 "modes": {
@@ -694,16 +716,22 @@ 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 two templates:
+The one bundled template 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 →
+  await-review.
+- **the advanced flow** — creating `.gtd/REQUIREMENTS.md` starts the fuller
+  machine: two-phase Q&A planning (product then architecture), package
+  decomposition, a per-package parallel build queue with an agentic spec-review
+  gate, then the same shared tail.
+- **`gtd review <commitish>`** — enters the shared `reviewing` state directly to
+  review a foreign branch.
 
-- **`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).
+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
@@ -715,7 +743,7 @@ 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
+gtd: no workflow configured — run `gtd init` to create .gtdrc.json
 ```
 
 ## A complete example
@@ -778,19 +806,22 @@ the file.
 
 ## Recipe: a per-task builder loop without a script state
 
-A `picking`-style queue arbiter (see
-[docs/examples/advanced-workflow.md](examples/advanced-workflow.md)) is a
-`script` state that turns a task-queue glob into a diff patterns can see. A
-driver that can't run scripts can get the same per-task loop out of pure
-prompt/`on` declarations instead, at the cost of trusting the agent to honor a
-marker protocol rather than a deterministic `ls`: see
+A `picking`-style queue arbiter (the bundled unified template's advanced flow
+carries one — see
+[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates)) is a `script`
+state that turns a task-queue glob into a diff patterns can see. A driver that
+can't run scripts can get the same per-task loop out of pure prompt/`on`
+declarations instead, at the cost of trusting the agent to honor a marker
+protocol rather than a deterministic `ls`: see
 [docs/design/work-packages.md §3](design/work-packages.md) ("Option B —
 agent-encoded verdict") for the worked example.
 
 ## A fuller example: two-phase planning, task decomposition, agent-prepared review
 
-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).
+The example above is deliberately small (it is close to the bundled unified
+template's simple flow). 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 — the unified template's
+**advanced flow** (started by creating `.gtd/REQUIREMENTS.md`) is exactly that,
+walked through in
+[STATES.md §10](../STATES.md#10-the-bundled-workflow-templates).

package/docs/design/state-file-association.md

@@ -68,8 +68,8 @@ patterns desyncs the machine. The vars are a DRY mechanism inside templates and
 the state↔file association, not a rename switch. (Making pattern keys var-aware
 at compile time is noted as possible future work.)
 
-The advanced example (`docs/examples/advanced-workflow.md`) gains the same
-`file:`/`mode:` annotations (it is the LSP-heavy flow), including
+The advanced flow of the bundled unified template (see STATES.md §10) gains the
+same `file:`/`mode:` annotations (it is the LSP-heavy flow), including
 `architectureFile` for its architecting phases (also `qa`-format).
 
 ## 3. The LSP becomes config-driven
@@ -105,7 +105,7 @@ The advanced example (`docs/examples/advanced-workflow.md`) gains the same
 | `src/Edge.ts` / `src/program.ts` | Render `file:` at rest; `file`/`mode` in both `--json` payloads + plain `status` lines.                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `src/Lsp.ts`                     | Config discovery, path→mode dispatch (with basename fallback), `gtd.openSteeringFile`.                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `src/workflows/default.yaml`     | §2's vars + per-state `file:`/`mode:`; templates switch to filename vars.                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Docs                             | STATES.md property table + §10; configuration.md (`file:`/`mode:` section + mode vocabulary + the pattern-literal limitation); cli.md JSON contracts; examples/advanced-workflow.md annotations; upgrading note (jump command is back, config-driven).                                                                                                                                                                                                                                     |
+| Docs                             | STATES.md property table + §10; configuration.md (`file:`/`mode:` section + mode vocabulary + the pattern-literal limitation); cli.md JSON contracts; the bundled unified template's advanced-flow annotations (STATES.md §10); upgrading note (jump command is back, config-driven).                                                                                                                                                                                                      |
 | Tests                            | Unit: validation (mode vocabulary, mode-requires-file, commit-state prohibition, aggregation), compile, `file:` render + failure path; LSP path→mode dispatch, fallback, openSteeringFile (pure helpers). E2e: `driver-json-status.feature` file/mode emission (present + omitted); `lsp.feature` @live — documentSymbol served for a CUSTOM-named qa file mapped via a real `.gtdrc` (proving config-driven dispatch), and the jump command returning the rendered path at a known state. |
 | Live verification                | Scratch repo with a custom workflow whose `file:` uses a var: `gtd status` shows the rendered `File:`/`Mode:`; LSP smoke against the custom filename; default workflow spot-check (`grilling` → `File: .gtd/TODO.md`, `Mode: qa`).                                                                                                                                                                                                                                                         |
 

package/docs/design/state-machine-validation.md

@@ -306,8 +306,8 @@ sub-millisecond — safe to run on every invocation, exactly like today's
 - **The bundled default must stay finding-free** — findings 7 and 10 are
   calibrated against it (`fixing`'s cap bounds the check loop; the literal
   `.gtd/...` patterns match the declared default vars). Any new check must be
-  validated against `default.yaml` and `docs/examples/advanced-workflow.md`
-  before landing.
+  validated against the bundled unified template (`src/workflows/unified.yaml`,
+  covering both its simple and advanced flows) before landing.
 - **Warning channel is the only architectural change** — everything else slots
   into the existing collect-and-merge flow in `compileWorkflowConfig`.
 

package/docs/design/steering-file-loops.md

@@ -133,7 +133,7 @@ review-deciding branch condition. Findings go into `.gtd/FORMAT.md` verbatim
 | `STATES.md` §10                                       | New table + walkthrough (both loops, the declaration-order subtleties, the hygiene invariant).                                                                                                                                                                                                                                                             |
 | `tests/integration/features/default-workflow.feature` | Rewritten: malformed-TODO lap (simulate `todo-validating` by writing `.gtd/FORMAT.md` + `gtd step check` — @inmem never executes scripts), valid draft → answer lap → accept; malformed-REVIEW lap; tick-all approve → `idle` with empty `.gtd/`; partial-tick feedback → TODO.md extraction → `grilling`; delete-shortcut approve; retry/escalation kept. |
 | `smoke.feature`                                       | Hop updates (`grilling` now routes to `todo-validating`).                                                                                                                                                                                                                                                                                                  |
-| Docs                                                  | `configuration.md` / `README.md` walkthrough mentions; `docs/examples/advanced-workflow.md` intro gains one line noting the default now carries the validation loops (the example itself is NOT reworked in this change — noted as a possible follow-up to rebase it on the new default).                                                                  |
+| Docs                                                  | `configuration.md` / `README.md` walkthrough mentions; the advanced flow is now part of the bundled unified template (see STATES.md §10) rather than a standalone example.                                                                                                                                                                                 |
 | Live verification                                     | Real-script drive (`gtd run` at each validator) covering: agent writes malformed TODO → FORMAT.md → fixed lap; answers folded; malformed REVIEW lap; tick-all approve; partial-tick feedback extracting TODO.md; final tree `.gtd`-free at idle.                                                                                                           |
 
 ## 5. The LSP server comes back (v3-shaped)

package/docs/design/work-packages.md

@@ -1,12 +1,11 @@
 # Design: the builder / work-packages flow as pure workflow configuration
 
-> Status: LANDED, then relocated (2026-07-22) — Option A shipped in the bundled
-> default workflow's `picking` state; the bundled default has since been
-> drastically simplified and no longer includes it. The full Option-A machine
-> now lives as a copy-paste example at
-> [docs/examples/advanced-workflow.md](../examples/advanced-workflow.md). The
-> rest of this document is kept as the decision record: why Option A was chosen
-> over B/C/D, and the process-per-task topology (§6) remains a documented,
+> Status: LANDED — Option A shipped in the bundled default workflow's `picking`
+> state. It now lives in the bundled **unified** template's advanced flow (the
+> `picking` state, reached by starting a cycle with `.gtd/REQUIREMENTS.md` — see
+> [STATES.md §10](../../STATES.md#10-the-bundled-workflow-templates)). The rest
+> of this document is kept as the decision record: why Option A was chosen over
+> B/C/D, and the process-per-task topology (§6) remains a documented,
 > unimplemented recipe.
 >
 > Context (as originally written): v2 had an engine-level package loop

package/docs/development.md

@@ -31,18 +31,16 @@ 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 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.
+bundled workflow template (`src/workflows/unified.yaml`) `gtd init` scaffolds 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.
 
 `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/simple.yaml` and `src/workflows/advanced.yaml` resolve when
-running from source.
+`src/workflows/unified.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/upgrading.md

@@ -16,7 +16,7 @@ subject (or the bare `gtd(<actor>): <to>`) 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 `simple` template). There is no special-casing for "this looks like an old
+the unified 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
-  `simple` template's `testCommand`, overridable via the top-level `vars:` key
-  or a `GTD_VAR_testCommand` environment variable — see
+  unified 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 `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).
+  `reviewBase: true`). The unified 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 `simple` template's own
+  deletes, matched by an ordinary `on` pattern. The unified 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
+  to the deterministic decider, in the unified 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,
@@ -87,7 +87,7 @@ upgrading.
   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 `simple` template:
+  the unified template:
 
   ```yaml
   modes:
@@ -116,9 +116,9 @@ 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
-  `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.
+  bundled 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
 
@@ -126,20 +126,20 @@ upgrading.
 upgrading each repo must scaffold one **once**:
 
 ```bash
-gtd init simple      # or: gtd init advanced
+gtd init      # takes no argument
 ```
 
-`gtd init simple` writes a `.gtdrc.json` for the `simple` template (its agent
-prompts extracted to editable `gtd-prompts/*.md` files the config references): 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
+`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:`)

package/package.json

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