Sprint Help

# Sprint Help

Get help with the sprint workflow, understand commands, and troubleshoot issues.

## Quick Start

/sprint help # Show this help /sprint init # Initialize sprint from punchlist /sprint 1 # Start Phase 1 /sprint # Continue current phase

## Overview

The sprint workflow is a fully automated development system that takes your project from planning to shipped features:

punchlist-builder → /sprint init → /sprint 1 → /sprint 2 → ... → Done! ↓ ↓ ↓ ↓ PUNCHLIST.md .sprint-config GitHub Issues PRs merged + Milestones + Branches + Tests passing

**What it does:**
1. Converts punchlist items into GitHub Issues
2. Creates feature branches using git worktrees
3. Implements features using specialized agents
4. Runs tests and fixes failures automatically
5. Creates and merges Pull Requests
6. Closes issues after QA verification
7. Repeats until all phases complete

**Key benefit:** You define what to build once (in the punchlist), then the system handles everything from issue creation to deployment.

## Prerequisites

Before running `/sprint init` or `/sprint`, ensure you have:

### Required Tools
- **GitHub CLI (`gh`)** - Must be authenticated
  ```bash
  gh auth login
  gh auth status  # Verify authentication

• Git - Repository with dev branch

  git -C .bare branch  # Should show 'dev' branch
  

Required Files

• Punchlist files - Generated by punchlist-builder agent
  • dev/PUNCHLIST.md - Main index with phase metadata
  • dev/PUNCHLIST_001.md - Phases 1-2 details (optional)
  • dev/PUNCHLIST_002.md - Phases 3-4 details (optional)
  • dev/PUNCHLIST_003.md - Phases 5-6 details (optional)

Repository Setup

• Working directory must be project root
• Dev branch must exist and be accessible
• Remote repository must be configured (for PRs)

Git Repository Structure

This project uses a bare repository with worktrees:

/project-root/
├── .bare/           # Bare repo (shared git data)
├── main/            # Worktree: stable releases (on main branch)
├── dev/             # Worktree: active development (on dev branch)
└── feat-XXX/        # Worktree: temporary feature branches

Key commands:

• Worktree operations: git -C .bare worktree [add|remove|list]
• Branch promotion dev→test: git push origin dev:test (from dev worktree)
• Branch promotion test→main: git merge origin/test (from main worktree)

Branch structure:

• main - Stable releases (checked out in main/)
• test - BRANCH ONLY (no worktree, promoted via push)
• dev - Active development (checked out in dev/)
• feature/* - Feature branches (checked out in feat-XXX/)

Command Reference

/sprint init

Purpose: Initialize sprint configuration from punchlist

What it does:

• Reads PUNCHLIST.md to extract phase metadata
• Generates .sprint-config.json with phase definitions
• Creates GitHub milestones for each phase
• Verifies git setup and GitHub authentication
• Reports initialization status

Usage:

/sprint init                    # Initialize from dev/PUNCHLIST.md
/sprint init path=./docs        # Initialize from custom directory

Output:

• .sprint-config.json in project root
• GitHub milestones created
• Verification report

When to use: Once per project, before starting any sprint work

---

/sprint

Purpose: Continue current phase (resume work)

What it does:

• Reads .sprint-config.json
• Checks for open GitHub issues
• Continues implementation of open issues
• Completes current phase if all issues closed

Usage:

/sprint                         # Continue where you left off

When to use:

• After interruptions or errors
• To resume work on current phase
• When you want to continue without specifying a phase

---

/sprint N

Purpose: Start specific phase N

What it does:

• Reads phase N configuration from .sprint-config.json
• Creates GitHub Issues from punchlist (if not started)
• Runs full implementation loop for all tickets
• Updates phase status to complete when done

Usage:

/sprint 1                       # Start Phase 1
/sprint 2                       # Start Phase 2
/sprint phase=3                 # Alternative syntax

When to use:

• Starting a new phase
• Jumping to a specific phase
• After /sprint init completes

---

/sprint help

Purpose: Show this help documentation

Usage:

/sprint help                    # Display help

Workflow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                      SPRINT WORKFLOW                            │
└─────────────────────────────────────────────────────────────────┘

Step 1: Build Punchlist
┌─────────────────────┐
│ punchlist-builder   │  User provides PRD or project description
│                     │  Agent generates PUNCHLIST.md with phases
└──────────┬──────────┘
           │
           ▼
Step 2: Initialize Sprint
┌─────────────────────┐
│   /sprint init      │  Parses punchlist
│                     │  Creates .sprint-config.json
│                     │  Creates GitHub milestones
└──────────┬──────────┘
           │
           ▼
Step 3: Execute Phases (repeat for each phase)
┌─────────────────────┐
│    /sprint N        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    PHASE IMPLEMENTATION LOOP                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  For each ticket in phase:                                      │
│                                                                 │
│  1. CREATE ISSUES                                               │
│     └─> github-issue-writer agent