opencode-multiagent 0.2.0 → 0.3.0-next.1

package/docs/configuration.md

@@ -0,0 +1,255 @@
+> 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`    | Enables runtime skill registry lookup and skill availability injection.              |
+
+### `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 |
+| ----------------- | ------------- | --------------------------------- | ----- |
+| `lead`            | Primary       | `anthropic/claude-opus-4-6`       | `500` |
+| `critic`          | Primary       | `openai/gpt-5.4`                  | `200` |
+| `planner`         | Primary       | `anthropic/claude-opus-4-6`       | `100` |
+| `executor`        | Primary       | `anthropic/claude-sonnet-4-6`     | `200` |
+| `scout`           | Research      | `anthropic/claude-sonnet-4-6`     | `24`  |
+| `worker`          | Coding        | `openai/gpt-5.3-codex`            | `30`  |
+| `heavy-worker`    | Coding        | `openai/gpt-5.4`                  | `40`  |
+| `deep-worker`     | Coding        | `anthropic/claude-opus-4-6`       | `60`  |
+| `ui-worker`       | Coding        | `anthropic/claude-opus-4-6`       | `30`  |
+| `ui-heavy-worker` | Coding        | `anthropic/claude-opus-4-6`       | `40`  |
+| `quick`           | Coding        | `opencode-go/minimax-m2.5`        | `16`  |
+| `reviewer`        | Quality       | `github-copilot/grok-code-fast-1` | `24`  |
+| `validator`       | Quality       | `openai/gpt-5.3-codex`            | `24`  |
+| `qa`              | Quality       | `openai/gpt-5.4`                  | `24`  |
+| `advisor`         | Advisory      | `openai/gpt-5.4`                  | `20`  |
+| `auditor`         | Quality       | `openai/gpt-5.4`                  | `24`  |
+| `strategist`      | Advisory      | `anthropic/claude-opus-4-6`       | `20`  |
+| `devil`           | Quality       | `anthropic/claude-sonnet-4-6`     | `8`   |
+| `scribe`          | Documentation | `anthropic/claude-sonnet-4-6`     | `30`  |
+| `librarian`       | Research      | `anthropic/claude-sonnet-4-6`     | `24`  |
+
+## `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": {
+    "lead": {
+      "steps": 650
+    }
+  }
+}
+```
+
+### 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)

package/docs/configuration.tr.md

@@ -0,0 +1,255 @@
+> Dil: [English](configuration.md) | **Türkçe**
+>
+> Geri: [README](../README.tr.md)
+
+# Konfigürasyon Referansı
+
+Bu doküman, plugin'in konfigürasyon yüzeylerini, her ayarın ne yaptığını ve override sırasının
+nasıl çalıştığını açıklar.
+
+## Konfigürasyon Dosyaları
+
+Plugin üç farklı konfigürasyon katmanı kullanır:
+
+1. Paketle birlikte gelen varsayılanlar: `defaults/opencode-multiagent.json`
+2. Kullanıcı runtime override dosyası: `~/.config/opencode/plugins/opencode-multiagent.json`
+3. Host OpenCode konfigürasyonu: `opencode.json`
+
+## Merge ve Override Kuralları
+
+### Runtime ayarları
+
+Plugin başlarken önce paketlenmiş varsayılanları, sonra da
+`~/.config/opencode/plugins/opencode-multiagent.json` dosyasını okur.
+
+Kullanıcı ayar dosyası şu bölümleri destekler:
+
+- `flags`
+- `agentSettings`
+- `profiles`
+
+Efektif runtime flag'leri şu sırayla çözülür:
+
+1. dahili `defaultFlags`
+2. merge edilmiş profillerden seçilen profil
+3. kullanıcı `flags`
+
+Yani kullanıcı `flags` her zaman seçilen profilin üstüne yazar, seçilen profil de dahili temel
+ayarların üstüne yazar.
+
+### Agent ayarları
+
+`agentSettings`, agent compilation sırasında uygulanır ve sadece `model`, `temperature` ve
+`steps` alanlarını doldurur; ancak bu alanlar host config içinde zaten açıkça tanımlanmışsa
+dokunulmaz.
+
+Pratik kural:
+
+- paketlenmiş agent markdown dosyaları temel tanımı sağlar
+- `agentSettings` merkezi varsayılan override sağlar
+- açıkça tanımladığınız `opencode.json -> agent.<name>.*` değerleri her zaman kazanır
+
+### MCP varsayılanları
+
+Paketlenmiş `mcpDefaults` bölümü korumacı şekilde enjekte edilir. Plugin, aktif OpenCode
+konfigürasyonunda aynı isimde bir sunucu yoksa MCP sunucusunu ekler.
+
+Pratik kural:
+
+- paketlenmiş `mcpDefaults` boşlukları doldurur
+- açıkça tanımladığınız `opencode.json -> mcp.<name>` değerleri her zaman kazanır
+
+## `flags`
+
+Üst seviye runtime flag'leri:
+
+| Anahtar               | Varsayılan | Ne yapar                                                                               |
+| --------------------- | ---------- | -------------------------------------------------------------------------------------- |
+| `profile`             | `standard` | Kullanıcı flag override'ları uygulanmadan önce temel runtime profilini seçer.          |
+| `enforcement`         | `true`     | Hassas dosya yolları ve yıkıcı shell komutları için yerel güvenlik kontrollerini açar. |
+| `observation`         | `true`     | Event ve tool çalıştırmalarını JSONL olarak loglar.                                    |
+| `prompt_controls`     | `true`     | Prompt metadata header'larını ve riskli prompt/komut içerik loglamasını açar.          |
+| `agent_compilation`   | `true`     | Paketlenmiş, global ve proje bazlı agent markdown dosyalarını aktif config'e derler.   |
+| `command_compilation` | `true`     | Paketlenmiş, global ve proje bazlı command markdown dosyalarını aktif config'e derler. |
+| `mcp_compilation`     | `true`     | Eksikse plugin tarafından yönetilen MCP varsayılanlarını aktif config'e enjekte eder.  |
+| `telemetry`           | `true`     | Session, tool ve hata telemetry kayıtlarını plugin loguna yazar.                       |
+| `supervision`         | `true`     | Delegated child session'lar için parent-child supervision hatırlatmalarını açar.       |
+| `quality_gate`        | `true`     | Edit yapan session'ları izler ve idle kalınca quality reminder üretir.                 |
+| `skill_injection`     | `false`    | Runtime skill registry taramasını ve skill availability injection'ını açar.            |
+
+### `skill_sources`
+
+Varsayılan değer:
+
+```json
+["${plugin_root}/skills", "${home}/.agents/skills", "${home}/skills"]
+```
+
+Bu dizi, `skill_injection` açıksa kullanılacak arama sırasını belirtir.
+
+- `${plugin_root}` kurulu paket kökünü gösterir
+- `${home}` aktif kullanıcının home dizinini gösterir
+
+### `compiler.permission_compilation`
+
+| Anahtar                           | Varsayılan | Ne yapar                                                                                                                                                 |
+| --------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compiler.permission_compilation` | `true`     | `bash`, `read`, `edit`, `glob`, `grep` ve `list` gibi temel araçlar için eksik top-level OpenCode permission varsayılanlarını temkinli biçimde doldurur. |
+
+### `experimental`
+
+Bu flag'ler opsiyonel prompt ve session transform davranışlarını açar:
+
+| Anahtar                                | Varsayılan | Ne yapar                                                   |
+| -------------------------------------- | ---------- | ---------------------------------------------------------- |
+| `experimental.chat_system_transform`   | `false`    | System prompt sonuna deneysel bir not ekler.               |
+| `experimental.chat_messages_transform` | `false`    | Dispatch öncesi son kullanıcı mesajına deneysel not ekler. |
+| `experimental.session_compacting`      | `false`    | Session compaction özetlerine deneysel context ekler.      |
+| `experimental.text_complete`           | `false`    | Tamamlanan LLM çıktılarının sonuna deneysel metin ekler.   |
+
+Bu alanlar varsayılan olarak sadece `strict` profilinde açıktır.
+
+### `supervision_config`
+
+| Anahtar                              | Varsayılan | Anlamı                                                                  |
+| ------------------------------------ | ---------- | ----------------------------------------------------------------------- |
+| `supervision_config.idle_timeout_ms` | `180000`   | Delegated child session'ın ne kadar süre boşta kalabileceğini belirler. |
+| `supervision_config.cooldown_ms`     | `300000`   | Supervision hatırlatmaları arasındaki bekleme süresi.                   |
+
+### `quality_config`
+
+| Anahtar                               | Varsayılan | Anlamı                                                                                       |
+| ------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
+| `quality_config.reminder_idle_ms`     | `120000`   | Edit yapan bir session ne kadar süre boşta kalırsa quality reminder düşünüleceğini belirler. |
+| `quality_config.reminder_cooldown_ms` | `300000`   | Quality reminder'lar arasındaki bekleme süresi.                                              |
+
+## `agentSettings`
+
+Bu bölüm, agent bazında şu varsayılanları merkezi olarak yönetir:
+
+- `model`
+- `temperature`
+- `steps`
+
+Paketlenmiş tüm agent'lar şu anda varsayılan olarak `temperature: 0` kullanır.
+
+| Agent             | Kategori      | Varsayılan model                  | Steps |
+| ----------------- | ------------- | --------------------------------- | ----- |
+| `lead`            | Primary       | `anthropic/claude-opus-4-6`       | `500` |
+| `critic`          | Primary       | `openai/gpt-5.4`                  | `200` |
+| `planner`         | Primary       | `anthropic/claude-opus-4-6`       | `100` |
+| `executor`        | Primary       | `anthropic/claude-sonnet-4-6`     | `200` |
+| `scout`           | Research      | `anthropic/claude-sonnet-4-6`     | `24`  |
+| `worker`          | Coding        | `openai/gpt-5.3-codex`            | `30`  |
+| `heavy-worker`    | Coding        | `openai/gpt-5.4`                  | `40`  |
+| `deep-worker`     | Coding        | `anthropic/claude-opus-4-6`       | `60`  |
+| `ui-worker`       | Coding        | `anthropic/claude-opus-4-6`       | `30`  |
+| `ui-heavy-worker` | Coding        | `anthropic/claude-opus-4-6`       | `40`  |
+| `quick`           | Coding        | `opencode-go/minimax-m2.5`        | `16`  |
+| `reviewer`        | Quality       | `github-copilot/grok-code-fast-1` | `24`  |
+| `validator`       | Quality       | `openai/gpt-5.3-codex`            | `24`  |
+| `qa`              | Quality       | `openai/gpt-5.4`                  | `24`  |
+| `advisor`         | Advisory      | `openai/gpt-5.4`                  | `20`  |
+| `auditor`         | Quality       | `openai/gpt-5.4`                  | `24`  |
+| `strategist`      | Advisory      | `anthropic/claude-opus-4-6`       | `20`  |
+| `devil`           | Quality       | `anthropic/claude-sonnet-4-6`     | `8`   |
+| `scribe`          | Documentation | `anthropic/claude-sonnet-4-6`     | `30`  |
+| `librarian`       | Research      | `anthropic/claude-sonnet-4-6`     | `24`  |
+
+## `mcpDefaults`
+
+Bunlar paketle birlikte gelen ve plugin tarafından yönetilen MCP sunucu tanımlarıdır.
+
+| Sunucu       | Tip      | Varsayılan enabled | Amaç                                                                      |
+| ------------ | -------- | ------------------ | ------------------------------------------------------------------------- |
+| `code_index` | `local`  | `true`             | İndeksli kod arama, dosya bulma, özet ve sembol sorguları.                |
+| `repo`       | `local`  | `true`             | Git status, diff, log, branch ve commit inceleme araçları.                |
+| `context7`   | `remote` | `false`            | Güncel kütüphane ve framework dokümantasyonu sorgulama.                   |
+| `exa`        | `remote` | `false`            | Web arama ve code context toplama.                                        |
+| `gh_grep`    | `remote` | `false`            | Public GitHub depolarında kod arama.                                      |
+| `github`     | `local`  | `false`            | GitHub repo, issue, PR ve dosya işlemleri. `GITHUB_PAT_TOKEN` gerektirir. |
+
+Notlar:
+
+- `code_index` ve `repo`, yerel geliştirme akışını doğrudan desteklediği için varsayılan olarak açıktır.
+- `github`, kimlik bilgisi gerektirdiği için varsayılan olarak kapalıdır.
+- `context7`, `exa` ve `gh_grep` opsiyonel uzak servislerdir; kapalı başlar.
+
+## `profiles`
+
+Plugin üç isimli profil ile gelir.
+
+| Profil     | En uygun senaryo           | Observation ve telemetry | Supervision ve quality | Experimental transform |
+| ---------- | -------------------------- | ------------------------ | ---------------------- | ---------------------- |
+| `minimal`  | En düşük runtime yükü      | Çoğu kapalı              | Çoğu kapalı            | Kapalı                 |
+| `standard` | Varsayılan günlük kullanım | Açık                     | Açık                   | Kapalı                 |
+| `strict`   | En yüksek koruma seviyesi  | Açık                     | Açık                   | Açık                   |
+
+Profil detayları:
+
+- `minimal`, enforcement'i açık bırakır ama log ve reminder davranışlarını azaltır.
+- `standard`, normal kullanım için varsayılan dengedir.
+- `strict`, standart korumaların üstüne tüm experimental transform'ları da açar.
+
+## Kullanıcı Override Örnekleri
+
+### Temel kullanıcı runtime dosyası
+
+Yol: `~/.config/opencode/plugins/opencode-multiagent.json`
+
+```json
+{
+  "flags": {
+    "profile": "strict"
+  },
+  "agentSettings": {
+    "lead": {
+      "steps": 650
+    }
+  }
+}
+```
+
+### Özel profil örneği
+
+```json
+{
+  "profiles": {
+    "sessiz": {
+      "observation": false,
+      "telemetry": false,
+      "supervision": false,
+      "quality_gate": false
+    }
+  },
+  "flags": {
+    "profile": "sessiz"
+  }
+}
+```
+
+### `opencode.json` içinde host taraflı MCP override
+
+Bir MCP sunucusunu açıkça etkinleştirmek veya değiştirmek istediğinizde host config kullanın:
+
+```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
+    }
+  }
+}
+```
+
+## İlgili Dokümanlar
+
+- [Kullanım Kılavuzu](usage-guide.tr.md)
+- [Ajan Referansı](agents.tr.md)