work-state

The scope chain's lifecycle-state driver. One question — where is this slug, and what's next? — answered as structured data computed from the filesystem, not narrated. The chain keeps real per-slug state on disk (vision / spec+INDEX / plan+spec-pin / blueprint / archive); /work-state <slug> reads that state and reports it the same way every time, machine-checked.

Governed by leverage-over-ceremony: replace the multi-directory hand-walk ("list specs, read INDEX, check the plan's pin, infer execute from recap") with one command, instant answer. The expensive part (is an artefact's content good enough) stays the model's/human's job — /work-state does only the cheap, deterministic part.

Where it sits. /checkpoint asks is it good; /work-state asks where is it / what's next. /update-changelog records what shipped (past); /work-state reports where in-flight work stands (present). /close-out closes a slug; /work-state reports when a slug has reached the close. Distinct lenses — /work-state is the one that's purely positional and purely deterministic.

When to run

• User types /work-state <slug> or /status <slug> (explicit).
• User asks "where is <slug> in the chain", "what's the next step for <slug>", "is <slug>'s plan stale", "did I ever execute <slug>".
• Do not auto-fire. Mode A, user-invoked. Read-only — it never writes, never mutates an artefact (the one inviolable property; see "What it does NOT do").

The chain and its dependency graph

The fixed stage order and what each stage depends on (the graph the resolver computes over):

Dependencies are enablers, not gates — the report never forbids skipping a stage; it only computes readiness.

Procedure (deterministic — no model call for any of this)

1. Resolve paths and the slug

• Base: $CLAUDE_PROJECT_DIR/.claude/ (cwd fallback if the env var is unset), same as every chain skill.
• /work-state <slug> → use the slug. /work-state with no slug → resolve per draft-plan's canonical slug-resolution cascade (draft-plan SKILL.md § Forms), asking which when several are active (single-slug v1; no fleet view — that's /coordinate's territory).

2. Detect each stage's status

Walk the trees and classify each stage as missing / present / stale / done / blocked:

• vision — .claude/visions/<slug>/ has an active version → present (it's a soft upstream; absence is not a blocker). Else missing.
• spec — read .claude/specs/INDEX.md for the slug's Current active version.
  • No row / no active version → missing.
  • Active version present, done_criteria_provisional: true (or status: draft) → present (exists but not promotable).
  • Active version present with an open question tagged blocks: plan → present, gap: "open questions block the plan: <count>", plus "questionnaire waiting: <file>" for each questionnaire-*.md in the slug folder.
  • Active version present with firm done_criteria → done (the spec is ready to build against).
  • Record the active spec version vM — the plan-staleness check needs it.
• plan — .claude/plans/<slug>/ active version (via .claude/plans/INDEX.md).
  • Spec missing → plan is blocked (gap: "no spec").
  • No active plan → missing.
  • Active plan present, read its spec: frontmatter pin (../../specs/<slug>/v<K>.md → version vK). A plan whose spec: is none (the --task convention) is exempt from the stale-pin check — report it present with the note "task plan, no spec pin." Otherwise compare vK to the spec's active vM:
    • vK == vM → present.
    • vK < vM → stale — the load-bearing finding. Name it: "plan pins spec v<K>, active spec is v<M>."
• blueprint — .claude/docs/<slug>/ active version present → present (optional stage; its absence is never a blocker, never the next: action unless explicitly asked). Apply the same spec-pin staleness if the blueprint records a pin. Else missing (and not blocked — it's optional).
• execute — has no versioned artefact. v1 is honest about this: report execute as not inspectable from artefacts unless a clear external signal exists (an .claude/archive/<date>-<slug>/ implies execute completed → done; a recap or git mention of the slug's completion may be cited as a soft signal, never asserted as fact). Default: present? with the note "execute leaves no versioned file — confirm from recap/git." Never guess done.
• archive — .claude/archive/<date>-<slug>/ exists → done (the chain is closed; close-out ran). Else missing.

3. Compute the next action and blockers

• Short-circuit first: if archive is done, the chain is closed — emit next: — chain closed for <slug>; nothing pending. and stop. Close-out retires the plan and blueprint on purpose, so their now-missing/stale state is the expected end state, not work to redo. Never propose /draft-plan (or any upstream stage) for a closed slug.
• next action = the first stage in chain order whose upstream dependency is satisfied (done/present) and whose own artefact is missing or stale. Emit its command + the reason:
  • spec missing → next: /spec <slug>
  • spec done, plan missing → next: /draft-plan <slug>
  • plan stale → next: /draft-plan <slug> (spec v<M> active, plan pins v<K> — stale)
  • plan present, execute not done → next: /execute <slug>
  • execute done, archive missing → next: /close-out <slug>
  • archive done → next: — chain closed for <slug>.
  • (blueprint, being optional, is offered as a secondary suggestion when plan is present and blueprint missing — never the primary next:.)
• blockers = every stage marked blocked, with its gap ("blueprint blocked: no plan" only when the user explicitly asks about the blueprint; otherwise optional stages are silent).

4. Render the report

Work state — <slug>

| Stage      | Status   | Detail                                              |
|------------|----------|-----------------------------------------------------|
| vision     | missing  | —                                                   |
| spec       | done     | v2 active (3 done-criteria)                         |
| plan       | stale    | pins spec v1, active spec is v2                     |
| blueprint  | missing  | optional                                            |
| execute    | —        | leaves no versioned file — confirm from recap/git   |
| archive    | missing  | —                                                   |

next: /draft-plan <slug>  (spec v2 active, plan pins v1 — stale)
blockers: none

Keep it compact. The table + the next: line + the blockers line are the whole output. No prose narration of what the stages mean — the user reading /work-state wants the state, not an essay.

What /work-state does NOT do

• Does not write or mutate anything. Read-only — no file is created, edited, moved, or deleted. This is the one inviolable property; if a future need wants a mutation (e.g. fixing a stale pin), that is /draft-plan's job, offered via the next: line, never done here.
• Does not judge content quality. v1 reports structural state (exists / stale-pin / next-ready), not whether an artefact is good enough. Content-adequacy ("the plan covers 2 of the spec's 5 criteria") is a fenced v2 question — and /checkpoint's lens, not this one.
• Does not gate or lock the workflow. It reports readiness; it never forbids skipping a stage. Dependencies are enablers, not gates.
• Does not guess execute-done. Execute leaves no versioned artefact; v1 says so honestly rather than inventing a status. Only an archive folder (or an explicit user/recap confirmation) upgrades execute to done.
• Does not call the model for the structural state. Stage detection, version-pin comparison, and ready-gap are pure filesystem logic.
• Does not track a fleet. Single-slug; the multi-slug session view is /coordinate's territory.
• Does not auto-fire. Mode A, user-invoked.

Relationship to other organs

• spec done-criteria / draft-plan spec-pin — supply the contracts the resolver reads: the spec's active version (specs INDEX) and the plan's pinned version (spec: frontmatter). The stale-pin check is their consistency, surfaced.
• archive (close-out) — the chain's close; /work-state reports archive: done when .claude/archive/<date>-<slug>/ exists. They bracket the chain (work-state = where are you, close-out = close it out).
• update-changelog — records completed work (past); /work-state reports in-flight state (present). The pair answers "what shipped / where's the active work" — the two halves of session re-alignment.
• checkpoint — orients over a slug for fit/intent audit; /work-state reports chain position. checkpoint asks "is it good," /work-state asks "where is it / what's next." Standalone (not folded into checkpoint or discover — the fast-path ergonomics want one dedicated command).
• discover — shares slug-path resolution conventions; /work-state stays a separate command.
• execute — /work-state's stale-pin check is most valuable as a pre-run guard (execute warning on a plan pinned to a superseded spec). That is a deferred v2 seam — named in execute's relationships, not built in v1; v1 ships the standalone report only.
• coordinate — a multi-slug /work-state would overlap coordinate's session board; kept single-slug to stay clear of it.
• Leverage over ceremony — the resolver is one deterministic command replacing the multi-directory hand-walk.