# Subagents & Chains

All agents are provided by [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) builtins.
No local agent files — we use the package's native prompts with intercom coordination via [`pi-intercom`](https://www.npmjs.com/package/pi-intercom).

## Built-in Agents

| Agent             | Purpose                         | Context | Notes                                                   |
| ----------------- | ------------------------------- | ------- | ------------------------------------------------------- |
| `scout`           | Fast codebase recon             | fresh   | **Overridden** with code-intel tools via settings.json  |
| `planner`         | Implementation planning         | fork    | Read-only, writes `plan.md`                             |
| `worker`          | Single-writer implementation    | fork    | Escalates unapproved decisions via `contact_supervisor` |
| `reviewer`        | Multi-type review               | fresh   | Handles diffs, plans, solutions, codebase health, PRs   |
| `context-builder` | Requirements-to-context handoff | fresh   | Writes `context.md` + `meta-prompt.md`                  |
| `researcher`      | Web research brief              | fresh   | Writes `research.md`                                    |
| `oracle`          | Decision-consistency advisory   | fork    | Checks inherited decisions for drift, no edits          |
| `delegate`        | Lightweight generic delegate    | fresh   | No fixed output                                         |

### Scout Override

`scout` is overridden in `settings.json` to use code-intel tools:

```json
{
  "subagents": {
    "agentOverrides": {
      "scout": {
        "tools": "read, inspect_code, find_symbol, search_config, lsp_navigation, ast_grep_search, bash, write, intercom"
      }
    }
  }
}
```

## Intercom Coordination

`pi-intercom` is installed so agents can use `contact_supervisor` to talk back to the parent:

- **`reason: "need_decision"`** — blocks the child, waits for parent reply
- **`reason: "progress_update"`** — non-blocking, fire-and-forget
- Parent replies via `intercom({ action: "reply", message: "..." })`

Without intercom, children are fire-and-forget. With it, blocked workers can ask for decisions mid-task.

## Usage

```bash
# Run a single agent
/run scout "explore the codebase"

# Chain agents sequentially
/chain scout -> planner -> worker

# Run agents in parallel
/parallel reviewer "correctness" -> reviewer "tests" -> reviewer "complexity"

# Review loop (worker → reviewer → fix worker, until clean)
/review-loop "implement feature X"

# Background work
/run worker[async] "implement the approved plan"
```

## Packaged Prompt Shortcuts

| Prompt                        | What it does                                           |
| ----------------------------- | ------------------------------------------------------ |
| `/parallel-review`            | Fresh-context reviewers with distinct angles           |
| `/review-loop`                | Worker → reviewers → fix worker, until clean or capped |
| `/parallel-research`          | `researcher` + `scout` for external + local context    |
| `/parallel-context-build`     | Parallel `context-builder` passes                      |
| `/parallel-handoff-plan`      | Research + context building → implementation handoff   |
| `/gather-context-and-clarify` | Scout/research → ask clarifying questions              |
| `/parallel-cleanup`           | Deslop + verbosity cleanup reviewers                   |

## System Prompt

`SYSTEM.md` defines the **Juergen** persona — a structured workflow that enforces reading docs → reading code → web search → asking questions → planning → user approval before any implementation. Think sysadmin rigor meets data science reproducibility.
