/workflow-status

name: workflow-status
user-invocable: true
version: 3.7.0
author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
license: MIT
argument-hint: "[--json-only] [--last-envelope <json|path>]"
description: >
  Read-only workflow sensor: run the deterministic script, read the fixed
  machine envelope, interpret the recommendation. Never edits. Triggers:
  "workflow-status", "workflow status", "what can I build next".

Workflow Status (the orchestrator's sensor)

One read-only pass that answers, in a single fixed JSON envelope: **what exists, what is blocked on what, what is startable right now, and what the recommended next command is.** The **script is the deterministic producer**: `scripts/workflow-status.mjs` executes the published `SENSOR_CORE` sequence (steps 1–9 including 6a) and prints the envelope. This skill runs the script, reads the JSON, interprets it against the references below, and prints the human report — it never assembles the envelope by hand.

Turn contract — verify before ending the turn

✓ The script was RUN — `bun scripts/workflow-status.mjs [--json-only]
  [--last-envelope <json|path>]` (node is the fallback when bun is absent, per
  the repository's runtime convention); the envelope is the script's stdout, never
  assembled by the model
✓ Nothing was edited, committed, pushed, or created — read-only, always
✓ `next.recommended` is non-bare (carries the unit's slug/NN, never a bare
  `/plan-feature`) AND the script computed it from the unit's resolved status
  **and** its current pre-execution evidence: `idea`/undesigned →
  `/design-feature <slug>`; `defined` → `/plan-feature <slug>` only on a current
  `SPEC-REVIEW-PASS`, else `/review-spec <slug>`; `planned`/`in-progress` → `/execute-phase <NN>` only on a
  current `PLAN-REVIEW-PASS`, else `/review-plan <NN>` (step 6a)
✓ `detail.crash_recovery` carries a verdict from the decision table and the
  envelope `state` matches it (CLEAN→OK, RESUMABLE→CONTINUE,
  AMBIGUOUS→NEEDS_INPUT)
✓ Every `detail.design_candidates[].next` begins with `/design-feature `
✓ Every degraded dimension is named in `detail.degradations` as
  `unavailable-<source>-<cause>` — and, when `--last-envelope` was supplied, the
  no-progress guard's `workflow_observations` note is present (never a silently
  repeated bland recommendation)
✓ The envelope is emitted on **every** invocation, including a same-session
  natural-language follow-up about state — never replaced by prose
✓ The human-readable summary is printed, then the machine envelope (the script's
  JSON) is the ABSOLUTE last output

With `--json-only`, skip the human-readable summary: print the envelope alone.

When to use

• Between orchestration steps: an external driver runs it to decide the next

command and model tier without parsing prose.

• Before picking work manually: "what can I start right now?"
• **Not** for judging quality (`review-change`/`audit-pr`) or product health

(`product-audit`) — this skill reports state, it never judges.

Step 0 — Discover the project (always first)

Per the agent guide's **Workflow conventions** + **documentation map**. The script reads what THIS skill needs (`docs/features/ROADMAP.md`, the fix index `docs/fix/README.md`, every in-flight feature folder's `TASKS.md` + `progress.md` + `review-findings.md`, and `docs/workflow/REPOSITORY_STATE.md`); read them yourself only to interpret a field the script emitted.

Progressive loading — fixed sensor route

The reference allowlist is exactly the seven linked paths below. Never invent or read another `references/` path. This skill is a read-only sensor.

1. [sensor core](references/SENSOR_CORE.md) — the sequence the script executes 2. [crash recovery](references/CRASH_RECOVERY.md) 3. [envelope core](references/ENVELOPE_CORE.md) 4. [envelope fields](references/ENVELOPE_FIELDS.md) 5. [pre-execution evidence](references/PRE_EXECUTION.md) 6. [guardrails](references/GUARDRAILS.md)

Add [sensor signals](references/SENSOR_SIGNALS.md) only when a unit, issue, finding, or recommendation exists; an empty project skips that file but still emits the empty shapes defined by envelope fields. Add [portability](references/PORTABILITY.md) only when the platform actually lacks a named primitive. `--json-only` does not skip any baseline file.

Portability

The sensor uses repository and forge commands only. When a named agent feature is unavailable, follow [portability](references/PORTABILITY.md) without changing the JSON contract.

Relationship to other skills

• The **sensor** counterpart to `ship-roadmap`'s conductor: an external

orchestrator calls `workflow-status` → routes on the envelope → invokes `plan-feature` / `execute-phase` / `review-change` / `audit-pr` / `triage-issue` directly, choosing the model per step — the same loop without the in-agent autopilot.

• Read-only sibling of `audit-docs` (which judges coherence and can fix) and

`product-audit` (which judges health): this one only reports state.

• Schema owner: `orchestration-envelope` (internal).

Done when

• The script ran and every claim in the report comes from its envelope — nothing

inferred from memory, nothing assembled by hand.

• `detail.design_candidates`, `detail.features`, `detail.fixes`,

`detail.startable_now`, `detail.blocked_units`, `detail.open_prs`, `detail.untriaged_issues`, `detail.urgent`, `detail.degradations`, and `detail.crash_recovery` were read from the envelope, and the envelope `state` matches the crash-recovery verdict.

• With `--last-envelope` supplied: the no-progress guard ran — a stalled

`/plan-feature`/`/design-feature` hint surfaces as a `workflow_observations` note, never a silent bland repeat, with no new write path introduced.

• The human summary (unless `--json-only`) and the envelope are printed, envelope

last.

• Nothing was modified anywhere.
• When the envelope carries `next.continuation`, the next-command echo **quotes the

emitted `next.continua