Core

Hybrid Task System

Sprint Summary

!node -e "try{const p=require('./prd.json');const sp=p.sprints?p.sprints[p.sprints.length-1]:p;const s=Object.values(sp.stories||p.stories||{});const name=sp.id||sp.name||p.sprint||'unknown';const n=f=>s.filter(f).length;const done=n(x=>x.passes===true);const pending=n(x=>x.passes===null||x.passes===undefined);const failed=n(x=>x.passes===false);const deferred=n(x=>x.passes==='deferred');const setup=n(x=>x.passes==='needs-setup');const other=s.length-done-pending-failed-deferred-setup;const arch=p.archived?(Number.isFinite(p.archived.totalCompleted)?' (+'+p.archived.totalCompleted+' archived)':' (archive present, count unreadable)'):'';console.log('Sprint:',name,'| Done:',done+arch,'| Pending:',pending,'| FAILED:',failed,'| Deferred:',deferred,'| Needs-setup:',setup,'| Total:',s.length,other?'| OTHER: '+other+' (unrecognised passes value)':'')}catch(e){console.log('No prd.json')}"

For large prd.json (100+ stories), use Grep to find specific stories. For typical sizes (<50 stories), reading the full file is fine with 1M context.

When to Sprint

• 5+ related tasks — create a sprint in prd.json
• < 5 tasks or single fixes — work directly, no sprint or stories needed
• Design/creative work — iterate freely, skip planning overhead
• Quick fixes — just fix, verify, done

Sprints are for tracking, not for ceremony. If the work is small, skip the overhead.

One layer, on purpose

prd.json is the task system. It is git-tracked, so sprint state survives /clear, compaction, a crash, and a week away — none of which the session-local task list survives.

The native task tools (TaskCreate/TaskUpdate/TaskList) were removed on Opus 4.8, Sonnet 5, and newer as of Claude Code 2.1.233, so do not plan around them. Track in-flight work in your own message to the user and write the outcome to prd.json.

prd.json Story Schema

{
  "id": "S26-001",
  "title": "Fix tooltip clipping",
  "priority": 1,
  "passes": null,
  "realness": null,
  "type": "fix",
  "category": "components",
  "notes": "",
  "resolution": ""
}

Realness Scale (0-100)

passes: true is binary and hides the difference between "wired up" and "works in production." Fill in realness when closing non-trivial stories so the sprint summary reflects reality.

Rules:

• Bug fixes default to 80 (fixing a real issue is usually production-ready).
• Features require a manual rating — don't auto-assign 100 just because passes: true.
• When in doubt, pick the lower number.
• Sprint summaries report the AVERAGE realness of closed stories, not just the pass count.

Resolution Learning

When completing bug fixes, document HOW:

[PATTERN]: [SPECIFIC FIX]

Examples:

• null-check: Added optional chaining at line 45
• missing-import: Added import for DateRange
• type-mismatch: Changed Record<string, T> to Partial<Record<K, T>>
• overflow: Added max-h + overflow-auto

Context Tips

With 1M context, aggressive token saving is unnecessary. Prefer clarity over brevity.

Archive Trigger

When ANY of these are true, run archive before starting new work:

• 4+ total sprints exist in prd.json
• prd.json > 500 lines
• prd.json > 50KB
• Starting a new sprint while previous sprint's stories are all complete

Do not ask — just archive. Archive keeps only last 3 sprints active. Completed stories move to .claude/archives/prd-archive-YYYY-MM.json.