tracerkit 1.12.0 → 1.13.0

package/README.md

@@ -94,14 +94,14 @@ 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:
+Same skills, same workflow. Storage is configured per-project:
 
 ```bash
-tracerkit init --storage github         # first install
+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. 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 instead of archived locally. Each project can use a different backend; local is the default. See [Configuration](docs/configuration.md) for details.
 
 </details>
 
@@ -140,7 +140,7 @@ Without arguments, shows a feature dashboard with status and progress before ask
 | Document                                         | Description                                        |
 | ------------------------------------------------ | -------------------------------------------------- |
 | [Examples](docs/examples.md)                     | Walk through end-to-end usage scenarios            |
-| [CLI Reference](docs/cli-reference.md)           | Lifecycle commands: init, update, uninstall        |
+| [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  |

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-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 { 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-9tiXr-15.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";
@@ -54,11 +54,11 @@ var { version: T } = JSON.parse(d(h(p(g(import.meta.url)), "..", "package.json")
 	"",
 	"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."
+	"init/update/uninstall default to the home directory when no path is given.",
+	"config defaults to the current working directory."
 ];
 function O(e) {
 	if (!e) return !1;
@@ -78,17 +78,14 @@ function A(e) {
 	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 "init": return o(k(r));
 		case "update": {
 			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));
+			let e = O(r[0]);
+			return v(e ? h(r[0]) : process.cwd(), e ? r.slice(1) : r);
 		}
 		case "uninstall": return l(k(r));
 		default: return D;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as e, l as t, n, r, s as i, t as a } from "./uninstall-BkaWoWd0.js";
+import { a as e, l as t, n, r, s as i, t as a } from "./uninstall-9tiXr-15.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 → uninstall-9tiXr-15.js}

@@ -3,20 +3,20 @@ 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 = {
+var u = "local", d = [u, "github"], f = {
 	prds: ".tracerkit/prds",
 	plans: ".tracerkit/plans",
 	archives: ".tracerkit/archives"
-}, m = { labels: {
+}, p = { labels: {
 	prd: "tk:prd",
 	plan: "tk:plan"
 } };
-function h(t) {
+function m(t) {
 	let r = s(t, ".tracerkit", "config.json");
 	if (!e(r)) return {
 		storage: u,
-		paths: { ...p },
-		github: { ...m }
+		paths: { ...f },
+		github: { ...p }
 	};
 	let i;
 	try {
@@ -25,33 +25,33 @@ function h(t) {
 		throw Error("Invalid .tracerkit/config.json — expected valid JSON");
 	}
 	return {
-		storage: g(i.storage),
-		paths: _(i.paths),
-		github: v(i.github)
+		storage: h(i.storage),
+		paths: g(i.paths),
+		github: _(i.github)
 	};
 }
-function g(e) {
-	return typeof e == "string" && f.includes(e) ? e : u;
+function h(e) {
+	return typeof e == "string" && d.includes(e) ? e : u;
 }
-function _(e) {
-	let t = x(e) ? e : {};
+function g(e) {
+	let t = b(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
+		prds: typeof t.prds == "string" ? t.prds : f.prds,
+		plans: typeof t.plans == "string" ? t.plans : f.plans,
+		archives: typeof t.archives == "string" ? t.archives : f.archives
 	};
 }
-function v(e) {
-	let t = x(e) ? e : {}, n = x(t.labels) ? t.labels : {};
+function _(e) {
+	let t = b(e) ? e : {}, n = b(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
+			prd: typeof n.prd == "string" ? n.prd : p.labels.prd,
+			plan: typeof n.plan == "string" ? n.plan : p.labels.plan
 		}
 	};
 }
-function y(r, i) {
+function v(r, i) {
 	let c = s(r, ".tracerkit", "config.json");
 	t(o(c), { recursive: !0 });
 	let l = {};
@@ -60,32 +60,31 @@ function y(r, i) {
 	} catch {
 		l = {};
 	}
-	let u = b(l, i);
+	let u = y(l, i);
 	a(c, JSON.stringify(u, null, 2) + "\n");
 }
-function b(e, t) {
+function y(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];
+	for (let e of Object.keys(t)) b(n[e]) && b(t[e]) ? n[e] = y(n[e], t[e]) : n[e] = t[e];
 	return n;
 }
-function x(e) {
+function b(e) {
 	return typeof e == "object" && !!e && !Array.isArray(e);
 }
-var S = [
+var x = [
 	"tk:brief",
 	"tk:prd",
 	"tk:plan",
 	"tk:check"
-], C = ["tk:verify"], w = {
+], S = ["tk:verify"], C = {
 	force: "--force",
 	help: "--help",
-	storage: "--storage",
 	version: "--version"
-}, T = [
+}, w = [
 	"brief",
 	"progress",
 	"archive"
-], E = [
+], T = [
 	{
 		name: "init",
 		args: "[path]",
@@ -106,46 +105,44 @@ var S = [
 		args: "[path]",
 		desc: "Remove TracerKit skill directories, keep .tracerkit/ artifacts"
 	}
-], D = s(o(l(import.meta.url)), "..", "skills");
-function O(e, t = "") {
+], E = s(o(l(import.meta.url)), "..", "skills");
+function D(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);
+		r.isDirectory() ? i.push(...D(s(e, r.name), n)) : i.push(n);
 	}
 	return i.sort();
 }
-function k(e) {
+function O(e) {
 	return `.claude/skills/tk:${e}`;
 }
-function A(e) {
+function k(e) {
 	return e.slice(18);
 }
-function j(e, t) {
+function A(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;
+	return t.paths.prds !== f.prds && (n = n.replaceAll(f.prds, t.paths.prds)), t.paths.plans !== f.plans && (n = n.replaceAll(f.plans, t.paths.plans)), t.paths.archives !== f.archives && (n = n.replaceAll(f.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;
 }
-function M(e, r, i) {
-	let c = i ?? O(D).map(k);
+function j(e, r, i) {
+	let c = i ?? D(E).map(O);
 	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));
+		let c = s(E, k(i)), l = s(e, i);
+		t(o(l), { recursive: !0 }), a(l, A(n(c, "utf8"), r));
 	}
 	return { copied: c };
 }
-function N(e) {
+function M(e) {
 	return c("sha256").update(e).digest("hex");
 }
-function P(t, r) {
-	let i = O(D).map(k), a = [], o = [], c = [];
+function N(t, r) {
+	let i = D(E).map(O), 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);
+			let e = A(n(s(E, k(l)), "utf8"), r);
+			M(Buffer.from(e)) === M(n(i)) ? a.push(l) : o.push(l);
 		}
 	}
 	return {
@@ -156,10 +153,10 @@ function P(t, r) {
 }
 //#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) {
+function P(t, n) {
+	if (!x.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — run `tracerkit init` first");
+	let r = m(t), { unchanged: a, modified: o, missing: c } = N(t, r), l = [];
+	for (let n of S) {
 		let r = s(t, ".claude", "skills", n);
 		e(r) && (i(r, {
 			recursive: !0,
@@ -172,7 +169,7 @@ function F(t, n) {
 		...u ? o : []
 	];
 	if (d.length > 0) {
-		M(t, r, d);
+		j(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)`);
@@ -185,18 +182,17 @@ function F(t, n) {
 }
 //#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}`);
+function F(t) {
+	if (x.some((n) => e(s(t, ".claude", "skills", n)))) return P(t, { force: !1 });
+	let { copied: n } = j(t, m(t));
+	return n.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");
+function I(t) {
+	if (!x.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — nothing to uninstall");
 	let n = [];
-	for (let r of S) {
+	for (let r of x) {
 		let a = s(t, ".claude", "skills", r);
 		e(a) && (i(a, {
 			recursive: !0,
@@ -206,4 +202,4 @@ function L(t) {
 	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 };
+export { T as a, C as c, m as d, v as f, j as i, x as l, F as n, w as o, P as r, S as s, I as t, u };

package/package.json

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

package/skills/brief/SKILL.md

@@ -2,9 +2,11 @@
 description: Session briefing — shows active features, progress, and suggested focus. Use at the start of a session to orient.
 ---
 
+**Config**: read `.tracerkit/config.json` (default: `local`). Follow matching `<!-- if:local/github -->` blocks. GitHub: use `github.repo` from config or git remote.
+
 # Session Briefing
 
-Get a quick overview of all active features, their progress, and what to focus on next.
+Overview of active features, progress, and suggested focus.
 
 ## Pre-loaded context
 
@@ -18,23 +20,16 @@ Get a quick overview of all active features, their progress, and what to focus o
 
 ## Algorithm
 
-Follow these steps exactly to build the briefing table:
-
 ### 1. Discover features
 
 <!-- if:local -->
 
-For each `.md` file in `.tracerkit/prds/`:
+For each `.md` file in `.tracerkit/prds/`: parse frontmatter, extract `status` and `created`. Skip `status: done`. Slug = filename without `.md`.
 
-1. Read the file
-2. Parse YAML frontmatter (the block between `---` fences at the top)
-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}}`:
+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
@@ -47,38 +42,22 @@ For each `.md` file in `.tracerkit/prds/`:
 
 <!-- if:local -->
 
-For each slug, check if `.tracerkit/plans/<slug>.md` exists. If it does:
-
-1. Read the plan file
-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.
+For each slug with a plan at `.tracerkit/plans/<slug>.md`:
 
-If no plan exists, progress is `—` and next is `—`.
+Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Sum → `checked/total`. First unchecked item → "Next" (strip trailing `[tag]`). No plan → `—`.
 
 <!-- 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:
+For each slug, find plan issue with label `{{github.labels.plan}}` and matching title. 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 `—`.
+Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Sum → `checked/total`. First unchecked item → "Next" (strip trailing `[tag]`). No plan → `—`.
 
 <!-- end:github -->
 
 ### 3. Build the table
 
-Sort features by `created` date ascending (no-date entries last). Calculate age from `created`:
+Sort by `created` ascending (no-date last). Age from `created`:
 
 - < 7 days → `Nd` (e.g. `3d`)
 - < 30 days → `Nw` (e.g. `2w`)
@@ -110,14 +89,13 @@ Append below the table:
 
 ### 5. Offer next steps
 
-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)
+Options: continue focused feature (read plan at `.tracerkit/plans/<slug>.md`), `/tk:prd` for new feature, `/tk:check <slug>` for progress.
+
+<!-- end:local -->
+<!-- if:github -->
+
+Options: continue focused feature (read plan issue), `/tk:prd` for new feature, `/tk:check <slug>` for progress.
+
 <!-- end:github -->
-- Start a new feature with `/tk:prd`
-- Check progress on a feature with `/tk:check <slug>`

package/skills/check/SKILL.md

@@ -3,6 +3,8 @@ description: Verify implementation against plan. Shows progress, finds blockers,
 argument-hint: '[slug]'
 ---
 
+**Config**: read `.tracerkit/config.json` (default: `local`). Follow matching `<!-- if:local/github -->` blocks. GitHub: use `github.repo` from config or git remote.
+
 # Check Implementation
 
 Check implementation against a plan. Update checks, stamp findings, transition status, and archive when done.
@@ -48,18 +50,11 @@ 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 -->
 
-After the table, ask which feature to verify.
+Ask which feature to verify.
 
 ## Progress Algorithm
 
-To count progress for a plan file:
-
-1. Find every `## Phase N` heading (regex: `^## Phase \d+`)
-2. Within each phase section (until the next `## ` heading), count:
-   - Checked: lines matching `^- \[x\] ` (case-insensitive)
-   - Unchecked: lines matching `^- \[ \] `
-3. Per-phase output: `  Phase N — title: checked/total`
-4. Sum across all phases → `Total: checked/total`
+Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Per-phase: `Phase N — title: checked/total`. Sum → `Total: checked/total`.
 
 ## Workflow
 
@@ -67,12 +62,12 @@ To count progress for a plan file:
 
 <!-- if:local -->
 
-Read `.tracerkit/plans/<slug>.md`. If it does not exist, list available plans and ask.
+Read `.tracerkit/plans/<slug>.md`. If missing, list 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.
+Find plan issue: open issue with label `{{github.labels.plan}}`, title matching `[{{github.labels.plan}}] <slug>:`. If missing, list plans and ask.
 
 <!-- end:github -->
 
@@ -80,18 +75,18 @@ Find the plan issue: search for an open GitHub Issue with label `{{github.labels
 
 <!-- if:local -->
 
-Read the source PRD referenced in the plan header (`> Source PRD: ...`).
+Read source PRD referenced in plan header (`> Source PRD: ...`).
 
 <!-- end:local -->
 <!-- if:github -->
 
-Read the source PRD issue referenced in the plan body (`> Source PRD: #<number>`).
+Read source PRD issue referenced in 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.
+If primary module file(s) from Phase 1 don't exist, skip subagent — report `0/N — not yet started`, list Phase 1 done-when items, jump to Step 5.
 
 ### 3b. Launch read-only review
 
@@ -132,7 +127,7 @@ Based on checks and findings, decide the status transition:
 
 ### 5. Report to user
 
-Count progress per phase using the Progress Algorithm above, then print the verdict report:
+Count progress per phase (Progress Algorithm), then print:
 
 ```markdown
 ## Verification: <slug>
@@ -186,35 +181,19 @@ 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:
-   - Read the PRD file
-   - In the YAML frontmatter (between `---` fences), find the `status:` line and replace its value with `done`. If no `status:` line exists, add `status: done` as a new line inside the frontmatter block.
-   - Add a `completed: <current UTC ISO 8601 timestamp>` line inside the frontmatter block (e.g. `completed: 2025-06-15T14:30:00Z`)
-   - Write the updated content to `.tracerkit/archives/<slug>/prd.md`
-3. Read `.tracerkit/plans/<slug>.md`
-   - Append to the end: `\n## Archived\n\nArchived on YYYY-MM-DD.\n`
-   - Write the result to `.tracerkit/archives/<slug>/plan.md`
-4. Delete `.tracerkit/prds/<slug>.md` (if it exists)
-5. Delete `.tracerkit/plans/<slug>.md`
+Archive to `.tracerkit/archives/<slug>/`:
 
-Tell the user: archived to `.tracerkit/archives/<slug>/`, one-line summary of the feature.
+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
 
 <!-- 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.
+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
 
 <!-- end:github -->
 
@@ -232,15 +211,3 @@ List the blockers to fix, then re-run `/tk:check <slug>`.
 - The only file writes this skill makes are: checkboxes + verdict block in the plan, and the archive steps 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)
-
-## Error Handling
-
-- 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

@@ -1,8 +1,10 @@
 ---
-description: Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved to .tracerkit/plans/. Use after /tk:prd.
+description: Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices. Use after /tk:prd.
 argument-hint: '[slug]'
 ---
 
+**Config**: read `.tracerkit/config.json` (default: `local`). Follow matching `<!-- if:local/github -->` blocks. GitHub: use `github.repo` from config or git remote.
+
 # PRD to Plan
 
 Break a PRD into phased vertical slices (tracer bullets).
@@ -32,7 +34,7 @@ Output: a GitHub Issue with label `{{github.labels.plan}}`.
 
 The argument (if provided) is: $ARGUMENTS
 
-Use the argument as `<slug>` if given. If no argument is provided, list available PRDs and ask which one to plan.
+Use argument as `<slug>`. If empty, list available PRDs and ask.
 
 ## Workflow
 
@@ -40,16 +42,12 @@ Use the argument as `<slug>` if given. If no argument is provided, list availabl
 
 <!-- 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.
+Read `.tracerkit/prds/<slug>.md`. If missing, list PRDs and ask. If `.tracerkit/plans/<slug>.md` exists, ask: overwrite or 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.
+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?
 
 <!-- end:github -->
 
@@ -57,9 +55,7 @@ Search for an existing plan issue with label `{{github.labels.plan}}` and title
 
 <!-- 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.
+Set `status: in_progress` in `.tracerkit/prds/<slug>.md` frontmatter. Change only `status`.
 
 <!-- end:local -->
 <!-- if:github -->
@@ -72,9 +68,9 @@ Update the PRD issue:
 
 ### 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.
+Map architecture, patterns, integration points. Skip if codebase context exists from prior step.
 
-**Research protocol**: codebase first, then project docs. If you cannot verify a technical claim from these sources, flag it as uncertain — never fabricate.
+**Research protocol**: codebase first, then docs. Unverifiable claims → flag as uncertain, never fabricate.
 
 ### 3. Identify durable architectural decisions
 
@@ -88,7 +84,7 @@ Before slicing, extract decisions that hold across all phases:
 
 ### 4. Draft vertical slices
 
-Each phase is a thin **tracer bullet** — a narrow but complete path through every integration layer (schema, service, API, UI, tests). A completed phase is demoable on its own.
+Each phase: thin vertical slice through all layers (schema → service → API → UI → tests). Demoable alone.
 
 **Deriving tasks from the PRD:**
 
@@ -106,9 +102,9 @@ Each phase is a thin **tracer bullet** — a narrow but complete path through ev
 
 **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:** write as a checkbox list of atomic, verifiable conditions — not prose. Each item must pass this test: _"Can an agent verify this by reading files, running a command, or checking a test result — with no subjective judgment?"_ Bad: "API is clean". Good: "`GET /api/revenue` returns `{ total: number }`". The agent marks `[x]` during implementation to track progress.
+**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.
 
-**When to use layer-by-layer instead:** If the PRD has complex schema changes that all modules depend on and no single user story can stand alone without the full schema, build the data foundation first, then slice the rest vertically.
+**Layer-by-layer exception:** if complex schema changes underpin all modules and no story stands alone, build data foundation first, then slice vertically.
 
 **Phase count thresholds:**
 
@@ -126,19 +122,13 @@ Assign an agent tag to tasks where appropriate:
 
 ### 5. Quiz the user
 
-Present the breakdown. For each phase show:
-
-- **Title**: short goal phrase
-- **User stories covered**: which PRD stories this addresses
-- **Done when**: the testable condition
-
-Ask: Does the granularity feel right? Should any phases merge or split? Iterate until approved.
+Present breakdown (title, user stories covered, done-when per phase). Ask: granularity right? Merge or split? Iterate until approved.
 
 ### 6. Save plan
 
 <!-- if:local -->
 
-Save to `.tracerkit/plans/<slug>.md` (create `.tracerkit/plans/` if missing).
+Save to `.tracerkit/plans/<slug>.md` (create dir if missing).
 
 ```markdown
 # Plan: <Feature Name>
@@ -149,16 +139,9 @@ Save to `.tracerkit/plans/<slug>.md` (create `.tracerkit/plans/` if missing).
 <!-- end:local -->
 <!-- if:github -->
 
-Ensure the following labels exist (create if missing):
+Ensure labels exist: `{{github.labels.plan}}`, `tk:in-progress` (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
+Create GitHub Issue — title: `[{{github.labels.plan}}] <slug>: Plan: <Feature Title>`, labels: `{{github.labels.plan}}`, `tk:in-progress`.
 
 ```markdown
 <!-- tk:metadata
@@ -210,16 +193,7 @@ 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 -->
+Print one line per phase: `Phase N — <title> (<condition summary>)`. Then ask: "Run `/tk:check <slug>` when ready?"
 
 ## Rules
 
@@ -234,14 +208,3 @@ Print issue number/URL and one line per phase: `Phase N — <title> (<condition
 - 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

@@ -1,11 +1,13 @@
 ---
-description: Create a PRD through user interview, codebase exploration, and module design, saved to .tracerkit/prds/. Use when starting a new feature or change.
+description: Create a PRD through user interview, codebase exploration, and module design. Use when starting a new feature or change.
 argument-hint: <idea>
 ---
 
+**Config**: read `.tracerkit/config.json` (default: `local`). Follow matching `<!-- if:local/github -->` blocks. GitHub: use `github.repo` from config or git remote.
+
 # PRD Writing
 
-Skip steps already satisfied. If user provided a description via arguments, skip to Step 2.
+Skip satisfied steps. If argument provided, skip to Step 2.
 
 ## Pre-loaded context
 
@@ -21,9 +23,7 @@ Skip steps already satisfied. If user provided a description via arguments, skip
 
 The argument is: $ARGUMENTS
 
-If the argument is empty, go straight to Step 1 (gather problem description). After gathering the idea, derive the slug from the idea.
-
-If the argument is provided, derive a slug using this exact algorithm:
+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
@@ -33,16 +33,12 @@ If the argument is provided, derive a slug using this exact algorithm:
 
 <!-- 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.
+Output: `.tracerkit/prds/<slug>.md`. If exists, ask: overwrite or 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.
+Output: GitHub Issue with label `{{github.labels.prd}}`, title `[{{github.labels.prd}}] <slug>: <Feature Title>`. If matching issue exists, ask: update or new slug?
 
 <!-- end:github -->
 
@@ -54,180 +50,86 @@ Ask the user for a detailed description of the problem and any solution ideas.
 
 ### 2. Explore codebase
 
-Verify assertions and map current state: data models, services, API routes, frontend structure, and test patterns. Note what exists vs. what must be built.
+Map current state: data models, services, API routes, frontend, tests. Note exists vs. must build.
 
-**Research protocol**: codebase first, then project docs. If you cannot verify a technical claim from these sources, flag it as uncertain — never fabricate.
+**Research protocol**: codebase first, then docs. Unverifiable claims → flag as uncertain, never fabricate.
 
 ### 3. Interview
 
-Interview relentlessly, one question at a time. Lead with your recommended answer; let the user confirm or correct. If a question can be answered by exploring code, explore instead of asking. For terse answers, offer concrete options (A/B/C).
+One question at a time. Lead with your recommended answer. Explore code instead of asking when possible. Offer A/B/C for terse answers.
 
-Walk these branches. **Skip rule**: skip a branch when the project type makes it irrelevant (e.g., skip Display/Access/Navigation for CLIs and libraries) AND the user's idea does not mention it.
+| Branch           | Key questions                           | Skip when                        |
+| ---------------- | --------------------------------------- | -------------------------------- |
+| Scope & Surface  | Where? New page or integrated? Roles?   | CLI/library, no new entry points |
+| Data & Concepts  | Definitions, existing vs missing data   | Never skip                       |
+| Behavior         | Interaction patterns, filtering, search | No user-facing behavior          |
+| Display          | Numbers, tables, charts, exports        | No UI                            |
+| Access & Privacy | Who sees what? Sensitive data?          | Single-user, no auth             |
+| Boundaries       | Out of scope, deferred features         | Never skip                       |
+| Integration      | Schema, services, external deps         | Self-contained change            |
 
-- **Scope & Surface** — Where does this live? New page/view or integrated? Which user roles? _Skip if_: single-surface project (CLI, library) with no new entry points.
-- **Data & Concepts** — Precise definitions for each new concept. What data exists, what's missing? _Never skip_ — every feature has data.
-- **Behavior & Interaction** — How does the user interact? Sorting, filtering, search, time ranges? _Skip if_: feature is purely internal/backend with no user-facing behavior change.
-- **Display & Output** — Numbers, tables, charts, forms? Exportable? URL-driven state? _Skip if_: no UI or formatted output involved.
-- **Access & Privacy** — Who sees what? Role-based restrictions? Sensitive data concerns? _Skip if_: single-user project with no auth layer.
-- **Boundaries** — What is explicitly out of scope? Adjacent features to defer? _Never skip_ — scope control prevents creep.
-- **Integration** — Schema changes? New or extended services? External dependencies? _Skip if_: self-contained change touching no external systems or storage.
+### 3b. Gray areas
 
-### 3b. Gray area checkpoint
-
-Before continuing, scan the interview for gray areas. Something is a gray area if any of these are true:
-
-- **Vague answer**: user said "maybe", "probably", "I think", or gave a one-word answer to a multi-part question
-- **Contradiction**: two answers conflict (e.g., "no auth needed" but "only admins can access")
-- **Unstated assumption**: you filled in a detail the user never confirmed
-- **Ambiguous scope**: a feature boundary is unclear (could be in or out of scope)
-
-Present as a numbered list:
-
-```
-Gray areas found:
-1. <ambiguity> — assumed <X>, confirm?
-2. <ambiguity> — two options: A or B
-```
-
-If the list is empty, say "No gray areas found" and move on. Otherwise, resolve each item with the user before proceeding.
+Surface ambiguities, contradictions, unstated assumptions. Present numbered list. Resolve all before continuing.
 
 ### 4. Design modules
 
-Sketch major modules to build or modify. Favor **deep modules** — a simple interface (1–3 entry points) hiding a large implementation that rarely changes, over shallow modules where the interface is nearly as complex as the implementation.
+Sketch modules. Favor **deep modules** — simple interface (1-3 entry points) hiding large implementation over shallow modules where interface ≈ implementation.
 
-Signals of shallow design: many small functions with 1:1 query mapping, callers compose multiple calls, adding a feature requires changing the interface.
+Shallow signals: many small 1:1 functions, callers compose multiple calls, feature changes require interface changes.
 
-Present modules to user. Confirm which need tests.
+Present modules. Confirm which need tests.
 
 ### 5. Write PRD
 
 <!-- if:local -->
 
-Save to `.tracerkit/prds/<slug>.md` (create `.tracerkit/prds/` if missing).
+Save to `.tracerkit/prds/<slug>.md` (create dir if missing).
 
 ```markdown
 ---
-created: <current UTC timestamp, ISO 8601, e.g. 2025-06-15T14:30:00Z>
+created: <UTC ISO 8601>
 status: created
 ---
 
 # Feature Name
-
-...
 ```
 
 <!-- end:local -->
 <!-- if:github -->
 
-Ensure the following labels exist in the repository (create them if missing):
+Ensure labels exist: `{{github.labels.prd}}`, `tk:created` (create 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
+Create GitHub Issue — title: `[{{github.labels.prd}}] <slug>: <Feature Title>`, labels: `{{github.labels.prd}}`, `tk:created`.
 
 ```markdown
 <!-- tk:metadata
-created: <current UTC timestamp, ISO 8601>
+created: <UTC ISO 8601>
 status: created
 -->
 
 # Feature Name
-
-...
 ```
 
 <!-- end:github -->
 
-Use this structure for the PRD body (same for both local file and issue body):
+PRD body structure (same for local file and issue body). Omit empty sections. No file paths or code snippets.
 
+```
 ## Problem Statement
-
-The problem from the user's perspective. Focus on pain and impact.
-
-## Current State
-
-What exists today that this feature changes or builds on. Skip for greenfield.
-
-- Relevant modules, services, or UI surfaces already in place
-- Current behavior the user experiences
-- Known limitations or workarounds
-
-## Solution
-
-The solution from the user's perspective. Describe the experience, not the architecture.
-
-## User Stories
-
-Long numbered list. Cover happy path, edge cases, error states.
-
-1. As a <actor>, I want <feature>, so that <benefit>
-
+## Current State (skip if greenfield)
+## Solution (user experience, not architecture)
+## User Stories (numbered, cover happy + edge + error)
 ## Implementation Decisions
-
-### New Modules
-
-- Module name, purpose, and public interface (function signatures with param types)
-- Why each module exists as a separate unit
-
-### Architectural Decisions
-
-- Key definitions (precise meaning of domain terms)
-- Data flow from storage to display
-- State management approach
-
+### New Modules (name, purpose, interface signatures)
+### Architectural Decisions (definitions, data flow, state)
 ### Schema Changes
-
-- New tables/columns needed, or "None required"
-
 ### API Contracts
-
-- New routes, request/response shapes
-
 ### Navigation
-
-- Where the feature is accessed, new routes added
-
-Do NOT include file paths or code snippets — they go stale.
-
-Omit any section whose content would be "None required" — only include sections with actual content.
-
-## Testing Decisions
-
-- What makes a good test (behavior, not implementation)
-- Which modules need tests
-- Key test cases (empty state, boundaries, isolation)
-- Prior art: similar test patterns in the codebase
-
-## Out of Scope
-
-Explicit list. Be specific — vague exclusions invite scope creep.
+## Testing Decisions (behavior tests, key cases, prior art)
+## Out of Scope (be specific)
+```
 
 ---
 
-<!-- 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
+Then ask: "Run `/tk:plan <slug>` next?"