@pmelab/gtd 20.4.0 → 21.1.0

package/.claude-plugin/plugin.json

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

@@ -56,7 +56,9 @@ enforces it at the OS level. See
 
 ## Quick start
 
-Pipe the output of `gtd install` into your coding agent and answer its
+Run `gtd install` at your repository's root. It writes a `gtd.config.ts` that
+runs gtd's shipped workflows — commit it; gtd refuses to run without one — and
+prints a briefing. 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.
 
@@ -92,9 +94,9 @@ Two commands make up the whole cycle. **`gtd next` says what to do now.
 that.
 
 The fastest way to understand it is to drive a few beats by hand. Any git
-repository with at least one commit will do — the first two beats need no setup
-at all, and `gtd init` seeds the one setting that matters later (your test
-command).
+repository with at least one commit will do once `gtd install` has written its
+`gtd.config.ts` and you have committed it — the first two beats need nothing
+else. Later beats run your test command, set under `env:` in `.gtdrc`.
 
 ### Beat 1 — `gtd next` says whose turn it is
 
@@ -412,20 +414,22 @@ noted in steps 3 and 4 below.
    users only; model `haiku`, `--model <name>` overrides) and reuses its login.
    With no `--provider`, `gtd judge run` picks jev when `TYPESAFE_API_KEY` is
    set and non-empty and no `--model` is given, else llm — never falling back
-   across them; a `.gtdrc` `judge: { provider, model }` key and the
-   `GTD_JUDGE_PROVIDER` / `GTD_JUDGE_MODEL` environment variables choose the
-   judge without editing the driver (flags win over both); `--model` with
-   `--provider fixed`/`jev` is refused. jev and llm exit 1 with nothing on
-   stdout when they cannot answer every question):
+   across them; the `GTD_JUDGE_PROVIDER` / `GTD_JUDGE_MODEL` environment
+   variables, a user-level `~/.config/gtd/judge.json` `{ provider, model }`, and
+   a `.gtdrc` `judge:` key choose the judge without editing the driver (flags
+   win over all three, in that order); `--model` with `--provider fixed`/`jev`
+   is refused. jev and llm exit 1 with nothing on stdout when they cannot answer
+   every question):
    - Every red round after the first: was the failure identical, new, or
      progress?
    - 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
+   gtd itself never calls a judge: `gtd loop`, the Claude Code mod and the
+   reference driver answer these through `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.7 floor
    and skip a gate unattended.**
 
@@ -505,9 +509,10 @@ starts a pure review of everything from `<commitish>` to HEAD — straight to st
 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
-are exported for yours to reuse. See
+The workflow itself is a plain async TypeScript function, and the
+`gtd.config.ts` at the repository root names it: the one `gtd install` writes
+re-exports the shipped workflows from `@pmelab/gtd/workflows`, and the pieces
+they are built from are exported for yours to reuse. 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,

package/claude/hooks/drive.ts

@@ -119,7 +119,9 @@ async function act(
 
 async function message(io: Io, b: Beat, beat: number, judged: string | undefined): Promise<Acted> {
   const verdict = b.judge && judged !== b.state ? await io.judge() : undefined
-  if (verdict || beat === 1) return { verdict }
+  // An unanswered judge gate never lands on its own, opening beat included:
+  // that would take the conservative default unseen.
+  if (verdict || (beat === 1 && !b.judge)) return { verdict }
   // Any later beat is a gate this run produced and the human has not read yet.
   const stop: Stop = { kind: "gate", text: b.content ?? "", ...where(b) }
   if (b.judge) stop.isJudge = true

package/claude/hooks/judge.ts

@@ -1,7 +1,8 @@
-// gtd's `llm` judge provider, answered by a subagent instead of `claude -p`.
-// A port of src/judges/providers/llm.ts (which needs Node, which a mod has
-// not): claude/hooks/judge.test.ts pins the prompt to gtd's own, so the two
-// cannot drift apart unnoticed.
+// A judge gate is answered by `gtd judge run`, except where its own
+// configuration would pick the `llm` provider: that one is answered by a
+// subagent instead of `claude -p`. A port of src/judges/providers/llm.ts
+// (which needs Node, which a mod has not): claude/hooks/judge.test.ts pins the
+// prompt to gtd's own, so the two cannot drift apart unnoticed.
 
 type Question = {
   id: string
@@ -14,6 +15,19 @@ export type Judgment = { state?: Record<string, string>; questions: Question[] }
 
 type Verdict = { id: string; answer: string | number; p: number }
 
+// The env a `gtd judge run` spawn adds to the inherited one, or `undefined` to
+// put the gate to the in-session subagent. A provider configured only in a
+// file is invisible here, so no variable and no key means the llm, as `gtd
+// judge run`'s own automatic pick does.
+export function judgeRunEnv(env: {
+  provider?: string | undefined
+  key?: string | undefined
+}): Record<string, string> | undefined {
+  const provider = env.provider || undefined
+  if (provider === "llm" || (provider === undefined && !env.key)) return undefined
+  return env.key ? { TYPESAFE_API_KEY: env.key } : {}
+}
+
 export const JUDGE_SYSTEM =
   "You are a strict, impartial judge. Answer each question from the supplied evidence alone.\n" +
   "Reply only with the structured answer; never use tools or ask questions."

package/claude/hooks/register.tsx

@@ -9,7 +9,7 @@ import type { Io, Turn, TurnEnd } from "./drive"
 import { doors, enter } from "./doors"
 import { subagentModel } from "./models"
 import { personaSpec, resumable } from "./persona"
-import { JUDGE_SYSTEM, judgePrompt, toVerdicts } from "./judge"
+import { JUDGE_SYSTEM, judgePrompt, judgeRunEnv, toVerdicts } from "./judge"
 import type { Judgment } from "./judge"
 import { catchFrom, throwTo } from "./handoff"
 import { documents } from "./schema"
@@ -153,13 +153,16 @@ function io($: $): Io {
     },
     judge: () =>
       docs($).judge(async (doc, j) => {
-        const key = (await $.env.get("TYPESAFE_API_KEY")) ?? (await $.env.get("TYPESAFE_AI_KEY"))
-        if (!key) return judgeInSession($, j)
+        const env = judgeRunEnv({
+          provider: await $.env.get("GTD_JUDGE_PROVIDER"),
+          key: (await $.env.get("TYPESAFE_API_KEY")) || (await $.env.get("TYPESAFE_AI_KEY")),
+        })
+        if (env === undefined) return judgeInSession($, j)
         try {
-          const r = await $.process.run(["gtd", "judge", "run", "--provider", "jev"], {
+          const r = await $.process.run(["gtd", "judge", "run"], {
             cwd: root,
             stdin: doc,
-            env: { TYPESAFE_API_KEY: key },
+            env,
             timeoutMs: TEN_MINUTES,
           })
           return r.exitCode === 0 && r.stdout.trim() ? r.stdout : undefined
@@ -511,8 +514,8 @@ async function writer($: $, prompt: string) {
   return delegate($, SHIPPER, prompt, model, "Your final answer, exactly as you would print it.")
 }
 
-// Without a TypeSafe key a judge gate is put to a small model, as gtd's own
-// llm provider does, but as a subagent of this session. Any doubt leaves the
+// Where `gtd judge run` would pick its llm, a judge gate is put to a small
+// model as that provider does, but as a subagent of this session. Any doubt leaves the
 // gate to the person, which routes the workflow its cautious way.
 async function judgeInSession($: $, j: Judgment) {
   try {