tc-tracker
by alirezarezvanitc-tracker helps AI coding sessions create, update, validate, resume, and close repository-local Technical Change records in docs/TC/. Use it for structured issue-like change tracking, lifecycle status, test evidence, and handoff notes.
This skill scores 84/100, which means it is a solid listing candidate for directory users who want structured technical-change tracking and AI-session continuity. The repository provides enough workflow documentation, command examples, references, and scripts for an agent to execute with much less guesswork than a generic prompt, though users should note some packaging and command-surface gaps.
- Clear trigger guidance: the skill states when to use it for tracking technical changes, AI session handoffs, audit trails, and specific `/tc`-style requests, plus when not to use it.
- Operationally concrete: README quick start provides runnable Python commands for initializing tracking, creating a TC, updating status/files, writing handoff context, and checking status.
- Real reusable implementation: five Python scripts plus schema, lifecycle, and handoff references support structured JSON records, state transitions, registry/status views, and validation.
- The SKILL.md has no explicit install command, so users may need directory tooling or manual copying to know where the scripts should live.
- The description mentions resume/close/export workflows, but the visible script set covers init/create/update/status/validation rather than dedicated resume, close, or export commands.
Overview of tc-tracker skill
What tc-tracker is for
tc-tracker is an engineering skill for structured Technical Change tracking: it helps an AI agent create, update, validate, resume, and close JSON change records under docs/TC/ in a project. Instead of relying on chat memory, loose notes, or commit messages, it records what changed, why, affected files, test evidence, status, blockers, and session handoff context.
Best-fit users and projects
The tc-tracker skill is a strong fit for teams using AI coding sessions that may span multiple chats, handoffs, or review cycles. It is especially useful when you need issue-like tracking for implementation work, audit trails for code changes, or repeatable status summaries across feature, bugfix, refactor, infrastructure, documentation, hotfix, and enhancement work.
Key differentiators for Issue Tracking
Unlike a generic “make an issue tracker” prompt, tc-tracker comes with a concrete storage layout, a TC ID convention, an append-only revision history model, validation scripts, and a lifecycle state machine. It is not a replacement for GitHub Issues or Jira; it is closer to a repository-local implementation log that connects code files, tests, decisions, and AI handoff notes.
When not to use tc-tracker
Avoid tc-tracker for trivial typo fixes, formatting-only edits, or one-off changelog generation from git history. It also may be too heavy if your project already enforces a mature issue workflow and you do not want additional JSON records in the repository.
How to Use tc-tracker skill
tc-tracker install and first files to read
Install the skill in a compatible skills environment with:
npx skills add alirezarezvani/claude-skills --skill tc-tracker
Then inspect the source directory at engineering/skills/tc-tracker. Read SKILL.md first for agent trigger rules and workflow, README.md for script examples, then references/lifecycle.md, references/tc-schema.md, and references/handoff-format.md. The Python helpers in scripts/ are practical assets, not just examples.
Initialize tracking in a project
The core tc-tracker usage starts by creating a repository-local tracking area:
python3 scripts/tc_init.py --project "My Project" --root .
This creates docs/TC/ with configuration, registry, records, and evidence locations. The initializer is idempotent, so rerunning it should report existing state rather than duplicating the setup. Run it from the target project root or pass an explicit --root /path/to/project.
Create and update a Technical Change
A strong first prompt gives the agent enough information to create a valid record without guessing:
Use tc-tracker to create a TC for adding JWT authentication. Project root is
.. Scope isfeature, priority ishigh. Summary: add login endpoint, JWT signing, and auth middleware. Motivation: protected API routes need authenticated access. Initial files likely affected:src/auth.py,src/middleware.py,tests/test_auth.py.
The corresponding script flow looks like:
python3 scripts/tc_create.py --root . \
--name "user-auth" \
--title "Add JWT authentication" \
--scope feature --priority high \
--summary "Adds JWT login endpoint, signing, and middleware" \
--motivation "Required for protected API endpoints"
python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
--set-status in_progress --reason "Starting implementation"
As work progresses, add affected files, test cases, decisions, and status changes rather than waiting until the end.
Use handoff and status commands well
The highest-value tc-tracker guide habit is writing a useful handoff before a session ends. Include concrete progress, next steps small enough to execute, blockers, decisions, and files in progress:
python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
--handoff-progress "Implemented JWT signing and wired middleware into router" \
--handoff-next "Add integration test for invalid token returning 401" \
--handoff-blocker "Need final test fixture shape for user records"
Check work with:
python3 scripts/tc_status.py --root . --all
python3 scripts/tc_validator.py --root .
For a resume prompt, ask the agent to read docs/TC/records/<TC-ID>/tc_record.json, especially session_context.handoff, then continue from the recorded next steps.
tc-tracker skill FAQ
Is tc-tracker a full issue tracker?
No. tc-tracker for Issue Tracking is repository-local and change-focused. It tracks implementation state, files, tests, decisions, and handoff context. Use GitHub Issues, Linear, or Jira for team assignment, discussion, labels, boards, and external stakeholder workflow.
What makes it better than an ordinary prompt?
An ordinary prompt can summarize work, but it usually does not enforce schema, lifecycle transitions, append-only revisions, or a repeatable directory layout. tc-tracker gives the AI agent a durable format and scripts for creating, updating, validating, and listing change records.
Is tc-tracker beginner-friendly?
Yes, if you are comfortable running Python scripts and committing JSON files. Beginners should start with README.md quick-start commands and avoid manually editing TC JSON until they understand references/tc-schema.md and references/lifecycle.md.
What can block adoption?
The main adoption cost is process overhead. Every meaningful change needs a TC record, status updates, and good handoff text. If your team will not maintain those records, the registry can become stale. The skill works best when TC updates are part of the coding workflow, not an afterthought.
How to Improve tc-tracker skill
Give tc-tracker stronger inputs
tc-tracker performs best when your prompt includes project root, change goal, scope, priority, motivation, likely files, test expectations, and current uncertainty. Weak input says “track auth work.” Strong input says “create a high-priority feature TC for JWT auth, affecting these files, with tests for valid token, invalid token, and missing token.”
Keep lifecycle transitions realistic
Respect the state machine: planned, in_progress, blocked, implemented, tested, and deployed. Do not mark a TC as tested without test evidence, and do not skip from early planning directly to deployed. If work regresses, move back to in_progress with a reason.
Improve handoff quality after each session
The most common failure mode is vague handoff text. Replace “finish tests” with specific actions such as “Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q.” Include blockers only when they are actively preventing progress, and record decisions with rationale so the next AI session does not re-litigate them.
Iterate with validation and review
After the first output, run status and validator scripts, then ask the agent to fix missing fields, invalid transitions, stale file lists, or weak test evidence. For better long-term results, review references/tc-schema.md and tune your prompts so every TC contains review-ready summaries, affected files, test cases, and session context before it is closed.