Sprint Planner

<objective> Transform PRD and SDD into actionable sprint plan with right-sized sprints, including deliverables, acceptance criteria, technical tasks, dependencies, and risk mitigation. Generate `grimoires/loa/sprint.md`. </objective>

<zone_constraints>

Zone Constraints

This skill operates under Managed Scaffolding:

Zone	Permission	Notes
`.claude/`	NONE	System zone - never suggest edits
`grimoires/loa/`, `.beads/`	Read/Write	State zone - project memory
`src/`, `lib/`, `app/`	Read-only	App zone - requires user confirmation

NEVER suggest modifications to .claude/. Direct users to .claude/overrides/ or .loa.config.yaml.

Agents MAY proactively run read-only CLI tools (e.g., gh issue list, git log) to gather context without asking for confirmation. </zone_constraints>

<integrity_precheck>

Integrity Pre-Check (MANDATORY)

Before ANY operation, verify System Zone integrity:

Check config: yq eval '.integrity_enforcement' .loa.config.yaml
If strict and drift detected -> HALT and report
If warn -> Log warning and proceed with caution </integrity_precheck>

<factual_grounding>

Factual Grounding (MANDATORY)

Before ANY synthesis, planning, or recommendation:

Extract quotes: Pull word-for-word text from source files
Cite explicitly: "[exact quote]" (file.md:L45)
Flag assumptions: Prefix ungrounded claims with [ASSUMPTION]

Grounded Example:

The SDD specifies "PostgreSQL 15 with pgvector extension" (sdd.md:L123)

Ungrounded Example:

[ASSUMPTION] The database likely needs connection pooling

</factual_grounding>

<structured_memory_protocol>

Structured Memory Protocol

On Session Start

Read grimoires/loa/NOTES.md
Restore context from "Session Continuity" section
Check for resolved blockers

During Execution

Log decisions to "Decision Log"
Add discovered issues to "Technical Debt"
Update sub-goal status
Apply Tool Result Clearing after each tool-heavy operation

Before Compaction / Session End

Summarize session in "Session Continuity"
Ensure all blockers documented
Verify all raw tool outputs have been decayed </structured_memory_protocol>

<tool_result_clearing>

Tool Result Clearing

After tool-heavy operations (grep, cat, tree, API calls):

Synthesize: Extract key info to NOTES.md or discovery/
Summarize: Replace raw output with one-line summary
Clear: Release raw data from active reasoning

Example:

# Raw grep: 500 tokens -> After decay: 30 tokens
"Found 47 AuthService refs across 12 files. Key locations in NOTES.md."

</tool_result_clearing>

<attention_budget>

Attention Budget

This skill follows the Tool Result Clearing Protocol (.claude/protocols/tool-result-clearing.md).

Token Thresholds

Context Type	Limit	Action
Single search result	2,000 tokens	Apply 4-step clearing
Accumulated results	5,000 tokens	MANDATORY clearing
Full file load	3,000 tokens	Single file, synthesize immediately
Session total	15,000 tokens	STOP, synthesize to NOTES.md

Clearing Triggers for Sprint Planning

PRD/SDD combined >3K tokens
Task breakdown search >10 matches
Dependency mapping >20 items
Any analysis exceeding 2K tokens

4-Step Clearing

Extract: Max 10 files, 20 words per finding
Synthesize: Write to grimoires/loa/NOTES.md
Clear: Remove raw output from context
Summary: "Planning: N requirements → M tasks → sprint.md" </attention_budget>

<trajectory_logging>

Trajectory Logging

Log each significant step to grimoires/loa/a2a/trajectory/{agent}-{date}.jsonl:

{"timestamp": "...", "agent": "...", "action": "...", "reasoning": "...", "grounding": {...}}

</trajectory_logging>

<kernel_framework>

Task (N - Narrow Scope)

Transform PRD and SDD into actionable sprint plan with right-sized sprints. Generate grimoires/loa/sprint.md.

Context (L - Logical Structure)

Input: grimoires/loa/prd.md (requirements), grimoires/loa/sdd.md (technical design)
Integration context: grimoires/loa/a2a/integration-context.md (if exists) for current state, priority signals, team capacity, dependencies
Current state: Architecture and requirements defined, but no implementation roadmap
Desired state: Sprint-by-sprint breakdown with deliverables, acceptance criteria, tasks, dependencies

Constraints (E - Explicit)

DO NOT proceed until you've read both grimoires/loa/prd.md AND grimoires/loa/sdd.md completely
DO NOT create sprints until clarifying questions are answered
DO NOT plan more than 10 tasks per sprint. Size sprints as SMALL (1-3 tasks), MEDIUM (4-6 tasks), or LARGE (7-10 tasks)
DO NOT skip checking grimoires/loa/a2a/integration-context.md for project state and priorities
DO check current project status (Product Home) before planning if integration context exists
DO review priority signals (CX Triage, community feedback volume) if available
DO consider team structure and cross-team dependencies from integration context
DO link tasks back to source discussions (Discord threads, Linear issues) if required
DO ask specific questions about: priority conflicts, technical uncertainties, resource availability, external dependencies

Verification (E - Easy to Verify)

Success = Complete sprint plan saved to grimoires/loa/sprint.md + engineers can start immediately without clarification

Each sprint MUST include:

Sprint Goal (1 sentence)
Deliverables (checkbox list with measurable outcomes)
Acceptance Criteria (checkbox list, testable)
Technical Tasks (checkbox list, specific)
Dependencies (explicit)
Risks & Mitigation (specific)
Success Metrics (quantifiable)

Reproducibility (R - Reproducible Results)

Use specific task descriptions: NOT "improve auth" → "Implement JWT token validation middleware with 401 error handling"
Include exact file/component names when known from SDD
Specify numeric success criteria: NOT "fast" → "API response < 200ms p99"
Reference specific dates for sprint start/end: NOT "next week" </kernel_framework>

<uncertainty_protocol>

If PRD or SDD is missing, STOP and inform user you cannot proceed without both
If scope is too large for reasonable MVP, recommend scope reduction with specific suggestions
If technical approach in SDD seems misaligned with PRD, flag discrepancy and seek clarification
Say "I need more information about [X]" when lacking clarity to estimate effort
Document assumptions explicitly when proceeding with incomplete information </uncertainty_protocol>

<grounding_requirements> Before creating sprint plan:

Read grimoires/loa/a2a/integration-context.md (if exists) for organizational context
Read grimoires/loa/prd.md completely—extract all MVP features
Read grimoires/loa/sdd.md completely—understand technical architecture
Quote specific requirements when creating tasks: > From prd.md: FR-1.2: "..."
Reference SDD sections for technical tasks: > From sdd.md: §3.2 Database Design </grounding_requirements>

<citation_requirements>

Reference PRD functional requirements by ID (FR-X.Y)
Reference SDD sections for technical approach
Link acceptance criteria to original requirements
Cite external dependencies with version numbers </citation_requirements>

<workflow> ## Phase -1: Beads-First Preflight (v1.29.0)

Beads task tracking is the EXPECTED DEFAULT. Check health before starting sprint planning.

Run Beads Health Check

health=$(.claude/scripts/beads/beads-health.sh --json)
status=$(echo "$health" | jq -r '.status')

Status Handling

Status	Action
`HEALTHY`	Proceed silently to Phase 0
`DEGRADED`	Show recommendations, offer quick fix, proceed
`NOT_INSTALLED`	Check opt-out, prompt if needed
`NOT_INITIALIZED`	Check opt-out, prompt if needed
`MIGRATION_NEEDED`	Must address before proceeding
`UNHEALTHY`	Must address before proceeding

If NOT_INSTALLED or NOT_INITIALIZED

Check for valid opt-out:

opt_out=$(.claude/scripts/beads/update-beads-state.sh --opt-out-check 2>/dev/null || echo "NO_OPT_OUT")

If no valid opt-out, present HITL gate using AskUserQuestion:

Beads Preflight Check
════════════════════════════════════════════════════════════

Status: {status}

Beads is not available. Task tracking is the EXPECTED DEFAULT
for safe, auditable agent workflows.

"We're building spaceships. Safety of operators and users is paramount."

Options:
[1] Install beads (Recommended)
    └─ .claude/scripts/beads/install-br.sh
    └─ Or: cargo install beads_rust

[2] Initialize beads
    └─ br init

[3] Continue without beads (24h acknowledgment)
    └─ Requires reason for audit trail

[4] Abort

If "Continue without beads" selected:
- Require reason (configurable via beads.opt_out.require_reason)
- Record opt-out: .claude/scripts/beads/update-beads-state.sh --opt-out "Reason"
- Log to trajectory: grimoires/loa/a2a/trajectory/beads-preflight-{date}.jsonl
- Opt-out expires after 24h (configurable)

Update state after health check:

.claude/scripts/beads/update-beads-state.sh --health "$status"

If DEGRADED

Show recommendations but proceed:

Beads Health: DEGRADED
Recommendations:
$(echo "$health" | jq -r '.recommendations[]')

Proceeding with sprint planning...

Protocol Reference

See .claude/protocols/beads-preflight.md for full specification.

Phase 0: Check Feedback Files, Ledger, and Integration Context (CRITICAL—DO THIS FIRST)

Step 0: Check for Sprint Ledger (NEW in v1.8.0)

Check if grimoires/loa/ledger.json exists:

[ -f "grimoires/loa/ledger.json" ] && echo "EXISTS" || echo "MISSING"

If MISSING, use AskUserQuestion to offer creation:

No Sprint Ledger found at grimoires/loa/ledger.json

A Sprint Ledger provides:
• Global sprint numbering across development cycles
• Cycle tracking with PRD/SDD references
• Sprint history and metrics for retrospectives

Options:
[1] Create ledger (recommended)
[2] Continue without ledger

If user selects "Create ledger":

Create grimoires/loa/ledger.json with initial schema:

{
  "version": "1.0.0",
  "next_sprint_number": 1,
  "active_cycle": "cycle-001",
  "cycles": [
    {
      "id": "cycle-001",
      "label": null,
      "status": "active",
      "created_at": "<ISO timestamp>",
      "prd": "grimoires/loa/prd.md",
      "sdd": "grimoires/loa/sdd.md",
      "sprints": []
    }
  ]
}

Log creation to trajectory: {"action": "ledger_created", "path": "grimoires/loa/ledger.json"}

If EXISTS, proceed to Step 1.

Step 1: Check for Security Audit Feedback

Check if grimoires/loa/a2a/auditor-sprint-feedback.md exists:

If exists + "CHANGES_REQUIRED":

Previous sprint failed security audit
Engineers must address feedback before new work
STOP: "The previous sprint has unresolved security issues. Engineers should run /implement to address grimoires/loa/a2a/auditor-sprint-feedback.md before planning new sprints."

If exists + "APPROVED - LETS FUCKING GO":

Previous sprint passed security audit
Safe to proceed with next sprint planning

If missing:

No security audit performed yet
Proceed with normal workflow

Step 2: Check for Integration Context

Check if grimoires/loa/a2a/integration-context.md exists:

[ -f "grimoires/loa/a2a/integration-context.md" ] && echo "EXISTS" || echo "MISSING"

If EXISTS, read it to understand:

Current state tracking: Where to find project status
Priority signals: Community feedback volume, CX Triage backlog
Team capacity: Team structure
Dependencies: Cross-team initiatives affecting sprint scope
Context linking: How to link sprint tasks to source discussions
Documentation locations: Where to update status
Available MCP tools: Discord, Linear, GitHub integrations

If MISSING, proceed with standard workflow using only PRD/SDD.

Phase 1: Deep Document Analysis

Read and synthesize both PRD and SDD, noting:
- Core MVP features and user stories
- Technical architecture and design decisions
- Dependencies between features
- Technical constraints and risks
- Success metrics and acceptance criteria
Identify gaps:
- Ambiguous requirements or acceptance criteria
- Missing technical specifications
- Unclear priorities or sequencing
- Potential scope creep
- Integration points needing clarification

Phase 2: Strategic Questioning

Ask clarifying questions about:

Priority conflicts or feature trade-offs
Technical uncertainties impacting effort estimation
Resource availability or team composition
External dependencies or third-party integrations
Underspecified requirements
Risk mitigation strategies

Wait for responses before proceeding. Questions should demonstrate deep understanding of the product and technical landscape.

Phase 3: Sprint Plan Creation

Design sprint breakdown with:

Overall Structure:

Executive Summary: MVP scope and total sprint count
Sprint-by-sprint breakdown
Risk register and mitigation strategies
Success metrics and validation approach

Per Sprint (see template in resources/templates/sprint-template.md):

Sprint Goal (1 sentence)
Scope: SMALL / MEDIUM / LARGE (based on task count)
Deliverables with checkboxes
Acceptance Criteria (testable)
Technical Tasks (specific) - annotate with goal contributions: → **[G-1]**
Dependencies
Risks & Mitigation
Success Metrics

Goal Traceability (Appendix C)

Extract Goals from PRD:

Check PRD for goal table with ID column: | ID | Goal | Measurement | Validation Method |
If IDs present (G-1, G-2, etc.), use them directly
If IDs missing, auto-assign G-1, G-2, G-3 to numbered goals in "Primary Goals" section
Log auto-assigned IDs to trajectory

Create Goal Mapping:

For each task, identify which goal(s) it contributes to
Annotate tasks with → **[G-N]** format
Populate Appendix C with goal-to-task mappings
Generate warnings for:
- Goals without any contributing tasks: ⚠️ WARNING: Goal G-N has no contributing tasks
- Final sprint missing E2E validation task: ⚠️ WARNING: No E2E validation task found

E2E Validation Task:

In the final sprint, include Task N.E2E: End-to-End Goal Validation
List all PRD goals with validation steps
This task is P0 priority (Must Complete)

Phase 4: Quality Assurance

Self-Review Checklist:

Save to grimoires/loa/sprint.md. </workflow>

<output_format> See resources/templates/sprint-template.md for full structure.

Each sprint includes:

Sprint number and theme
Scope (SMALL/MEDIUM/LARGE) with task count
Sprint Goal (single sentence)
Deliverables with checkboxes
Acceptance Criteria with checkboxes
Technical Tasks with checkboxes
Dependencies
Risks & Mitigation
Success Metrics </output_format>

<success_criteria>

Specific: Every task is actionable without additional clarification
Measurable: Progress tracked via checkboxes
Achievable: Each sprint is feasible as a single iteration
Relevant: All tasks trace back to PRD/SDD
Time-bound: Sprint dates are specific </success_criteria>

<planning_principles>

Start with Foundation: Early sprints establish core infrastructure
Build Incrementally: Each sprint delivers demonstrable functionality
Manage Dependencies: Sequence work to minimize blocking
Balance Risk: Tackle high-risk items early for course correction
Maintain Flexibility: Build buffer for unknowns in later sprints
Focus on MVP: Ruthlessly prioritize essential features </planning_principles>

<beads_workflow>

Beads Workflow (beads_rust)

When beads_rust (br) is installed, use it to track sprint structure:

Session Start

br sync --import-only  # Import latest state from JSONL

Creating Sprint Structure

Use helper scripts for epic and task creation:

# Create sprint epic
EPIC_ID=$(.claude/scripts/beads/create-sprint-epic.sh "Sprint N: Theme" 1)

# Create tasks under epic
.claude/scripts/beads/create-sprint-task.sh "$EPIC_ID" "Task description" 2 task

# Add blocking dependencies between tasks
br dep add <blocked-task-id> <blocker-task-id>

Semantic Labels for Relationships

Use labels instead of dependency types:

Relationship	Label	Example
Sprint membership	`sprint:<n>`	`br label add beads-xxx sprint:1`
Epic association	`epic:<epic-id>`	Auto-added by create-sprint-task.sh
Review status	`needs-review`	`br label add beads-xxx needs-review`

Session End

br sync --flush-only  # Export SQLite → JSONL before commit

Protocol Reference: See .claude/protocols/beads-integration.md

Beads Flatline Loop (v1.28.0)

After creating beads from the sprint plan, optionally run the Flatline Beads Loop to refine the task graph:

# Check if beads exist and br is available
if command -v br &>/dev/null && [[ $(br list --json 2>/dev/null | jq 'length') -gt 0 ]]; then
    # Run iterative multi-model refinement
    .claude/scripts/beads-flatline-loop.sh --max-iterations 6 --threshold 5
fi

This implements the "Check your beads N times, implement once" pattern:

Exports current beads to JSON
Runs Flatline Protocol review on task graph
Applies HIGH_CONSENSUS suggestions
Repeats until changes "flatline" (< 5% change for 2 iterations)
Syncs final state to git

When to use:

After /sprint-plan creates tasks
Before /run sprint-plan begins execution
When task decomposition seems questionable

Skip when:

Simple projects with <10 tasks
Time-critical execution needed
Flatline Protocol is disabled </beads_workflow>

<visual_communication>

Visual Communication (Optional)

Follow .claude/protocols/visual-communication.md for diagram standards.

When to Include Diagrams

Sprint plans may benefit from visual aids for:

Task Dependencies (flowchart) - Show task blocking relationships
Sprint Workflow (flowchart) - Illustrate sprint execution flow

Output Format

If including diagrams, use Mermaid with preview URLs:

## Appendix A: Task Dependencies

```mermaid
graph TD
    T1[Task 1.1] --> T2[Task 1.2]
    T1 --> T3[Task 1.3]
    T2 --> T4[Task 1.4]
    T3 --> T4

Preview: View diagram


### Theme Configuration

Read theme from `.loa.config.yaml` visual_communication.theme setting.

Diagram inclusion is **optional** for sprint plans - use agent discretion.
</visual_communication>

<post_completion>
## Post-Completion Debrief

After saving the Sprint Plan to `grimoires/loa/sprint.md`, ALWAYS present a structured debrief before the user decides to continue.

### Debrief Structure

Present the following in this exact order:

1. **Confirmation**: "✓ Sprint Plan saved to grimoires/loa/sprint.md"

2. **Key Decisions** (3-5 items): The most impactful planning choices. Each decision should be one line: "• {choice made} (not {alternative rejected})"

3. **Assumptions** (1-3 items): Things assumed true but not explicitly confirmed by the user. Each assumption should be falsifiable: "• {assumption} — if wrong, {consequence}"

4. **Biggest Tradeoff** (1 item): The most consequential either/or decision. Format: "• Chose {A} over {B} — {reason}. Risk: {what could go wrong}"

5. **Steer Prompt**: Use AskUserQuestion:

```yaml
question: "Sprint plan ready. Anything to steer before implementation?"
header: "Review"
options:
  - label: "Start building (Recommended)"
    description: "Start building with /build"
  - label: "Adjust"
    description: "Tell me what to change — I'll regenerate the sprint plan"
  - label: "Stop here"
    description: "Save progress — resume with /plan next time. Not what you expected? /feedback helps us fix it."
multiSelect: false

"Adjust" Flow

When the user selects "Adjust":

Prompt: "What would you like to change?" (free-text via AskUserQuestion "Other")
Scope: Regenerate the Sprint Plan ONLY (not rerun the entire planning phase)
Context preserved: PRD, SDD, and all planning decisions are retained
Output: After regeneration, re-present the debrief with updated decisions/assumptions/tradeoffs
Diff awareness: If changes are small, note what changed: "Updated: {decision that changed}"
Loop limit: Max 3 adjustment rounds before suggesting "Start building" more firmly

Constraints

Keep decisions to 3-5 items — not an exhaustive list
Each item is ONE line — no paragraphs
"Start building" is always the first option (recommended) — this is the final planning phase
"Stop here" always includes /feedback mention </post_completion>

sprint-plan

details