tracerkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helder Burato Berto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+<div align="center">
+
+# TracerKit
+
+[![CI](https://github.com/helderberto/tracerkit/actions/workflows/ci.yml/badge.svg)](https://github.com/helderberto/tracerkit/actions/workflows/ci.yml)
+
+A spec-driven workflow for Claude Code. Three skills take a feature from idea to verified archive: define, plan, verify.
+
+**Zero runtime dependencies** — pure Markdown skills, no build step.
+
+</div>
+
+## Get Started
+
+### 1. Install TracerKit
+
+```bash
+npx tracerkit init
+```
+
+Skills are installed globally to `~/.claude/skills/` — available in every project, no per-project setup needed.
+
+### 2. Use the skills
+
+Open Claude Code in any project and start using:
+
+```bash
+/tk:prd add dark mode support     # define the feature
+/tk:plan dark-mode-support        # break into vertical slices
+/tk:verify dark-mode-support      # verify and archive
+```
+
+### 3. Manage your installation
+
+```bash
+npx tracerkit update              # refresh to latest, skip modified files
+npx tracerkit uninstall           # remove TracerKit skills
+```
+
+<details>
+<summary>Install per-project instead</summary>
+
+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 init /path/to/proj  # or specify a path
+```
+
+Per-project commands:
+
+```bash
+npx tracerkit update .
+npx tracerkit uninstall .
+```
+
+</details>
+
+## Skills
+
+### `/tk:prd <idea>` — Write a PRD
+
+Interactive interview to define a feature. Explores the codebase, asks scoping questions one at a time, designs deep modules, and writes a structured PRD.
+
+**Output:** `prds/<slug>.md`
+
+### `/tk:plan <slug>` — Create an implementation plan
+
+Reads a PRD and breaks it into phased **tracer-bullet vertical slices** — each phase is a thin but complete path through every layer (schema, service, API, UI, tests), demoable on its own.
+
+**Output:** `plans/<slug>.md`
+
+### `/tk:verify <slug>` — Verify and archive
+
+Read-only review that compares the codebase against the plan's done-when conditions. Runs tests, checks user stories, and stamps a **PASS** or **NEEDS_WORK** verdict. On PASS, automatically archives the PRD and plan to `archive/<slug>/`.
+
+**Output:** Verdict block in `plans/<slug>.md` — on PASS: `archive/<slug>/prd.md` + `archive/<slug>/plan.md`
+
+## Why TracerKit?
+
+Most planning tools produce horizontal task lists — nothing works until everything is done. TracerKit uses **tracer-bullet vertical slices** instead: 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.
+
+The term comes from [The Pragmatic Programmer](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/).
+
+### Compared to
+
+**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. 5 phases, Python setup, rigid phase gates. TracerKit is 3 phases, zero deps, automated verification.
+
+**vs. [Kiro](https://kiro.dev/)** (AWS) — Powerful but locked to a dedicated IDE. TracerKit works inside Claude Code with pure Markdown skills.
+
+**vs. [OpenSpec](https://github.com/Fission-AI/OpenSpec)** — Similar philosophy, broader tool support. TracerKit trades breadth (Claude Code only) for depth — native skill discovery, subagents for verification, and fewer artifacts.
+
+**vs. nothing** — AI coding without specs means vague prompts and lost context between sessions. TracerKit adds structure without ceremony.
+
+<details>
+<summary>Full comparison table</summary>
+
+|                  | Spec Kit         | Kiro                       | OpenSpec                | TracerKit                          |
+| ---------------- | ---------------- | -------------------------- | ----------------------- | ---------------------------------- |
+| **What it is**   | CLI + extensions | Agentic IDE (VS Code fork) | Slash-command framework | Claude Code skills (pure Markdown) |
+| **Setup**        | Python + uv      | Dedicated IDE              | npm + init              | `npx tracerkit init`               |
+| **Phases**       | 5                | 3                          | 3                       | 3 (prd, plan, verify)              |
+| **Artifacts**    | 4 files          | 3+ files                   | 4+ files                | 2 files (PRD, plan)                |
+| **Verification** | Manual gates     | Diff approval              | Manual                  | Automated PASS/NEEDS_WORK          |
+| **Tool lock-in** | Any AI assistant | Kiro IDE only              | Any AI assistant        | Claude Code only                   |
+| **Runtime deps** | Python + uv      | Proprietary IDE            | None                    | None                               |
+
+</details>
+
+## Examples
+
+<details>
+<summary>New feature from scratch</summary>
+
+```bash
+# 1. Define the feature
+/tk:prd add dark mode support
+
+# 2. Break into phased vertical slices
+/tk:plan dark-mode-support
+
+# 3. Implement each phase with Claude
+
+# 4. Verify — auto-archives on PASS
+/tk:verify dark-mode-support
+```
+
+</details>
+
+<details>
+<summary>Iterating on an accepted PRD</summary>
+
+PRDs are living documents — refine them any time before or during implementation.
+
+```bash
+# Re-run the PRD skill — it detects the existing file and asks
+# whether to start fresh or revise
+/tk:prd update dark mode to detect system preference
+
+# Regenerate the plan from the updated PRD
+/tk:plan dark-mode-support
+```
+
+</details>
+
+<details>
+<summary>Verify → fix → re-verify loop</summary>
+
+```bash
+# First verification attempt
+/tk:verify dark-mode-support
+# → NEEDS_WORK: missing toggle persistence, 2 failing tests
+
+# Fix the blockers, then re-verify
+/tk:verify dark-mode-support
+# → PASS — auto-archived to archive/dark-mode-support/
+```
+
+</details>
+
+<details>
+<summary>Development flow diagram</summary>
+
+```
+                         +------------------+
+                         |   Idea / Issue   |
+                         +--------+---------+
+                                  |
+                                  v
+                       +----------+----------+
+                       |  /tk:prd <idea>     |
+                       |  Interview + Design |
+                       +----------+----------+
+                                  |
+                              prds/<slug>.md
+                                  |
+                                  v
+                       +----------+----------+
+                       |  /tk:plan <slug>    |
+                       |  Vertical Slices    |
+                       +----------+----------+
+                                  |
+                             plans/<slug>.md
+                                  |
+                                  v
+                       +----------+----------+
+                       |   Implement phases  |
+                       |   (you + Claude)    |
+                       +----------+----------+
+                                  |
+                                  v
+                       +----------+----------+
+                       |  /tk:verify <slug>  |
+                       |  Review + archive   |
+                       +----------+----------+
+                                  |
+                         +--------+--------+
+                         |                 |
+                    NEEDS_WORK           PASS
+                         |                 |
+                         v                 v
+                  Fix blockers      Auto-archived
+                  then re-run       to archive/
+                  /tk:verify
+```
+
+</details>
+
+## Contributing
+
+1. Fork the repo and create a feature branch
+2. Use TracerKit itself to plan your change (`/tk:prd` + `/tk:plan`)
+3. Implement following the plan phases
+4. `npm run lint:fix && npm run test:run && npm run typecheck`
+5. [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitlint)
+6. Open a PR against `main`
+
+## License
+
+[MIT License](LICENSE) © [helderberto](https://helderberto.com)

package/dist/bin.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { n as e, r as t, t as n } from "./uninstall-BWCq5Ivr.js";
+import { resolve as r } from "node:path";
+import { homedir as i } from "node:os";
+//#region src/cli.ts
+var a = [
+	"Usage: tracerkit <command> [path]",
+	"",
+	"Commands:",
+	"  init [path]       Install skills (global by default, or to a project path)",
+	"  update [path]     Refresh files from latest version, skip modified files",
+	"  uninstall [path]  Remove TracerKit skills, keep user artifacts"
+];
+function o(e) {
+	let t = e.find((e) => !e.startsWith("-"));
+	return t ? r(t) : i();
+}
+function s(r) {
+	let i = r[0], s = r.slice(1);
+	switch (i) {
+		case "init": return t(o(s));
+		case "update": return e(o(s));
+		case "uninstall": return n(o(s));
+		default: return a;
+	}
+}
+//#endregion
+//#region src/bin.ts
+var c = s(process.argv.slice(2));
+for (let e of c) console.log(e);
+//#endregion

package/dist/index.js

@@ -0,0 +1,2 @@
+import { i as e, n as t, r as n, t as r } from "./uninstall-BWCq5Ivr.js";
+export { e as SKILL_NAMES, n as init, r as uninstall, t as update };

package/dist/uninstall-BWCq5Ivr.js

@@ -0,0 +1,77 @@
+import { existsSync as e, mkdirSync as t, readFileSync as n, readdirSync as r, rmSync as i, writeFileSync as a } from "node:fs";
+import { dirname as o, join as s } from "node:path";
+import { createHash as c } from "node:crypto";
+import { fileURLToPath as l } from "node:url";
+//#region src/templates.ts
+var u = [
+	"tk:prd",
+	"tk:plan",
+	"tk:verify"
+], d = s(o(l(import.meta.url)), "..", "templates");
+function f(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(...f(s(e, r.name), n)) : i.push(n);
+	}
+	return i.sort();
+}
+function p(e, r) {
+	let i = r ?? f(d);
+	for (let r of i) {
+		let i = s(d, r), c = s(e, r);
+		t(o(c), { recursive: !0 }), a(c, n(i));
+	}
+	return { copied: i };
+}
+function m(e) {
+	return c("sha256").update(e).digest("hex");
+}
+function h(t) {
+	let r = f(d), i = [], a = [], o = [];
+	for (let c of r) {
+		let r = s(t, c);
+		e(r) ? m(n(s(d, c))) === m(n(r)) ? i.push(c) : a.push(c) : o.push(c);
+	}
+	return {
+		unchanged: i,
+		modified: a,
+		missing: o
+	};
+}
+//#endregion
+//#region src/commands/init.ts
+function g(t) {
+	for (let n of u) if (e(s(t, ".claude", "skills", n))) throw Error(`.claude/skills/${n}/ already exists — aborting`);
+	let { copied: n } = p(t);
+	return n.map((e) => `✓ ${e}`);
+}
+//#endregion
+//#region src/commands/update.ts
+function _(t) {
+	if (!u.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — run `tracerkit init` first");
+	let { unchanged: n, modified: r, missing: i } = h(t), a = [], o = [...n, ...i];
+	if (o.length > 0) {
+		p(t, o);
+		for (let e of n) a.push(`✓ ${e}`);
+		for (let e of i) a.push(`✓ ${e} (added)`);
+	}
+	for (let e of r) a.push(`⚠ ${e} (skipped — modified)`);
+	return a;
+}
+//#endregion
+//#region src/commands/uninstall.ts
+function v(t) {
+	if (!u.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — nothing to uninstall");
+	let n = [];
+	for (let r of u) {
+		let a = s(t, ".claude", "skills", r);
+		e(a) && (i(a, {
+			recursive: !0,
+			force: !0
+		}), n.push(`✗ .claude/skills/${r}/ removed`));
+	}
+	return n;
+}
+//#endregion
+export { u as i, _ as n, g as r, v as t };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "tracerkit",
+  "version": "1.0.0",
+  "description": "Stack-agnostic spec-driven workflow for AI coding assistants",
+  "license": "MIT",
+  "author": {
+    "name": "helderberto",
+    "url": "https://github.com/helderberto"
+  },
+  "homepage": "https://github.com/helderberto/tracerkit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helderberto/tracerkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/helderberto/tracerkit/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "tracerkit": "dist/bin.js"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-workflow",
+    "spec-driven",
+    "tracer-bullet",
+    "developer-tools",
+    "markdown",
+    "plugin"
+  ],
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build",
+    "release": "semantic-release"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  },
+  "overrides": {
+    "lodash-es": "4.17.21"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.5.0",
+    "@commitlint/config-conventional": "20.5.0",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/git": "10.0.1",
+    "@types/node": "25.5.0",
+    "@vitest/coverage-istanbul": "4.1.2",
+    "eslint": "10.1.0",
+    "eslint-config-prettier": "10.1.8",
+    "husky": "9.1.7",
+    "lint-staged": "16.4.0",
+    "prettier": "3.8.1",
+    "semantic-release": "25.0.3",
+    "typescript": "6.0.2",
+    "typescript-eslint": "8.58.0",
+    "vite": "8.0.3",
+    "vitest": "4.1.2"
+  }
+}

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

@@ -0,0 +1,139 @@
+---
+description: Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved to plans/. Use after /tk:prd.
+argument-hint: '[slug]'
+disable-model-invocation: true
+---
+
+# PRD to Plan
+
+Break a PRD into phased vertical slices (tracer bullets). Output: `plans/<slug>.md`.
+
+## Pre-loaded context
+
+- Available PRDs: !`ls prds/ 2>/dev/null || echo "no prds/ directory found"`
+
+## Input
+
+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.
+
+## Workflow
+
+### 1. Read the PRD
+
+Read `prds/<slug>.md`. If it does not exist, list available PRDs and ask.
+
+If `plans/<slug>.md` already exists, tell the user and ask whether to overwrite or pick a new name.
+
+### 2. Explore the codebase
+
+Understand current architecture, existing patterns, and integration points.
+
+### 3. Identify durable architectural decisions
+
+Before slicing, extract decisions that hold across all phases:
+
+- Route structures / URL patterns
+- Database schema shape
+- Key data models and definitions
+- Auth/authorization approach
+- Third-party service boundaries
+
+### 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.
+
+**Deriving tasks from the PRD:**
+
+| PRD Section       | Becomes                                          |
+| ----------------- | ------------------------------------------------ |
+| New Modules       | Implement module with interface                  |
+| Schema Changes    | Migration + validation                           |
+| API Contracts     | Route returning shape                            |
+| Navigation        | Wire component to route                          |
+| User Stories      | Verify coverage; add task if missing             |
+| Testing Decisions | Tests land in the phase where their module lands |
+| Out of Scope      | Never create tasks for these                     |
+
+**Within each slice, order by dependency:** schema → service → API → UI → tests. Happy paths before edge cases.
+
+**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.
+
+**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.
+
+Assign an agent tag to tasks where appropriate:
+
+- `[agent:debugger]` — tracing a bug or unexpected runtime behavior
+- `[agent:test-auditor]` — writing or reviewing tests
+- `[agent:code-reviewer]` — reviewing API surfaces, interfaces, or public contracts
+
+### 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.
+
+### 6. Save plan
+
+Save to `plans/<slug>.md` (create `plans/` if missing).
+
+```markdown
+# Plan: <Feature Name>
+
+> Source PRD: `prds/<slug>.md`
+
+## Architectural Decisions
+
+Durable decisions that apply across all phases:
+
+- **Key decision**: ...
+
+---
+
+## Phase 1 — <Goal>
+
+**User stories**: <list from PRD>
+
+### What to build
+
+Concise description of this vertical slice — end-to-end behavior, not layer-by-layer.
+
+### Done when
+
+<Specific, testable condition>
+
+---
+
+<!-- Repeat for each phase -->
+
+## Out of Scope
+
+Carried forward from PRD verbatim.
+
+## Open Questions
+
+Gaps found in the PRD needing resolution. Blank if none.
+```
+
+Print saved path and one line per phase: `Phase N — <title> (<condition summary>)`.
+
+## Rules
+
+- 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
+- Never modify the source PRD
+- 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
+- `plans/` missing — create it

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

@@ -0,0 +1,118 @@
+---
+description: Create a PRD through user interview, codebase exploration, and module design, saved to prds/. Use when starting a new feature or change.
+argument-hint: <idea>
+disable-model-invocation: true
+---
+
+# PRD Writing
+
+Skip steps already satisfied. If user provided a description via arguments, skip to Step 2.
+
+## Input
+
+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, convert it to a kebab-case slug (lowercase, spaces and underscores replaced with hyphens). This is `<slug>`. The output file is `prds/<slug>.md`.
+
+If `prds/<slug>.md` already exists, tell the user and ask whether to overwrite or pick a new name.
+
+## Workflow
+
+### 1. Gather problem description
+
+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.
+
+### 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).
+
+Walk these branches (skip any already resolved):
+
+- **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?
+
+### 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.
+
+Signals of shallow design: many small functions with 1:1 query mapping, callers compose multiple calls, adding a feature requires changing the interface.
+
+Present modules to user. Confirm which need tests.
+
+### 5. Write PRD
+
+Save to `prds/<slug>.md` (create `prds/` if missing).
+
+```markdown
+# Feature Name
+
+## Problem Statement
+
+The problem from the user's perspective. Focus on pain and impact.
+
+## 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>
+
+## 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
+
+### 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.
+
+## 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.
+```
+
+Tell the user: file created, one-line summary, next step is `/tk:plan <slug>`.
+
+## Error Handling
+
+- `prds/` missing — create it
+- Scope larger than expected — surface and re-scope with user before continuing

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

@@ -0,0 +1,122 @@
+---
+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]'
+disable-model-invocation: true
+---
+
+# Verify Implementation
+
+Compare current implementation against a plan, stamp a verdict, and archive on PASS.
+
+## Pre-loaded context
+
+- Available plans: !`ls plans/ 2>/dev/null || echo "no 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 `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 `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 — archive
+
+If the verdict is **PASS**, automatically archive:
+
+1. Create `archive/<slug>/` directory (and `archive/` if missing)
+2. Move `prds/<slug>.md` → `archive/<slug>/prd.md`
+3. Move `plans/<slug>.md` → `archive/<slug>/plan.md`
+4. Append closing timestamp to `archive/<slug>/plan.md`:
+
+```markdown
+---
+
+## Archived
+
+- **Status**: closed
+- **Closed**: YYYY-MM-DD HH:MM (UTC)
+```
+
+5. Tell the user: archived to `archive/<slug>/`, one-line summary of the feature.
+
+If `archive/<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
+- `plans/` missing — tell user to run `/tk:plan` first
+- `archive/<slug>/` already exists — warn and ask whether to overwrite