Back to catalog

sprint-plan

Create structured sprint plans with automated Git workflow. Generates TOML sprints, creates feature branches, and enforces proper development workflow.

• Category: discovered
• Tags: github, community
• Version: 1.1.0
• Author: walid
• Downloads: 0
• Updated: 2025-11-22

• Source: AEtherlight-ai/lumina

Download the latest version (v1.1.0) from this page.

SKILL.md

---
name: sprint-plan
version: 1.1.0
description: Create structured sprint plans with automated Git workflow. Generates TOML sprints, creates feature branches, and enforces proper development workflow.
---

# Sprint Planning Skill

## What This Skill Does

Automates sprint planning with Git workflow enforcement:
- Analyzes user requirements and generates sprint structure
- Creates TOML sprint definitions with phases and tasks
- Automatically creates Git branches for features/epics
- Enforces proper branch naming and workflow
- Integrates user context with standardized processes

## ⚠️ CRITICAL: Sprint Format Requirements

**REQUIRED task format:** `[tasks.TASK-ID]` (flat structure)
**OBSOLETE format:** `[[epic.*.tasks]]` (will break SprintLoader)

**5 Required fields per task:**
1. `id` - Task identifier
2. `name` - Task name (NOT "title")
3. `status` - Current status (pending, in_progress, completed)
4. `phase` - Phase name
5. `agent` - Agent assignment

**All other fields are OPTIONAL** - Use minimal format for quick tasks, rich format for complex features.

**Backward compatible:** Old sprints with minimal fields continue to work. New sprints can use rich metadata.

## ⚠️ CRITICAL: Sprint-Aware Naming Convention (Pattern-DOCS-002)

**REQUIRED naming format:** `{SPRINT_ID}_{TASK_ID}_{TYPE}.md`

**Why Sprint ID?** Prevents collisions when multiple sprints have the same task ID (e.g., Sprint 3 BUG-001 vs Sprint 17.1 BUG-001).

**Examples:**
- `17.1-BUGS_BUG-011_ENHANCED_PROMPT.md` (Sprint 17.1, enhanced prompt)
- `17.1-BUGS_BUG-011_QUESTIONS.md` (Sprint 17.1, questions document)
- `3_PROTECT-001_TEST_PLAN.md` (Sprint 3, test plan)
- `4_KEY-002_DESIGN.md` (Sprint 4, design document)

**Sprint ID Extraction:**
- From TOML filename: `ACTIVE_SPRINT_17.1_BUGS.toml` → Sprint ID = `17.1-BUGS`
- Replace underscores with hyphens: `17.1_BUGS` → `17.1-BUGS`

**Document Types:**
- `ENHANCED_PROMPT` - MVP-003 enhanced task prompt
- `QUESTIONS` - Q&A document for task clarification
- `TEST_PLAN` - Test plan and validation criteria
- `DESIGN` - Design document and architecture
- `RETROSPECTIVE` - Post-task retrospective

**Enforcement:**
- Automated via pre-commit hook (INFRA-003)
- Validates naming convention + TOML linking
- See: `docs/patterns/Pattern-DOCS-002-TaskDocumentLinking.md`

**Migration:**
- Old format still works (backward compatible)
- New documents MUST use sprint-aware naming

## When Claude Should Use This

Use this skill when the user:
- Says "plan a sprint" or "create a sprint"
- Wants to organize development work
- Needs to break down features into tasks
- Mentions sprint planning or agile development
- Requests to "add tasks to sprint", "enhance sprint", or "update sprint"

## Invocation Decision: CREATE vs ENHANCE

When this skill is invoked, FIRST determine the mode:

**CREATE Mode** - Creating a new sprint from scratch
- User says: "plan a sprint", "create a sprint", "start new sprint"
- Starting a new feature or project phase
- No existing sprint file to modify
- Workflow: Full sprint creation (Steps 1-6 in CREATE Workflow below)

**ENHANCE Mode** - Adding tasks to existing sprint
- User says: "add tasks to sprint", "enhance sprint", "update current sprint"
- Sprint in progress, needs additional tasks
- Existing `ACTIVE_SPRINT_*.toml` file to modify
- Workflow: Sprint enhancement (see ENHANCE Workflow section after CREATE workflow)

**How to decide:**
1. Check if user mentions "add", "enhance", "update" → ENHANCE mode
2. Check if `internal/sprints/ACTIVE_SPRINT*.toml` exists → Ask user which mode
3. If user explicitly says "create" or "new" → CREATE mode
4. Default: CREATE mode (new sprint)

---

## CREATE Mode Workflow

**Use this workflow when creating a new sprint from scratch.**

### Workflow Process

### 1. Gather Requirements
```
Ask the user:
1. Sprint duration? (1 week, 2 weeks, etc.)
2. Main features/goals?
3. Team size and roles?
4. Priority order?
```

### 2. Analyze and Structure
The skill will:
- Parse user requirements
- Identify epics and features
- Break down into phases
- Create task dependencies
- Assign complexity estimates
- **CRITICAL: Add error handling requirements for EVERY task**
  - Identify potential failure points
  - Require try-catch for all parsing/IO operations
  - Add validation criteria for error boundaries
  - Include error recovery strategies

### 2.5: Inject Template Tasks (Pattern-SPRINT-TEMPLATE-001)

**CRITICAL: After generating feature tasks, automatically inject normalized template tasks.**

This step ensures every sprint includes quality assurance, documentation, and retrospective tasks.

#### Template Injection Process

**Step 1: Load Template**
```javascript
// Load SPRINT_TEMPLATE.toml
const fs = require('fs');
const toml = require('@iarna/toml');

const templatePath = 'internal/sprints/SPRINT_TEMPLATE.toml';
const templateContent = fs.readFileSync(templatePath, 'utf-8');
const template = toml.parse(templateContent);

// Template structure:
// - template.metadata (version, task counts)
// - template.required.* (14 tasks - always include)
// - template.suggested.* (4 tasks - include with skip option)
// - template.conditional.* (8 tasks - condition-based)
// - template.retrospective.* (2 tasks - always include)
```

**Step 2: Detect Conditions**

Analyze sprint requirements to determine which conditional tasks to include:

```javascript
// Condition detection logic
const sprintName = metadata.sprint_name || "";
const sprintDescription = userRequirements || "";
const combinedText = (sprintName + " " + sprintDescription).toLowerCase();

// Publishing condition
const isPublishing = combinedText.includes("publish") ||
                     combinedText.includes("release") ||
                     combinedText.includes("version bump") ||
                     combinedText.includes("v1.0") ||
                     combinedText.includes("deploy");

// User-facing changes condition
const isUserFacing = combinedText.includes("ui") ||
                     combinedText.includes("ux") ||
                     combinedText.includes("user experience") ||
                     combinedText.includes("interface") ||
                     combinedText.includes("component") ||
                     combinedText.includes("breaking change");
```

**Condition Keywords:**

**Publishing Keywords** (triggers PUB-001 to PUB-005):
- "publish", "release", "version bump", "v1.0", "v2.0", "deploy", "distribution"
- Example: "Release v1.0 with authentication" → Publishing tasks included

**User-Facing Keywords** (triggers UX-001 to UX-003):
- "ui", "ux", "user experience", "interface", "component", "breaking change", "migration"
- Example: "Redesign authentication UI" → UX tasks included

**Step 3: Extract Template Tasks**

```javascript
// Extract task categories from template
const requiredTasks = Object.entries(template.required).map(([key, task]) => ({
  ...task,
  category: "REQUIRED",
  canSkip: false
}));

const suggestedTasks = Object.entries(template.suggested).map(([key, task]) => ({
  ...task,
  category: "SUGGESTED",
  canSkip: true,
  skipJustification: ""  // Prompt user for justification if skipping
}));

const conditionalTasks = [];
if (isPublishing) {
  // Include publishing tasks (PUB-001 to PUB-005)
  Object.entries(template.conditional)
    .filter(([key, task]) => task.id.startsWith("PUB-"))
    .forEach(([key, task]) => {
      conditionalTasks.push({
        ...task,
        category: "CONDITIONAL-PUBLISHING",
        condition: "Sprint includes publishing/release"
      });
    });
}

if (isUserFacing) {
  // Include UX tasks (UX-001 to UX-003)
  Object.entries(template.conditional)
    .filter(([key, task]) => task.id.startsWith("UX-"))
    .forEach(([key, task]) => {
      conditionalTasks.push({
        ...task,
        category: "CONDITIONAL-UX",
        condition: "Sprint has user-facing changes"
      });
    });
}

const retrospectiveTasks = Object.entries(template.retrospective).map(([key, task]) => ({
  ...task,
  category: "RETROSPECTIVE",
  canSkip: false
}));

// Total template tasks to inject
const allTemplateTasks = [
  ...requiredTasks,     // 14 tasks
  ...suggestedTasks,    // 4 tasks
  ...conditionalTasks,  // 0-8 tasks (condition-dependent)
  ...retrospectiveTasks // 2 tasks
];
```

**Step 4: Task ID Collision Avoidance**

Template tasks use category prefixes that won't collide with feature tasks:

**Template Task ID Prefixes** (reserved, never use for features):
- `DOC-*` - Documentation tasks (CHANGELOG, README, patterns)
- `QA-*` - Quality assurance tasks (tests, coverage, audits)
- `AGENT-*` - Agent synchronization tasks (context updates)
- `INFRA-*` - Infrastructure tasks (git hooks, validation)
- `CONFIG-*` - Configuration tasks (settings schema)
- `PERF-*` - Performance tasks (regression testing)
- `SEC-*` - Security tasks (vulnerability scans)
- `COMPAT-*` - Compatibility tasks (cross-platform, backwards compat)
- `PUB-*` - Publishing tasks (pre-publish, artifacts, verification)
- `UX-*` - User experience tasks (upgrade docs, screenshots)
- `RETRO-*` - Retrospective tasks (sprint retrospective, pattern extraction)

**Feature Task ID Prefixes** (use for generated tasks):
- `FEAT-*` - New features
- `AUTH-*` - Authentication features
- `API-*` - API endpoints
- `UI-*` - UI components (not to be confused with UX-* template tasks)
- `BUG-*` - Bug fixes
- `REFACTOR-*` - Refactoring tasks
- `[CUSTOM]-*` - Domain-specific prefixes (e.g., VOICE-*, DATA-*, SYNC-*)

**Validation:** Before adding feature tasks, ensure none use reserved template prefixes.

**Step 5: Merge Tasks**

```javascript
// Merge feature tasks with template tasks
const allTasks = {
  // Feature tasks (generated from requirements)
  ...featureTasks,

  // Template tasks (injected from SPRINT_TEMPLATE.toml)
  ...allTemplateTasks.reduce((acc, task) => {
    acc[task.id] = task;
    return acc;
  }, {})
};

// Example merged task list:
// - FEAT-001: Implement user authentication (feature)
// - FEAT-002: Add password reset flow (feature)
// - DOC-001: Update CHANGELOG.md (template-required)
// - DOC-002: Update README.md (template-required)
// - QA-001: Run ripple analysis (template-required)
// - PUB-001: Pre-publish validation (template-conditional, if publishing)
// - RETRO-001: Sprint retrospective (template-retrospective)
```

**Step 6: Generate Sprint TOML with Merged Tasks**

The final sprint TOML includes both feature and template tasks:

```toml
[metadata]
version = "1.0.0"
sprint_number = 1
status = "active"
# ... rest of metadata

# Feature tasks (from requirements)
[tasks.FEAT-001]
id = "FEAT-001"
name = "Implement user authentication"
status = "pending"
phase = "feature-development"
agent = "infrastructure-agent"
# ... rich format fields

[tasks.FEAT-002]
id = "FEAT-002"
name = "Add password reset flow"
status = "pending"
phase = "feature-development"
agent = "infrastructure-agent"
# ... rich format fields

# Template tasks (injected automatically)
[tasks.DOC-001]
id = "DOC-001"
name = "Update CHANGELOG.md with sprint changes"
status = "pending"
phase = "documentation"
agent = "documentation-agent"
# ... full template task definition

[tasks.QA-001]
id = "QA-001"
name = "Run ripple analysis for breaking changes"
status = "pending"
phase = "quality-assurance"
agent = "testing-agent"
# ... full template task definition

# ... all other template tasks (DOC-002 through DOC-005, QA-002 through QA-004, etc.)
# NOTE: DOC-005 is a REFACTORING task (context optimization, -500 lines estimated)

[tasks.RETRO-001]
id = "RETRO-001"
name = "Sprint retrospective"
status = "pending"
phase = "retrospective"
agent = "documentation-agent"
# ... full template task definition
```

#### Template Injection Summary

**Before Template Injection:**
- Feature tasks only: 5-10 tasks
- No quality assurance built in
- Easy to forget documentation, tests, retrospectives

**After Template Injection:**
- Feature tasks: 5-10 tasks
- Template tasks: 20-28 tasks (depending on conditions)
- Total: 25-38 tasks per sprint
- Quality assurance guaranteed
- Consistent sprint structure

**Benefits:**
- ✅ Never forget CHANGELOG updates
- ✅ Never skip test coverage checks
- ✅ Always include dependency audits
- ✅ Consistent retrospectives
- ✅ Automatic publishing checklists (when releasing)
- ✅ Built-in quality ratchet (prevents regression)

**Historical Bug Prevention:**
- DOC-001 (CHANGELOG) prevents undocumented releases (v0.13.29 issue)
- QA-003 (dependency audit) prevents native dep bugs (v0.13.23 issue)
- PUB-001 (pre-publish checklist) prevents version mismatch (v0.13.28 issue)
- INFRA-002 (sprint validation) prevents TOML format bugs (2025-11-03 issue)

**Total Time Saved:** 15+ hours of historical debugging prevented per sprint.

#### Example: Feature-Only Sprint

User: "Plan a sprint to build API endpoints for user management"

**Generated Feature Tasks:**
- API-001: Design user endpoints architecture
- API-002: Implement GET /users
- API-003: Implement POST /users
- API-004: Implement PUT /users/:id
- API-005: Implement DELETE /users/:id

**Injected Template Tasks (23 tasks):**
- REQUIRED (13): DOC-001 to DOC-004, QA-001 to QA-004, AGENT-001 to AGENT-002, INFRA-001 to INFRA-002, CONFIG-001
- SUGGESTED (4): PERF-001, SEC-001, COMPAT-001, COMPAT-002
- CONDITIONAL (0): No publishing keywords detected, no PUB-* tasks
- RETROSPECTIVE (2): RETRO-001, RETRO-002

**Total: 5 feature + 19 template = 24 tasks**

**Condition Detection:**
- isPublishing: false (no "release" or "publish" keywords)
- isUserFacing: false (API-only, no UI keywords)

#### Example: Release Sprint

User: "Plan a sprint to release v2.0 with UI redesign"

**Generated Feature Tasks:**
- UI-001: Redesign dashboard layout
- UI-002: Update theme system
- UI-003: Implement responsive design

**Injected Template Tasks (28 tasks):**
- REQUIRED (14): DOC-001 to DOC-005, QA-001 to QA-004, AGENT-001 to AGENT-002, INFRA-001 to INFRA-002, CONFIG-001
- SUGGESTED (4): PERF-001, SEC-001, COMPAT-001, COMPAT-002
- CONDITIONAL (8):
  - PUB-001 to PUB-005 (publishing detected: "release v2.0")
  - UX-001 to UX-003 (user-facing detected: "UI redesign")
- RETROSPECTIVE (2): RETRO-001, RETRO-002

**Total: 3 feature + 28 template = 31 tasks**

**Condition Detection:**
- isPublishing: true ("release" + "v2.0" keywords detected)
- isUserFacing: true ("UI" + "redesign" keywords detected)

#### SUGGESTED Task Handling

SUGGESTED tasks are included by default but can be skipped with written justification:

**User Prompt (during sprint creation):**
```
Template includes 4 SUGGESTED tasks:
- PERF-001: Performance regression testing
- SEC-001: Security vulnerability scan
- COMPAT-001: Cross-platform testing (Windows/Mac/Linux)
- COMPAT-002: Backwards compatibility check

These tasks are recommended but optional. Would you like to:
1. Include all suggested tasks (recommended)
2. Skip some tasks with justification

If skipping, please provide justification for each (e.g., "No performance-critical changes this sprint").
```

**If user skips with justification:**
```toml
# Add skip justification to sprint notes
[notes]
template_task_justifications = """
SUGGESTED Tasks Skipped:
- PERF-001: No performance-critical changes (API-only sprint)
- COMPAT-001: No platform-specific code changes
"""
```

**Justification examples:**
- "No performance-critical changes this sprint" (skip PERF-001)
- "Internal-only changes, no security risk" (skip SEC-001)
- "Pure TypeScript, no platform-specific code" (skip COMPAT-001)
- "No VS Code API changes, backwards compatible" (skip COMPAT-002)

### 3. Git Workflow Setup

#### For Each Epic/Feature:
```bash
# Create feature branch from master
git checkout master
git pull origin master
git checkout -b feature/[epic-name]

# Create sub-branches for phases
git checkout -b feature/[epic-name]/phase-1
```

#### Branch Naming Convention:
- `feature/[epic-name]` - Main feature branch
- `feature/[epic-name]/phase-[n]` - Phase branches
- `fix/[issue-name]` - Bug fix branches
- `refactor/[component-name]` - Refactoring branches

### 4. Generate Sprint Files

**CRITICAL: Sprint File Naming Convention**

Sprint files MUST follow this pattern to appear in the Sprint dropdown:

**Format:** `ACTIVE_SPRINT_[DESCRIPTOR].toml`

**Examples:**
- `ACTIVE_SPRINT_v0.15.4_UI_REFACTOR.toml` ✓ (version-based)
- `ACTIVE_SPRINT_2025-10-31.toml` ✓ (date-based)
- `ACTIVE_SPRINT_PHASE_1.toml` ✓ (phase-based)
- `ACTIVE_SPRINT_AUTH_FEATURE.toml` ✓ (feature-based)
- `ACTIVE_SPRINT.toml` ✓ (legacy format, still works)
- `sprint.toml` ✗ (won't appear in dropdown)

**Why:** The `ACTIVE_SPRINT` prefix is the identifier that makes it discoverable.
The descriptor after the underscore helps users identify which sprint is which.

**Location:** Place in `internal/sprints/` (ÆtherLight dev) or `sprints/` (user projects)

Create `sprints/ACTIVE_SPRINT_[DESCRIPTOR].toml`:

**CRITICAL: Use `[tasks.ID]` format (NOT `[[epic.*.tasks]]`)**
The SprintLoader expects flat task structure: `data.tasks[taskId]`

```toml
[meta]
sprint_name = "Sprint [Number]"
version = "[version]"
created = "YYYY-MM-DD"
status = "active"

# Tasks use flat structure: [tasks.TASK-ID]
[tasks.AUTH-001]
# REQUIRED FIELDS (5 fields - enforced by SprintSchemaValidator)
id = "AUTH-001"                    # Task ID (must match section key)
name = "Implement JWT tokens"      # Task name (NOT "title")
status = "pending"                 # Status: pending, in_progress, completed
phase = "authentication"           # Phase name
agent = "infrastructure-agent"     # Agent assignment (from AgentRegistry)

# COMMON OPTIONAL FIELDS (recommended for most tasks)
skill = "publish"                  # Optional: Automated workflow to use (see Step 3.6)
                                    # Only for tasks with automated workflows (publish, code-analyze, protect, etc.)
                                    # Omit for manual work (most tasks)
description = "Add JWT token generation and validation"
estimated_time = "4-6 hours"
estimated_lines = 300
dependencies = []                  # Array of task IDs this depends on
assigned_engineer = "engineer_1"
required_expertise = ["typescript", "security"]
deliverables = [
    "JWT token generation function",
    "Token validation middleware",
    "Unit tests for token operations"
]

# ERROR HANDLING (optional but strongly recommended - see template below)
error_handling = """
- Wrap JWT parsing in try-catch
- Handle expired token errors gracefully
- Validate token format before parsing
- Return clear error messages to user
"""
validation_criteria = [
    "All token operations have error boundaries",
    "Invalid tokens don't crash the app",
    "Clear error messages for auth failures"
]
```

### Minimal Valid Sprint (Backward Compatible)

For quick sprints or simple tasks, you only need the **5 required fields**:

```toml
[meta]
sprint_name = "Quick Bug Fix Sprint"
version = "1.0"
status = "active"
created = "2025-11-05"

[tasks.BUG-001]
id = "BUG-001"
name = "Fix login redirect"
status = "pending"
phase = "bugfix"
agent = "general-purpose"
```

This minimal format is **fully compatible** with the sprint system.

### Rich Sprint Format (Recommended for Complex Features)

For complex features, sprint tasks can include **rich metadata** for better context and tracking:

```toml
[tasks.FEATURE-001]
# REQUIRED FIELDS (always needed)
id = "FEATURE-001"
name = "Implement Enhanced Prompt Display"
status = "pending"
phase = "feature-development"
agent = "ui-agent"

# NARRATIVE FIELDS (helps understand WHY and context)
why = """
User expectation: Enhancement button should enhance text in-place.
Current state: Button disabled, function is empty stub.
Users frustrated by missing core feature.
"""

context = """
Feature was removed during v0.16.x refactoring to fix layout bugs.
PromptEnhancer.ts exists but not integrated with UI.
Pattern-UX-001 emphasizes real-time feedback for user actions.
"""

reasoning_chain = [
    "1. User t