Sprint Status Mod

Overview

The sprint status mod adds a live sprint progress view to Claude Code. It provides four complementary surfaces that keep sprint status visible without running a command:

Sidebar -- a detailed sprint dashboard in a pane alongside your conversation.
Band -- a single summary line above the prompt.
Status line segment -- sprint progress in the persistent status line.
Enhanced /gaia-sprint-status -- added columns and phase grouping in the text dashboard.

All four surfaces read from a shared snapshot cache that is refreshed automatically every 30 seconds and on every /sprint toggle.

The `/sprint` command

Type /sprint in the Claude Code prompt to toggle the sidebar open or closed. When no sprint is active, the command responds "No active sprint" and takes no further action.

Three other controls also toggle the sidebar:

Band hotkey -- type the digit 9 on an empty prompt.
Band button -- click the toggle on the band line above the prompt.
Esc -- closes the sidebar when it is open.

Pane placement

Claude Code decides where the pane appears at runtime. In a wide fullscreen terminal the sidebar docks on the right; in a narrower or non-fullscreen terminal it appears inline above the prompt.

Auto-open

When a sprint is active, the sidebar opens automatically at session start if the terminal is at least 144 columns wide. After you have manually opened it at least once, the auto-open threshold drops to 110 columns. You can open the sidebar manually at any terminal width.

Sidebar

The sidebar is the primary sprint view. Its sections, from top to bottom:

ACTION NEEDED banner

Appears at the top only when one or more items require attention. Each entry shows what needs action, a suggested command, and a since date. See ACTION NEEDED indicators for the full list of conditions.

Header and aggregate

The sprint identifier and a green live indicator, followed by the first goal (text wraps over as many lines as needed). Below it: a summary showing done/total stories, done/total points, and overall percentage.

Segmented bar

A horizontal bar with one block per status group, each proportional to that group's summed points:

Done (green)
Review (blue)
In-progress (yellow)
Blocked (red)
Ready-for-dev (gray)
Backlog/validating (dim)

Every present status gets at least one column. Directly under the bar, a colour key labels each status block.

When NO_COLOR is set, the bar falls back to text counts per status. In ASCII mode, single-character markers replace the coloured blocks.

Sub-line

Shows the active dependency phase, the current day (Day N of T), a pace flag (starting, on pace, behind pace, or overdue), and the number of blocked stories (in red when greater than zero). Parts are separated by a middle dot (·).

Readiness pills

Two labels that always show whether the sprint has reached key milestones, each with a ( yes ) or ( no ) indicator: Ready for sprint review and Ready to close sprint. When stories are ready to mark done, a count appears. A drift/waiting line appears under the pills when the cache reports status mismatches between story files and sprint state, showing the count and the first entry.

NOW block

Lists every in-progress, review, or blocked story with its task progress (tasks X/Y), gate count (gates X/6), a blocked-since marker when applicable, a drift marker when the story is behind schedule, and a HIGH-risk indicator. When nothing is actively being worked on, the block reads "No active work".

Agent activity sub-lines appear under each story when agents are running against it. See Agent activity.

Phase matrix

A compact grid showing every dependency phase. Done phases are collapsed; the active phase is expanded to show each story's stage (ready, dev, review, done); future phases are dimmed. Unphased stories appear at the end. HIGH-risk stories are marked.

A glyph legend appears directly above the matrix labeling the status glyphs for each status present in the sprint.

Selected-story detail

Navigate story rows with Tab, arrow keys, or Enter to expand a story's detail view. The detail shows the full task checklist, the six-gate review table, and the manual-test state when applicable.

Close button

The pane shows a 9 close button that dismisses the sidebar. The digit 9 on an empty prompt reopens it.

Status glyphs

Status	Unicode	ASCII
Done	✓	`[x]`
Review	☉	`[o]`
In-progress	◑	`[~]`
Blocked	✕	`[!]`
Ready-for-dev	·	`[-]`
Backlog	–	`[ ]`

Example sidebar layout

⚠ ACTION NEEDED
  Manual tests due for E5-S12
    → /gaia-test-manual
    since Oct 10

SPRINT  sprint-12  ● live
  Improve search performance

  3 of 6 stories · 12 of 21 pts · 57%

  █████████████████████████
  █ done  █ review  █ in-progress  █ ready-for-dev

  Phase 2 of 3 · Day 5 of 10 · on pace · 0 blocked

  Ready for sprint review  ( no )
  Ready to close sprint   ( no )

  NOW
  ◑ E3-S7 refactor-queries  tasks 3/5  gates 4/6 HIGH
    → dev-fullstack: implementing task 4
  ☉ E5-S18 update-search-api  tasks 1/4  gates 2/6

  ✓ done  ☉ review  ◑ in-progress  · ready-for-dev
                         READY  DEV  REVIEW DONE
  ✓ Phase 1 · 3 stories · 12 pts
  PHASE 2 (active)
   E3-S7 Refactor queries   ✓    ◌    ○    ○ HIGH
   E5-S18 Update search API   ✓    ✓    ◌    ○
  PHASE 3  E5-S20

Band

The band is a single summary line rendered above the Claude Code prompt. It reads:

9: sprint-12 · 12/21 pts · 3/6 done · 0 blocked

When ACTION NEEDED items exist in the same session, the band switches to a warning variant:

⚠ ACTION NEEDED · 2 items since Oct 10 → press 9

The band is absent when no sprint is active.

Status line segment

When a sprint is active, the GAIA status line includes a sprint progress segment:

sprint-12 57%

When an ACTION NEEDED condition is active (manual tests due, user action items, or sprint ready to close), the segment is prefixed with a warning indicator:

! sprint-12 57%

If the snapshot cache is missing or unreadable, the segment falls back to showing the sprint identifier only (no percentage, no warning). When no sprint is active, the segment is absent.

Upgrade note: the sprint progress segment appears automatically via status line self-heal after a plugin update. If it does not appear, run /gaia-statusline-refresh to install the updated runtime.

Enhanced `/gaia-sprint-status` dashboard

The /gaia-sprint-status text dashboard includes two additional columns:

Tasks X/Y -- completed vs total tasks for each story.
Gates X/6 -- passed review gates out of the six standard gates.

Stories are grouped by dependency phase with a phase header line. Unphased stories appear in a separate group at the end.

When any ACTION NEEDED condition is active, a warning header prints above the table with the count and first item summary.

When no sprint is active, the command prints "No active sprint" and exits. The stranded-ready advisory (stories left in ready-for-dev across sprints) continues to run its own independent scan.

Agent activity

The NOW block in the sidebar shows agent activity sub-lines under each story. Agents are linked to a story when their dispatch description starts with the story key followed by a colon (e.g., E5-S12: implementing task 4). This is the convention used by GAIA's /gaia-dev-story and /gaia-run-sprint dispatches. Agents whose descriptions do not follow this pattern appear as unlinked activity.

Agent activity is visible only in the session that dispatched the agents (same-session only). Up to five activity lines are shown per story.

ACTION NEEDED indicators

Four detection rules produce ACTION NEEDED entries:

Condition	Suggested command
Manual tests are due (all six review gates passed, manual verification required, no verdict recorded)	`/gaia-test-manual`
An action item is assigned to the user (matched by alias)	`/gaia-action-items`
All stories are done (the sprint can be closed)	`/gaia-sprint-close`

The sidebar, band, status line, and /gaia-sprint-status all show ACTION NEEDED when applicable.

Suggested commands come from a fixed allowlist (/gaia-test-manual, /gaia-sprint-close, /gaia-action-items). ACTION NEEDED items in the sidebar are display-only indicators -- they are never auto-executed.

Each entry includes a since date derived from the review-gate ledger timestamp or the story file modification time.

Configuration

The sprint_status_mod section in .gaia/config/project-config.yaml accepts one optional property:

`user_aliases`

An array of strings used to match action items assigned to the current user.

Absent: defaults to ["user"] plus the git user.name.
Set: the provided list fully replaces the default (it does not merge).
Empty list ([]): disables user-alias matching entirely.

Matching is case-insensitive.

# Example
sprint_status_mod:
  user_aliases:
    - "alice"
    - "Alice Smith"

View the current values with /gaia-config-show sprint_status_mod.

Graceful degradation

The sidebar and band require Claude Code mod support (the ui.render, ui.press, and session.start hooks). On builds that do not expose these hooks, the mod silently skips registration -- no error or warning is emitted.

When the cache has not been read yet or the cache file is absent, the sidebar pane shows "Sprint data unavailable" instead of rendering nothing. The band remains absent in this state. Once the cache loads successfully, the full dashboard replaces the fallback message.

The two non-mod surfaces continue to work on all builds:

/gaia-sprint-status renders the enhanced dashboard with Tasks/Gates columns and phase grouping.
The status line shows the sprint progress segment.