spacedock-dev/spacedock/fo-status-viewer

First Officer Status Viewer

Status Viewer

The ${SPACEDOCK_BIN:-spacedock} status launcher owns path resolution and mutation guards; skill instructions stay declarative and never reference a plugin-private script path.

Invoke it as:

${SPACEDOCK_BIN:-spacedock} status --workflow-dir {workflow_dir} [--page N|--limit N|--next-id|--next|--archived|--where ...|--boot|--validate|--resolve REF]

• --boot — startup roll-up (mods, ID style, next-ID candidate, orphans, PR state, dispatchables). Incompatible with --next, --next-id, --archived, --where.
• --validate — run before trusting manually edited workflow state.
• --resolve REF — deterministic lookup by slug, exact stored ID, or sd-b32 address prefix; --root rejects unqualified cross-workflow ambiguity rather than guessing.
• --next-id — preview the next-id candidate for sequential and sd-b32 (n/a for slug). For sd-b32, pass --id-seed "{slug-or-title}" and optionally --id-actor "{actor-or-agent}" so creation context enters the candidate. To file a new entity, do NOT pair --next-id with a hand-written file — use spacedock new under the eagerly loaded «write.classify» contract, which mints the id and atomically writes the stamped entity in one call. --next-id is candidate-preview only.
• --where <field>=<value> — THE entity query. One clause per flag; repeat

the flag to AND clauses (--where sprint=X --where 'sprint-readiness!=defer'). Two clauses in one string is an error, not an AND. field!= means non-empty, field= means empty. Unknown field names are a loud error listing the known fields. Known fields are this workflow's frontmatter keys plus the canonical set: id slug status title score source worktree pr started completed verdict mod-block archived issue. Never find/grep the state dir — query it.

• --next — dispatchable entities.

The --set flag updates entity frontmatter fields:

• --set {slug} field=value sets a field
• --set {slug} field= clears a field
• --set {slug} started or completed auto-fills a UTC ISO 8601 timestamp (skipped if already set)
• a field with a schema conventional list (today: verdict, [PASSED REJECTED]) is closed on write — any other token is refused byte-clean; --force bypasses. Clearing always passes. To supersede an entity, clear verdict and --archive it.

Captain-Facing State Display

The commissioned README directs the captain to dispatch the FO to inspect workflow state. Invoke status for captain-facing display on questions like:

• "what's the workflow state?" / "show me the workflow" / "what's going on?"
• "what's dispatchable?" / "what's ready?" / "what's next?"
• "what's archived?" / "show me the done entities"
• any ad-hoc question a status view answers (a single entity, entities in a stage, PR-pending).

Canonical invocations (all start with ${SPACEDOCK_BIN:-spacedock} status --workflow-dir {workflow_dir}):

• Overview: no extra flags shows the first 25 rows, sorted by later stage first then score descending; use --page N for more or --limit 0 for the full table.
• Dispatchables: --next.
• Archived-inclusive view: --archived returns active plus archived, not

archived-only. A full-sprint answer incl. done is one query: --where sprint=X --archived --fields slug,status,verdict,archived.

• Single-entity: --resolve {ref} then --where slug={resolved-slug}.

Output rendering guidance. Forward status stdout verbatim inside a fenced code block, with a one-line preface naming the request ("Workflow overview:", "Dispatchable entities:", "Archived entities:"). On empty results, render a literal note ("No dispatchable entities right now.") instead of an empty fence. Do not paraphrase rows, omit columns, invent fields, summarize counts, or editorialize.

Issue Filing

Do not file GitHub issues without explicit human approval.