tracerkit 1.6.1 → 1.7.1

package/README.md

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

package/package.json

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

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

@@ -41,13 +41,17 @@ Read `{{paths.plans}}/<slug>.md`. If it does not exist, list available plans and
 
 Read the source PRD referenced in the plan header (`> Source PRD: ...`).
 
-### 3. Launch read-only review
+### 3. Fast-path: check if implementation exists
+
+Before launching a subagent, check whether the primary module file(s) from Phase 1 exist. If none exist, skip the subagent entirely and report `0/N — not yet started`. List Phase 1's "Done when" items as next steps and jump to Step 5.
+
+### 3b. 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
+3. Run the project's test suite (e.g., `npm test`, `npx vitest run`) and include pass/fail results in the report. If no test command is discoverable, note this.
 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.
@@ -57,7 +61,7 @@ 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
+### 3c. Update checkboxes
 
 Using the subagent's report, update each checkbox in `{{paths.plans}}/<slug>.md` to `[x]` or `[ ]`.
 

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

@@ -33,7 +33,7 @@ If the PRD has no frontmatter, skip this step silently.
 
 ### 2. Explore the codebase
 
-Understand current architecture, existing patterns, and integration points.
+Understand current architecture, existing patterns, and integration points. If you already have codebase context from a prior step in this conversation (e.g., you just ran `/tk:prd`), skip the exploration and note which context you're reusing.
 
 **Research protocol**: codebase first, then project docs. If you cannot verify a technical claim from these sources, flag it as uncertain — never fabricate.
 
@@ -132,7 +132,7 @@ Carried forward from PRD verbatim.
 Gaps found in the PRD needing resolution. Blank if none.
 ```
 
-Print saved path and one line per phase: `Phase N — <title> (<condition summary>)`.
+Print saved path and one line per phase: `Phase N — <title> (<condition summary>)`. Then ask: "Run `/tk:check <slug>` when ready?"
 
 ## Rules
 
@@ -140,7 +140,7 @@ Print saved path and one line per phase: `Phase N — <title> (<condition summar
 - Each phase must be demoable end-to-end on its own
 - "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
+- Never modify the source PRD content — only update frontmatter status fields
 - Carry PRD's Out of Scope forward verbatim
 
 ## Error Handling

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

@@ -7,13 +7,17 @@ argument-hint: <idea>
 
 Skip steps already satisfied. If user provided a description via arguments, skip to Step 2.
 
+## Pre-loaded context
+
+- Existing PRDs: !`ls {{paths.prds}}/ 2>/dev/null || echo "none"`
+
 ## 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 `{{paths.prds}}/<slug>.md`.
+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 `{{paths.prds}}/<slug>.md` already exists, tell the user and ask whether to overwrite or pick a new name.
 
@@ -33,7 +37,7 @@ 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):
+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):
 
 - **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?
@@ -124,6 +128,8 @@ Long numbered list. Cover happy path, edge cases, error states.
 
 Do NOT include file paths or code snippets — they go stale.
 
+Omit any section whose content would be "None required" — only include sections with actual content.
+
 ## Testing Decisions
 
 - What makes a good test (behavior, not implementation)
@@ -136,7 +142,7 @@ Do NOT include file paths or code snippets — they go stale.
 Explicit list. Be specific — vague exclusions invite scope creep.
 ```
 
-Tell the user: file created, one-line summary, next step is `/tk:plan <slug>`.
+Tell the user: file created, one-line summary. Then ask: "Run `/tk:plan <slug>` next?"
 
 ## Error Handling