@pmelab/gtd 2.3.0 → 2.4.0

package/README.md

@@ -5,11 +5,12 @@
 > in the first place. Now I have something that actually helps me.
 
 A git-aware CLI that drives a turn-taking loop between a human and an autonomous
-coding agent: capture an idea, grill it into a plan, decompose it into work
-packages, execute with parallel subagents, test, agentically review each
-package, walk a human through a review, distill durable lessons from the cycle
-into the project's own docs, and finally squash the whole cycle into one
-conventional-commits commit at the end.
+coding agent: capture an idea, grill it into a product-level plan, grill that
+into a technical architecture, decompose it into work packages, execute with
+parallel subagents, test, agentically review each package, walk a human through
+a review, distill durable lessons from the cycle into the project's own docs,
+and finally squash the whole cycle into one conventional-commits commit at the
+end.
 
 Internally, gtd is a **pure fold** over git history. The decision core
 (`src/Machine.ts`) is a single IO-free function, `resolve(events)` — **no
@@ -19,7 +20,7 @@ merge-base with the default branch (whole-history fallback when there is no
 default branch, when HEAD equals the merge-base, or when there is no merge-base)
 plus the working tree, turns them into a `COMMIT[]` + single terminal `RESOLVE`
 event stream, and folds them through the machine. The fold lands on exactly
-**one** of 20 states, plus which actor (human or agent) is awaited there. A
+**one** of 21 states, plus which actor (human or agent) is awaited there. A
 single call resolves to a single state.
 
 Steering is entirely **machine-authored commit subjects** — there are no marker
@@ -28,7 +29,8 @@ files, sentinels, or auto-advance tails to parse. A turn commit looks like
 the machine performs itself between turns) looks like `gtd: tests green`.
 `src/Subjects.ts` is the closed grammar both the machine and the edge read.
 
-All workflow state lives under **`.gtd/`**: the plan (`.gtd/TODO.md`), work
+All workflow state lives under **`.gtd/`**: the product plan (`.gtd/TODO.md`),
+the technical architecture it converges into (`.gtd/ARCHITECTURE.md`), work
 packages (`.gtd/01-…/`), review records (`.gtd/REVIEW.md`, `.gtd/FEEDBACK.md`),
 and loop bookkeeping (`.gtd/ERRORS.md`, `.gtd/HEALTH.md`, `.gtd/LEARNINGS.md`,
 `.gtd/SQUASH_MSG.md`). One rule follows for every agent in the loop: **never
@@ -56,9 +58,10 @@ An agent loop is a two-beat protocol repeated forever:
    act, then go back to step 1; at a pending checkpoint (`prompt` is null) go
    straight back to step 1.
 
-A human acts by editing files (answering questions in `.gtd/TODO.md`, annotating
-`.gtd/REVIEW.md`, fixing code) and then running `gtd step` to capture the edit
-as their turn and hand control back to the agent side of the loop.
+A human acts by editing files (answering questions in `.gtd/TODO.md` or
+`.gtd/ARCHITECTURE.md`, annotating `.gtd/REVIEW.md`, fixing code) and then
+running `gtd step` to capture the edit as their turn and hand control back to
+the agent side of the loop.
 
 ```bash
 gtd step-agent            # advance the machine's own bookkeeping
@@ -166,8 +169,8 @@ invocation authored (oldest→newest), then a final `state: <state>` line:
 
 ```
 committed: gtd(human): grilling
-committed: gtd: grilled
-state: grilled
+committed: gtd: architecting
+state: architecting
 ```
 
 `--json` emits `{state, actions, commits}` instead (see
@@ -296,9 +299,9 @@ single-line JSON output instead of plain text.
 
 ```json
 {
-  "state": "grilled",
+  "state": "architecting",
   "actions": ["capture the human turn as \"gtd(human): grilling\""],
-  "commits": ["gtd(human): grilling", "gtd: grilled"]
+  "commits": ["gtd(human): grilling", "gtd: architecting"]
 }
 ```
 
@@ -429,9 +432,9 @@ GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
 
 ## States & subjects overview
 
-`resolve()` lands on exactly one of **20 states**: `grilling`, `grilled`,
-`planning`, `building`, `testing`, `fixing`, `escalate`, `agentic-review`,
-`close-package`, `review`, `await-review`, `done`, `learning`,
+`resolve()` lands on exactly one of **21 states**: `grilling`, `architecting`,
+`grilled`, `planning`, `building`, `testing`, `fixing`, `escalate`,
+`agentic-review`, `close-package`, `review`, `await-review`, `done`, `learning`,
 `await-learning-review`, `learning-apply`, `learning-applied`, `squashing`,
 `idle`, `health-check`, `health-fixing`. Each state has a fixed awaited actor
 (see `awaitedActor` in `src/Machine.ts`): `idle`, `escalate`, `await-review`,
@@ -448,7 +451,8 @@ The closed set of gates:
 
 | Gate             | Authored by                                                        |
 | ---------------- | ------------------------------------------------------------------ |
-| `grilling`       | human (answers) / agent (plan iteration)                           |
+| `grilling`       | human (answers) / agent (product-plan iteration)                   |
+| `architecting`   | human (answers) / agent (architecture iteration)                   |
 | `grilled`        | agent (converged, ready to decompose)                              |
 | `building`       | agent (package work, or human feedback while agent is out of turn) |
 | `fixing`         | agent (test-fix or review-fix round)                               |
@@ -463,8 +467,8 @@ The closed set of gates:
 ### Routing commits — `gtd: <phase>`
 
 Bookkeeping the machine authors itself between turns, never a turn a human or
-agent "wins": `gtd: grilled`, `gtd: planning`, `gtd: tests green`,
-`gtd: errors`, `gtd: package done`, `gtd: awaiting review`,
+agent "wins": `gtd: architecting`, `gtd: grilled`, `gtd: planning`,
+`gtd: tests green`, `gtd: errors`, `gtd: package done`, `gtd: awaiting review`,
 `gtd: review feedback`, `gtd: done`, `gtd: squash template`,
 `gtd: reviewing <hash>` (parameterized, from `gtd review`), `gtd: health-check`,
 `gtd: health-fix`, `gtd: learning template`, `gtd: learning drafted`,
@@ -477,25 +481,39 @@ this matters on upgrade.
 
 ## Workflow walkthroughs
 
-### Grilling
+### Grilling: two phases, product then architecture
 
 A dirty tree at a boundary HEAD (a fresh idea, sketched in a file or just left
 as pending code) is captured in **one** human turn: `gtd step` commits
 everything pending as `gtd(human): grilling` — nothing is reverted or seeded,
 the captured files stay in history. `gtd next` hands the agent that turn's diff;
-the agent develops `.gtd/TODO.md` into a concrete plan **in one turn**,
-proposing a **suggested default** for every open question, and leaves
-`.gtd/TODO.md` uncommitted for `gtd(agent): grilling`.
+the agent develops `.gtd/TODO.md` into a concrete **product-level** plan **in
+one turn** — user-facing decisions only, no architecture — proposing a
+**suggested default** for every open question, and leaves `.gtd/TODO.md`
+uncommitted for `gtd(agent): grilling`.
 
 There are no markers to answer — the human either:
 
 - **Accepts the suggested defaults**: runs a clean `gtd step` at the answer
-  gate. An empty `gtd(human): grilling` turn plus routing `gtd: grilled` lands
-  automatically, and `gtd next` emits the decompose prompt.
+  gate. An empty `gtd(human): grilling` turn plus routing `gtd: architecting`
+  lands automatically — `.gtd/ARCHITECTURE.md` is seeded from the converged
+  `.gtd/TODO.md` content and `.gtd/TODO.md` is deleted, in that one commit.
 - **Edits `.gtd/TODO.md`** with real answers, then runs `gtd step`, which
   captures the edit as a fresh `gtd(human): grilling` turn and hands it back to
   the agent for another round.
 
+Technical architecting works exactly the same way, one file later: the agent
+develops `.gtd/ARCHITECTURE.md` into a concrete **technical** plan — file/module
+structure, data model, tech-stack choices — and the human answers or accepts
+defaults at the `architecting` gate. Accepting converges to `gtd: grilled` and
+`gtd next` emits the decompose prompt (which now reads `.gtd/ARCHITECTURE.md`).
+
+**Escape hatch for already-technical input:** if the human's initial dirty tree
+already contains `.gtd/ARCHITECTURE.md` (their own technical sketch), `gtd step`
+captures the entry turn as `gtd(human): architecting` directly, skipping product
+grilling for that cycle entirely — no CLI flag needed, it's driven purely by
+which steering file is present.
+
 ### Build lifecycle: budgets
 
 Once decomposed, `.gtd/` holds ordered work packages. `gtd next` at
@@ -531,16 +549,16 @@ the threshold simply closes the package as usual.) Setting
 `agenticReview: false` force-approves every package immediately.
 
 A **do-nothing agent invocation** — `gtd step-agent` on a clean tree at ANY
-agent-awaited rest whose move is a file artifact (`grilling`, `grilled`,
-`building`, `fixing`, `agentic-review`, `review`, `squashing` while
+agent-awaited rest whose move is a file artifact (`grilling`, `architecting`,
+`grilled`, `building`, `fixing`, `agentic-review`, `review`, `squashing` while
 `.gtd/SQUASH_MSG.md` still holds the unmodified template, `learning` while
 `.gtd/LEARNINGS.md` still holds the unmodified template, and `learning-apply`
 unconditionally) — is inert: zero commits, no state consumed; `gtd next`
 re-emits the same prompt. This is load-bearing for the loop protocol, whose
 every iteration opens with `gtd step-agent` before the agent has acted: without
 the guard that opening beat would author junk empty turns — and worse, consume
-workflow state (an empty decompose turn would delete `.gtd/TODO.md` with no
-packages written; an empty squashing turn would squash the cycle under the
+workflow state (an empty decompose turn would delete `.gtd/ARCHITECTURE.md` with
+no packages written; an empty squashing turn would squash the cycle under the
 placeholder template). The same guards hold at the classification layer for
 histories that already carry such turns: a `gtd(agent): grilled` HEAD only
 routes to `gtd: planning` when packages exist, a `gtd(agent): review` HEAD only
@@ -549,8 +567,8 @@ routes to `gtd: awaiting review` when `.gtd/REVIEW.md` exists, and a squashing
 deliberate exception is `health-fixing`, whose empty turn is meaningful (the
 failure may have been environmental — the machine removes `.gtd/HEALTH.md` and
 re-tests). Human gates are unaffected: an empty **human** turn stays a signal
-(accept-defaults at grilling, clean approval at review, accept-the-draft-as-is
-at the learning review gate).
+(accept-defaults at grilling/architecting, clean approval at review,
+accept-the-draft-as-is at the learning review gate).
 
 ### Human review gate
 
@@ -622,15 +640,16 @@ With `squash: true` (the default), `gtd: done` (or, once learning has run,
 to `gtd: squash template`, writing and committing a `.gtd/SQUASH_MSG.md`
 template. `gtd next` then emits the squashing prompt: the agent overwrites
 `.gtd/SQUASH_MSG.md` with a real conventional-commits message (drawing on
-grilling-round decisions from history) and finishes its turn. `gtd step-agent`
-then performs the squash itself: `git reset --soft <base>` + `git commit`,
-collapsing every intermediate `gtd: *` commit of the cycle into one — including
-any review-feedback detours, and the learning phase's own commits if learning
-ran: the squash base is the cycle's ORIGINAL start (the first grilling run since
-the previous `gtd: done` boundary, or the `gtd: reviewing <hash>` anchor for an
-ad-hoc review cycle), not the most recent re-grilling round — the collapse folds
-the whole cycle into one, using the overwritten message's content verbatim (turn
-position, not message content, triggers the squash). Doc edits made during
+grilling- and architecting-round decisions from history) and finishes its turn.
+`gtd step-agent` then performs the squash itself: `git reset --soft <base>` +
+`git commit`, collapsing every intermediate `gtd: *` commit of the cycle into
+one — including any review-feedback detours, and the learning phase's own
+commits if learning ran: the squash base is the cycle's ORIGINAL start (the
+first grilling or, via the escape hatch, architecting turn since the previous
+`gtd: done` boundary, or the `gtd: reviewing <hash>` anchor for an ad-hoc review
+cycle), not the most recent re-grilling round — the collapse folds the whole
+cycle into one, using the overwritten message's content verbatim (turn position,
+not message content, triggers the squash). Doc edits made during
 `learning-apply` survive in the squashed tree, not as their own commit. With
 `squash: false`, `gtd: done` (or `gtd: learning applied`) is the resting
 boundary and no template is ever written.
@@ -659,6 +678,7 @@ fix-attempt budget to zero.
 | State                   | Awaits         | Turn/routing subject at rest                                     |
 | ----------------------- | -------------- | ---------------------------------------------------------------- |
 | `grilling`              | human or agent | `gtd(human): grilling` / `gtd(agent): grilling`                  |
+| `architecting`          | human or agent | `gtd: architecting` / `gtd(agent): architecting`                 |
 | `grilled`               | agent          | `gtd: grilled`                                                   |
 | `planning`              | agent          | `.gtd/` modified                                                 |
 | `building`              | agent          | `gtd: planning` / `gtd: package done`                            |
@@ -721,13 +741,14 @@ built-in defaults apply. Supported filenames (searched in this order):
   phase entirely — independent of `squash`.
 - **`models`** — model selection for the subagent-spawning states:
   - `planning` — high-reasoning tier (default `claude-opus-4-8`), used by
-    `decompose` (the `grilled`/`planning` states), `grilling`, `agentic-review`,
-    and `clean` (the `review`/`squashing`/`learning`/`learning-apply` states).
+    `decompose` (the `grilled`/`planning` states), `grilling`, `architecting`,
+    `agentic-review`, and `clean` (the `review`/`squashing`/`learning`/
+    `learning-apply` states).
   - `execution` — everyday tier (default `claude-sonnet-4-8`), used by
     `building` and `fixing`.
   - `states.*` — per-state overrides keyed by `decompose`, `grilling`,
-    `building`, `fixing`, `agentic-review`, `clean`. Unknown `states` keys are
-    **rejected**.
+    `architecting`, `building`, `fixing`, `agentic-review`, `clean`. Unknown
+    `states` keys are **rejected**.
 - **`$schema`** (string, optional) — stripped before validation, so it never
   counts as an unknown key. Point it at the published schema for editor-backed
   autocompletion. A `schema.json` is generated from the config schema at build
@@ -815,7 +836,7 @@ models:
 ### Decompose
 
 The Grilled/Planning states spawn a planning-model subagent that breaks
-`.gtd/TODO.md` into executable work packages under `.gtd/`:
+`.gtd/ARCHITECTURE.md` into executable work packages under `.gtd/`:
 
 ```
 .gtd/

package/dist/gtd.bundle.mjs

@@ -367039,6 +367039,7 @@ var Cwd = class _Cwd extends Context_exports.Tag("Cwd")() {
 var stateTier = {
   decompose: "planning",
   grilling: "planning",
+  architecting: "planning",
   building: "execution",
   fixing: "execution",
   "agentic-review": "planning",
@@ -367057,6 +367058,7 @@ var DEFAULT_REVIEW_THRESHOLD = 3;
 var ModelStatesSchema = Schema_exports.Struct({
   decompose: Schema_exports.optional(Schema_exports.String),
   grilling: Schema_exports.optional(Schema_exports.String),
+  architecting: Schema_exports.optional(Schema_exports.String),
   building: Schema_exports.optional(Schema_exports.String),
   fixing: Schema_exports.optional(Schema_exports.String),
   "agentic-review": Schema_exports.optional(Schema_exports.String),
@@ -387758,6 +387760,7 @@ var formatFile = (path16) => Effect_exports.gen(function* () {
 // src/Subjects.ts
 var turnSubject = (actor, gate) => `gtd(${actor}): ${gate}`;
 var ROUTING_SUBJECT = {
+  architecting: "gtd: architecting",
   grilled: "gtd: grilled",
   planning: "gtd: planning",
   "tests-green": "gtd: tests green",
@@ -387778,6 +387781,7 @@ var reviewingSubject = (baseHash) => `gtd: reviewing ${baseHash}`;
 var TURN_RE = /^gtd\((human|agent)\): (.+)$/;
 var TURN_GATES = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
@@ -387822,6 +387826,7 @@ var parseSubject = (subject) => {
 // src/Events.ts
 var GTD_DIR = ".gtd";
 var TODO_FILE = `${GTD_DIR}/TODO.md`;
+var ARCHITECTURE_FILE = `${GTD_DIR}/ARCHITECTURE.md`;
 var REVIEW_FILE = `${GTD_DIR}/REVIEW.md`;
 var FEEDBACK_FILE = `${GTD_DIR}/FEEDBACK.md`;
 var ERRORS_FILE = `${GTD_DIR}/ERRORS.md`;
@@ -387834,6 +387839,7 @@ var DONE_SUBJECT = "gtd: done";
 var WORKFLOW_FILE_EXCLUDES = [GTD_DIR];
 var GATE_OWN_STEERING_FILE = {
   grilling: TODO_FILE,
+  architecting: ARCHITECTURE_FILE,
   review: REVIEW_FILE
 };
 var SQUASH_OR_LEARNING_ROUTING_PHASES = /* @__PURE__ */ new Set([
@@ -388037,6 +388043,7 @@ var gatherEvents = (invoker) => (
     const gtdModified = entries2.some((e7) => isPackagePath(e7.path));
     const codeDirty = entries2.some((e7) => !isGtdPath(e7.path));
     const todoExists = yield* fs9.exists(resolve5(TODO_FILE));
+    const architectureExists = yield* fs9.exists(resolve5(ARCHITECTURE_FILE));
     const reviewPresent = yield* fs9.exists(resolve5(REVIEW_FILE));
     const feedbackPresent = yield* fs9.exists(resolve5(FEEDBACK_FILE));
     const errorsPresent = yield* fs9.exists(resolve5(ERRORS_FILE));
@@ -388051,6 +388058,7 @@ var gatherEvents = (invoker) => (
     const reviewCommitted = reviewTrackedAtHead && workingTreeClean;
     const reviewDirty = reviewTrackedAtHead && !workingTreeClean;
     const todoCommitted = todoExists && !isUncommitted(TODO_FILE);
+    const architectureCommitted = architectureExists && !isUncommitted(ARCHITECTURE_FILE);
     const pendingErrorsDeletion = entries2.some(
       (e7) => e7.path === ERRORS_FILE && e7.status.includes("D")
     );
@@ -388085,7 +388093,7 @@ var gatherEvents = (invoker) => (
       }
       const isGrillingTurn = (message) => {
         const parsed = parseSubject(subjectOf(message));
-        return parsed.kind === "turn" && parsed.gate === "grilling";
+        return parsed.kind === "turn" && (parsed.gate === "grilling" || parsed.gate === "architecting");
       };
       const firstGrilling = currentCycle.find((c7) => isGrillingTurn(c7.message));
       const lastAwaitingReview = (() => {
@@ -388133,7 +388141,7 @@ var gatherEvents = (invoker) => (
         const squashCycle = squashHistory.slice(prevDoneIdx + 1, lastDoneIdxForSquash + 1);
         const isGrillingTurnSubject = (subject) => {
           const parsed = parseSubject(subject);
-          return parsed.kind === "turn" && parsed.gate === "grilling";
+          return parsed.kind === "turn" && (parsed.gate === "grilling" || parsed.gate === "architecting");
         };
         const isReviewingAnchor = (subject) => {
           const parsed = parseSubject(subject);
@@ -388213,6 +388221,8 @@ var gatherEvents = (invoker) => (
       ...headTurnReviewSubstantive !== void 0 ? { headTurnReviewSubstantive } : {},
       todoExists,
       todoCommitted,
+      architectureExists,
+      architectureCommitted,
       packagesPresent: packages.length > 0,
       reviewPresent,
       feedbackPresent,
@@ -388272,6 +388282,7 @@ var SQUASH_TEMPLATE = [
   "Longer description of the change, if needed.",
   ""
 ].join("\n");
+var ARCHITECTURE_SEED_BANNER = "<!-- gtd: seeded from the converged product plan (.gtd/TODO.md); decide the technical/architectural questions below. -->\n\n";
 var LEARNING_TEMPLATE = [
   "<!-- gtd: replace this file's content with the actual distilled learnings for this cycle. -->",
   "<!-- Keep only durable, generalizable lessons \u2014 delete anything that's a one-off detail. -->",
@@ -388290,22 +388301,38 @@ var perform = (action) => (
     const resolve5 = (p4) => join10(root2, p4);
     const ensureGtdDir = fs9.makeDirectory(resolve5(GTD_DIR), { recursive: true }).pipe(Effect_exports.catchAll(() => Effect_exports.void));
     switch (action.kind) {
-      // Capture a human/agent turn: format the pending TODO.md (best-effort),
-      // then commit-all under `gtd(<actor>): <gate>` (--allow-empty).
+      // Capture a human/agent turn: format the pending TODO.md/ARCHITECTURE.md
+      // (best-effort), then commit-all under `gtd(<actor>): <gate>` (--allow-empty).
       case "captureTurn": {
         const todoExists = yield* fs9.exists(resolve5(TODO_FILE));
         if (todoExists) {
           yield* formatFile(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
+        const architectureExists = yield* fs9.exists(resolve5(ARCHITECTURE_FILE));
+        if (architectureExists) {
+          yield* formatFile(resolve5(ARCHITECTURE_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
+        }
         yield* git.commitAllWithPrefix(turnSubject(action.actor, action.gate));
         return { stop: false };
       }
       // Routing bookkeeping: delete the flagged files FIRST so their removal
       // lands in this same commit, then commit-all under `subject`.
+      // `seedArchitectureFromTodo` instead reads TODO.md, writes it (with a
+      // scaffold banner) as ARCHITECTURE.md, and deletes TODO.md — the
+      // grilling→architecting hand-off, in this same commit.
       case "commitRouting": {
-        if (action.removeTodo === true) {
+        if (action.seedArchitectureFromTodo === true) {
+          const todoContent = yield* fs9.readFileString(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.succeed("")));
+          yield* ensureGtdDir;
+          yield* fs9.writeFileString(
+            resolve5(ARCHITECTURE_FILE),
+            ARCHITECTURE_SEED_BANNER + todoContent
+          );
           yield* fs9.remove(resolve5(TODO_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
+        if (action.removeArchitecture === true) {
+          yield* fs9.remove(resolve5(ARCHITECTURE_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
+        }
         if (action.removeReview === true) {
           yield* fs9.remove(resolve5(REVIEW_FILE)).pipe(Effect_exports.catchAll(() => Effect_exports.void));
         }
@@ -388467,6 +388494,8 @@ var DEFAULT_PAYLOAD = {
   headTurnIsEmpty: false,
   todoExists: false,
   todoCommitted: false,
+  architectureExists: false,
+  architectureCommitted: false,
   packagesPresent: false,
   reviewPresent: false,
   feedbackPresent: false,
@@ -388556,6 +388585,9 @@ var learningFileConflictRules = [
 var isReviewPackagesConflict = (p4) => p4.reviewPresent && p4.packagesPresent;
 var isReviewCommittedTodoConflict = (p4) => p4.reviewPresent && p4.todoCommitted;
 var isUncommittedReviewWithTodoConflict = (p4) => p4.reviewPresent && !(p4.reviewCommitted || p4.reviewDirty) && p4.todoExists;
+var isReviewCommittedArchitectureConflict = (p4) => p4.reviewPresent && p4.architectureCommitted;
+var isUncommittedReviewWithArchitectureConflict = (p4) => p4.reviewPresent && !(p4.reviewCommitted || p4.reviewDirty) && p4.architectureExists;
+var isTodoArchitectureConflict = (p4) => p4.todoExists && p4.architectureExists;
 var isFeedbackReviewConflict = (p4) => p4.feedbackPresent && p4.reviewPresent;
 var isFeedbackWithoutPackages = (p4) => p4.feedbackPresent && !p4.packagesPresent;
 var isErrorsFeedbackConflict = (p4) => p4.errorsPresent && p4.feedbackPresent;
@@ -388571,6 +388603,15 @@ var reviewAndFeedbackRules = [
     isViolated: isUncommittedReviewWithTodoConflict,
     message: "uncommitted .gtd/REVIEW.md + .gtd/TODO.md"
   },
+  {
+    isViolated: isReviewCommittedArchitectureConflict,
+    message: ".gtd/REVIEW.md + committed .gtd/ARCHITECTURE.md"
+  },
+  {
+    isViolated: isUncommittedReviewWithArchitectureConflict,
+    message: "uncommitted .gtd/REVIEW.md + .gtd/ARCHITECTURE.md"
+  },
+  { isViolated: isTodoArchitectureConflict, message: ".gtd/TODO.md + .gtd/ARCHITECTURE.md" },
   { isViolated: isFeedbackReviewConflict, message: ".gtd/FEEDBACK.md + .gtd/REVIEW.md" },
   { isViolated: isFeedbackWithoutPackages, message: ".gtd/FEEDBACK.md without packages" },
   { isViolated: isErrorsFeedbackConflict, message: ".gtd/ERRORS.md + .gtd/FEEDBACK.md" },
@@ -388636,15 +388677,30 @@ var classifyHead = (subject, flags) => {
         kind: "mid-chain",
         state: "grilling",
         actor: "agent",
-        action: { kind: "commitRouting", subject: "gtd: grilled" }
+        action: {
+          kind: "commitRouting",
+          subject: "gtd: architecting",
+          seedArchitectureFromTodo: true
+        }
       } : { kind: "rest", state: "grilling", actor: "agent" };
     }
+    if (gate === "architecting") {
+      if (actor === "agent") {
+        return flags.headTurnIsEmpty ? { kind: "rest", state: "architecting", actor: "agent" } : { kind: "rest", state: "architecting", actor: "human" };
+      }
+      return flags.headTurnIsEmpty ? {
+        kind: "mid-chain",
+        state: "architecting",
+        actor: "agent",
+        action: { kind: "commitRouting", subject: "gtd: grilled" }
+      } : { kind: "rest", state: "architecting", actor: "agent" };
+    }
     if (actor === "agent" && gate === "grilled") {
       return flags.hasPackages ? {
         kind: "mid-chain",
         state: "grilled",
         actor: "agent",
-        action: { kind: "commitRouting", subject: "gtd: planning", removeTodo: true }
+        action: { kind: "commitRouting", subject: "gtd: planning", removeArchitecture: true }
       } : { kind: "rest", state: "grilled", actor: "agent" };
     }
     if (actor === "agent" && gate === "building") {
@@ -388718,6 +388774,8 @@ var classifyHead = (subject, flags) => {
   }
   if (parsed.kind === "routing") {
     switch (parsed.phase) {
+      case "architecting":
+        return { kind: "rest", state: "architecting", actor: "agent" };
       case "grilled":
         return { kind: "rest", state: "grilled", actor: "agent" };
       case "planning":
@@ -388764,6 +388822,7 @@ var classifyHead = (subject, flags) => {
 };
 var STATE_IS_OWN_GATE = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
@@ -388781,6 +388840,7 @@ var GATE_OVERRIDES = {
 var gateForState = (state) => STATE_IS_OWN_GATE.has(state) ? state : GATE_OVERRIDES[state] ?? "review";
 var INERT_EMPTY_AGENT_GATES = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
@@ -388883,6 +388943,9 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
   if (p4.todoExists) {
     return { kind: "rest", state: "grilling", actor: "agent" };
   }
+  if (p4.architectureExists) {
+    return { kind: "rest", state: "architecting", actor: "agent" };
+  }
   if (p4.packagesPresent && p4.packages.length > 0 && lastTurn?.actor === "agent" && lastTurn.gate === "building") {
     return {
       kind: "mid-chain",
@@ -388891,7 +388954,7 @@ var resolveBaseline = (p4, counters, head7, corrupt, lastTurn) => {
       action: { kind: "runTest", errorCount: 0, capReached: false }
     };
   }
-  if (!p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && !p4.todoExists) {
+  if (!p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && !p4.todoExists && !p4.architectureExists) {
     return resolveIdleOrHealth(p4);
   }
   return corrupt();
@@ -388904,13 +388967,14 @@ var resolveIdleOrHealth = (p4) => {
 var applyTurnTaking = (p4, counters, head7, baseline) => {
   const context10 = buildContext(p4, counters);
   const invoker = p4.invoker;
-  const isDirtyBoundaryEntry = invoker === "human" && !p4.workingTreeClean && !p4.todoCommitted && !p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
+  const isDirtyBoundaryEntry = invoker === "human" && !p4.workingTreeClean && !p4.todoCommitted && !p4.architectureCommitted && !p4.packagesPresent && !p4.reviewPresent && !p4.feedbackPresent && !p4.errorsPresent && !p4.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
   if (isDirtyBoundaryEntry) {
+    const entryGate = p4.architectureExists ? "architecting" : "grilling";
     return {
-      state: "grilling",
+      state: entryGate,
       actor: "human",
       pending: false,
-      edgeAction: { kind: "captureTurn", actor: "human", gate: "grilling" },
+      edgeAction: { kind: "captureTurn", actor: "human", gate: entryGate },
       context: context10
     };
   }
@@ -389020,9 +389084,14 @@ var predictTurn = (events) => {
     const subject = baseline.action.kind === "commitRouting" ? baseline.action.subject : baseline.action.kind === "captureTurn" ? `gtd(${baseline.action.actor}): ${baseline.action.gate}` : null;
     return { actor: baseline.actor, subject, state: baseline.state };
   }
-  const isDirtyBoundaryEntry = !payload.workingTreeClean && !payload.todoCommitted && !payload.packagesPresent && !payload.reviewPresent && !payload.feedbackPresent && !payload.errorsPresent && !payload.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
+  const isDirtyBoundaryEntry = !payload.workingTreeClean && !payload.todoCommitted && !payload.architectureCommitted && !payload.packagesPresent && !payload.reviewPresent && !payload.feedbackPresent && !payload.errorsPresent && !payload.healthPresent && (parseSubject(head7).kind === "boundary" || head7 === "gtd: done");
   if (isDirtyBoundaryEntry) {
-    return { actor: "human", subject: "gtd(human): grilling", state: "grilling" };
+    const entryGate = payload.architectureExists ? "architecting" : "grilling";
+    return {
+      actor: "human",
+      subject: `gtd(human): ${entryGate}`,
+      state: entryGate
+    };
   }
   if (baseline.state === "idle") {
     return { actor: "human", subject: null, state: "idle" };
@@ -389511,13 +389580,19 @@ var package_default = '<%\n  const lines = ["", "### Package: `" + it.pkg.name +
 var agent_turn_default = "Finish your turn by running `gtd step-agent`. Then run `gtd next` and follow\nits output \u2014 repeat this cycle as long as the output is addressed to you (the\nagent); when it awaits the human, stop and hand off.\n";
 
 // src/prompts/grilling-agent.md
-var grilling_agent_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development. Develop it into a concrete,\nimplementation-ready plan **in this one turn** \u2014 use subagents / internal\niteration to go as deep as needed; there is no further agent-only round after\nthis one.\n\n### Develop the plan\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to develop the plan.\nThe subagent works entirely by editing `.gtd/TODO.md`:\n\n1. **Explore the codebase before asking anything** \u2014 read the relevant files,\n   tests, and docs so every question below is one the codebase genuinely\n   cannot answer.\n2. **Replace the captured input / seed template with a real implementation\n   plan** \u2014 the files to change, exactly what changes, and why, grounded in\n   the codebase.\n3. **Iterate internally** (spawn further subagents, reconsider, cross-check)\n   until the plan is as complete as it can get without human input. Do not\n   leave this to a future round \u2014 there isn\'t one before the human is asked.\n4. For every remaining open question, write it near the top of the file with\n   a **suggested default** \u2014 your best-guess answer, stated plainly, that the\n   human can accept as-is. A question with no suggested default is incomplete.\n5. Leave `.gtd/TODO.md` **uncommitted** \u2014 the human\'s turn (`gtd step`) reads it\n   next.\n<% if (it.context.turnDiff && it.context.turnDiff.trim()) { %>\n<%~ include("@diff", { heading: "Latest human input (answers / sketch / review feedback)", diff: it.context.turnDiff, fenceFor: it.fenceFor }) %>\n\nRead the diff above as **feedback, not finished work**:\n\n- Code changes are suggestions \u2014 fold them into the plan and re-implement them\n  properly, including test coverage, rather than restoring them verbatim.\n- Code comments are positional feedback about the code at that location.\n- Plan-text changes are global feedback on the plan (or the reviewed work) as\n  a whole.\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var grilling_agent_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development. Develop it into a concrete,\nproduct-level plan **in this one turn** \u2014 use subagents / internal iteration\nto go as deep as needed; there is no further agent-only round after this one.\n\n**Scope: product and user-facing decisions only.** Do not decide\nimplementation details in this file \u2014 file/module structure, data models,\nlibrary or tech-stack choices, and other architecture questions belong to the\nnext phase (`.gtd/ARCHITECTURE.md`) and must not be treated as open questions\nhere.\n\n### Develop the plan\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to develop the plan.\nThe subagent works entirely by editing `.gtd/TODO.md`:\n\n1. **Explore the codebase before asking anything** \u2014 read the relevant files,\n   tests, and docs so every question below is one the codebase genuinely\n   cannot answer.\n2. **Replace the captured input / seed template with a real product plan** \u2014\n   what to build and why, and the user-facing behavior it should have,\n   grounded in the codebase. Leave *how* to build it for the next phase.\n3. **Iterate internally** (spawn further subagents, reconsider, cross-check)\n   until the plan is as complete as it can get without human input. Do not\n   leave this to a future round \u2014 there isn\'t one before the human is asked.\n4. For every remaining open question, write it near the top of the file with\n   a **suggested default** \u2014 your best-guess answer, stated plainly, that the\n   human can accept as-is. A question with no suggested default is incomplete.\n5. Leave `.gtd/TODO.md` **uncommitted** \u2014 the human\'s turn (`gtd step`) reads it\n   next.\n<% if (it.context.turnDiff && it.context.turnDiff.trim()) { %>\n<%~ include("@diff", { heading: "Latest human input (answers / sketch / review feedback)", diff: it.context.turnDiff, fenceFor: it.fenceFor }) %>\n\nRead the diff above as **feedback, not finished work**:\n\n- Code changes are suggestions \u2014 fold them into the plan and re-implement them\n  properly, including test coverage, rather than restoring them verbatim.\n- Code comments are positional feedback about the code at that location.\n- Plan-text changes are global feedback on the plan (or the reviewed work) as\n  a whole.\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/grilling-answers.md
-var grilling_answers_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development, with open questions written near\nthe top \u2014 each one carrying a suggested default.\n\nThis is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- To answer a question, edit `.gtd/TODO.md` in place (replace the question\'s text\n  with your answer, or annotate it), then run `gtd step`.\n- To accept **all** suggested defaults as-is, run `gtd step` with **no\n  edits** \u2014 this converges the plan and moves on to decomposition.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var grilling_answers_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` holds the plan under development, with open questions written near\nthe top \u2014 each one carrying a suggested default.\n\nThis is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- To answer a question, edit `.gtd/TODO.md` in place (replace the question\'s text\n  with your answer, or annotate it), then run `gtd step`.\n- To accept **all** suggested defaults as-is, run `gtd step` with **no\n  edits** \u2014 this converges the plan and moves on to technical architecting.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+
+// src/prompts/architecting-agent.md
+var architecting_agent_default = '<%~ include("@header") %>\n\n`.gtd/ARCHITECTURE.md` holds the technical plan under development \u2014 seeded\nfrom the converged product plan, or, if this is the very first turn on\nalready-technical input, written directly by the human. Develop it into a concrete,\nimplementation-ready technical plan **in this one turn** \u2014 use subagents /\ninternal iteration to go as deep as needed; there is no further agent-only\nround after this one.\n\n**Scope: technical/architectural decisions only.** Decide file/module\nstructure, data models, module boundaries, library or tech-stack choices, and\nerror-handling/concurrency strategy \u2014 the *how*, building on the *what*\nalready settled in this file\'s product content. Do not re-open or re-litigate\nproduct/user-facing decisions from the prior phase; treat them as settled\ncontext.\n\n### Develop the architecture\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to develop the\narchitecture. The subagent works entirely by editing `.gtd/ARCHITECTURE.md`:\n\n1. **Explore the codebase before asking anything** \u2014 read the relevant files,\n   tests, and docs so every question below is one the codebase genuinely\n   cannot answer.\n2. **Replace the seeded/captured content with a real architecture** \u2014 the\n   files to change, module/data-model structure, and why, grounded in the\n   codebase.\n3. **Iterate internally** (spawn further subagents, reconsider, cross-check)\n   until the architecture is as complete as it can get without human input.\n   Do not leave this to a future round \u2014 there isn\'t one before the human is\n   asked.\n4. For every remaining open question, write it near the top of the file with\n   a **suggested default** \u2014 your best-guess answer, stated plainly, that the\n   human can accept as-is. A question with no suggested default is incomplete.\n5. Leave `.gtd/ARCHITECTURE.md` **uncommitted** \u2014 the human\'s turn (`gtd step`)\n   reads it next.\n<% if (it.context.turnDiff && it.context.turnDiff.trim()) { %>\n<%~ include("@diff", { heading: "Latest human input (answers / sketch / review feedback)", diff: it.context.turnDiff, fenceFor: it.fenceFor }) %>\n\nRead the diff above as **feedback, not finished work**:\n\n- Code changes are suggestions \u2014 fold them into the architecture and\n  re-implement them properly, including test coverage, rather than restoring\n  them verbatim.\n- Code comments are positional feedback about the code at that location.\n- Plan-text changes are global feedback on the architecture (or the reviewed\n  work) as a whole.\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+
+// src/prompts/architecting-answers.md
+var architecting_answers_default = '<%~ include("@header") %>\n\n`.gtd/ARCHITECTURE.md` holds the technical plan under development, with open\nquestions written near the top \u2014 each one carrying a suggested default.\n\nThis is a human gate; there is nothing for the agent to do.\n\nTell the user:\n\n- To answer a question, edit `.gtd/ARCHITECTURE.md` in place (replace the\n  question\'s text with your answer, or annotate it), then run `gtd step`.\n- To accept **all** suggested defaults as-is, run `gtd step` with **no\n  edits** \u2014 this converges the architecture and moves on to decomposition.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/decompose.md
-var decompose_default = '<%~ include("@header") %>\n\n`.gtd/TODO.md` contains an implementation plan. Decompose it into an ordered set of\nexecutable work packages stored in the `.gtd/` directory. If `.gtd/` already\nholds packages from an earlier turn, immediately abort and raise an error.\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to perform the\ndecomposition. It creates numbered package directories, each holding numbered\ntask files:\n\n```\n.gtd/\n  01-<package-name>/\n    01-<task-name>.md\n    02-<task-name>.md\n  02-<package-name>/\n    ...\n```\n\n**Rules for the subagent:**\n\n1. **Packages are sequential, in dependency order** \u2014 ordinal-prefixed\n   directories (`01-`, `02-`, \u2026) execute in that order and the set is frozen\n   once written. Order them so each package depends only on lower-numbered ones.\n\n2. **Each package is green on its own** \u2014 the test suite runs after every\n   package. Never split a feature so the tree stays red until a later package\n   lands.\n\n3. **Tasks within a package are parallel and file-disjoint** \u2014 all tasks in a\n   package run simultaneously, each via one subagent, against the same working\n   tree with no isolation. Two tasks that would touch the same file must be\n   **merged** into one. If task B depends on task A, put them in separate\n   packages.\n\n4. **Vertical slices, not horizontal** \u2014 each package is a thin, end-to-end\n   slice that is demoable or verifiable on its own. Prefer many thin packages\n   over few thick ones; never a "set up infrastructure" package.\n\n5. **Task files are self-contained** \u2014 each task `.md` includes a clear\n   description of what to build, acceptance criteria as `- [ ] Criterion`\n   checkboxes, the relevant file paths to examine, and any constraints or edge\n   cases. It is the only context building agents will receive to work on the\n   task.\n\n6. **Specs must never reference `.gtd/` files** \u2014 `.gtd/TODO.md` is consumed\n   and **deleted** the moment decomposition completes, and every other file\n   under `.gtd/` (including these task specs) is machine-managed workflow\n   state. No task description, acceptance criterion, or constraint may require\n   creating, preserving, updating, or checking any `.gtd/` file \u2014 such a\n   criterion can never be satisfied and would derail the workflow.\n\n**DO NOT** commit any changes. This process runs within a larger orchestration\nthat depends on uncommitted changes.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var decompose_default = '<%~ include("@header") %>\n\n`.gtd/ARCHITECTURE.md` contains a converged architecture/technical plan.\nDecompose it into an ordered set of executable work packages stored in the\n`.gtd/` directory. If `.gtd/` already holds packages from an earlier turn,\nimmediately abort and raise an error.\n\nSpawn a **planning-model subagent** using model `<%= it.model %>` to perform the\ndecomposition. It creates numbered package directories, each holding numbered\ntask files:\n\n```\n.gtd/\n  01-<package-name>/\n    01-<task-name>.md\n    02-<task-name>.md\n  02-<package-name>/\n    ...\n```\n\n**Rules for the subagent:**\n\n1. **Packages are sequential, in dependency order** \u2014 ordinal-prefixed\n   directories (`01-`, `02-`, \u2026) execute in that order and the set is frozen\n   once written. Order them so each package depends only on lower-numbered ones.\n\n2. **Each package is green on its own** \u2014 the test suite runs after every\n   package. Never split a feature so the tree stays red until a later package\n   lands.\n\n3. **Tasks within a package are parallel and file-disjoint** \u2014 all tasks in a\n   package run simultaneously, each via one subagent, against the same working\n   tree with no isolation. Two tasks that would touch the same file must be\n   **merged** into one. If task B depends on task A, put them in separate\n   packages.\n\n4. **Vertical slices, not horizontal** \u2014 each package is a thin, end-to-end\n   slice that is demoable or verifiable on its own. Prefer many thin packages\n   over few thick ones; never a "set up infrastructure" package.\n\n5. **Task files are self-contained** \u2014 each task `.md` includes a clear\n   description of what to build, acceptance criteria as `- [ ] Criterion`\n   checkboxes, the relevant file paths to examine, and any constraints or edge\n   cases. It is the only context building agents will receive to work on the\n   task.\n\n6. **Specs must never reference `.gtd/` files** \u2014 `.gtd/ARCHITECTURE.md` is\n   consumed and **deleted** the moment decomposition completes, and every other file\n   under `.gtd/` (including these task specs) is machine-managed workflow\n   state. No task description, acceptance criterion, or constraint may require\n   creating, preserving, updating, or checking any `.gtd/` file \u2014 such a\n   criterion can never be satisfied and would derail the workflow.\n\n**DO NOT** commit any changes. This process runs within a larger orchestration\nthat depends on uncommitted changes.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/building.md
 var building_default = '<%~ include("@header") %>\n\nBuild the package described below by orchestrating the execution \u2014 you do not\nimplement the tasks yourself. Spawn **one subagent per task**, all in\n**parallel**, each using model `<%= it.model %>`:\n\n- **Context**: the task content only (it is self-contained).\n- **Fresh context**: each worker starts cold, with no shared history.\n- **Hands off `.gtd/`** (inline rule for workers): never create, edit, or\n  delete anything under `.gtd/` \u2014 it is workflow state owned by the machine.\n  If the task spec mentions a `.gtd/` file, skip that part.\n- **TDD discipline** (inline rules for workers):\n  - Write ONE test \u2192 implement \u2192 pass \u2192 repeat (vertical slices).\n  - **Do NOT** write all tests first then implement (horizontal slicing).\n  - Tests verify behavior through public interfaces, not implementation details\n    \u2014 a good test survives a refactor.\n\nWait for all workers to complete. **If any worker fails** (crash, timeout, error\n\u2014 not a test failure): report which tasks failed and ask the user whether to\nretry the failed tasks, skip and continue, or abort.\n\nLeave all changes uncommitted. An outside process handles that.\n<% if (it.context.packages[0]) { %>\n<%~ include("@package", { pkg: it.context.packages[0], fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
@@ -389538,7 +389613,7 @@ var review_default = '<%~ include("@header") %>\n\nSpawn a **planning-model suba
 var await_review_default = '<%~ include("@header") %>\n\n`.gtd/REVIEW.md` holds the review record for the completed work. This is a human\ngate; there is nothing for the agent to do.\n\nTell the user:\n\n- Read `.gtd/REVIEW.md` (and the underlying work it points at).\n- To **approve**: run `gtd step` with no edits, or only tick checkboxes in\n  `.gtd/REVIEW.md` \u2014 either way ends the review with an approval.\n- To **request changes**: write substantive edits or annotations into\n  `.gtd/REVIEW.md` (or the code) describing what\'s wrong, then run `gtd step` \u2014\n  this sends the feedback back for another round.\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/squashing.md
-var squashing_default = '<%~ include("@header") %>\n\nThe process is **approved and done**. `.gtd/SQUASH_MSG.md` has already been\ncommitted with a template \u2014 your job is to overwrite it with the real\nconventional-commits squash message and finish your turn.\n\n### Step 1 \u2014 Extract decisions from grilling rounds\n\nScan the git history of recent `gtd: ...` / `gtd(agent): ...` /\n`gtd(human): ...` commits. Look for changes to `.gtd/TODO.md` \u2014 specifically the\n`## Captured input` sections and any edits to plan text. Extract **key\ndecisions, trade-offs, and design choices** made during grilling rounds. These\nwill appear in the commit body so the history is self-documenting.\n\n### Step 2 \u2014 Draft the commit message\n\nDraft ONE conventional-commits message:\n\n```\ntype(scope): subject\n\nbody (explain the why \u2014 motivation, trade-offs, key decisions from grilling)\n```\n\n- **type**: `feat` / `fix` / `refactor` / `chore` / `docs` / `test`\n- **subject**: imperative mood, \u2264 72 characters, lowercase after the colon\n- **body**: include the important decisions / trade-offs from grilling\n  sessions. Omit if there were no meaningful decisions to capture.\n\n### Step 3 \u2014 Overwrite .gtd/SQUASH_MSG.md\n\nReplace the **entire content** of `.gtd/SQUASH_MSG.md` (plain text, no markdown\nwrapper, no leftover template scaffolding) with the message from Step 2, then\nleave it uncommitted and finish your turn \u2014 `gtd step-agent` performs the\nsquash using this file\'s content.\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nSquash base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
+var squashing_default = '<%~ include("@header") %>\n\nThe process is **approved and done**. `.gtd/SQUASH_MSG.md` has already been\ncommitted with a template \u2014 your job is to overwrite it with the real\nconventional-commits squash message and finish your turn.\n\n### Step 1 \u2014 Extract decisions from grilling rounds\n\nScan the git history of recent `gtd: ...` / `gtd(agent): ...` /\n`gtd(human): ...` commits. Look for changes to `.gtd/TODO.md` and\n`.gtd/ARCHITECTURE.md` \u2014 specifically the `## Captured input` sections and any\nedits to plan/architecture text. Extract **key decisions, trade-offs, and\ndesign choices** made during grilling and architecting rounds. These will\nappear in the commit body so the history is self-documenting.\n\n### Step 2 \u2014 Draft the commit message\n\nDraft ONE conventional-commits message:\n\n```\ntype(scope): subject\n\nbody (explain the why \u2014 motivation, trade-offs, key decisions from grilling)\n```\n\n- **type**: `feat` / `fix` / `refactor` / `chore` / `docs` / `test`\n- **subject**: imperative mood, \u2264 72 characters, lowercase after the colon\n- **body**: include the important decisions / trade-offs from grilling\n  sessions. Omit if there were no meaningful decisions to capture.\n\n### Step 3 \u2014 Overwrite .gtd/SQUASH_MSG.md\n\nReplace the **entire content** of `.gtd/SQUASH_MSG.md` (plain text, no markdown\nwrapper, no leftover template scaffolding) with the message from Step 2, then\nleave it uncommitted and finish your turn \u2014 `gtd step-agent` performs the\nsquash using this file\'s content.\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nSquash base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
 
 // src/prompts/learning.md
 var learning_default = '<%~ include("@header") %>\n\nThe process is **approved and done**, and headed for a squash. Before that\nhappens, `.gtd/LEARNINGS.md` has been committed with a template \u2014 your job is\nto overwrite it with the real, distilled learnings from this cycle so they\nsurvive the squash even though the granular history won\'t.\n\n### Step 1 \u2014 Walk the cycle\'s history\n\nScan the git history back to the cycle\'s start (the full-process diff is\ninlined below, and `git log` over the same range shows every `gtd: ...` /\n`gtd(agent): ...` / `gtd(human): ...` commit). Look specifically for:\n\n- **Test failures and fixes** \u2014 each `gtd: errors` round and the fix that\n  followed it. What broke, and what actually made it pass?\n- **Review feedback** \u2014 human `.gtd/REVIEW.md` notes and `gtd: review\n  feedback` detours. What did the human have to correct that the agent got\n  wrong on its own?\n- **Health-check rounds** \u2014 any `gtd: health-check` / `gtd: health-fix`\n  cycles. Environmental or systemic issues surfaced outside normal building?\n- **Grilling decisions** \u2014 `.gtd/TODO.md`\'s "## Captured input" sections and\n  plan edits. Trade-offs or conventions the human specified that a future\n  agent should already know.\n\n### Step 2 \u2014 Distill, don\'t transcribe\n\nFor each thing you found, ask: is this a **durable, generalizable lesson**\n(a convention, a gotcha, a pattern this project wants followed next time), or\na **one-off detail** specific to this change? Keep only the former. A future\nagent reading this should learn something that changes how it works on this\nproject, not a recap of what happened.\n\n### Step 3 \u2014 Overwrite .gtd/LEARNINGS.md\n\nReplace the **entire content** of `.gtd/LEARNINGS.md` with your distilled\nlearnings (plain markdown, no leftover template scaffolding). If nothing\ndurable surfaced this cycle, write a short explicit note saying so \u2014 don\'t\nleave the placeholder text in place. Leave the file uncommitted and finish\nyour turn; a human reviews it next before it\'s integrated into the project\'s\nown memory (CLAUDE.md/AGENTS.md/docs).\n<% if (it.context.squashDiff && it.context.squashDiff.trim()) { %>\n<%= it.context.squashBase !== undefined ? "\\nCycle base: " + it.context.squashBase + "\\n" : "" %>\n<%~ include("@diff", { heading: "Full-process diff (`git diff " + (it.context.squashBase !== undefined ? it.context.squashBase : "<squashBase>") + " HEAD`)", diff: it.context.squashDiff, fenceFor: it.fenceFor }) %>\n<% } %>\n\n<% if (it.tail) { %>\n<%~ include(it.tail) %>\n<% } %>\n';
@@ -389558,6 +389633,7 @@ var idle_default = "The repository is idle \u2014 no work cycle is in progress a
 // src/Prompt.ts
 var PROMPT_STATES = /* @__PURE__ */ new Set([
   "grilling",
+  "architecting",
   "grilled",
   "building",
   "fixing",
@@ -389575,6 +389651,7 @@ var PROMPT_STATES = /* @__PURE__ */ new Set([
 var isPromptState = (state) => PROMPT_STATES.has(state);
 var MODEL_STATE = {
   grilling: "grilling",
+  architecting: "architecting",
   grilled: "decompose",
   building: "building",
   fixing: "fixing",
@@ -389599,6 +389676,8 @@ eta.loadTemplate("@package", package_default);
 eta.loadTemplate("@agent-turn", agent_turn_default);
 eta.loadTemplate("@grilling-agent", grilling_agent_default);
 eta.loadTemplate("@grilling-answers", grilling_answers_default);
+eta.loadTemplate("@architecting-agent", architecting_agent_default);
+eta.loadTemplate("@architecting-answers", architecting_answers_default);
 eta.loadTemplate("@decompose", decompose_default);
 eta.loadTemplate("@building", building_default);
 eta.loadTemplate("@fixing", fixing_default);
@@ -389641,6 +389720,8 @@ var buildPrompt = (result, resolveModel = builtinResolveModel, output = "plain")
   let templateName;
   if (promptState === "grilling") {
     templateName = result.actor === "human" ? "@grilling-answers" : "@grilling-agent";
+  } else if (promptState === "architecting") {
+    templateName = result.actor === "human" ? "@architecting-answers" : "@architecting-agent";
   } else {
     templateName = STATE_TEMPLATE[promptState];
   }
@@ -389731,8 +389812,11 @@ var edgeActionHandlers = {
   captureTurn: (a5) => `capture the ${a5.actor} turn as "gtd(${a5.actor}): ${a5.gate}"`,
   commitRouting: (a5) => {
     let msg = `commit routing as "${a5.subject}"`;
+    if (a5.seedArchitectureFromTodo) {
+      msg += " (seeding .gtd/ARCHITECTURE.md from .gtd/TODO.md)";
+    }
     const removed = [];
-    if (a5.removeTodo) removed.push(".gtd/TODO.md");
+    if (a5.removeArchitecture) removed.push(".gtd/ARCHITECTURE.md");
     if (a5.removeReview) removed.push(".gtd/REVIEW.md");
     if (a5.removeFeedback) removed.push(".gtd/FEEDBACK.md");
     if (a5.removeHealth) removed.push(".gtd/HEALTH.md");

package/package.json

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

package/schema.json

@@ -33,6 +33,9 @@
             "grilling": {
               "type": "string"
             },
+            "architecting": {
+              "type": "string"
+            },
             "building": {
               "type": "string"
             },