| name | sprint-planner |
| description | Use this skill to plan a new sprint. It uses the Gemini CLI to intelligently decompose approved specs into atomic GitHub issues for the development team. Triggers include "plan sprint", "create sprint", or "start new sprint". |
Sprint Planner Skill
Purpose
To plan and initialize a new sprint by intelligently decomposing approved specifications into a comprehensive set of atomic GitHub issues. This skill bridges the gap between high-level specs and executable work items by using the Gemini CLI to analyze the spec's content and generate a thoughtful task breakdown. It then automates the creation of these tasks as GitHub issues within a new sprint milestone.
When to Use
Use this skill in the following situations:
- Starting a new sprint or development cycle.
- Converting an approved spec into actionable GitHub issues.
- When you want an AI-assisted breakdown of an epic into atomic implementation tasks.
Prerequisites
- Project board configured with an "Approved Backlog" status column.
- Approved spec files exist in the
docs/specs/ directory.
- An Epic issue exists on GitHub that links to the spec file in its body.
gh CLI tool installed and authenticated.jq tool installed for JSON parsing.gemini CLI tool installed and authenticated.
Workflow
Step 1: Review Project Board
Check the project board for approved specs (represented as Epics) ready to be planned.
Step 2: Discuss Sprint Scope with User
Engage the user to determine which epic(s) from the "Approved Backlog" to include in the sprint.
Step 3: Define Sprint Metadata
Work with the user to establish the sprint name (e.g., "Sprint 4").
Step 4: Run the Helper Script
Execute the sprint planning script to automate GitHub issue creation:
bash scripts/create-sprint-issues.sh
Step 5: Understand What the Script Does
The helper script automates these steps:
- Queries Project Board: Fetches all items from the "Approved Backlog" and prompts you to select an Epic to plan.
- Extracts Spec File: Parses the selected Epic's body to find the associated spec file path.
- Creates Milestone: Prompts you for a sprint name and creates the corresponding GitHub milestone.
- Decomposes Spec with AI: Instead of relying on a rigid format, the script sends the full content of the spec file and the parent Epic to the Gemini CLI. It asks the AI to generate a list of atomic, actionable tasks based on its understanding of the document.
- Creates GitHub Issues: The script parses the structured task list from Gemini's response and creates a GitHub issue for each task. Each issue is automatically titled, assigned to the new milestone, and includes a description and references to the parent Epic and spec file.
Step 6: Verify Issue Creation
After the script completes, review the newly created issues in your milestone.
gh issue list --milestone "Your Sprint Name"
Step 7: Review Created Issues with User
Walk through the AI-generated issues with your team. The generated tasks provide a strong baseline, but you should review them to confirm completeness, adjust priorities, and make any necessary refinements.
Error Handling
jq or Gemini Not Installed
Symptom: Script reports that jq or gemini command is not found.
Solution: Install the required tool and ensure it's in your system's PATH.
No Approved Epics Found
Symptom: Script reports no epics in the approved backlog.
Solution: Ensure your Epics are in the correct status column on your project board.
Epic Body Missing Spec Reference
Symptom: Script cannot find a spec file path in the Epic's body.
Solution: Edit the Epic's issue body on GitHub to include a valid path to a spec file (e.g., docs/specs/my-feature.md).
Gemini CLI Issues
Symptom: The script fails during the task decomposition step with an error from the gemini command.
Solution:
- Ensure the
gemini CLI is installed and authenticated (gemini auth).
- Check for API outages or network issues.
- The quality of the task breakdown depends on a functional Gemini CLI.
Notes
- Intelligent Decomposition: The skill no longer relies on a rigid task format in spec files. Gemini reads and understands the document to create tasks.
- LLM guides strategy, script executes: You decide which spec to plan; the script uses AI to handle the tedious decomposition and issue creation.
- One epic per run: Run the script once for each Epic you want to plan for the sprint.
- Traceability is built-in: Each created task issue automatically references the parent Epic and the source spec file.
- Manual refinement is expected: The AI-generated task list is a starting point. Review and adjust it with your team.
