Speckit Status

---
name: speckit-status
description: >
  Show the current SpecKit roadmap and workflow status in Codex.
  Aggregates workflow files and technical roadmaps, highlights
  active specs, identifies blocked work, and recommends the next
  unblocked spec to start. Read-only: never creates files, branches,
  or worktrees. Do not use to set up or scaffold a spec
  (speckit-scaffold-spec), run a workflow (speckit-autopilot), fix PR
  review comments (speckit-resolve-pr), or explain SDD methodology,
  the consensus protocol, or voting rules (speckit-coach).
---

# SpecKit Status Dashboard

## Installed Runtime Contract

Installed Claude and Codex surfaces resolve Python 3.11 or newer, invoke
`[resolved_python, "-m", "speckit_pro_runner"]`, send one JSON request on
stdin, read one JSON response from stdout, and surface stderr diagnostics.
Do not add a shell fallback, `jq` parsing path, Git Bash, WSL, or
PowerShell-specific command-language requirement for installed workflows.

The runner helper calls below (`generate-spec-index-check`, `o5-topology`) are
not pre-approved: they follow the session's permissions and may prompt. If a
call is denied, say so and continue the dashboard without that section.

Show the full project roadmap: completed specs, in-progress
specs, specs that haven't started yet, and a recommendation for
what to work on next. Also surface archive extension installation and
Archive Sweep cleanup safety when the project has archive state.

## Invocation

```text
$speckit-pro:speckit-status          # Show full roadmap + active specs
$speckit-pro:speckit-status all      # Same as above
$speckit-pro:speckit-status SPEC-013 # Show specific spec detail
```

## What to Do

### 1. Find All Data Sources

Search for workflow files, technical roadmap files, and design concept docs:

```text
Workflow files:    **/*-workflow.md  (active/completed specs with phase detail)
Technical roadmaps: **/*technical-roadmap*.md  OR  **/*-roadmap.md
Design concepts:   **/*-design-concept.md  (grill-me output per spec)
Also check:        docs/ai/specs/*-workflow.md
                   docs/ai/specs/.process/*-workflow.md
                   docs/ai/specs/.process/*-design-concept.md
                   docs/ai/specs/*-design-concept.md
                   docs/ai/*roadmap*.md
Archive state:     .specify/extensions.yml
                   .specify/extensions/.registry
                   .specify/extensions/archive/extension.yml
                   .specify/extensions/archive/RACECRAFT-PIN.md
```

Do not assume the user keeps everything under one directory. Search the current
checkout first, then list attached git worktrees (`git worktree list
--porcelain`, or without a shell the `gitdir` files under `.git/worktrees/`)
and search each one the same way, so workflows in attached worktrees are
included even when setup used a nonstandard worktree root. Record which
worktree and branch each workflow belongs to. Narrow to the files that
actually describe the SpecKit project; if a file looks unrelated, ignore it
rather than polluting the dashboard. If multiple roadmap files exist, pick the
most relevant current roadmap and say which file you used; do not merge
unrelated roadmaps unless the repo clearly uses a multi-roadmap setup.

For each design concept doc found, record the SPEC-ID it corresponds to
(parsed from the filename `SPEC-<ID>-design-concept.md` or from the doc's
frontmatter). This drives the **DC** (Design Concept) column in the
phase-detail dashboard and the per-spec detail view.

Search, glob and worktree discovery only identify candidates. This standalone
status skill must read every selected current roadmap and workflow file from
beginning to end before answering; snippets, cached summaries, and another skill's report
are not substitutes for a full-file read. Do not infer status, dependencies,
branch, or phase state from an unread section.

### 2. Parse the Technical Roadmap (Full Roadmap)

If a technical roadmap file exists, extract the **Progress Tracking**
table. This contains ALL specs in the project — including those
that haven't started the SpecKit workflow yet.

For each spec in the progress table, extract:

- **Spec ID** (e.g., SPEC-006)
- **Name** (e.g., Notifications)
- **Tools** count, only when the progress table has that column
- **Status** (✅ Complete, 🔄 In Progress, ⏳ Pending, ⚠️ Blocked)
- **Next Phase** or blocker info

Also extract:

- The **Dependency Graph** or tier information to show which
  specs can run in parallel and which are blocked
- Each spec's **Priority** (P1/P2/P3) from its section in the
  technical roadmap (line format:
  `**Priority:** P1 | **Depends On:** ...`)

### 3. Parse Workflow Files (Phase Detail)

For each workflow file found, extract:

- **Spec ID and Name** from the header
- **Phase statuses** from the "Workflow Overview" table
  (look for ⏳, 🔄, ✅, ⚠️)
- **Current phase** (the first ⏳ or 🔄 phase)
- **Branch** from the "Specification Context" table

### 4. Present Unified Dashboard

Combine technical roadmap and workflow data into a single report (illustrative:
the table skeletons pin the output format, and every cell holds a placeholder
rather than real project data; add a Tools column and summary line only when the
roadmap records tool counts):

```markdown
# SpecKit Project Status

## Summary

- **Total specs:** <n>
- **Complete:** <n> (SPEC-XXX, SPEC-YYY)
- **In progress:** <n>
- **Remaining:** <n>

## Completed Specs

| Spec | Name | PR | Notes |
|------|------|----|-------|
| SPEC-XXX | <name> | #<pr> | <note> |
| SPEC-YYY | <name> | #<pr> | <note> |

## Ready to Start (No Blockers)

These specs have no dependencies beyond the completed foundation and can start now:

| Spec | Name | Tier | Priority | Notes |
|------|------|------|----------|-------|
| SPEC-XXX | <name> | <tier> | P1 | <note> |
| SPEC-YYY | <name> | <tier> | P2 | <note> |
| ... | ... | ... | ... | ... |

## Blocked

| Spec | Name | Blocked By | Reason |
|------|------|------------|--------|
| SPEC-XXX | <name> | SPEC-YYY | <reason> |
| SPEC-YYY | <name> | SPEC-ZZZ | <reason> |

## Active Workflows (Phase Detail)

If any spec has a workflow file with phases in progress, show the phase-level
table. The **DC** column (Design Concept) shows ✅ if a `SPEC-<ID>-design-concept.md`
exists for the spec, ⏳ otherwise. A workflow file without a corresponding design
concept doc is a yellow flag — the phase prompts may be undercooked relative to
what `$speckit-pro:speckit-scaffold-spec` produces today:

| Spec | Name | DC | Specify | Clarify | Plan | Check | Tasks | Analyze | Impl | Next |
|------|------|----|---------|---------|------|-------|-------|---------|------|------|
| SPEC-XXX | <name> | ✅ | ✅ | ✅ | 🔄 | ⏳ | ⏳ | ⏳ | ⏳ | Plan |
| SPEC-YYY | <name> | ⏳ | ✅ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | Clarify (no design concept — re-run `$speckit-pro:speckit-scaffold-spec` or grill manually) |
```

Include an Archive Sweep summary when archive state exists:

- whether the archive extension is installed/enabled
- pinned source URL/ref/commit when available
- excluded current spec from `autopilot-state.json.archive_sweep`
- cleanup mode and `safeToApplyCleanup`
- next step: install/vendor archive, keep dry-run-only, or perform reviewed
  cleanup after archive success and recovery commands

#### Spec-Map Index Freshness (read-only)

As part of producing the dashboard, report whether each version-marked
`SPEC-MOC.md`'s generated navigation zones are current. Run the shared
generator in **read-only `--check` mode** — it regenerates the zones in
memory, diffs them against the committed maps, and **writes nothing**:

```text
Run runner helper generate-spec-index-check with repo root "$PWD".
```

Pass `"$PWD"` (the project root) explicitly. Without it the generator infers
its repo root from the script's own location, which in a cached-plugin install
is the plugin cache — not the user's project — so the freshness check would
scan the wrong tree.

Surface a single freshness line in the dashboard from the exit code:

- exit `0` → **index current**
- exit `1` → **index stale — run regen** (the maps drifted from their
  sources; the fix is `$speckit-pro:speckit-autopilot`, whose phase gates
  rebuild the zones — `speckit-status` does not regenerate them)
- exit `2` → **index check error: `<message>`** — name the failure from the
  generator's stderr line (e.g. a malformed `prs.json` or a non-regular-file
  map target)

**Read-only guarantee:** `speckit-status` MUST NOT write any file. It invokes
the generator only with `--check`, which writes nothing on **any** path —
including the exit-`2` error path. The dashboard never runs the generator in
write mode and never regenerates the maps itself; reporting staleness here is
purely advisory.

#### O5 Parent Rollup And Re-Slicing Status

When a spec directory contains `o5-parent-manifest.json`, validate topology
before reporting child status:

```text
Run runner helper o5-topology for specs/<parent-branch>.
```

This script is read-only and emits one JSON rollup. If `topologyStatus` is
`invalid`, show `computedStatus: invalid_topology` plus the actionable
`problems[]`; do not compute or invent a child rollup from invalid topology.
If valid, show exactly one child row per manifest child, in manifest order, and
surface `computedStatus`, `declaredRollupStatus`, and `declaredStatusDrift`.
Treat `declaredRollupStatus` as drift-check metadata only, never as the source
of truth.

Also surface final-gate re-slicing state when present in workflow or
`autopilot-state.json`: a blocked `final_reviewability_gate` means PR creation
has not started and status should point to the recorded re-slicing packet,
blocked operations, and the next re-slicing resume action instead of marking
implementation complete.

### 5. Recommend Next Spec

After the dashboard tables, add a `## Recommended Next` section
that proposes the next spec to implement.

**Algorithm:**

1. From the technical roadmap, collect all unblocked specs with status
   `⏳ Pending` (not `✅ Complete`, not `🔄 In Progress`, not
   blocked by incomplete specs).
2. For each, read its **Priority** (P1/P2/P3) from the spec's
   section in the technical roadmap.
3. Sort by: Priority (P1 first) → then technical roadmap order
   (preserves tier sequencing).
4. The **top recommendation** is the first spec in the sorted
   list.
5. Also list 1-2 **alternatives** from the same or next priority
   level, especially if they are smaller (a lower Projected
   reviewable LOC in the roadmap) for a quicker win.

**Output format** (illustrative: the shape is fixed, the values are
placeholders):

```markdown
## Recommended Next

**SPEC-XXX: <name>** (P1, Tier <tier>)

This is the highest-priority unblocked spec. <one or two sentences of scope,
taken from the spec's technical roadmap section.>

To get started:

```text
$speckit-pro:speckit-scaffold-spec SPEC-XXX
```

This creates the worktree, branch, and populated workflow file.
Then run `$speckit-pro:speckit-autopilot` to execute it.

**Alternatives** (if you prefer a smaller spec first):

- SPEC-YYY: <name> (P2)
- SPEC-ZZZ: <name> (P2)
```

**Edge cases:**

- If no unblocked specs remain, say "All unblocked specs are
  complete. Remaining specs are blocked by dependencies."
- If a spec is `🔄 In Progress`, recommend finishing it first:
  "SPEC-XXX is already in progress — finish it before starting
  a new spec."
- If all specs are complete, say "All specs complete — project
  roadmap is finished."
- If several workflow files describe the same spec, prefer the one that
  matches the active branch or the most recent in-progress state.
- If workflow files exist without a roadmap, report phase detail from the
  workflows and note that backlog visibility is incomplete.

### 6. If Specific Spec Requested

Show detailed information for that spec:

- All phase statuses with notes (from workflow file, if exists)
- Technical roadmap scope description
- Design Concept doc path (if `SPEC-<ID>-design-concept.md` exists) — also
  surface its frontmatter `question_count` and Open Questions count for a
  quick read on how thoroughly the spec was scoped
- Dependencies and what it enables
- Gate results and key artifacts produced
- Current blockers (if any)
- Files generated

If no workflow file exists for the requested spec, show the
technical roadmap scope and suggest creating a workflow file:

```text
SPEC-008 (Perspectives) — ⏳ Not Started
No workflow file found. To begin:
$speckit-pro:speckit-scaffold-spec SPEC-008
```

### 7. If No Technical Roadmap or Workflow Files Found

Tell the user:

- No technical roadmap or workflow files found in the project
- Guide them to create a technical roadmap:
  `$speckit-pro:speckit-coach help me create a technical roadmap`
- Or create a single workflow: copy
  `skills/speckit-coach/templates/workflow-template.md`

### 8. Boundaries

This skill does not mutate the repo. Do not create branches, edit workflow
files, or mark roadmap rows complete from inside the status skill. If the user
wants to act on the recommendation, direct them to the matching skill:

- $speckit-pro:speckit-scaffold-spec to prepare a spec
- $speckit-pro:speckit-autopilot to execute a workflow
- $speckit-pro:speckit-resolve-pr to address review feedback
- $speckit-pro:speckit-coach for process guidance