opencode-multiagent 0.2.1 → 0.4.0

package/dist/opencode-multiagent/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared types used across the opencode-multiagent plugin.
+ * Centralizes type definitions to avoid duplication and inconsistency.
+ */
+/** A generic record with unknown values — the safe default for untyped data. */
+export type GenericRecord = Record<string, unknown>;
+/**
+ * Minimal client interface for injecting prompts into sessions.
+ * Matches the subset of the SDK client used by supervision, quality, and hooks.
+ */
+export type PromptClient = {
+    session?: {
+        prompt?: (options: {
+            path: {
+                id: string;
+            };
+            body?: {
+                parts: Array<{
+                    type: string;
+                    text: string;
+                }>;
+                noReply?: boolean;
+            };
+        }) => Promise<unknown>;
+        /** Fallback prompt method — some SDK versions expose this instead of `prompt`. */
+        promptAsync?: (options: {
+            sessionID: string;
+            noReply?: boolean;
+            parts: Array<{
+                type: string;
+                text: string;
+            }>;
+        }) => Promise<unknown>;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/opencode-multiagent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/opencode-multiagent/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE;YACjB,IAAI,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAC;YACrB,IAAI,CAAC,EAAE;gBAAE,KAAK,EAAE,KAAK,CAAC;oBAAE,IAAI,EAAE,MAAM,CAAC;oBAAC,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAC,CAAC;gBAAC,OAAO,CAAC,EAAE,OAAO,CAAA;aAAE,CAAC;SAC5E,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QACvB,kFAAkF;QAClF,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE;YACtB,SAAS,EAAE,MAAM,CAAC;YAClB,OAAO,CAAC,EAAE,OAAO,CAAC;YAClB,KAAK,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SAC9C,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACxB,CAAC;CACH,CAAC"}

package/dist/opencode-multiagent/utils.d.ts

@@ -0,0 +1,9 @@
+export declare const compact: <T extends Record<string, unknown>>(value: T) => Partial<T>;
+export declare const clip: (value: unknown, size?: number) => string | undefined;
+export declare const text: (parts: unknown) => string;
+export declare const label: (value: unknown, keys?: string[]) => string | undefined;
+export declare const own: (value: unknown, key: string) => boolean;
+export declare const clone: <T>(value: T) => T;
+export declare const readJSON: <T>(path: string, fallback: T) => Promise<T>;
+export declare const merge: <T>(base: T, extra: unknown) => T;
+//# sourceMappingURL=utils.d.ts.map

package/dist/opencode-multiagent/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/opencode-multiagent/utils.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,KAAG,OAAO,CAAC,CAAC,CACmB,CAAC;AAEnG,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,EAAE,aAAU,KAAG,MAAM,GAAG,SAI1D,CAAC;AAIF,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,MAS9B,CAAC;AAET,eAAO,MAAM,KAAK,GAChB,OAAO,OAAO,EACd,eAA8C,KAC7C,MAAM,GAAG,SAQX,CAAC;AAEF,eAAO,MAAM,GAAG,GAAI,OAAO,OAAO,EAAE,KAAK,MAAM,KAAG,OACkB,CAAC;AAErE,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,CAGnC,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,MAAM,MAAM,EAAE,UAAU,CAAC,KAAG,OAAO,CAAC,CAAC,CAMtE,CAAC;AAEF,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,OAAO,KAAG,CAqBlD,CAAC"}

package/docs/agents.md

@@ -0,0 +1,148 @@
+> Language: **English** | [Turkish](agents.tr.md)
+>
+> Back: [README](../README.md)
+
+# Agent Reference
+
+`opencode-multiagent` ships 9 bundled agents:
+
+- 2 primary agents
+- 7 subagents
+
+All bundled agents currently default to `temperature: 0`.
+
+## System Shape
+
+The system is intentionally layered:
+
+- `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
+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
+
+### `planner`
+
+- Mode: `primary`
+- Default model: `anthropic/claude-opus-4-6`
+- 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: execution orchestration
+- Best for: running an approved plan by dispatching bounded coding tasks, coordinating reviewer and scout passes, and enforcing quality gates
+
+## Coding Agents
+
+### `coder`
+
+- Mode: `subagent`
+- Default model: `anthropic/claude-sonnet-4-6`
+- Steps: `40`
+- Purpose: standard coding work
+- Use when: the task is a bounded, non-UI, non-security-sensitive implementation slice
+
+### `ui-coder`
+
+- Mode: `subagent`
+- 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
+
+### `sec-coder`
+
+- Mode: `subagent`
+- Default model: `anthropic/claude-opus-4-6`
+- Steps: `60`
+- Purpose: security-sensitive work
+- Use when: the change touches authentication, authorization, cryptography, secrets handling, or other high-risk runtime behavior
+
+## Quality Agents
+
+### `reviewer`
+
+- Mode: `subagent`
+- 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: `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
+
+## Research Agent
+
+### `scout`
+
+- Mode: `subagent`
+- Default model: `anthropic/claude-sonnet-4-6`
+- 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
+
+### `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/**`, `.magent/**` artifacts, and GitHub workflow files
+
+## Agent Categories at a Glance
+
+| Category              | Agents                            |
+| --------------------- | --------------------------------- |
+| Primary orchestration | `planner`, `executor`             |
+| Coding                | `coder`, `ui-coder`, `sec-coder`  |
+| Quality               | `reviewer`, `auditor`             |
+| Research              | `scout`                           |
+| Documentation         | `docmaster`                       |
+
+## Summary Table
+
+| Agent       | Category      | Mode       | Model                         | Steps | Primary use                              |
+| ----------- | ------------- | ---------- | ----------------------------- | ----- | ---------------------------------------- |
+| `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
+
+- [Configuration Reference](configuration.md)
+- [Usage Guide](usage-guide.md)

package/docs/agents.tr.md

@@ -0,0 +1,149 @@
+> Dil: [English](agents.md) | **Türkçe**
+>
+> Geri: [README](../README.tr.md)
+
+# Ajan Referansı
+
+`opencode-multiagent`, 9 paketlenmiş ajan ile gelir:
+
+- 2 ana ajan
+- 7 alt ajan
+
+Paketlenmiş tüm ajanlar şu anda varsayılan olarak `temperature: 0` kullanır.
+
+## Sistem Yapısı
+
+Sistem katmanlı olacak şekilde tasarlanmıştır:
+
+- `planner` kullanıcıya dönük triage, planlama, challenge ve inspeksiyon işlemlerini yönetir
+- `executor` planı bounded uzman görevlerine dönüştürür ve yürütmeyi koordine eder
+- uzman alt ajanlar kodlama, review, araştırma ve dokümantasyon işlerini üstlenir
+
+## Yüksek Seviye Hiyerarşi
+
+```text
+kullanici
+  -> planner (triage + planlama + inspeksiyon)
+       -> executor (yürütme koordinasyonu)
+            -> coder (standart kodlama) -> reviewer, scout
+            -> ui-coder (UI/UX kodlama) -> reviewer, scout
+            -> sec-coder (güvenlik kodlama) -> reviewer, scout
+            -> reviewer (kalite kapısı)
+            -> scout (araştırma)
+            -> docmaster (.magent + doküman + GitHub)
+       -> auditor (plan açığı bulucu)
+       -> scout (araştırma)
+       -> reviewer (kanıt)
+       -> docmaster (plan kalıcılığı)
+```
+
+## Ana Ajanlar
+
+### `planner`
+
+- Mod: `primary`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `200`
+- Amaç: triage, planlama, challenge ve inspeksiyon
+- En uygun kullanım: route seçimi, iş delegasyonu, büyük işlerde kalıcı ve yürütmeye hazır plan üretmek, repo durumunu incelemek
+
+### `executor`
+
+- Mod: `primary`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `200`
+- Amaç: yürütme orkestrasyonu
+- En uygun kullanım: onaylanmış planı bounded uzman görevlerine bölüp doğrulama katmanları ile yürütmek, task board güncellemeleri
+
+## Kodlama Ajanları
+
+### `coder`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `40`
+- Amaç: standart kodlama
+- En uygun kullanım: UI dışı, orta zorlukta, varsayılan kodlama yolu gerektiğinde
+
+### `ui-coder`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `40`
+- Amaç: UI/UX
+- En uygun kullanım: iş daha çok component, view-local state, layout, accessibility veya responsive davranış ile ilgiliyse
+
+### `sec-coder`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `60`
+- Amaç: güvenlik hassas kodlama
+- En uygun kullanım: değişiklik hassas runtime davranışını, kimlik doğrulama veya güvenlik mantığını etkiliyorsa
+
+## Kalite Ajanları
+
+### `reviewer`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `30`
+- Amaç: kod inceleme, QA, doğrulama
+- En uygun kullanım: implementasyon tamamlandıktan sonra değişiklik yüzeyini incelemek, test/build/lint ile kanıt üretmek ve son kabul kararı vermek
+
+### `auditor`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `40`
+- Amaç: plan açığı bulucu
+- En uygun kullanım: iş yürütülmeden önce eksik adımları, zayıf kabul kriterlerini, sıralama sorunlarını ve verification boşluklarını yakalamak
+
+## Araştırma Ajanı
+
+### `scout`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `30`
+- Amaç: dosya keşfi, araştırma
+- En uygun kullanım: dosya bulma, sembol takibi, kod tabanı yapısını anlama ve yerel keşif
+
+## Dokümantasyon Ajanı
+
+### `docmaster`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `30`
+- Amaç: dokümantasyon, `.magent`, GitHub
+- En uygun kullanım: `README.md`, `AGENTS.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `docs/**` ve `.magent/**` güncellemeleri, GitHub işlemleri
+
+## Kategori Özeti
+
+| Kategori            | Ajanlar                              |
+| ------------------- | ------------------------------------ |
+| Ana orkestrasyon    | `planner`, `executor`                |
+| Kodlama ajanları    | `coder`, `ui-coder`, `sec-coder`     |
+| Kalite              | `reviewer`, `auditor`                |
+| Araştırma           | `scout`                              |
+| Dokümantasyon       | `docmaster`                          |
+
+## Özet Tablo
+
+| Agent       | Kategori      | Mod        | Model                         | Steps | Ana kullanım                                            |
+| ----------- | ------------- | ---------- | ----------------------------- | ----- | ------------------------------------------------------- |
+| `planner`   | Primary       | `primary`  | `anthropic/claude-opus-4-6`   | `200` | Triage, planlama, challenge, inspeksiyon                |
+| `executor`  | Primary       | `primary`  | `anthropic/claude-sonnet-4-6` | `200` | Yürütme orkestrasyonu                                   |
+| `coder`     | Coding        | `subagent` | `anthropic/claude-sonnet-4-6` | `40`  | Standart kodlama                                        |
+| `ui-coder`  | Coding        | `subagent` | `anthropic/claude-sonnet-4-6` | `40`  | UI/UX kodlama                                           |
+| `sec-coder` | Coding        | `subagent` | `anthropic/claude-opus-4-6`   | `60`  | Güvenlik hassas kodlama                                 |
+| `reviewer`  | Quality       | `subagent` | `anthropic/claude-sonnet-4-6` | `30`  | Kod inceleme, QA, doğrulama                             |
+| `auditor`   | Quality       | `subagent` | `anthropic/claude-opus-4-6`   | `40`  | Plan açığı bulma ve denetim                             |
+| `scout`     | Research      | `subagent` | `anthropic/claude-sonnet-4-6` | `30`  | Dosya keşfi ve araştırma                                |
+| `docmaster` | Documentation | `subagent` | `anthropic/claude-sonnet-4-6` | `30`  | Doküman, `.magent` yazımı ve GitHub                     |
+
+## İlgili Dokümanlar
+
+- [Konfigürasyon Referansı](configuration.tr.md)
+- [Kullanım Kılavuzu](usage-guide.tr.md)

package/docs/configuration.md

@@ -0,0 +1,244 @@
+> Language: **English** | [Turkish](configuration.tr.md)
+>
+> Back: [README](../README.md)
+
+# Configuration Reference
+
+This document explains the plugin's configuration surfaces, what each setting does, and how
+override precedence works.
+
+## Configuration Files
+
+The plugin uses three different configuration layers:
+
+1. Bundled defaults: `defaults/opencode-multiagent.json`
+2. User runtime overrides: `~/.config/opencode/plugins/opencode-multiagent.json`
+3. Host OpenCode config: `opencode.json`
+
+## Merge and Override Rules
+
+### Runtime settings
+
+At startup, the plugin loads bundled defaults and then reads the user override file at
+`~/.config/opencode/plugins/opencode-multiagent.json`.
+
+The user settings file currently supports these sections:
+
+- `flags`
+- `agentSettings`
+- `profiles`
+
+The effective runtime flags are resolved in this order:
+
+1. built-in `defaultFlags`
+2. selected profile from merged profiles
+3. user `flags`
+
+That means user `flags` always win over the selected profile, and the selected profile wins over
+the built-in baseline.
+
+### Agent settings
+
+`agentSettings` is applied during agent compilation and only fills `model`, `temperature`, and
+`steps` when those fields are not already explicitly set in the host config.
+
+Practical rule:
+
+- bundled agent markdown provides the default definition
+- `agentSettings` provides central default overrides
+- explicit `opencode.json -> agent.<name>.*` values win if you set them yourself
+
+### MCP defaults
+
+The bundled `mcpDefaults` section is injected conservatively. The plugin only adds an MCP server
+when the active OpenCode config does not already define a server with the same name.
+
+Practical rule:
+
+- bundled `mcpDefaults` fills gaps
+- explicit `opencode.json -> mcp.<name>` definitions always win
+
+## `flags`
+
+Top-level runtime flags:
+
+| Key                   | Default    | What it does                                                                         |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------ |
+| `profile`             | `standard` | Selects the base runtime profile before user flag overrides are applied.             |
+| `enforcement`         | `true`     | Enables local safety checks for sensitive file paths and destructive shell patterns. |
+| `observation`         | `true`     | Enables JSONL observation logging for events and tool execution traces.              |
+| `prompt_controls`     | `true`     | Adds prompt metadata headers and logs risky prompt or command content.               |
+| `agent_compilation`   | `true`     | Compiles bundled, global, and project agent markdown into the active config.         |
+| `command_compilation` | `true`     | Compiles bundled, global, and project command markdown into the active config.       |
+| `mcp_compilation`     | `true`     | Injects plugin-managed MCP server defaults into the active config when missing.      |
+| `telemetry`           | `true`     | Records session, tool, and error telemetry in the plugin log.                        |
+| `supervision`         | `true`     | Enables parent-child supervision reminders for idle delegated sessions.              |
+| `quality_gate`        | `true`     | Tracks edit activity and emits quality reminders for sessions that go idle.          |
+| `skill_injection`     | `false`    | Reserved. Loads the skill registry but does not inject content yet.                   |
+
+### `skill_sources`
+
+Default value:
+
+```json
+["${plugin_root}/skills", "${home}/.agents/skills", "${home}/skills"]
+```
+
+This is the ordered search path used when `skill_injection` is enabled.
+
+- `${plugin_root}` resolves to the installed package root
+- `${home}` resolves to the current user's home directory
+
+### `compiler.permission_compilation`
+
+| Key                               | Default | What it does                                                                                                                                   |
+| --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compiler.permission_compilation` | `true`  | Fills missing top-level OpenCode permission defaults conservatively for core tools such as `bash`, `read`, `edit`, `glob`, `grep`, and `list`. |
+
+### `experimental`
+
+These flags enable optional prompt and session transforms:
+
+| Key                                    | Default | What it does                                                           |
+| -------------------------------------- | ------- | ---------------------------------------------------------------------- |
+| `experimental.chat_system_transform`   | `false` | Appends an experimental note to the system prompt.                     |
+| `experimental.chat_messages_transform` | `false` | Appends an experimental note to the last user message before dispatch. |
+| `experimental.session_compacting`      | `false` | Adds experimental context to compaction summaries.                     |
+| `experimental.text_complete`           | `false` | Appends experimental text to completed LLM responses.                  |
+
+These are enabled by default only in the `strict` profile.
+
+### `supervision_config`
+
+| Key                                  | Default  | Meaning                                                                                         |
+| ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------- |
+| `supervision_config.idle_timeout_ms` | `180000` | How long a delegated child session can stay idle before supervision logic considers it overdue. |
+| `supervision_config.cooldown_ms`     | `300000` | Cooldown between supervision reminders.                                                         |
+
+### `quality_config`
+
+| Key                                   | Default  | Meaning                                                                              |
+| ------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| `quality_config.reminder_idle_ms`     | `120000` | How long an editing session can remain idle before a quality reminder is considered. |
+| `quality_config.reminder_cooldown_ms` | `300000` | Cooldown between quality reminders.                                                  |
+
+## `agentSettings`
+
+This section centralizes per-agent defaults for:
+
+- `model`
+- `temperature`
+- `steps`
+
+All bundled agents currently default to `temperature: 0`.
+
+| Agent       | Category      | Default model                 | Steps |
+| ----------- | ------------- | ----------------------------- | ----- |
+| `planner`   | Primary       | `anthropic/claude-opus-4-6`   | `200` |
+| `executor`  | Primary       | `anthropic/claude-sonnet-4-6` | `200` |
+| `coder`     | Coding        | `anthropic/claude-sonnet-4-6` | `40`  |
+| `ui-coder`  | Coding        | `anthropic/claude-sonnet-4-6` | `40`  |
+| `sec-coder` | Coding        | `anthropic/claude-opus-4-6`   | `60`  |
+| `reviewer`  | Quality       | `anthropic/claude-sonnet-4-6` | `30`  |
+| `auditor`   | Quality       | `anthropic/claude-opus-4-6`   | `40`  |
+| `scout`     | Research      | `anthropic/claude-sonnet-4-6` | `30`  |
+| `docmaster` | Documentation | `anthropic/claude-sonnet-4-6` | `30`  |
+
+## `mcpDefaults`
+
+These are plugin-owned MCP server definitions shipped with the package.
+
+| Server       | Type     | Enabled by default | Purpose                                                                         |
+| ------------ | -------- | ------------------ | ------------------------------------------------------------------------------- |
+| `code_index` | `local`  | `true`             | Indexed code search, file discovery, summaries, and symbol lookup.              |
+| `repo`       | `local`  | `true`             | Git status, diff, log, branch, and commit inspection tools.                     |
+| `context7`   | `remote` | `false`            | Live library and framework documentation lookup.                                |
+| `exa`        | `remote` | `false`            | Web search and code context retrieval.                                          |
+| `gh_grep`    | `remote` | `false`            | GitHub code search over public repositories.                                    |
+| `github`     | `local`  | `false`            | GitHub repository, issue, PR, and file operations. Requires `GITHUB_PAT_TOKEN`. |
+
+Notes:
+
+- `code_index` and `repo` are enabled in the bundled defaults because they support the local
+  development workflow directly.
+- `github` is disabled by default because it requires credentials.
+- `context7`, `exa`, and `gh_grep` are optional remote services and start disabled.
+
+## `profiles`
+
+The plugin ships three named profiles.
+
+| Profile    | Best for            | Observation and telemetry | Supervision and quality | Experimental transforms |
+| ---------- | ------------------- | ------------------------- | ----------------------- | ----------------------- |
+| `minimal`  | Lowest overhead     | Mostly off                | Mostly off              | Off                     |
+| `standard` | Default daily use   | On                        | On                      | Off                     |
+| `strict`   | Maximum guard rails | On                        | On                      | On                      |
+
+Profile details:
+
+- `minimal` keeps enforcement on, but reduces logging and reminder behavior.
+- `standard` is the default balance for normal use.
+- `strict` turns on all experimental transforms in addition to the normal runtime protections.
+
+## User Override Examples
+
+### Basic user runtime file
+
+Path: `~/.config/opencode/plugins/opencode-multiagent.json`
+
+```json
+{
+  "flags": {
+    "profile": "strict"
+  },
+  "agentSettings": {
+    "planner": {
+      "steps": 300
+    }
+  }
+}
+```
+
+### Custom profile example
+
+```json
+{
+  "profiles": {
+    "quiet": {
+      "observation": false,
+      "telemetry": false,
+      "supervision": false,
+      "quality_gate": false
+    }
+  },
+  "flags": {
+    "profile": "quiet"
+  }
+}
+```
+
+### Host-side MCP override in `opencode.json`
+
+Use the host config when you want to explicitly enable or replace an MCP server definition:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-multiagent"],
+  "mcp": {
+    "github": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+      "environment": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PAT_TOKEN}"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+## Related Docs
+
+- [Usage Guide](usage-guide.md)
+- [Agent Reference](agents.md)