claude-skills-reference/engineering/tc-tracker/references/tc-schema.md

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	yes	Freeform tags
related_tcs	array	yes	Cross-references
notes	string	yes	Freeform notes
metadata	object	yes	See below

description

{
  "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)

{
  "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)

{
  "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)

{
  "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

{
  "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

{
  "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

{
  "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)

{
  "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.