opencode-multiagent 0.2.1 → 0.3.0-next.1

package/docs/agents.md

@@ -0,0 +1,260 @@
+> Language: **English** | [Turkish](agents.tr.md)
+>
+> Back: [README](../README.md)
+
+# Agent Reference
+
+`opencode-multiagent` ships 20 bundled agents:
+
+- 4 primary agents
+- 16 subagents
+
+All bundled agents currently default to `temperature: 0`.
+
+## 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
+- 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
+```
+
+## Primary Agents
+
+### `lead`
+
+- 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`
+- 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
+
+### `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/`
+
+### `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
+
+## 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
+
+### `worker`
+
+- 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`
+- 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
+
+### `deep-worker`
+
+- 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
+- Use when: the work is mainly components, view-local state, layout, accessibility, or responsive behavior
+
+### `ui-heavy-worker`
+
+- 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
+
+## Quality and Review 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
+
+### `auditor`
+
+- Mode: `subagent`
+- Default model: `openai/gpt-5.4`
+- Steps: `24`
+- Purpose: aggressive read-only plan auditor
+- 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
+
+### `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
+
+## Documentation Agent
+
+### `scribe`
+
+- 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
+
+## 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`                                                                         |
+
+## 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                  |
+
+## Related Docs
+
+- [Configuration Reference](configuration.md)
+- [Usage Guide](usage-guide.md)

package/docs/agents.tr.md

@@ -0,0 +1,260 @@
+> Dil: [English](agents.md) | **Türkçe**
+>
+> Geri: [README](../README.tr.md)
+
+# Ajan Referansı
+
+`opencode-multiagent`, 20 paketlenmiş ajan ile gelir:
+
+- 4 ana ajan
+- 16 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:
+
+- `lead` kullanıcıya dönük routing'i yönetir
+- `critic` route'u sorgular veya repo durumunu inceler
+- `planner` büyük işler için kalıcı plan üretir
+- `executor` planı bounded worker yürütmesine dönüştürür
+- uzman alt ajanlar kodlama, review, arastirma ve dokumantasyon işlerini üstlenir
+
+## Yüksek Seviye Hiyerarşi
+
+```text
+kullanici
+  -> 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  (tekrarlanan QA başarısızlıklarında eskalasyon)
+       -> librarian
+       -> scout
+       -> scribe
+```
+
+## Ana Ajanlar
+
+### `lead`
+
+- Mod: `primary`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `500`
+- Amaç: kullanıcıya dönük tek giriş noktası olarak talebin tüm yaşam döngüsünü sahiplenmek
+- En uygun kullanım: route seçimi, iş delegasyonu, sonuçların birleştirilmesi ve kullanıcıya dönüş
+
+### `critic`
+
+- Mod: `primary`
+- Varsayılan model: `openai/gpt-5.4`
+- Steps: `200`
+- Amaç: challenge ve inspection ajanı olmak
+- En uygun kullanım: iş başlamadan önce route'u sorgulamak veya repo memory / plugin durumunu incelemek
+
+### `planner`
+
+- Mod: `primary`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `100`
+- Amaç: kod yazmadan kalıcı ve yürütmeye hazır plan üretmek
+- En uygun kullanım: büyük, cross-cutting, riskli veya çok aşamalı işler için `.magent/plans/` altında plan oluşturmak
+
+### `executor`
+
+- Mod: `primary`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `200`
+- Amaç: onaylanmış planı bounded worker görevlerine bölüp doğrulama katmanları ile yürütmek
+- En uygun kullanım: implementasyon orkestrasyonu, task board güncellemeleri, reviewer, validator ve QA akışını yönetmek
+
+## Kodlama Worker'ları
+
+### `quick`
+
+- Mod: `subagent`
+- Varsayılan model: `opencode-go/minimax-m2.5`
+- Steps: `16`
+- Amaç: çok küçük, açık ve düşük riskli düzenlemeler için hızlı worker
+- Ne zaman kullanılır: görev kelimesi kelimesine tanımlanmış, lokal ve net sınırları olan bir değişiklikse
+
+### `worker`
+
+- Mod: `subagent`
+- Varsayılan model: `openai/gpt-5.3-codex`
+- Steps: `30`
+- Amaç: normal bounded implementasyon işleri için standart worker
+- Ne zaman kullanılır: UI dışı, orta zorlukta, varsayılan kodlama yolu gerektiğinde
+
+### `heavy-worker`
+
+- Mod: `subagent`
+- Varsayılan model: `openai/gpt-5.4`
+- Steps: `40`
+- Amaç: riskli, cross-cutting veya güvenlik hassasiyeti olan implementasyon işleri
+- Ne zaman kullanılır: değişiklik birden fazla modülü, hassas runtime davranışını veya güvenlik mantığını etkiliyorsa
+
+### `deep-worker`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `60`
+- Amaç: belirsiz veya yoğun muhakeme gerektiren işler için uzun ufuklu tek sahipli worker
+- Ne zaman kullanılır: görev, daha fazla yerel analiz, akış takibi veya dikkatli çok adımlı bir uygulama gerektiriyorsa
+
+### `ui-worker`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `30`
+- Amaç: normal karmaşıklıktaki UI ve UX işleri
+- Ne zaman kullanılır: iş daha çok component, view-local state, layout, accessibility veya responsive davranış ile ilgiliyse
+
+### `ui-heavy-worker`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `40`
+- Amaç: geniş kapsamlı veya karmaşık durum yöneten UI ve UX işleri
+- Ne zaman kullanılır: iş birden fazla ekranı, karmaşık akışları veya koordineli etkileşim davranışlarını kapsıyorsa
+
+## Kalite ve Review Ajanları
+
+### `reviewer`
+
+- Mod: `subagent`
+- Varsayılan model: `github-copilot/grok-code-fast-1`
+- Steps: `24`
+- Amaç: küçük ve bounded değişiklikler için read-only kod incelemesi yapmak
+- En uygun kullanım: implementasyon tamamlandı denmeden önce 1-3 dosyalık dar bir değişiklik yüzeyini incelemek
+
+### `validator`
+
+- Mod: `subagent`
+- Varsayılan model: `openai/gpt-5.3-codex`
+- Steps: `24`
+- Amaç: gerekli en küçük doğrulama komutlarını çalıştıran bounded doğrulama ajanı
+- En uygun kullanım: test, build, lint ve typecheck gibi komutlarla kanıt üretmek
+
+### `qa`
+
+- Mod: `subagent`
+- Varsayılan model: `openai/gpt-5.4`
+- Steps: `24`
+- Amaç: son kabul kararını veren read-only kalite kapısı olmak
+- En uygun kullanım: daha yüksek riskli işlerde doğrulama sonrası net bir OKAY veya REJECT kararı gerektiğinde
+
+### `auditor`
+
+- Mod: `subagent`
+- Varsayılan model: `openai/gpt-5.4`
+- Steps: `24`
+- Amaç: agresif read-only plan denetimi yapmak
+- 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
+
+### `devil`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `8`
+- Amaç: araç kullanmadan saf devil's-advocate muhakemesi yürütmek
+- En uygun kullanım: varsayımları sorgulamak, kör noktaları göstermek ve hızlı karşı argüman üretmek
+
+## Araştırma ve Danışmanlık Ajanları
+
+### `scout`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `24`
+- Amaç: hızlı ve read-only repo haritalama yapmak
+- En uygun kullanım: dosya bulma, sembol takibi, kod tabanı yapısını anlama ve yerel keşif
+
+### `librarian`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `24`
+- Amaç: dış kaynak araştırması ve dokümantasyon toplamak
+- En uygun kullanım: güncel doküman sorgusu, dış karşılaştırmalar, API araştırması ve repo dışı kanıt toplama
+
+### `advisor`
+
+- Mod: `subagent`
+- Varsayılan model: `openai/gpt-5.4`
+- Steps: `20`
+- Amaç: bloke olmuş veya düşük güvenli implementasyon işleri için read-only teknik danışmanlık vermek
+- En uygun kullanım: worker'ı unblock etmek, yerel implementasyon yolları arasında seçim yapmak veya riskli bir kararı netleştirmek
+
+### `strategist`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-opus-4-6`
+- Steps: `20`
+- Amaç: yön ve mimari kararlarda yargı odaklı danışmanlık vermek
+- En uygun kullanım: yaklaşım doğrulamak, mimari riskleri görünür kılmak ve bir planın ilerlemesi gerekip gerekmediğine karar vermek
+
+## Dokümantasyon Ajanı
+
+### `scribe`
+
+- Mod: `subagent`
+- Varsayılan model: `anthropic/claude-sonnet-4-6`
+- Steps: `30`
+- Amaç: dokümantasyon yazmak ve `.magent` artifaktlarını yönetmek
+- En uygun kullanım: `README.md`, `AGENTS.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `docs/**` ve `.magent/**` güncellemeleri
+
+## Kategori Özeti
+
+| Kategori                 | Ajanlar                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------- |
+| Ana orkestrasyon         | `lead`, `critic`, `planner`, `executor`                                          |
+| Kodlama worker'ları      | `quick`, `worker`, `heavy-worker`, `deep-worker`, `ui-worker`, `ui-heavy-worker` |
+| Kalite ve review         | `reviewer`, `validator`, `qa`, `auditor`, `devil`                                |
+| Araştırma ve danışmanlık | `scout`, `librarian`, `advisor`, `strategist`                                    |
+| Dokümantasyon            | `scribe`                                                                         |
+
+## Özet Tablo
+
+| Agent             | Kategori      | Mod        | Model                             | Steps | Ana kullanım                                         |
+| ----------------- | ------------- | ---------- | --------------------------------- | ----- | ---------------------------------------------------- |
+| `lead`            | Primary       | `primary`  | `anthropic/claude-opus-4-6`       | `500` | Kullanıcıya dönük routing ve yaşam döngüsü sahipliği |
+| `critic`          | Primary       | `primary`  | `openai/gpt-5.4`                  | `200` | Challenge ve inspection                              |
+| `planner`         | Primary       | `primary`  | `anthropic/claude-opus-4-6`       | `100` | Kalıcı plan yazımı                                   |
+| `executor`        | Primary       | `primary`  | `anthropic/claude-sonnet-4-6`     | `200` | Yürütme orkestrasyonu ve doğrulama                   |
+| `quick`           | Coding        | `subagent` | `opencode-go/minimax-m2.5`        | `16`  | Çok küçük açık değişiklikler                         |
+| `worker`          | Coding        | `subagent` | `openai/gpt-5.3-codex`            | `30`  | Varsayılan bounded kodlama işi                       |
+| `heavy-worker`    | Coding        | `subagent` | `openai/gpt-5.4`                  | `40`  | Riskli cross-cutting implementasyon                  |
+| `deep-worker`     | Coding        | `subagent` | `anthropic/claude-opus-4-6`       | `60`  | Yoğun muhakeme isteyen tek sahipli kodlama           |
+| `ui-worker`       | Coding        | `subagent` | `anthropic/claude-opus-4-6`       | `30`  | Standart UI ve UX işi                                |
+| `ui-heavy-worker` | Coding        | `subagent` | `anthropic/claude-opus-4-6`       | `40`  | Geniş UI akışları ve ileri seviye state              |
+| `reviewer`        | Quality       | `subagent` | `github-copilot/grok-code-fast-1` | `24`  | Read-only kod incelemesi                             |
+| `validator`       | Quality       | `subagent` | `openai/gpt-5.3-codex`            | `24`  | Doğrulama komutları çalıştırma                       |
+| `qa`              | Quality       | `subagent` | `openai/gpt-5.4`                  | `24`  | Son kalite kapısı                                    |
+| `auditor`         | Quality       | `subagent` | `openai/gpt-5.4`                  | `24`  | Plan denetimi                                        |
+| `devil`           | Quality       | `subagent` | `anthropic/claude-sonnet-4-6`     | `8`   | Karşı argüman ve kör nokta üretimi                   |
+| `scout`           | Research      | `subagent` | `anthropic/claude-sonnet-4-6`     | `24`  | Yerel repo keşfi                                     |
+| `librarian`       | Research      | `subagent` | `anthropic/claude-sonnet-4-6`     | `24`  | Dış kaynak araştırması                               |
+| `advisor`         | Advisory      | `subagent` | `openai/gpt-5.4`                  | `20`  | Yerel implementasyon danışmanlığı                    |
+| `strategist`      | Advisory      | `subagent` | `anthropic/claude-opus-4-6`       | `20`  | Mimari ve yön kararı danışmanlığı                    |
+| `scribe`          | Documentation | `subagent` | `anthropic/claude-sonnet-4-6`     | `30`  | Doküman ve `.magent` yazımı                          |
+
+## İlgili Dokümanlar
+
+- [Konfigürasyon Referansı](configuration.tr.md)
+- [Kullanım Kılavuzu](usage-guide.tr.md)