opencode-multiagent 0.3.0-next.1 → 0.5.0

package/docs/agents.md

@@ -4,255 +4,157 @@
 
 # Agent Reference
 
-`opencode-multiagent` ships 20 bundled agents:
+`opencode-multiagent` ships 10 bundled agents:
 
-- 4 primary agents
-- 16 subagents
+- 3 primary agents
+- 7 subagents
 
-All bundled agents currently default to `temperature: 0`.
+Most bundled agents default to `temperature: 0`. The exception is `brainstormer` which uses `temperature: 0.3` for more creative exploration.
 
 ## System Shape
 
 The system is intentionally layered:
 
-- `lead` owns user-facing routing
-- `critic` challenges a route or inspects repo state
-- `planner` creates durable plans for larger work
-- `executor` turns a plan into bounded worker execution
+- `planner` owns user-facing triage, planning, challenge, and inspection
+- `executor` turns an approved plan into bounded subagent execution
 - specialized subagents handle coding, review, research, and documentation slices
 
 ## High-Level Hierarchy
 
 ```text
-user
-  -> lead
-       -> critic
-            -> devil
-            -> strategist
-       -> planner
-            -> strategist
-            -> auditor
-            -> devil
-            -> scribe / librarian / reviewer / scout
-       -> executor
-            -> quick / worker / heavy-worker / deep-worker
-            -> ui-worker / ui-heavy-worker
-            -> reviewer
-            -> validator
-            -> qa
-            -> advisor
-            -> scout
-            -> scribe
-            -> planner  (escalation after repeated QA failures)
-       -> librarian
-       -> scout
-       -> scribe
+brainstormer (pre-planning exploration + idea refinement)
+├── scout (research)
+└── auditor (stress-test ideas)
+
+planner (triage + planning + inspection)
+├── executor (execution coordination)
+│   ├── coder (standard coding) -> reviewer, scout
+│   ├── ui-coder (UI/UX coding) -> reviewer, scout
+│   ├── sec-coder (security coding) -> reviewer, scout
+│   ├── reviewer (quality gate)
+│   ├── scout (research)
+│   └── docmaster (.magent + docs + GitHub)
+├── auditor (plan gap finder)
+├── scout (research)
+├── reviewer (evidence)
+└── docmaster (plan persistence)
 ```
 
 ## Primary Agents
 
-### `lead`
+### `brainstormer`
 
 - Mode: `primary`
 - Default model: `anthropic/claude-opus-4-6`
-- Steps: `500`
-- Purpose: single user-facing entry point that owns the full request lifecycle
-- Best for: deciding the lightest safe route, delegating work, integrating results, and responding to the user
-
-### `critic`
-
-- Mode: `primary`
-- Default model: `openai/gpt-5.4`
+- Temperature: `0.3`
 - Steps: `200`
-- Purpose: challenge agent and inspection agent
-- Best for: pressure-testing a route before work starts, or inspecting repo memory and plugin state without implementing changes
+- Purpose: pre-planning exploration and idea refinement
+- Best for: exploring ideas with the user before planning begins, surfacing gaps and alternatives, challenging assumptions, and producing a planner-ready brief when the discussion concludes
 
 ### `planner`
 
 - Mode: `primary`
 - Default model: `anthropic/claude-opus-4-6`
-- Steps: `100`
-- Purpose: writes durable, execution-ready plans without implementing code
-- Best for: larger, cross-cutting, risky, or multi-phase work that needs a stable plan in `.magent/plans/`
+- Steps: `200`
+- Purpose: triage, planning, challenge, and inspection
+- Best for: deciding the lightest safe route, writing durable execution plans, challenging assumptions, inspecting repository state without implementing changes, and integrating results for the user
 
 ### `executor`
 
 - Mode: `primary`
 - Default model: `anthropic/claude-sonnet-4-6`
 - Steps: `200`
-- Purpose: runs the approved plan by dispatching bounded worker tasks and enforcing validation tiers
-- Best for: orchestrating implementation, task board updates, reviewer passes, validator runs, and QA gates
+- Purpose: execution orchestration
+- Best for: running an approved plan by dispatching bounded coding tasks, coordinating reviewer and scout passes, and enforcing quality gates
 
-## Coding Workers
-
-### `quick`
-
-- Mode: `subagent`
-- Default model: `opencode-go/minimax-m2.5`
-- Steps: `16`
-- Purpose: very fast worker for tiny, explicit, low-risk edits
-- Use when: the task is literal, local, and clearly bounded
+## Coding Agents
 
-### `worker`
+### `coder`
 
 - Mode: `subagent`
-- Default model: `openai/gpt-5.3-codex`
-- Steps: `30`
-- Purpose: standard worker for normal bounded implementation work
-- Use when: you need the default coding path for non-UI work without the highest risk level
-
-### `heavy-worker`
-
-- Mode: `subagent`
-- Default model: `openai/gpt-5.4`
+- Default model: `anthropic/claude-sonnet-4-6`
 - Steps: `40`
-- Purpose: heavy coding worker for risky, cross-cutting, or security-sensitive implementation
-- Use when: the change touches multiple modules, high-risk runtime behavior, or sensitive logic
+- Purpose: standard coding work
+- Use when: the task is a bounded, non-UI, non-security-sensitive implementation slice
 
-### `deep-worker`
+### `ui-coder`
 
 - Mode: `subagent`
-- Default model: `anthropic/claude-opus-4-6`
-- Steps: `60`
-- Purpose: long-horizon single-owner worker for ambiguous or reasoning-heavy coding tasks
-- Use when: a task needs more local analysis, flow tracing, or careful multi-step implementation inside one bounded slice
-
-### `ui-worker`
-
-- Mode: `subagent`
-- Default model: `anthropic/claude-opus-4-6`
-- Steps: `30`
-- Purpose: normal-complexity UI and UX worker
+- Default model: `anthropic/claude-sonnet-4-6`
+- Steps: `40`
+- Purpose: UI and UX work
 - Use when: the work is mainly components, view-local state, layout, accessibility, or responsive behavior
 
-### `ui-heavy-worker`
+### `sec-coder`
 
 - Mode: `subagent`
 - Default model: `anthropic/claude-opus-4-6`
-- Steps: `40`
-- Purpose: heavy UI and UX worker for broad or stateful interface changes
-- Use when: the work spans multiple screens, complex flows, or coordinated interaction behavior
+- Steps: `60`
+- Purpose: security-sensitive work
+- Use when: the change touches authentication, authorization, cryptography, secrets handling, or other high-risk runtime behavior
 
-## Quality and Review Agents
+## Quality Agents
 
 ### `reviewer`
 
 - Mode: `subagent`
-- Default model: `github-copilot/grok-code-fast-1`
-- Steps: `24`
-- Purpose: read-only local code reviewer for small bounded slices
-- Best for: reviewing 1-3 files or a focused diff slice before implementation is reported as done
-
-### `validator`
-
-- Mode: `subagent`
-- Default model: `openai/gpt-5.3-codex`
-- Steps: `24`
-- Purpose: bounded verification worker that runs the smallest meaningful commands
-- Best for: tests, builds, lint, and type checks that provide runtime evidence for a claimed change
-
-### `qa`
-
-- Mode: `subagent`
-- Default model: `openai/gpt-5.4`
-- Steps: `24`
-- Purpose: read-only quality gate that returns a final acceptance decision
-- Best for: higher-risk work where the system needs an explicit OKAY or REJECT verdict after validation
+- Default model: `anthropic/claude-sonnet-4-6`
+- Steps: `30`
+- Purpose: code review, QA, and validation
+- Best for: reviewing code changes, running build and test evidence, and issuing an acceptance verdict before work is reported as done
 
 ### `auditor`
 
 - Mode: `subagent`
-- Default model: `openai/gpt-5.4`
-- Steps: `24`
-- Purpose: aggressive read-only plan auditor
+- Default model: `anthropic/claude-opus-4-6`
+- Steps: `40`
+- Purpose: stubborn plan gap finder
 - Best for: finding missing steps, weak acceptance criteria, sequencing failures, and verification gaps before execution starts
 
-### `devil`
-
-- Mode: `subagent`
-- Default model: `anthropic/claude-sonnet-4-6`
-- Steps: `8`
-- Purpose: pure devil's-advocate reasoning agent with no tools
-- Best for: attacking assumptions, pointing out blind spots, and generating counter-arguments quickly
-
-## Research and Advisory Agents
+## Research Agent
 
 ### `scout`
 
 - Mode: `subagent`
 - Default model: `anthropic/claude-sonnet-4-6`
-- Steps: `24`
-- Purpose: fast read-only repository mapper
-- Best for: file discovery, symbol tracing, codebase structure questions, and git-aware local exploration
-
-### `librarian`
-
-- Mode: `subagent`
-- Default model: `anthropic/claude-sonnet-4-6`
-- Steps: `24`
-- Purpose: external research and documentation agent
-- Best for: live documentation lookup, external comparisons, API research, and evidence gathering outside the repo
-
-### `advisor`
-
-- Mode: `subagent`
-- Default model: `openai/gpt-5.4`
-- Steps: `20`
-- Purpose: read-only coding advisor for blocked or low-confidence implementation work
-- Best for: unblocking a worker, choosing between local implementation paths, or clarifying a risky decision without editing code
-
-### `strategist`
-
-- Mode: `subagent`
-- Default model: `anthropic/claude-opus-4-6`
-- Steps: `20`
-- Purpose: judgment-first plan and architecture advisor
-- Best for: validating direction, comparing approaches, surfacing architectural risks, and deciding whether a plan should proceed or change
+- Steps: `30`
+- Purpose: file discovery and external research
+- Best for: repository mapping, symbol tracing, codebase structure questions, git-aware local exploration, and live documentation or API lookup
 
 ## Documentation Agent
 
-### `scribe`
+### `docmaster`
 
 - Mode: `subagent`
 - Default model: `anthropic/claude-sonnet-4-6`
 - Steps: `30`
 - Purpose: documentation writer and `.magent` artifact manager
-- Best for: writing or updating `README.md`, `AGENTS.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `docs/**`, and `.magent/**` artifacts
+- Best for: writing or updating `README.md`, `AGENTS.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `docs/**`, `.magent/**` artifacts, and GitHub workflow files
 
 ## Agent Categories at a Glance
 
-| Category              | Agents                                                                           |
-| --------------------- | -------------------------------------------------------------------------------- |
-| Primary orchestration | `lead`, `critic`, `planner`, `executor`                                          |
-| Coding workers        | `quick`, `worker`, `heavy-worker`, `deep-worker`, `ui-worker`, `ui-heavy-worker` |
-| Quality and review    | `reviewer`, `validator`, `qa`, `auditor`, `devil`                                |
-| Research and advisory | `scout`, `librarian`, `advisor`, `strategist`                                    |
-| Documentation         | `scribe`                                                                         |
+| Category              | Agents                                     |
+| --------------------- | ------------------------------------------ |
+| Primary orchestration | `brainstormer`, `planner`, `executor`      |
+| Coding                | `coder`, `ui-coder`, `sec-coder`  |
+| Quality               | `reviewer`, `auditor`             |
+| Research              | `scout`                           |
+| Documentation         | `docmaster`                       |
 
 ## Summary Table
 
-| Agent             | Category      | Mode       | Model                             | Steps | Primary use                                 |
-| ----------------- | ------------- | ---------- | --------------------------------- | ----- | ------------------------------------------- |
-| `lead`            | Primary       | `primary`  | `anthropic/claude-opus-4-6`       | `500` | User-facing routing and lifecycle ownership |
-| `critic`          | Primary       | `primary`  | `openai/gpt-5.4`                  | `200` | Challenge and inspection                    |
-| `planner`         | Primary       | `primary`  | `anthropic/claude-opus-4-6`       | `100` | Durable plan authoring                      |
-| `executor`        | Primary       | `primary`  | `anthropic/claude-sonnet-4-6`     | `200` | Execution orchestration and validation      |
-| `quick`           | Coding        | `subagent` | `opencode-go/minimax-m2.5`        | `16`  | Tiny explicit edits                         |
-| `worker`          | Coding        | `subagent` | `openai/gpt-5.3-codex`            | `30`  | Default bounded coding work                 |
-| `heavy-worker`    | Coding        | `subagent` | `openai/gpt-5.4`                  | `40`  | Risky cross-cutting implementation          |
-| `deep-worker`     | Coding        | `subagent` | `anthropic/claude-opus-4-6`       | `60`  | Reasoning-heavy single-owner coding         |
-| `ui-worker`       | Coding        | `subagent` | `anthropic/claude-opus-4-6`       | `30`  | Standard UI and UX work                     |
-| `ui-heavy-worker` | Coding        | `subagent` | `anthropic/claude-opus-4-6`       | `40`  | Broad UI flows and advanced state           |
-| `reviewer`        | Quality       | `subagent` | `github-copilot/grok-code-fast-1` | `24`  | Read-only code review                       |
-| `validator`       | Quality       | `subagent` | `openai/gpt-5.3-codex`            | `24`  | Verification command execution              |
-| `qa`              | Quality       | `subagent` | `openai/gpt-5.4`                  | `24`  | Final quality gate                          |
-| `auditor`         | Quality       | `subagent` | `openai/gpt-5.4`                  | `24`  | Plan auditing                               |
-| `devil`           | Quality       | `subagent` | `anthropic/claude-sonnet-4-6`     | `8`   | Counter-arguments and blind spots           |
-| `scout`           | Research      | `subagent` | `anthropic/claude-sonnet-4-6`     | `24`  | Local repo exploration                      |
-| `librarian`       | Research      | `subagent` | `anthropic/claude-sonnet-4-6`     | `24`  | External research                           |
-| `advisor`         | Advisory      | `subagent` | `openai/gpt-5.4`                  | `20`  | Local implementation advice                 |
-| `strategist`      | Advisory      | `subagent` | `anthropic/claude-opus-4-6`       | `20`  | Architecture and direction advice           |
-| `scribe`          | Documentation | `subagent` | `anthropic/claude-sonnet-4-6`     | `30`  | Docs and `.magent` writing                  |
+| Agent          | Category      | Mode       | Model                         | Steps | Primary use                              |
+| -------------- | ------------- | ---------- | ----------------------------- | ----- | ---------------------------------------- |
+| `brainstormer` | Primary       | `primary`  | `anthropic/claude-opus-4-6`   | `200` | Pre-planning exploration and ideation    |
+| `planner`      | Primary       | `primary`  | `anthropic/claude-opus-4-6`   | `200` | Triage, planning, challenge, inspection  |
+| `executor`     | Primary       | `primary`  | `anthropic/claude-sonnet-4-6` | `200` | Execution orchestration                  |
+| `coder`        | Coding        | `subagent` | `anthropic/claude-sonnet-4-6` | `40`  | Standard bounded coding work             |
+| `ui-coder`     | Coding        | `subagent` | `anthropic/claude-sonnet-4-6` | `40`  | UI and UX work                           |
+| `sec-coder`    | Coding        | `subagent` | `anthropic/claude-opus-4-6`   | `60`  | Security-sensitive implementation        |
+| `reviewer`     | Quality       | `subagent` | `anthropic/claude-sonnet-4-6` | `30`  | Code review, QA, and validation          |
+| `auditor`      | Quality       | `subagent` | `anthropic/claude-opus-4-6`   | `40`  | Plan gap finding before execution        |
+| `scout`        | Research      | `subagent` | `anthropic/claude-sonnet-4-6` | `30`  | File discovery and external research     |
+| `docmaster`    | Documentation | `subagent` | `anthropic/claude-sonnet-4-6` | `30`  | Docs and `.magent` writing               |
 
 ## Related Docs