docs: document role-backed task agents

2026-08-02 17:15:09 +07:00
parent 06343fef42
commit 2f0e7772a7
1 changed files with 34 additions and 0 deletions
@@ -37,6 +37,40 @@ Parsing comes from frontmatter via `parseAgentFields()` (`src/discovery/helpers.
 - `output` is passed through as opaque schema data
 - `read-summarize: false` (parsed as `readSummarize`) forces the subagent's `read` tool to return verbatim file content instead of structural summaries — `runSubprocess` applies it as a `read.summarize.enabled: false` override on the subagent's isolated settings (`src/task/executor.ts`). `scout` and `librarian` ship with it disabled. Defaults to enabled when the field is absent.
 - `prewalk: true` starts the subagent on its resolved model and hands off to the default prewalk target (the `smol` role) at its first edit/write, exactly like the session-level `--prewalk`; a string value (e.g. `prewalk: "@smol"` or `prewalk: "openai/gpt-5-mini"`) picks a custom target. The `task.agentPrewalk` settings record (agent name → `"on"` / `"off"` / pattern, toggled per agent from `/agents` with `P`) overrides the frontmatter. Resolution happens in `runSubprocess` (`src/task/executor.ts`); an unresolvable target or a target equal to the starting model skips the hand-off instead of failing the spawn.
+## Role-backed custom agents
+
+OMP discovers user agents from `~/.omp/agent/agents/*.md` and project agents from `.omp/agents/*.md`.
+
+Give the agent a role alias in frontmatter, then dispatch it by name. For model routing, task dispatch sets only `agent`; it does not set a worker model:
+
+`~/.omp/agent/agents/reviewer.md`:
+
+```md
+---
+name: reviewer
+description: Review a change for correctness.
+model: "@review"
+---
+Review the assigned change and report concrete findings.
+```
+
+Set the role mapping in `~/.omp/agent/config.yml`:
+
+```yaml
+modelRoles:
+  review: spark/minimax-m3:high
+```
+
+`@review` resolves through `modelRoles.review`. Each `modelRoles.<role>` value stores a concrete model selector and may append a thinking suffix such as `:high` (`src/config/model-resolver.ts`). Changing that mapping affects subsequent task resolutions without editing agent definitions.
+
+For a dispatch, set the agent name and task:
+
+```json
+{"tasks":[{"agent":"reviewer","task":"Review the current change and report concrete findings."}]}
+```
+
+`/model` changes the current or default session selection. It is not the worker-role configuration mechanism; edit `modelRoles` instead.
+

 ## Bundled agents