/gaia-sprint-plan

Arguments

This command takes no required arguments. All sprint parameters are gathered interactively.

What it does

/gaia-sprint-plan builds a sprint by selecting stories from the backlog, applying sizing and priority rules, and committing the sprint atomically to the sprint tracking file. It reads the epics-and-stories breakdown, classifies each story by readiness, checks dependencies, enforces velocity limits, and produces a sprint plan document with a burndown estimate.

When to use it

• You have stories in ready-for-dev status and want to assemble the next sprint.
• You completed a sprint and need to plan the follow-up sprint using stories remaining in the backlog.
• Action items from a retrospective recommend pulling specific stories into the next sprint -- the priority-flag system auto-includes flagged stories.

Prerequisites

• Epics and stories must exist. .gaia/artifacts/planning-artifacts/epics-and-stories.md must be present. Run /gaia-create-epics first if it does not exist.
• Stories must have individual files. Only stories with a file under .gaia/artifacts/implementation-artifacts/epic-{epic_key}-*/ and status ready-for-dev are selectable. Run /gaia-create-story for any story that lacks a file.
• Open action items should be resolved. If any HIGH-priority action item has been open for two or more sprints, the command halts until you resolve it via /gaia-action-items or explicitly override.

Orchestration mode

When /gaia-sprint-plan starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:

────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-sprint-plan skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

Hotfix auto-injection

Stories with priority_flag: "hotfix" in their frontmatter are auto-injected into the active sprint at Step 1, before the interactive selection ceremony begins. This differs from the "next-sprint" flag, which pre-fills the candidate set for user confirmation.

Key behaviors (PR #772):

• Injection uses sprint-state.sh inject (the sanctioned boundary writer). The call is idempotent -- re-runs are no-ops.
• Capacity-exceeded does not block hotfix injection. A hotfix is a sanctioned bypass of normal sprint capacity.
• Multiple hotfix stories in a single run are all injected; each emits a WARNING log line.
• Hotfix stories must still pass the full /gaia-review-all including the wire-verification gate. A hotfix is faster to PLAN, not faster to TEST.
• The "hotfix" value is human-set only. Neither /gaia-add-feature nor triage may auto-set it.

How to invoke

/gaia-sprint-plan

No arguments are required. The command walks you through sprint scoping interactively.

What it does step by step

1. Load backlog Reads the epics-and-stories document and scans individual story files. Classifies stories into selectable (have a file, ready-for-dev) and non-selectable (missing file or wrong status). Stories flagged with priority_flag: "next-sprint" are auto-included in the candidate set. Stories with priority_flag: "hotfix" are auto-injected into the active sprint via sprint-state.sh inject before selection begins.
2. Check for blocking action items Scans the action-items tracker. If any HIGH-priority item has been open for two or more sprints, the command halts and directs you to resolve it first.
3. Sprint scoping Asks for the sprint duration (1 week, 2 weeks, or custom), the team velocity estimate in story points, and the sprint number. Displays the point values for each story size (S/M/L/XL).
4. Story selection Selects stories by priority (P0 first), checks that dependencies are met, and verifies the total points fit within the velocity estimate. Warns if P0 stories are excluded. For high-risk stories, checks that ATDD scenarios exist.
5. Commit sprint Registers each selected story in the sprint tracking file. Runs a dependency-inversion lint to detect ordering issues, and clears the priority_flag on included stories.
6. Write sprint plan Saves the sprint plan document with story assignments, execution order, burndown estimate, and testing readiness.
7. Validate (optional) If available, runs a validation pass to verify story keys exist, dependency ordering is correct, and point totals are accurate.
8. Report Displays the finalized sprint summary and suggests running /gaia-dev-story on the first story.

Inputs

Outputs

Examples

1. Happy path -- interactive planning

> /gaia-sprint-plan

Loading backlog from epics-and-stories.md...
  15 stories total, 8 selectable (ready-for-dev with files).
  3 not selectable (no file), 4 not selectable (wrong status).

  Auto-included by priority_flag: E5-S12, E5-S14

Escalation halt check: no blocking action items. Proceeding.

Sprint scoping:
  Duration? 2 weeks
  Velocity estimate? 21 points
  Sprint number? sprint-4

Sizing map: S=2, M=3, L=5, XL=8

Story selection:
  E5-S12  Add webhook retry logic       M (3)  [priority_flag: next-sprint]
  E5-S14  Improve error messages         S (2)  [priority_flag: next-sprint]
  E3-S9   Dashboard search               L (5)
  E3-S10  Export CSV                      M (3)
  E4-S6   Rate limiting middleware        L (5)
  E4-S7   API key rotation               M (3)
  Total: 21 / 21 points (100% capacity)

Committing sprint-4...
  Dependency lint: clean, no inversions.
  Priority flags cleared on E5-S12, E5-S14.

Sprint plan written to .gaia/artifacts/implementation-artifacts/sprint-4-plan.md.

Sprint-4 summary:
  Duration: 2 weeks | Velocity: 21 | Stories: 6 | Utilization: 100%

Next: run /gaia-dev-story E5-S12 to begin the first story.

2. Hotfix auto-injection

Stories with priority_flag: "hotfix" are injected into the active sprint automatically via sprint-state.sh inject before the interactive selection ceremony.

> /gaia-sprint-plan

Loading backlog from epics-and-stories.md...
  12 stories total, 6 selectable.

Hotfix injection:
  WARNING: hotfix story E12-S4 injected into active sprint via
           priority_flag: "hotfix"
  WARNING: hotfix story E12-S5 injected into active sprint via
           priority_flag: "hotfix"

  Auto-included by priority_flag: E5-S18

Sprint scoping:
  Duration? 2 weeks
  Velocity estimate? 21 points
  Sprint number? sprint-5

Story selection (hotfix stories already injected):
  E12-S4  Fix payment webhook timeout    S (2)  [hotfix -- already injected]
  E12-S5  Patch auth token expiry        S (2)  [hotfix -- already injected]
  E5-S18  Webhook retry backoff          M (3)  [priority_flag: next-sprint]
  E3-S11  Dashboard filtering            L (5)
  Total: 12 / 21 points (57% capacity)

Committing sprint-5...
Sprint-5 summary:
  Duration: 2 weeks | Velocity: 21 | Stories: 4 | Utilization: 57%

3. Capacity exceeded with hotfix still injected

Hotfix injection is a sanctioned capacity bypass. Even when the sprint is at or over capacity, hotfix stories are injected.

> /gaia-sprint-plan

Loading backlog...
  8 selectable stories.

Hotfix injection:
  WARNING: hotfix story E12-S4 injected into active sprint via
           priority_flag: "hotfix"

Sprint scoping:
  Velocity estimate? 13 points

Story selection:
  E12-S4  Fix payment webhook timeout    S (2)  [hotfix -- already injected]
  E3-S9   Dashboard search               L (5)
  E4-S6   Rate limiting middleware        L (5)
  E3-S10  Export CSV                      M (3)
  Total: 15 / 13 points (115% capacity)

  WARNING: Sprint is 2 points over velocity estimate.
  Hotfix stories cannot be removed. Deselect a non-hotfix story? y
  Deselecting E3-S10 (M, 3 pts).
  Total: 12 / 13 points (92% capacity)

Committing sprint-6...

4. Escalation halt -- blocking action item

> /gaia-sprint-plan

Escalation halt check:

  HALT: HIGH-priority action item open for 2+ sprints:
    AI-42  "Standardize error response format"  escalation_count: 3  priority: HIGH
    AI-77  "Migrate legacy auth tokens"          escalation_count: 2  priority: HIGH

  Resolve these items before planning a new sprint:
    - Run /gaia-action-items to resolve
    - Or re-invoke with explicit override to acknowledge

5. Dependency-blocked story excluded

> /gaia-sprint-plan

Loading backlog...

Story selection:
  BLOCKED: Story E4-S7 depends on E4-S5 (status: in-progress).
  E4-S7 removed from candidates.

  E3-S9   Dashboard search               L (5)
  E4-S6   Rate limiting middleware        L (5)
  E5-S14  Improve error messages          S (2)
  Total: 12 / 13 points (92% capacity)

Committing sprint-7...
  Dependency lint: clean, no inversions.

What to run next

• /gaia-dev-story -- implement the first story in the sprint.
• /gaia-sprint-status -- view the sprint dashboard at any time during the sprint.
• /gaia-correct-course -- if scope needs to change mid-sprint.

Troubleshooting

"Escalation halt: HIGH-priority action item open for 2+ sprints"

A recurring issue must be resolved before new sprint commitments are made. Run /gaia-action-items to resolve the blocking item, or re-invoke with an explicit override if you have acknowledged the item.

"Story has no individual file"

The story exists in epics-and-stories.md but has no detailed file. Run /gaia-create-story {key} to generate it.

"Dependency not done"

A selected story depends on another story that is not yet done. Either include the dependency in this sprint (ordered before the dependent), or remove the dependent story.

"Dependency inversion detected"

A story appears before its dependency in the sprint order. You can accept the suggested reorder or override and keep the original order.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

• echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
• .gaia/config/project-config.yaml contains:

  orchestration:
    mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Related commands