Stats
Actions
Tags
From agent-flow
Plans a sprint from backlog issues using capacity constraints, priority ranking, and configurable gates. Supports dry-run, auto-apply, and release-level planning.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-flow:sprint-plan [--all] [--apply] [--dry-run] [--limit <N>] [--yolo][--all] [--apply] [--dry-run] [--limit <N>] [--yolo]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Input: `$ARGUMENTS` = optional flags (`--all`, `--apply`, `--dry-run`, `--limit <N>`, `--yolo`)
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].
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.
Before dispatch, check Agent Overrides: follow ../../core/agent-override-injector.md.
If {Agent Overrides path}/priority-engine.md exists, append its content to agent context as ## Project-Specific Instructions\n{file content}.
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.
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)Before dispatch, check Agent Overrides: follow ../../core/agent-override-injector.md.
If {Agent Overrides path}/sprint-planner.md exists, append its content to agent context as ## Project-Specific Instructions\n{file content}.
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 | — | — | — | — |
npx claudepluginhub asysta-act/agent-flow --plugin agent-flowPlans sprints by estimating capacity from velocity and availability, selecting backlog stories, mapping dependencies, identifying risks, and outputting a summary with goal. Use for sprint prep.
Recommends sprint scope by pulling backlog from Jira/Linear MCP or manual input, calculating team capacity from velocity and availability, and suggesting committed work, stretch goals, and deferred items.
Runs structured sprint planning: reviews backlog, sets goal, selects stories, estimates capacity, and assigns work. Use at sprint start.