Baldrick Run Skill

Execute autonomous iterations on feature specifications until all are complete.

The Job

Each iteration:

Read ## Codebase Patterns at top of progress.txt FIRST
Read baldrick-learnings.md for additional patterns
Find ## SELECTED SPEC in context (the loop has already selected it by priority → risk → created → id)
Implement that single spec
Run build, test, lint commands
Update spec to passes: true
Append progress with learnings
Add reusable patterns to progress.txt and baldrick-learnings.md
Commit changes

Priority Order

Specs are selected deterministically in this order:

Priority: high > medium > low
Risk: spike > integration > standard > polish
Created: older first (from created: frontmatter)
Id: A→Z (tiebreaker)

This ensures critical work first, unknowns (spikes) early, polish last.

Progress Format

After completing each spec, append to progress.txt:

## 2025-01-08 14:30 - feature-name
Session: baldrick-20250108143000-12345
- What was done: Implemented X, added Y, fixed Z
- Test output: (paste actual output)
- Learnings: (patterns discovered, gotchas encountered)
- Next: Related work or follow-ups

Pattern Consolidation

If you discover a REUSABLE pattern during implementation:

Add to ## Codebase Patterns at TOP of progress.txt
Add to baldrick-learnings.md for permanent storage

Good patterns:

"Migrations: always use IF NOT EXISTS"
"API responses: wrap in { data, error } shape"
"Tests: mock database with jest.mock"

Do NOT add:

Story-specific implementation details
Temporary debugging notes

Completion Signals

Per-spec completion:

Update YAML frontmatter: passes: true
Commit changes

All specs complete:

Run final verification
Create done marker: touch .baldrick-done
Output: <promise>COMPLETE</promise>

Quality Requirements

Every iteration must:

Pass typecheck
Pass tests
Pass lint
Keep commits focused and minimal
Follow existing code patterns

Do NOT commit broken code.

Commands

# Run 10 iterations (default)
./baldrick run

# Run specific number of iterations
./baldrick run 20

# Preview without executing
./baldrick run 5 --dry-run

# Stream Claude output (or use stream-json + jq)
./baldrick run 10 --verbose
./baldrick run 10 --stream-json   # requires jq

# Work on single spec until done
./baldrick once login-feature
./baldrick once login-feature --max 15
./baldrick once login-feature --max 15 --verbose

Reviewer Mode

Every 5th iteration, switch from Worker to Reviewer:

Check progress.txt - are we on track?
Verify completed specs actually work
Run tests to confirm
Fix issues before continuing
If stuck 2+ iterations, try different approach

This prevents broken code from compounding.

Alternative Loops (Skills)

Beyond feature specs, use these skills for goal-oriented loops:

coverage-loop - Increase test coverage to target %
lint-loop - Fix all linting errors
entropy-loop - Reduce code smells and duplication

Load the skill and describe your goal. The skill iterates until complete.

Session Tracking

Each run is tracked with:

Session ID: baldrick-YYYYMMDDHHMMSS-PID
Log file: logs/baldrick-YYYYMMDD-HHMMSS.log
Last session: .last-session file

When switching branches or features, previous sessions are automatically archived.

Stuck Detection

If the same spec fails twice without changes:

Warning is added to prompt
Claude advised to try different approach
Consider breaking spec into smaller pieces

Archive on Session Change

When you switch git branches or start a new feature:

Previous specs, progress, and logs are archived
Archive saved to archive/YYYY-MM-DD-feature-name/
Fresh progress.txt created for new session

This prevents mixing work across features.

baldrick-run