@pmelab/gtd 59.0.0 → 60.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "59.0.0",
+  "version": "60.0.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -57,9 +57,9 @@ driver enforces it at the OS level. See
 
 > **A repository's `gtd.config.ts` is code, and gtd runs it.** A custom workflow
 > is a TypeScript module, and every gtd command that looks at workflow state —
-> `gtd next`, `gtd lsp`, `gtd door` and `gtd doors` included, not just
-> `gtd land` — evaluates it. Treat it like a Makefile or a `package.json`
-> script: don't run gtd in a checkout you don't trust.
+> `gtd next`, `gtd lsp` and `gtd start` included, not just `gtd land` —
+> evaluates it. Treat it like a Makefile or a `package.json` script: don't run
+> gtd in a checkout you don't trust.
 
 ## Quick start
 
@@ -67,7 +67,7 @@ Put a `gtd.config.ts` at your repository's root (see [Install](#install)) and
 commit it; gtd refuses to run without one. The repository need not be a
 JavaScript project: gtd resolves the config's `@pmelab/gtd/*` imports itself, so
 a Python, Rust or notes repository needs no `package.json` and no install. Then
-run `gtd install`: it writes nothing and prints a briefing (and where to get a
+run `gtd guide`: it writes nothing and prints a briefing (and where to get a
 workflow, if you have none yet). Pipe that briefing into your coding agent and
 answer its questions. It should build you a script that will autonomously run
 the process for you. Ask your agent if you have any questions.
@@ -155,14 +155,14 @@ gtd land
 
 ```
 commit everything with this message: gtd(human): idle → unwind
-(run `gtd land --json=script | sh` to get the landing script)
+(to land it: s=$(gtd land --json=script) && sh -c "$s")
 ```
 
 You could run that commit by hand. Take the script instead — it spells out the
 exact message and reports what landed:
 
 ```bash
-gtd land --json=script | sh
+s=$(gtd land --json=script) && sh -c "$s"
 ```
 
 ```
@@ -205,7 +205,7 @@ before:
 
 ```bash
 sh -c "$(gtd next --json=content)"
-gtd land --json=script | sh
+s=$(gtd land --json=script) && sh -c "$s"
 ```
 
 `--json=<field>` is how a script reads one value out of a beat. Bare `--json`
@@ -263,7 +263,7 @@ gtd next | claude -p --dangerously-skip-permissions
 **The turn ends when `claude -p` returns** — a command the agent backgrounds
 dies unread, and the process stalls on an empty turn. Claude Code lets the agent
 background commands and caps foreground ones at 10 minutes by default, so a real
-driver exports these first (`gtd install`'s reference driver does):
+driver exports these first (`gtd guide`'s reference driver does):
 
 ```bash
 export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
@@ -278,7 +278,7 @@ The prompt tells the agent to asses your request and write
 `.gtd/REQUIREMENTS.md`, and that file is the turn. Land it like any other beat:
 
 ```bash
-gtd land --json=script | sh
+s=$(gtd land --json=script) && sh -c "$s"
 ```
 
 `gtd next --json=validate` is there if you want to check the agent's work first:
@@ -303,7 +303,7 @@ while :; do
     # Nothing left to do, abort.
     stalled) gtd next >&2; exit 1 ;;
   esac
-  gtd land --json=script | sh
+  s=$(gtd land --json=script) && sh -c "$s"
 done
 ```
 
@@ -346,9 +346,9 @@ The requirements go to the top of `.gtd/TODO.md`, above whatever it already
 holds. A long, multi-line requirements paste still starts a process; if Claude
 Code never expanded the paste, gtd says it could not read it, and you add the
 requirements to the top of `.gtd/TODO.md` and run `/gtd`. `/gtd <door> [args]`
-takes one of the doors `gtd doors` lists (gtd-workflows' `default` brings `fix`,
-`review [base]`, and `rollout <flag>` and `cleanup <flag>` where the config
-exports them); text whose word count does not fit a door's args (bare
+takes one of the doors a bare `gtd start` lists (gtd-workflows' `default` brings
+`fix`, `review [base]`, and `rollout <flag>` and `cleanup <flag>` where the
+config exports them); text whose word count does not fit a door's args (bare
 `/gtd rollout` included) starts a process from that text as requirements. At
 every human rest Claude itself takes over: it walks you through the open
 questions one at a time, answers your own questions about the plan or the diff,
@@ -381,7 +381,7 @@ But lets be honest, who reads documentation these days. Paste this into your
 coding agent:
 
 ```
-!gtd install
+!gtd guide
 ```
 
 It prints a self-contained briefing that teaches the agent to set the project
@@ -390,8 +390,8 @@ you what you want before it starts driving. You get one prompt to paste, not a
 state name to choose. The four commands: **`gtd-build`** drives beats until the
 process rests; **`gtd-edit`** opens the steering file the process is waiting on
 right now — falling back to `.gtd/TODO.md` when the resting state declares none;
-**`gtd-door <name> [args...]`** starts a process through one of the doors
-`gtd doors` lists (`gtd-door fix`, `gtd-door review [base]` with gtd-workflows'
+**`gtd-door <name> [args...]`** starts a process through one of the doors a bare
+`gtd start` lists (`gtd-door fix`, `gtd-door review [base]` with gtd-workflows'
 `default`) and drives it. The `.gtd/TODO.md` fallback is also how you begin: on
 a clean repository the edit command opens the empty `.gtd/TODO.md`, and whatever
 you write there is the first sketch the whole process gets planned from. As a
@@ -447,9 +447,9 @@ The workflow itself is a plain async TypeScript function, and the
 `gtd.config.ts` at the repository root names it. A workflow may be a factory —
 `feature({ testCommand: "npm run ci" })` — whose options gtd validates when it
 loads the config: a misspelled or mistyped one fails every command, naming the
-workflow, the key and what was expected. `gtd doors` lists the doors of the
-workflows your config exports, and `gtd --workflow <name>` starts any workflow
-by name. See
+workflow, the key and what was expected. `gtd start` lists the workflows your
+config exports and the doors they bring, and `gtd start <name> [args...]` starts
+one by name; a door named like a workflow wins. See
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md) —
 and remember gtd evaluates that file on every command. A shared workflow package
 bundling its own `@pmelab/gtd` is checked against the running gtd and refused,
@@ -484,14 +484,16 @@ doesn't lose it. `/gtd ship` pushes this process's own ref to origin alongside
 the branch (never the others) and writes a `Gtd-History: <ref>` trailer on the
 squashed commit. The push is forced, so it replaces origin's copy of that one
 ref. If that push fails, the ship fails and nothing is squashed. Recover the
-full trail with `gtd history fetch | sh`, then `gtd history show <ref>`.
+full trail with `s=$(gtd history fetch --json=script) && sh -c "$s"`, then
+`gtd history show <ref>`.
 
 ```sh
 gtd history list                 # one line per kept process
 gtd history show <ref>           # replay its steps, judge verdicts and approvals
 gtd history metrics [ref...]     # how the kept processes went, per process and in total
 gtd history judges [ref...]      # how often each judge's verdicts were overturned
-gtd history fetch | sh           # pull every kept ref from origin
+# pull every kept ref from origin
+s=$(gtd history fetch --json=script) && sh -c "$s"
 ```
 
 `gtd history metrics` measures gtd-workflows' `default` `feature` workflow from
@@ -537,12 +539,13 @@ contradicts it:
 
 Any other verdict has no outcome. The report counts verdicts, scored verdicts
 and overturns per judge and per `p` bucket (`0.8-0.9: 1/2` — one of two
-overturned). `--var <threshold>=<value>` re-decides every past verdict under
-another threshold and prints the decisions that would change, against the
-threshold each process recorded (a process that recorded none is left out):
+overturned). `--threshold <name>=<value>` (formerly `--var`) re-decides every
+past verdict under another threshold and prints the decisions that would change,
+against the threshold each process recorded (a process that recorded none is
+left out):
 
 ```sh
-gtd history judges --var qualityTriageMinP=0.9
+gtd history judges --threshold qualityTriageMinP=0.9
 # what-if qualityTriageMinP=0.9: 7 noise drops become notes (2 overturned)
 ```
 
@@ -600,25 +603,26 @@ approvals as `approvals` (`[]` when none), and `gtd history show` prints each as
 gtd is one package, `@pmelab/gtd`, and every entrypoint shares its version and
 [SemVer promise](https://github.com/pmelab/gtd/blob/main/COMPATIBILITY.md).
 
-| Import                        | What it is                                                                                                                                                                      |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@pmelab/gtd/flows`           | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), `scope`, workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                                |
-| `@pmelab/gtd/wire`            | The driver protocol: `WIRE_SCHEMA`, the exit codes and the types of every `--json` document.                                                                                    |
-| `@pmelab/gtd/steering`        | The steering-file formats (`qa`, `review`, `findings`) and the review-note readers.                                                                                             |
-| `@pmelab/gtd/workflow-kit`    | Policy-free building blocks to compose a workflow from: health checks, quality laps, scenario freezing, review tails.                                                           |
-| `@pmelab/gtd/testkit`         | Runs any workflow against the real engine in an in-memory repository, under any test runner. See [Testing a workflow](https://github.com/pmelab/gtd/blob/main/docs/testing.md). |
-| `@pmelab/gtd/testkit/gherkin` | The testkit as quickpickle steps for vitest. Needs `vitest` and `quickpickle`, optional peer dependencies.                                                                      |
+| Import                        | What it is                                                                                                                                                                                                                         |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@pmelab/gtd/flows`           | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), `scope`, `workflow()`, workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                                                                     |
+| `@pmelab/gtd/wire`            | The driver protocol: `WIRE_SCHEMA`, the exit codes and the types of every `--json` document.                                                                                                                                       |
+| `@pmelab/gtd/steering`        | The steering-file formats (`qa`, `review`, `findings`), the review-note readers, and `sections`, `threads` and `openQuestions` as plain functions.                                                                                 |
+| `@pmelab/gtd/workflow-kit`    | Policy-free building blocks to compose a workflow from: health checks, quality laps, scenario freezing, review tails. See [Workflow kit](https://github.com/pmelab/gtd/blob/main/docs/workflow-kit.md).                            |
+| `@pmelab/gtd/testkit`         | Runs any workflow against the real engine in an in-memory repository, under any test runner, plus a flow-context harness for rendering prompts. See [Testing a workflow](https://github.com/pmelab/gtd/blob/main/docs/testing.md). |
+| `@pmelab/gtd/testkit/gherkin` | The testkit as quickpickle steps for vitest. Needs `vitest` and `quickpickle`, optional peer dependencies.                                                                                                                         |
 
 Types come from the TypeScript sources the package ships. Configs never need an
 install for any of these but the testkit's: gtd resolves a `gtd.config.ts`'s
 `@pmelab/gtd/*` imports to its own copy.
 
-The `gtd` bin's commands — `next`, `land`, `abandon`, `restore`, `validate`,
-`check`, `uncheck`, `install`, `summary`, `base`, `door`, `doors`, `version`,
-`help`, `history list`, `history show`, `history metrics`, `history judges`,
-`history fetch`, `strays`, and the tools `ui`, `lsp`, `judge` (`judge answer`,
+The `gtd` bin's commands — `next`, `land`, `start`, `abandon`, `restore`,
+`validate`, `check`, `uncheck`, `guide`, `summary`, `base`, `version`, `help`,
+`history list`, `history show`, `history metrics`, `history judges`,
+`history fetch`, `strays`, the tools `ui`, `lsp`, `judge` (`judge answer`,
 `judge run`) — are listed in the
-[CLI reference](https://github.com/pmelab/gtd/blob/main/docs/cli.md).
+[CLI reference](https://github.com/pmelab/gtd/blob/main/docs/cli.md). Every
+command that prints a script takes `--json=script`, and `--` ends the options.
 
 ## License
 

package/claude/hooks/doors.ts

@@ -1,4 +1,4 @@
-// Doors are the workflow's named shortcuts into a process (`gtd doors`). gtd
+// Doors are the workflow's named shortcuts into a process (`gtd start` lists them). gtd
 // prints the script that starts one; running it is the driver's job, as with
 // every git write gtd plans. The mod hardcodes no door: it asks gtd.
 
@@ -12,19 +12,23 @@ export type Door = {
 
 const fail = (text: string): Shipped => ({ ok: false, text })
 
+type Startable = { kind: "workflow"; name: string } | ({ kind: "door" } & Door)
+
 // Every door the repository offers; none when gtd cannot say.
 export async function doors(io: ShipIo): Promise<Door[]> {
-  const listed = await io.run(["gtd", "doors", "--json"])
+  const listed = await io.run(["gtd", "start", "--json"])
   if (listed.code !== 0) return []
   try {
-    return JSON.parse(listed.out) as Door[]
+    return (JSON.parse(listed.out) as Startable[]).flatMap((s) =>
+      s.kind === "door" ? [{ name: s.name, workflow: s.workflow, args: s.args }] : [],
+    )
   } catch {
     return []
   }
 }
 
 export async function enter(io: ShipIo, name: string, args: string[]): Promise<Shipped> {
-  const argv = ["gtd", "door", name, ...args]
+  const argv = ["gtd", "start", name, ...args]
   const planned = await io.run(argv)
   if (planned.code !== 0)
     return fail(planned.err.trim() || `${argv.join(" ")} exited ${planned.code}`)