<!--
Long Horizon Dev
Part of the Bles Software agent skills repository:
https://www.bles-software.com/claude-skills

Install for Claude Code:
  mkdir -p ~/.claude/skills/long-horizon-dev
  mv long-horizon-dev.md ~/.claude/skills/long-horizon-dev/SKILL.md

Install for Codex:
  mkdir -p ~/.codex/skills/long-horizon-dev
  mv long-horizon-dev.md ~/.codex/skills/long-horizon-dev/SKILL.md

For Gemini CLI and other agents, drop the body of this file into the
project instruction file the agent already reads.
-->

---
name: long-horizon-dev
description: >
  Structured development workflow for ANY coding task (small or large).
  Triggers on: feature requests, bug fixes, refactoring, new projects,
  implementation tasks, "build", "implement", "fix", "create", "add feature".
  Creates a 4-file planning system (Prompt.md, Plan.md, Implement.md, Documentation.md)
  for durable project memory, then executes milestone-by-milestone with verification.
---

# Long Horizon Development Skill

You are a disciplined software engineer that follows a structured development workflow
for every task. This ensures coherence, traceability, and quality across tasks of any size.

## When This Skill Activates

This skill activates for ALL development tasks including:
- Feature implementation (any size)
- Bug fixes
- Refactoring
- New project creation
- System changes
- API development
- UI changes
- Infrastructure work

## The 4-File Planning System

Before writing any code, create these files in the project's working directory
under a `.dev/` folder (create it if it doesn't exist):

### 1. Prompt.md — The Specification

```markdown
# Task Specification

## Goal
[Clear, specific description of what needs to be built/fixed]

## Non-Goals
[What this task explicitly does NOT cover]

## Constraints
- [Performance requirements]
- [Compatibility requirements]
- [Style/convention requirements]

## Deliverables
- [ ] [Specific deliverable 1]
- [ ] [Specific deliverable 2]

## Done When
- [ ] [Acceptance criterion 1]
- [ ] [Acceptance criterion 2]
- [ ] All tests pass
- [ ] No lint errors
```

### 2. Plan.md — The Milestones

```markdown
# Execution Plan

## Milestone 1: [Name]
- **What**: [Specific changes]
- **Files**: [Files to create/modify]
- **Validation**: [Command to verify — test, lint, build, curl, etc.]
- **Done when**: [Exit criterion]

## Milestone 2: [Name]
...

## Architecture Notes
[Key design decisions and rationale]
```

**Rules for milestones:**
- Size each milestone for single-loop completion (15-60 min work)
- Every milestone has a validation command
- Stop-and-fix: repair failures before progressing to next milestone
- Small tasks (bug fix, simple feature) = 1-2 milestones
- Medium tasks = 3-5 milestones
- Large tasks = 5+ milestones

### 3. Implement.md — The Execution Runbook

```markdown
# Implementation Runbook

1. Read Plan.md — it is the source of truth
2. Execute milestones sequentially
3. After each milestone:
   - Run the validation command
   - If it fails: diagnose, fix, re-validate (do NOT skip)
   - If it passes: update Documentation.md, proceed to next
4. Keep diffs scoped — no scope creep
5. Update Documentation.md after each milestone
```

### 4. Documentation.md — The Audit Log

```markdown
# Development Log

## Status: [In Progress / Complete]
## Current Milestone: [N of M]

### Completed
- [x] Milestone 1: [Name] — [timestamp]
  - Changes: [summary]
  - Decisions: [any choices made and why]

### In Progress
- [ ] Milestone 2: [Name]
  - Status: [what's happening]

### Known Issues
- [Any issues discovered during implementation]

### How to Test
- [Commands to verify the work]
```

## Execution Loop

For EVERY milestone, follow this cycle:

```
1. PLAN    → Read the milestone spec
2. EDIT    → Make code changes
3. RUN     → Execute validation command
4. OBSERVE → Check output/logs
5. REPAIR  → Fix any failures (do NOT skip)
6. UPDATE  → Update Documentation.md
7. NEXT    → Move to next milestone
```

## Scaling Rules

### Small Tasks (< 30 min)
- Create lightweight versions of the 4 files (can be brief)
- 1-2 milestones
- Don't over-plan — execute quickly
- Still validate before declaring done

### Medium Tasks (30 min - 2 hours)
- Full 4-file system
- 3-5 milestones with proper validation
- Update docs after each milestone

### Large Tasks (2+ hours)
- Detailed 4-file system with architecture notes
- 5+ milestones, each independently verifiable
- Periodic self-check: "Am I still on spec?"
- Course correction if drifting

## Quality Gates

After ALL milestones complete:
1. Re-read Prompt.md — did we deliver everything?
2. Run full test suite
3. Run linter
4. Check for regressions
5. Update Documentation.md with final status
6. Clean up any temporary files

## Important

- The Plan is the source of truth, not your memory
- If the plan needs updating, update Plan.md explicitly
- Never skip validation — a green check now prevents hours of debugging later
- Small tasks get small plans, but they still get plans
- Document decisions so future-you (or the next agent) understands why