# Subagent profiles — README

This directory contains **profile presets** for the built-in subagents
shipped by `pi-subagents` (scout, planner, worker, oracle, reviewer,
researcher, context-builder, delegate).

A profile is a saved snapshot of `settings.subagents`. Loading it
overwrites the relevant block in `~/.pi/agent/settings.json`. It does
**not** affect your custom `~/.pi/agent/agents/ollama-*.md` agents —
those have their `model:` set in their own frontmatter.

## Files

| File | Purpose |
|---|---|
| `ollama.quality.json` | Best answers. All built-ins on M3 / K2.6 / K2.7-code, `thinking: high`. Default for real work. |
| `ollama.quota.json`   | Save tokens. `scout`, `context-builder`, `researcher`, `delegate` use Gemini 3 Flash with `thinking: low/medium`. `worker` uses K2.7-code with `thinking: medium`. `planner` / `oracle` / `reviewer` stay on M3 / K2.6. |

## How to load a profile

```
/subagents-load-profile ollama.quality
```

You'll be asked whether to also switch the parent session's model to
the profile's worker model. Say yes for full effect.

To list all available profiles:

```
/subagents-profiles
```

To verify a profile is still valid (the proxy models haven't retired
out from under it):

```
/subagents-check-profile ollama.quality
```

## What profiles are NOT

Profiles are **not** automatic orchestration. Loading a profile does
not trigger any workflow. It only sets the model + thinking on the
8 built-in agents that the parent (or a chain) might later invoke.

If you want automatic orchestration, see:
- `~/.pi/agent/chains/feature-build.chain.md` — static 5-stage workflow
- `~/.pi/agent/chains/research-brief.chain.md` — static 2-stage workflow
- `~/.pi/agent/agents/ollama-orchestrator.md` — adaptive agent that
  decomposes a complex task and dispatches subagents at runtime

## The three layers (cheat sheet)

| Layer | Lives in | Orchestrates? | Affects custom `ollama-*` agents? |
|---|---|---|---|
| A single subagent | `~/.pi/agent/agents/*.md` | No — it's a worker | N/A |
| A profile | `~/.pi/agent/profiles/pi-subagents/*.json` | No — it's a config swap | No |
| A chain | `~/.pi/agent/chains/*.chain.md` | Yes — static, pre-defined stages | N/A |
| The parent Pi agent | The session you're in | Yes — adaptive, per-task | Yes (its own model + tools) |
| `ollama-orchestrator` | `~/.pi/agent/agents/ollama-orchestrator.md` | Yes — adaptive, has `subagent` tool | N/A |
| pi-crew `team` tool | The parent's tool belt | Yes — heavy, durable, worktree-aware | N/A |

## When to use which

| Situation | Reach for |
|---|---|
| One self-contained job one role can do | A single subagent (e.g. `/run ollama-coder "..."`) |
| You want to swap defaults on the built-ins for the current session | `/subagents-load-profile ollama.quality` (or `ollama.quota`) |
| Recurring multi-step job with fixed stages | `/run-chain feature-build "..."` (or `research-brief`) |
| Complex open-ended task that needs adaptive decomposition | Tell the parent "use ollama-orchestrator to handle this" |
| Long-running, multi-writer, durable-state job | `team` tool (pi-crew) — say "use pi-crew to ..." |