@pmelab/gtd 6.8.0 → 6.9.1

package/README.md

@@ -58,13 +58,19 @@ gtd init
 This writes a `.gtdrc.json` for the bundled unified workflow, with each agent
 state's prompt saved as an editable Markdown file under `gtd-prompts/` and
 referenced from the config (review and commit both). Edit a prompt by editing
-its `gtd-prompts/*.md` file — no config edit needed. It also seeds a top-level
-`modes:` block suggesting **Prettier** as the steering-file formatter
-(`npx prettier --write` for the built-in `qa`/`review` modes — format only, so
-gtd still validates); edit or drop it freely (swap in dprint, a script, or
-delete the key). `gtd init` takes no argument. gtd ships **no** default
-workflow: a state command run before `gtd init` fails, pointing you back here.
-See [Configuration](docs/configuration.md#gtd-init) for the template.
+its `gtd-prompts/*.md` file — no config edit needed. File references resolve
+relative to **the `.gtdrc` that declares them**, so a config and its
+`gtd-prompts/` can even live in a parent directory shared across repos while gtd
+runs from each repo root — run `gtd init` from that parent directory (it need
+not be a git repo) to scaffold it there (see
+[Configuration](docs/configuration.md#content-values-inline-or-a-file-reference)).
+It also seeds a top-level `modes:` block suggesting **Prettier** as the
+steering-file formatter (`npx prettier --write` for the built-in `qa`/`review`
+modes — format only, so gtd still validates); edit or drop it freely (swap in
+dprint, a script, or delete the key). `gtd init` takes no argument. gtd ships
+**no** default workflow: a state command run before `gtd init` fails, pointing
+you back here. See [Configuration](docs/configuration.md#gtd-init) for the
+template.
 
 ## How it works
 

package/dist/gtd.bundle.mjs

@@ -189815,6 +189815,49 @@ const resolveContent = (value, configDir, where, errors) => {
 		return;
 	}
 };
+/**
+* Inline every `./`/`../` content file reference in ONE raw `workflow:` value
+* against `configDir` — the directory of the `.gtdrc` that DECLARED it — and
+* return a copy with those references replaced by the referenced file's text.
+*
+* Used by `src/Config.ts`'s `loadMerged` to resolve each config level's
+* references against its OWN file's directory BEFORE the levels are
+* deep-merged. The merge collapses every level into one anonymous object, so it
+* erases which file a given `states.x.prompt` came from; resolving up front,
+* per level, is the only way `./gtd-prompts/x.md` in a parent `.gtdrc` resolves
+* against the parent (not the cwd a child repo runs from). `compileWorkflowConfig`
+* is then invoked with `inlineFileRefs: false` on the merged result.
+*
+* Malformed shapes (a non-object workflow, non-object `states`, a non-object
+* state, a non-string content value) pass through untouched —
+* `compileWorkflowConfig`/`validateDefinition` own those findings; this pass
+* only rewrites the strings it recognizes as file references, collecting a load
+* error (via `resolveContent`) for any that is missing or unreadable.
+*/
+const inlineWorkflowFileRefs = (rawWorkflow, configDir, errors) => {
+	if (!isPlainObject$1(rawWorkflow)) return rawWorkflow;
+	const rawStates = rawWorkflow["states"];
+	if (!isPlainObject$1(rawStates)) return rawWorkflow;
+	const states = {};
+	for (const [name, state] of Object.entries(rawStates)) {
+		if (!isPlainObject$1(state)) {
+			states[name] = state;
+			continue;
+		}
+		const next = { ...state };
+		for (const key of CONTENT_KEYS) {
+			const value = state[key];
+			if (typeof value !== "string" || !isFileReference(value)) continue;
+			const resolved = resolveContent(value, configDir, `state "${name}" (${key})`, errors);
+			if (resolved !== void 0) next[key] = resolved;
+		}
+		states[name] = next;
+	}
+	return {
+		...rawWorkflow,
+		states
+	};
+};
 const KNOWN_EDGE_KEYS = /* @__PURE__ */ new Set(["to", "describe"]);
 /**
 * Compile one `on` row's value into an `OnEdge` (or `undefined`, pushing a
@@ -189883,8 +189926,15 @@ const compileRetry = (raw, name, errors) => {
 		otherwise
 	} : void 0;
 };
-/** Exactly one of script/prompt/message/commit, each a string, file-refs auto-inlined. */
-const compileContent = (raw, name, configDir, errors) => {
+/**
+* Exactly one of script/prompt/message/commit, each a string, file-refs
+* auto-inlined. `inlineFileRefs` is `false` only when the caller
+* (`src/Config.ts`'s `loadMerged`) has ALREADY inlined every reference per
+* declaring file — the content is then taken verbatim, so a `script:` whose
+* inlined text happens to begin with `./` is never mistaken for a second file
+* reference and re-resolved.
+*/
+const compileContent = (raw, name, configDir, errors, inlineFileRefs) => {
 	const content = {};
 	for (const key of CONTENT_KEYS) {
 		const rawValue = raw[key];
@@ -189893,6 +189943,10 @@ const compileContent = (raw, name, configDir, errors) => {
 			errors.push(`state "${name}": "${key}" must be a string`);
 			continue;
 		}
+		if (!inlineFileRefs) {
+			content[key] = rawValue;
+			continue;
+		}
 		const resolved = resolveContent(rawValue, configDir, `state "${name}" (${key})`, errors);
 		if (resolved !== void 0) content[key] = resolved;
 	}
@@ -189991,7 +190045,7 @@ const assembleStateDef = (parts) => ({
 	...assembleContentFields(parts.content)
 });
 /** One state's full shape: actor, content, `on`, `initial`, `retry`. */
-const compileState = (name, raw, configDir, errors) => {
+const compileState = (name, raw, configDir, errors, inlineFileRefs) => {
 	if (!isPlainObject$1(raw)) {
 		errors.push(`state "${name}": must be an object, got ${describeType(raw)}`);
 		return {};
@@ -190000,7 +190054,7 @@ const compileState = (name, raw, configDir, errors) => {
 	if (unknownKeys.length > 0) errors.push(`state "${name}": unknown key(s) ${unknownKeys.join(", ")}`);
 	return assembleStateDef({
 		actor: compileActor(raw, name, errors),
-		content: compileContent(raw, name, configDir, errors),
+		content: compileContent(raw, name, configDir, errors, inlineFileRefs),
 		on: compileOn(raw.on, name, errors),
 		initial: compileInitial(raw, name, errors),
 		retry: compileRetry(raw.retry, name, errors),
@@ -190019,12 +190073,15 @@ const compileState = (name, raw, configDir, errors) => {
 * file's own directory, used to resolve `./`/`../` file references. `rcModes`
 * is the already-compiled top-level `.gtdrc` `modes:` key (`src/Config.ts`),
 * layered over the workflow's own `modes:` per half BEFORE validation — so a
-* state may name a mode either layer declares. Throws a single
-* `Error` (message: `"workflow config:\n  - ..."`, one line per finding) on
-* ANY config-shape problem or `validateDefinition` finding — never partially
-* succeeds.
-*/
-const compileWorkflowConfig = (raw, configDir, rcModes) => {
+* state may name a mode either layer declares. `inlineFileRefs` (default
+* `true`) inlines content file references against `configDir`; the real config
+* path (`src/Config.ts`'s `loadMerged`) passes `false` because it has already
+* inlined every reference per declaring file across the merge chain, so
+* `configDir` is then irrelevant. Throws a single `Error` (message:
+* `"workflow config:\n  - ..."`, one line per finding) on ANY config-shape
+* problem or `validateDefinition` finding — never partially succeeds.
+*/
+const compileWorkflowConfig = (raw, configDir, rcModes, inlineFileRefs = true) => {
 	if (!isPlainObject$1(raw)) throw new Error(`workflow config: must be an object, got ${describeType(raw)}`);
 	const errors = [];
 	const unknownTopKeys = Object.keys(raw).filter((k) => !KNOWN_TOP_KEYS.has(k));
@@ -190037,7 +190094,7 @@ const compileWorkflowConfig = (raw, configDir, rcModes) => {
 		throw new Error(formatErrors(errors));
 	}
 	const states = {};
-	for (const [name, s] of Object.entries(rawStates)) states[name] = compileState(name, s, configDir, errors);
+	for (const [name, s] of Object.entries(rawStates)) states[name] = compileState(name, s, configDir, errors, inlineFileRefs);
 	const definition = modes !== void 0 ? {
 		states,
 		modes
@@ -190327,22 +190384,50 @@ const makeExplorer = () => (0, import_dist.cosmiconfig)("gtd", {
 /**
 * Load and deep-merge every config level from cwd up the directory chain.
 * Innermost (cwd) wins. Returns the merged plain object (undecoded).
-*/
+*
+* A `workflow:` value's `./`/`../` content file references are inlined PER
+* LEVEL against that level's OWN file directory (`dirname(result.filepath)`)
+* BEFORE merging — because the deep-merge collapses every level into one
+* anonymous object and erases which file each `states.x.prompt` came from.
+* Resolving up front is what lets a `.gtdrc` stored in a parent directory
+* reference `./gtd-prompts/x.md` and have it resolve against the parent, even
+* though gtd runs from a child repo (a different cwd). Any missing/unreadable
+* reference is collected and thrown as one aggregated `workflow config:` error,
+* exactly like the compiler's own resolution. The merged, already-inlined
+* `workflow:` is later compiled with `inlineFileRefs: false` (see
+* `toOperations`).
+*/
+/**
+* Normalize one loaded config level: validate it is a plain object, then inline
+* its `workflow:` file references against its OWN file's directory (collecting
+* any missing/unreadable reference into `refErrors`). A level with no
+* `workflow:` key passes through untouched.
+*/
+const inlineLevel = (config, filepath, refErrors) => {
+	if (!isPlainObject(config)) throw new Error(`${filepath}: config must be a plain object, got ${Array.isArray(config) ? "array" : String(config)}`);
+	if (config["workflow"] === void 0) return config;
+	return {
+		...config,
+		workflow: inlineWorkflowFileRefs(config["workflow"], dirname(filepath), refErrors)
+	};
+};
+/** Read every config level from cwd up the chain, outermost→innermost, each with its file references already inlined per declaring file. Throws on a malformed level or an aggregated set of bad references. */
+const readConfigLevels = async (root) => {
+	const chain = walkUp(root, homedir());
+	const explorer = makeExplorer();
+	const levels = [];
+	const refErrors = [];
+	for (let i = chain.length - 1; i >= 0; i--) {
+		const result = await explorer.search(chain[i]);
+		if (!result || result.isEmpty) continue;
+		levels.push(inlineLevel(result.config, result.filepath, refErrors));
+	}
+	if (refErrors.length > 0) throw new Error(`workflow config:\n${refErrors.map((e) => `  - ${e}`).join("\n")}`);
+	return levels;
+};
 const loadMerged = (root) => tryPromise({
 	try: async () => {
-		const home = homedir();
-		const chain = walkUp(root, home);
-		const explorer = makeExplorer();
-		const levels = [];
-		for (let i = chain.length - 1; i >= 0; i--) {
-			const dir = chain[i];
-			const result = await explorer.search(dir);
-			if (result && !result.isEmpty) {
-				if (!isPlainObject(result.config)) throw new Error(`${result.filepath}: config must be a plain object, got ${Array.isArray(result.config) ? "array" : String(result.config)}`);
-				levels.push(result.config);
-			}
-		}
-		return levels.reduce((acc, level) => deepMerge(acc, level), {});
+		return (await readConfigLevels(root)).reduce((acc, level) => deepMerge(acc, level), {});
 	},
 	catch: (e) => e instanceof Error ? e : new Error(String(e))
 });
@@ -190396,18 +190481,19 @@ const compileRcVars = (raw) => {
 const NO_WORKFLOW_MESSAGE = "gtd: no workflow configured — run `gtd init` to create .gtdrc.json";
 /**
 * Compile the decoded config's `workflow:` key plus its top-level
-* `vars:`/`modes:` keys into `ConfigOperations`. `root` is used as the
-* workflow compiler's `configDir` — the directory a custom workflow's
-* `./`-relative content references resolve against. Throws `NO_WORKFLOW_MESSAGE`
-* when no `workflow:` key is present (there is no bundled default to fall back
-* to — see `gtd init`), or (via `compileWorkflowConfig`/`compileRcVars`) on any
-* invalid workflow/vars.
+* `vars:`/`modes:` keys into `ConfigOperations`. Its `./`/`../` content file
+* references were already inlined per declaring file by `loadMerged`, so the
+* compiler is invoked with `inlineFileRefs: false` and `root` is passed only as
+* an (unused) `configDir` placeholder. Throws `NO_WORKFLOW_MESSAGE` when no
+* `workflow:` key is present (there is no bundled default to fall back to — see
+* `gtd init`), or (via `compileWorkflowConfig`/`compileRcVars`) on any invalid
+* workflow/vars.
 */
 const toOperations = (decoded, root) => {
 	const rcVars = compileRcVars(decoded.vars);
 	const rcModes = compileRcModes(decoded.modes);
 	if (decoded.workflow === void 0) throw new Error(NO_WORKFLOW_MESSAGE);
-	const { definition, vars: workflowVars } = compileWorkflowConfig(decoded.workflow, root, rcModes);
+	const { definition, vars: workflowVars } = compileWorkflowConfig(decoded.workflow, root, rcModes, false);
 	return {
 		workflow: definition,
 		workflowVars,
@@ -191386,7 +191472,7 @@ var WorktreeReader = class WorktreeReader extends Tag("WorktreeReader")() {
 };
 //#endregion
 //#region src/workflows/unified.yaml
-var unified_default = "# The unified gtd workflow template — written verbatim into `.gtdrc.json`\n# (nested under a `workflow:` key) by `gtd init` (no argument). gtd ships no\n# default workflow: a repo picks this bundled template with `gtd init`, and a\n# state command run with no workflow configured fails (see src/Config.ts).\n# See STATES.md §10 for the full walkthrough.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `gtd init` DERIVES the scaffolded\n# `.gtdrc.json` from this inline source (`renderInitScaffold`): each agent\n# state's `prompt:` is written out as an editable `gtd-prompts/<state>.md`\n# file; human `message:`/check `script:`/the `done` `commit:` body stay inline.\n#\n# ── Three entry points, one shared tail ────────────────────────────────────\n#\n# The initial `idle` state FORKS on which steering file the human creates:\n#\n#   * .gtd/REQUIREMENTS.md -> the ADVANCED flow (product + technical Q&A,\n#     package decomposition, per-package parallel build + agentic spec-review).\n#   * anything else (e.g. .gtd/TODO.md) -> the SIMPLE flow (one grilling Q&A\n#     loop, a monolithic build, no decomposition, no agentic review).\n#\n# A third entry, `gtd review <commitish>`, jumps straight to `reviewing`\n# (reviewEntry) to review a foreign branch through the same shared tail.\n#\n# All three converge at `reviewing` -> `await-review`. From there:\n#   * full sign-off (tick every box, or delete REVIEW.md) -> squashing -> done\n#     (the ONLY path to the finale — the whole cycle collapses into one commit).\n#   * partial sign-off / notes -> review-deciding extracts the unticked items\n#     into REVIEW_FEEDBACK.md -> feedback-building implements them -> checking\n#     -> reviewing regenerates an INCREMENTAL REVIEW.md (review-deciding carries\n#     `reviewBase: true`, so each feedback round's review + checkout window\n#     covers only `last-review..HEAD`) -> await-review, looping until sign-off.\n#   * a code-only human edit (REVIEW.md untouched) -> checking -> reviewing.\n#\n# The shared health segment (`checking`/`fixing`/`escalate`) serves the simple\n# build, the feedback loop, and code-only edits — its green edge targets\n# `reviewing`. The advanced per-package loop keeps its OWN health triple\n# (`adv-checking`/`adv-fixing`/`adv-escalate`) because its green edge targets\n# the per-package `spec-review` gate instead.\n#\n# KNOWN LIMITATION: `on` pattern keys are NOT Eta templates — they keep the\n# LITERAL `.gtd/...` paths matching these vars' DEFAULT values. Repointing a\n# file var changes what templates read/write WITHOUT changing what the `on`\n# patterns match, desyncing the machine (see docs/configuration.md).\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_VAR_plannerModel` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/architecting/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n\nstates:\n  # ── Shared entry ────────────────────────────────────────────────────────\n  idle:\n    actor: human\n    initial: true\n    # Every human-gate `message:` below closes with the same rendered \"What\n    # each change does next\" list, built from `it.edges` (the resting state's\n    # own `on` edges — each edge's `describe:` is the single source of truth).\n    message: |\n      No active gtd cycle.\n\n      To start one, create a steering file describing what you want built:\n\n      - `.gtd/TODO.md` — a short sketch — starts the SIMPLE flow (plan, build,\n        review).\n      - `.gtd/REQUIREMENTS.md` — the product requirements — starts the ADVANCED\n        flow (product + technical Q&A, package decomposition, parallel build,\n        per-package agentic review).\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* .gtd/REQUIREMENTS.md\":\n        to: adv-grilling\n        describe: >-\n          Save the product requirements to `.gtd/REQUIREMENTS.md` to start the\n          ADVANCED flow — the agent develops them through product then technical\n          Q&A, decomposes the work into packages, and builds each in parallel\n          (**adv-grilling**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Save a short sketch to `.gtd/TODO.md` (or any other change) to start\n          the SIMPLE flow — the agent reads it, explores the codebase, and\n          develops it into a concrete implementation plan (**grilling**).\n\n  # ── Simple flow: one Q&A loop, monolithic build ───────────────────────────\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.todoFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.todoFile %>` holds a short sketch of what to build (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete implementation plan.\n\n      For every question you cannot settle yourself, add it under a\n      `## Open Questions` heading near the top, one `### <question>`\n      sub-heading each, its body your suggested answer in plain prose (always\n      suggest one — the human accepts it by leaving it untouched, or overrides\n      it by editing it). Omit the section entirely once there are none.\n\n      If `<%= it.vars.todoFile %>` already carries a `## Open Questions`\n      section from a previous lap, the human has now responded to that whole\n      batch: fold every one of those questions into the plan — the human's edit\n      where they gave one, your own suggestion where they left it untouched (an\n      untouched suggestion IS acceptance) — and MOVE each resolved\n      `### <question>` block down into a `## Answered Questions` section at the\n      bottom. Raise any genuinely new questions under `## Open Questions`.\n\n      Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n      not commit, and do not run `gtd step agent` yourself; the harness does\n      that.\n    on:\n      \"* **\": grilling-answer\n\n  grilling-answer:\n    actor: human\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.todoFile %>` holds the plan under development, with any\n      open questions under `## Open Questions` — each carrying a suggested\n      answer. Answer a question by editing its body in place; leave a\n      suggestion untouched to accept it.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: building\n        describe: >-\n          Change nothing to accept every suggested answer as-is and move on to\n          implementation (**building**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Edit the plan — answer a question, add detail, or raise a new one — to\n          send it back for another round of grilling (**grilling**).\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create or edit anything under `.gtd/` except deleting\n      `<%= it.vars.todoFile %>`, which this prompt tells you to delete once its\n      work is complete.\n\n      The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n      Read that plan and implement it in full. Use TDD discipline: one test,\n      then the implementation that passes it, then the next — never write all\n      the tests first.\n\n      Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n      and verified. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  # ── Advanced flow: product + technical Q&A ────────────────────────────────\n  adv-grilling:\n    actor: agent\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.requirementsFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.requirementsFile %>` holds the product requirements (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete, PRODUCT-level plan in this one turn.\n\n      Scope: product and user-facing decisions only. Leave implementation\n      details (file/module structure, data models, tech-stack choices) for the\n      next phase (`<%= it.vars.architectureFile %>`).\n\n      For every remaining open question, add it under a `## Open Questions`\n      heading near the top, one `### <question>` sub-heading each, its body your\n      suggested answer in plain prose (always suggest one). Omit the section\n      once there are none. On a return lap, fold the whole answered batch into\n      the plan and move each resolved `### <question>` block down into a\n      `## Answered Questions` section at the bottom.\n\n      Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n    on:\n      \"* **\": adv-grilling-answer\n\n  adv-grilling-answer:\n    actor: human\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.requirementsFile %>` holds the product plan under\n      development, with any open questions under `## Open Questions` — each\n      carrying a suggested answer. Answer a question by editing its body in\n      place; leave a suggestion untouched to accept it.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: architecting\n        describe: >-\n          Change nothing to accept the product plan and move on to technical\n          architecting (**architecting**).\n      \"* **\":\n        to: adv-grilling\n        describe: >-\n          Edit the product plan — answer a question, add detail, or raise a new\n          one — to send it back for another round (**adv-grilling**).\n\n  architecting:\n    actor: agent\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.architectureFile %>` and `<%= it.vars.requirementsFile %>`,\n      which this prompt tells you to write and delete respectively.\n\n      Read `<%= it.vars.requirementsFile %>` (the converged product plan) and\n      develop `<%= it.vars.architectureFile %>` from it in this one turn:\n      file/module structure, data models, library/tech-stack choices,\n      error-handling strategy — the *how*, building on the *what* already\n      settled. Do not re-open product-level decisions; treat them as settled.\n\n      For every remaining open question, add it under a `## Open Questions`\n      heading exactly as the grilling phase does (one `### <question>` each, its\n      body your suggested answer). Omit the section once there are none. On a\n      return lap, fold the whole answered batch in and move each resolved block\n      down into a `## Answered Questions` section at the bottom.\n\n      Once `<%= it.vars.architectureFile %>` is written, delete\n      `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n      must not linger. Leave everything uncommitted and finish your turn.\n    on:\n      \"* **\": architecting-answer\n\n  architecting-answer:\n    actor: human\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.architectureFile %>` holds the technical plan under\n      development, with any open questions under `## Open Questions`. Answer a\n      question by editing its body in place; leave a suggestion untouched to\n      accept it.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: decompose\n        describe: >-\n          Change nothing to accept the technical plan and move on to decomposing\n          the work into packages (**decompose**).\n      \"* **\":\n        to: architecting\n        describe: >-\n          Edit the technical plan to send it back for another round\n          (**architecting**).\n\n  # ── Advanced flow: decomposition + per-package parallel build loop ─────────\n  decompose:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except the\n      package files this prompt tells you to write (under\n      `<%= it.vars.packagesDir %>/`), and `<%= it.vars.architectureFile %>`,\n      which it tells you to delete.\n\n      Read `<%= it.vars.architectureFile %>` (the converged technical plan) and\n      decompose it into an ordered set of WORK PACKAGES, one file each under\n      `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n      `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n      test suite can pass again after each one lands.\n\n      Each package file describes a set of INDEPENDENT tasks that can be\n      implemented concurrently without ordering constraints between them — a\n      single build turn will fan them out to parallel subagents. Give each task\n      a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n      relevant paths. Also state the package's overall requirement so it can be\n      reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n      package — split them across ordered packages instead.\n\n      No package file may reference any other `.gtd/` file. Once the package\n      files are written, delete `<%= it.vars.architectureFile %>`. Leave\n      everything uncommitted and finish your turn.\n    on:\n      \"* .gtd/packages/**\": picking\n\n  picking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package queue arbiter) — the loop driver executes\n      # this verbatim, then steps the check actor. Mechanics only: take the\n      # first package file (by name) under the packages dir into NEXT.md, or\n      # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n      # MEANS (another package to build vs. the queue closing out to review) is\n      # decided by this state's own `on` rules at capture time — never here.\n      set +e\n      next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n      if [ -n \"$next\" ]; then\n        printf '%s' \"$next\" > <%~ it.vars.nextFile %>\n      else\n        rm -f <%~ it.vars.nextFile %>\n      fi\n    on:\n      \"D .gtd/NEXT.md\": reviewing\n      \"* .gtd/NEXT.md\": adv-building\n      \"C\": reviewing\n\n  adv-building:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/`; in\n      particular do NOT delete the package file (the `spec-review` gate reads it\n      after you) and never touch `<%= it.vars.nextFile %>` — the `picking` state\n      owns it.\n\n      The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n      That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n      this one turn, fanning the independent tasks out to parallel subagents\n      where your harness supports it — each task is self-contained and can be\n      built concurrently. Implement EXACTLY the tasks this package describes — no\n      more, no less; leave every other package file untouched. Use TDD\n      discipline within each task.\n\n      Leave the package file in place and everything else uncommitted, then\n      finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  adv-checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output <%~ it.vars.feedbackFile %>\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > <%~ it.vars.feedbackFile %>\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f <%~ it.vars.feedbackFile %>\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": adv-fixing\n      \"M .gtd/FEEDBACK.md\": adv-fixing\n      \"D .gtd/FEEDBACK.md\": spec-review\n      \"C\": spec-review\n\n  adv-fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    retry:\n      max: 3\n      otherwise: adv-escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": adv-checking\n\n  adv-escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: adv-checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or\n          `.gtd/FEEDBACK.md` — to re-run the check (**adv-checking**).\n\n  spec-review:\n    actor: agent\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    # Bounded per cycle: once entered `max` times, a transition into it is\n    # redirected to `closing` (force-close the package and move on — the\n    # unresolved concern is deferred to the shared human review at the tail,\n    # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n    # pools across packages — the same documented limitation the shared\n    # `fixing` cap has (see STATES.md / docs/configuration.md).\n    retry:\n      max: 3\n      otherwise: closing\n    prompt: |\n      You are an autonomous coding agent reviewing a freshly-built work package\n      against its own spec. `.gtd/` holds this workflow's own state — never\n      create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.specFeedbackFile %>`, which this prompt tells you to write\n      when — and only when — you find problems.\n\n      The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n      Read that spec, then verify the package's implementation (the diff below)\n      against it: are all its tasks done, acceptance criteria met, and the code\n      sound and consistent with the codebase?\n\n      - If it fully satisfies the spec, write NOTHING and finish your turn — a\n        clean turn is your approval.\n      - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n        concrete problems for a fix turn to address. Be specific.\n\n      Do not fix anything yourself and do not delete the package file — a later\n      step owns that. Finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Diff under review\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"A .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"M .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"D .gtd/SPEC_FEEDBACK.md\": closing\n      \"C\": closing\n\n  spec-fix:\n    actor: agent\n    file: <%= it.vars.specFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.specFeedbackFile %>`, which this prompt tells you to address\n      and then delete.\n\n      Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n      current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n      then fix the code to resolve every concern. Keep the change focused.\n\n      Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n      Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  closing:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package closer) — remove the just-reviewed package\n      # file (its path is in NEXT.md) plus any leftover spec feedback, so\n      # `picking` selects the NEXT package (or falls through to review when the\n      # queue is empty). Reached on approval (spec-review clean) and on the\n      # spec-review retry cap (force-close, deferring the concern to the tail).\n      set +e\n      pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n      [ -n \"$pkg\" ] && rm -f \"$pkg\"\n      rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n    on:\n      \"* **\": picking\n\n  # ── Shared health segment (simple build, feedback loop, code-only edits) ──\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output <%~ it.vars.feedbackFile %>\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > <%~ it.vars.feedbackFile %>\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f <%~ it.vars.feedbackFile %>\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"D .gtd/FEEDBACK.md\": reviewing\n      \"C\": reviewing\n\n  fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    retry:\n      max: 3\n      otherwise: escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": checking\n\n  escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or `.gtd/FEEDBACK.md` —\n          to re-run the check (**checking**).\n\n  # ── Shared tail: agent review -> human review -> squash finale ────────────\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    # `gtd review <commitish>` (a plain non-gtd branch, e.g. a colleague's PR)\n    # enters here directly, recording the resolved base as a `Gtd-Review-Base:`\n    # trailer on its empty entry commit — everything below then reuses the same\n    # reviewing/await-review/feedback machinery over <commitish>..HEAD.\n    reviewEntry: true\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewFile %>`, which this prompt tells you to write.\n\n      Write `<%= it.vars.reviewFile %>` to help a human review the diff below in\n      this EXACT format:\n\n      - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n      - Somewhere in the document: `<!-- base: <%= it.startCommit %> -->`\n      - At least one `## <Chunk Title>` heading, grouping hunks semantically\n        (same feature/refactor/fix, even across files) — a short explanation of\n        what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n        pointer per hunk (checkboxes are for the human to tick, not you; every\n        path is `./`-relative, with an optional `#line` and an optional\n        ` — note`).\n\n      The diff below is `it.reviewDiff` — on a feedback round it covers ONLY the\n      changes made since the previous review, so you review just what changed,\n      not items already signed off. Leave `<%= it.vars.reviewFile %>`\n      uncommitted and finish your turn.\n      <% if (it.reviewDiff.trim()) { %>\n\n      ## Full diff under review\n\n      ```diff\n      <%~ it.reviewDiff %>\n      ```\n      <% } %>\n    on:\n      \"* **\": await-review\n\n  await-review:\n    actor: human\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # While the cycle rests here, gtd opens a \"review checkout window\": raw HEAD\n    # is rewound to the review base (the most-recent `review-deciding` commit —\n    # so a feedback round shows only `last-review..HEAD` — or the process start\n    # on the first review) with the working tree untouched, surfacing the diff\n    # as ordinary uncommitted changes. It closes on the next invocation.\n    reviewWindow: true\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the cycle — one\n      `- [ ]` checkbox per reviewable item, grouped into chunks.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"D .gtd/REVIEW.md\":\n        to: squashing\n        describe: >-\n          Delete `.gtd/REVIEW.md` outright to sign off on the whole cycle at\n          once and collapse it into one commit (**squashing**).\n      \"M .gtd/REVIEW.md\":\n        to: review-deciding\n        describe: >-\n          Edit `.gtd/REVIEW.md` — tick a `- [ ]` box to `- [x]` to sign off that\n          item, or add notes — to hand it to a deterministic check\n          (**review-deciding**) that squashes when every box is ticked, or sends\n          the still-unticked items back for another build+review round.\n      \"* **\":\n        to: checking\n        describe: >-\n          Change only code, leaving `.gtd/REVIEW.md` untouched, to re-run the\n          tests on your manual fix and re-review it (**checking**).\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n    # the point the previous review round ended, so the next `reviewing` turn\n    # (and the review checkout window) covers only the changes since then. On\n    # the first review there is no such commit, so the base is the cycle start.\n    reviewBase: true\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — if REVIEW.md still has any unticked \"- [ ]\" pointer,\n      # extract those pointers (with their notes) into REVIEW_FEEDBACK.md;\n      # either way, remove REVIEW.md. What the resulting diff MEANS (feedback\n      # round vs. full sign-off) is decided by this state's own `on` rules. The\n      # A/M REVIEW_FEEDBACK.md rows are declared BEFORE the D REVIEW.md row so a\n      # feedback round — which always also deletes REVIEW.md — is captured as\n      # feedback, not mistaken for a sign-off.\n      set +e\n      mkdir -p .gtd\n      if grep -qE '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %> 2>/dev/null; then\n        {\n          echo \"Feedback from review — address these before continuing:\"\n          echo\n          grep -E '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' <%~ it.vars.reviewFile %>\n        } > <%~ it.vars.reviewFeedbackFile %>\n      fi\n      rm -f <%~ it.vars.reviewFile %>\n    on:\n      \"A .gtd/REVIEW_FEEDBACK.md\": feedback-building\n      \"M .gtd/REVIEW_FEEDBACK.md\": feedback-building\n      \"D .gtd/REVIEW.md\": squashing\n      \"C\": await-review\n\n  feedback-building:\n    actor: agent\n    file: <%= it.vars.reviewFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent addressing review feedback. `.gtd/`\n      holds this workflow's own state — never create, edit, or delete anything\n      under `.gtd/` except `<%= it.vars.reviewFeedbackFile %>`, which this\n      prompt tells you to address and then delete.\n\n      The review feedback to address is: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n      Implement exactly those changes — no Q&A, no re-planning. Use TDD\n      discipline. Delete `<%= it.vars.reviewFeedbackFile %>` once every item is\n      addressed. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  squashing:\n    actor: agent\n    file: <%= it.vars.commitMsgFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. The cycle is approved and done.\n      `.gtd/` holds this workflow's own state — never create, edit, or delete\n      anything under `.gtd/` except `<%= it.vars.commitMsgFile %>`, which this\n      prompt tells you to write.\n\n      Write `<%= it.vars.commitMsgFile %>` with ONE conventional-commits message\n      for the entire cycle (subject line `type(scope): subject`, imperative\n      mood, <= 72 characters; a body explaining the why, trade-offs, and key\n      decisions). Plain text, no markdown wrapper.\n\n      Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n      entering this file squashes the whole cycle into one commit using its\n      content as the message.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Full cycle diff\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"A .gtd/COMMIT_MSG.md\": done\n      \"M .gtd/COMMIT_MSG.md\": done\n\n  done:\n    commit: |\n      <%~ it.read(it.vars.commitMsgFile) %>\n\n      Token cost: <%= it.processCost %>\n      <% it.processCostByModel.forEach(function(m){ %>\n      - <%= m.model %>: <%= m.cost %>\n      <% }) %>\n";
+var unified_default = "# The unified gtd workflow template — written verbatim into `.gtdrc.json`\n# (nested under a `workflow:` key) by `gtd init` (no argument). gtd ships no\n# default workflow: a repo picks this bundled template with `gtd init`, and a\n# state command run with no workflow configured fails (see src/Config.ts).\n# See STATES.md §10 for the full walkthrough.\n#\n# Compiled through the exact same `compileWorkflowConfig` a user's `.gtdrc`\n# `workflow:` key goes through — no privileged code path\n# (src/workflows/templates.ts does the compiling). Every content string below\n# is INLINE (no `./`-relative file references): the bundled template ships\n# inside a single-file build (`dist/gtd.bundle.mjs`), so its content must\n# already be resolved at BUILD time. `gtd init` DERIVES the scaffolded\n# `.gtdrc.json` from this inline source (`renderInitScaffold`): each agent\n# state's `prompt:` is written out as an editable `gtd-prompts/<state>.md`\n# file; human `message:`/check `script:`/the `done` `commit:` body stay inline.\n#\n# ── Three entry points, one shared tail ────────────────────────────────────\n#\n# The initial `idle` state FORKS on which steering file the human creates:\n#\n#   * .gtd/REQUIREMENTS.md -> the ADVANCED flow (product + technical Q&A,\n#     package decomposition, per-package parallel build + agentic spec-review).\n#   * anything else (e.g. .gtd/TODO.md) -> the SIMPLE flow (one grilling Q&A\n#     loop, a monolithic build, no decomposition, no agentic review).\n#\n# A third entry, `gtd review <commitish>`, jumps straight to `reviewing`\n# (reviewEntry) to review a foreign branch through the same shared tail.\n#\n# All three converge at `reviewing` -> `await-review`. From there:\n#   * full sign-off (tick every box, or delete REVIEW.md) -> squashing -> done\n#     (the ONLY path to the finale — the whole cycle collapses into one commit).\n#   * partial sign-off / notes -> review-deciding extracts the unticked items\n#     into REVIEW_FEEDBACK.md -> feedback-building implements them -> checking\n#     -> reviewing regenerates an INCREMENTAL REVIEW.md (review-deciding carries\n#     `reviewBase: true`, so each feedback round's review + checkout window\n#     covers only `last-review..HEAD`) -> await-review, looping until sign-off.\n#   * a code-only human edit (REVIEW.md untouched) -> checking -> reviewing.\n#\n# The shared health segment (`checking`/`fixing`/`escalate`) serves the simple\n# build, the feedback loop, and code-only edits — its green edge targets\n# `reviewing`. The advanced per-package loop keeps its OWN health triple\n# (`adv-checking`/`adv-fixing`/`adv-escalate`) because its green edge targets\n# the per-package `spec-review` gate instead.\n#\n# KNOWN LIMITATION: `on` pattern keys are NOT Eta templates — they keep the\n# LITERAL `.gtd/...` paths matching these vars' DEFAULT values. Repointing a\n# file var changes what templates read/write WITHOUT changing what the `on`\n# patterns match, desyncing the machine (see docs/configuration.md).\n\nvars:\n  testCommand: npm test\n  todoFile: .gtd/TODO.md\n  requirementsFile: .gtd/REQUIREMENTS.md\n  architectureFile: .gtd/ARCHITECTURE.md\n  packagesDir: .gtd/packages\n  nextFile: .gtd/NEXT.md\n  reviewFile: .gtd/REVIEW.md\n  reviewFeedbackFile: .gtd/REVIEW_FEEDBACK.md\n  feedbackFile: .gtd/FEEDBACK.md\n  specFeedbackFile: .gtd/SPEC_FEEDBACK.md\n  commitMsgFile: .gtd/COMMIT_MSG.md\n  # The two opaque model tiers every agent state draws from — repoint them here\n  # (or via a top-level `.gtdrc` `vars:` key / a `GTD_VAR_plannerModel` env var)\n  # to change every state on that tier at once. `plannerModel` (default \"smart\")\n  # is the heavier tier for the one-shot planning/architecting/review turns;\n  # `coderModel` (default \"base\") is the tier for the build/fix turns.\n  plannerModel: smart\n  coderModel: base\n\nstates:\n  # ── Shared entry ────────────────────────────────────────────────────────\n  idle:\n    actor: human\n    initial: true\n    # Every human-gate `message:` below closes with the same rendered \"What\n    # each change does next\" list, built from `it.edges` (the resting state's\n    # own `on` edges — each edge's `describe:` is the single source of truth).\n    message: |\n      No active gtd cycle.\n\n      To start one, create a steering file describing what you want built:\n\n      - `.gtd/TODO.md` — a short sketch — starts the SIMPLE flow (plan, build,\n        review).\n      - `.gtd/REQUIREMENTS.md` — the product requirements — starts the ADVANCED\n        flow (product + technical Q&A, package decomposition, parallel build,\n        per-package agentic review).\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* .gtd/REQUIREMENTS.md\":\n        to: adv-grilling\n        describe: >-\n          Save the product requirements to `.gtd/REQUIREMENTS.md` to start the\n          ADVANCED flow — the agent develops them through product then technical\n          Q&A, decomposes the work into packages, and builds each in parallel\n          (**adv-grilling**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Save a short sketch to `.gtd/TODO.md` (or any other change) to start\n          the SIMPLE flow — the agent reads it, explores the codebase, and\n          develops it into a concrete implementation plan (**grilling**).\n\n  # ── Simple flow: one Q&A loop, monolithic build ───────────────────────────\n  grilling:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.todoFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.todoFile %>` holds a short sketch of what to build (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete implementation plan.\n\n      For every question you cannot settle yourself, add it under a\n      `## Open Questions` heading near the top, one `### <question>`\n      sub-heading each, its body your suggested answer in plain prose (always\n      suggest one — the human accepts it by leaving it untouched, or overrides\n      it by editing it). Omit the section entirely once there are none.\n\n      If `<%= it.vars.todoFile %>` already carries a `## Open Questions`\n      section from a previous lap, the human has now responded to that whole\n      batch: fold every one of those questions into the plan — the human's edit\n      where they gave one, your own suggestion where they left it untouched (an\n      untouched suggestion IS acceptance) — and MOVE each resolved\n      `### <question>` block down into a `## Answered Questions` section at the\n      bottom. Raise any genuinely new questions under `## Open Questions`.\n\n      Leave `<%= it.vars.todoFile %>` uncommitted and finish your turn — do\n      not commit, and do not run `gtd step agent` yourself; the harness does\n      that.\n    on:\n      \"* **\": grilling-answer\n\n  grilling-answer:\n    actor: human\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.todoFile %>` holds the plan under development, with any\n      open questions under `## Open Questions` — each carrying a suggested\n      answer. Answer a question by editing its body in place; leave a\n      suggestion untouched to accept it.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: building\n        describe: >-\n          Change nothing to accept every suggested answer as-is and move on to\n          implementation (**building**).\n      \"* **\":\n        to: grilling\n        describe: >-\n          Edit the plan — answer a question, add detail, or raise a new one — to\n          send it back for another round of grilling (**grilling**).\n\n  building:\n    actor: agent\n    file: <%= it.vars.todoFile %>\n    mode: qa\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create or edit anything under `.gtd/` except deleting\n      `<%= it.vars.todoFile %>`, which this prompt tells you to delete once its\n      work is complete.\n\n      The plan to implement is: <%~ it.read(it.vars.todoFile) %>\n\n      Read that plan and implement it in full. Use TDD discipline: one test,\n      then the implementation that passes it, then the next — never write all\n      the tests first.\n\n      Delete `<%= it.vars.todoFile %>` once the work it describes is complete\n      and verified. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  # ── Advanced flow: product + technical Q&A ────────────────────────────────\n  adv-grilling:\n    actor: agent\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.requirementsFile %>`, which this prompt tells you to develop.\n\n      `<%= it.vars.requirementsFile %>` holds the product requirements (or\n      feedback from a prior review lap). Read it, explore the codebase, and\n      develop it into a concrete, PRODUCT-level plan in this one turn.\n\n      Scope: product and user-facing decisions only. Leave implementation\n      details (file/module structure, data models, tech-stack choices) for the\n      next phase (`<%= it.vars.architectureFile %>`).\n\n      For every remaining open question, add it under a `## Open Questions`\n      heading near the top, one `### <question>` sub-heading each, its body your\n      suggested answer in plain prose (always suggest one). Omit the section\n      once there are none. On a return lap, fold the whole answered batch into\n      the plan and move each resolved `### <question>` block down into a\n      `## Answered Questions` section at the bottom.\n\n      Leave `<%= it.vars.requirementsFile %>` uncommitted and finish your turn.\n    on:\n      \"* **\": adv-grilling-answer\n\n  adv-grilling-answer:\n    actor: human\n    file: <%= it.vars.requirementsFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.requirementsFile %>` holds the product plan under\n      development, with any open questions under `## Open Questions` — each\n      carrying a suggested answer. Answer a question by editing its body in\n      place; leave a suggestion untouched to accept it.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: architecting\n        describe: >-\n          Change nothing to accept the product plan and move on to technical\n          architecting (**architecting**).\n      \"* **\":\n        to: adv-grilling\n        describe: >-\n          Edit the product plan — answer a question, add detail, or raise a new\n          one — to send it back for another round (**adv-grilling**).\n\n  architecting:\n    actor: agent\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    model: <%= it.vars.plannerModel %>\n    memory: plan\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.architectureFile %>` and `<%= it.vars.requirementsFile %>`,\n      which this prompt tells you to write and delete respectively.\n\n      Read `<%= it.vars.requirementsFile %>` (the converged product plan) and\n      develop `<%= it.vars.architectureFile %>` from it in this one turn:\n      file/module structure, data models, library/tech-stack choices,\n      error-handling strategy — the *how*, building on the *what* already\n      settled. Do not re-open product-level decisions; treat them as settled.\n\n      For every remaining open question, add it under a `## Open Questions`\n      heading exactly as the grilling phase does (one `### <question>` each, its\n      body your suggested answer). Omit the section once there are none. On a\n      return lap, fold the whole answered batch in and move each resolved block\n      down into a `## Answered Questions` section at the bottom.\n\n      Once `<%= it.vars.architectureFile %>` is written, delete\n      `<%= it.vars.requirementsFile %>` — its content has been folded in and it\n      must not linger. Leave everything uncommitted and finish your turn.\n    on:\n      \"* **\": architecting-answer\n\n  architecting-answer:\n    actor: human\n    file: <%= it.vars.architectureFile %>\n    mode: qa\n    message: |\n      `<%= it.vars.architectureFile %>` holds the technical plan under\n      development, with any open questions under `## Open Questions`. Answer a\n      question by editing its body in place; leave a suggestion untouched to\n      accept it.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"C\":\n        to: decompose\n        describe: >-\n          Change nothing to accept the technical plan and move on to decomposing\n          the work into packages (**decompose**).\n      \"* **\":\n        to: architecting\n        describe: >-\n          Edit the technical plan to send it back for another round\n          (**architecting**).\n\n  # ── Advanced flow: decomposition + per-package parallel build loop ─────────\n  decompose:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except the\n      package files this prompt tells you to write (under\n      `<%= it.vars.packagesDir %>/`), and `<%= it.vars.architectureFile %>`,\n      which it tells you to delete.\n\n      Read `<%= it.vars.architectureFile %>` (the converged technical plan) and\n      decompose it into an ordered set of WORK PACKAGES, one file each under\n      `<%= it.vars.packagesDir %>/` (e.g. `<%= it.vars.packagesDir %>/01-name.md`,\n      `<%= it.vars.packagesDir %>/02-name.md`, ...). Order the packages so the\n      test suite can pass again after each one lands.\n\n      Each package file describes a set of INDEPENDENT tasks that can be\n      implemented concurrently without ordering constraints between them — a\n      single build turn will fan them out to parallel subagents. Give each task\n      a clear description, acceptance criteria as `- [ ]` checkboxes, and the\n      relevant paths. Also state the package's overall requirement so it can be\n      reviewed against its spec. Do NOT put ordering-dependent tasks in the same\n      package — split them across ordered packages instead.\n\n      No package file may reference any other `.gtd/` file. Once the package\n      files are written, delete `<%= it.vars.architectureFile %>`. Leave\n      everything uncommitted and finish your turn.\n    on:\n      \"* .gtd/packages/**\": picking\n\n  picking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package queue arbiter) — the loop driver executes\n      # this verbatim, then steps the check actor. Mechanics only: take the\n      # first package file (by name) under the packages dir into NEXT.md, or\n      # remove NEXT.md when the queue is empty. What NEXT.md's presence/absence\n      # MEANS (another package to build vs. the queue closing out to review) is\n      # decided by this state's own `on` rules at capture time — never here.\n      set +e\n      # Hoist the NEXT path once, at the TOP: Eta's autoTrim eats the newline\n      # after an interpolation tag, so no tag may be the last token on a line —\n      # it would glue the next line's `else`/`fi` onto it and break the script.\n      # Below this point everything is plain bash.\n      nextFile=\"<%~ it.vars.nextFile %>\"\n      next=$(ls <%~ it.vars.packagesDir %>/*.md 2>/dev/null | head -n 1)\n      if [ -n \"$next\" ]; then\n        printf '%s' \"$next\" > \"$nextFile\"\n      else\n        rm -f \"$nextFile\"\n      fi\n    on:\n      \"D .gtd/NEXT.md\": reviewing\n      \"* .gtd/NEXT.md\": adv-building\n      \"C\": reviewing\n\n  adv-building:\n    actor: agent\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/`; in\n      particular do NOT delete the package file (the `spec-review` gate reads it\n      after you) and never touch `<%= it.vars.nextFile %>` — the `picking` state\n      owns it.\n\n      The package to implement is: <%~ it.read(it.vars.nextFile) %>\n\n      That file describes a set of INDEPENDENT tasks. Implement ALL of them in\n      this one turn, fanning the independent tasks out to parallel subagents\n      where your harness supports it — each task is self-contained and can be\n      built concurrently. Implement EXACTLY the tasks this package describes — no\n      more, no less; leave every other package file untouched. Use TDD\n      discipline within each task.\n\n      Leave the package file in place and everything else uncommitted, then\n      finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  adv-checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": adv-fixing\n      \"M .gtd/FEEDBACK.md\": adv-fixing\n      \"D .gtd/FEEDBACK.md\": spec-review\n      \"C\": spec-review\n\n  adv-fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    retry:\n      max: 3\n      otherwise: adv-escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": adv-checking\n\n  adv-escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: adv-checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or\n          `.gtd/FEEDBACK.md` — to re-run the check (**adv-checking**).\n\n  spec-review:\n    actor: agent\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    # Bounded per cycle: once entered `max` times, a transition into it is\n    # redirected to `closing` (force-close the package and move on — the\n    # unresolved concern is deferred to the shared human review at the tail,\n    # which sees the whole diff anyway). NOTE the cap is PROCESS-scoped, so it\n    # pools across packages — the same documented limitation the shared\n    # `fixing` cap has (see STATES.md / docs/configuration.md).\n    retry:\n      max: 3\n      otherwise: closing\n    prompt: |\n      You are an autonomous coding agent reviewing a freshly-built work package\n      against its own spec. `.gtd/` holds this workflow's own state — never\n      create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.specFeedbackFile %>`, which this prompt tells you to write\n      when — and only when — you find problems.\n\n      The package spec is: <%~ it.read(it.vars.nextFile) %>\n\n      Read that spec, then verify the package's implementation (the diff below)\n      against it: are all its tasks done, acceptance criteria met, and the code\n      sound and consistent with the codebase?\n\n      - If it fully satisfies the spec, write NOTHING and finish your turn — a\n        clean turn is your approval.\n      - If it does not, write `<%= it.vars.specFeedbackFile %>` listing the\n        concrete problems for a fix turn to address. Be specific.\n\n      Do not fix anything yourself and do not delete the package file — a later\n      step owns that. Finish your turn.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Diff under review\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"A .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"M .gtd/SPEC_FEEDBACK.md\": spec-fix\n      \"D .gtd/SPEC_FEEDBACK.md\": closing\n      \"C\": closing\n\n  spec-fix:\n    actor: agent\n    file: <%= it.vars.specFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.specFeedbackFile %>`, which this prompt tells you to address\n      and then delete.\n\n      Read `<%= it.vars.specFeedbackFile %>` (the reviewer's concerns about the\n      current package) and the package spec (`<%= it.read(it.vars.nextFile) %>`),\n      then fix the code to resolve every concern. Keep the change focused.\n\n      Delete `<%= it.vars.specFeedbackFile %>` once every concern is addressed.\n      Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": adv-checking\n\n  closing:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn (the package closer) — remove the just-reviewed package\n      # file (its path is in NEXT.md) plus any leftover spec feedback, so\n      # `picking` selects the NEXT package (or falls through to review when the\n      # queue is empty). Reached on approval (spec-review clean) and on the\n      # spec-review retry cap (force-close, deferring the concern to the tail).\n      set +e\n      pkg=$(cat <%~ it.vars.nextFile %> 2>/dev/null)\n      [ -n \"$pkg\" ] && rm -f \"$pkg\"\n      rm -f <%~ it.vars.specFeedbackFile %> <%~ it.vars.nextFile %>\n    on:\n      \"* **\": picking\n\n  # ── Shared health segment (simple build, feedback loop, code-only edits) ──\n  checking:\n    actor: check\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — run the suite; a red run records .gtd/FEEDBACK.md, a\n      # green run cleans it up. The `on` rules decide what that means.\n      set +e\n      mkdir -p .gtd\n      # Hoist the feedback path once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on\n      # a line — it would glue the next line's `else`/`fi` onto it and break\n      # the script. Below this point everything is plain bash.\n      feedback=\"<%~ it.vars.feedbackFile %>\"\n      <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1\n      code=$?\n      if [ \"$code\" -ne 0 ]; then\n        if [ -s .gtd/.check-output ]; then\n          mv .gtd/.check-output \"$feedback\"\n        else\n          rm -f .gtd/.check-output\n          printf 'the test command failed with exit code %s and produced no output.' \"$code\" > \"$feedback\"\n        fi\n      else\n        rm -f .gtd/.check-output\n        rm -f \"$feedback\"\n      fi\n    on:\n      \"A .gtd/FEEDBACK.md\": fixing\n      \"M .gtd/FEEDBACK.md\": fixing\n      \"D .gtd/FEEDBACK.md\": reviewing\n      \"C\": reviewing\n\n  fixing:\n    actor: agent\n    file: <%= it.vars.feedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: fix\n    retry:\n      max: 3\n      otherwise: escalate\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.\n\n      Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix the\n      code so the suite passes. Keep the change focused — do not refactor\n      unrelated code. If the feedback is wrong, empty or delete\n      `<%= it.vars.feedbackFile %>` instead of \"fixing\" a non-issue.\n\n      Leave everything uncommitted and finish your turn — do not commit.\n    on:\n      \"* **\": checking\n\n  escalate:\n    actor: human\n    file: <%= it.vars.feedbackFile %>\n    message: |\n      The agent could not get the check to pass after repeated attempts.\n      `<%= it.vars.feedbackFile %>` holds the last failing output.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"* **\":\n        to: checking\n        describe: >-\n          Fix the failure yourself — edit the code and/or `.gtd/FEEDBACK.md` —\n          to re-run the check (**checking**).\n\n  # ── Shared tail: agent review -> human review -> squash finale ────────────\n  reviewing:\n    actor: agent\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    model: <%= it.vars.plannerModel %>\n    memory: review\n    # `gtd review <commitish>` (a plain non-gtd branch, e.g. a colleague's PR)\n    # enters here directly, recording the resolved base as a `Gtd-Review-Base:`\n    # trailer on its empty entry commit — everything below then reuses the same\n    # reviewing/await-review/feedback machinery over <commitish>..HEAD.\n    reviewEntry: true\n    prompt: |\n      You are an autonomous coding agent. `.gtd/` holds this workflow's own\n      state — never create, edit, or delete anything under `.gtd/` except\n      `<%= it.vars.reviewFile %>`, which this prompt tells you to write.\n\n      Write `<%= it.vars.reviewFile %>` to help a human review the diff below in\n      this EXACT format:\n\n      - First non-blank line: `# Review: <%= it.currentCommit.slice(0, 7) %>`\n      - Somewhere in the document: `<!-- base: <%= it.startCommit %> -->`\n      - At least one `## <Chunk Title>` heading, grouping hunks semantically\n        (same feature/refactor/fix, even across files) — a short explanation of\n        what changed and why, then one `- [ ] ./path/to/file.ts#42 — note` file\n        pointer per hunk (checkboxes are for the human to tick, not you; every\n        path is `./`-relative, with an optional `#line` and an optional\n        ` — note`).\n\n      The diff below is `it.reviewDiff` — on a feedback round it covers ONLY the\n      changes made since the previous review, so you review just what changed,\n      not items already signed off. Leave `<%= it.vars.reviewFile %>`\n      uncommitted and finish your turn.\n      <% if (it.reviewDiff.trim()) { %>\n\n      ## Full diff under review\n\n      ```diff\n      <%~ it.reviewDiff %>\n      ```\n      <% } %>\n    on:\n      \"* **\": await-review\n\n  await-review:\n    actor: human\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # While the cycle rests here, gtd opens a \"review checkout window\": raw HEAD\n    # is rewound to the review base (the most-recent `review-deciding` commit —\n    # so a feedback round shows only `last-review..HEAD` — or the process start\n    # on the first review) with the working tree untouched, surfacing the diff\n    # as ordinary uncommitted changes. It closes on the next invocation.\n    reviewWindow: true\n    message: |\n      `<%= it.vars.reviewFile %>` holds the review record for the cycle — one\n      `- [ ]` checkbox per reviewable item, grouped into chunks.\n\n      What each change does next (then run `gtd step human`):\n      <% it.edges.forEach(function (e) { if (e.describe) { %>\n      <%~ \"- \" + e.describe + \"\\n\" %>\n      <% } }) %>\n    on:\n      \"D .gtd/REVIEW.md\":\n        to: squashing\n        describe: >-\n          Delete `.gtd/REVIEW.md` outright to sign off on the whole cycle at\n          once and collapse it into one commit (**squashing**).\n      \"M .gtd/REVIEW.md\":\n        to: review-deciding\n        describe: >-\n          Edit `.gtd/REVIEW.md` — tick a `- [ ]` box to `- [x]` to sign off that\n          item, or add notes — to hand it to a deterministic check\n          (**review-deciding**) that squashes when every box is ticked, or sends\n          the still-unticked items back for another build+review round.\n      \"* **\":\n        to: checking\n        describe: >-\n          Change only code, leaving `.gtd/REVIEW.md` untouched, to re-run the\n          tests on your manual fix and re-review it (**checking**).\n\n  review-deciding:\n    actor: check\n    file: <%= it.vars.reviewFile %>\n    mode: review\n    # Anchors the INCREMENTAL review base: its most-recent in-process commit is\n    # the point the previous review round ended, so the next `reviewing` turn\n    # (and the review checkout window) covers only the changes since then. On\n    # the first review there is no such commit, so the base is the cycle start.\n    reviewBase: true\n    script: |\n      #!/usr/bin/env bash\n      # gtd check turn — if REVIEW.md still has any unticked \"- [ ]\" pointer,\n      # extract those pointers (with their notes) into REVIEW_FEEDBACK.md;\n      # either way, remove REVIEW.md. What the resulting diff MEANS (feedback\n      # round vs. full sign-off) is decided by this state's own `on` rules. The\n      # A/M REVIEW_FEEDBACK.md rows are declared BEFORE the D REVIEW.md row so a\n      # feedback round — which always also deletes REVIEW.md — is captured as\n      # feedback, not mistaken for a sign-off.\n      set +e\n      mkdir -p .gtd\n      # Hoist the review paths once, at the TOP: Eta's autoTrim eats the\n      # newline after an interpolation tag, so no tag may be the last token on a\n      # line — it would glue the next line onto it and break the script. Below\n      # this point everything is plain bash.\n      reviewFile=\"<%~ it.vars.reviewFile %>\"\n      reviewFeedbackFile=\"<%~ it.vars.reviewFeedbackFile %>\"\n      if grep -qE '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' \"$reviewFile\" 2>/dev/null; then\n        {\n          echo \"Feedback from review — address these before continuing:\"\n          echo\n          grep -E '^[[:space:]]*-[[:space:]]*\\[[[:space:]]*\\]' \"$reviewFile\"\n        } > \"$reviewFeedbackFile\"\n      fi\n      rm -f \"$reviewFile\"\n    on:\n      \"A .gtd/REVIEW_FEEDBACK.md\": feedback-building\n      \"M .gtd/REVIEW_FEEDBACK.md\": feedback-building\n      \"D .gtd/REVIEW.md\": squashing\n      \"C\": await-review\n\n  feedback-building:\n    actor: agent\n    file: <%= it.vars.reviewFeedbackFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent addressing review feedback. `.gtd/`\n      holds this workflow's own state — never create, edit, or delete anything\n      under `.gtd/` except `<%= it.vars.reviewFeedbackFile %>`, which this\n      prompt tells you to address and then delete.\n\n      The review feedback to address is: <%~ it.read(it.vars.reviewFeedbackFile) %>\n\n      Implement exactly those changes — no Q&A, no re-planning. Use TDD\n      discipline. Delete `<%= it.vars.reviewFeedbackFile %>` once every item is\n      addressed. Leave everything else uncommitted and finish your turn.\n    on:\n      \"* **\": checking\n\n  squashing:\n    actor: agent\n    file: <%= it.vars.commitMsgFile %>\n    model: <%= it.vars.coderModel %>\n    memory: build\n    prompt: |\n      You are an autonomous coding agent. The cycle is approved and done.\n      `.gtd/` holds this workflow's own state — never create, edit, or delete\n      anything under `.gtd/` except `<%= it.vars.commitMsgFile %>`, which this\n      prompt tells you to write.\n\n      Write `<%= it.vars.commitMsgFile %>` with ONE conventional-commits message\n      for the entire cycle (subject line `type(scope): subject`, imperative\n      mood, <= 72 characters; a body explaining the why, trade-offs, and key\n      decisions). Plain text, no markdown wrapper.\n\n      Leave `<%= it.vars.commitMsgFile %>` uncommitted and finish your turn —\n      entering this file squashes the whole cycle into one commit using its\n      content as the message.\n      <% if (it.processDiff.trim()) { %>\n\n      ## Full cycle diff\n\n      ```diff\n      <%~ it.processDiff %>\n      ```\n      <% } %>\n    on:\n      \"A .gtd/COMMIT_MSG.md\": done\n      \"M .gtd/COMMIT_MSG.md\": done\n\n  done:\n    commit: |\n      <%~ it.read(it.vars.commitMsgFile) %>\n\n      Token cost: <%= it.processCost %>\n      <% it.processCostByModel.forEach(function(m){ %>\n      - <%= m.model %>: <%= m.cost %>\n      <% }) %>\n";
 //#endregion
 //#region src/workflows/templates.ts
 /**
@@ -204404,7 +204490,7 @@ const runInitCommand = (argv, json, write) => gen(function* () {
 	if (args.length > 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd init: too many arguments — init takes no argument, got: ${args.join(", ")}`));
 	const git = yield* GitService;
 	const fs = yield* FileSystem;
-	yield* assertRunningFromRepoRoot(git, fs);
+	const inRepo = yield* assertInitLocation(git, fs);
 	const { root } = yield* Cwd;
 	if (yield* configPresentAt(root)) return yield* fail$2(/* @__PURE__ */ new Error("gtd init: a gtd config already exists — remove it before re-initializing"));
 	const toError = (e) => e instanceof Error ? e : new Error(String(e));
@@ -204418,11 +204504,12 @@ const runInitCommand = (argv, json, write) => gen(function* () {
 	if (json) write(JSON.stringify({
 		written: ".gtdrc.json",
 		workflow: "unified",
-		prompts: scaffold.prompts.map((p) => p.path)
+		prompts: scaffold.prompts.map((p) => p.path),
+		inRepo
 	}) + "\n");
 	else {
 		const promptCount = scaffold.prompts.length;
-		write(`Wrote .gtdrc.json with the bundled unified workflow, and its ${promptCount} agent prompt${promptCount === 1 ? "" : "s"} as editable Markdown under ${PROMPTS_DIR}/ (referenced from the config).\n\nReview and commit them before starting: an uncommitted .gtdrc.json (or prompt\nfile) counts as a pending change, so the initial state would capture it on the\nfirst step. Once committed, run \`gtd step human\` to begin.\n`);
+		write(`Wrote .gtdrc.json with the bundled unified workflow, and its ${promptCount} agent prompt${promptCount === 1 ? "" : "s"} as editable Markdown under ${PROMPTS_DIR}/ (referenced from the config).\n\n` + (inRepo ? "Review and commit them before starting: an uncommitted .gtdrc.json (or prompt\nfile) counts as a pending change, so the initial state would capture it on the\nfirst step. Once committed, run `gtd step human` to begin.\n" : "This directory is not a git repository, so there is nothing to commit here. The\nconfig applies to any gtd repository nested below it — gtd discovers it by\nwalking up from the repository root. Run `gtd step human` from such a repo to\nbegin.\n"));
 	}
 });
 /**
@@ -204812,6 +204899,24 @@ const assertRunningFromRepoRoot = (git, fs) => gen(function* () {
 	const topLevel = yield* git.topLevel();
 	if ((yield* fs.realPath(topLevel)) !== (yield* fs.realPath(process.cwd()))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd must be run from the repository root (${topLevel}); the current directory is ${process.cwd()}`));
 });
+/**
+* `gtd init` writes only a `.gtdrc.json` (+ prompt files) — it derives no state,
+* so unlike the state commands it need not sit in a git repository at all. It
+* may run EITHER at a repository root OR in a directory outside any repository —
+* the latter scaffolds a shared config a nested repo picks up by walking up the
+* cwd→home chain (see the parent-dir layout in docs/configuration.md). The one
+* placement it must refuse is a repository SUBDIRECTORY: gtd runs from the repo
+* root and discovers config by walking UP, so a config written below the root
+* would silently never be found. Returns whether cwd is inside a repository (at
+* its root), so the caller can tailor the "commit before starting" guidance —
+* there is nothing to commit outside a repo.
+*/
+const assertInitLocation = (git, fs) => gen(function* () {
+	const topLevel = yield* either(git.topLevel());
+	if (topLevel._tag === "Left") return false;
+	if ((yield* fs.realPath(topLevel.right)) !== (yield* fs.realPath(process.cwd()))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd init must be run from the repository root (${topLevel.right}) or from a directory outside any git repository; the current directory is a repository subdirectory: ${process.cwd()}`));
+	return true;
+});
 /** Dispatches to the named `run*Command` handler for every known subcommand. */
 const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 	switch (sub) {

package/docs/configuration.md

@@ -92,11 +92,23 @@ engine, and [§3](../STATES.md#3-pattern-grammar) for the pattern grammar.
 ### Content values: inline or a file reference
 
 A `script`/`prompt`/`message`/`commit` value starting with `./` or `../` is a
-**file reference** — resolved relative to the config file's own directory and
-read at load time. A missing or unreadable file reference is a **load error**,
-collected and thrown with every other config problem — never silently treated as
-inline text. Any other string (including one that merely contains a `/`, or an
-absolute path) is inline Eta template source, used verbatim.
+**file reference** — resolved relative to **the directory of the `.gtdrc` that
+declared it** (not the directory `gtd` runs from) and read at load time. A
+missing or unreadable file reference is a **load error**, collected and thrown
+with every other config problem — never silently treated as inline text. Any
+other string (including one that merely contains a `/`, or an absolute path) is
+inline Eta template source, used verbatim.
+
+Because references anchor to the declaring file, a `.gtdrc` and its
+`gtd-prompts/` (or `prompts/`) directory can live **outside** the repo — e.g. in
+a parent directory shared across several repos. gtd still runs from the repo
+root, discovers the parent `.gtdrc` by walking up the directory chain (see
+["Lookup and precedence"](#lookup-and-precedence) — cwd→home), and inlines each
+level's `./`-relative references against that level's own directory. When
+workflows are layered across levels, every reference resolves against the file
+that wrote it, so a parent's `./gtd-prompts/x.md` and a child's never collide.
+You can scaffold such a shared config by running [`gtd init`](#gtd-init) from
+that parent directory — it need not be a git repository.
 
 ```yaml
 workflow:
@@ -677,6 +689,16 @@ load time, so a prompt is editable Markdown and editing it changes the workflow
 with no config edit. Human `message:` blocks and check `script:` bodies stay
 inline in the config (they are workflow mechanics, not prompts).
 
+`gtd init` writes only config — it derives no git state — so it need not run in
+a git repository. It runs at a **repository root** or in a directory **outside
+any repository** (scaffolding a shared config a nested repo picks up by walking
+up — see the parent-dir note under
+[file references](#content-values-inline-or-a-file-reference)); its guidance
+adjusts to say there is nothing to commit when it is not in a repo. It refuses
+only to write into a repository **subdirectory**, where the upward config walk
+would never find the file. Either way, it will not overwrite an existing config
+at that directory (remove it first to re-scaffold).
+
 It also seeds a top-level [`modes:`](#modes--pluggable-steering-file-modes)
 block as a ready-to-edit suggestion — a Prettier `format:` for each built-in
 steering-file mode the template uses:

package/package.json

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