tracerkit 1.11.3 → 1.12.0

package/README.md

@@ -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.
+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.
 
 ## Get Started
 
@@ -32,7 +32,7 @@ npm install -g tracerkit
 tracerkit init
 ```
 
-Skills are installed to `~/.claude/skills/`, available in every project. Safe to re-run — adds missing skills without overwriting ones you've modified.
+Skills are installed to `~/.claude/skills/`, available in every project. Safe to re-run: adds missing skills without overwriting ones you've modified.
 
 <details>
 <summary>Per-project install (team members get skills via git)</summary>
@@ -54,7 +54,7 @@ Inside Claude Code, run:
 /plugin install tk@claude-plugins-official
 ```
 
-Run `/reload-plugins` if needed. Skills are available immediately — no build step, no config.
+Run `/reload-plugins` if needed. Skills are available immediately, no build step, no config.
 
 </details>
 
@@ -91,6 +91,20 @@ AI:  | Feature           | Status      | Age | Progress | Next
 
 See [Examples](docs/examples.md) for full walkthroughs.
 
+<details>
+<summary>GitHub Issues as storage backend</summary>
+
+Same skills, same workflow. Artifacts live in GitHub Issues instead of local files:
+
+```bash
+tracerkit init --storage github         # first install
+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. See [Configuration](docs/configuration.md) for details.
+
+</details>
+
 ## Skills
 
 TracerKit ships skills that take a feature from idea to verified archive.
@@ -99,19 +113,19 @@ TracerKit ships skills that take a feature from idea to verified archive.
 
 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`
+**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`
+**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.
+**Output:** Feature dashboard in the terminal. No files written.
 
 ### `/tk:check [slug]`: Verify and archive
 
@@ -119,7 +133,7 @@ Verifies the codebase against the plan's done-when checkboxes. Runs tests, valid
 
 Without arguments, shows a feature dashboard with status and progress before asking which feature to check.
 
-**Output:** Verdict block in `.tracerkit/plans/<slug>.md`. On `done`: `.tracerkit/archives/<slug>/prd.md` + `.tracerkit/archives/<slug>/plan.md`
+**Output:** Verdict block appended to the plan. On `done`: archives to `.tracerkit/archives/<slug>/` (local) or closes both issues (GitHub).
 
 ## Docs
 
@@ -127,7 +141,7 @@ Without arguments, shows a feature dashboard with status and progress before ask
 | ------------------------------------------------ | -------------------------------------------------- |
 | [Examples](docs/examples.md)                     | Walk through end-to-end usage scenarios            |
 | [CLI Reference](docs/cli-reference.md)           | Lifecycle commands: init, update, uninstall        |
-| [Configuration](docs/configuration.md)           | Configure custom artifact paths via `config.json`  |
+| [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  |
 

package/dist/bin.js

@@ -1,44 +1,101 @@
 #!/usr/bin/env node
-import { a as e, i as t, n, r, s as i, t as a } from "./uninstall-BhTMOfMb.js";
-import { readFileSync as o } from "node:fs";
-import { dirname as s, resolve as c } from "node:path";
-import { fileURLToPath as l } from "node:url";
-import { homedir as u } from "node:os";
+import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as s, r as c, t as l } from "./uninstall-BkaWoWd0.js";
+import { existsSync as u, readFileSync as d, statSync as f } from "node:fs";
+import { dirname as p, join as m, resolve as h } from "node:path";
+import { fileURLToPath as g } from "node:url";
+import { homedir as _ } from "node:os";
+//#region src/commands/config.ts
+function v(e, t) {
+	let [n, r] = t;
+	return n ? r ? x(e, n, r) : b(e, n) : y(e);
+}
+function y(e) {
+	let t = n(e), r = t.storage === "local" ? {
+		storage: t.storage,
+		paths: t.paths
+	} : t;
+	return JSON.stringify(r, null, 2).split("\n");
+}
+function b(e, t) {
+	let r = C(n(e), t);
+	return r === void 0 ? [`Unknown key: ${t}`] : typeof r == "object" ? [JSON.stringify(r, null, 2)] : [String(r)];
+}
+function x(e, t, n) {
+	r(e, w(t, n));
+	let i = [`✓ Set ${t} = ${n}`];
+	return S(e, i), i;
+}
+function S(e, t) {
+	a.some((t) => u(m(e, ".claude", "skills", t))) && (i(e, n(e)), t.push("✓ Skills re-rendered"));
+}
+function C(e, t) {
+	let n = t.split("."), r = e;
+	for (let e of n) {
+		if (typeof r != "object" || !r) return;
+		r = r[e];
+	}
+	return r;
+}
+function w(e, t) {
+	let n = e.split("."), r = {}, i = r;
+	for (let e = 0; e < n.length - 1; e++) {
+		let t = {};
+		i[n[e]] = t, i = t;
+	}
+	return i[n[n.length - 1]] = t, r;
+}
+//#endregion
 //#region src/cli.ts
-var { version: d } = JSON.parse(o(c(s(l(import.meta.url)), "..", "package.json"), "utf8")), f = Math.max(...t.map((e) => `${e.name} ${e.args}`.length)), p = [
+var { version: T } = JSON.parse(d(h(p(g(import.meta.url)), "..", "package.json"), "utf8")), E = Math.max(...e.map((e) => `${e.name} ${e.args}`.length)), D = [
 	"Usage: tracerkit <command> [path]",
 	"",
 	"Commands:",
-	...t.map((e) => `  ${`${e.name} ${e.args}`.padEnd(f + 2)}${e.desc}`),
+	...e.map((e) => `  ${`${e.name} ${e.args}`.padEnd(E + 2)}${e.desc}`),
 	"",
 	"Options:",
 	"  --force           Overwrite modified files during update",
+	"  --storage <type>  Set storage (local, github) during init",
 	"  --help, -h        Show this help message",
 	"  --version, -v     Print version",
 	"",
 	"All commands default to the home directory when no path is given."
 ];
-function m(e, t = u()) {
+function O(e) {
+	if (!e) return !1;
+	try {
+		return f(h(e)).isDirectory();
+	} catch {
+		return !1;
+	}
+}
+function k(e, t = _()) {
 	let n = e.find((e) => !e.startsWith("-"));
-	return n ? c(n) : t;
-}
-function h(t) {
-	if (t.includes(i.help) || t.includes("-h")) return p;
-	if (t.includes(i.version) || t.includes("-v")) return [`tracerkit/${d}`];
-	let o = t[0], s = t.slice(1);
-	if (e.includes(o)) return [`"${o}" has been removed — skills handle this now.`, "Run `tracerkit update` to get the latest skills."];
-	switch (o) {
-		case "init": return n(m(s));
+	return n ? h(n) : t;
+}
+function A(e) {
+	if (e.includes(t.help) || e.includes("-h")) return D;
+	if (e.includes(t.version) || e.includes("-v")) return [`tracerkit/${T}`];
+	let n = e[0], r = e.slice(1);
+	if (s.includes(n)) return [`"${n}" has been removed — skills handle this now.`, "Run `tracerkit update` to get the latest skills."];
+	switch (n) {
+		case "init": {
+			let e = r.indexOf(t.storage), n = e >= 0 ? r[e + 1] : void 0;
+			return o(k(e >= 0 ? r.filter((t, n) => n !== e && n !== e + 1) : r), { storage: n });
+		}
 		case "update": {
-			let e = s.includes(i.force), t = r(m(s.filter((e) => e !== i.force)), { force: e });
-			return t.push("", "Updated to the latest TracerKit."), t.push("If using Claude Code, restart your session to load changes."), t;
+			let e = r.includes(t.force), n = c(k(r.filter((e) => e !== t.force)), { force: e });
+			return n.push("", "Updated to the latest TracerKit."), n.push("If using Claude Code, restart your session to load changes."), n;
+		}
+		case "config": {
+			let e = O(r[0]) ? h(r[0]) : _();
+			return v(e, e === _() ? r : r.slice(1));
 		}
-		case "uninstall": return a(m(s));
-		default: return p;
+		case "uninstall": return l(k(r));
+		default: return D;
 	}
 }
 //#endregion
 //#region src/bin.ts
-var g = h(process.argv.slice(2));
-for (let e of g) console.log(e);
+var j = A(process.argv.slice(2));
+for (let e of j) console.log(e);
 //#endregion

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 } from "./uninstall-BhTMOfMb.js";
-export { t as COMMANDS, r as DEPRECATED_SKILLS, e as SKILL_NAMES, n as init, a as uninstall, i as update };
+import { a as e, l as t, n, r, s as i, t as a } from "./uninstall-BkaWoWd0.js";
+export { e as COMMANDS, i as DEPRECATED_SKILLS, t as SKILL_NAMES, n as init, a as uninstall, r as update };

package/dist/uninstall-BkaWoWd0.js

@@ -0,0 +1,209 @@
+import { existsSync as e, mkdirSync as t, readFileSync as n, readdirSync as r, rmSync as i, writeFileSync as a } from "node:fs";
+import { dirname as o, join as s } from "node:path";
+import { createHash as c } from "node:crypto";
+import { fileURLToPath as l } from "node:url";
+//#region src/config.ts
+var u = "local", d = "github", f = [u, d], p = {
+	prds: ".tracerkit/prds",
+	plans: ".tracerkit/plans",
+	archives: ".tracerkit/archives"
+}, m = { labels: {
+	prd: "tk:prd",
+	plan: "tk:plan"
+} };
+function h(t) {
+	let r = s(t, ".tracerkit", "config.json");
+	if (!e(r)) return {
+		storage: u,
+		paths: { ...p },
+		github: { ...m }
+	};
+	let i;
+	try {
+		i = JSON.parse(n(r, "utf8"));
+	} catch {
+		throw Error("Invalid .tracerkit/config.json — expected valid JSON");
+	}
+	return {
+		storage: g(i.storage),
+		paths: _(i.paths),
+		github: v(i.github)
+	};
+}
+function g(e) {
+	return typeof e == "string" && f.includes(e) ? e : u;
+}
+function _(e) {
+	let t = x(e) ? e : {};
+	return {
+		prds: typeof t.prds == "string" ? t.prds : p.prds,
+		plans: typeof t.plans == "string" ? t.plans : p.plans,
+		archives: typeof t.archives == "string" ? t.archives : p.archives
+	};
+}
+function v(e) {
+	let t = x(e) ? e : {}, n = x(t.labels) ? t.labels : {};
+	return {
+		...typeof t.repo == "string" ? { repo: t.repo } : {},
+		labels: {
+			prd: typeof n.prd == "string" ? n.prd : m.labels.prd,
+			plan: typeof n.plan == "string" ? n.plan : m.labels.plan
+		}
+	};
+}
+function y(r, i) {
+	let c = s(r, ".tracerkit", "config.json");
+	t(o(c), { recursive: !0 });
+	let l = {};
+	if (e(c)) try {
+		l = JSON.parse(n(c, "utf8"));
+	} catch {
+		l = {};
+	}
+	let u = b(l, i);
+	a(c, JSON.stringify(u, null, 2) + "\n");
+}
+function b(e, t) {
+	let n = { ...e };
+	for (let e of Object.keys(t)) x(n[e]) && x(t[e]) ? n[e] = b(n[e], t[e]) : n[e] = t[e];
+	return n;
+}
+function x(e) {
+	return typeof e == "object" && !!e && !Array.isArray(e);
+}
+var S = [
+	"tk:brief",
+	"tk:prd",
+	"tk:plan",
+	"tk:check"
+], C = ["tk:verify"], w = {
+	force: "--force",
+	help: "--help",
+	storage: "--storage",
+	version: "--version"
+}, T = [
+	"brief",
+	"progress",
+	"archive"
+], E = [
+	{
+		name: "init",
+		args: "[path]",
+		desc: "Install skills to ~/.claude/skills/ (or [path] if given)"
+	},
+	{
+		name: "update",
+		args: "[path]",
+		desc: "Refresh unchanged files from latest version, skip modified"
+	},
+	{
+		name: "config",
+		args: "[path] [key] [value]",
+		desc: "Get or set TracerKit configuration"
+	},
+	{
+		name: "uninstall",
+		args: "[path]",
+		desc: "Remove TracerKit skill directories, keep .tracerkit/ artifacts"
+	}
+], D = s(o(l(import.meta.url)), "..", "skills");
+function O(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(...O(s(e, r.name), n)) : i.push(n);
+	}
+	return i.sort();
+}
+function k(e) {
+	return `.claude/skills/tk:${e}`;
+}
+function A(e) {
+	return e.slice(18);
+}
+function j(e, t) {
+	let n = e;
+	t.paths.prds !== p.prds && (n = n.replaceAll(p.prds, t.paths.prds)), t.paths.plans !== p.plans && (n = n.replaceAll(p.plans, t.paths.plans)), t.paths.archives !== p.archives && (n = n.replaceAll(p.archives, t.paths.archives));
+	let r = t.storage ?? "local", i = r === "local" ? d : u;
+	return n = n.replace(RegExp(`<!-- if:${i} -->[^\\S\\n]*\\n[\\s\\S]*?<!-- end:${i} -->[^\\S\\n]*\\n?`, "g"), ""), n = n.replace(RegExp(`<!-- if:${r} -->[^\\S\\n]*\\n`, "g"), ""), n = n.replace(RegExp(`<!-- end:${r} -->[^\\S\\n]*\\n?`, "g"), ""), 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 M(e, r, i) {
+	let c = i ?? O(D).map(k);
+	for (let i of c) {
+		let c = s(D, A(i)), l = s(e, i);
+		t(o(l), { recursive: !0 }), a(l, j(n(c, "utf8"), r));
+	}
+	return { copied: c };
+}
+function N(e) {
+	return c("sha256").update(e).digest("hex");
+}
+function P(t, r) {
+	let i = O(D).map(k), a = [], o = [], c = [];
+	for (let l of i) {
+		let i = s(t, l);
+		if (!e(i)) c.push(l);
+		else {
+			let e = j(n(s(D, A(l)), "utf8"), r);
+			N(Buffer.from(e)) === N(n(i)) ? a.push(l) : o.push(l);
+		}
+	}
+	return {
+		unchanged: a,
+		modified: o,
+		missing: c
+	};
+}
+//#endregion
+//#region src/commands/update.ts
+function F(t, n) {
+	if (!S.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — run `tracerkit init` first");
+	let r = h(t), { unchanged: a, modified: o, missing: c } = P(t, r), l = [];
+	for (let n of C) {
+		let r = s(t, ".claude", "skills", n);
+		e(r) && (i(r, {
+			recursive: !0,
+			force: !0
+		}), l.push(`✗ .claude/skills/${n}/ removed (deprecated)`));
+	}
+	let u = n?.force ?? !1, d = [
+		...a,
+		...c,
+		...u ? o : []
+	];
+	if (d.length > 0) {
+		M(t, r, d);
+		for (let e of a) l.push(`✓ ${e}`);
+		for (let e of c) l.push(`✓ ${e} (added)`);
+		if (u) for (let e of o) l.push(`✓ ${e} (replaced)`);
+	}
+	if (!u && o.length > 0) {
+		for (let e of o) l.push(`⚠ ${e} (skipped — modified)`);
+		l.push("", "Run `tracerkit update --force` to replace modified files with latest versions.");
+	}
+	return l;
+}
+//#endregion
+//#region src/commands/init.ts
+function I(t, n) {
+	let r = h(t), i = n?.storage && n.storage !== r.storage;
+	if (i && y(t, { storage: n.storage }), S.some((n) => e(s(t, ".claude", "skills", n)))) return F(t, { force: !!i });
+	let { copied: a } = M(t, h(t));
+	return a.map((e) => `✓ ${e}`);
+}
+//#endregion
+//#region src/commands/uninstall.ts
+function L(t) {
+	if (!S.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — nothing to uninstall");
+	let n = [];
+	for (let r of S) {
+		let a = s(t, ".claude", "skills", r);
+		e(a) && (i(a, {
+			recursive: !0,
+			force: !0
+		}), n.push(`✗ .claude/skills/${r}/ removed`));
+	}
+	return n;
+}
+//#endregion
+export { E as a, w as c, h as d, y as f, M as i, S as l, I as n, T as o, F as r, C as s, L as t, u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracerkit",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "description": "Spec-driven workflow for Claude Code: replace ad-hoc prompts with PRD → plan → verify.",
   "license": "MIT",
   "author": {

package/skills/brief/SKILL.md

@@ -8,7 +8,13 @@ Get a quick overview of all active features, their progress, and what to focus o
 
 ## Pre-loaded context
 
+<!-- if:local -->
+
 - Available PRDs: !`ls .tracerkit/prds/ 2>&1`
+  <!-- end:local -->
+  <!-- if:github -->
+- Available PRDs: list open GitHub Issues with label `{{github.labels.prd}}`
+<!-- end:github -->
 
 ## Algorithm
 
@@ -16,6 +22,8 @@ Follow these steps exactly to build the briefing table:
 
 ### 1. Discover features
 
+<!-- if:local -->
+
 For each `.md` file in `.tracerkit/prds/`:
 
 1. Read the file
@@ -23,9 +31,22 @@ For each `.md` file in `.tracerkit/prds/`:
 3. Extract `status` and `created` fields
 4. Skip files where `status: done`
 5. The slug is the filename without `.md`
+   <!-- end:local -->
+   <!-- if:github -->
+
+   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>: ...`
+<!-- end:github -->
 
 ### 2. Count progress from plans
 
+<!-- if:local -->
+
 For each slug, check if `.tracerkit/plans/<slug>.md` exists. If it does:
 
 1. Read the plan file
@@ -38,6 +59,23 @@ For each slug, check if `.tracerkit/plans/<slug>.md` exists. If it does:
 
 If no plan exists, progress is `—` and next is `—`.
 
+<!-- end:local -->
+<!-- if:github -->
+
+For each slug, search for a GitHub Issue with label `{{github.labels.plan}}` and title matching `[{{github.labels.plan}}] <slug>:`. If found:
+
+1. Read the plan issue body
+2. Find every `## Phase N` heading (regex: `^## Phase \d+`)
+3. Within each phase section (until the next `## ` heading), count:
+   - Checked items: lines matching `^- \[x\] ` (case-insensitive)
+   - Unchecked items: lines matching `^- \[ \] `
+4. Sum checked and total across all phases → `checked/total`
+5. Find the first unchecked item (`^- \[ \] (.+)`) in the entire plan — that's the "Next" value. Strip any trailing `[tag]` markers.
+
+If no plan issue exists, progress is `—` and next is `—`.
+
+<!-- end:github -->
+
 ### 3. Build the table
 
 Sort features by `created` date ascending (no-date entries last). Calculate age from `created`:
@@ -74,6 +112,12 @@ Append below the table:
 
 Ask the user what they'd like to do:
 
+<!-- if:local -->
+
 - Continue the focused feature (read its plan at `.tracerkit/plans/<slug>.md`)
+  <!-- end:local -->
+  <!-- if:github -->
+- Continue the focused feature (read its plan issue)
+<!-- end:github -->
 - Start a new feature with `/tk:prd`
 - Check progress on a feature with `/tk:check <slug>`

package/skills/check/SKILL.md

@@ -9,7 +9,13 @@ Check implementation against a plan. Update checks, stamp findings, transition s
 
 ## Pre-loaded context
 
+<!-- if:local -->
+
 - Available plans: !`ls .tracerkit/plans/ 2>&1`
+  <!-- end:local -->
+  <!-- if:github -->
+- Available plans: list open GitHub Issues with label `{{github.labels.plan}}`
+<!-- end:github -->
 
 ## Input
 
@@ -25,11 +31,22 @@ If no argument is provided, build a summary table before asking which one to che
 | <slug>  | ...    | 3/7      |
 ```
 
+<!-- if:local -->
+
 For each `.md` file in `.tracerkit/prds/`:
 
 1. Read the file, parse YAML frontmatter (block between `---` fences)
 2. Extract `status` — use `unknown` if missing
 3. If `.tracerkit/plans/<slug>.md` exists, count progress (see Progress Algorithm below). Show `—` if no plan.
+   <!-- end:local -->
+   <!-- if:github -->
+
+   List open GitHub Issues with label `{{github.labels.prd}}`:
+
+4. For each PRD issue, extract `status` from labels (`tk:created`, `tk:in-progress`)
+5. Find matching plan issue with label `{{github.labels.plan}}` and same slug in title
+6. If plan issue exists, count progress from checkboxes in its body (see Progress Algorithm below). Show `—` if no plan.
+<!-- end:github -->
 
 After the table, ask which feature to verify.
 
@@ -48,12 +65,30 @@ To count progress for a plan file:
 
 ### 1. Load the plan
 
+<!-- if:local -->
+
 Read `.tracerkit/plans/<slug>.md`. If it does not exist, list available plans and ask.
 
+<!-- end:local -->
+<!-- if:github -->
+
+Find the plan issue: search for an open GitHub Issue with label `{{github.labels.plan}}` and title matching `[{{github.labels.plan}}] <slug>:`. Read its body. If not found, list available plan issues and ask.
+
+<!-- end:github -->
+
 ### 2. Load the PRD
 
+<!-- if:local -->
+
 Read the source PRD referenced in the plan header (`> Source PRD: ...`).
 
+<!-- end:local -->
+<!-- if:github -->
+
+Read the source PRD issue referenced in the plan body (`> Source PRD: #<number>`).
+
+<!-- end:github -->
+
 ### 3. Fast-path: check if implementation exists
 
 Before launching a subagent, check whether the primary module file(s) from Phase 1 exist. If none exist, skip the subagent entirely and report `0/N — not yet started`. List Phase 1's "Done when" items as next steps and jump to Step 5.
@@ -76,8 +111,17 @@ Collect findings into two categories:
 
 ### 3c. Update checkboxes
 
+<!-- if:local -->
+
 Using the subagent's report, update each checkbox in `.tracerkit/plans/<slug>.md` to `[x]` or `[ ]`.
 
+<!-- end:local -->
+<!-- if:github -->
+
+Using the subagent's report, update each checkbox in the plan issue body to `[x]` or `[ ]` by editing the issue.
+
+<!-- end:github -->
+
 ### 4. Determine outcome
 
 Based on checks and findings, decide the status transition:
@@ -112,8 +156,17 @@ Total: checked/total
 
 ### 6. Stamp the plan
 
+<!-- if:local -->
+
 Append a verdict block at the bottom of `.tracerkit/plans/<slug>.md`:
 
+<!-- end:local -->
+<!-- if:github -->
+
+Append a verdict block at the bottom of the plan issue body by editing the issue:
+
+<!-- end:github -->
+
 ```markdown
 ---
 
@@ -129,7 +182,11 @@ If a previous verdict block exists, replace it with the new one.
 
 ### 7. On `done` — archive
 
-If all checks pass and zero BLOCKERS, perform these steps in order:
+If all checks pass and zero BLOCKERS:
+
+<!-- if:local -->
+
+Perform these steps in order:
 
 1. Create directory `.tracerkit/archives/<slug>/`
 2. If `.tracerkit/prds/<slug>.md` exists:
@@ -145,6 +202,22 @@ If all checks pass and zero BLOCKERS, perform these steps in order:
 
 Tell the user: archived to `.tracerkit/archives/<slug>/`, one-line summary of the feature.
 
+<!-- end:local -->
+<!-- if:github -->
+
+Perform these steps in order:
+
+1. Update the PRD issue:
+   - Add `tk:done` label, remove `tk:in-progress` label
+   - Update the `<!-- tk:metadata -->` comment: set `status: done`, add `completed: <current UTC ISO 8601 timestamp>`
+2. Close the PRD issue with reason `completed`
+3. Close the plan issue with reason `completed`
+4. If there is a current PR associated with this work, reference it in a closing comment on the PRD issue
+
+Tell the user: issues closed (include issue numbers), one-line summary of the feature.
+
+<!-- end:github -->
+
 ### 8. On `in_progress` (no blockers)
 
 Show progress summary (checked/total per phase), list the next unchecked items to implement. Keep going.
@@ -164,5 +237,10 @@ List the blockers to fix, then re-run `/tk:check <slug>`.
 
 - Plan not found — list available plans and ask
 - PRD referenced in plan not found — warn and continue with plan checks only
+<!-- if:local -->
 - `.tracerkit/plans/` missing — tell user to run `/tk:plan` first
 - `.tracerkit/archives/<slug>/` already exists — warn and ask whether to remove it first
+  <!-- end:local -->
+  <!-- if:github -->
+- Issue update fails — report the error and suggest checking `gh auth status`
+<!-- end:github -->

package/skills/plan/SKILL.md

@@ -5,11 +5,28 @@ argument-hint: '[slug]'
 
 # PRD to Plan
 
-Break a PRD into phased vertical slices (tracer bullets). Output: `.tracerkit/plans/<slug>.md`.
+Break a PRD into phased vertical slices (tracer bullets).
+
+<!-- if:local -->
+
+Output: `.tracerkit/plans/<slug>.md`.
+
+<!-- end:local -->
+<!-- if:github -->
+
+Output: a GitHub Issue with label `{{github.labels.plan}}`.
+
+<!-- end:github -->
 
 ## Pre-loaded context
 
+<!-- if:local -->
+
 - Available PRDs: !`ls .tracerkit/prds/ 2>&1`
+  <!-- end:local -->
+  <!-- if:github -->
+- Available PRDs: list open GitHub Issues with label `{{github.labels.prd}}`
+<!-- end:github -->
 
 ## Input
 
@@ -21,16 +38,38 @@ Use the argument as `<slug>` if given. If no argument is provided, list availabl
 
 ### 1. Read the PRD
 
+<!-- if:local -->
+
 Read `.tracerkit/prds/<slug>.md`. If it does not exist, list available PRDs and ask.
 
 If `.tracerkit/plans/<slug>.md` already exists, tell the user and ask whether to overwrite or pick a new name.
 
+<!-- end:local -->
+<!-- if:github -->
+
+Find the PRD issue: search for an open GitHub Issue with label `{{github.labels.prd}}` and title matching `[{{github.labels.prd}}] <slug>:`. Read its body. If not found, list available PRD issues and ask.
+
+Search for an existing plan issue with label `{{github.labels.plan}}` and title matching `[{{github.labels.plan}}] <slug>:`. If found, tell the user and ask whether to update it or pick a new name.
+
+<!-- end:github -->
+
 ### 1b. Update PRD status
 
+<!-- if:local -->
+
 Update the YAML frontmatter in `.tracerkit/prds/<slug>.md` to `status: in_progress`. Change only the `status` field — do not touch any other frontmatter fields or the markdown content below the closing `---`.
 
 If the PRD has no frontmatter, skip this step silently.
 
+<!-- end:local -->
+<!-- if:github -->
+
+Update the PRD issue:
+
+- Remove `tk:created` label, add `tk:in-progress` label
+- Update the `<!-- tk:metadata -->` comment in the issue body to `status: in_progress`
+<!-- end:github -->
+
 ### 2. Explore the codebase
 
 Understand current architecture, existing patterns, and integration points. If you already have codebase context from a prior step in this conversation (e.g., you just ran `/tk:prd`), skip the exploration and note which context you're reusing.
@@ -97,13 +136,46 @@ Ask: Does the granularity feel right? Should any phases merge or split? Iterate
 
 ### 6. Save plan
 
+<!-- if:local -->
+
 Save to `.tracerkit/plans/<slug>.md` (create `.tracerkit/plans/` if missing).
 
 ```markdown
 # Plan: <Feature Name>
 
 > Source PRD: `.tracerkit/prds/<slug>.md`
+```
+
+<!-- end:local -->
+<!-- if:github -->
 
+Ensure the following labels exist (create if missing):
+
+- `{{github.labels.plan}}` — TracerKit implementation plan
+- `tk:in-progress` — Plan generated, implementation underway
+
+Create a GitHub Issue with:
+
+- **Title**: `[{{github.labels.plan}}] <slug>: Plan: <Feature Title>`
+- **Labels**: `{{github.labels.plan}}`, `tk:in-progress`
+- **Body**: the plan content below, with a source PRD reference by issue number
+
+```markdown
+<!-- tk:metadata
+source_prd: #<PRD issue number>
+slug: <slug>
+-->
+
+# Plan: <Feature Name>
+
+> Source PRD: #<PRD issue number>
+```
+
+<!-- end:github -->
+
+Use this structure for the plan body:
+
+```markdown
 ## Architectural Decisions
 
 Durable decisions that apply across all phases:
@@ -138,19 +210,38 @@ Carried forward from PRD verbatim.
 Gaps found in the PRD needing resolution. Blank if none.
 ```
 
+<!-- if:local -->
+
 Print saved path and one line per phase: `Phase N — <title> (<condition summary>)`. Then ask: "Run `/tk:check <slug>` when ready?"
 
+<!-- end:local -->
+<!-- if:github -->
+
+Print issue number/URL and one line per phase: `Phase N — <title> (<condition summary>)`. Then ask: "Run `/tk:check <slug>` when ready?"
+
+<!-- end:github -->
+
 ## Rules
 
 - Phases derive from PRD user stories — never invented
 - Each phase must be demoable end-to-end on its own
 - "Done when" must be a checkbox list of testable conditions, not prose
 - **Safety valve**: if a phase has >5 "Done when" items, stop and split it into smaller phases before continuing
+<!-- if:local -->
 - Never modify the source PRD content — only update frontmatter status fields
+  <!-- end:local -->
+  <!-- if:github -->
+- Never modify the source PRD content — only update metadata and labels
+<!-- end:github -->
 - Carry PRD's Out of Scope forward verbatim
 
 ## Error Handling
 
 - PRD not found — list available PRDs and ask
 - PRD missing sections — note gaps inline and continue
+<!-- if:local -->
 - `.tracerkit/plans/` missing — create it
+  <!-- end:local -->
+  <!-- if:github -->
+- Issue creation fails — report the error and suggest checking `gh auth status`
+<!-- end:github -->

package/skills/prd/SKILL.md

@@ -9,7 +9,13 @@ Skip steps already satisfied. If user provided a description via arguments, skip
 
 ## Pre-loaded context
 
+<!-- if:local -->
+
 - Existing PRDs: !`ls .tracerkit/prds/ 2>&1`
+  <!-- end:local -->
+  <!-- if:github -->
+- Existing PRDs: list open GitHub Issues with label `{{github.labels.prd}}`
+<!-- end:github -->
 
 ## Input
 
@@ -25,10 +31,21 @@ If the argument is provided, derive a slug using this exact algorithm:
 4. Take the first 4 remaining words (or fewer if less exist)
 5. Join with hyphens → `<slug>`
 
+<!-- if:local -->
+
 The output file is `.tracerkit/prds/<slug>.md`.
 
 If `.tracerkit/prds/<slug>.md` already exists, tell the user and ask whether to overwrite or pick a new name.
 
+<!-- end:local -->
+<!-- if:github -->
+
+The output is a GitHub Issue with label `{{github.labels.prd}}` and title `[{{github.labels.prd}}] <slug>: <Feature Title>`.
+
+Search for an existing open issue with title matching `[{{github.labels.prd}}] <slug>:`. If found, tell the user and ask whether to update it or pick a new slug.
+
+<!-- end:github -->
+
 ## Workflow
 
 ### 1. Gather problem description
@@ -84,6 +101,8 @@ Present modules to user. Confirm which need tests.
 
 ### 5. Write PRD
 
+<!-- if:local -->
+
 Save to `.tracerkit/prds/<slug>.md` (create `.tracerkit/prds/` if missing).
 
 ```markdown
@@ -94,6 +113,38 @@ status: created
 
 # Feature Name
 
+...
+```
+
+<!-- end:local -->
+<!-- if:github -->
+
+Ensure the following labels exist in the repository (create them if missing):
+
+- `{{github.labels.prd}}` — TracerKit PRD
+- `tk:created` — PRD written, no plan yet
+
+Create a GitHub Issue with:
+
+- **Title**: `[{{github.labels.prd}}] <slug>: <Feature Title>`
+- **Labels**: `{{github.labels.prd}}`, `tk:created`
+- **Body**: the PRD content below, with metadata in an HTML comment
+
+```markdown
+<!-- tk:metadata
+created: <current UTC timestamp, ISO 8601>
+status: created
+-->
+
+# Feature Name
+
+...
+```
+
+<!-- end:github -->
+
+Use this structure for the PRD body (same for both local file and issue body):
+
 ## Problem Statement
 
 The problem from the user's perspective. Focus on pain and impact.
@@ -155,11 +206,28 @@ Omit any section whose content would be "None required" — only include section
 ## Out of Scope
 
 Explicit list. Be specific — vague exclusions invite scope creep.
-```
+
+---
+
+<!-- if:local -->
 
 Tell the user: file created, one-line summary. Then ask: "Run `/tk:plan <slug>` next?"
 
+<!-- end:local -->
+<!-- if:github -->
+
+Tell the user: issue created (include issue number and URL), one-line summary. Then ask: "Run `/tk:plan <slug>` next?"
+
+<!-- end:github -->
+
 ## Error Handling
 
+<!-- if:local -->
+
 - `.tracerkit/prds/` missing — create it
+  <!-- end:local -->
+  <!-- if:github -->
+- Labels missing — create them before creating the issue
+- Issue creation fails — report the error and suggest checking `gh auth status`
+<!-- end:github -->
 - Scope larger than expected — surface and re-scope with user before continuing

package/dist/uninstall-BhTMOfMb.js

@@ -1,153 +0,0 @@
-import { existsSync as e, mkdirSync as t, readFileSync as n, readdirSync as r, rmSync as i, writeFileSync as a } from "node:fs";
-import { dirname as o, join as s } from "node:path";
-import { createHash as c } from "node:crypto";
-import { fileURLToPath as l } from "node:url";
-//#region src/config.ts
-var u = {
-	prds: ".tracerkit/prds",
-	plans: ".tracerkit/plans",
-	archives: ".tracerkit/archives"
-};
-function d(t) {
-	let r = s(t, ".tracerkit", "config.json");
-	if (!e(r)) return { paths: { ...u } };
-	let i, a;
-	try {
-		i = n(r, "utf8"), a = JSON.parse(i);
-	} catch {
-		throw Error("Invalid .tracerkit/config.json — expected valid JSON");
-	}
-	let o = typeof a.paths == "object" && a.paths !== null ? a.paths : {};
-	return { paths: {
-		prds: typeof o.prds == "string" ? o.prds : u.prds,
-		plans: typeof o.plans == "string" ? o.plans : u.plans,
-		archives: typeof o.archives == "string" ? o.archives : u.archives
-	} };
-}
-var f = [
-	"tk:brief",
-	"tk:prd",
-	"tk:plan",
-	"tk:check"
-], p = ["tk:verify"], m = {
-	force: "--force",
-	help: "--help",
-	version: "--version"
-}, h = [
-	"brief",
-	"progress",
-	"archive"
-], g = [
-	{
-		name: "init",
-		args: "[path]",
-		desc: "Install skills to ~/.claude/skills/ (or [path] if given)"
-	},
-	{
-		name: "update",
-		args: "[path]",
-		desc: "Refresh unchanged files from latest version, skip modified"
-	},
-	{
-		name: "uninstall",
-		args: "[path]",
-		desc: "Remove TracerKit skill directories, keep .tracerkit/ artifacts"
-	}
-], _ = s(o(l(import.meta.url)), "..", "skills");
-function v(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(...v(s(e, r.name), n)) : i.push(n);
-	}
-	return i.sort();
-}
-function y(e) {
-	return `.claude/skills/tk:${e}`;
-}
-function b(e) {
-	return e.slice(18);
-}
-function x(e, t) {
-	let n = e;
-	return t.paths.prds !== u.prds && (n = n.replaceAll(u.prds, t.paths.prds)), t.paths.plans !== u.plans && (n = n.replaceAll(u.plans, t.paths.plans)), t.paths.archives !== u.archives && (n = n.replaceAll(u.archives, t.paths.archives)), n;
-}
-function S(e, r, i) {
-	let c = i ?? v(_).map(y);
-	for (let i of c) {
-		let c = s(_, b(i)), l = s(e, i);
-		t(o(l), { recursive: !0 }), a(l, x(n(c, "utf8"), r));
-	}
-	return { copied: c };
-}
-function C(e) {
-	return c("sha256").update(e).digest("hex");
-}
-function w(t, r) {
-	let i = v(_).map(y), a = [], o = [], c = [];
-	for (let l of i) {
-		let i = s(t, l);
-		if (!e(i)) c.push(l);
-		else {
-			let e = x(n(s(_, b(l)), "utf8"), r);
-			C(Buffer.from(e)) === C(n(i)) ? a.push(l) : o.push(l);
-		}
-	}
-	return {
-		unchanged: a,
-		modified: o,
-		missing: c
-	};
-}
-//#endregion
-//#region src/commands/update.ts
-function T(t, n) {
-	if (!f.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — run `tracerkit init` first");
-	let r = d(t), { unchanged: a, modified: o, missing: c } = w(t, r), l = [];
-	for (let n of p) {
-		let r = s(t, ".claude", "skills", n);
-		e(r) && (i(r, {
-			recursive: !0,
-			force: !0
-		}), l.push(`✗ .claude/skills/${n}/ removed (deprecated)`));
-	}
-	let u = n?.force ?? !1, m = [
-		...a,
-		...c,
-		...u ? o : []
-	];
-	if (m.length > 0) {
-		S(t, r, m);
-		for (let e of a) l.push(`✓ ${e}`);
-		for (let e of c) l.push(`✓ ${e} (added)`);
-		if (u) for (let e of o) l.push(`✓ ${e} (replaced)`);
-	}
-	if (!u && o.length > 0) {
-		for (let e of o) l.push(`⚠ ${e} (skipped — modified)`);
-		l.push("", "Run `tracerkit update --force` to replace modified files with latest versions.");
-	}
-	return l;
-}
-//#endregion
-//#region src/commands/init.ts
-function E(t) {
-	if (f.some((n) => e(s(t, ".claude", "skills", n)))) return T(t);
-	let { copied: n } = S(t, d(t));
-	return n.map((e) => `✓ ${e}`);
-}
-//#endregion
-//#region src/commands/uninstall.ts
-function D(t) {
-	if (!f.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — nothing to uninstall");
-	let n = [];
-	for (let r of f) {
-		let a = s(t, ".claude", "skills", r);
-		e(a) && (i(a, {
-			recursive: !0,
-			force: !0
-		}), n.push(`✗ .claude/skills/${r}/ removed`));
-	}
-	return n;
-}
-//#endregion
-export { h as a, f as c, g as i, E as n, p as o, T as r, m as s, D as t };