tracerkit 1.14.0 → 1.16.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,49 +101,36 @@ 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.
 
-</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
+To migrate existing artifacts between backends:
 
-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.
+```bash
+tracerkit migrate-storage           # local→github or github→local (auto-detected)
+```
 
-### `/tk:check [slug]`: Verify and archive
+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.
 
-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.
+</details>
 
-Without arguments, shows a feature dashboard with status and progress before asking which feature to check.
+## Skills
 
-**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
 
-| Document                                         | Description                                        |
-| ------------------------------------------------ | -------------------------------------------------- |
-| [Examples](docs/examples.md)                     | Walk through end-to-end usage scenarios            |
-| [CLI Reference](docs/cli-reference.md)           | Commands: init, update, config, uninstall          |
-| [Configuration](docs/configuration.md)           | Storage backends, GitHub options, custom paths     |
-| [Metadata Lifecycle](docs/metadata-lifecycle.md) | Understand YAML frontmatter states and transitions |
-| [Comparison](docs/comparison.md)                 | Compare TracerKit to Spec Kit, Kiro, and OpenSpec  |
+| Document                                         | Description                                                |
+| ------------------------------------------------ | ---------------------------------------------------------- |
+| [Examples](docs/examples.md)                     | Walk through end-to-end usage scenarios                    |
+| [CLI Reference](docs/cli-reference.md)           | Commands: init, update, config, migrate-storage, uninstall |
+| [Configuration](docs/configuration.md)           | Storage backends, GitHub options, custom paths             |
+| [Metadata Lifecycle](docs/metadata-lifecycle.md) | Understand YAML frontmatter states and transitions         |
+| [Comparison](docs/comparison.md)                 | Compare TracerKit to Spec Kit, Kiro, and OpenSpec          |
 
 ## Contributing
 

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-C4K7aNpf.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-C4K7aNpf.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-C4K7aNpf.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"
@@ -38,8 +37,7 @@ 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 b(e) {
@@ -128,7 +126,7 @@ function M(e) {
 }
 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 P(e, r, i) {
 	let o = i ?? A(k).map(j);
@@ -188,19 +186,23 @@ function L(t, n) {
 }
 //#endregion
 //#region src/commands/init.ts
-function R(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 z = {
+var te = {
 	created: "tk:created",
 	in_progress: "tk:in-progress",
 	done: "tk:done"
+}, R = {
+	"tk:created": "created",
+	"tk:in-progress": "in_progress",
+	"tk:done": "done"
 };
-function B(e) {
+function z(e) {
 	let t = e.match(/^---\n([\s\S]*?)---\n([\s\S]*)$/);
 	if (!t) return {
 		metadata: {},
@@ -218,91 +220,91 @@ function B(e) {
 		body: t[2]
 	};
 }
-function V(e) {
+function B(e) {
 	let t = Object.entries(e);
 	return t.length === 0 ? "<!-- tk:metadata\n-->" : `<!-- tk:metadata\n${t.map(([e, t]) => `${e}: ${t}`).join("\n")}\n-->`;
 }
+function V(e) {
+	return te[e] ?? "tk:created";
+}
 function H(e) {
-	return z[e] ?? "tk:created";
+	let t = e.match(/<!--\s*tk:metadata\n([\s\S]*?)-->\n*([\s\S]*)$/);
+	if (!t) return {
+		metadata: {},
+		body: e
+	};
+	let n = {};
+	for (let e of t[1].split("\n")) {
+		let t = e.indexOf(":");
+		if (t === -1) continue;
+		let r = e.slice(0, t).trim(), i = e.slice(t + 1).trim();
+		r && (n[r] = i);
+	}
+	return {
+		metadata: n,
+		body: t[2]
+	};
 }
 function U(e) {
+	let t = Object.entries(e);
+	return t.length === 0 ? "---\n---\n" : `---\n${t.map(([e, t]) => `${e}: ${t}`).join("\n")}\n---\n`;
+}
+function W(e) {
 	let t = e.match(/\[[^\]]+\]\s+([^:]+):/);
 	return t ? t[1].trim() : null;
 }
-function W(e) {
+function G(e) {
 	let t = e.match(/^#\s+(.+)$/m);
 	return t ? t[1].trim() : "Untitled";
 }
-function G(t, i) {
+function K(t, i) {
 	let a = [], s = c(t, i.paths.prds);
 	if (e(s)) for (let e of r(s)) {
 		if (!e.endsWith(".md")) continue;
-		let t = o(e, ".md"), { metadata: r, body: i } = B(n(c(s, e), "utf8"));
+		let t = o(e, ".md"), { metadata: r, body: i } = z(n(c(s, e), "utf8"));
 		a.push({
 			slug: t,
 			type: "prd",
 			metadata: r,
 			body: i,
-			title: W(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: W(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 } = B(n(i, "utf8"));
-			a.push({
-				slug: r,
-				type: "prd",
-				metadata: {
-					...e,
-					status: "done"
-				},
-				body: t,
-				title: W(t),
-				archived: !0
-			});
-		}
-		if (e(o)) {
-			let e = n(o, "utf8");
-			a.push({
-				slug: r,
-				type: "plan",
-				metadata: { status: "done" },
-				body: e,
-				title: W(e),
-				archived: !0
-			});
-		}
-	}
 	return a;
 }
-function K(e) {
-	return d(`gh ${e.map((e) => `'${e.replace(/'/g, "'\\''")}'`).join(" ")}`, {
-		encoding: "utf8",
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		]
-	}).trim();
-}
-function q(e, t) {
+function q(e) {
+	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",
@@ -312,7 +314,7 @@ function q(e, t) {
 		".nameWithOwner"
 	]);
 }
-function J(e, t, n) {
+function X(e, t, n) {
 	let r = n([
 		"issue",
 		"list",
@@ -323,16 +325,22 @@ function J(e, t, n) {
 		"--state",
 		"all",
 		"--json",
-		"number,title,labels,state",
+		"number,title,body,labels,state",
 		"--limit",
 		"1000"
 	]);
 	return JSON.parse(r || "[]");
 }
-function Y(e, t) {
-	return t.some((t) => U(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 X(e, t, n) {
+function ne(e, t, n) {
 	for (let r of t) n([
 		"label",
 		"create",
@@ -342,7 +350,7 @@ function X(e, t, n) {
 		"--force"
 	]);
 }
-function Z(e, t, n) {
+function re(e, t, n) {
 	let r = [
 		"issue",
 		"create",
@@ -357,7 +365,7 @@ function Z(e, t, n) {
 	let i = n(r).match(/\/(\d+)\s*$/);
 	return i ? parseInt(i[1], 10) : 0;
 }
-function Q(e, t, n) {
+function ie(e, t, n) {
 	n([
 		"issue",
 		"close",
@@ -366,36 +374,109 @@ function Q(e, t, n) {
 		e
 	]);
 }
-function $(e, t) {
-	let n = t?.runGh ?? K, r = _(e), i = [];
-	if (r.storage !== "local") return [`Storage is already "${r.storage}". Nothing to migrate.`];
-	let a = q(r, n), o = G(e, r);
-	if (o.length === 0) return x(e, { storage: p }), i.push("No artifacts found — nothing to migrate."), i.push(`✓ Storage switched to "${p}".`), i;
-	let s = r.github.labels?.prd ?? "tk:prd", c = r.github.labels?.plan ?? "tk:plan";
-	X(a, [
+function ae(e, t, n) {
+	let r = n([
+		"pr",
+		"list",
+		"--repo",
+		e,
+		"--search",
+		t,
+		"--state",
+		"merged",
+		"--json",
+		"number,title",
+		"--limit",
+		"5"
+	]);
+	return JSON.parse(r || "[]");
+}
+function oe(e, t, n, r) {
+	r([
+		"issue",
+		"comment",
+		String(t),
+		"--repo",
+		e,
+		"--body",
+		n
+	]);
+}
+function se(e) {
+	for (let t of e) {
+		let e = R[t];
+		if (e) return e;
+	}
+	return "created";
+}
+function Q(e, n) {
+	t(s(e), { recursive: !0 }), a(e, 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 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";
+	ne(i, [
+		o,
 		s,
-		c,
-		...[...new Set(o.map((e) => H(e.metadata.status ?? "created")))]
+		...[...new Set(a.map((e) => V(e.metadata.status ?? "created")))]
 	], n);
-	let l = J(a, s, n), u = J(a, c, n);
-	for (let e of o) {
-		let t = e.type === "prd" ? s : c, r = e.type === "prd" ? l : u;
-		if (Y(e.slug, r)) {
-			i.push(`⚠ skip ${e.type} "${e.slug}" — already exists on GitHub`);
+	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 (Z(e.slug, a)) {
+			r.push(`⚠ skip ${e.type} "${e.slug}" — already exists on GitHub`);
 			continue;
 		}
-		let o = H(e.metadata.status ?? "created"), d = `${V(e.metadata)}\n\n${e.body.replace(/^\n/, "")}`, f = Z(a, {
+		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, o]
+			body: f,
+			labels: [t, d]
 		}, n);
-		e.archived ? (Q(a, f, n), i.push(`✓ ${e.type} "${e.slug}" → issue #${f} (closed)`)) : i.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 x(e, { storage: p }), i.push(`✓ Storage switched to "${p}".`), i;
+	return x(e, { storage: p }), r.push(`✓ Storage switched to "${p}".`), 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 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 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 { 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 x(t, { storage: f }), i.push(`✓ Storage switched to "${f}".`), i;
 }
 //#endregion
 //#region src/commands/uninstall.ts
-function ee(t) {
+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 w) {
@@ -408,4 +489,4 @@ function ee(t) {
 	return n;
 }
 //#endregion
-export { P as a, T as c, f as d, _ as f, L as i, E as l, $ as n, O as o, x as p, R as r, D as s, ee as t, w 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.14.0",
-  "description": "Spec-driven workflow for Claude Code: replace ad-hoc prompts with PRD → plan → verify.",
+  "version": "1.16.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,13 @@ 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.
 
 ## 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}}`
@@ -175,25 +175,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 +208,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

@@ -24,7 +24,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}}`
@@ -102,7 +102,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.
 
@@ -131,15 +131,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 +155,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 +165,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
@@ -195,6 +217,28 @@ 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?"
 
+## Execution guidance
+
+When implementing this plan, **always offer to create a feature branch** before writing any code:
+
+> "Create branch `feat/<slug>` for this work? (Y/n)"
+
+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
 
 - Phases derive from PRD user stories — never invented

package/skills/prd/SKILL.md

@@ -13,7 +13,7 @@ Skip satisfied steps. If argument provided, skip to Step 2.
 
 <!-- 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,10 +26,11 @@ 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 -->
 
@@ -98,12 +99,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
 -->