tracerkit 1.9.6 → 1.10.0

package/README.md

@@ -13,29 +13,25 @@ Replace ad-hoc AI prompts with a repeatable spec-driven workflow: from idea to v
 
 Named after the tracer-bullet technique from _The Pragmatic Programmer_: **Tracer** + **Kit**.
 
-**Markdown skills, one CLI.** No build step, no project dependencies.
+**Markdown skills, zero runtime deps.** No build step, no project dependencies.
 
 </div>
 
 ## 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.
+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.
 
-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.
-
-**Deterministic CLI, intelligent skills.** The CLI produces structured, repeatable output — feature tables, progress counts, archive operations — while the skills layer AI reasoning on top. The foundation is deterministic, so every session starts from the same ground truth. AI adds the judgment: interviewing you for scope, designing modules, verifying implementation against specs.
+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
 
 ### Install
 
 ```bash
-npm install -g tracerkit
-tracerkit init
+$ npm install -g tracerkit
+$ tracerkit init
 ```
 
-The global install is by design — skills call `tracerkit brief`, `tracerkit progress`, and `tracerkit archive` directly to get deterministic output before the AI acts on it. Having the CLI in your PATH keeps this seamless.
-
 Skills are installed to `~/.claude/skills/`, available in every project. Safe to re-run — adds missing skills without overwriting ones you've modified.
 
 ### Workflow
@@ -77,9 +73,9 @@ See [Examples](docs/examples.md) for full walkthroughs.
 To scope skills to a single project (team members get them via git):
 
 ```bash
-npx tracerkit init .              # install to .claude/skills/ in current dir
-npx tracerkit update .            # update project-scoped skills
-npx tracerkit uninstall .         # remove project-scoped skills
+$ tracerkit init .              # install to .claude/skills/ in current dir
+$ tracerkit update .            # update project-scoped skills
+$ tracerkit uninstall .         # remove project-scoped skills
 ```
 
 </details>
@@ -119,7 +115,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)           | Browse all CLI commands and flags                  |
+| [CLI Reference](docs/cli-reference.md)           | Lifecycle commands: init, update, uninstall        |
 | [Configuration](docs/configuration.md)           | Configure custom artifact paths via `config.json`  |
 | [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,145 +1,15 @@
 #!/usr/bin/env node
-import { c as e, i as t, n, o as r, r as i, t as a } from "./uninstall-C4dWMK0k.js";
-import { existsSync as o, mkdirSync as s, readFileSync as c, readdirSync as l, rmSync as u, unlinkSync as d, writeFileSync 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/frontmatter.ts
-var v = /^---\n([\s\S]*?)\n---(?:\n|$)/;
-function y(e) {
-	return e.replace(/\r\n/g, "\n");
-}
-function b(e) {
-	let t = y(e).match(v);
-	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 x(e, t, n) {
-	let r = y(e), i = r.match(v);
-	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}`;
-	let c = r.slice(i[0].length);
-	return `---\n${a.join("\n")}\n---\n${c}`;
-}
-//#endregion
-//#region src/commands/archive.ts
-function S(t, n) {
-	let r = e(t), i = m(t, r.paths.prds, `${n}.md`), a = m(t, r.paths.plans, `${n}.md`), l = m(t, r.paths.archives, n), p = o(i);
-	if (!o(a)) throw Error(`Plan "${n}" not found at ${a}`);
-	if (o(l)) throw Error(`Archive "${n}" already exists at ${l}`);
-	s(l, { recursive: !0 });
-	try {
-		let e = (/* @__PURE__ */ new Date()).toISOString(), t = [];
-		if (p) {
-			let t = c(i, "utf8");
-			t = x(t, "status", "done"), t = x(t, "completed", e), f(m(l, "prd.md"), t);
-		} else t.push(`Warning: PRD "${n}" missing, archiving plan only`);
-		let o = c(a, "utf8");
-		return o += `\n## Archived\n\nArchived on ${e.slice(0, 10)}.\n`, f(m(l, "plan.md"), o), p && d(i), d(a), t.push(`Archived "${n}" to ${r.paths.archives}/${n}/`), p && t.push(`  prd.md  — status: done, completed: ${e}`), t.push("  plan.md — archived block appended"), t;
-	} catch (e) {
-		throw u(l, {
-			recursive: !0,
-			force: !0
-		}), e;
-	}
-}
-//#endregion
-//#region src/plan.ts
-var C = /^## (Phase \d+\s*.*)$/, w = /^- \[x\] /i, T = /^- \[ \] /;
-function E(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(C);
-		if (t.startsWith("## ")) {
-			i ? (r = {
-				title: i[1].trim(),
-				checked: 0,
-				total: 0
-			}, n.push(r)) : r = null;
-			continue;
-		}
-		r && (w.test(t) ? (r.checked++, r.total++) : T.test(t) && r.total++);
-	}
-	return { phases: n };
-}
-//#endregion
-//#region src/commands/brief.ts
-var D = /^- \[ \] (.+)/;
-function O(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 k(e) {
-	for (let t of e.split("\n")) {
-		let e = t.trimStart().match(D);
-		if (e) return e[1].replace(/\s*\[.*?\]\s*$/, "").trim();
-	}
-	return "—";
-}
-function A(t, n = /* @__PURE__ */ new Date()) {
-	let r = e(t), i = m(t, r.paths.prds);
-	if (!o(i)) return ["No features found — run `/tk:prd` to start one."];
-	let a = l(i).filter((e) => e.endsWith(".md")).sort();
-	if (a.length === 0) return ["No features found — run `/tk:prd` to start one."];
-	let s = m(t, r.paths.plans), u = [];
-	for (let e of a) {
-		let t = e.replace(/\.md$/, ""), n = b(c(m(i, e), "utf8"));
-		if (n.status === "done") continue;
-		let r = n.status || "unknown", a = n.created || "", l = a && !isNaN(new Date(a).getTime()) ? a : "", d = "—", f = "—", p = m(s, `${t}.md`);
-		if (o(p)) {
-			let e = c(p, "utf8"), { phases: t } = E(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 = k(e);
-		}
-		u.push({
-			slug: t,
-			status: r,
-			created: l,
-			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 t = e.created ? O(e.created, n) : "";
-		return `| ${e.slug} | ${e.status} | ${t} | ${e.progress} | ${e.next} |`;
-	}), f = u.filter((e) => e.status === "in_progress"), p = f.length === 1 ? f[0] : f[0] ?? u[0];
-	return [
-		"| Feature | Status | Age | Progress | Next |",
-		"|---------|--------|-----|----------|------|",
-		...d,
-		"",
-		`**Focus → ${p.slug}**`
-	];
-}
-//#endregion
-//#region src/commands/progress.ts
-function j(t, n) {
-	let r = m(t, e(t).paths.plans, `${n}.md`);
-	if (!o(r)) throw Error(`Plan "${n}" not found at ${r}`);
-	let { phases: i } = E(c(r, "utf8"));
-	if (i.length === 0) return ["No phases found in plan.", "Total: 0/0"];
-	let a = [], s = 0, l = 0;
-	for (let e of i) s += e.checked, l += e.total, a.push(`  ${e.title}: ${e.checked}/${e.total}`);
-	return a.push(""), a.push(`Total: ${s}/${l}`), a;
-}
-//#endregion
+import { a as e, i as t, n, r, s as i, t as a } from "./uninstall-Bgs58wa2.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";
 //#region src/cli.ts
-var { version: M } = JSON.parse(c(h(p(g(import.meta.url)), "..", "package.json"), "utf8")), N = Math.max(...t.map((e) => `${e.name} ${e.args}`.length)), P = [
+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 = [
 	"Usage: tracerkit <command> [path]",
 	"",
 	"Commands:",
-	...t.map((e) => `  ${`${e.name} ${e.args}`.padEnd(N + 2)}${e.desc}`),
+	...t.map((e) => `  ${`${e.name} ${e.args}`.padEnd(f + 2)}${e.desc}`),
 	"",
 	"Options:",
 	"  --force           Overwrite modified files during update",
@@ -148,43 +18,27 @@ var { version: M } = JSON.parse(c(h(p(g(import.meta.url)), "..", "package.json")
 	"",
 	"All commands default to the home directory when no path is given."
 ];
-function F(e, t = _()) {
+function m(e, t = u()) {
 	let n = e.find((e) => !e.startsWith("-"));
-	return n ? h(n) : t;
-}
-function I(e, t) {
-	let n = e.findIndex((e) => !e.startsWith("-"));
-	if (n === -1) return [
-		"Error: missing <slug> argument",
-		"",
-		...P
-	];
-	let r = e[n], i = e.filter((e, t) => t !== n);
-	try {
-		return t(F(i, process.cwd()), r);
-	} catch (e) {
-		return [`Error: ${e instanceof Error ? e.message : String(e)}`];
-	}
-}
-function L(e) {
-	if (e.includes(r.help) || e.includes("-h")) return P;
-	if (e.includes(r.version) || e.includes("-v")) return [`tracerkit/${M}`];
-	let t = e[0], o = e.slice(1);
-	switch (t) {
-		case "brief": return A(F(o, process.cwd()));
-		case "init": return n(F(o));
+	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));
 		case "update": {
-			let e = o.includes(r.force), t = i(F(o.filter((e) => e !== r.force)), { force: e });
+			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;
 		}
-		case "uninstall": return a(F(o));
-		case "progress": return I(o, j);
-		case "archive": return I(o, S);
-		default: return P;
+		case "uninstall": return a(m(s));
+		default: return p;
 	}
 }
 //#endregion
 //#region src/bin.ts
-var R = L(process.argv.slice(2));
-for (let e of R) console.log(e);
+var g = h(process.argv.slice(2));
+for (let e of g) console.log(e);
 //#endregion

package/dist/index.js

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

package/dist/{uninstall-C4dWMK0k.js → uninstall-Bgs58wa2.js}

@@ -34,6 +34,10 @@ var f = [
 	help: "--help",
 	version: "--version"
 }, h = [
+	"brief",
+	"progress",
+	"archive"
+], g = [
 	{
 		name: "init",
 		args: "[path]",
@@ -48,53 +52,38 @@ var f = [
 		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)"
 	}
-], g = s(o(l(import.meta.url)), "..", "templates");
-function _(e, t = "") {
+], _ = s(o(l(import.meta.url)), "..", "templates");
+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(..._(s(e, r.name), n)) : i.push(n);
+		r.isDirectory() ? i.push(...v(s(e, r.name), n)) : i.push(n);
 	}
 	return i.sort();
 }
-function v(e, t) {
+function y(e, t) {
 	return e.replaceAll("{{paths.prds}}", t.paths.prds).replaceAll("{{paths.plans}}", t.paths.plans).replaceAll("{{paths.archives}}", t.paths.archives);
 }
-function y(e, r, i) {
-	let c = i ?? _(g);
+function b(e, r, i) {
+	let c = i ?? v(_);
 	for (let i of c) {
-		let c = s(g, i), l = s(e, i);
-		t(o(l), { recursive: !0 }), a(l, v(n(c, "utf8"), r));
+		let c = s(_, i), l = s(e, i);
+		t(o(l), { recursive: !0 }), a(l, y(n(c, "utf8"), r));
 	}
 	return { copied: c };
 }
-function b(e) {
+function x(e) {
 	return c("sha256").update(e).digest("hex");
 }
-function x(t, r) {
-	let i = _(g), a = [], o = [], c = [];
+function S(t, r) {
+	let i = v(_), a = [], o = [], c = [];
 	for (let l of i) {
 		let i = s(t, l);
 		if (!e(i)) c.push(l);
 		else {
-			let e = v(n(s(g, l), "utf8"), r);
-			b(Buffer.from(e)) === b(n(i)) ? a.push(l) : o.push(l);
+			let e = y(n(s(_, l), "utf8"), r);
+			x(Buffer.from(e)) === x(n(i)) ? a.push(l) : o.push(l);
 		}
 	}
 	return {
@@ -105,9 +94,9 @@ function x(t, r) {
 }
 //#endregion
 //#region src/commands/update.ts
-function S(t, n) {
+function C(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 } = x(t, r), l = [];
+	let r = d(t), { unchanged: a, modified: o, missing: c } = S(t, r), l = [];
 	for (let n of p) {
 		let r = s(t, ".claude", "skills", n);
 		e(r) && (i(r, {
@@ -121,7 +110,7 @@ function S(t, n) {
 		...u ? o : []
 	];
 	if (m.length > 0) {
-		y(t, r, m);
+		b(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)`);
@@ -134,14 +123,14 @@ function S(t, n) {
 }
 //#endregion
 //#region src/commands/init.ts
-function C(t) {
-	if (f.some((n) => e(s(t, ".claude", "skills", n)))) return S(t);
-	let { copied: n } = y(t, d(t));
+function w(t) {
+	if (f.some((n) => e(s(t, ".claude", "skills", n)))) return C(t);
+	let { copied: n } = b(t, d(t));
 	return n.map((e) => `✓ ${e}`);
 }
 //#endregion
 //#region src/commands/uninstall.ts
-function w(t) {
+function T(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) {
@@ -154,4 +143,4 @@ function w(t) {
 	return n;
 }
 //#endregion
-export { p as a, d as c, h as i, C as n, m as o, S as r, f as s, w as t };
+export { h as a, f as c, g as i, w as n, p as o, C as r, m as s, T as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracerkit",
-  "version": "1.9.6",
+  "version": "1.10.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

@@ -8,22 +8,69 @@ Get a quick overview of all active features, their progress, and what to focus o
 
 ## Pre-loaded context
 
-- Briefing: !`tracerkit brief 2>&1`
+- Available PRDs: !`ls {{paths.prds}}/ 2>&1`
 
-## Workflow
+## Algorithm
 
-### 1. Present the briefing
+Follow these steps exactly to build the briefing table:
 
-Display the output above as-is. Features with `status: done` are excluded (already archived).
+### 1. Discover features
 
-### 3. Focus recommendation
+For each `.md` file in `{{paths.prds}}/`:
 
-The **Focus** line at the bottom suggests which feature to work on:
+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`
 
-- If exactly 1 feature is `in_progress`, it's auto-selected
-- Otherwise, the oldest feature by `created` date is selected
+### 2. Count progress from plans
 
-### 4. Offer next steps
+For each slug, check if `{{paths.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.
+
+If no plan exists, progress is `—` and next is `—`.
+
+### 3. Build the table
+
+Sort features by `created` date ascending (no-date entries last). Calculate age from `created`:
+
+- < 7 days → `Nd` (e.g. `3d`)
+- < 30 days → `Nw` (e.g. `2w`)
+- 30+ days → `Nmo` (e.g. `1mo`)
+
+Output this exact table format:
+
+```
+| Feature | Status | Age | Progress | Next |
+|---------|--------|-----|----------|------|
+| <slug>  | <status> | <age> | <checked>/<total> | <next item> |
+```
+
+If no features found, output: `No features found — run /tk:prd to start one.`
+
+### 4. Determine focus
+
+Apply these rules in order:
+
+1. Exactly 1 feature with `status: in_progress` → auto-select it
+2. Multiple `in_progress` features → select the oldest by `created`
+3. Zero `in_progress` features → select the oldest overall
+
+Append below the table:
+
+```
+**Focus → <slug>**
+```
+
+### 5. Offer next steps
 
 Ask the user what they'd like to do:
 

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

@@ -17,20 +17,33 @@ The argument (if provided) is: $ARGUMENTS
 
 Use the argument as `<slug>` if given.
 
-If no argument is provided, scan `{{paths.prds}}/` and `{{paths.plans}}/` and show a summary table before asking which one to check:
+If no argument is provided, build a summary table before asking which one to check:
 
-```
+```markdown
 | Feature | Status | Progress |
-|---------|--------|----------|
+| ------- | ------ | -------- |
 | <slug>  | ...    | 3/7      |
 ```
 
-- **Feature**: slug (filename without `.md`)
-- **Status**: from PRD frontmatter (`created`, `in_progress`, `done`) — `unknown` if no frontmatter
-- **Progress**: run `tracerkit progress <slug>` for each feature with a plan — use the Total line (e.g. "3/7"). Show `—` if no plan.
+For each `.md` file in `{{paths.prds}}/`:
+
+1. Read the file, parse YAML frontmatter (block between `---` fences)
+2. Extract `status` — use `unknown` if missing
+3. If `{{paths.plans}}/<slug>.md` exists, count progress (see Progress Algorithm below). Show `—` if no plan.
 
 After the table, 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`
+
 ## Workflow
 
 ### 1. Load the plan
@@ -75,20 +88,25 @@ Based on checks and findings, decide the status transition:
 
 ### 5. Report to user
 
-Run `tracerkit progress <slug>` to get exact per-phase progress, then print the verdict report:
+Count progress per phase using the Progress Algorithm above, then print the verdict report:
 
-```
+```markdown
 ## Verification: <slug>
 
 ### Status: created | in_progress | done
 
 ### Progress
-<output from tracerkit progress>
+
+Phase 1 — title: checked/total
+Phase 2 — title: checked/total
+Total: checked/total
 
 ### BLOCKERS
+
 - (list or "None")
 
 ### SUGGESTIONS
+
 - (list or "None")
 ```
 
@@ -111,13 +129,19 @@ If a previous verdict block exists, replace it with the new one.
 
 ### 7. On `done` — archive
 
-If all checks pass and zero BLOCKERS, run:
-
-```
-tracerkit archive <slug>
-```
+If all checks pass and zero BLOCKERS, perform these steps in order:
 
-This handles: PRD frontmatter update (`status: done`, `completed` timestamp), file moves to `{{paths.archives}}/<slug>/`, and archived block on the plan.
+1. Create directory `{{paths.archives}}/<slug>/`
+2. If `{{paths.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 `{{paths.archives}}/<slug>/prd.md`
+3. Read `{{paths.plans}}/<slug>.md`
+   - Append to the end: `\n## Archived\n\nArchived on YYYY-MM-DD.\n`
+   - Write the result to `{{paths.archives}}/<slug>/plan.md`
+4. Delete `{{paths.prds}}/<slug>.md` (if it exists)
+5. Delete `{{paths.plans}}/<slug>.md`
 
 Tell the user: archived to `{{paths.archives}}/<slug>/`, one-line summary of the feature.
 
@@ -132,14 +156,13 @@ List the blockers to fix, then re-run `/tk:check <slug>`.
 ## Rules
 
 - The review subagent must be **read-only** — it must not create, edit, or delete any files
-- The only file writes this skill makes are: checkboxes + verdict block in the plan, and the archive command on `done`
-- Never modify the source PRD manually — `tracerkit archive` handles frontmatter updates
+- 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 — `tracerkit archive` supports plan-only archiving
+- 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
 - `{{paths.plans}}/` missing — tell user to run `/tk:plan` first
-- `{{paths.archives}}/<slug>/` already exists — `tracerkit archive` will error; warn and ask whether to remove it first
+- `{{paths.archives}}/<slug>/` already exists — warn and ask whether to remove it first

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

@@ -67,11 +67,17 @@ 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, testable conditions — not prose. Each item should be independently verifiable. The agent marks `[x]` during implementation to track progress.
+**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.
 
 **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.
 
-**Phase count:** 2–3 for single-module, 3–5 for multi-module, 5+ means consider splitting the PRD.
+**Phase count thresholds:**
+
+- 1 module touched → 2–3 phases max
+- 2–3 modules touched → 3–5 phases max
+- 4+ modules or 6+ phases → stop and ask the user to split the PRD
+
+Count "modules touched" by scanning the PRD's New Modules and Schema Changes sections.
 
 Assign an agent tag to tasks where appropriate:
 

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

@@ -17,7 +17,15 @@ 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: use only the text before `—` or `–` (if present), take at most 3–4 keywords, strip filler words (a, the, for, etc.), then convert to kebab-case (lowercase, hyphens). This is `<slug>`. The output file is `{{paths.prds}}/<slug>.md`.
+If the argument is provided, derive a slug using this exact algorithm:
+
+1. Take only the text before the first `—` or `–` (if present)
+2. Lowercase the text
+3. Remove filler words: a, an, the, for, of, to, in, on, with, and, or, but, is, be
+4. Take the first 4 remaining words (or fewer if less exist)
+5. Join with hyphens → `<slug>`
+
+The output file is `{{paths.prds}}/<slug>.md`.
 
 If `{{paths.prds}}/<slug>.md` already exists, tell the user and ask whether to overwrite or pick a new name.
 
@@ -37,19 +45,26 @@ Verify assertions and map current state: data models, services, API routes, fron
 
 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).
 
-Walk these branches (skip any already resolved or irrelevant to the project type — e.g., for CLI tools and libraries, skip UI-specific branches like Display, Access, Navigation unless the idea involves them):
+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.
 
-- **Scope & Surface** — Where does this live? New page/view or integrated? Which user roles?
-- **Data & Concepts** — Precise definitions for each new concept. What data exists, what's missing?
-- **Behavior & Interaction** — How does the user interact? Sorting, filtering, search, time ranges?
-- **Display & Output** — Numbers, tables, charts, forms? Exportable? URL-driven state?
-- **Access & Privacy** — Who sees what? Role-based restrictions? Sensitive data concerns?
-- **Boundaries** — What is explicitly out of scope? Adjacent features to defer?
-- **Integration** — Schema changes? New or extended services? External dependencies?
+- **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 area checkpoint
 
-Before continuing, list any unresolved ambiguities from the interview — vague answers, contradictions, assumptions you made without confirmation. Present them as a numbered list:
+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:
@@ -57,7 +72,7 @@ Gray areas found:
 2. <ambiguity> — two options: A or B
 ```
 
-If the list is empty, say so and move on. Otherwise, resolve each item with the user before proceeding.
+If the list is empty, say "No gray areas found" and move on. Otherwise, resolve each item with the user before proceeding.
 
 ### 4. Design modules