--- name: AILANG Sprint Planner description: Analyze design docs, calculate velocity from recent work, and create realistic sprint plans with day-by-day breakdowns. Use when user asks to "plan sprint", "create sprint plan", or wants to estimate development timeline. --- # AILANG Sprint Planner Create comprehensive, data-driven sprint plans by analyzing design documentation, current implementation status, and recent velocity. ## Quick Start **Most common usage:** ```bash # User says: "Plan the next sprint based on v0.4.0 roadmap" # This skill will: # 1. Read design doc (design_docs/planned/v0.4-roadmap.md) # 2. Analyze CHANGELOG for recent velocity # 3. Review current implementation status # 4. Propose realistic milestones with LOC estimates # 5. Create day-by-day task breakdown ``` ## When to Use This Skill Invoke this skill when: - User says "plan sprint", "create sprint plan", "plan next phase" - User asks to estimate timeline for a feature or design doc - User wants to know how long implementation will take - User needs to prioritize work for upcoming development ## Coordinator Integration **When invoked by the AILANG Coordinator** (detected by GitHub issue reference in the prompt), you MUST output these markers at the end of your response: ``` SPRINT_PLAN_PATH: design_docs/planned/vX_Y/sprint-plan-name.md SPRINT_JSON_PATH: .ailang/state/sprints/sprint_ID.json ``` **Why?** The coordinator uses these markers to: 1. Read the sprint plan content for GitHub comments 2. Track artifacts across pipeline stages 3. Provide visibility to humans reviewing the issue **Example completion:** ``` ## Sprint Plan Created I've created the sprint plan with 3 milestones... **SPRINT_PLAN_PATH**: `design_docs/planned/v0_6_3/m-feature-sprint-plan.md` **SPRINT_JSON_PATH**: `.ailang/state/sprints/sprint_M-FEATURE.json` ``` ## Documentation URLs When planning sprints that involve adding error messages, help text, or documentation links: **Website**: https://ailang.sunholo.com/ **Documentation Source**: The website documentation lives in this repo at `docs/` - Markdown files: `docs/docs/` (guides, reference, etc.) - Static assets: `docs/static/` - Docusaurus config: `docs/docusaurus.config.js` **Common Documentation Paths**: - Language syntax: `/docs/reference/language-syntax` - Module system: `/docs/guides/module_execution` - Getting started: `/docs/guides/getting-started` - REPL guide: `/docs/guides/getting-started#repl` - Implementation status: `/docs/reference/implementation-status` - Benchmarking: `/docs/guides/benchmarking` - Evaluation: `/docs/guides/evaluation/README` **Full URL Example**: ``` https://ailang.sunholo.com/docs/reference/language-syntax ``` **Best Practices**: - When planning features that include documentation links, verify the URLs exist before including them in sprint estimates - Look in `docs/docs/` to verify the file exists locally - Use `ls docs/docs/reference/` or `ls docs/docs/guides/` to find available pages ## Role in Long-Running Agent Pattern **sprint-planner acts as the "Initializer" agent** in the two-phase pattern from [Anthropic's long-running agent article](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): - **Initializer (sprint-planner)**: Creates infrastructure for execution - Analyzes design docs and calculates velocity - Creates markdown sprint plan (human-readable) - **NEW**: Creates JSON progress file (machine-readable) - Sets up session resumption infrastructure - Sends handoff message to sprint-executor - **Coding Agent (sprint-executor)**: Works incrementally across sessions - Reads JSON progress file on each session start - Updates only `passes` field as milestones complete - Can pause/resume work across multiple sessions This separation enables **multi-session continuity** - sprints can span days or weeks with Claude resuming work from where it left off. ## Available Scripts ### `scripts/analyze_velocity.sh [days]` Analyze recent development velocity from CHANGELOG and git commits. **Usage:** ```bash # Analyze last 7 days (default) .claude/skills/sprint-planner/scripts/analyze_velocity.sh # Analyze last 14 days .claude/skills/sprint-planner/scripts/analyze_velocity.sh 14 ``` **Output:** ``` Analyzing velocity for last 7 days... === Recent CHANGELOG Entries === Total: ~1,200 LOC Total: ~800 LOC === Recent Commits (last 7 days) === abc1234 Complete M-DX1.5: Migrate all builtins def5678 Add Type Builder DSL === Files Changed (last 7 days) === 15 files changed, 1200 insertions(+), 300 deletions(-) === Velocity Summary === Based on CHANGELOG entries and git history, estimate: - Average LOC/day from recent milestones - Typical milestone duration - Current development pace ``` ### `scripts/create_sprint_json.sh [design_doc_md]` **NEW**: Create structured JSON progress file for multi-session sprint execution. **Usage:** ```bash # Create JSON progress file from sprint plan .claude/skills/sprint-planner/scripts/create_sprint_json.sh \ "M-S1" \ "design_docs/planned/v0_4_0/m-s1-sprint-plan.md" \ "design_docs/planned/v0_4_0/m-s1-parser-improvements.md" ``` **What it does:** - Creates `.ailang/state/sprints/sprint_.json` with feature list - Implements "constrained modification" pattern (only `passes` field changes) - Enables session resumption via structured state - Provides template for milestone details (to be filled in) **Output:** - JSON progress file at `.ailang/state/sprints/sprint_.json` - Validation check - Next steps instructions (edit JSON, send handoff message) **File Organization:** Sprint JSON files are stored in `.ailang/state/sprints/` to keep the state directory organized. **Integration with sprint-executor:** After creating the JSON file, sprint-executor can: - Resume work across multiple Claude Code sessions - Track progress programmatically - Update velocity metrics automatically ## Sprint Planning Workflow **CRITICAL: Always end by handing off to sprint-executor after user approval!** ### 1. Read and Analyze Design Document **Input**: Path to design doc (e.g., `design_docs/planned/v0.4-roadmap.md`) **What to extract:** - Completed milestones (marked ✅) - Remaining milestones (marked ❌, ⏳, 📋) - Target metrics (LOC estimates, timeline, acceptance criteria) - Dependencies between milestones ### 2. Review Current Implementation Status **Check these sources:** - `CHANGELOG.md` - Recent features and LOC counts - `git log --oneline --since="1 week ago"` - Actual commits - `make test-coverage-badge` - Current test coverage - Design doc vs reality - gaps or partial implementations ### 3. Analyze Recent Velocity **Use the velocity script:** ```bash .claude/skills/sprint-planner/scripts/analyze_velocity.sh ``` **Calculate:** - LOC per day from recent milestones - Average milestone duration - Actual completion rate vs estimates ### 4. Identify Remaining Work **List incomplete milestones with:** - Dependencies (what blocks what) - Estimated effort (from design doc) - Priority (based on dependencies, critical path) - Current velocity (can we realistically do this?) ### 5. Propose Sprint Plan **Use the template:** See [`resources/sprint_plan_template.md`](resources/sprint_plan_template.md) **Include:** - **Sprint Summary**: Goal, duration, key deliverables - **Milestone Breakdown**: For each milestone: - Name and description - Estimated LOC (implementation + tests) - **Example files to create/update** (CRITICAL - required for every new feature) - Dependencies - Acceptance criteria - Risk factors - **Task List**: Day-by-day breakdown (if < 1 week) or weekly (if longer) - **Success Metrics**: - Test coverage target - **Example files created and verified working** (CRITICAL - see CLAUDE.md) - Docs to update ### 6. Present for Feedback **Show user:** - Proposed milestones with estimates - Assumptions made - Areas where input is needed - Realistic timeline based on actual velocity **Be ready to revise** based on user priorities or constraints. ### 7. Finalize and Document **Once approved:** ```bash # Create sprint plan document (markdown - human-readable) # Naming: M-.md (M-P1 for parser, M-T1 for types, etc.) ``` **Include in sprint plan:** - Goal and motivation - Technical approach - Day-by-day implementation plan - Acceptance criteria - Estimated LOC - Dependencies **NEW: Create JSON progress file (machine-readable):** ```bash # Create structured progress file for multi-session execution .claude/skills/sprint-planner/scripts/create_sprint_json.sh \ "" \ "design_docs/planned/vX_Y/-plan.md" \ "design_docs/planned/vX_Y/-design.md" ``` ### 8. MANDATORY: Populate JSON with Real Milestones **The script creates a TEMPLATE - you MUST populate it with real data!** The `create_sprint_json.sh` script generates placeholder content. **Before handing off to sprint-executor, you MUST edit the JSON file to include actual milestones.** **Required edits to `.ailang/state/sprints/sprint_.json`:** 1. **Replace placeholder features array** with real milestones: ```json "features": [ { "id": "M1_ACTUAL_NAME", "description": "Real description from your sprint plan", "estimated_loc": 150, "dependencies": [], "acceptance_criteria": [ "Actual criterion from sprint plan", "Another real criterion" ], "passes": null, "started": null, "completed": null, "notes": null } ] ``` 2. **Update velocity estimates** to match your sprint plan: ```json "velocity": { "target_loc_per_day": 150, "estimated_total_loc": 670, "estimated_days": 4 } ``` **Validation checklist before handoff:** - [ ] No milestone has `"id": "MILESTONE_ID"` (placeholder) - [ ] Each milestone has real acceptance criteria (not "Criterion 1") - [ ] `estimated_total_loc` matches sum of milestone LOC - [ ] `estimated_days` matches sprint plan duration - [ ] At least 2 milestones defined **sprint-executor will REJECT the sprint if placeholders remain!** ### 8.1. Link GitHub Issues (Automatic via ailang messages) **The script automatically discovers related GitHub issues using `ailang messages` integration.** The `create_sprint_json.sh` script automatically: 1. **Syncs GitHub issues** via `ailang messages import-github` 2. Extracts message IDs from the design doc's "Bug Report" field (pattern: `msg_YYYYMMDD_HHMMSS_hash`) 3. **Queries local messages** for issues matching design doc keywords 4. Extracts explicit `#123` references from the design doc 5. Adds `github_issues: [...]` to the sprint JSON **Why link GitHub issues?** - Development commits use `refs #123` to link without closing - Final commit uses `Fixes #123` to AUTO-CLOSE issue on merge - Issues are updated with links to commits/PRs - Audit trail from bug report → design doc → sprint → commits → release **Important: "refs" vs "Fixes"** - `refs #17` - Links commit to issue (NO auto-close) - use during development - `Fixes #17`, `Closes #17`, `Resolves #17` - AUTO-CLOSES issue when merged - use in final commit **Deduplication:** `ailang messages import-github` checks existing issues by number before importing. Issues are never duplicated. **Manual linking (if auto-extraction misses issues):** ```bash # Add GitHub issues to sprint JSON jq '.github_issues = [17, 42]' .ailang/state/sprints/sprint_.json > tmp && mv tmp .ailang/state/sprints/sprint_.json ``` **Example JSON with linked issues:** ```json { "sprint_id": "M-BUG-FIX", "github_issues": [17, 42], "features": [...] } ``` **Workflow with GitHub integration:** 1. External project sends bug report: `ailang messages send user "Bug: ..." --type bug --github` 2. GitHub issue #17 is created and linked to message 3. Design doc references message ID: `**Bug Report**: msg_20251210_..._abc123` 4. `create_sprint_json.sh` extracts message ID, looks up issue #17, adds to JSON 5. Sprint-executor includes `refs #17` in milestone commits (links, no close) 6. Final sprint commit uses `Fixes #17` to auto-close issue on merge ### 9. ALWAYS Hand Off to sprint-executor **CRITICAL: After creating an approved sprint plan, ALWAYS hand off to sprint-executor immediately.** This is the standard workflow: 1. **sprint-planner** (this skill): Creates plan + JSON progress file 2. **sprint-executor** (implementation agent): Executes the plan with TDD **Send handoff message:** ```bash ailang agent send sprint-executor '{ "type": "plan_ready", "correlation_id": "sprint__", "sprint_id": "", "plan_path": "design_docs/planned/vX_Y/-plan.md", "progress_path": ".ailang/state/sprints/sprint_.json", "estimated_duration": "X days (Y hours)", "milestones": [ {"id": "M1", "name": "...", "estimated_hours": X}, {"id": "M2", "name": "...", "estimated_hours": Y} ], "discovery": "Key findings from analysis", "total_loc_estimate": N, "risk_level": "low|medium|high" }' ``` **Why this workflow?** - sprint-executor specializes in TDD, continuous linting, progress tracking - Enables multi-session work (sprints can span days/weeks) - Proper separation of concerns: planning vs execution **Optional: Commit before handoff:** ```bash git add design_docs/YYYYMMDD/M-.md git add .ailang/state/sprints/sprint_.json git commit -m "Add M- sprint plan with JSON progress tracking" ``` ## Analysis Framework ### Design Doc Analysis Checklist - [ ] Current status: What's ✅ vs ❌ vs ⏳ - [ ] Timeline: Days/weeks remaining, velocity metrics - [ ] Priority matrix: Critical vs nice-to-have - [ ] Deferred items: Features pushed to later versions - [ ] Technical debt: Known issues or limitations ### Implementation Analysis Checklist - [ ] CHANGELOG.md: Recent features, LOC counts, test counts - [ ] Git history: Actual work done (not just documented) - [ ] Test files: Coverage, test counts, test patterns - [ ] Code files: Actual implementation, not just stubs - [ ] TODO/FIXME: Inline comments about future work - [ ] **Example files: What works vs what's broken** (check `examples/` directory) - [ ] **Example coverage: Does every new feature have a working example?** (CRITICAL) ### Gap Analysis Checklist - [ ] Features in design doc but not implemented - [ ] Features implemented but not in design doc - [ ] Estimated LOC vs actual LOC (for velocity) - [ ] Planned vs actual timeline - [ ] Test coverage gaps - [ ] Documentation gaps ## Resources ### Sprint Plan Template See [`resources/sprint_plan_template.md`](resources/sprint_plan_template.md) for complete sprint plan structure. ## Best Practices ### 1. Be Conservative with Estimates - Use actual velocity from recent work - Add 20-30% buffer for unknowns - Don't promise more than recent velocity suggests ### 2. Prioritize Ruthlessly - Focus on highest-value items first - Don't try to do everything in one sprint - Defer nice-to-haves to future sprints ### 3. Make Tasks Concrete - ❌ "Implement X" is too vague - ✅ "Write parser for X syntax (~100 LOC) + 15 test cases" is concrete - Each task should be achievable in 1 day or less ### 4. Consider Technical Debt - Don't just add features, also fix issues - Balance new work with quality improvements - Factor in time for bug fixes and refactoring ### 5. Plan for Testing - Every feature needs tests - Test LOC is usually 30-50% of implementation LOC - Include test writing in timeline estimates ### 6. Document Assumptions - Make implicit assumptions explicit - Note areas of uncertainty - Highlight where you need user input ### 7. Verify Design Doc Has Systemic Analysis **Before planning a sprint for a bug fix, verify the design doc addresses systemic issues.** The `design-doc-creator` skill includes guidance for auditing related code paths before writing a design doc. If the design doc only fixes the reported symptom without checking for similar gaps, send it back for revision. **Quick check:** Does the design doc mention: - [ ] Search for similar code paths performed? - [ ] Other types/cases checked for same gap? - [ ] Unified fix covering all cases (not just reported one)? **If not:** Ask user to revise design doc before planning sprint. See `design-doc-creator` skill for full systemic analysis checklist. ## Output Format See [`resources/sprint_plan_template.md`](resources/sprint_plan_template.md) for full template. **Key sections:** - Summary (goal, duration, risk level) - Current status analysis (completed, velocity, remaining) - Proposed milestones (with tasks, criteria, risks) - Success metrics - Dependencies and open questions ## Progressive Disclosure This skill loads information progressively: 1. **Always loaded**: This SKILL.md file (YAML frontmatter + workflow) 2. **Execute as needed**: Scripts in `scripts/` (velocity analysis) 3. **Load on demand**: `resources/sprint_plan_template.md` (template) Scripts execute without loading into context window, saving tokens. ## Coordinator Integration (v0.6.2+) The sprint-planner skill integrates with the AILANG Coordinator for automated workflows. ### Autonomous Workflow When configured in `~/.ailang/config.yaml`, the sprint-planner agent: 1. Receives handoff messages from design-doc-creator 2. Creates sprint plans from design docs 3. Hands off to sprint-executor on completion ```yaml coordinator: agents: - id: sprint-planner inbox: sprint-planner workspace: /path/to/ailang capabilities: [research, docs, planning] trigger_on_complete: [sprint-executor] auto_approve_handoffs: false session_continuity: true ``` ### Receiving Handoffs from design-doc-creator The sprint-planner receives: ```json { "type": "design_doc_ready", "correlation_id": "task-123", "design_doc_path": "design_docs/planned/v0_6_3/m-semantic-caching.md", "session_id": "claude-session-abc" } ``` ### Sending Tasks to sprint-planner ```bash # Direct task (skip design-doc-creator) ailang messages send sprint-planner "Plan sprint for M-CACHE feature" \ --title "Sprint: M-CACHE" --from "user" # Reference existing design doc ailang messages send sprint-planner '{"design_doc_path": "design_docs/planned/v0_6_3/m-cache.md"}' \ --title "Sprint: M-CACHE" --from "design-doc-creator" ``` ### Handoff Message to sprint-executor On completion, sprint-planner sends: ```json { "type": "plan_ready", "correlation_id": "sprint_M-CACHE_20251231", "sprint_id": "M-CACHE", "plan_path": "design_docs/planned/v0_6_3/m-cache-sprint-plan.md", "progress_path": ".ailang/state/sprints/sprint_M-CACHE.json", "session_id": "claude-session-xyz", "estimated_duration": "3 days", "total_loc_estimate": 650, "risk_level": "medium" } ``` ### Human-in-the-Loop With `auto_approve_handoffs: false`: 1. Sprint plan is created in worktree 2. JSON progress file is created 3. Approval request shows sprint plan in dashboard 4. Human reviews plan feasibility 5. Approve → Merges to main, triggers sprint-executor 6. Reject → Worktree preserved, plan can be revised ### Session Continuity With `session_continuity: true`: - Receives `session_id` from design-doc-creator handoff - Uses `--resume SESSION_ID` for Claude Code CLI - Preserves context from previous agent's work - Enables seamless multi-agent conversations ## Notes - This skill is interactive - expect back-and-forth with user - Sprint plans should be realistic, not aspirational - Use actual data (velocity, LOC counts) over guesses - Update design docs as reality diverges from plan - Don't commit plan until approved by user