tracerkit 1.4.2 → 1.4.4

package/README.md

@@ -8,15 +8,15 @@
 [![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 three-step spec process: from idea to verified, archived code.
 
-**Zero runtime dependencies** — pure Markdown skills, no build step.
+**Zero runtime dependencies.** Pure Markdown skills, no build step.
 
 </div>
 
 ## Why TracerKit?
 
-AI coding without specs means vague prompts and lost context between sessions. Most planning tools produce horizontal task lists — nothing works until everything is done.
+AI coding without specs means vague prompts and lost context between sessions. 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.
 
@@ -30,15 +30,25 @@ The term comes from [The Pragmatic Programmer](https://pragprog.com/titles/tpp20
 npx tracerkit init
 ```
 
-Skills are installed globally to `~/.claude/skills/` — available in every project, no per-project setup needed.
+Skills are installed globally to `~/.claude/skills/`, available in every project. No per-project setup needed.
 
 ### 2. Use the workflow
 
-```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
 ```
+You: /tk:prd add dark mode support
+AI:  ✓ Written .tracerkit/prds/dark-mode-support.md
+
+You: /tk:plan dark-mode-support
+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/
+```
+
+See [Examples](docs/examples.md) for full walkthroughs.
 
 <details>
 <summary>Per-project usage</summary>
@@ -59,224 +69,41 @@ npx tracerkit uninstall .         # remove project-scoped skills
 
 The three-step workflow that takes a feature from idea to verified archive.
 
-#### `/tk:prd <idea>` — Write a PRD
+#### `/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:** `.tracerkit/prds/<slug>.md`
 
-#### `/tk:plan <slug>` — Create an implementation plan
+#### `/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.
+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:** `.tracerkit/plans/<slug>.md`
 
-#### `/tk:verify <slug>` — Verify and archive
+#### `/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 `.tracerkit/archives/<slug>/`.
+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 `.tracerkit/archives/<slug>/`.
 
-**Output:** Verdict block in `.tracerkit/plans/<slug>.md` — on PASS: `.tracerkit/archives/<slug>/prd.md` + `.tracerkit/archives/<slug>/plan.md`
+**Output:** Verdict block in `.tracerkit/plans/<slug>.md`. On ✅ PASS: `.tracerkit/archives/<slug>/prd.md` + `.tracerkit/archives/<slug>/plan.md`
 
 ### Helper skills
 
-Useful but optional — this category will grow over time.
-
-#### `/tk:status` — Workflow dashboard
-
-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.
-
-## Examples
+Useful but optional. This category will grow over time.
 
-<details>
-<summary>New feature from scratch</summary>
-
-```
-You: /tk:prd add dark mode support
-AI:  Starting PRD interview...
-     ? What problem does this solve for users?
-     ? Should it detect system preference or manual toggle only?
-     ? Which components need theming?
-     ...
-     ✓ Written .tracerkit/prds/dark-mode-support.md
+#### `/tk:status`: Workflow dashboard
 
-You: /tk:plan dark-mode-support
-AI:  Reading PRD...
-     ✓ Phase 1 — CSS variables + ThemeProvider (schema → context → tests)
-     ✓ Phase 2 — Toggle component + localStorage (UI → persistence → tests)
-     ✓ Phase 3 — System preference detection (media query → sync → tests)
-     Written .tracerkit/plans/dark-mode-support.md
+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.
 
-You: # implement each phase with Claude...
+## Docs
 
-You: /tk:verify dark-mode-support
-AI:  Verifying against plan...
-     ✓ All done-when conditions met
-     ✓ Tests passing
-     PASS — archived to .tracerkit/archives/dark-mode-support/
-```
-
-</details>
-
-<details>
-<summary>Iterating on an accepted PRD</summary>
-
-```
-You: /tk:prd update dark mode to detect system preference
-AI:  Found existing .tracerkit/prds/dark-mode-support.md
-     ? Start fresh or revise the existing PRD?
-     ...
-     ✓ Updated .tracerkit/prds/dark-mode-support.md
-
-You: /tk:plan dark-mode-support
-AI:  Reading updated PRD...
-     ✓ Regenerated .tracerkit/plans/dark-mode-support.md with new scope
-```
-
-</details>
-
-<details>
-<summary>Verify → fix → re-verify loop</summary>
-
-```
-You: /tk:verify dark-mode-support
-AI:  Verifying against plan...
-     ✗ Missing toggle persistence in localStorage
-     ✗ 2 failing tests in ThemeProvider.test.ts
-     NEEDS_WORK — 2 blockers found
-
-You: # fix the blockers...
-
-You: /tk:verify dark-mode-support
-AI:  Verifying against plan...
-     ✓ All done-when conditions met
-     ✓ Tests passing
-     PASS — archived to .tracerkit/archives/dark-mode-support/
-```
-
-</details>
-
-<details>
-<summary>Check workflow status</summary>
-
-```
-You: /tk:status
-AI:  Feature Status Dashboard
-     ┌──────────────────────┬─────────────┬─────┐
-     │ Feature              │ Status      │ Age │
-     ├──────────────────────┼─────────────┼─────┤
-     │ dark-mode-support    │ in_progress │ 3d  │
-     │ api-rate-limiting    │ created     │ 1d  │
-     │ user-avatars         │ done        │ 7d  │
-     └──────────────────────┴─────────────┴─────┘
-```
-
-</details>
-
-## CLI Reference
-
-| Command                    | Description                                    |
-| -------------------------- | ---------------------------------------------- |
-| `tracerkit init`           | Install skills to `~/.claude/skills/`          |
-| `tracerkit init <path>`    | Install skills to a specific project directory |
-| `tracerkit update`         | Refresh to latest version, skip modified files |
-| `tracerkit update --force` | Replace modified files with latest versions    |
-| `tracerkit uninstall`      | Remove TracerKit skills, keep user artifacts   |
-| `tracerkit --version`      | Print version                                  |
-| `tracerkit --help`         | Show help message                              |
-
-All commands default to the home directory. Pass a path to target a specific project.
-
-## Configuration
-
-Artifacts are stored under `.tracerkit/` by default. To customize paths, create `.tracerkit/config.json`:
-
-```json
-{
-  "paths": {
-    "prds": ".tracerkit/prds",
-    "plans": ".tracerkit/plans",
-    "archives": ".tracerkit/archives"
-  }
-}
-```
-
-Any missing key falls back to its default. The file is optional — without it, all defaults apply. After changing config, run `tracerkit update` to regenerate skills with the new paths.
-
-## Metadata Lifecycle
-
-Each PRD carries YAML frontmatter that tracks its position in the workflow. The skills update it automatically — you never need to edit it by hand.
-
-**Fields:**
-
-- `created` — ISO 8601 UTC timestamp, set when the PRD is written
-- `status` — `created` | `in_progress` | `done`
-- `completed` — ISO 8601 UTC timestamp, set when verification passes
-
-**How it changes:**
-
-| Stage    | Skill               | Frontmatter                                          |
-| -------- | ------------------- | ---------------------------------------------------- |
-| Defined  | `/tk:prd`           | `created: 2025-06-15T14:30:00Z`<br>`status: created` |
-| Planning | `/tk:plan`          | `status: in_progress`                                |
-| Verified | `/tk:verify` (PASS) | `status: done`<br>`completed: 2025-06-20T09:00:00Z`  |
-
-<details>
-<summary>Example frontmatter at each stage</summary>
-
-After `/tk:prd`:
-
-```yaml
----
-created: 2025-06-15T14:30:00Z
-status: created
----
-```
-
-After `/tk:plan`:
-
-```yaml
----
-created: 2025-06-15T14:30:00Z
-status: in_progress
----
-```
-
-After `/tk:verify` (PASS):
-
-```yaml
----
-created: 2025-06-15T14:30:00Z
-status: done
-completed: 2025-06-20T09:00:00Z
----
-```
-
-</details>
-
-## 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>
+| Document                                         | Description                                         |
+| ------------------------------------------------ | --------------------------------------------------- |
+| [Examples](docs/examples.md)                     | End-to-end usage walkthroughs                       |
+| [CLI Reference](docs/cli-reference.md)           | All CLI commands and flags                          |
+| [Configuration](docs/configuration.md)           | Custom artifact paths via `config.json`             |
+| [Metadata Lifecycle](docs/metadata-lifecycle.md) | YAML frontmatter states and transitions             |
+| [Compared to](docs/compared-to.md)               | How TracerKit differs from Spec Kit, Kiro, OpenSpec |
 
 ## Contributing
 
@@ -291,6 +118,10 @@ completed: 2025-06-20T09:00:00Z
 
 For support, please [open a GitHub issue](https://github.com/helderberto/tracerkit/issues). We welcome bug reports, feature requests, and questions.
 
+## Acknowledgments
+
+This project was born out of [Claude Code for Real Engineers](https://www.aihero.dev/cohorts/claude-code-for-real-engineers-2026-04), a cohort by [Matt Pocock](https://github.com/mattpocock). The hands-on approach to building real things with Claude Code sparked the idea for TracerKit. If you're serious about AI-assisted engineering, I can't recommend Matt's cohorts and content highly enough.
+
 ## License
 
 [MIT License](LICENSE) © [helderberto](https://helderberto.com)

package/package.json

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

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

@@ -24,7 +24,7 @@ For each file `{{paths.prds}}/<slug>.md`:
 
 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
+- **Result**: ✅ PASS or 🚧 NEEDS_WORK
 - **BLOCKERS**: count
 - **SUGGESTIONS**: count
 

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

@@ -1,11 +1,11 @@
 ---
-description: Compare implementation against plan, emit BLOCKERS/SUGGESTIONS and a PASS or NEEDS_WORK verdict. Auto-archives on PASS. Use after implementing a plan.
+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.
+Compare current implementation against a plan, stamp a verdict, and archive on ✅ PASS.
 
 ## Pre-loaded context
 
@@ -38,13 +38,13 @@ Use a **read-only subagent** (no file writes, no edits) to:
 
 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.
+- **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
+- **✅ PASS** — zero BLOCKERS
+- **🚧 NEEDS_WORK** — one or more BLOCKERS
 
 ### 5. Report to user
 
@@ -53,7 +53,7 @@ Print the verdict report:
 ```
 ## Verification: <slug>
 
-### Verdict: PASS | NEEDS_WORK
+### Verdict: ✅ PASS | 🚧 NEEDS_WORK
 
 ### BLOCKERS
 - (list or "None")
@@ -71,7 +71,7 @@ Append a verdict block at the bottom of `{{paths.plans}}/<slug>.md`:
 
 ## Verdict
 
-- **Result**: PASS | NEEDS_WORK
+- **Result**: ✅ PASS | 🚧 NEEDS_WORK
 - **Date**: YYYY-MM-DD
 - **BLOCKERS**: (count)
 - **SUGGESTIONS**: (count)
@@ -79,9 +79,9 @@ Append a verdict block at the bottom of `{{paths.plans}}/<slug>.md`:
 
 If a previous verdict block exists, replace it with the new one.
 
-### 7. On PASS — update PRD status and archive
+### 7. On ✅ PASS — update PRD status and archive
 
-If the verdict is **PASS**:
+If the verdict is **✅ PASS**:
 
 **First**, update the YAML frontmatter in `{{paths.prds}}/<slug>.md`:
 
@@ -110,17 +110,17 @@ If the verdict is **PASS**:
 
 If `{{paths.archives}}/<slug>/` already exists, warn and ask whether to overwrite.
 
-### 8. On NEEDS_WORK
+### 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
+- 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
+- If the PRD file is missing but the plan has a ✅ PASS verdict, warn but proceed with archiving the plan only
 
 ## Error Handling