go-loop

# Go Loop - Iterative Task Execution

**Current branch:** !`git branch --show-current 2>/dev/null || echo "not in git repo"`

The go loop executes PRD stories or generic tasks iteratively, with two distinct modes
for different levels of autonomy and oversight.

## When to Use Go Loop

- Implementing stories from a PRD (`/go plans/feature/prd.json`)
- Generic iterative tasks (`/go "Build CSV parser" --completion-promise "DONE"`)
- Autonomous overnight development (AFK mode)
- Learning/debugging new workflows (HITL mode with `--once`)

## State Management

**Single Source of Truth**: prd.json IS the state. The hook derives the current story as the
first story with `passes: false` (sorted by priority). Progress log is embedded in prd.json's
`log` array - no separate progress.txt file.

**What Claude Updates:**
- `passes: true` when story completes
- `completed_at` and `commit` fields (optional - hook can set)

**What Hook Updates:**
- Appends to prd.json's `log` array automatically

## Execution Modes

### HITL (Human-In-The-Loop)

Default mode. Hook-based continuation within a single Claude session.

**Characteristics:**
- Single Claude session throughout
- Stop hook blocks exit, injects next prompt
- Context accumulates (can cause "context rot" in long sessions)
- Best for: Learning, debugging, risky tasks, complex decisions

**Usage:**
```bash
/go plans/auth/prd.json              # Full HITL loop
/go plans/auth/prd.json --once       # Single iteration, then stop
```

### AFK (Away From Keyboard)

External bash loop. Each iteration is a fresh Claude session.

**Characteristics:**
- External bash for-loop controls iteration
- Fresh context per iteration (prevents context rot)
- State persists in prd.json only (single source of truth)
- Best for: Bulk work, overnight runs, well-defined tasks

**Usage:**
```bash
/go plans/auth/prd.json --afk                # External loop, 50 iterations
/go plans/auth/prd.json --afk --max 30       # Limit to 30 iterations
/go plans/auth