auto-run

Autonomous Orchestrator Loop: $ARGUMENTS

You are an autonomous orchestrator. You dispatch workers, handle their completions, reconcile results, and dispatch newly unblocked tasks — repeating until all work is done or limits are reached.

Workers run in isolated git worktrees via the Agent tool. Each worker gets its own filesystem — no conflicts possible.

Section 1: Argument Parsing

Arguments: $ARGUMENTS

Parse the following flags:

• --max-batches N — Stop after N dispatch rounds (default: unlimited)
• --max-hours H — Stop after H hours (default: unlimited)
• --max-concurrent N — Max parallel workers per batch (default: 3)
• --sequential — Execute tasks one at a time directly on the current branch (no worktrees, no PRs per task). Use for dependent/sequential tasks. Passes --sequential to /dispatch.
• --dry-run — Show what would be dispatched without acting
• --resume — Resume from checkpoint (skip orient)
• --skip-milestone-review — Skip the milestone review phase after tasks complete
• --milestone-review-iterations N — Max milestone review iterations (default: 5)
• --through <task-id> — Complete everything needed to finish this task, then stop
• --epic <epic-id> — Complete all tasks within this epic, then stop
• --only <id1> <id2> ... — Only dispatch these specific tasks (and their blockers)

Section 2: Initial Setup

Check for Checkpoint

Read checkpoint at docs/auto-run-checkpoint.json (resolve from main repo root via git worktree list | head -1 | awk '{print $1}').

If --resume AND checkpoint exists with status "running":

1. Read checkpoint state (including scope config)
2. Log resumption context: batch number, completed list, in-progress list, scope
3. Check if any previously in-progress tasks have since completed — look for session summaries:

   ls docs/session_summaries/<task-id>*.txt 2>/dev/null
   

4. If summaries found → reconcile them first: Call /reconcile-summary --yes via Skill tool
5. Skip orient, proceed to dispatch loop (Section 3)

If fresh start (no checkpoint or no --resume):

1. Run /orient via Skill tool
2. Resolve scope (see Section 2.1)
3. Write initial checkpoint

Write checkpoint JSON to docs/auto-run-checkpoint.json with:

• version: 2
• status: "running"
• start_time: current ISO8601 timestamp
• config: parsed flags (max_batches, max_hours, max_concurrent)
• scope: resolved scope (see 2.1)
• batch_number: 0
• tasks: { completed: [], failed: [], in_progress: [] }
• stats: { total_dispatched: 0, total_completed: 0, total_failed: 0, total_batches: 0 }

2.1 Resolve Scope

Determine which tasks are in-scope for this auto-run:

If --through <task-id>: Walk the dependency graph backward from <task-id> to find all transitive blockers. Call get_issue(id=<task-id>, includeRelations=true) and recursively resolve each blockedBy entry's own blockers.

Build a set of all task IDs that must complete for <task-id> to be unblocked and completable. Include <task-id> itself. Store as scope.task_ids in checkpoint. Set scope.mode to "through" and scope.target to <task-id>.

If --epic <project-name>: List all tasks in this project by calling list_issues(project=<project-name>).

Store all issue IDs as scope.task_ids. Set scope.mode to "epic" and scope.target to <project-name>.

If --only <id1> <id2> ...: Use exactly those task IDs. Also resolve their transitive blockers (tasks that must complete first) and include those in scope. Store as scope.task_ids. Set scope.mode to "only".

If no scope flags: scope.task_ids = null (all ready tasks are in scope). Set scope.mode to "all".

Log the resolved scope:

Auto-run scope: N tasks [list IDs]. Target: <task-id or epic-id or "all">

First Dispatch

1. Query ready tasks: call list_issues(state=Todo), then for each call get_issue(includeRelations=true) and filter to those with empty blockedBy arrays
2. Filter ready tasks to only those in scope.task_ids (if set; if null, use all)
3. If no in-scope ready tasks:
   • Check if target task is already closed → exit with completion report
   • Otherwise report "No ready tasks in scope" and exit
4. If ready tasks exist:
   • Calculate count = min(ready_count, max_concurrent)
   • If --sequential: Call /dispatch --sequential <specific-task-ids> --no-plan --yes via Skill tool. This dispatches tasks one at a time in foreground (no worktrees). The orchestrator blocks until each task completes.
   • If parallel (default): Call /dispatch <specific-task-ids> --count <count> --no-plan --yes via Skill tool, passing only in-scope task IDs
5. Update checkpoint: add dispatched tasks to in_progress, set batch_number: 1

Section 3: Main Loop

If --sequential: The loop is synchronous. Each /dispatch --sequential call blocks until all tasks in that batch complete. After completion, proceed directly to Step B (Reconcile) → Step B.5 (Pull) → Step D (Dispatch Next). No background notifications needed.

If parallel (default): The loop is driven by background agent completion notifications. When a worker finishes (you are notified of its completion), process the result:

Step A — Identify Completion

When notified of a worker's completion, extract the task ID from the worker's name or result. Check for session summary:

ls docs/session_summaries/<task-id>*.txt 2>/dev/null

Step B — Reconcile

If summary exists: Call /reconcile-summary <task-id> --yes via Skill tool.

After reconciliation, check if the completed task touched frontend files:

# Check the session summary for frontend file extensions
grep -E '\.(tsx|jsx|vue|svelte|html|css|scss)' docs/session_summaries/<task-id>*.txt 2>/dev/null

If frontend files were modified, note for milestone review:

Frontend changes detected in <task-id> — Playwright browser verification will run during milestone review.

If no summary (worker may have failed):

1. Check the worker's return value for error information
2. Mark as failed
3. If Linear MCP is available, create investigation task with quality gate:

   save_issue(
     title="Investigate: <task-id> failed",
     team=<team>,
     priority=1,
     project=<project>,
     labels=["Bug"],
     description="## Problem\n<what the worker was attempting and how it failed>\n\n## Approach\nInvestigate root cause: check worker logs, git state, and error output.\n\n## Acceptance Criteria\n- [ ] Root cause identified\n- [ ] Fix applied or follow-up task created\n\n## Target Files\n- <files the failed task was working on>"
   )
   

   After creation, run post-write validation: get_issue(id=<created-id>) — check for formatting artifacts and rewrite if needed.

Update checkpoint: move task from in_progress to completed (or failed).

Circuit breaker: If the same task ID appears in the checkpoint's failed list with attempts >= 2, skip it and log: "Task failed twice — flagged for human attention."

Step B.5 — Pull and Clean Up

After reconciliation, pull changes so subsequent dispatches see the latest code:

If --sequential: No worktree prune needed (no worktrees created). Workers already committed directly to this branch, so git pull may not be necessary — but run it to sync with any remote changes:

git pull origin $(git branch --show-current) --rebase 2>/dev/null || true

If parallel (default): Prune completed worktrees and pull the worker's merged changes:

git worktree prune
git pull origin $(git branch --show-current)

Step C — Check Limits

• If --max-batches reached → write checkpoint with status: "paused", report "Auto-run paused. N tasks remain.", exit.
• If --max-hours elapsed (compare current time to start_time in checkpoint) → same.

Step D — Dispatch Next Batch

1. Query ready tasks (same pattern as First Dispatch: list_issues + get_issue filter)
2. Filter to in-scope tasks only (if scope.task_ids is set in checkpoint)
3. Calculate available_slots = max_concurrent - current_in_progress_count

If in-scope ready tasks AND available_slots > 0:

• If --sequential: Call /dispatch --sequential <specific-task-ids> --no-plan --yes via Skill tool. This blocks until all tasks complete.
• If parallel (default): Call /dispatch <specific-task-ids> --no-plan --yes via Skill tool (pass only in-scope IDs, limited to available_slots)
• Increment batch_number in checkpoint
• Add dispatched tasks to in_progress in checkpoint

Completion checks:

• If --through target task is now closed → all done → go to Section 4 (Completion)
• If --epic and all epic children closed → all done → go to Section 4
• If no in-scope ready AND no in-progress → all done → go to Section 4
• If no in-scope ready BUT tasks still in-progress → wait for more completions (background agents will notify you when they finish; in --sequential mode this does not apply since dispatch blocks)

Step E — Context Self-Monitoring

After every 3 reconciliation cycles, assess context health. If you notice degradation (losing track of state, responses feeling truncated, difficulty recalling earlier context):

1. Write checkpoint with status: "running" (preserving all current state)
2. Log: "Context limit approaching. Exiting for wrapper restart."
3. Exit gracefully — the wrapper script (if running) will restart with --resume

Section 4: Completion

When no ready tasks AND no in-progress tasks (all work done):

1. Final reconciliation: Call /reconcile-summary --yes via Skill tool

Step 1.5: Milestone Review Phase

After reconciliation, run an iterative review-fix pass on accumulated branch changes:

1. If --skip-milestone-review was passed: skip, log "Milestone review skipped by flag"

2. Detect milestone branch:

   git branch -r --list 'origin/milestone/*' | sort -V | tail -1
   

3. If no milestone branch found: skip, log "No milestone branch found — skipping milestone review"

4. Update checkpoint: milestone_review.status: "in_progress"

5. Dispatch a review worker using Agent tool:

   • isolation: "worktree"
   • mode: "bypassPermissions"
   • Prompt: Check out the milestone branch, run /milestone-review --max-iterations <N> --base-branch main (use --milestone-review-iterations value or default 5)
   • The worker pushes fixes directly to the milestone branch (no separate PR — the milestone-to-main PR is the human review checkpoint)

6. Wait for worker completion

7. Read the worker's report/session summary

8. Update checkpoint: milestone_review.status: "completed" with stats from the worker's report

9. Write checkpoint with status: "completed" and final stats

10. Final report:

═══════════════════════════════════════════
AUTO-RUN COMPLETE
═══════════════════════════════════════════
Duration: <elapsed time>
Batches: <count>
Completed: <count> tasks
Failed: <count> tasks

MILESTONE REVIEW:
- Status: <completed|skipped|N/A>
- Iterations: <count>
- Findings fixed: <count>
- Findings deferred: <count> (needs human decision)

COMPLETED:
- <task-id>: <title>
- ...

FAILED:
- <task-id>: <title> — <reason>
- ...

REMAINING (if any):
- <task-id>: <title>
- ...

═══════════════════════════════════════════

4. If Linear MCP is available, call list_issues to show final board state.

Checkpoint Schema

File: docs/auto-run-checkpoint.json

{
  "version": 2,
  "status": "running|completed|paused|errored",
  "start_time": "ISO8601",
  "last_updated": "ISO8601",
  "config": {
    "max_batches": null,
    "max_hours": null,
    "max_concurrent": 3,
    "execution_mode": "parallel|sequential"
  },
  "scope": {
    "mode": "all|through|epic|only",
    "target": "INT-14",
    "task_ids": ["INT-12", "INT-13", "INT-14"]
  },
  "batch_number": 2,
  "session_count": 1,
  "tasks": {
    "completed": [{ "id": "INT-12", "title": "...", "completed_at": "...", "batch": 1 }],
    "failed": [{ "id": "INT-14", "title": "...", "reason": "...", "attempts": 1 }],
    "in_progress": [{ "id": "INT-13", "title": "...", "dispatched_at": "...", "batch": 2 }]
  },
  "stats": {
    "total_dispatched": 4,
    "total_completed": 1,
    "total_failed": 0,
    "total_batches": 2
  },
  "milestone_review": {
    "status": "pending|in_progress|completed|skipped",
    "iterations": 0,
    "findings_fixed": 0,
    "findings_deferred": 0
  }
}

Error Handling

• Failed tasks: If Linear MCP available, create investigation issues; otherwise log and continue
• Circuit breaker: Same task failing twice → skip and flag for human attention
• No task tracker: If Linear MCP is not available, exit with "No task tracker configured. Connect Linear MCP or use /dispatch manually."
• Checkpoint corruption: If checkpoint can't be parsed, start fresh (warn user)