sprint-planner

AILANG Sprint Planner

Create comprehensive, data-driven sprint plans by analyzing design documentation, current implementation status, and recent velocity.

Current State

• Branch: !'git branch --show-current'
• Current version: !'cat std/VERSION'
• Active sprints: !'ls .ailang/state/sprints/ 2>/dev/null | head -5 || echo "none"'
• Planned design docs: !'ls design_docs/planned/ 2>/dev/null | head -10'
• Recent velocity (7d): !'git diff --stat $(git log --since="7 days ago" --format=%H | tail -1) HEAD 2>/dev/null | tail -1 || echo "no recent commits"'
• Unread messages: !'ailang messages list --unread --compact 2>/dev/null | head -5 || echo "none"'

Use the data above first. Only re-run these commands manually if the injected context is empty or you need to refresh after making changes.

Quick Start

Most common usage:

# 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:

• 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:

# 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 <sprint_id> <sprint_plan_md> [design_doc_md]

NEW: Create structured JSON progress file for multi-session sprint execution.

Usage:

# 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_<id>.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_<id>.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:

.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

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:

# Create sprint plan document (markdown - human-readable)
# Naming: M-<type><number>.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):

# Create structured progress file for multi-session execution
.claude/skills/sprint-planner/scripts/create_sprint_json.sh \
  "<sprint-id>" \
  "design_docs/planned/vX_Y/<sprint-id>-plan.md" \
  "design_docs/planned/vX_Y/<feature>-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_<id>.json:

1. Replace placeholder features array with real milestones:

   "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:

   "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):

# Add GitHub issues to sprint JSON
jq '.github_issues = [17, 42]' .ailang/state/sprints/sprint_<id>.json > tmp && mv tmp .ailang/state/sprints/sprint_<id>.json

Example JSON with linked issues:

{
  "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:

ailang agent send sprint-executor '{
  "type": "plan_ready",
  "correlation_id": "sprint_<sprint-id>_<date>",
  "sprint_id": "<sprint-id>",
  "plan_path": "design_docs/planned/vX_Y/<sprint-id>-plan.md",
  "progress_path": ".ailang/state/sprints/sprint_<id>.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:

git add design_docs/YYYYMMDD/M-<milestone>.md
git add .ailang/state/sprints/sprint_<id>.json
git commit -m "Add M-<milestone> 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 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 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

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:

{
  "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

# 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:

{
  "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