@pmelab/gtd 15.10.0 → 16.0.0

package/README.md

@@ -26,7 +26,10 @@ for the settings most projects tune.
 Also install all three skill sources the bundled workflow names in its prompts —
 none is optional. See
 [Setup](https://github.com/pmelab/gtd/blob/main/docs/setup.md) for the list, the
-install flags, and the never-install-the-plugin caveat.
+install flags, and the never-install-the-plugin caveat. Each bundled agent step
+has its own addressable `.gtdrc` `skills:` entry — see
+[Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#the-skills-key)
+to repoint one to a set your own harness has instead.
 
 > **A repository's `gtd.config.ts` is code, and gtd runs it.** A custom workflow
 > is a TypeScript module, and every gtd command that looks at workflow state —

package/dist/gtd.bundle.mjs

@@ -30966,6 +30966,8 @@ const changesSince = (hash, pattern) => {
 const head = () => ctx().head();
 /** The process's diff base: the commit before it began, or the base `gtd --entry` fixed. */
 const start = () => ctx().start();
+/** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. See `FlowContext.skillsFor` for `ownSkills`. */
+const skillsFor = (localName, ownSkills) => ctx().skillsFor(localName, ownSkills);
 /** The merged workflow variables. */
 const vars = new Proxy({}, {
 	get: (_target, key) => typeof key === "string" ? ctx().vars[key] : void 0,
@@ -31185,6 +31187,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	scope: () => scope,
 	sectionBodies: () => sectionBodies,
 	sections: () => sections,
+	skillsFor: () => skillsFor,
 	start: () => start,
 	threads: () => threads,
 	vars: () => vars,
@@ -47773,7 +47776,11 @@ const replay = async (input) => {
 		truncated: judgeCuts.get(request) ?? []
 	} : void 0;
 	const judgeCuts = /* @__PURE__ */ new WeakMap();
-	const resolve = (request) => {
+	const resolveSkills = (name, ownSkills) => {
+		const resolved = input.configuredSkills?.[name] ?? ownSkills ?? input.skills?.[name];
+		return resolved !== void 0 && resolved.length === 0 ? void 0 : resolved;
+	};
+	const resolve = (request, name) => {
 		if (request.kind === "agent") {
 			const persona = {};
 			for (const s of scopes) {
@@ -47784,7 +47791,8 @@ const replay = async (input) => {
 				...request,
 				options: {
 					...persona,
-					...request.options
+					...request.options,
+					skills: resolveSkills(name, request.options.skills)
 				}
 			};
 		}
@@ -47803,7 +47811,7 @@ const replay = async (input) => {
 		const name = scoped(request.name);
 		const occurrence = (occurrences.get(name) ?? 0) + 1;
 		occurrences.set(name, occurrence);
-		const resolved = resolve(request);
+		const resolved = resolve(request, name);
 		const reached = {
 			id: {
 				name,
@@ -47968,6 +47976,7 @@ const replay = async (input) => {
 		}),
 		vars: input.vars,
 		start: () => input.start,
+		skillsFor: (localName, ownSkills) => resolveSkills(scoped(localName), ownSkills) ?? [],
 		head: () => {
 			const rest = commits.slice(cursor);
 			return rest.length > 0 && rest.every((c) => c.parsed.step === void 0) ? rest[rest.length - 1].hash : position.hash;
@@ -48241,21 +48250,18 @@ const withSkills = (skills, prompt) => {
 	if (skills === void 0 || skills.trim() === "") return prompt;
 	return `${skillsPreamble.replaceAll("{skills}", skills)}\n\n${prompt}`;
 };
-/** `skills:` split on `,`, each name trimmed, empty entries dropped — `[]` for `undefined`, `""`, or blank. */
-const splitSkills = (raw) => (raw ?? "").split(",").map((name) => name.trim()).filter((name) => name.length > 0);
 /**
-* An `agent()` step declaring `skills`: the raw, comma-separated var feeds
-* both the `skills` option (the wire's `skills` key, split) and, re-joined
-* with `", "`, `withSkills`'s preamble — one declaration, so the two can
-* never drift apart.
+* An `agent()` step whose preamble names its resolved skills: `skillsFor`
+* resolves `name` (scoped from here, same as `agent()`'s own resolver) for
+* the preamble prose, passing `options.skills` through as `ownSkills` — the
+* same precedence tier `agent()`'s own wire resolver gives a call's own
+* `skills` option, so a step that declares one (`reviewQuality`'s per-turn
+* lens) gets it in the preamble too, not just on the wire, whenever no
+* bundled or configured entry outranks it. Both reads share one resolver
+* (`Replay.ts`'s `resolveSkills`), so the preamble and the wire can't drift
+* apart.
 */
-const agentWithSkills = (name, skills, prompt, options = {}) => {
-	const list = splitSkills(skills);
-	return agent(name, withSkills(list.join(", "), prompt), {
-		...options,
-		skills: list
-	});
-};
+const agentWithSkills = (name, prompt, options = {}) => agent(name, withSkills(skillsFor(name, options.skills).join(", "), prompt), options);
 const unwindFailure = (commit) => `gtd could not unwind ${commit} out of your working tree.`;
 const idleMessage = () => `No active gtd process.
 
@@ -48899,10 +48905,13 @@ every commit is machine-authored.
   high-level architectural changes — never which files changed; \`git
   diff --stat\` is for that, not this message
 - If the range removes or renames a documented config key, CLI flag, or
-  workflow state — a public surface, not an internal one — add a literal
-  \`BREAKING CHANGE:\` footer naming what disappears. A \`!\` on the type
-  prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's own
-  commit-analyzer has missed that marker before, cutting no release
+  workflow state, OR makes a previously-accepted config value now fail to
+  load (a stricter validation, an escape a value must now spell differently)
+  — a public surface, not an internal one, either way — add a literal
+  \`BREAKING CHANGE:\` footer naming what breaks and, for the second case,
+  the exact escape or rewrite a committed \`.gtdrc\` needs. A \`!\` on the
+  type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
+  own commit-analyzer has missed that marker before, cutting no release
   until a follow-up commit carried the literal footer instead
 
 The process's entry commit is \`${it.entryCommit}\`. ${human}Inspect the range: \`git log ${it.processBase}..${it.processTip}\`
@@ -48926,21 +48935,21 @@ const SPEC_FEEDBACK = ".gtd/SPEC_FEEDBACK.md";
 const planner = () => vars.plannerModel ?? "";
 const coder = () => vars.coderModel ?? "";
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
-const triage$1 = (base) => agentWithSkills("triage", vars.triageSkills, designTriagePrompt(base), {
+const triage$1 = (base) => agentWithSkills("triage", designTriagePrompt(base), {
 	label: "Triaging the change",
 	file: REQUIREMENTS,
 	mode: "qa",
 	model: planner(),
 	system: designSystem()
 });
-const author = () => agentWithSkills("author", vars.architectureSkills, architectureAuthorPrompt(), {
+const author = () => agentWithSkills("author", architectureAuthorPrompt(), {
 	label: "Refining the technical plan",
 	file: ARCHITECTURE,
 	mode: "qa",
 	model: planner(),
 	system: architectSystem()
 });
-const decompose = () => agentWithSkills("decompose", vars.decomposeSkills, architectureDecomposePrompt(), {
+const decompose = () => agentWithSkills("decompose", architectureDecomposePrompt(), {
 	label: "Decomposing into packages",
 	model: planner(),
 	system: architectSystem()
@@ -48959,37 +48968,37 @@ const answerTechnicalQuestions = () => human("gate.answer", {
 	mode: "qa",
 	acceptClean: true
 });
-const build = (pkg) => agentWithSkills("building", vars.buildSkills, packagesItemBuildingPrompt(pkg), {
+const build = (pkg) => agentWithSkills("building", packagesItemBuildingPrompt(pkg), {
 	label: "Building",
 	model: coder(),
 	system: builderSystem()
 });
-const fixSuite = () => agentWithSkills("fix-suite", vars.fixSkills, packagesItemFixSuitePrompt(), {
+const fixSuite = () => agentWithSkills("fix-suite", packagesItemFixSuitePrompt(), {
 	label: "Fixing the check",
 	file: FEEDBACK,
 	model: coder(),
 	system: builderSystem()
 });
-const fixSpec = (pkg) => agentWithSkills("fix-spec", vars.reviewFixSkills, packagesItemFixSpecPrompt(pkg), {
+const fixSpec = (pkg) => agentWithSkills("fix-spec", packagesItemFixSpecPrompt(pkg), {
 	label: "Fixing review feedback",
 	file: SPEC_FEEDBACK,
 	model: coder(),
 	system: builderSystem()
 });
 /** Review `pkg` against its spec, focused on the `failing` sections the pre-judge could not clear. */
-const reviewPackage = (pkg, failing = []) => agentWithSkills("spec.review", vars.specReviewSkills, packagesItemSpecReviewPrompt(pkg, failing), {
+const reviewPackage = (pkg, failing = []) => agentWithSkills("spec.review", packagesItemSpecReviewPrompt(pkg, failing), {
 	label: "Reviewing the package",
 	model: planner(),
 	system: specReviewerSystem(),
 	allowEmpty: true
 });
-const fix = () => agentWithSkills("fix", vars.fixSkills, buildFixPrompt(), {
+const fix = () => agentWithSkills("fix", buildFixPrompt(), {
 	label: "Fixing the check",
 	file: FEEDBACK,
 	model: coder(),
 	system: finisherSystem()
 });
-const describeEscalation = () => agentWithSkills("health.describe", vars.escalateSkills, healthDescribePrompt(), {
+const describeEscalation = () => agentWithSkills("health.describe", healthDescribePrompt(), {
 	label: "Describing the escalation",
 	file: FEEDBACK,
 	model: coder(),
@@ -49008,15 +49017,21 @@ const escalationExhausted = () => human("health.exhausted", {
 	file: ESCALATION,
 	acceptClean: true
 });
-/** One quality review, through the skill `lens`. */
-const reviewQuality = (lens) => agentWithSkills("quality.reviewing", lens, buildQualityReviewingPrompt(lens), {
+/**
+* One quality review, through the skill `lens`. `lens` rides as this turn's
+* own `skills` option — a `.gtdrc` `build.quality.reviewing` entry still
+* overrides it (config beats a flow-supplied list same as any other step),
+* but absent one the lens itself is what the turn loads by default.
+*/
+const reviewQuality = (lens) => agentWithSkills("quality.reviewing", buildQualityReviewingPrompt(lens), {
 	label: "Reviewing (one quality lens)",
 	file: QUALITY,
 	model: planner(),
 	system: reviewerSystem(),
-	allowEmpty: true
+	allowEmpty: true,
+	skills: [lens]
 });
-const fixQuality = () => agentWithSkills("fix-quality", vars.reviewFixSkills, buildFixQualityPrompt(), {
+const fixQuality = () => agentWithSkills("fix-quality", buildFixQualityPrompt(), {
 	label: "Fixing quality findings",
 	file: QUALITY,
 	model: coder(),
@@ -49024,7 +49039,7 @@ const fixQuality = () => agentWithSkills("fix-quality", vars.reviewFixSkills, bu
 	allowEmpty: true
 });
 /** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given. */
-const reviewing = (base, carry) => agentWithSkills("review.reviewing", vars.reviewSkills, buildReviewReviewingPrompt(base, carry), {
+const reviewing = (base, carry) => agentWithSkills("review.reviewing", buildReviewReviewingPrompt(base, carry), {
 	label: "Reviewing",
 	file: REVIEW,
 	mode: "review",
@@ -49033,7 +49048,7 @@ const reviewing = (base, carry) => agentWithSkills("review.reviewing", vars.revi
 	base
 });
 /** Answer every `question` note inline in `.gtd/REVIEW.md`. */
-const answerReviewQuestions = (notes) => agentWithSkills("review.answer-review-questions", vars.reviewSkills, buildReviewAnswerQuestionsPrompt(notes), {
+const answerReviewQuestions = (notes) => agentWithSkills("review.answer-review-questions", buildReviewAnswerQuestionsPrompt(notes), {
 	label: "Answering your questions",
 	file: REVIEW,
 	mode: "review",
@@ -49044,7 +49059,7 @@ const answerReviewQuestions = (notes) => agentWithSkills("review.answer-review-q
 * Fix every `nit` note in one turn. Its name puts it in the `build.review`
 * conversation, which has one identity — so it runs as the reviewer, not the coder.
 */
-const fixNits = (notes) => agentWithSkills("review.fix-nits", vars.reviewFixSkills, buildReviewFixNitsPrompt(notes), {
+const fixNits = (notes) => agentWithSkills("review.fix-nits", buildReviewFixNitsPrompt(notes), {
 	label: "Fixing your nits",
 	file: REVIEW,
 	model: planner(),
@@ -49063,7 +49078,7 @@ const reviewMissing = (round) => human("review.review-missing", {
 	label: "Nothing to review"
 });
 /** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
-const collecting = (capture) => agentWithSkills("review.collecting", vars.reviewSkills, buildReviewCollectingPrompt(capture), {
+const collecting = (capture) => agentWithSkills("review.collecting", buildReviewCollectingPrompt(capture), {
 	label: "Collecting your feedback",
 	file: REQUIREMENTS,
 	mode: "qa",
@@ -49528,8 +49543,8 @@ const architecturePass = async () => {
 };
 //#endregion
 //#region src/workflows/review.ts
-/** The skills the quality lap reviews with, one turn each: the `qualityReviews` var. */
-const qualityLenses = () => splitSkills(vars.qualityReviews);
+/** The lenses the quality lap reviews with, one turn each: the `qualityReviews` var, split on `,` and trimmed. Unlike a `skills:` entry, this fans out into one whole turn per entry rather than naming one step's skill list — see `build.quality.reviewing` in `./skills.ts` for the (separate) skills a lens turn itself loads. */
+const qualityLenses = () => (vars.qualityReviews ?? "").split(",").map((lens) => lens.trim()).filter((lens) => lens.length > 0);
 /**
 * One review turn per lens over the whole change, each appending what it
 * finds blocking to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
@@ -49761,18 +49776,33 @@ const defaults = {
 	specPreJudge: "0.9",
 	reviewNoteActionable: "0.7",
 	architectureSkipMinP: "0.85",
-	triageSkills: "spec-driven-development, planning-and-task-breakdown",
-	architectureSkills: "api-and-interface-design, documentation-and-adrs, ponytail",
-	decomposeSkills: "incremental-implementation, planning-and-task-breakdown",
-	buildSkills: "test-driven-development, incremental-implementation",
-	fixSkills: "debugging-and-error-recovery",
-	reviewFixSkills: "incremental-implementation, code-simplification",
-	reviewSkills: "code-review-and-quality",
-	specReviewSkills: "code-review-and-quality, spec-driven-development",
-	escalateSkills: "debugging-and-error-recovery",
 	qualityReviews: "owasp-security, ponytail-review, test-audit"
 };
 //#endregion
+//#region src/workflows/skills.ts
+const skills = {
+	"design.triage": ["spec-driven-development", "planning-and-task-breakdown"],
+	"architecture.author": [
+		"api-and-interface-design",
+		"documentation-and-adrs",
+		"ponytail"
+	],
+	"architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
+	"packages.item.building": ["test-driven-development", "incremental-implementation"],
+	"packages.item.fix-suite": ["debugging-and-error-recovery"],
+	"packages.item.fix-spec": ["incremental-implementation", "code-simplification"],
+	"packages.item.spec.review": ["code-review-and-quality", "spec-driven-development"],
+	"packages.item.health.describe": ["debugging-and-error-recovery"],
+	"build.fix": ["debugging-and-error-recovery"],
+	"build.health.describe": ["debugging-and-error-recovery"],
+	"build.quality.reviewing": [],
+	"build.fix-quality": ["incremental-implementation", "code-simplification"],
+	"build.review.reviewing": ["code-review-and-quality"],
+	"build.review.answer-review-questions": ["code-review-and-quality"],
+	"build.review.fix-nits": ["incremental-implementation", "code-simplification"],
+	"build.review.collecting": ["code-review-and-quality"]
+};
+//#endregion
 //#region src/workflows/unified.ts
 var unified_exports = /* @__PURE__ */ __exportAll({
 	ARCHITECTURE: () => ARCHITECTURE,
@@ -49827,6 +49857,7 @@ var unified_exports = /* @__PURE__ */ __exportAll({
 	reviewPackage: () => reviewPackage,
 	reviewQuality: () => reviewQuality,
 	reviewing: () => reviewing,
+	skills: () => skills,
 	specReview: () => specReview,
 	steering: () => steering,
 	summary: () => summary,
@@ -50643,6 +50674,15 @@ const modesJsonSchema = {
 		}
 	}
 };
+/** The `skills:` shape: full step name -> its skill list (`compileSkillsMap`). An entry REPLACES the step's bundled list wholesale, never adds to it — and the schema can validate an entry's VALUE but never its KEY, since step names come from the workflow in play, not a fixed set. */
+const skillsJsonSchema = {
+	type: "object",
+	description: "Flat step full-name -> skill-name array map. Each entry REPLACES the named step's bundled skill list wholesale (never merges into it); [] means no skills at all for that step, and no preamble. A key naming a step the workflow in play does not declare is a load error listing the known names — the schema itself cannot validate a key, only a value's shape.",
+	additionalProperties: {
+		type: "array",
+		items: { type: "string" }
+	}
+};
 /**
 * A real (not `Unknown`) schema, unlike `vars`/`modes`: it is a flat settings
 * struct with no per-mode map to compile, so its JSON Schema derives from the
@@ -50663,7 +50703,8 @@ const UiSchema = Struct({
 const ConfigSchema = Struct({
 	vars: optional$1(Unknown.annotations({ jsonSchema: varsJsonSchema })),
 	modes: optional$1(Unknown.annotations({ jsonSchema: modesJsonSchema })),
-	ui: optional$1(UiSchema)
+	ui: optional$1(UiSchema),
+	skills: optional$1(Unknown.annotations({ jsonSchema: skillsJsonSchema }))
 });
 //#endregion
 //#region src/SteeringFormats.ts
@@ -50736,7 +50777,7 @@ const dedupeDiagnostics = (diagnostics) => {
 };
 //#endregion
 //#region src/workflow/compile.ts
-const isPlainObject$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isPlainObject$3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const describeType = (v) => {
 	if (v === null) return "null";
 	if (Array.isArray(v)) return "array";
@@ -50756,7 +50797,7 @@ const compileVarsMap = (raw) => {
 		vars: {},
 		diagnostics
 	};
-	if (!isPlainObject$2(raw)) {
+	if (!isPlainObject$3(raw)) {
 		diagnostics.push(err(["vars"], `"vars" must be a mapping of name -> scalar value, got ${describeType(raw)}`));
 		return {
 			vars: {},
@@ -50776,10 +50817,75 @@ const compileVarsMap = (raw) => {
 		diagnostics
 	};
 };
+const isStringArray$1 = (v) => Array.isArray(v) && v.every((entry) => typeof entry === "string");
+/** A flat `step full name -> skill list` map; a malformed value is a load error and is dropped. */
+const compileSkillsMap = (raw) => {
+	const diagnostics = [];
+	if (raw === void 0) return {
+		skills: {},
+		diagnostics
+	};
+	if (!isPlainObject$3(raw)) {
+		diagnostics.push(err(["skills"], `"skills" must be a mapping of step name -> array of skill names, got ${describeType(raw)}`));
+		return {
+			skills: {},
+			diagnostics
+		};
+	}
+	const skills = Object.create(null);
+	for (const [key, value] of Object.entries(raw)) {
+		if (!isStringArray$1(value)) {
+			diagnostics.push(err(["skills", key], `"skills.${key}" must be an array of skill names (strings), got ${describeType(value)}`));
+			continue;
+		}
+		skills[key] = value;
+	}
+	return {
+		skills,
+		diagnostics
+	};
+};
+/**
+* The nine `*Skills` workflow vars this package deletes, each naming the
+* `.gtdrc` `skills:` step key(s) that replace it — four of the nine fan out to
+* several keys, because a var once shared between steps now addresses
+* them independently. Deliberately the only place gtd special-cases a var
+* name by string; meant to be deleted a major release after this ships.
+*/
+const DEAD_SKILLS_VARS = {
+	triageSkills: ["design.triage"],
+	architectureSkills: ["architecture.author"],
+	decomposeSkills: ["architecture.decompose"],
+	buildSkills: ["packages.item.building"],
+	fixSkills: ["packages.item.fix-suite", "build.fix"],
+	reviewFixSkills: [
+		"packages.item.fix-spec",
+		"build.fix-quality",
+		"build.review.fix-nits"
+	],
+	reviewSkills: [
+		"build.review.reviewing",
+		"build.review.answer-review-questions",
+		"build.review.collecting"
+	],
+	specReviewSkills: ["packages.item.spec.review"],
+	escalateSkills: ["packages.item.health.describe", "build.health.describe"]
+};
+/** `vars:` entries naming one of the nine deleted `*Skills` vars — scoped to `.gtdrc` `vars:` only; there is no environment scan anywhere in this check, so a `GTD_BUILDSKILLS` gets neither this diagnostic nor any other. */
+const deadSkillsVarDiagnostics = (rawVars) => {
+	if (!isPlainObject$3(rawVars)) return [];
+	const diagnostics = [];
+	for (const key of Object.keys(rawVars)) {
+		const replacement = DEAD_SKILLS_VARS[key];
+		if (replacement === void 0) continue;
+		diagnostics.push(err(["vars", key], `"vars.${key}" was removed — skills are now configured per step, under the "skills:" key, addressed by: ${replacement.join(", ")}`));
+	}
+	return diagnostics;
+};
 const MODE_COMMAND_KEYS = ["format", "validate"];
 /** One `modes:` entry; malformed entries are load errors and are dropped. */
 const compileMode = (name, entry, diagnostics) => {
-	if (!isPlainObject$2(entry)) {
+	if (!isPlainObject$3(entry)) {
 		diagnostics.push(err(["modes", name], `mode "${name}": must be an object with "format" and/or "validate", got ${describeType(entry)}`));
 		return;
 	}
@@ -50809,7 +50915,7 @@ const compileModesMap = (raw) => {
 		modes: {},
 		diagnostics
 	};
-	if (!isPlainObject$2(raw)) {
+	if (!isPlainObject$3(raw)) {
 		diagnostics.push(err(["modes"], `"modes" must be a mapping of mode name -> { format, validate }, got ${describeType(raw)}`));
 		return {
 			modes: {},
@@ -50838,7 +50944,7 @@ const mergeModes = (base, override) => {
 };
 /** Stamp a whole (possibly deeply nested) value with ONE origin, recursively — used when `inner` replaces `base` wholesale: every key inside still needs its own node, or a LATER layer partially overriding just one nested key would silently lose the rest of this subtree's origin. */
 const uniformOrigin = (value, origin) => {
-	if (!isPlainObject$2(value)) return { self: origin };
+	if (!isPlainObject$3(value)) return { self: origin };
 	const children = {};
 	for (const [key, v] of Object.entries(value)) children[key] = uniformOrigin(v, origin);
 	return {
@@ -50856,7 +50962,7 @@ const uniformOrigin = (value, origin) => {
 * findings, not one origin for the whole merged key.
 */
 const mergeWithOrigin = (base, baseOrigin, inner, innerOrigin) => {
-	if (!isPlainObject$2(base) || !isPlainObject$2(inner)) return {
+	if (!isPlainObject$3(base) || !isPlainObject$3(inner)) return {
 		value: inner,
 		origin: uniformOrigin(inner, innerOrigin)
 	};
@@ -50907,7 +51013,7 @@ const compileConfig = (layers) => {
 	let merged = {};
 	let originTree = { self: BUILT_IN_ORIGIN };
 	for (const layer of layers) {
-		const value = isPlainObject$2(layer.value) ? layer.value : {};
+		const value = isPlainObject$3(layer.value) ? layer.value : {};
 		const step = mergeWithOrigin(merged, originTree, value, layer.origin);
 		merged = step.value;
 		originTree = step.origin;
@@ -50917,17 +51023,91 @@ const compileConfig = (layers) => {
 	const ui = mergedConfig["ui"];
 	const { vars: rcVars, diagnostics: varsDiagnostics } = compileVarsMap(mergedConfig["vars"]);
 	diagnostics.push(...withOrigin(varsDiagnostics, lookupIn));
+	diagnostics.push(...withOrigin(deadSkillsVarDiagnostics(mergedConfig["vars"]), lookupIn));
 	const { modes: rcModes, diagnostics: modesDiagnostics } = compileModesMap(mergedConfig["modes"]);
 	diagnostics.push(...withOrigin(modesDiagnostics, lookupIn));
+	const skillsKeys = [];
+	for (const layer of layers) {
+		if (!isPlainObject$3(layer.value)) continue;
+		const own = compileSkillsMap(layer.value["skills"]);
+		diagnostics.push(...own.diagnostics.map((d) => ({
+			...d,
+			origin: layer.origin
+		})));
+		skillsKeys.push(...Object.keys(own.skills).map((key) => ({
+			key,
+			origin: layer.origin
+		})));
+	}
+	const { skills: rcSkills } = compileSkillsMap(mergedConfig["skills"]);
 	const seeded = Object.fromEntries(BUILT_IN_MODE_NAMES.map((name) => [name, { validate: seededValidateCommand(name) }]));
 	return {
 		rcVars,
 		modes: mergeModes(seeded, rcModes),
 		...ui !== void 0 ? { ui } : {},
+		rcSkills,
+		skillsKeys,
 		diagnostics: dedupeDiagnostics(sortDiagnostics(diagnostics, layerOrder))
 	};
 };
 //#endregion
+//#region src/workflow/interpolate.ts
+const VAR_PATTERN = /\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+const isPlainObject$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+* `modes.*.format`, `modes.*.validate` and `ui.format` — gtd hands these
+* straight to bash, where `$` already means the shell's own expansion. The
+* predicate reads only the config PATH shape, never the value: sniffing for
+* `$GTD_FILE` would exempt whichever command happens not to name it, and
+* silently interpolate one that names something else instead.
+*/
+const isBashExemptPath = (path) => {
+	if (path.length === 3 && path[0] === "modes" && (path[2] === "format" || path[2] === "validate")) return true;
+	if (path.length === 2 && path[0] === "ui" && path[1] === "format") return true;
+	return false;
+};
+const interpolateString = (value, path, env, diagnostics) => value.replace(VAR_PATTERN, (match, braced, bare) => {
+	if (match === "$$") return "$";
+	const name = braced ?? bare;
+	if (name === void 0) return match;
+	const resolved = env[name];
+	if (resolved !== void 0) return resolved;
+	diagnostics.push({
+		severity: "error",
+		path,
+		message: `"${match}" references environment variable "${name}", which is not set`,
+		origin: ""
+	});
+	return match;
+});
+const walk = (value, path, env, diagnostics) => {
+	if (typeof value === "string") return isBashExemptPath(path) ? value : interpolateString(value, path, env, diagnostics);
+	if (Array.isArray(value)) return value.map((v, i) => walk(v, [...path, i], env, diagnostics));
+	if (isPlainObject$2(value)) {
+		const out = {};
+		for (const [key, v] of Object.entries(value)) out[key] = walk(v, [...path, key], env, diagnostics);
+		return out;
+	}
+	return value;
+};
+/**
+* Expand `$NAME`/`${NAME}` from `env` over every string leaf of a decoded
+* `.gtdrc` layer, except the three paths gtd hands to bash. `$$` yields a
+* literal `$`; any other `$` not followed by a valid name (a trailing `$`,
+* `$1`, `$-`, `$ `) is left untouched. Exactly one pass: `String.replace`
+* never rescans a replacement's own text, so an environment variable's value
+* can never be read back as config syntax. An unset name is a load-error
+* `Diagnostic` naming the config path; the original `$NAME` text is left in
+* place rather than blanked.
+*/
+const interpolate = (config, env) => {
+	const diagnostics = [];
+	return {
+		value: walk(config, [], env, diagnostics),
+		diagnostics
+	};
+};
+//#endregion
 //#region src/workflow/vars.ts
 const PREFIX = "GTD_";
 /**
@@ -57718,7 +57898,7 @@ const dropOptionalUndefinedArtifacts = (all) => {
 * findings surface together through `load`'s single sorted/deduped report,
 * the same as every other producer in this package.
 */
-const decodeLevel = (level) => gen(function* () {
+const decodeLevel = (level, env) => gen(function* () {
 	if (!isPlainObject$1(level.config)) return {
 		layer: void 0,
 		diagnostics: [{
@@ -57739,13 +57919,17 @@ const decodeLevel = (level) => gen(function* () {
 			origin: level.filepath
 		}))
 	};
+	const interpolated = interpolate(result.right, env);
 	return {
 		layer: {
 			origin: level.filepath,
 			dir: dirname(level.filepath),
-			value: result.right
+			value: interpolated.value
 		},
-		diagnostics: []
+		diagnostics: interpolated.diagnostics.map((d) => ({
+			...d,
+			origin: level.filepath
+		}))
 	};
 });
 /**
@@ -57769,7 +57953,7 @@ const load = gen(function* () {
 	const discovery = yield* ConfigDiscovery;
 	const levels = yield* discovery.levels(host.root, host.home);
 	for (const level of levels) yield* narrator.narrate(`config: layer ${level.filepath}`);
-	const decoded = yield* forEach$2(levels, decodeLevel);
+	const decoded = yield* forEach$2(levels, (level) => decodeLevel(level, host.env));
 	const layers = decoded.flatMap((d) => d.layer !== void 0 ? [d.layer] : []);
 	const decodeDiagnostics = decoded.flatMap((d) => d.diagnostics);
 	const compiled = compileConfig(layers);
@@ -57779,7 +57963,18 @@ const load = gen(function* () {
 		catch: (e) => new GtdError(`gtd config:\n  - ${module?.filepath ?? "(built-in default)"}: ${e instanceof Error ? e.message : String(e)}`)
 	});
 	const layerOrder = [...levels.map((level) => level.filepath), ...module ? [module.filepath] : []];
-	const diagnostics = dedupeDiagnostics(sortDiagnostics([...decodeDiagnostics, ...compiled.diagnostics], layerOrder));
+	const knownSkillNames = Object.keys(loaded.skills).sort();
+	const unknownSkillDiagnostics = compiled.skillsKeys.filter(({ key }) => !Object.hasOwn(loaded.skills, key)).map(({ key, origin }) => ({
+		severity: "error",
+		path: ["skills", key],
+		message: `"skills.${key}" names a step this workflow does not declare — known step names: ${knownSkillNames.join(", ")}`,
+		origin
+	}));
+	const diagnostics = dedupeDiagnostics(sortDiagnostics([
+		...decodeDiagnostics,
+		...compiled.diagnostics,
+		...unknownSkillDiagnostics
+	], layerOrder));
 	const fatal = diagnostics.filter((d) => d.severity === "error");
 	if (fatal.length > 0) {
 		const lines = fatal.map(formatDiagnostic);
@@ -57793,6 +57988,8 @@ const load = gen(function* () {
 			base: loaded.base,
 			steering: loaded.steering,
 			modes: compiled.modes,
+			skills: loaded.skills,
+			configuredSkills: compiled.rcSkills,
 			initial
 		},
 		workflowVars: { ...loaded.defaults },
@@ -57839,6 +58036,13 @@ const stringRecord = (exports, name) => {
 	if (typeof value !== "object" || value === null || Object.values(value).some((entry) => typeof entry !== "string")) throw new Error(`the "${name}" export is not a record of strings`);
 	return value;
 };
+const isStringArray = (v) => Array.isArray(v) && v.every((entry) => typeof entry === "string");
+/** Read a module's optional `skills` export: full step name -> skill list, mirroring `stringRecord` for the vars-shaped exports. */
+const skillsRecord = (exports) => {
+	const value = exports["skills"] ?? {};
+	if (typeof value !== "object" || value === null || Object.values(value).some((entry) => !isStringArray(entry))) throw new Error(`the "skills" export is not a record of skill-name arrays`);
+	return value;
+};
 const optionalFunction = (exports, name) => {
 	const value = exports[name];
 	if (value === void 0) return void 0;
@@ -57857,6 +58061,7 @@ const fromModule = (exported, origin, dependencyFiles) => {
 		flow,
 		defaults: stringRecord(exports, "defaults"),
 		steering: stringRecord(exports, "steering"),
+		skills: skillsRecord(exports),
 		summary: optionalFunction(exports, "summary"),
 		base: optionalFunction(exports, "base"),
 		origin,
@@ -63775,6 +63980,8 @@ const replayFor = (setup, pending) => replay({
 	start: setup.run.diffBase,
 	startTree: setup.run.diffBase === EMPTY_TREE$1 ? treeFromRecord({}) : commitTree(setup.workspace, setup.run.diffBase),
 	budgetBytes: setup.budget,
+	skills: setup.def.skills,
+	configuredSkills: setup.def.configuredSkills,
 	...pending !== void 0 ? { pending } : {}
 });
 const replayError = (outcome) => {
@@ -63996,7 +64203,9 @@ const entryRefusal = (rest, name, entryVars) => gen(function* () {
 		},
 		vars,
 		start: "",
-		budgetBytes: rest.setup.budget
+		budgetBytes: rest.setup.budget,
+		skills: rest.def.skills,
+		configuredSkills: rest.def.configuredSkills
 	}));
 	if (outcome.kind === "refused") return outcome.message;
 	if (outcome.kind === "rest") return outcome.entryRead ? void 0 : `"${name}" is not an enterable state — this workflow reads no entry`;

package/package.json

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