@pmelab/gtd 18.1.0 → 20.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "18.1.0",
+  "version": "20.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

@@ -40,11 +40,15 @@ the read side to its agent. `read` is not a security boundary unless your driver
 enforces it at the OS level. See
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#file-access).
 
+> **`fastTestCommand` is required, with no fallback to `testCommand`.** Set it
+> (everything but e2e) under `env:` in `.gtdrc` or as `GTD_FASTTESTCOMMAND`; gtd
+> stops at the start gate, writing `.gtd/SETUP.md`, until it is.
+
 > **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` and `gtd lsp` 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`, `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.
 
 ## Quick start
 
@@ -303,14 +307,14 @@ Then, in any repository:
 ```
 
 That starts a process from your requirements and drives it until it needs you.
-`/gtd fix` and `/gtd review [base]` take the two side doors described below.
-Every human rest opens Claude Code's own question dialog, with a link to
-`gtd ui` for the step; review there, then answer **I'm done, continue**. When
-the process finishes, **Yes, open the pull request** (or `/gtd ship`) squashes
-it into one commit and opens it. A process can change hands at any gate: **Hand
-off to someone else** (or `/gtd throw @dev`) opens a draft pull request assigned
-to them, and `/gtd catch <pr>` picks it up exactly where it waits, so whoever
-wrote the requirements can hand the architecture to someone else. See
+`/gtd fix` and `/gtd review [base]` take the two doors described below. Every
+human rest opens Claude Code's own question dialog, with a link to `gtd ui` for
+the step; review there, then answer **I'm done, continue**. When the process
+finishes, **Yes, open the pull request** (or `/gtd ship`) squashes it into one
+commit and opens it. A process can change hands at any gate: **Hand off to
+someone else** (or `/gtd throw @dev`) opens a draft pull request assigned to
+them, and `/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote
+the requirements can hand the architecture to someone else. See
 [Inside Claude Code](https://github.com/pmelab/gtd/blob/main/docs/driver.md#inside-claude-code-the-gtd-mod).
 
 ### Then let an agent build your own
@@ -328,34 +332,34 @@ 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-review <commitish>`** starts a review round over that commitish and
-drives it; **`gtd-fix`** enters the fix process 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 final step, if it finds
-an LSP-capable editor, the briefing also offers to wire up live diagnostics and
-review actions in it — asking first and naming the exact file, and merging
-rather than overwriting your editor's config. That editor integration also adds
-a footnote at the exact cursor position with one code action, landing the cursor
-in the new, empty definition ready to type, and jumps between a footnote's
-marker and its definition both ways — so leaving a comment for the next agent
-turn never means hand-typing the `[^name]` syntax yourself. In a review file, a
-`./path#42-70` hunk pointer is also a clickable link straight to that file and
-range, no go-to-definition required. A footnote can also hold a `H:`/`A:`
-conversation (a thread — see [configuration](docs/configuration.md)); the editor
-outlines threads, flags the open ones, and a `gtd: reply` code action adds your
-empty `- H:` entry and puts the cursor there;
-`gtd check <mode> <file> --open-threads` lists the ones still waiting on you,
-and a review question gets its answer at the review gate again, not a lap. The
-same conversation works as bare `// H: …` / `// A: …` line comments (`#`, `--`,
-`;` by language) in files the process changed; `gtd check --open-threads` alone
-lists the open ones (editor-only — the phone UI does not show them).
+**`gtd-door <name> [args...]`** starts a process through a door (`gtd-door fix`,
+`gtd-door review [base]`) 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 final step, if it finds an LSP-capable editor,
+the briefing also offers to wire up live diagnostics and review actions in it —
+asking first and naming the exact file, and merging rather than overwriting your
+editor's config. That editor integration also adds a footnote at the exact
+cursor position with one code action, landing the cursor in the new, empty
+definition ready to type, and jumps between a footnote's marker and its
+definition both ways — so leaving a comment for the next agent turn never means
+hand-typing the `[^name]` syntax yourself. In a review file, a `./path#42-70`
+hunk pointer is also a clickable link straight to that file and range, no
+go-to-definition required. A footnote can also hold a `H:`/`A:` conversation (a
+thread — see [configuration](docs/configuration.md)); the editor outlines
+threads, flags the open ones, and a `gtd: reply` code action adds your empty
+`- H:` entry and puts the cursor there; `gtd check <mode> <file> --open-threads`
+lists the ones still waiting on you, and a review question gets its answer at
+the review gate again, not a lap. The same conversation works as bare `// H: …`
+/ `// A: …` line comments (`#`, `--`, `;` by language) in files the process
+changed; `gtd check --open-threads` alone lists the open ones (editor-only — the
+phone UI does not show them).
 
 ### The workflow it ships with
 
 One built-in workflow drives all of that. From where you sit, it has four
 moments — everything between them runs without you, with the judged exceptions
-noted in steps 2, 3, and 4 below.
+noted in steps 3 and 4 below.
 
 1. **You sketch.** Change anything, or write the idea into `.gtd/TODO.md`. Rough
    is fine; it is treated as a sketch, not as work.
@@ -368,25 +372,22 @@ noted in steps 2, 3, and 4 below.
    the same gate again. Close a thread by replying with a conclusion or deleting
    it. While a thread's last entry is the agent's, moving on is refused. Leave
    the file untouched and start the loop to accept the plan as-is, unanswered
-   questions and all. One point along this phase is judged rather than always
-   asking you outright:
-   - Before the how-it-should-be-built pass starts: does this plan actually need
-     one? A confident no skips it — and the review it would have raised — going
-     straight from your answers to a single built package, with no technical
-     plan shown to you at all.
-
-   The reference driver answers this judgment itself (`gtd judge run`, auto
-   selection); if that fails it shows you the message and stops, same as any
-   other question. **The `llm` provider's `p` is self-reported by the model, not
-   a measured probability, so a confidently wrong haiku verdict can skip a
-   question you would have asked.**
+   questions and all. Every plan gets the technical pass: its document has four
+   sections, in order — `## Interfaces`, `## Call Stacks`, `## E2E Scenarios`,
+   `## Unit Tests` — behind a leading `## Open Questions` when there are any.
+   `## E2E Scenarios` is never empty: it holds the scenarios, or, when nothing
+   user-visible changes, the line `No e2e change.` with a one-line reason.
 
 3. **You wait.** The work is split into packages and built one at a time, each
-   one checked against your test suite and fixed until it passes, then reviewed
-   against its own spec before moving on. Three points along that loop are
-   judged rather than always asking you outright — each stops and hands you a
-   verdict to make (`gtd judge answer`, or land with a clean tree to accept the
-   conservative default, which never skips work;
+   one starting from the unit tests it declares (a build turn missing one is
+   refused), checked against the fast suite and fixed until it passes before
+   moving on. A package that rewords a frozen `.feature` step stops at a wording
+   gate: accept the change, or reject it and the original is restored. After the
+   last package a full run (e2e included) has its own fix loop before the
+   quality lap. Two points along the process are judged rather than always
+   asking you outright — each stops and hands you a verdict to make
+   (`gtd judge answer`, or land with a clean tree to accept the conservative
+   default, which never skips work;
    `gtd judge run --provider fixed --answers <path>` — or the
    `GTD_JUDGE_ANSWERS` env var, inline JSON — answers one from a file, piped
    between `gtd judge --json` and `gtd judge answer`;
@@ -403,17 +404,15 @@ noted in steps 2, 3, and 4 below.
    stdout when they cannot answer every question):
    - Every red round after the first: was the failure identical, new, or
      progress?
-   - Before spending a review turn on a package: does the code already satisfy
-     each of its requirements?
-   - After a review turn raises concerns: would each one actually violate the
-     spec if left unaddressed, or is it a nit?
+   - After you review: is each of your notes an edit, a question, a nit or
+     praise?
 
    The reference driver answers these itself (`gtd judge run`, auto selection:
    jev when `TYPESAFE_API_KEY` is set, else `llm` via `claude`, default model
    haiku, `--model <name>` overrides); if that fails it shows you the message
    and stops. **The `llm` provider's `p` is self-reported by the model, not a
-   measured probability, so a confidently wrong verdict can clear the 0.9/0.7
-   floors and skip a gate unattended.**
+   measured probability, so a confidently wrong verdict can clear the 0.7 floor
+   and skip a gate unattended.**
 
    Once the last package is built, the whole change goes through a qualitative
    review lap before you see anything: six lenses, one turn each, in order —
@@ -421,11 +420,10 @@ noted in steps 2, 3, and 4 below.
    `conventions`, `spec-challenge`. Each traces the change from its own angle
    and records every finding, blocking or not; one fix turn then fixes ALL of
    them once, with no re-review after the fix. A clean turn means approval only
-   when that lens found nothing at all. The per-package review above only judges
-   that package against its own spec; this lap is where code quality is looked
+   when that lens found nothing at all. This lap is where code quality is looked
    at, and every round pays for it. It never replaces step 4 — your review stays
-   the final gate, and nothing here skips it. The `gtd --entry fix-precheck`
-   side door (below) repairs a red baseline through this same lap.
+   the final gate, and nothing here skips it. The `fix` door (below) repairs a
+   red baseline through this same lap.
 
    A red suite that keeps failing past a few fix attempts escalates instead of
    retrying forever: an agent turn reads the failing output and writes
@@ -438,10 +436,10 @@ noted in steps 2, 3, and 4 below.
 
 4. **You review.** You get a review document listing what changed and what to
    look at. Before you see it, an automatic risk-fix pass
-   (`build.review.fix-risks`) runs. Any risk the reviewer names (a note opening
-   with `Risk:`) is fixed first, the suite kept green, and the review rewritten
-   — once per review round, so a risk the rewrite still names reaches you
-   unfixed; risk: a fix lands with no check that the risk was real. Tick the
+   (`build.review.fix.risks.fixing`) runs. Any risk the reviewer names (a note
+   opening with `Risk:`) is fixed first, the suite kept green, and the review
+   rewritten — once per review round, so a risk the rewrite still names reaches
+   you unfixed; risk: a fix lands with no check that the risk was real. Tick the
    boxes to approve, or write what is wrong. Approving ends the process;
    feedback is judged note by note, each as `edit`, `question`, `nit` or
    `praise`. An `edit` sends the process back to step 2 for a fresh plan — it
@@ -480,15 +478,17 @@ the agent may overturn the answer. See
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md)
 for its `ui:` settings.
 
-Two side doors skip step 1. `gtd --entry fix-precheck` repairs a red baseline as
-its own reviewed commit instead of starting a process. And
+The bundled workflows are named `feature` (the ordinary start above), `fix` and
+`review`. Two doors start the other two and skip step 1. `gtd door fix` repairs
+a red baseline as its own reviewed commit instead of starting a process. And
 
 ```bash
-gtd --entry review-gate.check --var reviewBase=<commitish>
+gtd door review <commitish>
 ```
 
 starts a pure review of everything from `<commitish>` to HEAD — straight to step
-4, no planning and no building.
+4, no planning and no building. `gtd doors` lists every door; a `gtd.config.ts`
+can add its own. `gtd --workflow <name>` starts any workflow by name.
 
 The workflow itself is a plain async TypeScript function: a `gtd.config.ts` at
 the repository root replaces it, and the pieces the bundled one is built from

package/claude/hooks/doors.ts

@@ -0,0 +1,34 @@
+// Doors are the workflow's named shortcuts into a process (`gtd doors`). 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.
+
+import type { ShipIo, Shipped } from "./ship"
+
+export type Door = {
+  name: string
+  workflow: string
+  args: { name: string; optional: boolean }[]
+}
+
+const fail = (text: string): Shipped => ({ ok: false, text })
+
+// 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"])
+  if (listed.code !== 0) return []
+  try {
+    return JSON.parse(listed.out) as Door[]
+  } catch {
+    return []
+  }
+}
+
+export async function enter(io: ShipIo, name: string, args: string[]): Promise<Shipped> {
+  const argv = ["gtd", "door", name, ...args]
+  const planned = await io.run(argv)
+  if (planned.code !== 0)
+    return fail(planned.err.trim() || `${argv.join(" ")} exited ${planned.code}`)
+  const started = await io.run(["sh", "-c", planned.out])
+  if (started.code !== 0) return fail(`The door script failed.\n${started.err.trim()}`)
+  return { ok: true, text: `Started ${name}.` }
+}

package/claude/hooks/drive.ts

@@ -7,6 +7,7 @@ import type { AccessDef } from "./access"
 export type Beat = {
   kind: string
   idle?: boolean | string
+  initial?: boolean | string
   state?: string
   label?: string
   file?: string

package/claude/hooks/register.tsx

@@ -6,7 +6,7 @@ import { accessDenial } from "./access"
 import type { AccessDef } from "./access"
 import { afterReload, drive, isTrue } from "./drive"
 import type { Beat, Io, Landing, Turn, TurnEnd } from "./drive"
-import { enter } from "./entry"
+import { doors, enter } from "./doors"
 import { subagentModel } from "./models"
 import { personaSpec, resumable } from "./persona"
 import { JUDGE_SYSTEM, judgePrompt, toVerdicts } from "./judge"
@@ -257,11 +257,11 @@ async function start($: $, landTurn?: string) {
 async function begin($: $, requirements: string) {
   await findRoot($)
   const b = JSON.parse(await gtd($, ["next", "--json"])) as Beat
-  if (b.state === "idle" && !isTrue(b.idle)) {
+  if (isTrue(b.initial) && !isTrue(b.idle)) {
     const paths = (b.changes ?? []).map((c) => c.path).join(", ")
     return `The working tree has uncommitted changes (${paths}); gtd would start from those. Commit, stash or revert them, or run /gtd to start from them.`
   }
-  if (b.state !== "idle") {
+  if (!isTrue(b.initial)) {
     return `A gtd process is already underway at ${b.state}. Run /gtd to continue it.`
   }
   const file = b.file ?? ".gtd/TODO.md"
@@ -381,7 +381,7 @@ async function throwNow($: $, target: string | undefined) {
     state: b.state,
     label: b.label,
     content: b.content,
-    isIdle: b.state === "idle" && isTrue(b.idle),
+    isIdle: isTrue(b.idle),
   }
   const thrown = await throwTo(shipIo($), rest, target, new Date().toISOString()).catch(
     (err: unknown) => ({ ok: false, text: String(err) }),
@@ -401,9 +401,9 @@ async function throwNow($: $, target: string | undefined) {
   }
 }
 
-async function enterNow($: $, door: "fix" | "review", base: string | undefined) {
+async function enterNow($: $, door: string, args: string[]) {
   if ((await read($, run)).isRunning) return "Stop the loop first: /gtd stop."
-  const entered = await enter(shipIo($), door, base)
+  const entered = await enter(shipIo($), door, args)
   if (entered.ok) await start($)
   return entered.text
 }
@@ -655,9 +655,6 @@ async function command($: $, arg: string): Promise<string | undefined> {
   switch (verb) {
     case "status":
       return gtd($, ["next"])
-    case "fix":
-    case "review":
-      return enterNow($, verb, rest[0])
     case "throw":
       void throwNow($, rest[0])
       return undefined
@@ -671,14 +668,16 @@ async function command($: $, arg: string): Promise<string | undefined> {
     case "":
       return resume($)
     default:
-      return begin($, arg)
+      return (await doors(shipIo($))).some((d) => d.name === verb)
+        ? enterNow($, verb, rest)
+        : begin($, arg)
   }
 }
 
 async function resume($: $) {
   const b = JSON.parse(await gtd($, ["next", "--json"])) as Beat
-  if (b.state === "idle" && isTrue(b.idle)) {
-    return "Nothing is in progress. Start a process with /gtd <requirements>, or sketch the change in .gtd/TODO.md and run /gtd."
+  if (isTrue(b.idle)) {
+    return `Nothing is in progress. Start a process with /gtd <requirements>, or sketch the change in ${b.file ?? ".gtd/TODO.md"} and run /gtd.`
   }
   await start($)
   return undefined
@@ -726,7 +725,7 @@ export const register: Register = (on) => {
       name: "gtd",
       description: "Drive gtd until it rests on you; pass requirements to start a new process",
       argumentHint:
-        "[requirements | fix | review [base] | stop | status | ship [-n] | throw [@user] | catch <pr|branch>]",
+        "[requirements | <door> [args] | stop | status | ship [-n] | throw [@user] | catch <pr|branch>]",
       immediate: true,
     })
     return next(e)

package/claude/hooks/ship.ts

@@ -162,8 +162,9 @@ async function squash(
   }
   // `gtd summary` also describes a process still underway; shipping that
   // would publish half of it.
-  const state = (await io.run(["gtd", "next", "--json=state"])).out.trim()
-  if (state !== "idle") {
+  const initial = (await io.run(["gtd", "next", "--json=initial"])).out.trim()
+  if (initial !== "true") {
+    const state = (await io.run(["gtd", "next", "--json=state"])).out.trim()
     return fail(`The gtd process is still underway (at ${state}). Finish it, then ship.`)
   }
   const range = await processRange(git, summary.out)