tracerkit 1.4.7 → 1.6.0

package/README.md

@@ -8,7 +8,7 @@
 [![npm version](https://img.shields.io/npm/v/tracerkit)](https://www.npmjs.com/package/tracerkit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Replace ad-hoc AI prompts with a repeatable three-step spec process: from idea to verified, archived code.
+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**.
 
@@ -43,9 +43,11 @@ AI:  ✓ Phase 1 — CSS variables + ThemeProvider
      ✓ Phase 2 — Toggle component + localStorage
      ✓ Written .tracerkit/plans/dark-mode-support.md
 
-You: /tk:verify dark-mode-support
-AI:  ✓ All done-when conditions met
-     ✅ PASS — archived to .tracerkit/archives/dark-mode-support/
+You: # implement each phase...
+
+You: /tk:check dark-mode-support
+AI:  ✓ All checks verified — status: done
+     Archived to .tracerkit/archives/dark-mode-support/
 ```
 
 See [Examples](docs/examples.md) for full walkthroughs.
@@ -65,11 +67,7 @@ npx tracerkit uninstall .         # remove project-scoped skills
 
 ## Skills
 
-TracerKit ships four skills — three for the core workflow, one for visibility.
-
-### Core skills
-
-Three steps that take a feature from idea to verified archive.
+TracerKit ships three skills that take a feature from idea to verified archive.
 
 #### `/tk:prd <idea>`: Write a PRD
 
@@ -83,19 +81,13 @@ Reads a PRD and breaks it into phased **tracer-bullet vertical slices**. Each ph
 
 **Output:** `.tracerkit/plans/<slug>.md`
 
-#### `/tk:verify <slug>`: Verify and archive
-
-Read-only review that checks the codebase against the plan's done-when conditions. Runs tests, validates user stories, and stamps a **✅ PASS** or **🚧 NEEDS_WORK** verdict. On ✅ PASS, archives the PRD and plan to `.tracerkit/archives/<slug>/` automatically.
-
-**Output:** Verdict block in `.tracerkit/plans/<slug>.md`. On ✅ PASS: `.tracerkit/archives/<slug>/prd.md` + `.tracerkit/archives/<slug>/plan.md`
-
-### Helper skills
+#### `/tk:check [slug]`: Check and archive
 
-Useful but optional.
+Checks the codebase against the plan's done-when checkboxes. Runs tests, validates user stories, updates check progress, and transitions the PRD status. On `done`, archives the PRD and plan to `.tracerkit/archives/<slug>/` automatically.
 
-#### `/tk:status`: Workflow dashboard
+Without arguments, shows a feature dashboard with status and progress before asking which feature to check.
 
-Scans `.tracerkit/prds/` and prints a table of all features grouped by status (`in_progress`, `created`, `done`), with age, latest verdict, and blocker/suggestion counts. Read-only. No files are modified.
+**Output:** Verdict block in `.tracerkit/plans/<slug>.md`. On `done`: `.tracerkit/archives/<slug>/prd.md` + `.tracerkit/archives/<slug>/plan.md`
 
 ## Docs
 

package/dist/bin.js

@@ -1,17 +1,85 @@
 #!/usr/bin/env node
-import { n as e, r as t, t as n } from "./uninstall-C6vhDv_T.js";
-import { readFileSync as r } from "node:fs";
-import { dirname as i, resolve as a } from "node:path";
-import { fileURLToPath as o } from "node:url";
-import { homedir as s } from "node:os";
+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";
+//#region src/frontmatter.ts
+var h = /^---\n([\s\S]*?)\n---(?:\n|$)/;
+function g(e) {
+	return e.replace(/\r\n/g, "\n");
+}
+function _(e, t, n) {
+	let r = g(e), i = r.match(h);
+	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 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 });
+	try {
+		let e = (/* @__PURE__ */ new Date()).toISOString(), t = [];
+		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;
+	} catch (e) {
+		throw s(p, {
+			recursive: !0,
+			force: !0
+		}), e;
+	}
+}
+//#endregion
+//#region src/plan.ts
+var y = /^## (Phase \d+\s*.*)$/, b = /^- \[x\] /i, x = /^- \[ \] /;
+function S(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);
+		if (t.startsWith("## ")) {
+			i ? (r = {
+				title: i[1].trim(),
+				checked: 0,
+				total: 0
+			}, n.push(r)) : r = null;
+			continue;
+		}
+		r && (b.test(t) ? (r.checked++, r.total++) : x.test(t) && r.total++);
+	}
+	return { phases: n };
+}
+//#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;
+}
+//#endregion
 //#region src/cli.ts
-var { version: c } = JSON.parse(r(a(i(o(import.meta.url)), "..", "package.json"), "utf8")), l = [
+var { version: w } = JSON.parse(o(f(u(p(import.meta.url)), "..", "package.json"), "utf8")), T = [
 	"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)",
 	"",
 	"Options:",
 	"  --force           Overwrite modified files during update",
@@ -20,26 +88,42 @@ var { version: c } = JSON.parse(r(a(i(o(import.meta.url)), "..", "package.json")
 	"",
 	"All commands default to the home directory when no path is given."
 ];
-function u(e) {
-	let t = e.find((e) => !e.startsWith("-"));
-	return t ? a(t) : s();
-}
-function d(r) {
-	if (r.includes("--help") || r.includes("-h")) return l;
-	if (r.includes("--version") || r.includes("-v")) return [`tracerkit/${c}`];
-	let i = r[0], a = r.slice(1);
+function E(e, t = m()) {
+	let n = e.find((e) => !e.startsWith("-"));
+	return n ? f(n) : t;
+}
+function D(e, t) {
+	let n = e.findIndex((e) => !e.startsWith("-"));
+	if (n === -1) return [
+		"Error: missing <slug> argument",
+		"",
+		...T
+	];
+	let r = e[n], i = e.filter((e, t) => t !== n);
+	try {
+		return t(E(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 t(u(a));
+		case "init": return n(E(a));
 		case "update": {
-			let t = a.includes("--force"), n = e(u(a.filter((e) => e !== "--force")), { force: t });
+			let t = a.includes("--force"), n = e(E(a.filter((e) => e !== "--force")), { force: t });
 			return n.push("", "Updated to the latest TracerKit."), n.push("If using Claude Code, restart your session to load changes."), n;
 		}
-		case "uninstall": return n(u(a));
-		default: return l;
+		case "uninstall": return r(E(a));
+		case "progress": return D(a, C);
+		case "archive": return D(a, v);
+		default: return T;
 	}
 }
 //#endregion
 //#region src/bin.ts
-var f = d(process.argv.slice(2));
-for (let e of f) console.log(e);
+var k = O(process.argv.slice(2));
+for (let e of k) console.log(e);
 //#endregion

package/dist/index.js

@@ -1,2 +1,2 @@
-import { i as e, n as t, r as n, t as r } from "./uninstall-C6vhDv_T.js";
-export { e as SKILL_NAMES, n as init, r as uninstall, t as update };
+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 };

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

@@ -24,44 +24,41 @@ function d(t) {
 		archives: typeof o.archives == "string" ? o.archives : u.archives
 	} };
 }
-//#endregion
-//#region src/templates.ts
 var f = [
 	"tk:prd",
 	"tk:plan",
-	"tk:verify",
-	"tk:status"
-], p = s(o(l(import.meta.url)), "..", "templates");
-function m(e, t = "") {
+	"tk:check"
+], p = ["tk:verify"], m = s(o(l(import.meta.url)), "..", "templates");
+function h(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(...m(s(e, r.name), n)) : i.push(n);
+		r.isDirectory() ? i.push(...h(s(e, r.name), n)) : i.push(n);
 	}
 	return i.sort();
 }
-function h(e, t) {
+function g(e, t) {
 	return e.replaceAll("{{paths.prds}}", t.paths.prds).replaceAll("{{paths.plans}}", t.paths.plans).replaceAll("{{paths.archives}}", t.paths.archives);
 }
-function g(e, r, i) {
-	let c = i ?? m(p);
+function _(e, r, i) {
+	let c = i ?? h(m);
 	for (let i of c) {
-		let c = s(p, i), l = s(e, i);
-		t(o(l), { recursive: !0 }), a(l, h(n(c, "utf8"), r));
+		let c = s(m, i), l = s(e, i);
+		t(o(l), { recursive: !0 }), a(l, g(n(c, "utf8"), r));
 	}
 	return { copied: c };
 }
-function _(e) {
+function v(e) {
 	return c("sha256").update(e).digest("hex");
 }
-function v(t, r) {
-	let i = m(p), a = [], o = [], c = [];
+function y(t, r) {
+	let i = h(m), a = [], o = [], c = [];
 	for (let l of i) {
 		let i = s(t, l);
 		if (!e(i)) c.push(l);
 		else {
-			let e = h(n(s(p, l), "utf8"), r);
-			_(Buffer.from(e)) === _(n(i)) ? a.push(l) : o.push(l);
+			let e = g(n(s(m, l), "utf8"), r);
+			v(Buffer.from(e)) === v(n(i)) ? a.push(l) : o.push(l);
 		}
 	}
 	return {
@@ -72,35 +69,43 @@ function v(t, r) {
 }
 //#endregion
 //#region src/commands/init.ts
-function y(t) {
+function b(t) {
 	for (let n of f) if (e(s(t, ".claude", "skills", n))) throw Error(`.claude/skills/${n}/ already exists — aborting`);
-	let { copied: n } = g(t, d(t));
+	let { copied: n } = _(t, d(t));
 	return n.map((e) => `✓ ${e}`);
 }
 //#endregion
 //#region src/commands/update.ts
-function b(t, n) {
+function x(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: i, modified: a, missing: o } = v(t, r), c = [], l = n?.force ?? !1, u = [
-		...i,
-		...o,
-		...l ? a : []
+	let r = d(t), { unchanged: a, modified: o, missing: c } = y(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 (u.length > 0) {
-		g(t, r, u);
-		for (let e of i) c.push(`✓ ${e}`);
-		for (let e of o) c.push(`✓ ${e} (added)`);
-		if (l) for (let e of a) c.push(`✓ ${e} (replaced)`);
+	if (m.length > 0) {
+		_(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 (!l && a.length > 0) {
-		for (let e of a) c.push(`⚠ ${e} (skipped — modified)`);
-		c.push("", "Run `tracerkit update --force` to replace modified files with latest versions.");
+	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 c;
+	return l;
 }
 //#endregion
 //#region src/commands/uninstall.ts
-function x(t) {
+function S(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) {
@@ -113,4 +118,4 @@ function x(t) {
 	return n;
 }
 //#endregion
-export { f as i, b as n, y as r, x as t };
+export { f as a, p as i, x as n, d as o, b as r, S as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracerkit",
-  "version": "1.4.7",
+  "version": "1.6.0",
   "description": "Spec-driven workflow for Claude Code: replace ad-hoc prompts with PRD → plan → verify.",
   "license": "MIT",
   "author": {
@@ -50,8 +50,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
-    "prepare": "husky",
-    "prepublishOnly": "npm run build",
+    "prepare": "husky || true && npm run build",
     "release": "semantic-release"
   },
   "lint-staged": {

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

@@ -0,0 +1,141 @@
+---
+description: Verify implementation against plan. Shows progress, finds blockers, and archives when done. Use after implementing a plan, or without arguments to see a feature dashboard.
+argument-hint: '[slug]'
+---
+
+# Check Implementation
+
+Check implementation against a plan. Update checks, stamp findings, transition status, and archive when done.
+
+## Pre-loaded context
+
+- Available plans: !`ls {{paths.plans}}/ 2>/dev/null || echo "no {{paths.plans}}/ directory found"`
+
+## Input
+
+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:
+
+```
+| 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 `npx tracerkit progress <slug>` for each feature with a plan — use the Total line (e.g. "3/7"). Show `—` if no plan.
+
+After the table, ask which feature to verify.
+
+## Workflow
+
+### 1. Load the plan
+
+Read `{{paths.plans}}/<slug>.md`. If it does not exist, list available plans and ask.
+
+### 2. Load the PRD
+
+Read the source PRD referenced in the plan header (`> Source PRD: ...`).
+
+### 3. Launch read-only review
+
+Use a **read-only subagent** (no file writes, no edits) to:
+
+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
+3. Run any test commands referenced in the plan or discoverable via project conventions
+4. Compare user stories from the PRD against actual behavior
+
+For each checkbox, determine whether it should be verified (`[x]`) or not (`[ ]`) and report this — do not edit any files.
+
+Collect findings into two categories:
+
+- **BLOCKERS** — checked items that don't hold up, failing tests, broken contracts. These prevent transitioning to `done`.
+- **SUGGESTIONS** — improvements, minor gaps, style issues. These do not prevent `done`.
+
+### 3b. Update checkboxes
+
+Using the subagent's report, update each checkbox in `{{paths.plans}}/<slug>.md` to `[x]` or `[ ]`.
+
+### 4. Determine outcome
+
+Based on checks and findings, decide the status transition:
+
+- All checks verified + zero BLOCKERS → transition PRD to `done`
+- Some checks verified + zero BLOCKERS → keep PRD as `in_progress`
+- BLOCKERS found → keep PRD as `in_progress`
+
+### 5. Report to user
+
+Run `npx tracerkit progress <slug>` to get exact per-phase progress, then print the verdict report:
+
+```
+## Verification: <slug>
+
+### Status: created | in_progress | done
+
+### Progress
+<output from tracerkit progress>
+
+### BLOCKERS
+- (list or "None")
+
+### SUGGESTIONS
+- (list or "None")
+```
+
+### 6. Stamp the plan
+
+Append a verdict block at the bottom of `{{paths.plans}}/<slug>.md`:
+
+```markdown
+---
+
+## Verdict
+
+- **Date**: YYYY-MM-DD
+- **Checks**: (checked/total)
+- **BLOCKERS**: (count)
+- **SUGGESTIONS**: (count)
+```
+
+If a previous verdict block exists, replace it with the new one.
+
+### 7. On `done` — archive
+
+If all checks pass and zero BLOCKERS, run:
+
+```
+npx tracerkit archive <slug>
+```
+
+This handles: PRD frontmatter update (`status: done`, `completed` timestamp), file moves to `{{paths.archives}}/<slug>/`, and archived block on the plan.
+
+Tell the user: archived to `{{paths.archives}}/<slug>/`, one-line summary of the feature.
+
+### 8. On `in_progress` (no blockers)
+
+Show progress summary (checked/total per phase), list the next unchecked items to implement. Keep going.
+
+### 9. On `in_progress` (with blockers)
+
+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
+- 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
+
+## 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

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

@@ -35,6 +35,8 @@ If the PRD has no frontmatter, skip this step silently.
 
 Understand current architecture, existing patterns, and integration points.
 
+**Research protocol**: codebase first, then project docs. If you cannot verify a technical claim from these sources, flag it as uncertain — never fabricate.
+
 ### 3. Identify durable architectural decisions
 
 Before slicing, extract decisions that hold across all phases:
@@ -65,6 +67,8 @@ 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.
+
 **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.
@@ -112,7 +116,8 @@ Concise description of this vertical slice — end-to-end behavior, not layer-by
 
 ### Done when
 
-<Specific, testable condition>
+- [ ] Atomic, testable condition
+- [ ] Another testable condition
 
 ---
 
@@ -133,7 +138,8 @@ Print saved path and one line per phase: `Phase N — <title> (<condition summar
 
 - Phases derive from PRD user stories — never invented
 - Each phase must be demoable end-to-end on its own
-- "Done when" must be testable, not vague
+- "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
 - Never modify the source PRD
 - Carry PRD's Out of Scope forward verbatim
 

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

@@ -27,6 +27,8 @@ Ask the user for a detailed description of the problem and any solution ideas.
 
 Verify assertions and map current state: data models, services, API routes, frontend structure, and test patterns. Note what exists vs. what must be built.
 
+**Research protocol**: codebase first, then project docs. If you cannot verify a technical claim from these sources, flag it 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).
@@ -41,6 +43,18 @@ Walk these branches (skip any already resolved):
 - **Boundaries** — What is explicitly out of scope? Adjacent features to defer?
 - **Integration** — Schema changes? New or extended services? External dependencies?
 
+### 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:
+
+```
+Gray areas found:
+1. <ambiguity> — assumed <X>, confirm?
+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.
+
 ### 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.
@@ -65,6 +79,14 @@ status: created
 
 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.

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

@@ -1,64 +0,0 @@
----
-description: Show a dashboard of all features and their workflow status. Use any time to check progress.
----
-
-# Workflow Dashboard
-
-Scan all PRDs and display a status overview of every feature in the workflow.
-
-## Workflow
-
-### 1. Scan PRDs
-
-List all `.md` files in `{{paths.prds}}/`. If the directory is missing or empty, print "No features found — run `/tk:prd` to start one." and stop.
-
-### 2. Parse each PRD
-
-For each file `{{paths.prds}}/<slug>.md`:
-
-1. Read YAML frontmatter (between opening and closing `---` delimiters)
-2. Extract fields: `created`, `status`, `completed`
-3. If no frontmatter exists, treat as `status: unknown` with no age
-
-### 3. Read verdict data
-
-For each slug, check if `{{paths.plans}}/<slug>.md` exists. If it does, find the last `## Verdict` block and extract:
-
-- **Result**: ✅ PASS or 🚧 NEEDS_WORK
-- **BLOCKERS**: count
-- **SUGGESTIONS**: count
-
-If no plan or no verdict block exists, leave verdict columns blank.
-
-### 4. Print the table
-
-Group features by status in this order: `in_progress`, `created`, `done`, `unknown`.
-
-Within each group, sort by `created` date (oldest first). Features without a `created` date sort last.
-
-Print a markdown table:
-
-```
-## Workflow Dashboard
-
-| Feature | Status | Age | Verdict | Blockers | Suggestions |
-|---------|--------|-----|---------|----------|-------------|
-| <slug>  | ...    | ... | ...     | ...      | ...         |
-```
-
-Column definitions:
-
-- **Feature**: the slug (filename without `.md`)
-- **Status**: `created`, `in_progress`, `done`, or `unknown`
-- **Age**: human-readable duration since `created` (e.g. "3d", "2w", "1mo") — blank if no `created`
-- **Verdict**: latest verdict result or blank
-- **Blockers**: blocker count from latest verdict or blank
-- **Suggestions**: suggestion count from latest verdict or blank
-
-After the table, print a one-line summary: `N features: X in progress, Y created, Z done`.
-
-## Rules
-
-- Read-only — this skill must not create, edit, or delete any files
-- Graceful degradation for missing frontmatter, missing plans, or missing verdicts
-- No arguments accepted — always scans all PRDs

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

@@ -1,130 +0,0 @@
----
-description: Compare implementation against plan, emit BLOCKERS/SUGGESTIONS and a ✅ PASS or 🚧 NEEDS_WORK verdict. Auto-archives on ✅ PASS. Use after implementing a plan.
-argument-hint: '[slug]'
----
-
-# Verify Implementation
-
-Compare current implementation against a plan, stamp a verdict, and archive on ✅ PASS.
-
-## Pre-loaded context
-
-- Available plans: !`ls {{paths.plans}}/ 2>/dev/null || echo "no {{paths.plans}}/ directory found"`
-
-## Input
-
-The argument (if provided) is: $ARGUMENTS
-
-Use the argument as `<slug>` if given. If no argument is provided, list available plans and ask which one to verify.
-
-## Workflow
-
-### 1. Load the plan
-
-Read `{{paths.plans}}/<slug>.md`. If it does not exist, list available plans and ask.
-
-### 2. Load the PRD
-
-Read the source PRD referenced in the plan header (`> Source PRD: ...`).
-
-### 3. Launch read-only review
-
-Use a **read-only subagent** (no file writes, no edits) to:
-
-1. Read every section of the plan — architectural decisions, each phase, done-when conditions
-2. For each phase, explore the codebase to verify the done-when condition is satisfied
-3. Run any test commands referenced in the plan or discoverable via project conventions
-4. Compare user stories from the PRD against actual behavior
-
-Collect findings into two categories:
-
-- **BLOCKERS** — done-when conditions not met, missing functionality, failing tests, broken contracts. These prevent a ✅ PASS.
-- **SUGGESTIONS** — improvements, minor gaps, style issues. These do not prevent a ✅ PASS.
-
-### 4. Determine verdict
-
-- **✅ PASS** — zero BLOCKERS
-- **🚧 NEEDS_WORK** — one or more BLOCKERS
-
-### 5. Report to user
-
-Print the verdict report:
-
-```
-## Verification: <slug>
-
-### Verdict: ✅ PASS | 🚧 NEEDS_WORK
-
-### BLOCKERS
-- (list or "None")
-
-### SUGGESTIONS
-- (list or "None")
-```
-
-### 6. Stamp the plan
-
-Append a verdict block at the bottom of `{{paths.plans}}/<slug>.md`:
-
-```markdown
----
-
-## Verdict
-
-- **Result**: ✅ PASS | 🚧 NEEDS_WORK
-- **Date**: YYYY-MM-DD
-- **BLOCKERS**: (count)
-- **SUGGESTIONS**: (count)
-```
-
-If a previous verdict block exists, replace it with the new one.
-
-### 7. On ✅ PASS — update PRD status and archive
-
-If the verdict is **✅ PASS**:
-
-**First**, update the YAML frontmatter in `{{paths.prds}}/<slug>.md`:
-
-- Set `status: done`
-- Add `completed: <current UTC timestamp, ISO 8601, e.g. 2025-06-15T14:30:00Z>`
-- Do not touch any other frontmatter fields or the markdown content below the closing `---`
-- If the PRD has no frontmatter, skip frontmatter update silently
-
-**Then**, automatically archive:
-
-1. Create `{{paths.archives}}/<slug>/` directory (and `{{paths.archives}}/` if missing)
-2. Move `{{paths.prds}}/<slug>.md` → `{{paths.archives}}/<slug>/prd.md`
-3. Move `{{paths.plans}}/<slug>.md` → `{{paths.archives}}/<slug>/plan.md`
-4. Append closing timestamp to `{{paths.archives}}/<slug>/plan.md`:
-
-```markdown
----
-
-## Archived
-
-- **Status**: closed
-- **Closed**: YYYY-MM-DD HH:MM (UTC)
-```
-
-5. Tell the user: archived to `{{paths.archives}}/<slug>/`, one-line summary of the feature.
-
-If `{{paths.archives}}/<slug>/` already exists, warn and ask whether to overwrite.
-
-### 8. On 🚧 NEEDS_WORK
-
-Tell the user: fix the listed blockers, then re-run `/tk:verify <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: the verdict block in the plan, and the archive move on ✅ PASS
-- Never modify the source PRD (except moving it to archive)
-- Never modify implementation code — only observe and report
-- If the PRD file is missing but the plan has a ✅ PASS verdict, warn but proceed with archiving the plan only
-
-## Error Handling
-
-- Plan not found — list available plans and ask
-- PRD referenced in plan not found — warn and continue with plan only
-- `{{paths.plans}}/` missing — tell user to run `/tk:plan` first
-- `{{paths.archives}}/<slug>/` already exists — warn and ask whether to overwrite