tracerkit 1.7.0 → 1.8.0

package/README.md

@@ -10,7 +10,7 @@
 
 Replace ad-hoc AI prompts with a repeatable spec-driven workflow: from idea to verified, archived code.
 
-Named after the tracer-bullet technique from _The Pragmatic Programmer_ — **Tracer** + **Kit**.
+Named after the tracer-bullet technique from _The Pragmatic Programmer_: **Tracer** + **Kit**.
 
 **Zero runtime dependencies.** Pure Markdown skills, no build step.
 
@@ -18,7 +18,7 @@ Named after the tracer-bullet technique from _The Pragmatic Programmer_ — **Tr
 
 ## Why TracerKit?
 
-Without specs, every AI session starts from scratch — vague prompts, duplicated context, no way to confirm "done." Most planning tools produce flat task lists where nothing works until everything is done.
+Without specs, every AI session starts from scratch. Vague prompts, duplicated context, no way to confirm "done." Most planning tools produce flat task lists where nothing works until everything is done.
 
 TracerKit takes a different approach: **tracer-bullet vertical slices**. Each phase cuts through every layer (schema → service → API → UI → tests), so every phase is demoable on its own. Integration problems surface early, context stays focused, and AI assistants get small, well-scoped phases instead of sprawling layers.
 
@@ -36,17 +36,19 @@ Skills are installed globally to `~/.claude/skills/`, available in every project
 
 ```
 You: /tk:prd add dark mode support
-AI:  ✓ Written .tracerkit/prds/dark-mode-support.md
+AI:  Written .tracerkit/prds/dark-mode-support.md
+     Run `/tk:plan dark-mode-support` next?
 
 You: /tk:plan dark-mode-support
-AI:  ✓ Phase 1 — CSS variables + ThemeProvider
-     ✓ Phase 2 — Toggle component + localStorage
-     ✓ Written .tracerkit/plans/dark-mode-support.md
+AI:  Phase 1 — Theme visible end-to-end
+     Phase 2 — User can toggle and persist preference
+     Written .tracerkit/plans/dark-mode-support.md
+     Run `/tk:check dark-mode-support` when ready?
 
-You: # implement each phase...
+You: # open the plan, implement each phase, write tests...
 
 You: /tk:check dark-mode-support
-AI:  ✓ All checks verified — status: done
+AI:  Status: done | Total: 5/5
      Archived to .tracerkit/archives/dark-mode-support/
 ```
 
@@ -97,7 +99,7 @@ Without arguments, shows a feature dashboard with status and progress before ask
 | [CLI Reference](docs/cli-reference.md)           | Browse all CLI commands and flags                  |
 | [Configuration](docs/configuration.md)           | Configure custom artifact paths via `config.json`  |
 | [Metadata Lifecycle](docs/metadata-lifecycle.md) | Understand YAML frontmatter states and transitions |
-| [Compared to](docs/compared-to.md)               | Compare TracerKit to Spec Kit, Kiro, and OpenSpec  |
+| [Comparison](docs/comparison.md)                 | Compare TracerKit to Spec Kit, Kiro, and OpenSpec  |
 
 ## Contributing
 

package/dist/bin.js

@@ -1,16 +1,28 @@
 #!/usr/bin/env node
-import { n as e, o as t, r as n, t as r } from "./uninstall-Dri3LFXP.js";
-import { existsSync as i, mkdirSync as a, readFileSync as o, rmSync as s, unlinkSync as c, writeFileSync as l } from "node:fs";
-import { dirname as u, join as d, resolve as f } from "node:path";
-import { fileURLToPath as p } from "node:url";
-import { homedir as m } from "node:os";
+import { i as e, n as t, r as n, s as r, t as i } from "./uninstall-DO2YpTSz.js";
+import { existsSync as a, mkdirSync as o, readFileSync as s, readdirSync as c, rmSync as l, unlinkSync as u, writeFileSync as d } from "node:fs";
+import { dirname as f, join as p, resolve as m } from "node:path";
+import { fileURLToPath as h } from "node:url";
+import { homedir as g } from "node:os";
 //#region src/frontmatter.ts
-var h = /^---\n([\s\S]*?)\n---(?:\n|$)/;
-function g(e) {
+var _ = /^---\n([\s\S]*?)\n---(?:\n|$)/;
+function v(e) {
 	return e.replace(/\r\n/g, "\n");
 }
-function _(e, t, n) {
-	let r = g(e), i = r.match(h);
+function y(e) {
+	let t = v(e).match(_);
+	if (!t) return {};
+	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 n;
+}
+function b(e, t, n) {
+	let r = v(e), i = r.match(_);
 	if (!i) return `---\n${t}: ${n}\n---\n${r}`;
 	let a = i[1].split("\n"), o = RegExp(`^${t}\\s*:`), s = a.findIndex((e) => o.test(e));
 	s === -1 ? a.push(`${t}: ${n}`) : a[s] = `${t}: ${n}`;
@@ -19,21 +31,21 @@ function _(e, t, n) {
 }
 //#endregion
 //#region src/commands/archive.ts
-function v(e, n) {
-	let r = t(e), u = d(e, r.paths.prds, `${n}.md`), f = d(e, r.paths.plans, `${n}.md`), p = d(e, r.paths.archives, n), m = i(u);
-	if (!i(f)) throw Error(`Plan "${n}" not found at ${f}`);
-	if (i(p)) throw Error(`Archive "${n}" already exists at ${p}`);
-	a(p, { recursive: !0 });
+function x(e, t) {
+	let n = r(e), i = p(e, n.paths.prds, `${t}.md`), c = p(e, n.paths.plans, `${t}.md`), f = p(e, n.paths.archives, t), m = a(i);
+	if (!a(c)) throw Error(`Plan "${t}" not found at ${c}`);
+	if (a(f)) throw Error(`Archive "${t}" already exists at ${f}`);
+	o(f, { recursive: !0 });
 	try {
-		let e = (/* @__PURE__ */ new Date()).toISOString(), t = [];
+		let e = (/* @__PURE__ */ new Date()).toISOString(), r = [];
 		if (m) {
-			let t = o(u, "utf8");
-			t = _(t, "status", "done"), t = _(t, "completed", e), l(d(p, "prd.md"), t);
-		} else t.push(`Warning: PRD "${n}" missing, archiving plan only`);
-		let i = o(f, "utf8");
-		return i += `\n## Archived\n\nArchived on ${e.slice(0, 10)}.\n`, l(d(p, "plan.md"), i), m && c(u), c(f), t.push(`Archived "${n}" to ${r.paths.archives}/${n}/`), m && t.push(`  prd.md  — status: done, completed: ${e}`), t.push("  plan.md — archived block appended"), t;
+			let t = s(i, "utf8");
+			t = b(t, "status", "done"), t = b(t, "completed", e), d(p(f, "prd.md"), t);
+		} else r.push(`Warning: PRD "${t}" missing, archiving plan only`);
+		let a = s(c, "utf8");
+		return a += `\n## Archived\n\nArchived on ${e.slice(0, 10)}.\n`, d(p(f, "plan.md"), a), m && u(i), u(c), r.push(`Archived "${t}" to ${n.paths.archives}/${t}/`), m && r.push(`  prd.md  — status: done, completed: ${e}`), r.push("  plan.md — archived block appended"), r;
 	} catch (e) {
-		throw s(p, {
+		throw l(f, {
 			recursive: !0,
 			force: !0
 		}), e;
@@ -41,11 +53,11 @@ function v(e, n) {
 }
 //#endregion
 //#region src/plan.ts
-var y = /^## (Phase \d+\s*.*)$/, b = /^- \[x\] /i, x = /^- \[ \] /;
-function S(e) {
+var S = /^## (Phase \d+\s*.*)$/, C = /^- \[x\] /i, w = /^- \[ \] /;
+function T(e) {
 	let t = e.replace(/\r\n/g, "\n").split("\n"), n = [], r = null;
 	for (let e of t) {
-		let t = e.trimStart(), i = t.match(y);
+		let t = e.trimStart(), i = t.match(S);
 		if (t.startsWith("## ")) {
 			i ? (r = {
 				title: i[1].trim(),
@@ -54,32 +66,80 @@ function S(e) {
 			}, n.push(r)) : r = null;
 			continue;
 		}
-		r && (b.test(t) ? (r.checked++, r.total++) : x.test(t) && r.total++);
+		r && (C.test(t) ? (r.checked++, r.total++) : w.test(t) && r.total++);
 	}
 	return { phases: n };
 }
 //#endregion
+//#region src/commands/brief.ts
+var E = /^- \[ \] (.+)/;
+function D(e, t) {
+	let n = new Date(e);
+	if (isNaN(n.getTime())) return "";
+	let r = Math.floor((t.getTime() - n.getTime()) / 864e5);
+	return r < 0 ? "" : r < 7 ? `${r}d` : r < 30 ? `${Math.floor(r / 7)}w` : `${Math.floor(r / 30)}mo`;
+}
+function O(e) {
+	for (let t of e.split("\n")) {
+		let e = t.trimStart().match(E);
+		if (e) return e[1].replace(/\s*\[.*?\]\s*$/, "").trim();
+	}
+	return "—";
+}
+function k(e, t = /* @__PURE__ */ new Date()) {
+	let n = r(e), i = p(e, n.paths.prds);
+	if (!a(i)) return ["No features found — run `/tk:prd` to start one."];
+	let o = c(i).filter((e) => e.endsWith(".md")).sort();
+	if (o.length === 0) return ["No features found — run `/tk:prd` to start one."];
+	let l = p(e, n.paths.plans), u = [];
+	for (let e of o) {
+		let t = e.replace(/\.md$/, ""), n = y(s(p(i, e), "utf8"));
+		if (n.status === "done") continue;
+		let r = n.status || "unknown", o = n.created || "", c = o && !isNaN(new Date(o).getTime()) ? o : "", d = "—", f = "—", m = p(l, `${t}.md`);
+		if (a(m)) {
+			let e = s(m, "utf8"), { phases: t } = T(e), n = t.reduce((e, t) => e + t.checked, 0), r = t.reduce((e, t) => e + t.total, 0);
+			r > 0 && (d = `${n}/${r}`), f = O(e);
+		}
+		u.push({
+			slug: t,
+			status: r,
+			created: c,
+			progress: d,
+			next: f
+		});
+	}
+	if (u.length === 0) return ["No features found — run `/tk:prd` to start one."];
+	u.sort((e, t) => e.created && t.created ? new Date(e.created).getTime() - new Date(t.created).getTime() : e.created ? -1 : t.created ? 1 : 0);
+	let d = u.map((e) => {
+		let n = e.created ? D(e.created, t) : "";
+		return `| ${e.slug} | ${e.status} | ${n} | ${e.progress} | ${e.next} |`;
+	}), f = u.filter((e) => e.status === "in_progress"), m = f.length === 1 ? f[0] : f[0] ?? u[0];
+	return [
+		"| Feature | Status | Age | Progress | Next |",
+		"|---------|--------|-----|----------|------|",
+		...d,
+		"",
+		`**Focus → ${m.slug}**`
+	];
+}
+//#endregion
 //#region src/commands/progress.ts
-function C(e, n) {
-	let r = d(e, t(e).paths.plans, `${n}.md`);
-	if (!i(r)) throw Error(`Plan "${n}" not found at ${r}`);
-	let { phases: a } = S(o(r, "utf8"));
-	if (a.length === 0) return ["No phases found in plan.", "Total: 0/0"];
-	let s = [], c = 0, l = 0;
-	for (let e of a) c += e.checked, l += e.total, s.push(`  ${e.title}: ${e.checked}/${e.total}`);
-	return s.push(""), s.push(`Total: ${c}/${l}`), s;
+function A(e, t) {
+	let n = p(e, r(e).paths.plans, `${t}.md`);
+	if (!a(n)) throw Error(`Plan "${t}" not found at ${n}`);
+	let { phases: i } = T(s(n, "utf8"));
+	if (i.length === 0) return ["No phases found in plan.", "Total: 0/0"];
+	let o = [], c = 0, l = 0;
+	for (let e of i) c += e.checked, l += e.total, o.push(`  ${e.title}: ${e.checked}/${e.total}`);
+	return o.push(""), o.push(`Total: ${c}/${l}`), o;
 }
 //#endregion
 //#region src/cli.ts
-var { version: w } = JSON.parse(o(f(u(p(import.meta.url)), "..", "package.json"), "utf8")), T = [
+var { version: j } = JSON.parse(s(m(f(h(import.meta.url)), "..", "package.json"), "utf8")), M = Math.max(...e.map((e) => `${e.name} ${e.args}`.length)), N = [
 	"Usage: tracerkit <command> [path]",
 	"",
 	"Commands:",
-	"  init [path]       Install skills to ~/.claude/skills/ (or [path] if given)",
-	"  update [path]     Refresh unchanged files from latest version, skip modified",
-	"  uninstall [path]  Remove TracerKit skill directories, keep .tracerkit/ artifacts",
-	"  progress <slug>   Show per-phase checkbox progress for a plan",
-	"  archive <slug>    Archive a completed feature (PRD + plan)",
+	...e.map((e) => `  ${`${e.name} ${e.args}`.padEnd(M + 2)}${e.desc}`),
 	"",
 	"Options:",
 	"  --force           Overwrite modified files during update",
@@ -88,42 +148,43 @@ var { version: w } = JSON.parse(o(f(u(p(import.meta.url)), "..", "package.json")
 	"",
 	"All commands default to the home directory when no path is given."
 ];
-function E(e, t = m()) {
+function P(e, t = g()) {
 	let n = e.find((e) => !e.startsWith("-"));
-	return n ? f(n) : t;
+	return n ? m(n) : t;
 }
-function D(e, t) {
+function F(e, t) {
 	let n = e.findIndex((e) => !e.startsWith("-"));
 	if (n === -1) return [
 		"Error: missing <slug> argument",
 		"",
-		...T
+		...N
 	];
 	let r = e[n], i = e.filter((e, t) => t !== n);
 	try {
-		return t(E(i, process.cwd()), r);
+		return t(P(i, process.cwd()), r);
 	} catch (e) {
 		return [`Error: ${e instanceof Error ? e.message : String(e)}`];
 	}
 }
-function O(t) {
-	if (t.includes("--help") || t.includes("-h")) return T;
-	if (t.includes("--version") || t.includes("-v")) return [`tracerkit/${w}`];
-	let i = t[0], a = t.slice(1);
-	switch (i) {
-		case "init": return n(E(a));
+function I(e) {
+	if (e.includes("--help") || e.includes("-h")) return N;
+	if (e.includes("--version") || e.includes("-v")) return [`tracerkit/${j}`];
+	let r = e[0], a = e.slice(1);
+	switch (r) {
+		case "brief": return k(P(a, process.cwd()));
+		case "init": return n(P(a));
 		case "update": {
-			let t = a.includes("--force"), n = e(E(a.filter((e) => e !== "--force")), { force: t });
+			let e = a.includes("--force"), n = t(P(a.filter((e) => e !== "--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 "uninstall": return r(E(a));
-		case "progress": return D(a, C);
-		case "archive": return D(a, v);
-		default: return T;
+		case "uninstall": return i(P(a));
+		case "progress": return F(a, A);
+		case "archive": return F(a, x);
+		default: return N;
 	}
 }
 //#endregion
 //#region src/bin.ts
-var k = O(process.argv.slice(2));
-for (let e of k) console.log(e);
+var L = I(process.argv.slice(2));
+for (let e of L) console.log(e);
 //#endregion

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, r, t as i } from "./uninstall-Dri3LFXP.js";
-export { t as DEPRECATED_SKILLS, e as SKILL_NAMES, r as init, i as uninstall, n as update };
+import { a as e, i as t, n, o as r, r as i, t as a } from "./uninstall-DO2YpTSz.js";
+export { t as COMMANDS, e as DEPRECATED_SKILLS, r as SKILL_NAMES, i as init, a as uninstall, n as update };

package/dist/{uninstall-Dri3LFXP.js → uninstall-DO2YpTSz.js}

@@ -25,40 +25,72 @@ function d(t) {
 	} };
 }
 var f = [
+	"tk:brief",
 	"tk:prd",
 	"tk:plan",
 	"tk:check"
-], p = ["tk:verify"], m = s(o(l(import.meta.url)), "..", "templates");
-function h(e, t = "") {
+], p = ["tk:verify"], m = [
+	{
+		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"
+	},
+	{
+		name: "brief",
+		args: "[path]",
+		desc: "Show active features, progress, and suggested focus"
+	},
+	{
+		name: "progress",
+		args: "<slug>",
+		desc: "Show per-phase checkbox progress for a plan"
+	},
+	{
+		name: "archive",
+		args: "<slug>",
+		desc: "Archive a completed feature (PRD + plan)"
+	}
+], h = s(o(l(import.meta.url)), "..", "templates");
+function g(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(...h(s(e, r.name), n)) : i.push(n);
+		r.isDirectory() ? i.push(...g(s(e, r.name), n)) : i.push(n);
 	}
 	return i.sort();
 }
-function g(e, t) {
+function _(e, t) {
 	return e.replaceAll("{{paths.prds}}", t.paths.prds).replaceAll("{{paths.plans}}", t.paths.plans).replaceAll("{{paths.archives}}", t.paths.archives);
 }
-function _(e, r, i) {
-	let c = i ?? h(m);
+function v(e, r, i) {
+	let c = i ?? g(h);
 	for (let i of c) {
-		let c = s(m, i), l = s(e, i);
-		t(o(l), { recursive: !0 }), a(l, g(n(c, "utf8"), r));
+		let c = s(h, i), l = s(e, i);
+		t(o(l), { recursive: !0 }), a(l, _(n(c, "utf8"), r));
 	}
 	return { copied: c };
 }
-function v(e) {
+function y(e) {
 	return c("sha256").update(e).digest("hex");
 }
-function y(t, r) {
-	let i = h(m), a = [], o = [], c = [];
+function b(t, r) {
+	let i = g(h), a = [], o = [], c = [];
 	for (let l of i) {
 		let i = s(t, l);
 		if (!e(i)) c.push(l);
 		else {
-			let e = g(n(s(m, l), "utf8"), r);
-			v(Buffer.from(e)) === v(n(i)) ? a.push(l) : o.push(l);
+			let e = _(n(s(h, l), "utf8"), r);
+			y(Buffer.from(e)) === y(n(i)) ? a.push(l) : o.push(l);
 		}
 	}
 	return {
@@ -69,16 +101,16 @@ function y(t, r) {
 }
 //#endregion
 //#region src/commands/init.ts
-function b(t) {
+function x(t) {
 	for (let n of f) if (e(s(t, ".claude", "skills", n))) throw Error(`.claude/skills/${n}/ already exists — aborting`);
-	let { copied: n } = _(t, d(t));
+	let { copied: n } = v(t, d(t));
 	return n.map((e) => `✓ ${e}`);
 }
 //#endregion
 //#region src/commands/update.ts
-function x(t, n) {
+function S(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 } = y(t, r), l = [];
+	let r = d(t), { unchanged: a, modified: o, missing: c } = b(t, r), l = [];
 	for (let n of p) {
 		let r = s(t, ".claude", "skills", n);
 		e(r) && (i(r, {
@@ -92,7 +124,7 @@ function x(t, n) {
 		...u ? o : []
 	];
 	if (m.length > 0) {
-		_(t, r, m);
+		v(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)`);
@@ -105,7 +137,7 @@ function x(t, n) {
 }
 //#endregion
 //#region src/commands/uninstall.ts
-function S(t) {
+function C(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) {
@@ -118,4 +150,4 @@ function S(t) {
 	return n;
 }
 //#endregion
-export { f as a, p as i, x as n, d as o, b as r, S as t };
+export { p as a, m as i, S as n, f as o, x as r, d as s, C as t };

package/package.json

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

package/templates/.claude/skills/tk:brief/SKILL.md

@@ -0,0 +1,40 @@
+---
+description: Session briefing — shows active features, progress, and suggested focus. Use at the start of a session to orient.
+---
+
+# Session Briefing
+
+Get a quick overview of all active features, their progress, and what to focus on next.
+
+## Pre-loaded context
+
+- Briefing: !`npx tracerkit brief 2>/dev/null || echo "no {{paths.prds}}/ directory found"`
+
+## Workflow
+
+### 1. Present the briefing
+
+Display the output above as-is. The table includes:
+
+- **Feature**: slug (PRD filename without `.md`)
+- **Status**: from PRD frontmatter (`created`, `in_progress`) — `unknown` if no frontmatter
+- **Age**: time since `created` date
+- **Progress**: checked/total from plan checkboxes, or `—` if no plan
+- **Next**: first unchecked item from the plan, or `—`
+
+Features with `status: done` are excluded (already archived).
+
+### 2. Focus recommendation
+
+The **Focus** line at the bottom suggests which feature to work on:
+
+- If exactly 1 feature is `in_progress`, it's auto-selected
+- Otherwise, the oldest feature by `created` date is selected
+
+### 3. Offer next steps
+
+Ask the user what they'd like to do:
+
+- Continue the focused feature (read its plan at `{{paths.plans}}/<slug>.md`)
+- Start a new feature with `/tk:prd`
+- Check progress on a feature with `/tk:check <slug>`

package/templates/.claude/skills/tk:check/SKILL.md

@@ -47,7 +47,7 @@ Before launching a subagent, check whether the primary module file(s) from Phase
 
 ### 3b. Launch read-only review
 
-Use a **read-only subagent** (no file writes, no edits) to:
+Use a **general-purpose subagent** (not `code-review` — that agent is for PR reviews). The subagent must be **read-only** (no file writes, no edits). It should:
 
 1. Read every section of the plan — architectural decisions, each phase, done-when checkboxes
 2. For each phase, check every `- [ ]` / `- [x]` item against the codebase