name: spec-status
description: Show pipeline overview of all specifications with status counts and stale detection
allowed-tools: Bash(find:), Bash(grep:), Bash(stat:*), Read, Glob

Spec Status Skill

Display a pipeline overview of all specifications in the repository.

Usage

/spec-status

Output Format

Spec Pipeline:
  Draft:        2  001-valkey, 002-gpu-nodes
  Implementing: 1  003-queue
  Done:        15  (in docs/specs/done/)

Stale (>14 days unchanged):
  001-valkey (last modified: 2025-01-05)

Workflow

1. Find Active Specs

# Find all spec.md files excluding done/ and templates/
find docs/specs -name "spec.md" \
  -not -path "*/done/*" \
  -not -path "*/templates/*" \
  -type f 2>/dev/null

2. Parse Status from Each Spec

For each spec file found:

# Extract status field from spec header
grep -oP '\*\*Status\*\*:\s*\K[^\s|]+' "$SPEC_FILE"

Valid statuses: draft, in-review, approved, implementing, done

3. Count Done Specs

# Count specs in done/ directory
find docs/specs/done -name "spec.md" -type f 2>/dev/null | wc -l

4. Detect Stale Specs

# Find specs not modified in 14+ days
find docs/specs -name "spec.md" \
  -not -path "*/done/*" \
  -not -path "*/templates/*" \
  -mtime +14 \
  -type f 2>/dev/null

5. Format Output

Group specs by status and display:
- Draft: Specs with draft or in-review status
- Implementing: Specs with approved or implementing status
- Done: Count of specs in docs/specs/done/
- Stale: Specs unchanged for 14+ days (needs attention)

Status Categories

GitHub Issue Labels

This skill shows file-based status. For GitHub issue labels:

# List spec issues by label
gh issue list --label "spec:draft"
gh issue list --label "spec:implementing"
gh issue list --label "spec:done"

Example Output

For a repository with:
- 2 specs in draft status
- 1 spec being implemented
- 15 archived specs
- 1 stale spec

╔════════════════════════════════════════════════════════════════╗
║  Spec Pipeline Status                                         ║
╚════════════════════════════════════════════════════════════════╝

  Stage          Count   Specs
  ─────────────────────────────────────────────────────────────
  Draft            2     001-valkey-caching, 002-gpu-node-pool
  Implementing     1     003-queue-composition
  Done            15     (archived in docs/specs/done/)

⚠️  Stale Specs (>14 days without changes):
  → 001-valkey-caching (last modified: 2025-01-05)
    Consider: Resume work or archive if abandoned

Related Skills

• /spec - Create new specification
• /clarify - Resolve [NEEDS CLARIFICATION] markers
• /create-pr - Create PR (auto-references spec)