2d1f0d2b53
Self-contained skill for tracking technical changes with structured JSON records, an enforced state machine, and a session handoff format that lets a new AI session resume work cleanly when a previous one expires. Includes: - 5 stdlib-only Python scripts (init, create, update, status, validator) all supporting --help and --json - 3 reference docs (lifecycle state machine, JSON schema, handoff format) - /tc dispatcher in commands/tc.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
# TC Tracker
|
|
|
|
Structured tracking for technical changes (TCs) with a strict state machine, append-only revision history, and a session-handoff block that lets a new AI session resume in-progress work cleanly.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Initialize tracking in your project
|
|
python3 scripts/tc_init.py --project "My Project" --root .
|
|
|
|
# 2. Create a new TC
|
|
python3 scripts/tc_create.py --root . \
|
|
--name "user-auth" \
|
|
--title "Add JWT authentication" \
|
|
--scope feature --priority high \
|
|
--summary "Adds JWT login + middleware" \
|
|
--motivation "Required for protected endpoints"
|
|
|
|
# 3. Move it to in_progress and record some work
|
|
python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
|
|
--set-status in_progress --reason "Starting implementation"
|
|
|
|
python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
|
|
--add-file src/auth.py:created \
|
|
--add-file src/middleware.py:modified
|
|
|
|
# 4. Write a session handoff before stopping
|
|
python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
|
|
--handoff-progress "JWT middleware wired up" \
|
|
--handoff-next "Write integration tests" \
|
|
--handoff-blocker "Waiting on test fixtures"
|
|
|
|
# 5. Check status
|
|
python3 scripts/tc_status.py --root . --all
|
|
```
|
|
|
|
## Included Scripts
|
|
|
|
- `scripts/tc_init.py` — Initialize `docs/TC/` in a project (idempotent)
|
|
- `scripts/tc_create.py` — Create a new TC record with sequential ID
|
|
- `scripts/tc_update.py` — Update fields, status, files, handoff, with atomic writes
|
|
- `scripts/tc_status.py` — View a single TC or the full registry
|
|
- `scripts/tc_validator.py` — Validate a record or registry against schema + state machine
|
|
|
|
All scripts:
|
|
- Use Python stdlib only
|
|
- Support `--help` and `--json`
|
|
- Use exit codes 0 (ok) / 1 (warnings) / 2 (errors)
|
|
|
|
## References
|
|
|
|
- `references/tc-schema.md` — JSON schema reference
|
|
- `references/lifecycle.md` — State machine and transitions
|
|
- `references/handoff-format.md` — Session handoff structure
|
|
|
|
## Slash Command
|
|
|
|
When installed with the rest of this repo, the `/tc <subcommand>` slash command (defined at `commands/tc.md`) dispatches to these scripts.
|
|
|
|
## Installation
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
cp -R engineering/tc-tracker ~/.claude/skills/tc-tracker
|
|
```
|
|
|
|
### OpenAI Codex
|
|
|
|
```bash
|
|
cp -R engineering/tc-tracker ~/.codex/skills/tc-tracker
|
|
```
|