# Speckit Status

> Use when the user wants to read SpecKit project status, see the full roadmap dashboard, check which specs are complete, in-progress, blocked, or ready to start, see phase-level progress for active specs, find which active worktrees exist and what spec each belongs to, check the status or current phase of a specific SPEC-ID, identify what is blocking a spec and why, get a recommendation for the next spec to implement, or summarize overall project health and next steps. Triggers on: show roadmap, project status, active workflows, blockers, dashboard, all specs, phases complete, next phase, list worktrees, which spec should I start, what is next, SpecKit progress, project health, check SPEC-XXX, is SPEC-XXX done, is SPEC-XXX blocked. Read-only: never creates files, branches, or worktrees. Do NOT use to set up or scaffold a spec (use speckit-scaffold-spec), execute a workflow autonomously (use speckit-autopilot), fix PR review comments (use speckit-resolve-pr), or ask about SDD methodology (use speckit-coach).

- Skill: `racecraft-lab/speckit-status` (Agent Skill)
- Install (CLI): `npx skillmds@latest add racecraft-lab/speckit-status`
- Raw SKILL.md: https://api.skillmd.com/api/skills/racecraft-lab/speckit-status/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: racecraft-lab (https://skillmd.com/u/racecraft-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/racecraft-lab/speckit-status

---


# 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.

## Codex Skill-Selection Guard

If this file is loaded in Codex, the runtime selected the Claude Code
variant from `skills/` instead of the Codex variant from `codex-skills/`.
Do not follow the Claude-oriented instructions below in Codex. Immediately
read and follow `../../codex-skills/speckit-status/SKILL.md` from this plugin
root, treat that document as the active skill, and report that the fallback
guard was triggered.

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/*-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
```

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.

### 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
- **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):

```markdown
# SpecKit Project Status

## Summary

- **Total specs:** <n>
- **Complete:** <n> (SPEC-XXX, SPEC-YYY)
- **In progress:** <n>
- **Remaining:** <n>
- **Tools:** <n> of <n> new tools implemented

## Completed Specs

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

## Ready to Start (No Blockers)

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

| Spec | Name | Tools | Tier | Priority | Notes |
|------|------|-------|------|----------|-------|
| SPEC-XXX | <name> | <n> | <tier> | P1 | <note> |
| SPEC-YYY | <name> | <n> | <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 (fewer tools) for a
   quicker win.

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

```markdown
## Recommended Next

**SPEC-XXX: <name>** (<n> tools, 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> (<n> tools, P2)
- SPEC-ZZZ: <name> (<n> tools, 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."

### 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`