Run

# /run Command

## Purpose

Autonomous execution of sprint implementation with cycle loop until review and audit pass.

## Usage

/run [options] /run sprint-1 /run sprint-1 --max-cycles 10 --timeout 4 /run sprint-1 --branch feature/my-branch /run sprint-1 --dry-run /run sprint-1 --local /run sprint-1 --confirm-push

## Arguments

| Argument | Description | Required |
|----------|-------------|----------|
| `target` | Sprint to implement (e.g., `sprint-1`) | Yes |

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--max-cycles N` | Maximum iteration cycles | 20 |
| `--timeout H` | Maximum runtime in hours | 8 |
| `--branch NAME` | Feature branch name | `feature/<target>` |
| `--dry-run` | Validate but don't execute | false |
| `--reset-ice` | Reset circuit breaker before starting | false |
| `--local` | Keep all changes local (no push, no PR) | false |
| `--confirm-push` | Prompt before pushing to remote | false |

## Pre-flight Checks (Jack-In)

Before execution begins, validate:

1. **Configuration Check**
   ```bash
   # Check if run_mode.enabled is true in .loa.config.yaml
   if ! yq '.run_mode.enabled // false' .loa.config.yaml | grep -q true; then
     echo "ERROR: Run Mode not enabled. Set run_mode.enabled: true in .loa.config.yaml"
     exit 1
   fi

2. Beads-First Check (v1.29.0)

   # Autonomous mode REQUIRES beads by default
   health=$(.claude/scripts/beads/beads-health.sh --quick --json)
   status=$(echo "$health" | jq -r '.status')
   
   if [[ "$status" != "HEALTHY" && "$status" != "DEGRADED" ]]; then
     # Check for override
     beads_required=$(yq '.beads.autonomous.requires_beads // true' .loa.config.yaml)
     if [[ "$beads_required" == "true" ]]; then
       echo "HALT: Autonomous mode requires beads (status: $status)"
       echo ""
       echo "Beads provides:"
       echo "  - Task state persistence across context windows"
       echo "  - Progress tracking for overnight/unattended execution"
       echo "  - Recovery from interruptions"
       echo ""
       echo "To fix:"
       echo "  cargo install beads_rust && br init"
       echo ""
       echo "To override (not recommended):"
       echo "  Set beads.autonomous.requires_beads: false in .loa.config.yaml"
       echo "  Or: export LOA_BEADS_AUTONOMOUS_OVERRIDE=true"
       exit 1
     fi
   fi
   
   # Update health state
   .claude/scripts/beads/update-beads-state.sh --health "$status"
   

3. Branch Safety Check

   # Verify not on protected branch using ICE
   .claude/scripts/run-mode-ice.sh validate
   

4. Permission Check

   # Verify all required permissions configured
   .claude/scripts/check-permissions.sh --quiet
   

5. State Check

   # Check for conflicting .run/ state
   if [[ -f .run/state.json ]]; then
     current_state=$(jq -r '.state' .run/state.json)
     if [[ "$current_state" == "RUNNING" ]]; then
       echo "ERROR: Run already in progress. Use /run-halt or /run-resume"
       exit 1
     fi
   fi
   

Execution Flow

State Machine

READY → JACK_IN → RUNNING → COMPLETE/HALTED → JACKED_OUT

Main Loop

initialize_state()
while circuit_breaker.state == CLOSED:
  1. /implement $target
  2. commit_changes()
  3. track_deleted_files()
  4. update_state(phase: REVIEW)

  5. /review-sprint $target
  6. if has_findings(engineer-feedback.md):
       record_cycle(findings)
       check_circuit_breaker()
       continue  # Loop back to implement

  7. update_state(phase: AUDIT)
  8. /audit-sprint $target
  9. if has_findings(auditor-sprint-feedback.md):
       record_cycle(findings)
       check_circuit_breaker()
       continue  # Loop back to implement

  10. if COMPLETED marker exists:
        update_state(state: COMPLETE)
        break

create_draft_pr()
update_state(state: JACKED_OUT)

State Management

State File Structure

File: .run/state.json

{
  "run_id": "run-20260119-abc123",
  "target": "sprint-1",
  "branch": "feature/sprint-1",
  "state": "RUNNING",
  "phase": "IMPLEMENT",
  "timestamps": {
    "started": "2026-01-19T10:00:00Z",
    "last_activity": "2026-01-19T11:30:00Z"
  },
  "cycles": {
    "current": 3,
    "limit": 20,
    "history": [
      {"cycle": 1, "phase": "IMPLEMENT", "findings": 5, "files_changed": 10},
      {"cycle": 2, "phase": "REVIEW", "findings": 2, "files_changed": 3}
    ]
  },
  "metrics": {
    "files_changed": 15,
    "files_deleted": 2,
    "commits": 3,
    "findings_fixed": 7
  },
  "options": {
    "max_cycles": 20,
    "timeout_hours": 8,
    "dry_run": false,
    "local_mode": false,
    "confirm_push": false,
    "push_mode": "AUTO"
  },
  "completion": {
    "pushed": false,
    "pr_created": false,
    "pr_url": null,
    "skipped_reason": null
  }
}

Push Mode Options (v1.30.0)

Field	Type	Description
options.local_mode	boolean	True if --local flag was used
options.confirm_push	boolean	True if --confirm-push flag was used
options.push_mode	string	Resolved mode: LOCAL, PROMPT, or AUTO
completion.pushed	boolean	Whether commits were pushed to remote
completion.pr_created	boolean	Whether PR was created
completion.pr_url	string|null	PR URL if created, null otherwise
completion.skipped_reason	string|null	Why push was skipped (e.g., local_mode, user_declined)

Atomic State Updates

# Write to temp file first
state_update() {
  local temp_file=".run/state.json.tmp"
  local state_file=".run/state.json"

  # Update state with jq
  jq "$1" "$state_file" > "$temp_file"

  # Atomic rename
  mv "$temp_file" "$state_file"
}

Circuit Breaker

Circuit Breaker File

File: .run/circuit-breaker.json

{
  "state": "CLOSED",
  "triggers": {
    "same_issue": {
      "count": 0,
      "threshold": 3,
      "last_hash": null
    },
    "no_progr