opencode-multiagent 0.2.0 → 0.3.0-next.1

package/docs/usage-guide.md

@@ -0,0 +1,226 @@
+> Language: **English** | [Turkish](usage-guide.tr.md)
+>
+> Back: [README](../README.md)
+
+# Usage Guide
+
+This guide covers the practical day-to-day use of `opencode-multiagent` as an OpenCode plugin.
+
+## 1. Install the Plugin
+
+Add the plugin to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-multiagent"]
+}
+```
+
+That is the smallest supported setup.
+
+Reference examples:
+
+- `examples/opencode.json`
+- `examples/opencode.with-overrides.json`
+
+## 2. What Happens When the Plugin Loads
+
+When OpenCode loads the package, the plugin:
+
+1. reads bundled defaults from `defaults/opencode-multiagent.json`
+2. reads user overrides from `~/.config/opencode/plugins/opencode-multiagent.json`
+3. builds the effective runtime flags and agent settings
+4. compiles bundled agent and command markdown into the active config
+5. injects plugin-owned MCP defaults only when the host config does not already define them
+6. prefers `lead` as the default top-level agent when available
+7. enables runtime hooks for telemetry, file locks, supervision, quality reminders, and the shared task board
+
+## 3. Normal User Flow
+
+In normal use, you do not need to pick worker agents manually. The system is designed so the
+top-level interaction goes through `lead`.
+
+Typical flow:
+
+```text
+user -> lead -> critic/planner/executor -> specialized subagents
+```
+
+### The main routing roles
+
+| Agent      | Role                                                                      |
+| ---------- | ------------------------------------------------------------------------- |
+| `lead`     | Owns the request lifecycle, chooses routing, and integrates results.      |
+| `critic`   | Challenges a route or inspects repository state before work proceeds.     |
+| `planner`  | Writes a durable execution plan for larger or riskier work.               |
+| `executor` | Runs the plan by dispatching bounded worker tasks and validating results. |
+
+## 4. Triage Levels
+
+`lead` uses a tiered routing model.
+
+| Tier     | Meaning                                                  | Typical route                           |
+| -------- | -------------------------------------------------------- | --------------------------------------- |
+| `Tier 0` | Tiny, explicit, low-risk work                            | `lead -> executor -> quick/worker`      |
+| `Tier 1` | Bounded work that benefits from a challenge pass         | `lead -> critic -> executor`            |
+| `Tier 2` | Cross-cutting, risky, ambiguous, or migration-heavy work | `lead -> critic -> planner -> executor` |
+| `Tier 3` | Inspection and repo-memory work                          | `lead -> critic`                        |
+
+As a user, the practical takeaway is simple: ask for the task naturally and let `lead` decide the
+route unless you have a strong reason to override the flow.
+
+## 5. Shared Task Board
+
+The plugin exposes three shared task tools:
+
+- `task_create`
+- `task_update`
+- `task_list`
+
+These are used internally by the agent system to track work, but they are also important to
+understand when reading logs or `.magent` artifacts.
+
+### Task lifecycle
+
+Possible task states:
+
+- `pending`
+- `claimed`
+- `in_progress`
+- `completed`
+- `failed`
+- `blocked`
+
+### Persistence
+
+When a project root is available, the task board is persisted to:
+
+- `.magent/tasks/taskboard.json`
+
+This makes multi-step execution easier to inspect after a session.
+
+## 6. Profiles
+
+The plugin ships three runtime profiles:
+
+| Profile    | When to use it                                                               |
+| ---------- | ---------------------------------------------------------------------------- |
+| `minimal`  | You want lower runtime overhead and fewer reminders/logs.                    |
+| `standard` | Normal default usage. Best starting point for most users.                    |
+| `strict`   | You want the strongest runtime controls and experimental transforms enabled. |
+
+Example user override file:
+
+```json
+{
+  "flags": {
+    "profile": "strict"
+  }
+}
+```
+
+## 7. Overriding Agent Defaults
+
+Use `~/.config/opencode/plugins/opencode-multiagent.json` for centralized plugin-level overrides.
+
+Example:
+
+```json
+{
+  "agentSettings": {
+    "lead": {
+      "steps": 650
+    },
+    "reviewer": {
+      "model": "openai/gpt-5.4"
+    }
+  }
+}
+```
+
+Use `opencode.json` when you want an explicit host-level override for a specific OpenCode field.
+
+Example:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-multiagent"],
+  "agent": {
+    "lead": {
+      "steps": 650
+    }
+  }
+}
+```
+
+## 8. MCP Servers
+
+Bundled MCP defaults:
+
+- `code_index`
+- `repo`
+- `context7`
+- `exa`
+- `gh_grep`
+- `github`
+
+Important behavior:
+
+- if the host config already defines one of these servers, the plugin does not overwrite it
+- `code_index` and `repo` are enabled by default
+- `context7`, `exa`, `gh_grep`, and `github` start disabled in bundled defaults
+
+### Enabling GitHub MCP
+
+Use `opencode.json` to explicitly enable it:
+
+```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
+    }
+  }
+}
+```
+
+## 9. Logs and Generated Artifacts
+
+Common generated files and directories:
+
+| Path                                                  | Purpose                                           |
+| ----------------------------------------------------- | ------------------------------------------------- |
+| `~/.config/opencode/logs/opencode-multiagent.jsonl`   | Observation and telemetry log                     |
+| `~/.config/opencode/plugins/opencode-multiagent.json` | User runtime overrides                            |
+| `.magent/tasks/taskboard.json`                        | Shared task board persistence                     |
+| `.magent/plans/`                                      | Durable plans created through planner and scribe  |
+| `.magent/exec/`                                       | Execution artifacts maintained during larger work |
+
+## 10. Development Workflow
+
+If you are developing the plugin itself, the usual workflow is:
+
+```bash
+mise run setup
+mise run test
+mise run typecheck
+mise run validate-config
+mise run build
+```
+
+If `mise` is unavailable in your local shell, the equivalent direct commands are based on `bun`,
+`tsx`, and `tsc`.
+
+## Related Docs
+
+- [Configuration Reference](configuration.md)
+- [Agent Reference](agents.md)

package/docs/usage-guide.tr.md

@@ -0,0 +1,227 @@
+> Dil: [English](usage-guide.md) | **Türkçe**
+>
+> Geri: [README](../README.tr.md)
+
+# Kullanım Kılavuzu
+
+Bu kılavuz, `opencode-multiagent` eklentisinin günlük kullanımını pratik açıdan anlatır.
+
+## 1. Plugin Kurulumu
+
+`opencode.json` dosyasına plugin'i ekleyin:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-multiagent"]
+}
+```
+
+Bu, desteklenen en küçük kurulumdur.
+
+Referans örnekler:
+
+- `examples/opencode.json`
+- `examples/opencode.with-overrides.json`
+
+## 2. Plugin Yüklenince Ne Olur
+
+OpenCode paketi yüklediğinde plugin şu adımları uygular:
+
+1. `defaults/opencode-multiagent.json` içindeki varsayılanları okur
+2. `~/.config/opencode/plugins/opencode-multiagent.json` içindeki kullanıcı override'larını okur
+3. efektif runtime flag ve agent ayarlarını oluşturur
+4. paketlenmiş agent ve command markdown dosyalarını aktif config'e derler
+5. host config içinde yoksa plugin'e ait MCP varsayılanlarını ekler
+6. mümkünse `lead` ajanını varsayılan top-level ajan olarak tercih eder
+7. telemetry, file lock, supervision, quality reminder ve ortak task board hook'larını açar
+
+## 3. Normal Kullanım Akışı
+
+Normal kullanımda worker ajanları elle seçmeniz gerekmez. Sistem, top-level etkileşimin `lead`
+üzerinden gitmesi için tasarlanmıştır.
+
+Tipik akış:
+
+```text
+kullanici -> lead -> critic/planner/executor -> uzman alt ajanlar
+```
+
+### Temel routing rolleri
+
+| Agent      | Rol                                                                        |
+| ---------- | -------------------------------------------------------------------------- |
+| `lead`     | Talebin tüm yaşam döngüsünü yönetir, route seçer ve sonuçları birleştirir. |
+| `critic`   | İş başlamadan önce rota veya repo durumunu sorgular.                       |
+| `planner`  | Büyük veya riskli işlerde kalıcı bir yürütme planı üretir.                 |
+| `executor` | Planı bounded worker görevlerine bölerek uygular ve sonuçları doğrular.    |
+
+## 4. Triage Seviyeleri
+
+`lead`, katmanlı bir routing modeli kullanır.
+
+| Seviye   | Anlamı                                                         | Tipik route                             |
+| -------- | -------------------------------------------------------------- | --------------------------------------- |
+| `Tier 0` | Küçük, açık, düşük riskli işler                                | `lead -> executor -> quick/worker`      |
+| `Tier 1` | Kısa bir challenge turundan fayda gören bounded işler          | `lead -> critic -> executor`            |
+| `Tier 2` | Cross-cutting, riskli, belirsiz veya migration ağırlıklı işler | `lead -> critic -> planner -> executor` |
+| `Tier 3` | İnceleme ve repo-memory işleri                                 | `lead -> critic`                        |
+
+Kullanıcı açısından pratik kural basittir: güçlü bir sebep yoksa görevi doğal şekilde tarif edin ve
+`lead` ajanının route seçmesine izin verin.
+
+## 5. Ortak Task Board
+
+Plugin üç ortak task aracı sunar:
+
+- `task_create`
+- `task_update`
+- `task_list`
+
+Bu araçlar ajan sistemi tarafından dahili olarak kullanılır; ancak log ve `.magent` çıktılarının
+nasıl oluştuğunu anlamak için bilinmeleri faydalıdır.
+
+### Task yaşam döngüsü
+
+Olası task durumları:
+
+- `pending`
+- `claimed`
+- `in_progress`
+- `completed`
+- `failed`
+- `blocked`
+
+### Kalıcılık
+
+Bir proje kökü varsa task board şu dosyaya yazılır:
+
+- `.magent/tasks/taskboard.json`
+
+Bu sayede çok adımlı yürütmeler oturum sonrasında da incelenebilir.
+
+## 6. Profiller
+
+Plugin üç runtime profili ile gelir:
+
+| Profil     | Ne zaman kullanılır                                                      |
+| ---------- | ------------------------------------------------------------------------ |
+| `minimal`  | Daha düşük runtime yükü ve daha az log/reminder istediğinizde            |
+| `standard` | Normal varsayılan kullanım; çoğu kullanıcı için en iyi başlangıç noktası |
+| `strict`   | En güçlü runtime kontrolleri ve experimental transform'lar gerektiğinde  |
+
+Örnek kullanıcı override dosyası:
+
+```json
+{
+  "flags": {
+    "profile": "strict"
+  }
+}
+```
+
+## 7. Agent Varsayılanlarını Override Etme
+
+Merkezi plugin düzeyi override için `~/.config/opencode/plugins/opencode-multiagent.json`
+kullanın.
+
+Örnek:
+
+```json
+{
+  "agentSettings": {
+    "lead": {
+      "steps": 650
+    },
+    "reviewer": {
+      "model": "openai/gpt-5.4"
+    }
+  }
+}
+```
+
+Belirli bir OpenCode alanını açıkça override etmek istediğinizde `opencode.json` kullanın.
+
+Örnek:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-multiagent"],
+  "agent": {
+    "lead": {
+      "steps": 650
+    }
+  }
+}
+```
+
+## 8. MCP Sunucuları
+
+Paketle gelen MCP varsayılanları:
+
+- `code_index`
+- `repo`
+- `context7`
+- `exa`
+- `gh_grep`
+- `github`
+
+Önemli davranışlar:
+
+- host config zaten aynı isimli sunucuyu tanımlıyorsa plugin onun üstüne yazmaz
+- `code_index` ve `repo` varsayılan olarak açıktır
+- `context7`, `exa`, `gh_grep` ve `github` paket varsayılanlarında kapalı başlar
+
+### GitHub MCP'yi etkinleştirme
+
+Bunu açıkça etkinleştirmek için `opencode.json` 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
+    }
+  }
+}
+```
+
+## 9. Loglar ve Üretilen Artifaktlar
+
+Sık görülen dosya ve dizinler:
+
+| Yol                                                   | Amaç                                                      |
+| ----------------------------------------------------- | --------------------------------------------------------- |
+| `~/.config/opencode/logs/opencode-multiagent.jsonl`   | Observation ve telemetry logu                             |
+| `~/.config/opencode/plugins/opencode-multiagent.json` | Kullanıcı runtime override dosyası                        |
+| `.magent/tasks/taskboard.json`                        | Ortak task board verisi                                   |
+| `.magent/plans/`                                      | Planner ve scribe tarafından yazılan kalıcı planlar       |
+| `.magent/exec/`                                       | Büyük yürütmeler sırasında tutulan execution artifaktları |
+
+## 10. Geliştirme Akışı
+
+Plugin'in kendisini geliştiriyorsanız tipik akış şöyledir:
+
+```bash
+mise run setup
+mise run test
+mise run typecheck
+mise run validate-config
+mise run build
+```
+
+Yerel shell ortamınızda `mise` yoksa aynı doğrulamalar `bun`, `tsx` ve `tsc` tabanlı komutlarla da
+çalıştırılabilir.
+
+## İlgili Dokümanlar
+
+- [Konfigürasyon Referansı](configuration.tr.md)
+- [Ajan Referansı](agents.tr.md)

package/examples/opencode.with-overrides.json

@@ -4,11 +4,7 @@
   "mcp": {
     "github": {
       "type": "local",
-      "command": [
-        "npx",
-        "-y",
-        "@modelcontextprotocol/server-github"
-      ],
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
       "environment": {
         "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PAT_TOKEN}"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-multiagent",
-  "version": "0.2.0",
+  "version": "0.3.0-next.1",
   "type": "module",
   "description": "Multi-agent orchestration plugin for OpenCode",
   "license": "MIT",
@@ -15,31 +15,34 @@
   "publishConfig": {
     "access": "public"
   },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./agents/*": "./agents/*",
     "./commands/*": "./commands/*",
     "./defaults/*": "./defaults/*",
     "./skills/*": "./skills/*"
   },
   "files": [
-    "src",
+    "dist",
     "agents",
     "commands",
     "defaults",
+    "docs",
     "skills",
     "examples",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "README.tr.md",
+    "RELEASE.md"
   ],
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "validate-config": "tsx scripts/validate.ts",
-    "config-server": "tsx scripts/config-server.ts",
-    "telemetry-report": "tsx scripts/telemetry-report.ts",
-    "ci:check": "npm run typecheck && npm run validate-config",
-    "pack:dry-run": "npm pack --dry-run"
-  },
   "keywords": [
     "opencode",
     "plugin",
@@ -51,10 +54,17 @@
     "@opencode-ai/plugin": ">=1.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.1",
     "@opencode-ai/plugin": "1.0.85",
     "@types/node": "^24.0.0",
+    "bun-types": "latest",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "^5.1.3",
+    "prettier": "^3.2.4",
     "tsx": "^4.20.6",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.47.0"
   },
   "engines": {
     "node": ">=18"