opencode-multiagent 0.2.1 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md
+
+## Build, Test, and Validation
+
+- **Setup**: `mise run setup`
+- **Build**: `mise run build`
+- **Dev build**: `mise run dev`
+- **Test**: `mise run test`
+- **Lint**: `mise run lint`
+- **Fix lint**: `mise run lint:fix`
+- **Format**: `mise run format`
+- **Typecheck**: `mise run typecheck`
+- **Validate defaults**: `mise run validate-config`
+- **Package preview**: `mise run pack:dry-run`
+- **Full local check**: `mise run ci:check`
+- **Config server**: `mise run config-server` (starts local HTTP API on port 4242 for reading/writing plugin settings)
+- **Telemetry report**: `mise run telemetry-report` (renders JSONL telemetry summary)
+- **Version bump**: `mise run version` (runs `npm version` for release prep)
+- **Publish**: `mise run publish` (publishes to npm)
+- **Package lint**: `mise run pkgjsonlint` (enforces package.json constraints)
+
+## Hard Constraints
+
+- **No `scripts` in `package.json`.** The `pkgjsonlint` task enforces this. All tasks live in `.mise/tasks/` as executable files. Never add a `scripts` block to `package.json`.
+- **`no-console` in source code.** ESLint enforces `no-console: error` in `src/`. Use the plugin's logging utilities instead. `scripts/` is exempt.
+- **Bilingual documentation.** Files in `docs/` have Turkish translations with `.tr.md` suffix. When updating a doc, update both language versions.
+
+## Packaging Context
+
+- Runtime package entry is compiled to `dist/index.js`.
+- Type declarations are emitted to `dist/**/*.d.ts`.
+- Raw ecosystem assets are published from `agents/`, `commands/`, `defaults/`, `docs/`, `skills/`, and `examples/`.
+- `@opencode-ai/plugin` stays external during bundling.
+- `scripts/` contains dev-time TypeScript utilities (validation, config server, telemetry). Not shipped. Run via `tsx`.
+- `hk.pkl` at root is the [hk](https://github.com/jdx/hk) git hook configuration. `mise run setup` installs hooks from it.
+
+## Code Style Guidelines
+
+### Imports and Modules
+
+- Use ESM `import` / `export` syntax.
+- Keep explicit `.ts` extensions for internal source imports.
+- Group imports by external modules first, then local modules.
+
+### Formatting
+
+- Use Prettier defaults from `.prettierrc`.
+- Prefer single quotes.
+- Keep lines near 100 characters.
+- Use semicolons.
+
+### TypeScript
+
+- Keep `strict` mode clean.
+- Prefer early returns over nested conditionals.
+- Avoid `any` when a real type is available.
+- Public exports should stay intentionally typed.
+
+### Runtime Safety
+
+- Preserve asset-path correctness for both source execution and bundled `dist/` execution.
+- Do not inline or remove bundled markdown / JSON directories from packaging.
+- Keep `defaults/` schemas and runtime loaders in sync.
+
+## Agent Memory
+
+- `.magent/` is the runtime agent memory store (gitignored). Only `docmaster` may write here.
+- Plans go in `.magent/plans/` and must include: Objective, Phases, Acceptance Criteria, Risks, Verification Gates.
+- `.magent/board.json` is the live task board (gitignored). Managed by the plugin automatically.
+
+## Testing Notes
+
+- Add tests under `tests/`.
+- Prefer focused unit tests for runtime helpers and hook behavior.
+- Keep smoke coverage for the published package entry surface.
+
+## Project Context
+
+- This repository is an OpenCode plugin package.
+- The package ships compiled JavaScript plus bundled agent, command, defaults, and skill assets.
+- Release automation is driven by Release Please and npm trusted publishing.
+- The plugin ships 9 bundled agent definitions, 9 slash commands, and 22 skill directories.
+- Slash commands in `commands/` use YAML frontmatter (`description`, `agent`, `model`) and `$ARGUMENTS` placeholder.

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [0.4.0](https://github.com/vaur94/opencode-multiagent/compare/v0.3.0...v0.4.0) (2026-03-15)
+
+
+### Features
+
+* add task↔session correlation, automatic lifecycle, quality gates, and concurrency control ([9901065](https://github.com/vaur94/opencode-multiagent/commit/99010651a6fe532d505ed722be56d9e0a952c0a1))
+
+
+### Bug Fixes
+
+* remove prerelease strategy so releases publish as latest ([f495780](https://github.com/vaur94/opencode-multiagent/commit/f49578042672047a0d5d480c673eb620db712164))
+* use direct command for pack dry-run in publish workflow ([723f9c7](https://github.com/vaur94/opencode-multiagent/commit/723f9c7879eedbfe444da07d4f0124109f249ae7))
+
+## [0.3.0](https://github.com/vaur94/opencode-multiagent/compare/v0.2.1...v0.3.0) (2026-03-15)
+
+
+### Features
+
+* adopt bun packaging and unified settings ([281fb23](https://github.com/vaur94/opencode-multiagent/commit/281fb23eec4af1b640f80de0c7963c7419babed3))
+
+
+### Bug Fixes
+
+* align release tasks with bun-first packaging ([566ceea](https://github.com/vaur94/opencode-multiagent/commit/566ceeaf5aff653d0c67368caabe123b43e8b0aa))
+* upgrade npm in publish workflow ([54ac5ce](https://github.com/vaur94/opencode-multiagent/commit/54ac5ceff566889d021fd8fa6bb38d0ae89de19a))
+
+## [0.2.1](https://github.com/vaur94/opencode-multiagent/releases/tag/v0.2.1)
+
+- Baseline release before the Bun template packaging migration.

package/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Thank you for your interest in contributing.
+
+## Reporting Issues
+
+- Search existing issues before opening a new one.
+- Include reproduction steps, expected behavior, and actual behavior.
+- For runtime bugs, include OpenCode version, Node or Bun version, and OS details when relevant.
+
+> **Note:** Issues inactive for 60 days may be marked stale and closed after 7 days.
+
+## Submitting Changes
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feat/my-change`).
+3. Make your changes.
+4. Run the local verification suite:
+   ```bash
+   mise run ci:check
+   ```
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/) format.
+6. Push and open a Pull Request.
+
+## Pull Request Guidelines
+
+- PR titles must follow Conventional Commits format.
+- Keep PRs focused on one logical change.
+- Add or update tests when behavior changes.
+- Ensure packaged assets and compiled output assumptions still hold.
+
+## Code Style
+
+- ESLint and Prettier are the source of truth.
+- Run `mise run lint:fix` and `mise run format` before opening a PR.
+- See `AGENTS.md` for project-specific implementation notes.

package/README.md

@@ -1,54 +1,19 @@
-# opencode-multiagent
-
-`opencode-multiagent` is a TypeScript OpenCode plugin package for running a disciplined multi-agent control plane through the standard OpenCode plugin system.
-
-- 4 primary agents: `lead`, `critic`, `planner`, `executor`
-- 16 subagents for coding, review, research, docs, and repo mapping
-- plugin-managed MCP defaults and MCP tool enforcement
-- central agent settings, profiles, telemetry, file-lock, and QA reminder guards
-- npm-loaded plugin model through `opencode.json`
-
-## Install
-
-For plugin consumers, the primary integration is `opencode.json`.
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-multiagent"]
-}
-```
+> Language: **English** | [Turkish](README.tr.md)
 
-OpenCode resolves the package from the plugin array and loads the plugin from the package export.
-
-Example configs:
-
-- `examples/opencode.json`
-- `examples/opencode.with-overrides.json`
-
-## Development
-
-For working on this plugin package itself:
-
-```bash
-npm install
-npm run ci:check
-```
-
-Local OpenCode development can use a linked package or a local package path in `opencode.json` while iterating.
-
-## Migration from the old setup
+# opencode-multiagent
 
-If your old `opencode.json` manually carried MCP servers, plugin-managed agents, or broad permission defaults, simplify it.
+`opencode-multiagent` is an OpenCode plugin that installs a structured multi-agent control
+plane through the standard plugin system.
 
-Recommended migration:
+- 2 primary agents: `planner`, `executor`
+- 7 subagents for coding, review, research, and documentation
+- plugin-managed MCP defaults, telemetry, file locks, supervision, and a shared task board
+- compiled npm package with bundled `agents/`, `commands/`, `defaults/`, `skills/`,
+  `examples/`, and `docs/`
 
-1. Add `"plugin": ["opencode-multiagent"]`
-2. Remove duplicated `mcp` definitions unless you are intentionally overriding a bundled server
-3. Remove duplicated bundled `agent` entries unless you are intentionally overriding a field like `steps`
-4. Remove broad tool permission blocks that were only compensating for the old flat config
+## Quick Start
 
-Minimal target:
+Add the plugin to `opencode.json`:
 
 ```json
 {
@@ -57,153 +22,64 @@ Minimal target:
 }
 ```
 
-Override example:
+Optional host-side override example:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": ["opencode-multiagent"],
   "agent": {
-    "lead": {
-      "steps": 650
+    "planner": {
+      "steps": 300
     }
   }
 }
 ```
 
-## Architecture
-
-### Primary agents
-
-- `lead` - single entry point, lifecycle owner, 4-tier triage
-- `critic` - challenge mode plus inspection mode
-- `planner` - durable plan authoring
-- `executor` - task orchestration and validation tiers
-
-### Subagents
-
-- `scout`
-- `worker`, `heavy-worker`, `deep-worker`, `ui-worker`, `ui-heavy-worker`, `quick`
-- `reviewer`, `validator`, `qa`
-- `advisor`, `strategist`, `auditor`, `devil`
-- `scribe`
-- `librarian`
-
-### Lead triage
-
-- `Tier 0` - trivial work -> `executor`
-- `Tier 1` - bounded work -> `critic` then `executor`
-- `Tier 2` - complex work -> `critic` then `planner` then `executor`
-- `Tier 3` - investigation or repo-memory work -> `critic` inspection mode
+More examples:
 
-## Plugin responsibilities
-
-The plugin `config` hook:
-
-- injects bundled markdown agents and commands
-- applies central agent setting overrides from `defaults/agent-settings.json`
-- injects plugin-managed MCP defaults from `defaults/mcp-defaults.json`
-- blocks disallowed MCP tool usage using compiled per-agent permission rules
-- disables native user-facing OpenCode agents when the plugin-managed replacements are active
-- prefers `lead` as `default_agent`
-
-The runtime hook layer also provides:
-
-- telemetry JSONL logging
-- file-lock protection for overlapping edits across sessions
-- repeated QA handoff reminders
-- quality reminders for verification-like follow-up
-- supervision for child sessions
-
-## Plugin-owned MCP behavior
-
-Bundled MCP defaults:
-
-- `code_index`
-- `repo`
-- `context7`
-- `exa`
-- `gh_grep`
-- `github`
-
-Behavior:
-
-- if the host config does not define one of these servers, the plugin injects its bundled default
-- if the host config already defines one of these servers, the plugin does not overwrite it
-- agent access is shaped by bundled frontmatter permissions and re-checked in runtime hooks
-
-That means the plugin owns the baseline MCP layer, while the host config remains the override layer.
-
-## Runtime config
-
-User overrides live under `~/.config/opencode/plugins/`:
-
-- `opencode-multiagent.flags.json`
-- `opencode-multiagent.agent-settings.json`
-- `opencode-multiagent.profiles.json`
-
-Bundled defaults live in `defaults/` and are merged conservatively at runtime.
-
-## Scripts
-
-```bash
-npm run typecheck
-npm run validate-config
-npm run config-server
-npm run telemetry-report
-npm run ci:check
-npm run pack:dry-run
-```
-
-## Release model
-
-- CI is npm-based
-- publish flow is npm trusted publishing ready
-- plugin consumption stays `opencode.json -> plugin`
-- the package is source-first TypeScript; OpenCode can load the exported TypeScript entry directly
-
-## Publishing
-
-This repository is set up for npm trusted publishing through GitHub Actions OIDC.
+- `examples/opencode.json`
+- `examples/opencode.with-overrides.json`
 
-Before any release:
+## Documentation
 
-```bash
-npm run ci:check
-npm run pack:dry-run
-```
+| Document                | English                                          | Turkish                                                | Covers                                                                  |
+| ----------------------- | ------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------- |
+| Configuration Reference | [`docs/configuration.md`](docs/configuration.md) | [`docs/configuration.tr.md`](docs/configuration.tr.md) | Flags, profiles, agent settings, MCP defaults, and override rules       |
+| Usage Guide             | [`docs/usage-guide.md`](docs/usage-guide.md)     | [`docs/usage-guide.tr.md`](docs/usage-guide.tr.md)     | Installation, workflows, task board usage, profiles, and MCP enablement |
+| Agent Reference         | [`docs/agents.md`](docs/agents.md)               | [`docs/agents.tr.md`](docs/agents.tr.md)               | All primary agents and subagents, routing, models, and roles            |
 
-### First publish
+## Development
 
-The first npm publish must be done manually from the repository root because trusted publishing cannot create a brand-new package on npm by itself.
+This repository follows the `bun-module` tooling model with `mise` tasks.
 
 ```bash
-npm whoami
-npm publish --access public
+mise run setup
+mise run ci:check
 ```
 
-Do not use local provenance for the first publish. Provenance is generated later by the GitHub Actions publish workflow.
-
-If npm requires browser or OTP confirmation, complete that locally first.
-
-### Trusted publisher setup
-
-After the first successful publish, create the npm trusted publisher mapping for this repository:
+Useful commands:
 
 ```bash
-npx -y npm@11.11.0 trust github opencode-multiagent --repo vaur94/opencode-multiagent --file publish.yml
+mise run build
+mise run dev
+mise run test
+mise run lint
+mise run lint:fix
+mise run format
+mise run validate-config
+mise run pack:dry-run
 ```
 
-The workflow filename must stay `publish.yml` on npm's side, not `.github/workflows/publish.yml`.
+## Packaging
 
-### Workflow behavior
+- runtime entry: `dist/index.js`
+- type declarations: `dist/**/*.d.ts`
+- bundled assets: `agents/`, `commands/`, `defaults/`, `skills/`, `examples/`, `docs/`
+- external peer dependency: `@opencode-ai/plugin`
 
-- GitHub release `published` events perform a real `npm publish --provenance --access public`
-- manual `workflow_dispatch` runs verification by default and only publish when the `publish` input is enabled
-- release tags must match `v<package.json version>` before the publish step can run
+Release details live in `RELEASE.md`.
 
-## Notes
+## License
 
-- no file-copy install or update workflow remains
-- no bundled test suite remains; validation is static and structural by design
-- this package is now aligned to the standard OpenCode plugin loading model instead of the old copied-global-file model
+MIT

package/README.tr.md

@@ -0,0 +1,84 @@
+> Dil: [English](README.md) | **Türkçe**
+
+# opencode-multiagent
+
+`opencode-multiagent`, standart plugin sistemi uzerinden yapilandirilmis bir multi-agent
+kontrol duzlemi kuran bir OpenCode eklentisidir.
+
+- 2 ana ajan: `planner`, `executor`
+- kodlama, review, arastirma ve dokumantasyon icin 7 alt ajan
+- plugin tarafindan yonetilen MCP varsayilanlari, telemetry, file lock, supervision ve ortak task board
+- `agents/`, `commands/`, `defaults/`, `skills/`, `examples/` ve `docs/` ile birlikte yayinlanan derlenmis npm paketi
+
+## Hizli Baslangic
+
+`opencode.json` dosyasina plugin'i ekleyin:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-multiagent"]
+}
+```
+
+Host tarafinda override ornegi:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-multiagent"],
+  "agent": {
+    "planner": {
+      "steps": 300
+    }
+  }
+}
+```
+
+Daha fazla ornek:
+
+- `examples/opencode.json`
+- `examples/opencode.with-overrides.json`
+
+## Dokumantasyon
+
+| Dokuman                 | English                                          | Turkish                                                | Icerik                                                                        |
+| ----------------------- | ------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Konfigurasyon Referansi | [`docs/configuration.md`](docs/configuration.md) | [`docs/configuration.tr.md`](docs/configuration.tr.md) | Flag'ler, profiller, agent ayarlari, MCP varsayilanlari ve override kurallari |
+| Kullanim Kilavuzu       | [`docs/usage-guide.md`](docs/usage-guide.md)     | [`docs/usage-guide.tr.md`](docs/usage-guide.tr.md)     | Kurulum, is akisleri, task board kullanimi, profiller ve MCP etkinlestirme    |
+| Ajan Referansi          | [`docs/agents.md`](docs/agents.md)               | [`docs/agents.tr.md`](docs/agents.tr.md)               | Tum ana ve alt ajanlar, routing mantigi, modeller ve gorevleri                |
+
+## Gelistirme
+
+Bu depo, `bun-module` arac seti modelini `mise` task'lari ile kullanir.
+
+```bash
+mise run setup
+mise run ci:check
+```
+
+Sik kullanilan komutlar:
+
+```bash
+mise run build
+mise run dev
+mise run test
+mise run lint
+mise run lint:fix
+mise run format
+mise run validate-config
+mise run pack:dry-run
+```
+
+## Paketleme
+
+- runtime entry: `dist/index.js`
+- type declaration dosyalari: `dist/**/*.d.ts`
+- paketlenen varliklar: `agents/`, `commands/`, `defaults/`, `skills/`, `examples/`, `docs/`
+- external peer dependency: `@opencode-ai/plugin`
+
+Release detaylari `RELEASE.md` icindedir.
+
+## Lisans
+
+MIT

package/RELEASE.md

@@ -0,0 +1,68 @@
+# Release Process
+
+This project uses Release Please and npm Trusted Publishing for automated releases.
+
+It follows two release channels:
+
+- **Pre-release**: default branch pushes can publish `x.x.x-next.N` builds to the `next` npm dist-tag.
+- **Stable releases**: Release Please merges create stable releases published to the `latest` npm dist-tag.
+
+You can also trigger a manual publish workflow with the `latest` or `next` tag.
+
+## First Release
+
+Before automated releases work for a brand-new npm package, you must perform the first release manually.
+
+### Checklist
+
+1. Confirm `package.json` metadata is correct.
+2. Run `npm login`.
+3. Run `mise run build`.
+4. Run `mise run publish --otp <your-2fa-code>`.
+5. In npm package settings, add a trusted publisher for GitHub Actions:
+   - **Organization or user**: `vaur94`
+   - **Repository**: `opencode-multiagent`
+   - **Workflow filename**: `publish.yml`
+
+## Conventional Commits
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `fix:` patches
+- `feat:` minor features
+- `feat!:` or `fix!:` breaking changes
+
+While the package is still `0.x`, breaking changes bump the minor version.
+
+## Automated Release Flow
+
+1. Push conventional commits to `master` or `main`.
+2. Release Please analyzes commits and updates the release PR.
+3. Non-release pushes on the default branch publish a `next` build from that exact commit SHA.
+4. When the release PR is merged, GitHub creates the stable release and publishes `latest` from that exact release commit.
+
+## Manual Publish Flow
+
+Use GitHub Actions `publish.yml` with the desired npm tag when you need a manual publish.
+
+## Do Not
+
+- Do not edit Release Please PRs by hand.
+- Do not manually bump versions outside Release Please unless you are intentionally doing a one-off prerelease publish.
+- Do not create long-lived npm tokens for CI; use trusted publishing.
+
+## Trusted Publishing
+
+This repository uses npm Trusted Publishing with GitHub Actions OIDC:
+
+- no long-lived npm tokens are required
+- each publish uses short-lived workflow-bound credentials
+- provenance attestations are generated automatically in CI
+
+## Helpful Commands
+
+```bash
+mise run ci:check
+mise run pack:dry-run
+mise run publish --dry-run --tag next
+```

package/agents/AGENTS.md

@@ -0,0 +1,91 @@
+# agents/
+
+Bundled agent definitions for the multi-agent system. Each `.md` file defines one agent's identity, capabilities, and permissions.
+
+## Frontmatter Schema
+
+Every agent file starts with a YAML frontmatter block:
+
+| Field         | Type   | Required | Description                                                                            |
+| ------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
+| `description` | string | yes      | One-line agent description                                                             |
+| `mode`        | string | yes      | `primary` (user-facing, can be entry point) or `subagent` (dispatched by other agents) |
+| `model`       | string | yes      | Model identifier in `provider/model` format (e.g., `anthropic/claude-sonnet-4-6`)      |
+| `temperature` | number | yes      | Sampling temperature (0–2)                                                             |
+| `steps`       | number | yes      | Maximum tool-use steps per session                                                     |
+| `permission`  | object | yes      | Permission map (see below)                                                             |
+
+## Permission Model
+
+Permissions use a **deny-by-default** model. The top-level `'*': deny` blocks everything, then specific capabilities are explicitly allowed.
+
+```yaml
+permission:
+  '*': deny # deny everything by default
+  read:
+    '*': allow # allow reading all files
+    '*.env': deny # except .env files
+  edit: allow # allow editing (or use glob patterns)
+  bash: allow # allow shell execution
+  task:
+    '*': deny # deny dispatching all agents
+    coder: allow # except coder
+    reviewer: allow # except reviewer
+  skill:
+    '*': deny # deny all skills
+    executing-plans: allow # except specific ones
+```
+
+### Permission keys
+
+- `read`, `edit` — file access (supports glob patterns)
+- `bash` — shell command execution
+- `glob`, `grep`, `list`, `lsp` — code navigation tools
+- `todoread`, `todowrite` — task list management
+- `task` — sub-agent dispatch (nested: agent names)
+- `skill` — skill loading (nested: skill names)
+- `task_create`, `task_update`, `task_list` — shared task board
+- `code_index_*`, `repo_git_*` — MCP tool access
+- `webfetch`, `websearch`, `codesearch` — external access
+- `external_directory` — external directory access
+
+## agentSettings Coupling
+
+Each agent name must have a matching entry in `defaults/opencode-multiagent.json` under `agentSettings`. This entry controls the runtime model, temperature, and step overrides. The frontmatter values are defaults; `agentSettings` overrides take precedence.
+
+## Disabled Native Agents
+
+The following agent names are reserved and suppressed by the plugin to prevent conflicts with OpenCode's built-in agents:
+
+- `build`, `plan`, `general`, `explore`
+
+Do not create agent files with these names.
+
+## Current Agents (9)
+
+**Primary:** `planner`, `executor`
+
+**Subagents:** `coder`, `ui-coder`, `sec-coder`, `reviewer`, `auditor`, `scout`, `docmaster`
+
+## Agent Hierarchy
+
+```
+planner (triage + planning + inspection)
+├── executor (execution coordination)
+│   ├── coder (standard coding)
+│   │   ├── reviewer (self-review)
+│   │   └── scout (context lookup)
+│   ├── ui-coder (UI/UX coding)
+│   │   ├── reviewer (self-review)
+│   │   └── scout (context lookup)
+│   ├── sec-coder (security-sensitive coding)
+│   │   ├── reviewer (self-review)
+│   │   └── scout (context lookup)
+│   ├── reviewer (quality gate)
+│   ├── scout (research)
+│   └── docmaster (.magent + docs + GitHub)
+├── auditor (plan gap finder)
+├── scout (research)
+├── reviewer (evidence)
+└── docmaster (plan persistence)
+```