@pmelab/gtd 2.8.0 → 3.1.0

package/README.md

@@ -21,18 +21,20 @@ No chat scrollback. No lost sessions. No infinite fix loops. Just git.
 - **Shareable.** Push the branch, and the workflow travels with it — the state
   lives in the commits, so another machine (or another person) picks up exactly
   where you left off.
-- **Files, not chat.** Plans live in `.gtd/TODO.md`, reviews in
-  `.gtd/REVIEW.md`. Answer the agent's questions inline, approve by ticking
-  checkboxes — all in your own editor. There is no chat UI to lose.
+- **Files, not chat.** Plans live in `.gtd/TODO.md`. Request changes by editing
+  it, approve by leaving the tree clean — all in your own editor. There is no
+  chat UI to lose.
 - **Harness agnostic.** gtd emits prompts to stdout (or JSON). Claude Code, a
   bash loop, a CI job, or you reading it out loud — the workflow doesn't care
   who executes it.
-- **Bounded, not runaway.** Fix attempts are budgeted. When the cap is hit, gtd
-  stops and escalates to a human instead of burning tokens rewriting the same
-  test for the 47th time.
-- **Clean history.** When the feature ships, all the intermediate `gtd:` commits
-  squash into one conventional commit — as if a very disciplined engineer did it
-  in one sitting.
+- **Bounded, not runaway.** Fix attempts are capped (`retry` on a state). When
+  the cap is hit, gtd redirects to a human gate instead of burning tokens
+  rewriting the same test for the 47th time.
+- **Your call on history.** Every intermediate `gtd(actor): state` commit is a
+  real, attributed commit — nothing hidden in chat. Squash them into one
+  conventional commit if you want that (an interactive rebase, an amend, a PR's
+  squash-merge, or a custom workflow with a `commit:` finale), or don't — gtd
+  makes no assumption.
 
 ## Install
 
@@ -51,30 +53,41 @@ schema stub on first run (see [Configuration](docs/configuration.md#auto-init)).
 
 ## How it works
 
-Three commands drive everything:
-
-- **`gtd step`** — advance the workflow as the **human** actor.
-- **`gtd step-agent`** — advance the workflow as the **agent** actor.
-- **`gtd next`** — print the prompt for whichever actor is currently awaited,
-  without mutating anything.
-
-The loop is two beats, repeated: run `gtd step-agent`, then `gtd next --json`.
-If the `actor` field says `"agent"`, feed the prompt to your agent and repeat;
-if it says `"human"`, stop — it's your move. You act by editing files (answering
-questions, reviewing the diff in your editor, fixing code) and running
-`gtd step`.
-
-Along the way, gtd grills your idea into a product plan, then a technical
-architecture, decomposes it into work packages, builds them one at a time, runs
-your tests after every package, has the agent review its own diff, walks you
-through a final review, and squashes the whole cycle into one clean commit.
-
-You don't have to start at the beginning: the steering file you hand the entry
-turn picks the phase — plain notes start product grilling,
-`.gtd/ARCHITECTURE.md` starts technical grilling, a final `.gtd/PLAN.md` goes
-straight to decomposition, and a hand-written `.gtd/HEALTH.md` goes straight
-into the error-fixing loop. See
-[Entry points](docs/workflow.md#entry-points-which-file-starts-the-cycle-where).
+gtd is a small **pattern machine**: named states, each awaiting one actor and
+carrying one piece of content (a script, a prompt, a message, or a squash commit
+template), with an ordered set of change-patterns routing to the next state.
+Four commands drive it:
+
+- **`gtd step <actor>`** — authenticate as `<actor>` and perform the one
+  transition the pending changes match.
+- **`gtd next [--json]`** — print whichever actor is awaited and what they
+  should do, without mutating anything.
+- **`gtd run`** — execute the awaited script (the only place gtd itself spawns a
+  subprocess), then step its actor.
+- **`gtd status`** — a dry-run report of the resolved state and which pattern
+  each pending change matches.
+
+The loop is one beat, repeated: run `gtd next --json` and dispatch on `kind` —
+`"message"` means it's a human's move (stop and hand off); `"script"` means
+`gtd run` it; `"prompt"` means feed `content` to your agent, then run
+`gtd step <actor>` once it's done. See [STATES.md](STATES.md) for the model and
+[Driving the loop](docs/loop.md) for the full protocol.
+
+Along the way, the bundled default workflow develops your sketch into an
+implementation plan — asking any open question it can't settle itself via a
+deterministic `.gtd/TODO.md` format, validated before it ever reaches you —
+builds it, runs your tests (looping on failures), and hands you a
+`.gtd/REVIEW.md` checkbox review of the cycle's diff: tick a box to approve that
+item, or edit/untick for feedback. Approving rests the cycle back at idle, with
+every turn commit still sitting in history for you to squash however you like
+(or not at all; gtd makes no assumption) — see
+[STATES.md](STATES.md#10-the-bundled-default-workflow) for the full shape. A
+heavier machine — two-phase Q&A planning, an architecture phase, task
+decomposition, a per-task build loop, and a squash finale — is preserved as a
+copy-paste `.gtdrc` example at
+[docs/examples/advanced-workflow.md](docs/examples/advanced-workflow.md). The
+workflow itself is just `.gtdrc` config — swap it for your own (see
+[Configuration](docs/configuration.md)).
 
 `gtd-loop`, installed alongside `gtd`, is a ready-to-run driver for the whole
 protocol — point it at a repo and it runs the loop until it's your turn. See
@@ -82,21 +95,29 @@ protocol — point it at a repo and it runs the loop until it's your turn. See
 
 Before wiring gtd into a repo, note the
 [repository requirements](docs/cli.md#repository-requirements) — most
-importantly: gitignore everything your test command writes.
+importantly: gitignore everything your scripts write.
+
+Editor integration: `gtd lsp` starts an LSP server over stdio for `.gtd/`
+steering files — symbols and check/uncheck actions over a `review`-mode file's
+chunks, symbols over a `qa`-mode file's open questions, diagnostics for both
+(live as you edit), and a `gtd.openSteeringFile` command that jumps to the
+current state's steering file. Config-driven via each state's `file:`/`mode:`
+(see [CLI reference](docs/cli.md#gtd-lsp)) — falls back to basename dispatch
+(`TODO.md`/`REVIEW.md`) with no config in sight.
 
 ## Documentation
 
+- [STATES.md](STATES.md) — the full pattern-machine specification: the model,
+  the pattern grammar, resolution, retry, the squash lifecycle, and the bundled
+  default workflow
 - [CLI reference](docs/cli.md) — every command, exit codes, JSON schemas,
   repository requirements
-- [The workflow](docs/workflow.md) — states, grilling, budgets, the review gate,
-  learning, squash
 - [Driving the loop](docs/loop.md) — the reference loop driver, `gtd-loop`,
   custom agents
-- [Configuration](docs/configuration.md) — `.gtdrc` schema, lookup, auto-init
-- [Upgrading from v1](docs/upgrading-from-v1.md) — breaking changes and
-  migration
+- [Configuration](docs/configuration.md) — `.gtdrc` `workflow:` schema, lookup,
+  auto-init
+- [Upgrading](docs/upgrading.md) — breaking changes and migration
 - [Development](docs/development.md) — building, testing, releasing
-- [STATES.md](STATES.md) — the full state-machine specification
 
 ## License
 

package/bin/gtd-loop

@@ -1,18 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Drives the two-beat protocol (docs/loop.md "The reference loop driver") to a
-# human gate. Both mutators are attempted every iteration, refusal-tolerant:
-# whichever actor is actually awaited claims the turn (captures the human's
-# uncommitted edit after a halt, or the agent's own edit from the previous
-# iteration), the other refuses harmlessly.
+# Drives the v3 pattern-machine loop (see docs/loop.md): each iteration asks
+# `gtd next --json` who's up and what they should do, dispatching on `kind`:
+#   - "message" (a human rest)  -> halt, tell the user what gtd is waiting on.
+#   - "script"  (a check rest) -> `gtd run` executes it and steps the check
+#     actor in one command; zero new commits = green with nothing owed (the
+#     terminal signal at idle).
+#   - "prompt"  (an agent rest) -> feed `content` to the agent, then
+#     `gtd step <actor>` ourselves — the harness owns ending the turn, not
+#     the prompt text.
+# `.model` (optional, opaque) is exported as $GTD_LOOP_MODEL for the agent
+# adapter invoked at a "prompt" rest; the default adapter appends `--model
+# "$GTD_LOOP_MODEL"` only when it's non-empty.
 prev_state=""
-prev_prompt=""
+prev_content=""
 
 while true; do
-  gtd step --json >/dev/null 2>&1 || true
-  gtd step-agent --json >/dev/null 2>&1 || true
-
   if ! next_json="$(gtd next --json 2>&1)"; then
     echo "gtd-loop: could not determine the next step:" >&2
     echo "$next_json" >&2
@@ -20,39 +24,55 @@ while true; do
     exit 1
   fi
 
-  actor="$(jq -r .actor <<<"$next_json")"
-  pending="$(jq -r .pending <<<"$next_json")"
   state="$(jq -r .state <<<"$next_json")"
-  prompt="$(jq -r .prompt <<<"$next_json")"
+  actor="$(jq -r .actor <<<"$next_json")"
+  kind="$(jq -r .kind <<<"$next_json")"
+  content="$(jq -r .content <<<"$next_json")"
+  model="$(jq -r '.model // empty' <<<"$next_json")"
 
-  if [[ "$actor" != "agent" ]]; then
+  if [[ "$kind" == "message" ]]; then
     echo "--- Your turn ($state) ---"
     gtd next
     exit 0
   fi
 
-  if [[ "$pending" == "true" ]]; then
+  if [[ "$kind" == "script" ]]; then
+    head_before="$(git rev-parse HEAD 2>/dev/null || echo none)"
+    gtd run
+    head_after="$(git rev-parse HEAD 2>/dev/null || echo none)"
+    if [[ "$head_before" == "$head_after" ]]; then
+      echo "--- Settled ($state: check passed, nothing to do) ---"
+      exit 0
+    fi
     prev_state=""
-    prev_prompt=""
+    prev_content=""
     continue
   fi
 
-  # Stall detection (skills/loop/SKILL.md): the same agent-owned state and
-  # prompt repeating means the last dispatch made no progress — stop rather
-  # than spin on it.
-  if [[ "$state" == "$prev_state" && "$prompt" == "$prev_prompt" ]]; then
+  # kind == "prompt": stall detection (skills/loop/SKILL.md) — the same
+  # agent-owned state and content repeating means the last dispatch made no
+  # progress; stop rather than spin on it.
+  if [[ "$state" == "$prev_state" && "$content" == "$prev_content" ]]; then
     echo "gtd-loop: no progress at '$state' — the agent's last turn changed nothing. Stopping to avoid spinning." >&2
     gtd next >&2
     exit 1
   fi
   prev_state="$state"
-  prev_prompt="$prompt"
+  prev_content="$content"
 
   # Swappable agent adapter: GTD_LOOP_AGENT_CMD lets any coding agent CLI
-  # stand in for the default, receiving the prompt via $GTD_LOOP_PROMPT.
+  # stand in for the default, receiving the prompt via $GTD_LOOP_PROMPT and
+  # the state's opaque model hint (if any) via $GTD_LOOP_MODEL. An adapter
+  # that ignores $GTD_LOOP_MODEL keeps working — it's exported alongside
+  # $GTD_LOOP_PROMPT, never required.
   cmd="${GTD_LOOP_AGENT_CMD:-}"
   if [[ -z "$cmd" ]]; then
-    cmd='claude -p "$GTD_LOOP_PROMPT" --dangerously-skip-permissions'
+    if [[ -n "$model" ]]; then
+      cmd='claude -p "$GTD_LOOP_PROMPT" --model "$GTD_LOOP_MODEL" --dangerously-skip-permissions'
+    else
+      cmd='claude -p "$GTD_LOOP_PROMPT" --dangerously-skip-permissions'
+    fi
   fi
-  GTD_LOOP_PROMPT="$prompt" bash -c "$cmd"
+  GTD_LOOP_PROMPT="$content" GTD_LOOP_MODEL="$model" bash -c "$cmd"
+  gtd step "$actor" >/dev/null
 done