alirezarezvani/claude-skills / engineering/skills/tc-tracker
tc-tracker
VerifiedUse when tracking technical changes as records, or handing work between AI sessions with a change record. Creates, updates and validates change records with tc_create.py, tc_update.py and tc_validator.py.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.2 KB |
| SKILL.md | skill md | 10.0 KB |
| references/handoff-format.md | markdown | 5.2 KB |
| references/lifecycle.md | markdown | 3.9 KB |
| references/tc-schema.md | markdown | 5.3 KB |
| scripts/tc_create.py | script | 9.7 KB |
| scripts/tc_init.py | script | 6.7 KB |
| scripts/tc_status.py | script | 7.2 KB |
| scripts/tc_update.py | script | 13.8 KB |
| scripts/tc_validator.py | script | 13.9 KB |
references/tc-schema.md
View on GitHub# TC Record Schema
A TC record is a JSON object stored at `docs/TC/records/<TC-ID>/tc_record.json`. Every record is validated against this schema and a state machine on every write.
## Top-Level Fields
| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `tc_id` | string | yes | Pattern: `TC-NNN-MM-DD-YY-slug` |
| `parent_tc` | string \| null | no | For sub-TCs only |
| `title` | string | yes | 5-120 characters |
| `status` | enum | yes | One of: `planned`, `in_progress`, `blocked`, `implemented`, `tested`, `deployed` |
| `priority` | enum | yes | `critical`, `high`, `medium`, `low` |
| `created` | ISO 8601 | yes | UTC timestamp |
| `updated` | ISO 8601 | yes | UTC timestamp, refreshed on every write |
| `created_by` | string | yes | Author identifier (e.g., `user:micha`, `ai:claude-opus`) |
| `project` | string | yes | Project name (denormalized from registry) |
| `description` | object | yes | See below |
| `files_affected` | array | yes | See below |
| `revision_history` | array | yes | Append-only, sequential `R<n>` IDs |
| `sub_tcs` | array | no | Child TCs |
| `test_cases` | array | yes | Sequential `T<n>` IDs |
| `approval` | object | yes | See below |
| `session_context` | object | yes | See below |
| `tags` | array<string> | yes | Freeform tags |
| `related_tcs` | array<string> | yes | Cross-references |
| `notes` | string | yes | Freeform notes |
| `metadata` | object | yes | See below |
## description
```json
{
"summary": "string (10+ chars)",
"motivation": "string (1+ chars)",
"scope": "feature|bugfix|refactor|infrastructure|documentation|hotfix|enhancement",
"detailed_design": "string|null",
"breaking_changes": ["string", "..."],
"dependencies": ["string", "..."]
}
```
## files_affected (array of objects)
```json
{
"path": "src/auth.py",
"action": "created|modified|deleted|renamed",
"description": "string|null",
"lines_added": "integer|null",
"lines_removed": "integer|null"
}
```
## revision_history (array of objects, append-only)
```json
{
"revision_id": "R1",
"timestamp": "2026-04-05T12:34:56+00:00",
"author": "ai:claude-opus",
"summary": "Created TC record",
"field_changes": [
{
"field": "status",
"action": "set|changed|added|removed",
"old_value": "planned",
"new_value": "in_progress",
"reason": "Starting implementation"
}
]
}
```
**Rules:**
- IDs are sequential: R1, R2, R3, ... no gaps allowed.
- The first entry is always the creation event.
- Existing entries are NEVER modified or deleted.
## test_cases (array of objects)
```json
{
"test_id": "T1",
"title": "Login returns JWT for valid credentials",
"procedure": ["POST /login", "with valid creds"],
"expected_result": "200 + token in body",
"actual_result": "string|null",
"status": "pending|pass|fail|skip|blocked",
"evidence": [
{
"type": "log_snippet|screenshot|file_reference|command_output",
"description": "string",
"content": "string|null",
"path": "string|null",
"timestamp": "ISO|null"
}
],
"tested_by": "string|null",
"tested_date": "ISO|null"
}
```
## approval
```json
{
"approved": false,
"approved_by": "string|null",
"approved_date": "ISO|null",
"approval_notes": "string",
"test_coverage_status": "none|partial|full"
}
```
**Consistency rule:** if `approved=true`, both `approved_by` and `approved_date` MUST be set.
## session_context
```json
{
"current_session": {
"session_id": "string",
"platform": "claude_code|claude_web|api|other",
"model": "string",
"started": "ISO",
"last_active": "ISO|null"
},
"handoff": {
"progress_summary": "string",
"next_steps": ["string", "..."],
"blockers": ["string", "..."],
"key_context": ["string", "..."],
"files_in_progress": [
{
"path": "src/foo.py",
"state": "editing|needs_review|partially_done|ready",
"notes": "string|null"
}
],
"decisions_made": [
{
"decision": "string",
"rationale": "string",
"timestamp": "ISO"
}
]
},
"session_history": [
{
"session_id": "string",
"platform": "string",
"model": "string",
"started": "ISO",
"ended": "ISO",
"summary": "string",
"changes_made": ["string", "..."]
}
]
}
```
## metadata
```json
{
"project": "string",
"created_by": "string",
"last_modified_by": "string",
"last_modified": "ISO",
"estimated_effort": "trivial|small|medium|large|epic|null"
}
```
## Registry Schema (`tc_registry.json`)
```json
{
"project_name": "string",
"created": "ISO",
"updated": "ISO",
"next_tc_number": 1,
"records": [
{
"tc_id": "TC-001-...",
"title": "string",
"status": "enum",
"scope": "enum",
"priority": "enum",
"created": "ISO",
"updated": "ISO",
"path": "records/TC-001-.../tc_record.json"
}
],
"statistics": {
"total": 0,
"by_status": { "planned": 0, "in_progress": 0, "blocked": 0, "implemented": 0, "tested": 0, "deployed": 0 },
"by_scope": { "feature": 0, "bugfix": 0, "refactor": 0, "infrastructure": 0, "documentation": 0, "hotfix": 0, "enhancement": 0 },
"by_priority": { "critical": 0, "high": 0, "medium": 0, "low": 0 }
}
}
```
Statistics are recomputed on every registry write. Never edit them by hand.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |