/nav-loop

name: nav-loop
description: Run tasks until complete with structured completion signals. Auto-invoke when user says "run until done", "keep going until complete", "iterate until finished", "loop mode", "autonomous mode".
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
version: 1.0.0

Navigator Loop Skill

Execute tasks iteratively until completion with structured signals, stagnation detection, and dual-condition exit gates.

Why This Exists

Traditional AI coding requires manual "keep going" prompts. Navigator Loop provides:

• **Structured completion signals** (NAVIGATOR_STATUS block)
• **Dual-condition exit gate** (heuristics + explicit signal)
• **Stagnation detection** (circuit breaker for stuck loops)
• **Progress visibility** (phases: INIT → RESEARCH → IMPL → VERIFY → COMPLETE)

Based on Ralph's autonomous loop innovations, adapted for Navigator's context-efficient architecture.

When to Invoke

**Auto-invoke when**:

• User says "run until done", "keep going until complete"
• User says "iterate until finished", "autonomous mode"
• User says "loop mode", "don't stop until done"
• Task document has `loop_mode: true`

**DO NOT invoke if**:

• Single-step task (no iteration needed)
• User says "just do this once"
• Already in loop mode (prevent nested loops)
• User explicitly disabled loop mode

Configuration

Loop mode settings in `.agent/.nav-config.json`:

{
  "loop_mode": {
    "enabled": false,
    "max_iterations": 5,
    "stagnation_threshold": 3,
    "exit_requires_explicit_signal": true,
    "show_status_block": true,
    "iteration_approval": "none",
    "periodic_interval": 3,
    "never_pause_on_stagnation": false,
    "stagnation_diversify_strategy": "combine"
  }
}

**Core options**:

• `enabled`: Default state for new tasks
• `max_iterations`: Hard cap to prevent infinite loops (1-20)
• `stagnation_threshold`: Same-state count before pause (2-5)
• `exit_requires_explicit_signal`: Require EXIT_SIGNAL alongside heuristics
• `show_status_block`: Render NAVIGATOR_STATUS each iteration

**Autonomous / overnight options** (v6.2.2+):

• `iteration_approval`: When to prompt the user for accept/reject between iterations.
• `"none"` (default) — never prompt; loop runs uninterrupted
• `"strict"` — prompt after every iteration
• `"periodic"` — prompt every N iterations (where N = `periodic_interval`, default 3)
• `periodic_interval`: When `iteration_approval == "periodic"`, the cadence of prompts. Default 3 (every 3rd iteration). Set higher for less frequent check-ins on long overnight runs (e.g., 5 or 10).
• `never_pause_on_stagnation`: If `true`, stagnation triggers **auto-diversification** instead of an `AskUserQuestion` pause. Required for true overnight runs. Inspired by karpathy/autoresearch's NEVER STOP directive.
• `stagnation_diversify_strategy`: Which recovery to attempt when `never_pause_on_stagnation` fires.
• `"combine"` — combine previous near-misses / partially-met indicators
• `"radical"` — try a substantially different approach (re-architect, swap library)
• `"reread"` — re-read the in-scope task/system docs for missed signals

**Safety guard**: Setting `never_pause_on_stagnation: true` REQUIRES `max_iterations` to be set explicitly (the default of 5 is fine; the point is — no infinite default). Without a max, an autonomous loop can spin forever on a fundamentally broken task.

Execution Steps

Step 1: Initialize Loop State

**Load configuration**:

python3 functions/phase_detector.py --init

**Initialize tracking variables**:

iteration = 1
max_iterations = config.loop_mode.max_iterations or 5
stagnation_threshold = config.loop_mode.stagnation_threshold or 3
hash_history = []
phase = "INIT"

**Display loop start**:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LOOP MODE ACTIVATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: {TASK_DESCRIPTION}
Max iterations: {max_iterations}
Stagnation threshold: {stagnation_threshold}

Starting iteration 1...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 2: Execute Iteration

**Perform task work** based on current phase:

| Phase | Actions | |-------|---------| | INIT | Load context, understand requirements | | RESEARCH | Explore codebase, find patterns | | IMPL | Write code, make changes | | VERIFY | Run tests, validate functionality, **simplify code** | | COMPLETE | All indicators met, ready to exit |

**Track changes during iteration**:

• Files read (for RESEARCH detection)
• Files changed (for IMPL detection)
• Tests run (for VERIFY detection)
• Commits made (for completion indicator)

Step 3: Generate Status Block

**After each iteration**, generate NAVIGATOR_STATUS:

python3 functions/status_generator.py \
  --phase "{phase}" \
  --iteration "{iteration}" \
  --max-iterations "{max_iterations}" \
  --indicators "{indicators_json}" \
  --state-hash "{current_hash}" \
  --prev-hash "{previous_hash}" \
  --stagnation-count "{stagnation_count}"

**Display status block**:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NAVIGATOR_STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase: {PHASE}
Iteration: {N}/{MAX}
Progress: {PERCENT}%

Completion Indicators:
  [{x or space}] Code changes committed
  [{x or space}] Tests passing
  [{x or space}] Code simplified
  [{x or space}] Documentation updated
  [{x or space}] Ticket closed
  [{x or space}] Marker created

Exit Conditions:
  Heuristics: {MET}/{TOTAL} (need 2+)
  EXIT_SIGNAL: {true/false}

State Hash: {HASH}
Previous Hash: {PREV_HASH}
Stagnation: {COUNT}/{THRESHOLD}

Next Action: {NEXT_ACTION}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 3.5: Per-Iteration Approval Gate (optional)

**Skip this step if** `config.loop_mode.iteration_approval == "none"` (default).

**Run this step if** the user wants oversight between iterations — for risky changes, learning the loop's behavior, or sanity-checki