trace-me-if-you-can

A Claude Code plugin that keeps a local trace.md memory of your project and syncs progress to three Notion databases — a Squad Backlog (user-value-level stories), a Squad AC (acceptance criteria, Given/When/Then), and a Squad TC (test cases, generated from Backlog + AC + your codebase). All three are linked back to Backlog rows.

All three databases use a fixed canonical column set — the plugin will refuse to set up against a database that's missing required columns or has the wrong types.

Manual-only, user-triggered. Inspired by gsd.

Install

npx [email protected]

That's it. One command, no Claude Code plugin marketplace dance. Re-run the same command any time to update. Restart Claude Code (or /reload) so the new /trace-* commands appear.

Installs at user level — ~/.claude/commands/ and ~/.claude/skills/trace-core/ — so the commands are available in every project.

To remove:

npx [email protected] --uninstall

Alternative: Claude Code plugin marketplace

If you prefer the native plugin flow (lets you manage it via /plugin):

/plugin marketplace add i4BSolutions/trace-me-if-you-can
/plugin install trace-me-if-you-can@trace-me-if-you-can

Pick one method — don't run both, you'll get duplicate commands.

Commands

| Command | What it does | |---|---| | /trace-profile | First-run setup. Asks for your project name, Notion token, all three database IDs (Backlog, AC, TC), and your Notion user ID. Verifies the DBs against the canonical schemas, writes trace.md, stores the token in .env. | | /trace | Re-scans the entire project, rewrites trace.md's Project Snapshot (Backlog + AC; preserves Test cases), creates/updates rows in the Backlog and AC DBs, appends a dated entry to the Progress Log. Every run is a full refresh of docs → Notion. | | /trace-tc | Generates Test Cases from the Backlog (excluding Rejected ones), the matching AC rows, and the codebase. Learns house style from existing TCs in the Notion TC DB. Syncs to Notion and updates the Test cases block in trace.md. | | /trace-progress | Reconciles trace.md with Notion across all three DBs. Mirrors live status into trace.md and cascade-drops Rejected backlogs (and their AC + TC lines) out of the local snapshot. Writes to trace.md, never to Notion. | | /trace-profile-check | Show the active profile without making Notion calls. | | /trace-profile-change | Swap the active Notion user ID (leaves token and DB IDs alone). | | /trace-update | Update the plugin to the latest version on npm. Re-runs npx trace-me-if-you-can-cc@latest, refreshing /trace-* commands and the trace-core skill in ~/.claude/. Does not touch trace.md or .env. |

Files the plugin touches in your project

• trace.md — the memory file, at project root. Human-readable, machine-parsed.
• .env — stores TRACE_NOTION_TOKEN. The plugin ensures .env is in .gitignore.

The env var name is TRACE_NOTION_TOKEN (not NOTION_TOKEN) to avoid colliding with other Notion integrations you may already have in the same project.

Notion requirements

1. Create a Notion internal integration. Copy its token.

2. Create (or pick) three databases in your workspace with these exact columns:

   Squad Backlog | Property | Type | |---|---| | Title | title | | Status | status | | Priority | status | | Project | select | | Epic | select | | Version | select | | Type | multi_select | | User Story | rich_text | | Develop By | people | | Create Time | created_time |

   Squad AC | Property | Type | |---|---| | ID | title | | Given | rich_text | | When | rich_text | | Then | rich_text | | Check | status | | User Story | relation → Squad Backlog | | Backlog Status | rollup (Status via User Story) | | Dev | rollup (Develop By via User Story) | | Project | rollup (Project via User Story) | | Epic | rollup (Epic via User Story) |

   Squad TC | Property | Type | |---|---| | ID | title | | Title | rich_text | | Preconditions | rich_text | | Test Steps | rich_text | | Test Data | rich_text | | Expected Result | rich_text | | Notes | rich_text | | Test Type | multi_select | | Priority | select | | Status | status | | User Story Ref | relation → Squad Backlog | | Epic | rollup (Epic via User Story Ref) | | Sprint | rollup | | Backlog Status | rollup (Status via User Story Ref) | | Project | rollup (Project via User Story Ref) | | Backlog Dev | formula (text) |

3. Share all three databases with the integration (Notion → database → ... → Connections → add your integration). Without this, every API call will 404 with object_not_found.

4. Add your project name as an option to the Backlog Project select before running /trace-profile — /trace will not auto-create select options.

5. Have your Notion user ID ready (Settings → Account → … → Copy link to profile → the UUID in the URL).

How trace.md works

trace.md is the plugin's memory — the same idea as GSD's .planning/ artifacts.

• Profile — project name, user ID, all three DB IDs. Rewritten atomically.
• Database Schemas — locked to the canonical column lists above. /trace-profile captures titles + select option lists; /trace refreshes option lists if they drift.
• Project Snapshot — current Backlog, AC, and Test cases with their Notion page IDs. /trace rewrites Backlog + AC; /trace-tc rewrites Test cases; /trace-progress rewrites all three with Notion as the source of truth, cascade-dropping Rejected backlogs and their children from the local snapshot.
• Progress Log — append-only, newest entry on top, dated.

/trace, /trace-tc, and /trace-progress all refuse to run without trace.md; that's by design — /trace-profile is the only bootstrap.

Security

• The Notion token is written to .env and never echoed in any command's output.
• The plugin ensures .env is git-ignored.
• All API responses that fail are surfaced verbatim — no silent retries.

License

MIT. Do what you want; no warranty.