run

# Devloop Run

Execute plan tasks autonomously. **Do the work directly.**

**Bash hygiene**: prefer quiet flags to minimize output (`npm install --silent`, `git status -sb`, pipe long output through `| tail -n 20`).

**Monitor for long commands**: Use Monitor (not Bash) for test suites, builds, and full-codebase linting to stream output in real-time. Use Bash for all short commands (git ops, ls, devloop scripts).

Long-running commands that warrant Monitor:
- Test suites: `npm test`, `pytest`, `go test ./...`, `cargo test`, `make test`, `jest`, `vitest`, `mocha`
- Builds: `npm run build`, `make`, `cargo build`, `go build`, `tsc`, `webpack`, `vite build`, `gradle`, `mvn`
- Full-codebase linting: `eslint .`, `ruff check .`, `pylint src/`, `golangci-lint run`

Monitor pattern (always include failure patterns in the filter):
```
Monitor({ description: "test run", command: "npm test 2>&1 | grep --line-buffered -E 'PASS|FAIL|Error|passed|failed'", timeout_ms: 300000, persistent: false })
```
Fallback: if Monitor errors or is unavailable, use Bash directly.

## Step 1: Check Plan State
Run `${CLAUDE_PLUGIN_ROOT}/scripts/check-plan-complete.sh .devloop/plan.md`.
- **No plan**: Show entry points (`/devloop:plan`) and STOP.
- **Complete**: **AskUserQuestion**: Ship it, Archive, or Review. STOP.
- **Pending**: Continue to Step 2.

## Step 2: Parse Arguments
- `--max-iterations N`: Default 50.
- `--interactive`: Prompt at each task.
- `--next-issue`: Jump to Step 2b (Issue-to-ship workflow).

## Step 2b: Next Issue Workflow
1. Check for incomplete plan (prompt to replace).
2. Fetch with `gh issue list`.
3. Prioritize: bug/critical > security > feat > oldest.
4. Select issue, create `.devloop/plan.md` with required frontmatter (title, issue, url, status).
5. Post-completion: Validate (tests/lint) and commit with `Closes #N`.

## Step 3: Resume State
If `.devloop/next-action.json` exists, load and resume.

## Step 4: Setup Execution
Unless `--interactive`, create `.claude/ralph-loop.local.md` with iteration limits and completion promise: `<promise>ALL PLAN TASKS COMPLETE</promise>`.
**Optional**: Sync plan to native tasks with `${CLAUDE_PLUGIN_ROOT}/scripts/sync-plan-to-tasks.sh`.

## Step 5: Execute Tasks
Read plan, find all `- [ ]` tasks.

### 5a. Detect Parallel Groups
Scan pending tasks for `[parallel:X]` markers. If multiple pending tasks share the same group letter, they can run concurrently.

### 5b. Model Selection Per Task
Parse the `[model:X]` annotation from each task line:
- **`[model:haiku]`**: Spawn Agent with `model: "haiku"` — use for simple/mechanical tasks
- **`[model:sonnet]`**: Spawn Agent with `model: "sonnet"` — use for complex reasoning tasks
- **No annotation**: Do the work inline — no agent spawn needed

### 5c. Execute (Parallel or Sequential)
**For parallel groups**: Spawn one Agent per task in the group simultaneously (multiple Agent calls in a single message). Each agent receives the task description, phase context, and relevant files.

**For sequential tasks** (no parallel marker, or all group members not yet pending): Process one at a time.

Agent spawn pattern:

> **Prompt caching**: Put STATIC content first (identical across spawns → cached), DYNAMIC content last (varies per task → not cached). This maximizes cache hits when multiple agents are spawned in the same session.

```yaml
Agent:
  model: "haiku"  # or "sonnet" per [model:X] annotation
  prompt: |
    Instructions: Implement the task below. Do NOT modify plan.md or commit.
    Phase: [phase name]
    [STATIC: any shared project conventions or plan-level context here]

    Task: [description]
    Context: [relevant files and conventions -- dynamic, task-specific]
```

### 5d. Update Progress
1. Mark task `[x]` in `plan.md`.
2. Update native task to `completed`.
3. Check overall completion.
- **All complete**: Output `<promise>ALL PLAN TASKS COMPLETE</promise>`.
- **Tasks remain**: Continue (Autonomous) or Prompt (Interactive).
- **Checkpoints**: If `auto_commit: true`, commit at phase boundaries.

## Step 7: Finalize
**AskUserQuestion**: Ship it, Archive, or Review.

---
**Now**: Check plan state and begin.