state-tracker

state-tracker

.claude/state/spec.json is a one-file aggregate of the project's spec/issue/PR work pipeline. It exists so an LLM (or human) can answer "what's currently in flight, and against which spec?" with a single Read — no find over .claude/spec/ plus per-file frontmatter parse.

Ships with the dev plugin; install via marketplace. Operates on the current repo's .claude/state/spec.json.

SSOT relationship

Source	Authority	When it wins
.claude/spec/*.md frontmatter (status:)	SSOT	Always — the spec file is the truth
.claude/state/spec.json	aggregate cache	Faster lookup; if it conflicts with frontmatter, regenerate from frontmatter

The cache is regeneratable any time via init (scan spec dir + frontmatter aggregate). Direct edits are allowed but rare — prefer the 4 ops below.

Schema (versioned JSON)

{
  "schema": 1,
  "updated_at": "<ISO 8601>",
  "in_progress": [
    {
      "spec": ".claude/spec/<YYYY-MM-DD>-<slug>.md",
      "section": "<spec internal anchor, optional>",
      "linked": { "issue": <number or null>, "pr": <number or null> },
      "description": "<spec 'Goal' first line, or user-provided one-liner>"
    }
  ],
  "completed": [
    {
      "spec": ".claude/spec/<YYYY-MM-DD>-<slug>.md",
      "linked": { "issue": <number or null>, "pr": <number or null> },
      "description": "<same as above>",
      "completed_at": "<YYYY-MM-DD>",
      "merge_sha": "<short SHA, 7 chars>"
    }
  ]
}

Operations

read — print current state

1. If .claude/state/spec.json does not exist → print empty state ({ "in_progress": [], "completed": [] }) and inform the user. Do NOT auto-create; ask if they want init.
2. Read and pretty-print. Highlight in_progress first.

init — regenerate from spec frontmatter (one-shot)

1. Confirm with user (AskUserQuestion) — this overwrites the file. Default: cancel.
2. find .claude/spec -maxdepth 1 -name '*.md' -not -name '_template.md'.
3. For each spec file, parse YAML frontmatter (best effort):
   • status: draft | in-progress | merged → bucket selection
   • ## Goal first non-empty line → description
   • Optional issue: / pr: keys → linked
4. Write .claude/state/spec.json with schema: 1 and updated_at = now.
5. Print summary: N in-progress, M completed.