Menu
Plans a sprint from backlog issues using capacity constraints and priority ranking
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Analyzes a specific bug from the issue tracker (analysis only, no code changes)
Validate Automation Config, MCP servers, and tokens
Creates backlog epics in issue tracker from a specification document
Multi-agent discussion -- brings 2-3 agent perspectives into one conversation
Run the fix pipeline on a single ticket OR a batch -- auto-resumes from checkpoint if state exists
Implements a feature from the issue tracker -- spec, design, fix, review, test, publish
Based on SOC occupation classification
| name | sprint-plan |
| description | Plans a sprint from backlog issues using capacity constraints and priority ranking |
| allowed-tools | mcp__*, Bash, Read, Glob, Grep, Task |
| argument-hint | [--all] [--apply] [--dry-run] [--limit <N>] [--yolo] |
| disable-model-invocation | true |
Input: $ARGUMENTS = optional flags (--all, --apply, --dry-run, --limit <N>, --yolo)
Parse $ARGUMENTS:
--all: Plan ALL sprints (release plan), not just the next one--apply: After planning, dispatch /agent-flow:implement-feature or /agent-flow:fix-bugs per selected issue--dry-run: Display plan only, no tracker writes, no execution dispatch--limit <N>: Override Max issues config value (valid range: 1โ50; out of range โ clamp with WARN)--yolo: Auto-approve Gate 1 and Gate 3 (Gate 2 ALWAYS blocks โ even in --yolo)--yolo does NOT imply --apply. Explicit --yolo --apply is required for full automation.
--dry-run overrides --apply (if both present, dry-run wins โ no tracker writes, no execution).
Read Automation Config from CLAUDE.md section ## Automation Config. Follow ../../core/config-reader.md.
Required:
Sprint Planning section (REQUIRED for sprint-plan โ see Cold-start rules if absent):
2 weeks)story-points)suggest)If ### Sprint Planning section is absent: run in suggest mode with cold-start warnings at every gate.
Do NOT block โ planning still proceeds with effective_capacity = null (unconstrained).
Optional:
./reports/metrics.md)customization/)--apply)Config validation rules:
Sprint duration: must be 1 week, 2 weeks, 3 weeks, or 4 weeks. Other values: WARN, use 2 weeks.Capacity unit: must be story-points or hours. Other values: WARN, use story-points.Team capacity: must be positive integer. 0 treated as unconfigured.Velocity target: must be positive integer. If Velocity target > Team capacity (both set): WARN "Velocity target ({V}) exceeds Team capacity ({C}). Using Team capacity." Use Team capacity.Mode: must be suggest or apply. Other values: WARN, use suggest.Max issues: must be integer 1โ50. Out of range: clamp to [1, 50] with WARN.Epic template: file path. If set but file not found: WARN, use built-in template.Follow ../../core/mcp-preflight.md. Before any pipeline operation, verify MCP tool availability:
mcp__* tool matching the tracker type is accessibletracker_tier for Gate 1 display: MCP if available, Bash if only REST fallback, Skip if neither/agent-flow:check-setup for diagnostics."Create .agent-flow/sprint-{YYYYMMDD-HHmmss}/ directory.
Initialize state.json following the schema in state/schema.md with:
status: "running", mode: "sprint-planning", pipeline: "sprint-plan"run_id: "sprint-{YYYYMMDD-HHmmss}"sprint.name: null (populated after Gate 1)sprint.issues: [] (populated after Gate 1)Follow atomic write protocol from ../../core/state-manager.md.
3-tier fallback โ determine effective_capacity and velocity_source:
Tier 1 (historical): Check if ./reports/metrics.md (or Metrics โ Output path) exists.
avg_time_to_fix and success_rate. Set velocity_source = "historical".Tier 2 (heuristic): If Team capacity or Velocity target is configured in Sprint Planning section:
effective_capacity per capacity model (section Rules โ Capacity model below).velocity_source = "heuristic".Tier 3 (manual/unconstrained): If neither Tier 1 nor Tier 2 applies:
--yolo mode: prompt "No capacity data. Enter team capacity for this sprint (in {unit}), or press Enter for unconstrained planning:"
effective_capacity. Set velocity_source = "manual".effective_capacity = null. Set velocity_source = "unconstrained".--yolo mode: skip prompt, set effective_capacity = null, velocity_source = "unconstrained".Display cold-start warning if velocity_source != "historical":
"No velocity data available. Sprint plan uses {velocity_source} data. Run /agent-flow:metrics after this sprint to calibrate future planning."
This warning is displayed at every gate until velocity_source = "historical".
Via MCP server (per Issue Tracker โ Type), fetch open issues:
--limit flag value โ Max issues config value โ default 20If 0 issues found: display "No open issues found matching the query. Nothing to plan." STOP (set state status: "completed").
If metrics report exists (from Step 0c Tier 1 check): read per-area data.
For each fetched issue: check tracker comments for [agent-flow] Triage completed or [agent-flow] Spec analysis completed. Extract complexity estimate if present. Store as triage_complexity[issue_id].
Before dispatch, check Agent Overrides: follow ../../core/agent-override-injector.md for priority-engine overrides.
You MUST invoke Task(subagent_type='agent-flow:priority-engine', model='opus'). DO NOT inline-execute.
Context: list of issues + historical data (if available) + triage complexity map.
If priority-engine fails or returns an error: BLOCK with:
[agent-flow] ๐ด Pipeline Block
Agent: priority-engine
Step: Step 3 (Priority ranking)
Reason: Priority-engine agent failed.
Detail: {error output}
Recommendation: Check agent logs. Run /agent-flow:prioritize standalone to diagnose.
Before dispatch, check Agent Overrides: follow ../../core/agent-override-injector.md for sprint-planner overrides.
You MUST invoke Task(subagent_type='agent-flow:sprint-planner', model='sonnet'). DO NOT inline-execute.
Context:
--all flag presence (if set, sprint-planner generates multi-sprint release plan)If sprint-planner fails or Blocks: BLOCK pipeline with sprint-planner's block detail.
Display the full sprint-planner output table.
If velocity_source != "historical": display cold-start warning (see Step 0c).
Display prompt:
Sprint plan uses {used}/{effective_capacity or "โ"} {unit}. {N} issues selected, {M} overflow.
Tracker assignment: {tracker_tier} ({tracker_type})
Execution: {suggest only | --apply}
Accept this sprint plan? [Y/n]
Behavior:
--yolo: auto-approve, display "[auto-approved]"status: "completed" (clean exit).Update state.json: write sprint issue list with effort scores, effective_capacity, velocity_source.
Follow atomic write protocol from ../../core/state-manager.md.
For each issue in the Selected Issues table:
triage_complexity[issue_id] exists (from Step 2 enrichment)unmapped_ac_listIf unmapped_ac_list is non-empty:
WARNING: The following issues have insufficient acceptance criteria for quality implementation:
| Issue | AC Count | Concern |
|-------|----------|---------|
| {ID} | {N} | {No triage/spec analysis found | Only {N} AC โ may produce incomplete implementation} |
Issues without sufficient AC may produce lower-quality implementations.
Consider running /agent-flow:analyze-bug or /agent-flow:implement-feature --dry-run on these issues first.
Continue with sprint? [Y/n]
--yolo mode. Display warning and prompt regardless.status: "completed".If --dry-run: display plan summary and STOP before tracker writes:
"Dry run complete. No tracker writes performed." Set state status: "completed".
Display:
Ready to start sprint:
- Sprint: {sprint_name}
- Issues: {N}
- Total effort: {total_points} {unit}
- Tracker writes: {sprint assignment via {tracker_tier} ({tracker_type}) | skipped (--dry-run)}
- Execution: {suggest only (use --apply to auto-execute) | auto-execute (--apply)}
Proceed? [Y/n]
Behavior:
--yolo: auto-approve, display "[auto-approved]"status: "completed".Update state.json: mark status as "approved". Follow atomic write protocol from ../../core/state-manager.md.
Generate sprint_name: Sprint {YYYY}-W{WW} (current year, current ISO week number, zero-padded).
Name-to-ID resolution (pre-loop): For trackers requiring internal IDs (Jira, Linear, GitHub, Gitea, Redmine), resolve sprint/milestone/cycle name to tracker-internal identifier ONCE before the assignment loop. Cache the resolved ID.
Jira pre-check: Detect Scrum vs Kanban board. If Kanban: skip sprint operations entirely, display "Kanban board detected โ sprint assignment skipped. Sprint plan is still generated." NON-BLOCKING.
For each selected issue, execute sprint assignment using 3-tier fallback:
| Tracker | MCP Tool | Parameters | Notes |
|---|---|---|---|
| YouTrack | mcp__youtrack__update_issue or equivalent | issueId: {ID}, field: {Sprint field from config or "Sprint"}, value: {sprint_name} | Sprint field name from config (default: Sprint) |
| Jira | mcp__jira__add_issues_to_sprint or equivalent | sprintId: {resolved_id}, issues: [{ID}] | Pre-check: board.type must be "scrum". If Kanban: skip. |
| Linear | mcp__linear__update_issue or equivalent | issueId: {ID}, cycleId: {resolved_uuid} | Requires name-to-UUID resolution via list_cycles |
| GitHub | mcp__github__update_issue or equivalent | owner: {owner}, repo: {repo}, issue_number: {N}, milestone: {resolved_number} | Requires milestone name-to-number resolution |
| Gitea | Skip to Tier 2 | -- | Gitea MCP sprint assignment unverified; go directly to Tier 2 |
| Redmine | mcp__redmine__update_issue or equivalent | issue_id: {ID}, fixed_version_id: {resolved_id} | Always Version, no Agile Plugin detection. Requires version name-to-ID resolution. |
If Tier 1 MCP call fails (tool unavailable or call error): fall through to Tier 2.
Only attempted if Tier 1 fails (MCP tool not available or MCP call returns error). If the required environment variable is not set: skip to Tier 3 immediately. Never prompt for tokens mid-pipeline.
| Tracker | Command Pattern | Auth Environment Variable |
|---|---|---|
| YouTrack | curl -X POST {instance}/api/issues/{ID} -H "Authorization: Bearer $YOUTRACK_TOKEN" -H "Content-Type: application/json" -d '{"customFields":[{"name":"{sprint_field}","$type":"SingleEnumIssueCustomField","value":{"name":"{sprint_name}"}}]}' | YOUTRACK_TOKEN |
| Jira | curl -X POST {instance}/rest/agile/1.0/sprint/{resolved_id}/issue -u "$JIRA_USER:$JIRA_TOKEN" -H "Content-Type: application/json" -d '{"issues":["{ID}"]}' | JIRA_USER, JIRA_TOKEN |
| Linear | curl -X POST https://api.linear.app/graphql -H "Authorization: $LINEAR_TOKEN" -H "Content-Type: application/json" -d '{"query":"mutation { issueUpdate(id: \"{ID}\", input: {cycleId: \"{resolved_uuid}\"}) { success } }"}' | LINEAR_TOKEN |
| GitHub | curl -X PATCH https://api.github.com/repos/{owner}/{repo}/issues/{issue_number} -H "Authorization: token $GITHUB_TOKEN" -H "Content-Type: application/json" -d '{"milestone": {resolved_number}}' | GITHUB_TOKEN |
| Gitea | curl -X PATCH {instance}/api/v1/repos/{owner}/{repo}/issues/{issue_number} -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" -d '{"milestone": {resolved_id}}' | GITEA_TOKEN |
| Redmine | curl -X PUT {instance}/issues/{ID}.json -H "X-Redmine-API-Key: $REDMINE_TOKEN" -H "Content-Type: application/json" -d '{"issue":{"fixed_version_id":{resolved_id}}}' | REDMINE_TOKEN |
Display: "Could not assign {ID} to {sprint_name} in {tracker_type}. Assign manually in your tracker."
Set sprint_assigned: false for this issue. Continue to next issue.
All assignment failures are NON-BLOCKING. On any tier failure: log WARN, set sprint_assigned: false, continue.
After all assignments: display "Assigned {success}/{total} issues to {sprint_name}."
Update state.json per issue: write sprint_assigned (true/false). Follow atomic write protocol from ../../core/state-manager.md.
--apply only)If --apply is NOT present: display suggested commands and STOP:
Sprint planned. To implement:
/agent-flow:implement-feature {ID-1}
/agent-flow:implement-feature {ID-2}
...
/agent-flow:fix-bugs {BUG-ID-1}
If --apply is present: for each selected issue in dependency order:
/agent-flow:fix-bugs {ID}; otherwise โ dispatch /agent-flow:implement-feature {ID}state.json per child: write child_run_id, issue status, increment completed_issues or blocked_issuesUpdate state.json: set top-level status to "completed". Follow atomic write protocol from ../../core/state-manager.md.
--all mode (release plan)If --all is set and overflow issues remain after Step 5:
Append release summary after all sprints:
### Release Summary
| Sprint | Issues | {unit} | Notable |
|--------|--------|--------|---------|
| Sprint {YYYY}-W{WW} | {N} | {total} {unit} | {P0 issues or "--"} |
| Sprint {YYYY}-W{WW+2} | {N} | {total} {unit} | -- |
Sprint {YYYY}-W{WW} (ISO 8601 week, zero-padded, e.g. Sprint 2026-W16)--yolo โ insufficient AC is a quality signal that cannot be bypassed--dry-run wins over --apply when both are present--yolo --apply is the only path to fully automated sprint dispatchvelocity_source != "historical"../../core/agent-override-injector.md before every Task dispatchIF Team capacity AND Velocity target both configured:
IF Velocity target > Team capacity:
WARN "Velocity target exceeds Team capacity. Using Team capacity."
effective_capacity = Team capacity
ELSE:
effective_capacity = min(Team capacity, Velocity target)
ELSE IF only Team capacity configured:
effective_capacity = Team capacity
ELSE IF only Velocity target configured:
effective_capacity = Velocity target
ELSE:
effective_capacity = null (unconstrained โ top-N by priority)
Triage complexity takes precedence over priority-engine Effort score.
| Source | XS / 1 | S / 2 | M / 3 | L / 4 | 5 |
|---|---|---|---|---|---|
| Triage complexity โ SP | 1 | 2 | 3 | 5 | โ |
| Triage complexity โ Hours | 2 | 4 | 8 | 16 | โ |
| Priority-engine Effort โ SP | 1 | 2 | 3 | 5 | 8 |
| Priority-engine Effort โ Hours | 0.5 | 1 | 2 | 4 | 8 |
| Default (no data) | 3 SP or 2h | โ | โ | โ | โ |