ticket-track
Frontmatter-based Ticket tracking system. Provides two core capabilities: (1) READ operations for querying ticket info without loading full files - use query/list/summary commands, (2) UPDATE operations for agents to track progress without reporting back - use claim/complete/release commands. Eliminates need for agents to report progress to main thread.
When & Why to Use This Skill
Ticket Track is a specialized frontmatter-based ticket tracking system optimized for AI agent workflows. It enables autonomous task management by allowing agents to update ticket statuses (pending, in-progress, completed) directly within Markdown files using YAML frontmatter. This system significantly reduces context window usage by providing lightweight READ and UPDATE operations, eliminating the need for agents to report progress back to the main thread and ensuring a streamlined, single-file architecture for project oversight.
Use Cases
- Autonomous Task Management: Agents can independently claim, update, and complete tickets using CLI commands, reducing the need for manual status reporting in the conversation.
- Context-Efficient Status Monitoring: Users can query specific ticket statuses or generate project-wide summaries without loading entire documentation files, saving valuable context tokens.
- Multi-Agent Coordination: Prevents redundant work in multi-agent environments by providing a clear, file-based 'source of truth' for task assignments and real-time progress.
- Legacy System Integration: Offers backward compatibility with older CSV-based tracking systems, allowing teams to reference historical data while migrating to modern Markdown-based workflows.
| name | ticket-track |
|---|---|
| description | "Frontmatter-based Ticket tracking system. Provides two core capabilities: (1) READ operations for querying ticket info without loading full files - use query/list/summary commands, (2) UPDATE operations for agents to track progress without reporting back - use claim/complete/release commands. Eliminates need for agents to report progress to main thread." |
Ticket Track
Frontmatter-based Ticket status tracking - eliminates the need to read full files or ask agents for progress.
Core Design
Main Thread Ticket Frontmatter Agent
| | |
| READ (query/list) | |
|-------------------------->| |
|<--------------------------| |
| (direct read) | |
| | |
| | UPDATE (claim/complete)
| |<-----------------------|
| | (direct write) |
Key Benefits:
- No need to read full ticket files for status
- No need to ask agents for progress
- Minimal context consumption
- Single file architecture (status in frontmatter)
Frontmatter Status Fields
Status is tracked directly in each Ticket's YAML frontmatter:
---
# ... other fields ...
# === Status Tracking ===
status: "pending" # pending | in_progress | completed
assigned: false # true if someone claimed
started_at: null # ISO 8601 timestamp
completed_at: null # ISO 8601 timestamp
---
| Field | Type | Description |
|---|---|---|
status |
string | "pending", "in_progress", "completed" |
assigned |
boolean | Whether someone has claimed the ticket |
started_at |
datetime | When work started (ISO 8601, e.g., 2025-12-27T10:30:00) |
completed_at |
datetime | When work completed (ISO 8601) |
READ Operations (Main Thread / Any Role)
Query ticket info without loading full files.
Query Single Ticket
uv run .claude/hooks/ticket-tracker.py query 0.16.0-W1-001 --version v0.16.0
Output: Status, agent, action+target, 5W1H from frontmatter.
List Tickets by Status
# All tickets
uv run .claude/hooks/ticket-tracker.py list --version v0.16.0
# Filter by status
uv run .claude/hooks/ticket-tracker.py list --in-progress --version v0.16.0
uv run .claude/hooks/ticket-tracker.py list --pending --version v0.16.0
uv run .claude/hooks/ticket-tracker.py list --completed --version v0.16.0
Quick Summary
# Auto-detect version
uv run .claude/hooks/ticket-tracker.py summary
# Specify version
uv run .claude/hooks/ticket-tracker.py summary --version v0.16.0
Output Example:
📊 Ticket Summary v0.16.0 (2/34 completed) [markdown]
----------------------------------------------------------------------------------------------------
0.16.0-W1-001 | ✅ | parsley | Fix ISBNValidator.validate() format validation
0.16.0-W1-002 | 🔄 | parsley | Implement ISBNScannerService.startScan() (1h30m)
0.16.0-W1-003 | ⏸️ | parsley | Implement ISBNScannerService result handling
UPDATE Operations (Agent Use)
Update status without reporting back to main thread.
Claim Ticket (Before Starting)
uv run .claude/hooks/ticket-tracker.py claim 0.16.0-W1-001 --version v0.16.0
Updates frontmatter:
assigned: truestarted_at: [current ISO timestamp]status: "in_progress"
Output:
✅ Claimed 0.16.0-W1-001
Start Time: 2025-12-27T10:30:00
Complete Ticket (After Finishing)
uv run .claude/hooks/ticket-tracker.py complete 0.16.0-W1-001 --version v0.16.0
Updates frontmatter:
status: "completed"completed_at: [current ISO timestamp]
Output:
✅ Completed 0.16.0-W1-001 (1h30m)
Release Ticket (If Unable to Continue)
uv run .claude/hooks/ticket-tracker.py release 0.16.0-W1-001 --version v0.16.0
Updates frontmatter:
assigned: falsestarted_at: nullstatus: "pending"
Output:
✅ Released 0.16.0-W1-001
Status Icons
| Icon | Status | Condition |
|---|---|---|
| ⏸️ | Pending | status: "pending" |
| 🔄 | In Progress | status: "in_progress" |
| ✅ | Completed | status: "completed" |
Backward Compatibility (v0.15.x CSV Format)
The tracker supports read-only access to old CSV-format tickets for historical reference.
How It Works
When querying older versions (v0.15.x), the system:
- Auto-detects format: Checks for
tickets/directory (Markdown) ortickets.csv(CSV) - Falls back to CSV: If Markdown tickets not found, reads from CSV
- Display warning: Shows read-only notice for CSV format
Example
uv run .claude/hooks/ticket-tracker.py summary --version v0.15.16
Output:
⚠️ v0.15.16 uses old CSV format (read-only mode)
Status update commands (claim/complete/release) not supported in v0.15.x
Please upgrade to v0.16.0+ for new Markdown Ticket system
📊 Ticket Summary v0.15.16 (15/34 completed) [csv]
----------------------------------------------------------------------------------------------------
...
Limitations
| Operation | v0.16.0+ (Markdown) | v0.15.x (CSV) |
|---|---|---|
summary |
✅ Full support | ✅ Read-only |
list |
✅ Full support | ✅ Read-only |
query |
✅ Full support | ⚠️ Limited |
claim |
✅ Full support | ❌ Not supported |
complete |
✅ Full support | ❌ Not supported |
release |
✅ Full support | ❌ Not supported |
Best Practices
Main Thread
- DON'T ask agents for progress → Use
summarycommand - DON'T read ticket files for status → Use
querycommand - DO run
summaryregularly for overview
Agents
- DON'T report progress to main thread → Use
completecommand - DO run
claimbefore starting - DO run
completeafter finishing
File Structure
docs/work-logs/
├── v0.16.0/ # New version (Markdown format)
│ └── tickets/
│ ├── 0.16.0-W1-001.md # Ticket with frontmatter
│ ├── 0.16.0-W1-002.md
│ └── ...
├── v0.15.16/ # Old version (CSV format, read-only)
│ ├── tickets.csv # Legacy CSV tracking
│ └── ...
Related Skills
/ticket-create- Create Atomic Tickets interactively
Resources
Scripts
.claude/hooks/ticket-tracker.py- Main tracking script.claude/hooks/frontmatter_parser.py- Frontmatter parsing module
References
.claude/methodologies/frontmatter-ticket-tracking-methodology.md- Full methodology.claude/methodologies/csv-ticket-tracking-methodology.md- Legacy CSV methodology (deprecated)