artifact-tracking

name	artifact-tracking
description	Token-efficient tracking for AI orchestration. CLI-first for status updates (~50 tokens), agent fallback for complex ops (~1KB). Use when: updating task status, querying blockers, creating progress files, validating phases.

Artifact Tracking Skill

Token-efficient tracking artifacts for AI agent orchestration.

Quick Operations (CLI First)

Operation	Command	Tokens
Mark complete	python scripts/update-status.py -f FILE -t TASK-X -s completed	~50
Batch update	python scripts/update-batch.py -f FILE --updates "T1:completed,T2:completed"	~100
Query pending	python scripts/query_artifacts.py --status pending	~50
Validate	python scripts/validate_artifact.py -f FILE	~50

Scripts location: .claude/skills/artifact-tracking/scripts/

Agent Operations (When Needed)

For complex operations requiring judgment:

Operation	Agent	When to Use
CREATE file	artifact-tracker	New phase, need template
UPDATE complex	artifact-tracker	Blockers with context, decisions
QUERY synthesis	artifact-query	Cross-phase analysis, handoffs
VALIDATE quality	artifact-validator	Pre-completion checks

Agent invocation:

Task("artifact-tracker", "Create Phase 2 progress for auth-overhaul PRD")
Task("artifact-query", "Show all blocked tasks in auth-overhaul phases 1-3")

File Locations

Type	Location	Limit
Progress	.claude/progress/[prd]/phase-N-progress.md	ONE per phase
Context	.claude/worknotes/[prd]/context.md	ONE per PRD
Bug fixes	.claude/worknotes/fixes/bug-fixes-YYYY-MM.md	ONE per month
Observations	.claude/worknotes/observations/observation-log-MM-YY.md	ONE per month

Policy: .claude/specs/doc-policy-spec.md

YAML Format (Source of Truth)

---
type: progress
prd: "prd-name"
phase: 2
status: in_progress
progress: 40

tasks:
  - id: "TASK-2.1"
    status: "pending"           # pending|in_progress|completed|blocked
    assigned_to: ["agent-name"] # REQUIRED for orchestration
    dependencies: []            # REQUIRED for orchestration
    model: "opus"               # Optional: opus|sonnet|haiku

parallelization:
  batch_1: ["TASK-2.1", "TASK-2.2"]  # Run parallel
  batch_2: ["TASK-2.3"]              # After batch_1
---

Token Efficiency

Operation	Traditional	Optimized	Savings
Task list	25KB	2KB	92%
Query blockers	75KB	3KB	96%
Status update	25KB	50 bytes	99.8%

Detailed References

• Creating files: ./creating-artifacts.md
• Updating tasks: ./updating-artifacts.md
• Querying data: ./querying-artifacts.md
• Validating: ./validating-artifacts.md
• Orchestration: ./orchestration-reference.md
• Best practices: ./best-practices.md
• Common patterns: ./common-patterns.md
• Format spec: ./format-specification.md
• Templates: ./templates/
• Schemas: ./schemas/