tracerkit 1.19.2 → 1.19.4

package/README.md

@@ -29,7 +29,7 @@ DEFINE          PLAN           BUILD            VERIFY
   │               │               │                 │
   ▼               ▼               ▼                 ▼
 PRD doc       Phased plan    Implement phase    Pass/fail
-                              + feedback loops   + status
+                              + feedback loops
 ```
 
 ## Get Started
@@ -125,17 +125,17 @@ AI:  Phase 1 — Theme visible end-to-end (3 remaining)
      Implementing... all checks pass. Commit?
 
 You: /tk:check dark-mode-support
-AI:  Status: done | Total: 5/5
-     Marked complete in .tracerkit/prds/dark-mode-support.md
+AI:  Total: 7/7
+     All phases complete — implementation verified.
 ```
 
 Between sessions, `/tk:brief` shows active features and picks up where you left off:
 
 ```
 You: /tk:brief
-AI:  | Feature           | Status      | Age | Progress | Next                         |
-     |-------------------|-------------|-----|----------|------------------------------|
-     | dark-mode-support | in_progress | 3d  | 3/7      | Toggle component renders ... |
+AI:  dark-mode-support (3/7)
+       Phase 1 — Theme visible end-to-end: 3/3
+     > Phase 2 — User can toggle and persist preference: 0/4
 
      **Focus → dark-mode-support**
 ```
@@ -144,26 +144,25 @@ See [Examples](docs/examples.md) for full walkthroughs.
 
 ## Skills
 
-| Skill              | What it does                                           | Output                                              |
-| ------------------ | ------------------------------------------------------ | --------------------------------------------------- |
-| `/tk:prd <idea>`   | Interview → codebase scan → structured PRD             | `.tracerkit/prds/<slug>.md`                         |
-| `/tk:plan <slug>`  | PRD → phased vertical slices, each demoable on its own | `.tracerkit/plans/<slug>.md`                        |
-| `/tk:build <slug>` | Implement next incomplete phase, run feedback loops    | Code changes + checked items in plan                |
-| `/tk:brief`        | Feature dashboard with progress and suggested focus    | Terminal only, no files                             |
-| `/tk:check [slug]` | Verify done-when checkboxes against codebase and tests | Verdict block in plan, status updated when all pass |
+| Skill              | What it does                                           | Output                               |
+| ------------------ | ------------------------------------------------------ | ------------------------------------ |
+| `/tk:prd <idea>`   | Interview → codebase scan → structured PRD             | `.tracerkit/prds/<slug>.md`          |
+| `/tk:plan <slug>`  | PRD → phased vertical slices, each demoable on its own | `.tracerkit/plans/<slug>.md`         |
+| `/tk:build <slug>` | Implement next incomplete phase, run feedback loops    | Code changes + checked items in plan |
+| `/tk:brief`        | Feature dashboard with progress and suggested focus    | Terminal only, no files              |
+| `/tk:check [slug]` | Verify done-when checkboxes against codebase and tests | Checkboxes updated in plan           |
 
 ## Docs
 
-| Document                                         | Description                                        |
-| ------------------------------------------------ | -------------------------------------------------- |
-| [Examples](docs/examples.md)                     | Walk through end-to-end usage scenarios            |
-| [CLI Reference](docs/cli-reference.md)           | Commands: init, update, uninstall                  |
-| [Metadata Lifecycle](docs/metadata-lifecycle.md) | Understand YAML frontmatter states and transitions |
-| [Comparison](docs/comparison.md)                 | Compare TracerKit to Spec Kit, Kiro, and OpenSpec  |
-| [Cursor Setup](docs/cursor-setup.md)             | Use TracerKit skills in Cursor                     |
-| [Gemini CLI Setup](docs/gemini-cli-setup.md)     | Use TracerKit skills in Gemini CLI                 |
-| [Copilot Setup](docs/copilot-setup.md)           | Use TracerKit skills in GitHub Copilot             |
-| [OpenCode Setup](docs/opencode-setup.md)         | Use TracerKit skills in OpenCode                   |
+| Document                                     | Description                                       |
+| -------------------------------------------- | ------------------------------------------------- |
+| [Examples](docs/examples.md)                 | Walk through end-to-end usage scenarios           |
+| [CLI Reference](docs/cli-reference.md)       | Commands: init, update, uninstall                 |
+| [Comparison](docs/comparison.md)             | Compare TracerKit to Spec Kit, Kiro, and OpenSpec |
+| [Cursor Setup](docs/cursor-setup.md)         | Use TracerKit skills in Cursor                    |
+| [Gemini CLI Setup](docs/gemini-cli-setup.md) | Use TracerKit skills in Gemini CLI                |
+| [Copilot Setup](docs/copilot-setup.md)       | Use TracerKit skills in GitHub Copilot            |
+| [OpenCode Setup](docs/opencode-setup.md)     | Use TracerKit skills in OpenCode                  |
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracerkit",
-  "version": "1.19.2",
+  "version": "1.19.4",
   "description": "Spec-driven workflow for AI coding agents — PRD → plan → build → verify. Pure Markdown skills, zero runtime deps.",
   "license": "MIT",
   "author": {

package/skills/brief/SKILL.md

@@ -8,47 +8,37 @@ Overview of active features, progress, and suggested focus.
 
 ## Pre-loaded context
 
-- Available PRDs: !`ls .tracerkit/prds/*.md 2>/dev/null || echo "(none)"`
+- Available plans: !`ls .tracerkit/plans/*.md 2>/dev/null || echo "(none)"`
 
 ## Algorithm
 
-### 1. Discover features
+### 1. Discover plans
 
-For each `.md` file in `.tracerkit/prds/`: parse frontmatter, extract `status` and `created`. Skip `status: done`. Slug = filename without `.md`.
+Glob `.tracerkit/plans/*.md`. Slug = filename without `.md`. If no plans found, output: `No plans found — run /tk:prd to start one.`
 
-### 2. Count progress from plans
+### 2. Count progress
 
-For each slug with a plan at `.tracerkit/plans/<slug>.md`:
+For each plan, count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Per-phase: `checked/total`. Sum across phases → total progress. First phase with unchecked items → cursor.
 
-Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Sum → `checked/total`. First unchecked item → "Next" (strip trailing `[tag]`). No plan → `—`.
+Skip plans where all items are checked (fully complete).
 
-### 3. Build the table
+### 3. Show progress
 
-Sort by `created` ascending (no-date last). 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:
+For each incomplete plan:
 
 ```
-| Feature | Status | Age | Progress | Next |
-|---------|--------|-----|----------|------|
-| <slug>  | <status> | <age> | <checked>/<total> | <next item> |
+<slug> (checked/total)
+  Phase 1 — title: checked/total
+> Phase 2 — title: checked/total
+  Phase 3 — title: checked/total
 ```
 
-If no features found, output: `No features found — run /tk:prd to start one.`
-
-### 4. Determine focus
-
-Apply these rules in order:
+The `>` marks the first incomplete phase (cursor). Completed phases show without `>`.
 
-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
+### 4. Suggest focus
 
-Append below the table:
+If exactly one incomplete plan → auto-select it.
+If multiple incomplete plans → select the one closest to completion.
 
 ```
 **Focus → <slug>**
@@ -58,6 +48,6 @@ Append below the table:
 
 Present options and wait for the user's choice:
 
-1. Continue focused feature — read plan at `.tracerkit/plans/<slug>.md` (Recommended)
+1. Continue focused feature — `/tk:build <slug>` (Recommended)
 2. Start new feature — `/tk:prd`
 3. Check progress — `/tk:check <slug>`

package/skills/check/SKILL.md

@@ -1,11 +1,11 @@
 ---
-description: Verify implementation against plan. Shows progress, finds blockers, and marks complete when done. Use after implementing a plan, or without arguments to see a feature dashboard.
+description: Verify implementation against plan. Shows progress and finds blockers. Use after implementing a plan.
 argument-hint: '[slug]'
 ---
 
 # Check Implementation
 
-Check implementation against a plan. Update checks, stamp findings, transition status, and mark complete when done.
+Verify plan checkboxes against the codebase. Unmark items that don't hold up (`[x]` → `[ ]`).
 
 **Interactive prompts**: present options as a numbered list and wait for the user's choice.
 
@@ -17,23 +17,9 @@ Check implementation against a plan. Update checks, stamp findings, transition s
 
 The argument (if provided) is: $ARGUMENTS
 
-Use the argument as `<slug>` if given.
+Use the argument as `<slug>` if given. Accepts slug or `@file` reference.
 
-If no argument is provided, build a summary table before asking which one to check:
-
-```markdown
-| Feature | Status | Progress |
-| ------- | ------ | -------- |
-| <slug>  | ...    | 3/7      |
-```
-
-For each `.md` file in `.tracerkit/prds/`:
-
-1. Read the file, parse YAML frontmatter (block between `---` fences)
-2. Extract `status` — use `unknown` if missing
-3. If `.tracerkit/plans/<slug>.md` exists, count progress (see Progress Algorithm below). Show `—` if no plan.
-
-Present each feature as a numbered option and wait for the user's choice.
+If no argument is provided, list available plans as numbered options and wait for the user's choice.
 
 ## Progress Algorithm
 
@@ -45,57 +31,48 @@ Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Per-phase: `Pha
 
 Read `.tracerkit/plans/<slug>.md`. If missing, list plans as numbered options and wait for the user's choice.
 
-### 2. Load the PRD
-
-Read source PRD referenced in plan header (`> Source PRD: ...`).
+### 2. Fast-path: check if implementation exists
 
-### 3. Fast-path: check if implementation exists
+If primary module file(s) from Phase 1 don't exist, skip subagent — report `0/N — not yet started`, list Phase 1 done-when items.
 
-If primary module file(s) from Phase 1 don't exist, skip subagent — report `0/N — not yet started`, list Phase 1 done-when items, jump to Step 5.
+### 3. Launch read-only review
 
-### 3b. Launch read-only review
-
-Use a **general-purpose subagent** (not `code-review` — that agent is for PR reviews). The subagent must be **read-only** (no file writes, no edits). It should:
+Use a **general-purpose subagent** (not `code-review`). The subagent must be **read-only** (no file writes, no edits). It should:
 
 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 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.
+3. Run the project's test suite and include pass/fail results
+4. For each checkbox, determine whether it should be checked (`[x]`) or unchecked (`[ ]`)
 
 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`.
-
-### 3c. Update checkboxes
+- **BLOCKERS** — checked items that don't hold up, failing tests, broken contracts
+- **SUGGESTIONS** — improvements, minor gaps, style issues
 
-Using the subagent's report, update each checkbox in `.tracerkit/plans/<slug>.md` to `[x]` or `[ ]`.
+### 4. Update checkboxes
 
-### 4. Determine outcome
+Using the subagent's report, update each checkbox in `.tracerkit/plans/<slug>.md`:
 
-Based on checks and findings, decide the status transition:
+- Items that pass verification → `[x]`
+- Items that fail verification → `[ ]` (unmark)
 
-- 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
+### 5. Report
 
 Count progress per phase (Progress Algorithm), then print:
 
-```markdown
+```text
 ## Verification: <slug>
 
-### Status: created | in_progress | done
-
 ### Progress
 
-Phase 1 — title: checked/total
-Phase 2 — title: checked/total
-Total: checked/total
+  Phase 1 — title: checked/total
+> Phase 2 — title: checked/total
+  Total: checked/total
+```
 
+The `>` marks the first incomplete phase (cursor).
+
+```text
 ### BLOCKERS
 
 - (list or "None")
@@ -105,41 +82,18 @@ Total: checked/total
 - (list or "None")
 ```
 
-### 6. Stamp the plan
-
-Append a verdict block at the bottom of `.tracerkit/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` — mark complete
-
-If all checks pass and zero BLOCKERS:
-
-1. Update PRD frontmatter: `status: done`, add `completed: <UTC ISO 8601>`
-2. Update plan frontmatter: `status: done`, add `completed: <UTC ISO 8601>`
+If all items verified (total checked = total):
 
-### 8. On `in_progress` (no blockers)
+> All phases complete — implementation verified.
 
-Show progress summary (checked/total per phase), list the next unchecked items to implement. Keep going.
+### 6. Next steps
 
-### 9. On `in_progress` (with blockers)
+If blockers exist, list items to fix, then re-run `/tk:check <slug>`.
 
-List the blockers to fix, then re-run `/tk:check <slug>`.
+If all items verified, suggest creating a PR or shipping.
 
 ## 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 status updates on `done`
+- The only file writes this skill makes are: checkbox updates in the plan
 - Never modify implementation code — only observe and report
-- If the PRD file is missing but all checks pass, warn and proceed — mark the plan complete only (skip PRD status update)

package/skills/plan/SKILL.md

@@ -32,10 +32,6 @@ If `.tracerkit/plans/<slug>.md` exists, present options and wait:
 1. Overwrite existing (Recommended)
 2. Pick a new name
 
-### 1b. Update PRD status
-
-Set `status: in_progress` in `.tracerkit/prds/<slug>.md` frontmatter. Change only `status`.
-
 ### 2. Explore the codebase
 
 Map architecture, patterns, integration points. Skip if codebase context exists from prior step.
@@ -107,19 +103,9 @@ Iterate until approved.
 Save to `.tracerkit/plans/<slug>.md` (create dir if missing).
 
 ```markdown
----
-source_prd: .tracerkit/prds/<slug>.md
-slug: <slug>
-status: in_progress
----
-
 # Plan: <Feature Name>
-
-> Source PRD: `.tracerkit/prds/<slug>.md`
 ```
 
-Then update PRD frontmatter: add `plan: .tracerkit/plans/<slug>.md` field (creates backlink).
-
 Use this structure for the plan body:
 
 ```markdown
@@ -173,5 +159,5 @@ To implement this plan phase by phase, run `/tk:build <slug>`. It handles branch
 - 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 content — only update frontmatter status fields
+- Never modify the source PRD content
 - Carry PRD's Out of Scope forward verbatim

package/skills/prd/SKILL.md

@@ -74,11 +74,6 @@ Present modules. Confirm which need tests.
 Save to `.tracerkit/prds/<slug>.md` (create dir if missing).
 
 ```markdown
----
-created: <UTC ISO 8601>
-status: created
----
-
 # Feature Name
 ```