From 2f0e7772a7098b9600a4f1f553305dd06beaaeff Mon Sep 17 00:00:00 2001 From: Fatih Al-Aziz Date: Sun, 2 Aug 2026 17:15:09 +0700 Subject: [PATCH] docs: document role-backed task agents --- docs/task-agent-discovery.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/task-agent-discovery.md b/docs/task-agent-discovery.md index ea8392bbc..9df255195 100644 --- a/docs/task-agent-discovery.md +++ b/docs/task-agent-discovery.md @@ -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.` 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