tracerkit 1.15.0 → 1.17.0

package/README.md

@@ -9,7 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/tracerkit)](https://www.npmjs.com/package/tracerkit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Replace ad-hoc AI prompts with a repeatable spec-driven workflow: from idea to verified, archived spec.
+Replace ad-hoc AI prompts with a repeatable spec-driven workflow: from idea to verified spec.
 
 Named after the tracer-bullet technique from _The Pragmatic Programmer_: **Tracer** + **Kit**.
 
@@ -19,9 +19,9 @@ Named after the tracer-bullet technique from _The Pragmatic Programmer_: **Trace
 
 ## Why TracerKit?
 
-AI assistants work best with small, well-scoped tasks, not sprawling layers or flat task lists. TracerKit structures every feature as **tracer-bullet vertical slices**: each phase cuts through every layer (schema → service → API → UI → tests) and is demoable on its own. Integration problems surface early, not at the end.
+AI assistants work best with small, well-scoped tasks — not sprawling layers or flat task lists. TracerKit structures every feature as **tracer-bullet vertical slices**: each phase cuts through every layer (schema → service → API → UI → tests) and is demoable on its own. Integration problems surface early, not at the end.
 
-The workflow is three skills: **define** (`/tk:prd`), **plan** (`/tk:plan`), **verify** (`/tk:check`). Skills are pure Markdown with zero runtime deps. The AI reads your specs directly, counts progress, and archives completed work. No build step, no CLI at runtime.
+Three skills drive the workflow: **define** (`/tk:prd`), **plan** (`/tk:plan`), **verify** (`/tk:check`). The AI reads your specs directly, counts progress, and marks completed work done. Pure Markdown, zero runtime deps.
 
 ## Get Started
 
@@ -75,10 +75,10 @@ You: # open the plan, implement each phase, write tests...
 
 You: /tk:check dark-mode-support
 AI:  Status: done | Total: 5/5
-     Archived to .tracerkit/archives/dark-mode-support/
+     Marked complete in .tracerkit/prds/dark-mode-support.md
 ```
 
-Use `/tk:brief` at the start of any session to see active features and pick up where you left off:
+Between sessions, `/tk:brief` shows active features and picks up where you left off:
 
 ```
 You: /tk:brief
@@ -101,7 +101,7 @@ tracerkit config storage github         # set current project to use GitHub
 tracerkit config github.repo org/repo   # set target repo
 ```
 
-PRDs and plans become GitHub Issues with `tk:prd` and `tk:plan` labels. On `/tk:check` pass, issues are closed instead of archived locally. Each project can use a different backend; local is the default. See [Configuration](docs/configuration.md) for details.
+PRDs and plans become GitHub Issues with `tk:prd` and `tk:plan` labels. On `/tk:check` pass, issues are closed with `completed` reason and any related PRs are linked automatically. Each project can use a different backend; local is the default. See [Configuration](docs/configuration.md) for details.
 
 To migrate existing artifacts between backends:
 
@@ -109,39 +109,18 @@ To migrate existing artifacts between backends:
 tracerkit migrate-storage           # local→github or github→local (auto-detected)
 ```
 
-Direction is inferred from the current `storage` config. All artifacts are migrated, existing duplicates are skipped, and the config is flipped to the target backend. Source artifacts are left intact as backup. For archived features migrating to GitHub, merged PRs matching the slug are linked automatically.
+Direction is inferred from the current `storage` config. All artifacts are migrated, existing duplicates are skipped, and the config is flipped to the target backend. Source artifacts are left intact as backup.
 
 </details>
 
 ## Skills
 
-TracerKit ships skills that take a feature from idea to verified archive.
-
-### `/tk:prd <idea>`: Write a PRD
-
-Interactive interview that explores your codebase, asks scoping questions one at a time, designs deep modules, and writes a structured PRD.
-
-**Output:** `.tracerkit/prds/<slug>.md` (local) or GitHub Issue with `tk:prd` label
-
-### `/tk:plan <slug>`: Create an implementation plan
-
-Reads a PRD and breaks it into phased **tracer-bullet vertical slices**. Each phase is a thin but complete path through every layer (schema, service, API, UI, tests), demoable on its own.
-
-**Output:** `.tracerkit/plans/<slug>.md` (local) or GitHub Issue with `tk:plan` label
-
-### `/tk:brief`: Session briefing
-
-Shows active features, their progress, and suggested focus. Use at the start of a session to orient.
-
-**Output:** Feature dashboard in the terminal. No files written.
-
-### `/tk:check [slug]`: Verify and archive
-
-Verifies the codebase against the plan's done-when checkboxes. Runs tests, validates user stories, updates phase progress, and transitions the PRD status. On `done`, archives the PRD and plan to `.tracerkit/archives/<slug>/` automatically.
-
-Without arguments, shows a feature dashboard with status and progress before asking which feature to check.
-
-**Output:** Verdict block appended to the plan. On `done`: archives to `.tracerkit/archives/<slug>/` (local) or closes both issues (GitHub).
+| Skill              | What it does                                           | Output                                                                                          |
+| ------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `/tk:prd <idea>`   | Interview → codebase scan → structured PRD             | `.tracerkit/prds/<slug>.md` or GitHub Issue                                                     |
+| `/tk:plan <slug>`  | PRD → phased vertical slices, each demoable on its own | `.tracerkit/plans/<slug>.md` or GitHub Issue                                                    |
+| `/tk:brief`        | Feature dashboard with progress and suggested focus    | Terminal only, no files                                                                         |
+| `/tk:check [slug]` | Verify done-when checkboxes against codebase and tests | Verdict block in plan. On `done`: status updated (local) or issues closed + PRs linked (GitHub) |
 
 ## Docs
 

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as e, f as t, i as n, l as r, n as i, o as a, p as o, r as s, s as c, t as l, u } from "./uninstall-k_ZGY-Mk.js";
+import { a as e, f as t, i as n, l as r, n as i, o as a, p as o, r as s, s as c, t as l, u } from "./uninstall-Ba_zfPOx.js";
 import { existsSync as d, readFileSync as f, statSync as p } from "node:fs";
 import { dirname as m, join as h, resolve as g } from "node:path";
 import { fileURLToPath as _ } from "node:url";

package/dist/index.js

@@ -1,2 +1,2 @@
-import { c as e, i as t, n, o as r, r as i, t as a, u as o } from "./uninstall-k_ZGY-Mk.js";
+import { c as e, i as t, n, o as r, r as i, t as a, u as o } from "./uninstall-Ba_zfPOx.js";
 export { r as COMMANDS, e as DEPRECATED_SKILLS, o as SKILL_NAMES, i as init, n as migrateStorage, a as uninstall, t as update };

package/dist/{uninstall-k_ZGY-Mk.js → uninstall-Ba_zfPOx.js}

@@ -6,8 +6,7 @@ import { execSync as d } from "node:child_process";
 //#region src/config.ts
 var f = "local", p = "github", m = [f, p], h = {
 	prds: ".tracerkit/prds",
-	plans: ".tracerkit/plans",
-	archives: ".tracerkit/archives"
+	plans: ".tracerkit/plans"
 }, g = { labels: {
 	prd: "tk:prd",
 	plan: "tk:plan"
@@ -26,24 +25,23 @@ function _(t) {
 		throw Error("Invalid .tracerkit/config.json — expected valid JSON");
 	}
 	return {
-		storage: ee(i.storage),
-		paths: v(i.paths),
-		github: y(i.github)
+		storage: v(i.storage),
+		paths: y(i.paths),
+		github: b(i.github)
 	};
 }
-function ee(e) {
+function v(e) {
 	return typeof e == "string" && m.includes(e) ? e : f;
 }
-function v(e) {
-	let t = S(e) ? e : {};
+function y(e) {
+	let t = C(e) ? e : {};
 	return {
 		prds: typeof t.prds == "string" ? t.prds : h.prds,
-		plans: typeof t.plans == "string" ? t.plans : h.plans,
-		archives: typeof t.archives == "string" ? t.archives : h.archives
+		plans: typeof t.plans == "string" ? t.plans : h.plans
 	};
 }
-function y(e) {
-	let t = S(e) ? e : {}, n = S(t.labels) ? t.labels : {};
+function b(e) {
+	let t = C(e) ? e : {}, n = C(t.labels) ? t.labels : {};
 	return {
 		...typeof t.repo == "string" ? { repo: t.repo } : {},
 		labels: {
@@ -52,7 +50,7 @@ function y(e) {
 		}
 	};
 }
-function b(r, i) {
+function x(r, i) {
 	let o = c(r, ".tracerkit", "config.json");
 	t(s(o), { recursive: !0 });
 	let l = {};
@@ -61,31 +59,31 @@ function b(r, i) {
 	} catch {
 		l = {};
 	}
-	let u = x(l, i);
+	let u = S(l, i);
 	a(o, JSON.stringify(u, null, 2) + "\n");
 }
-function x(e, t) {
+function S(e, t) {
 	let n = { ...e };
-	for (let e of Object.keys(t)) S(n[e]) && S(t[e]) ? n[e] = x(n[e], t[e]) : n[e] = t[e];
+	for (let e of Object.keys(t)) C(n[e]) && C(t[e]) ? n[e] = S(n[e], t[e]) : n[e] = t[e];
 	return n;
 }
-function S(e) {
+function C(e) {
 	return typeof e == "object" && !!e && !Array.isArray(e);
 }
-var C = [
+var w = [
 	"tk:brief",
 	"tk:prd",
 	"tk:plan",
 	"tk:check"
-], w = ["tk:verify"], T = {
+], T = ["tk:verify"], E = {
 	force: "--force",
 	help: "--help",
 	version: "--version"
-}, E = [
+}, D = [
 	"brief",
 	"progress",
 	"archive"
-], D = [
+], O = [
 	{
 		name: "init",
 		args: "[path]",
@@ -111,44 +109,44 @@ var C = [
 		args: "[path]",
 		desc: "Migrate artifacts between local and GitHub storage backends"
 	}
-], O = c(s(u(import.meta.url)), "..", "skills");
-function k(e, t = "") {
+], k = c(s(u(import.meta.url)), "..", "skills");
+function A(e, t = "") {
 	let n = r(e, { withFileTypes: !0 }), i = [];
 	for (let r of n) {
 		let n = t ? `${t}/${r.name}` : r.name;
-		r.isDirectory() ? i.push(...k(c(e, r.name), n)) : i.push(n);
+		r.isDirectory() ? i.push(...A(c(e, r.name), n)) : i.push(n);
 	}
 	return i.sort();
 }
-function A(e) {
+function j(e) {
 	return `.claude/skills/tk:${e}`;
 }
-function j(e) {
+function M(e) {
 	return e.slice(18);
 }
-function M(e, t) {
+function N(e, t) {
 	let n = e;
-	return t.paths.prds !== h.prds && (n = n.replaceAll(h.prds, t.paths.prds)), t.paths.plans !== h.plans && (n = n.replaceAll(h.plans, t.paths.plans)), t.paths.archives !== h.archives && (n = n.replaceAll(h.archives, t.paths.archives)), t.github?.repo && (n = n.replaceAll("{{github.repo}}", t.github.repo)), t.github?.labels?.prd && (n = n.replaceAll("{{github.labels.prd}}", t.github.labels.prd)), t.github?.labels?.plan && (n = n.replaceAll("{{github.labels.plan}}", t.github.labels.plan)), n;
+	return t.paths.prds !== h.prds && (n = n.replaceAll(h.prds, t.paths.prds)), t.paths.plans !== h.plans && (n = n.replaceAll(h.plans, t.paths.plans)), t.github?.repo && (n = n.replaceAll("{{github.repo}}", t.github.repo)), t.github?.labels?.prd && (n = n.replaceAll("{{github.labels.prd}}", t.github.labels.prd)), t.github?.labels?.plan && (n = n.replaceAll("{{github.labels.plan}}", t.github.labels.plan)), n;
 }
-function N(e, r, i) {
-	let o = i ?? k(O).map(A);
+function P(e, r, i) {
+	let o = i ?? A(k).map(j);
 	for (let i of o) {
-		let o = c(O, j(i)), l = c(e, i);
-		t(s(l), { recursive: !0 }), a(l, M(n(o, "utf8"), r));
+		let o = c(k, M(i)), l = c(e, i);
+		t(s(l), { recursive: !0 }), a(l, N(n(o, "utf8"), r));
 	}
 	return { copied: o };
 }
-function P(e) {
+function F(e) {
 	return l("sha256").update(e).digest("hex");
 }
-function F(t, r) {
-	let i = k(O).map(A), a = [], o = [], s = [];
+function I(t, r) {
+	let i = A(k).map(j), a = [], o = [], s = [];
 	for (let l of i) {
 		let i = c(t, l);
 		if (!e(i)) s.push(l);
 		else {
-			let e = M(n(c(O, j(l)), "utf8"), r);
-			P(Buffer.from(e)) === P(n(i)) ? a.push(l) : o.push(l);
+			let e = N(n(c(k, M(l)), "utf8"), r);
+			F(Buffer.from(e)) === F(n(i)) ? a.push(l) : o.push(l);
 		}
 	}
 	return {
@@ -159,10 +157,10 @@ function F(t, r) {
 }
 //#endregion
 //#region src/commands/update.ts
-function I(t, n) {
-	if (!C.some((n) => e(c(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — run `tracerkit init` first");
-	let r = _(t), { unchanged: a, modified: o, missing: s } = F(t, r), l = [];
-	for (let n of w) {
+function L(t, n) {
+	if (!w.some((n) => e(c(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — run `tracerkit init` first");
+	let r = _(t), { unchanged: a, modified: o, missing: s } = I(t, r), l = [];
+	for (let n of T) {
 		let r = c(t, ".claude", "skills", n);
 		e(r) && (i(r, {
 			recursive: !0,
@@ -175,7 +173,7 @@ function I(t, n) {
 		...u ? o : []
 	];
 	if (d.length > 0) {
-		N(t, r, d);
+		P(t, r, d);
 		for (let e of a) l.push(`✓ ${e}`);
 		for (let e of s) l.push(`✓ ${e} (added)`);
 		if (u) for (let e of o) l.push(`✓ ${e} (replaced)`);
@@ -188,14 +186,14 @@ function I(t, n) {
 }
 //#endregion
 //#region src/commands/init.ts
-function te(t) {
-	if (C.some((n) => e(c(t, ".claude", "skills", n)))) return I(t, { force: !1 });
-	let { copied: n } = N(t, _(t));
+function ee(t) {
+	if (w.some((n) => e(c(t, ".claude", "skills", n)))) return L(t, { force: !1 });
+	let { copied: n } = P(t, _(t));
 	return n.map((e) => `✓ ${e}`);
 }
 //#endregion
 //#region src/commands/migrate-storage.ts
-var L = {
+var te = {
 	created: "tk:created",
 	in_progress: "tk:in-progress",
 	done: "tk:done"
@@ -227,7 +225,7 @@ function B(e) {
 	return t.length === 0 ? "<!-- tk:metadata\n-->" : `<!-- tk:metadata\n${t.map(([e, t]) => `${e}: ${t}`).join("\n")}\n-->`;
 }
 function V(e) {
-	return L[e] ?? "tk:created";
+	return te[e] ?? "tk:created";
 }
 function H(e) {
 	let t = e.match(/<!--\s*tk:metadata\n([\s\S]*?)-->\n*([\s\S]*)$/);
@@ -269,66 +267,44 @@ function K(t, i) {
 			type: "prd",
 			metadata: r,
 			body: i,
-			title: G(i),
-			archived: !1
+			title: G(i)
 		});
 	}
 	let l = c(t, i.paths.plans);
 	if (e(l)) for (let e of r(l)) {
 		if (!e.endsWith(".md")) continue;
-		let t = o(e, ".md"), r = n(c(l, e), "utf8");
+		let t = o(e, ".md"), r = n(c(l, e), "utf8"), { metadata: i, body: s } = z(r);
 		a.push({
 			slug: t,
 			type: "plan",
-			metadata: {},
-			body: r,
-			title: G(r),
-			archived: !1
+			metadata: i,
+			body: s,
+			title: G(s || r)
 		});
 	}
-	let u = c(t, i.paths.archives);
-	if (e(u)) for (let t of r(u, { withFileTypes: !0 })) {
-		if (!t.isDirectory()) continue;
-		let r = t.name, i = c(u, r, "prd.md"), o = c(u, r, "plan.md");
-		if (e(i)) {
-			let { metadata: e, body: t } = z(n(i, "utf8"));
-			a.push({
-				slug: r,
-				type: "prd",
-				metadata: {
-					...e,
-					status: "done"
-				},
-				body: t,
-				title: G(t),
-				archived: !0
-			});
-		}
-		if (e(o)) {
-			let e = n(o, "utf8");
-			a.push({
-				slug: r,
-				type: "plan",
-				metadata: { status: "done" },
-				body: e,
-				title: G(e),
-				archived: !0
-			});
-		}
-	}
 	return a;
 }
 function q(e) {
-	return d(`gh ${e.map((e) => `'${e.replace(/'/g, "'\\''")}'`).join(" ")}`, {
-		encoding: "utf8",
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		]
-	}).trim();
-}
-function J(e, t) {
+	let t = e;
+	if (t.code === "ENOENT") return /* @__PURE__ */ Error("gh CLI not found — install it: https://cli.github.com");
+	let n = (t.stderr ?? t.message ?? "").toLowerCase();
+	return n.includes("not logged in") || n.includes("authentication") ? /* @__PURE__ */ Error("Not authenticated with GitHub. Run: gh auth login") : n.includes("rate limit") || n.includes("403") ? /* @__PURE__ */ Error("GitHub rate limit exceeded. Wait and retry.") : n.includes("not found") || n.includes("404") ? /* @__PURE__ */ Error("Repository not found. Check github.repo in .tracerkit/config.json") : e instanceof Error ? e : Error(String(e));
+}
+function J(e) {
+	try {
+		return d(`gh ${e.map((e) => `'${e.replace(/'/g, "'\\''")}'`).join(" ")}`, {
+			encoding: "utf8",
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		}).trim();
+	} catch (e) {
+		throw q(e);
+	}
+}
+function Y(e, t) {
 	return e.github.repo ? e.github.repo : t([
 		"repo",
 		"view",
@@ -338,7 +314,7 @@ function J(e, t) {
 		".nameWithOwner"
 	]);
 }
-function Y(e, t, n) {
+function X(e, t, n) {
 	let r = n([
 		"issue",
 		"list",
@@ -355,10 +331,16 @@ function Y(e, t, n) {
 	]);
 	return JSON.parse(r || "[]");
 }
-function X(e, t) {
-	return t.some((t) => W(t.title) === e);
+function Z(e, t) {
+	return t.some((t) => {
+		if (t.body) {
+			let { metadata: n } = H(t.body);
+			if (n.slug) return n.slug === e;
+		}
+		return W(t.title) === e;
+	});
 }
-function Z(e, t, n) {
+function ne(e, t, n) {
 	for (let r of t) n([
 		"label",
 		"create",
@@ -368,7 +350,7 @@ function Z(e, t, n) {
 		"--force"
 	]);
 }
-function ne(e, t, n) {
+function re(e, t, n) {
 	let r = [
 		"issue",
 		"create",
@@ -383,7 +365,7 @@ function ne(e, t, n) {
 	let i = n(r).match(/\/(\d+)\s*$/);
 	return i ? parseInt(i[1], 10) : 0;
 }
-function re(e, t, n) {
+function ie(e, t, n) {
 	n([
 		"issue",
 		"close",
@@ -392,7 +374,7 @@ function re(e, t, n) {
 		e
 	]);
 }
-function ie(e, t, n) {
+function ae(e, t, n) {
 	let r = n([
 		"pr",
 		"list",
@@ -409,7 +391,7 @@ function ie(e, t, n) {
 	]);
 	return JSON.parse(r || "[]");
 }
-function ae(e, t, n, r) {
+function oe(e, t, n, r) {
 	r([
 		"issue",
 		"comment",
@@ -420,7 +402,7 @@ function ae(e, t, n, r) {
 		n
 	]);
 }
-function oe(e) {
+function se(e) {
 	for (let t of e) {
 		let e = R[t];
 		if (e) return e;
@@ -430,82 +412,74 @@ function oe(e) {
 function Q(e, n) {
 	t(s(e), { recursive: !0 }), a(e, n);
 }
-function $(e, t) {
-	let n = t?.runGh ?? q, r = _(e);
-	return r.storage === "local" ? se(e, r, n) : le(e, r, n);
+function ce(e, t) {
+	let n = t?.runGh ?? J, r = _(e);
+	return r.storage === "local" ? le(e, r, n) : ue(e, r, n);
 }
-function se(e, t, n) {
-	let r = [], i = J(t, n), a = K(e, t);
-	if (a.length === 0) return b(e, { storage: p }), r.push("No artifacts found — nothing to migrate."), r.push(`✓ Storage switched to "${p}".`), r;
+function le(e, t, n) {
+	let r = [], i = Y(t, n), a = K(e, t);
+	if (a.length === 0) return x(e, { storage: p }), r.push("No artifacts found — nothing to migrate."), r.push(`✓ Storage switched to "${p}".`), r;
 	let o = t.github.labels?.prd ?? "tk:prd", s = t.github.labels?.plan ?? "tk:plan";
-	Z(i, [
+	ne(i, [
 		o,
 		s,
 		...[...new Set(a.map((e) => V(e.metadata.status ?? "created")))]
 	], n);
-	let c = Y(i, o, n), l = Y(i, s, n);
+	let c = X(i, o, n), l = X(i, s, n);
 	for (let e of a) {
 		let t = e.type === "prd" ? o : s, a = e.type === "prd" ? c : l;
-		if (X(e.slug, a)) {
+		if (Z(e.slug, a)) {
 			r.push(`⚠ skip ${e.type} "${e.slug}" — already exists on GitHub`);
 			continue;
 		}
-		let u = V(e.metadata.status ?? "created"), d = `${B(e.metadata)}\n\n${e.body.replace(/^\n/, "")}`, f = ne(i, {
+		let u = e.metadata.status ?? "created", d = V(u), f = `${B(e.metadata)}\n\n${e.body.replace(/^\n/, "")}`, p = re(i, {
 			title: `[${t}] ${e.slug}: ${e.title}`,
-			body: d,
-			labels: [t, u]
+			body: f,
+			labels: [t, d]
 		}, n);
-		e.archived ? (re(i, f, n), ce(i, e.slug, f, n), r.push(`✓ ${e.type} "${e.slug}" → issue #${f} (closed)`)) : r.push(`✓ ${e.type} "${e.slug}" → issue #${f}`);
+		u === "done" ? (ie(i, p, n), $(i, e.slug, p, n), r.push(`✓ ${e.type} "${e.slug}" → issue #${p} (closed)`)) : r.push(`✓ ${e.type} "${e.slug}" → issue #${p}`);
 	}
-	return b(e, { storage: p }), r.push(`✓ Storage switched to "${p}".`), r;
+	return x(e, { storage: p }), r.push(`✓ Storage switched to "${p}".`), r;
 }
-function ce(e, t, n, r) {
-	let i = ie(e, t, r);
-	i.length !== 0 && ae(e, n, `Linked PR: ${i.map((e) => `#${e.number}`).join(", ")}`, r);
+function $(e, t, n, r) {
+	let i = ae(e, t, r);
+	i.length !== 0 && oe(e, n, `Linked PR: ${i.map((e) => `#${e.number}`).join(", ")}`, r);
 }
-function le(t, n, r) {
-	let i = [], a = J(n, r), o = n.github.labels?.prd ?? "tk:prd", s = n.github.labels?.plan ?? "tk:plan", l = Y(a, o, r), u = Y(a, s, r), d = [...l.map((e) => ({
+function ue(t, n, r) {
+	let i = [], a = Y(n, r), o = n.github.labels?.prd ?? "tk:prd", s = n.github.labels?.plan ?? "tk:plan", l = X(a, o, r), u = X(a, s, r), d = [...l.map((e) => ({
 		...e,
 		type: "prd"
 	})), ...u.map((e) => ({
 		...e,
 		type: "plan"
 	}))];
-	if (d.length === 0) return b(t, { storage: f }), i.push("No GitHub issues found — nothing to migrate."), i.push(`✓ Storage switched to "${f}".`), i;
+	if (d.length === 0) return x(t, { storage: f }), i.push("No GitHub issues found — nothing to migrate."), i.push(`✓ Storage switched to "${f}".`), i;
 	for (let r of d) {
-		let a = W(r.title);
-		if (!a) continue;
-		let o = r.labels.map((e) => e.name), s = o.includes("tk:done") && r.state === "CLOSED", { metadata: l, body: u } = H(r.body ?? ""), d = l.status ?? oe(o);
-		if (s) {
-			let o = c(t, n.paths.archives, a), s = c(o, "prd.md"), f = c(o, "plan.md"), p = r.type === "prd" ? s : f;
-			if (e(p)) {
-				i.push(`⚠ skip ${r.type} "${a}" — local file already exists`);
-				continue;
-			}
-			r.type === "prd" ? Q(p, `${U({
-				...l,
-				status: d
-			})}\n${u}`) : Q(p, u), i.push(`✓ ${r.type} "${a}" → ${p} (archived)`);
-		} else {
-			let o = c(t, r.type === "prd" ? n.paths.prds : n.paths.plans, `${a}.md`);
-			if (e(o)) {
-				i.push(`⚠ skip ${r.type} "${a}" — local file already exists`);
-				continue;
-			}
-			r.type === "prd" ? Q(o, `${U({
-				...l,
-				status: d
-			})}\n${u}`) : Q(o, u), i.push(`✓ ${r.type} "${a}" → ${o}`);
+		let { metadata: a, body: o } = H(r.body ?? ""), s = a.slug ?? W(r.title);
+		if (!s) continue;
+		let l = r.labels.map((e) => e.name), u = a.status ?? se(l), d = c(t, r.type === "prd" ? n.paths.prds : n.paths.plans, `${s}.md`);
+		if (e(d)) {
+			i.push(`⚠ skip ${r.type} "${s}" — local file already exists`);
+			continue;
+		}
+		if (r.type === "prd") Q(d, `${U({
+			...a,
+			status: u
+		})}\n${o}`);
+		else {
+			let e = {};
+			a.source_prd && (e.source_prd = a.source_prd), (a.slug || s) && (e.slug = a.slug ?? s), u && (e.status = u), a.completed && (e.completed = a.completed), Q(d, `${U(e)}\n${o}`);
 		}
+		i.push(`✓ ${r.type} "${s}" → ${d}`);
 	}
-	return b(t, { storage: f }), i.push(`✓ Storage switched to "${f}".`), i;
+	return x(t, { storage: f }), i.push(`✓ Storage switched to "${f}".`), i;
 }
 //#endregion
 //#region src/commands/uninstall.ts
-function ue(t) {
-	if (!C.some((n) => e(c(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — nothing to uninstall");
+function de(t) {
+	if (!w.some((n) => e(c(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — nothing to uninstall");
 	let n = [];
-	for (let r of C) {
+	for (let r of w) {
 		let a = c(t, ".claude", "skills", r);
 		e(a) && (i(a, {
 			recursive: !0,
@@ -515,4 +489,4 @@ function ue(t) {
 	return n;
 }
 //#endregion
-export { N as a, w as c, f as d, _ as f, I as i, T as l, $ as n, D as o, b as p, te as r, E as s, ue as t, C as u };
+export { P as a, T as c, f as d, _ as f, L as i, E as l, ce as n, O as o, x as p, ee as r, D as s, de as t, w as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tracerkit",
-  "version": "1.15.0",
-  "description": "Spec-driven workflow for Claude Code: replace ad-hoc prompts with PRD → plan → verify.",
+  "version": "1.17.0",
+  "description": "Spec-driven workflow for AI coding agents — PRD → plan → verify. Pure Markdown skills, zero runtime deps.",
   "license": "MIT",
   "author": {
     "name": "helderberto",

package/skills/brief/SKILL.md

@@ -12,7 +12,7 @@ Overview of active features, progress, and suggested focus.
 
 <!-- if:local -->
 
-- Available PRDs: !`ls .tracerkit/prds/ 2>&1`
+- Available PRDs: !`ls .tracerkit/prds/*.md 2>/dev/null || echo "(none)"`
   <!-- end:local -->
   <!-- if:github -->
 - Available PRDs: list open GitHub Issues with label `{{github.labels.prd}}`
@@ -31,11 +31,11 @@ For each `.md` file in `.tracerkit/prds/`: parse frontmatter, extract `status` a
 
 List open GitHub Issues with label `{{github.labels.prd}}`:
 
-6. For each issue, parse the `<!-- tk:metadata -->` comment in the body
-7. Extract `status` and `created` fields from the metadata
-8. Also check labels: `tk:created`, `tk:in-progress`
-9. Skip issues with `tk:done` label
-10. The slug is extracted from the title: `[{{github.labels.prd}}] <slug>: ...`
+1. For each issue, parse the `<!-- tk:metadata -->` comment in the body
+2. Extract `status` and `created` fields from the metadata
+3. Also check labels: `tk:created`, `tk:in-progress`
+4. Skip issues with `tk:done` label
+5. The slug is extracted from the title: `[{{github.labels.prd}}] <slug>: ...`
 <!-- end:github -->
 
 ### 2. Count progress from plans

package/skills/check/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Verify implementation against plan. Shows progress, finds blockers, and archives when done. Use after implementing a plan, or without arguments to see a feature dashboard.
+description: Verify implementation against plan. Shows progress, finds blockers, and marks complete when done. Use after implementing a plan, or without arguments to see a feature dashboard.
 argument-hint: '[slug]'
 ---
 
@@ -7,13 +7,15 @@ argument-hint: '[slug]'
 
 # Check Implementation
 
-Check implementation against a plan. Update checks, stamp findings, transition status, and archive when done.
+Check implementation against a plan. Update checks, stamp findings, transition status, and mark complete when done.
+
+**Interactive prompts**: use `AskUserQuestion` for all user-facing questions — selections and confirmations.
 
 ## Pre-loaded context
 
 <!-- if:local -->
 
-- Available plans: !`ls .tracerkit/plans/ 2>&1`
+- Available plans: !`ls .tracerkit/plans/*.md 2>/dev/null || echo "(none)"`
   <!-- end:local -->
   <!-- if:github -->
 - Available plans: list open GitHub Issues with label `{{github.labels.plan}}`
@@ -50,7 +52,7 @@ For each `.md` file in `.tracerkit/prds/`:
 6. If plan issue exists, count progress from checkboxes in its body (see Progress Algorithm below). Show `—` if no plan.
 <!-- end:github -->
 
-Ask which feature to verify.
+Use `AskUserQuestion` with each feature as an option to let the user pick which to verify.
 
 ## Progress Algorithm
 
@@ -62,12 +64,12 @@ Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Per-phase: `Pha
 
 <!-- if:local -->
 
-Read `.tracerkit/plans/<slug>.md`. If missing, list plans and ask.
+Read `.tracerkit/plans/<slug>.md`. If missing, list plans and use `AskUserQuestion` to select one.
 
 <!-- end:local -->
 <!-- if:github -->
 
-Find plan issue: open issue with label `{{github.labels.plan}}`, title matching `[{{github.labels.plan}}] <slug>:`. If missing, list plans and ask.
+Find plan issue: open issue with label `{{github.labels.plan}}`, title matching `[{{github.labels.plan}}] <slug>:`. If missing, list plans and use `AskUserQuestion` to select one.
 
 <!-- end:github -->
 
@@ -175,25 +177,25 @@ Append a verdict block at the bottom of the plan issue body by editing the issue
 
 If a previous verdict block exists, replace it with the new one.
 
-### 7. On `done` — archive
+### 7. On `done` — mark complete
 
 If all checks pass and zero BLOCKERS:
 
 <!-- if:local -->
 
-Archive to `.tracerkit/archives/<slug>/`:
-
-1. Copy PRD → `prd.md` (set `status: done`, add `completed` timestamp in frontmatter)
-2. Copy plan → `plan.md` (append `## Archived` with date)
-3. Delete originals
+1. Update PRD frontmatter: `status: done`, add `completed: <UTC ISO 8601>`
+2. Update plan frontmatter: `status: done`, add `completed: <UTC ISO 8601>`
 
 <!-- end:local -->
 <!-- if:github -->
 
-1. PRD issue: add `tk:done`, remove `tk:in-progress`, set metadata `status: done` + `completed` timestamp
-2. Close PRD issue (reason: `completed`)
-3. Close plan issue (reason: `completed`)
-4. If current PR exists, reference it in closing comment on PRD issue
+1. If on a feature branch with commits ahead of default:
+   a. Push branch if not pushed
+   b. Open PR with `Closes #<prd-number>, Closes #<plan-number>` (or update existing PR body)
+2. Search merged PRs matching slug: `gh pr list --search <slug> --state merged` — add comment on PRD issue linking found PRs
+3. PRD issue: add `tk:done`, remove `tk:in-progress`, update metadata `status: done` + `completed` timestamp
+4. Close PRD issue (reason: `completed`)
+5. Close plan issue (reason: `completed`)
 
 <!-- end:github -->
 
@@ -208,6 +210,6 @@ List the blockers to fix, then re-run `/tk:check <slug>`.
 ## Rules
 
 - The review subagent must be **read-only** — it must not create, edit, or delete any files
-- The only file writes this skill makes are: checkboxes + verdict block in the plan, and the archive steps on `done`
+- The only file writes this skill makes are: checkboxes + verdict block in the plan, and the status updates on `done`
 - Never modify implementation code — only observe and report
-- If the PRD file is missing but all checks pass, warn and proceed — archive the plan only (skip PRD steps in archive)
+- If the PRD file is missing but all checks pass, warn and proceed — mark the plan complete only (skip PRD status update)

package/skills/plan/SKILL.md

@@ -9,6 +9,8 @@ argument-hint: '[slug]'
 
 Break a PRD into phased vertical slices (tracer bullets).
 
+**Interactive prompts**: use `AskUserQuestion` for all user-facing questions — selections, confirmations, and approval steps.
+
 <!-- if:local -->
 
 Output: `.tracerkit/plans/<slug>.md`.
@@ -24,7 +26,7 @@ Output: a GitHub Issue with label `{{github.labels.plan}}`.
 
 <!-- if:local -->
 
-- Available PRDs: !`ls .tracerkit/prds/ 2>&1`
+- Available PRDs: !`ls .tracerkit/prds/*.md 2>/dev/null || echo "(none)"`
   <!-- end:local -->
   <!-- if:github -->
 - Available PRDs: list open GitHub Issues with label `{{github.labels.prd}}`
@@ -34,7 +36,7 @@ Output: a GitHub Issue with label `{{github.labels.plan}}`.
 
 The argument (if provided) is: $ARGUMENTS
 
-Use argument as `<slug>`. If empty, list available PRDs and ask.
+Use argument as `<slug>`. If empty, list available PRDs and use `AskUserQuestion` with each PRD as an option.
 
 ## Workflow
 
@@ -42,12 +44,12 @@ Use argument as `<slug>`. If empty, list available PRDs and ask.
 
 <!-- if:local -->
 
-Read `.tracerkit/prds/<slug>.md`. If missing, list PRDs and ask. If `.tracerkit/plans/<slug>.md` exists, ask: overwrite or new name?
+Read `.tracerkit/prds/<slug>.md`. If missing, list PRDs and use `AskUserQuestion` to select one. If `.tracerkit/plans/<slug>.md` exists, use `AskUserQuestion` with options: "Overwrite existing" / "Pick a new name".
 
 <!-- end:local -->
 <!-- if:github -->
 
-Find PRD issue: open issue with label `{{github.labels.prd}}`, title matching `[{{github.labels.prd}}] <slug>:`. If missing, list PRDs and ask. If plan issue with label `{{github.labels.plan}}` and matching title exists, ask: update or new name?
+Find PRD issue: open issue with label `{{github.labels.prd}}`, title matching `[{{github.labels.prd}}] <slug>:`. If missing, list PRDs and use `AskUserQuestion` to select one. If plan issue with label `{{github.labels.plan}}` and matching title exists, use `AskUserQuestion` with options: "Update existing plan" / "Use a new name".
 
 <!-- end:github -->
 
@@ -102,7 +104,7 @@ Each phase: thin vertical slice through all layers (schema → service → API
 
 **Phase naming:** use a goal phrase answering "what can we demo when this is done?" (e.g., "Phase 1 — Revenue visible end-to-end"), not a layer name.
 
-**Done when:** checkbox list of atomic, verifiable conditions (not prose). Test: "Can an agent verify by reading files, running a command, or checking a test?" Agent marks `[x]` during implementation.
+**Done when:** checkbox list of atomic, verifiable conditions. Each must name a test file/name, a shell command, or a file+content to verify. No prose-only conditions. Test: "Can an agent verify by reading files, running a command, or checking a test?"
 
 **Layer-by-layer exception:** if complex schema changes underpin all modules and no story stands alone, build data foundation first, then slice vertically.
 
@@ -110,7 +112,7 @@ Each phase: thin vertical slice through all layers (schema → service → API
 
 - 1 module touched → 2–3 phases max
 - 2–3 modules touched → 3–5 phases max
-- 4+ modules or 6+ phases → stop and ask the user to split the PRD
+- 4+ modules or 6+ phases → stop and use `AskUserQuestion`: "PRD touches 4+ modules. Split before planning?" with options: "Split the PRD" (Recommended) / "Continue anyway"
 
 Count "modules touched" by scanning the PRD's New Modules and Schema Changes sections.
 
@@ -122,7 +124,7 @@ Assign an agent tag to tasks where appropriate:
 
 ### 5. Quiz the user
 
-Present breakdown (title, user stories covered, done-when per phase). Ask: granularity right? Merge or split? Iterate until approved.
+Present breakdown (title, user stories covered, done-when per phase). Use `AskUserQuestion`: "How's the granularity?" with options: "Looks good, proceed" (Recommended) / "Merge some phases" / "Split a phase". Iterate until approved.
 
 ### 6. Save plan
 
@@ -131,15 +133,23 @@ Present breakdown (title, user stories covered, done-when per phase). Ask: granu
 Save to `.tracerkit/plans/<slug>.md` (create dir if missing).
 
 ```markdown
+---
+source_prd: .tracerkit/prds/<slug>.md
+slug: <slug>
+status: in_progress
+---
+
 # Plan: <Feature Name>
 
 > Source PRD: `.tracerkit/prds/<slug>.md`
 ```
 
+Then update PRD frontmatter: add `plan: .tracerkit/plans/<slug>.md` field.
+
 <!-- end:local -->
 <!-- if:github -->
 
-Ensure labels exist: `{{github.labels.plan}}`, `tk:in-progress` (create if missing).
+Ensure labels exist: `gh label create {{github.labels.plan}} --repo {{github.repo}} --force`, `gh label create tk:in-progress --repo {{github.repo}} --force`.
 
 Create GitHub Issue — title: `[{{github.labels.plan}}] <slug>: Plan: <Feature Title>`, labels: `{{github.labels.plan}}`, `tk:in-progress`.
 
@@ -147,6 +157,7 @@ Create GitHub Issue — title: `[{{github.labels.plan}}] <slug>: Plan: <Feature
 <!-- tk:metadata
 source_prd: #<PRD issue number>
 slug: <slug>
+status: in_progress
 -->
 
 # Plan: <Feature Name>
@@ -156,6 +167,19 @@ slug: <slug>
 
 <!-- end:github -->
 
+### 6b. Backlink PRD
+
+<!-- if:local -->
+
+Already linked via PRD frontmatter `plan:` field (set in step 6).
+
+<!-- end:local -->
+<!-- if:github -->
+
+Add comment on PRD issue: "Plan: #<plan-issue-number>" (creates cross-reference).
+
+<!-- end:github -->
+
 Use this structure for the plan body:
 
 ```markdown
@@ -193,7 +217,25 @@ Carried forward from PRD verbatim.
 Gaps found in the PRD needing resolution. Blank if none.
 ```
 
-Print one line per phase: `Phase N — <title> (<condition summary>)`. Then ask: "Run `/tk:check <slug>` when ready?"
+Print one line per phase: `Phase N — <title> (<condition summary>)`. Then use `AskUserQuestion`: "What's next?" with options: "Start implementing" (Recommended) / "Run `/tk:check <slug>`" / "Done for now".
+
+## Execution guidance
+
+When implementing this plan, **always offer to create a feature branch** before writing any code. Use `AskUserQuestion`: "Create branch `feat/<slug>`?" with options: "Yes, create branch" (Recommended) / "No, stay on current branch". If accepted, create the branch from the default branch.
+
+### During implementation
+
+Mark each "Done when" checkbox `[x]` **immediately after verifying** the condition.
+
+Always update the local plan file (`.tracerkit/plans/<slug>.md`): change `- [ ]` → `- [x]`. This file is the working copy for both local and GitHub modes.
+
+<!-- if:github -->
+
+**Sync to GitHub at phase boundaries**: after completing all items in a phase, update the plan issue body with `gh issue edit` to reflect the local state. This avoids per-item API calls.
+
+After all phases, open a PR with body containing `Closes #<prd-issue>, Closes #<plan-issue>`.
+
+<!-- end:github -->
 
 ## Rules
 

package/skills/prd/SKILL.md

@@ -9,11 +9,13 @@ argument-hint: <idea>
 
 Skip satisfied steps. If argument provided, skip to Step 2.
 
+**Interactive prompts**: use `AskUserQuestion` for all user-facing questions — choices, confirmations, and interview questions. This provides structured selection UI instead of plain text prompts.
+
 ## Pre-loaded context
 
 <!-- if:local -->
 
-- Existing PRDs: !`ls .tracerkit/prds/ 2>&1`
+- Existing PRDs: !`ls .tracerkit/prds/*.md 2>/dev/null || echo "(none)"`
   <!-- end:local -->
   <!-- if:github -->
 - Existing PRDs: list open GitHub Issues with label `{{github.labels.prd}}`
@@ -26,19 +28,20 @@ The argument is: $ARGUMENTS
 If empty, go to Step 1; derive slug after gathering the idea. If provided, derive slug:
 
 1. Take only the text before the first `—` or `–` (if present)
-2. Lowercase the text
-3. Remove filler words: a, an, the, for, of, to, in, on, with, and, or, but, is, be
-4. Take the first 4 remaining words (or fewer if less exist)
-5. Join with hyphens → `<slug>`
+2. Strip leading command verbs: create, build, implement, add, update, fix, make, write, plan, get, show, support
+3. Lowercase the text
+4. Remove filler words: a, an, the, for, of, to, in, on, with, and, or, but, is, be
+5. Take the first 4 remaining words (or fewer if less exist)
+6. Join with hyphens → `<slug>`
 
 <!-- if:local -->
 
-Output: `.tracerkit/prds/<slug>.md`. If exists, ask: overwrite or new name?
+Output: `.tracerkit/prds/<slug>.md`. If exists, use `AskUserQuestion` with options: "Overwrite existing" / "Pick a new name".
 
 <!-- end:local -->
 <!-- if:github -->
 
-Output: GitHub Issue with label `{{github.labels.prd}}`, title `[{{github.labels.prd}}] <slug>: <Feature Title>`. If matching issue exists, ask: update or new slug?
+Output: GitHub Issue with label `{{github.labels.prd}}`, title `[{{github.labels.prd}}] <slug>: <Feature Title>`. If matching issue exists, use `AskUserQuestion` with options: "Update existing issue" / "Use a new slug".
 
 <!-- end:github -->
 
@@ -56,7 +59,7 @@ Map current state: data models, services, API routes, frontend, tests. Note exis
 
 ### 3. Interview
 
-One question at a time. Lead with your recommended answer. Explore code instead of asking when possible. Offer A/B/C for terse answers.
+One question at a time. Lead with your recommended answer (mark it `(Recommended)` and list first). Explore code instead of asking when possible. Use `AskUserQuestion` with 2–4 options for each interview question — structured choices are faster than free-text.
 
 | Branch           | Key questions                           | Skip when                        |
 | ---------------- | --------------------------------------- | -------------------------------- |
@@ -70,7 +73,7 @@ One question at a time. Lead with your recommended answer. Explore code instead
 
 ### 3b. Gray areas
 
-Surface ambiguities, contradictions, unstated assumptions. Present numbered list. Resolve all before continuing.
+Surface ambiguities, contradictions, unstated assumptions. For each gray area, use `AskUserQuestion` with proposed resolution options. Resolve all before continuing.
 
 ### 4. Design modules
 
@@ -78,7 +81,7 @@ Sketch modules. Favor **deep modules** — simple interface (1-3 entry points) h
 
 Shallow signals: many small 1:1 functions, callers compose multiple calls, feature changes require interface changes.
 
-Present modules. Confirm which need tests.
+Present modules. Use `AskUserQuestion` (multiSelect) to confirm which modules need tests.
 
 ### 5. Write PRD
 
@@ -98,12 +101,13 @@ status: created
 <!-- end:local -->
 <!-- if:github -->
 
-Ensure labels exist: `{{github.labels.prd}}`, `tk:created` (create if missing).
+Ensure labels exist: `gh label create {{github.labels.prd}} --repo {{github.repo}} --force`, `gh label create tk:created --repo {{github.repo}} --force`.
 
 Create GitHub Issue — title: `[{{github.labels.prd}}] <slug>: <Feature Title>`, labels: `{{github.labels.prd}}`, `tk:created`.
 
 ```markdown
 <!-- tk:metadata
+slug: <slug>
 created: <UTC ISO 8601>
 status: created
 -->
@@ -132,4 +136,4 @@ PRD body structure (same for local file and issue body). Omit empty sections. No
 
 ---
 
-Then ask: "Run `/tk:plan <slug>` next?"
+Then use `AskUserQuestion`: "What's next?" with options: "Run `/tk:plan <slug>`" (Recommended) / "Done for now".