Sprint-Until — Deadline-Driven Incremental Upgrade Loop

A Claude Code skill that autonomously upgrades a project through iterative improvements until a specified deadline. Perfect for polishing projects, fixing bugs, improving test coverage, or optimizing performance under time pressure.

Status: Production-ready (v1.0.0) Model: Uses claude -p for persistent external loops (context-window safe) Repository: quantsquirrel/claude-sprint-until

---

Quick Start

1. Install

Clone the repository to your dev tools directory:

git clone https://github.com/quantsquirrel/claude-sprint-until.git ~/dev/tools/claude-sprint-until
cd ~/dev/tools/claude-sprint-until
bash setup.sh

The setup.sh script will:

• Validate SKILL.md
• Create a symlink in ~/.claude/skills/sprint-until
• Print a verification checklist

2. Use

Invoke the skill with a deadline:

# Sprint until 6 AM today
/sprint-until 06:00

# Sprint until 11 PM with specific focus areas
/sprint-until 23:00 --focus tests,performance,security

# Sprint with custom iteration cap
/sprint-until 2026-03-06T18:00 --max-iterations 50

3. Monitor

While the sprint runs:

# Watch progress in real-time
tail -f .sprint/loop.log

# Check iterations completed
cat .sprint/progress.json | jq '.iterations | length'

# View learnings
tail -20 .sprint/learnings.md

# Manual stop (creates .sprint/STOP)
touch .sprint/STOP

# Mark project as fully upgraded (exits loop)
touch .sprint/DONE

---

How It Works

The skill is external persistence loop that spawns a fresh claude -p session per iteration. This design is immune to context window exhaustion—each session is independent.

Flow

User: /sprint-until 06:00 --focus "tests,performance"
           │
           ▼
    ┌─ Parse Arguments ─────────────────────┐
    │ deadline, focus, max-iterations, etc  │
    └─────────┬───────────────────────────┘
              ▼
    ┌─ Confirm Configuration ───────────────┐
    │ Warn about API cost                   │
    │ Ask for approval                      │
    └─────────┬───────────────────────────┘
              ▼
    ┌─ Initialize .sprint/ ─────────────────┐
    │ config.json, progress.json, learnings │
    │ Git tag: sprint/start                 │
    └─────────┬───────────────────────────┘
              ▼
    ┌─ Launch sprint-loop.sh (background)───┐
    │ For each iteration until deadline:    │
    │  1. Generate iteration prompt         │
    │  2. Spawn fresh claude -p session     │
    │  3. Claude picks ONE improvement      │
    │  4. Implement, verify, commit         │
    │  5. Tag: sprint/iter-N                │
    │  6. Log progress & learnings          │
    │  7. Check termination conditions      │
    └───────────────────────────────────────┘

Iteration Loop (Inside sprint-loop.sh)

Each iteration:

1. Analyze — Read project structure, recent progress, and learnings
2. Pick — Choose ONE improvement (by focus priority)
3. Implement — Make the change
4. Verify — Run tests/checks to ensure it works
5. Commit — Safe git commit with tag sprint/iter-N
6. Log — Update progress.json and learnings.md
7. Check — Exit if deadline reached, manual stop, or stagnation detected

---

Configuration & Arguments

Deadline (Required)

Either time-of-day or ISO datetime:

/sprint-until 06:00                    # 6 AM today (or tomorrow if past)
/sprint-until 23:59                    # 11:59 PM
/sprint-until 2026-03-06T18:00         # Specific date + time

Focus Areas (Optional, default: auto-detect)

Comma-separated list. Priority order when not specified:

1. Failing tests / bugs
2. Missing test coverage
3. Type safety / lint errors
4. Performance bottlenecks
5. Security issues
6. Code quality / refactoring
7. Documentation

/sprint-until 06:00 --focus "tests,type-safety"
/sprint-until 06:00 --focus "security,performance"
/sprint-until 06:00 --focus "general"  # Auto-detect

Max Iterations (Optional, default: 100)

Safety cap on iterations:

/sprint-until 06:00 --max-iterations 50  # Stop after 50 iterations

Cost Warning

Each iteration costs ~$0.50 USD (varies by project size). The skill warns before starting. Use --max-iterations to control budget.

---

Sprint State (.sprint/)

The skill creates a .sprint/ directory in your project root:

.sprint/
├── config.json              # Deadline, focus, max-iterations
├── progress.json            # Array of completed iterations
├── learnings.md             # Append-only log of what worked
├── events.jsonl             # Timestamped events (JSON Lines)
├── iteration-1.json         # Claude's response for iteration 1
├── iteration-1.stderr       # Stderr log for iteration 1
├── iteration-2.json
├── iteration-2.stderr
├── ...
├── loop.log                 # Main loop's stdout + stderr
├── STOP                     # Touch to stop (removed after stop)
└── DONE                     # Touch to mark fully upgraded

Adding to .gitignore

The skill auto-adds .sprint/ to .gitignore if not already present. Keep this in git so teammates don't accidentally commit sprint artifacts.

---

Git Integration

The skill creates git tags per iteration:

git tag -l | grep sprint
# sprint/start       (start of sprint)
# sprint/iter-1      (after iteration 1)
# sprint/iter-2      (after iteration 2)
# ...

Rollback to a Specific Iteration

# Rollback to state after iteration 3
git checkout sprint/iter-3 -- .

# Or inspect what changed in iteration 5
git diff sprint/iter-4 sprint/iter-5

---

Stopping the Sprint

Natural Termination

The sprint stops automatically when:

• Deadline reached — time is up
• Fully upgraded — create touch .sprint/DONE
• Stagnation — 3 consecutive iterations with no changes

Manual Stop

# Graceful stop (loop exits after current iteration)
touch .sprint/STOP

# Emergency kill (only if needed)
kill $(cat .sprint/loop.log | grep "PID:" | tail -1 | awk '{print $NF}')

---

Troubleshooting

"claude binary not found"

Ensure Claude Code is installed:

which claude
# /Users/yourname/.local/bin/claude
# or /usr/local/bin/claude
# or /opt/homebrew/bin/claude

"loop already running with pid=XXXX"

Either:

1. The loop is still running (check ps aux | grep claude)
2. The .sprint/.loop-lock directory is stale

# Remove stale lock
rm -rf .sprint/.loop-lock

# Then restart
/sprint-until 06:00

"No meaningful improvements found"

The loop may have hit stagnation (3+ iterations with no changes). Check:

tail -20 .sprint/loop.log          # Last loop messages
tail -20 .sprint/learnings.md      # What was learned
cat .sprint/progress.json | jq '.iterations[-5:]'  # Last 5 iterations

If your project is genuinely "done" (all tests passing, no lint errors, good coverage), create:

echo "Fully upgraded at iteration $(cat .sprint/progress.json | jq '.iterations | length')" > .sprint/DONE

"Claude runs out of context"

This skill is designed to avoid context exhaustion by spawning fresh claude -p sessions per iteration. If you hit context limits:

1. Lower MAX_TURNS (default: 50):

   MAX_TURNS=20 /sprint-until 06:00

2. Lower ITER_TIMEOUT_SEC (default: 1200 = 20 min):

   ITER_TIMEOUT_SEC=600 /sprint-until 06:00

3. Reduce focus scope:

   /sprint-until 06:00 --focus "tests"  # Narrower target

---

Environment Variables

Advanced users can tune behavior:

# Cooldown between iterations (seconds, default: 5)
COOLDOWN=10 /sprint-until 06:00

# Max turns per iteration (default: 50)
MAX_TURNS=30 /sprint-until 06:00

# Max timeout per iteration (seconds, default: 1200)
ITER_TIMEOUT_SEC=1800 /sprint-until 06:00

# Budget cap (USD, default: unlimited)
MAX_BUDGET_USD=50 /sprint-until 06:00

# Stagger before stagnation (default: 3)
MAX_NO_CHANGE_ITERS=5 /sprint-until 06:00

# Custom iteration prompt template
PROMPT_TEMPLATE=/path/to/custom-prompt.md /sprint-until 06:00

# Allowed tools (comma-separated, default: Edit,Write,Bash,Read,Glob,Grep,Agent)
ALLOWED_TOOLS=Edit,Write,Bash,Read /sprint-until 06:00

# Disable verbose output
VERBOSE_FLAG="" /sprint-until 06:00

---

Common Workflows

Polish Before Release

# 2-hour sprint focused on quality
/sprint-until $(date -d "+2 hours" +%H:%M) --focus "tests,type-safety,performance"

Fix Failing Tests

# Run until all tests pass
/sprint-until 18:00 --focus "failing-tests"

Coverage Push

# Improve test coverage
/sprint-until 20:00 --focus "coverage"

Security Hardening

# Audit and fix security issues
/sprint-until 23:59 --focus "security"

---

Architecture & Design

See SKILL.md for detailed:

• Step-by-step execution flow
• Focus area priority reference
• Rollback procedures
• Sprint state schema

For automation opportunities and future enhancements, see AUTOMATION_ANALYSIS.md.

---

Development & Testing

Run Tests

bash tests/test.sh  # (if present)

Modify Iteration Prompt

Edit references/iteration-prompt.md and restart the skill.

Contribute

1. Fork quantsquirrel/claude-sprint-until
2. Create feature branch
3. Test thoroughly
4. Open PR

---

License

MIT. See LICENSE file.

---

FAQ

Q: Will this break my project? A: No. Each iteration includes verification steps (tests, type checks) before commit. If something fails, it's logged and the loop moves on.

Q: How much will this cost? A: Each iteration costs ~$0.50 USD. A 10-iteration sprint = ~$5. Use --max-iterations to control budget.

Q: Can I run multiple sprints in parallel? A: Not on the same project (lock prevents it). For different projects, each gets its own .sprint/ directory.

Q: What if the deadline passes during an iteration? A: The loop checks before each iteration. If deadline has passed, it exits gracefully.

Q: Can I resume a paused sprint? A: Yes, if the .sprint/ directory exists, the script resumes from the last completed iteration.

---

Support

• Issues: GitHub Issues
• Documentation: SKILL.md, AUTOMATION_ANALYSIS.md
• Inspiration: snarktank/ralph, Q00/ouroboros, claude-code-guide

---

Changelog

v1.0.0 (2026-03-05)

• Initial release
• External bash loop for unlimited iterations
• Multi-focus area support
• Git integration with per-iteration tags
• Real-time progress tracking
• Stagnation detection