https://github.com/whchi/your-legion
Plugin-first OpenCode multi-agent system inspired by oh-my-openagent
https://github.com/whchi/your-legion
ai-agent multi-agent opencode plugin-system typescript
Last synced: 4 days ago
JSON representation
Plugin-first OpenCode multi-agent system inspired by oh-my-openagent
- Host: GitHub
- URL: https://github.com/whchi/your-legion
- Owner: whchi
- Created: 2026-05-08T04:46:42.000Z (26 days ago)
- Default Branch: main
- Last Pushed: 2026-05-25T07:40:47.000Z (9 days ago)
- Last Synced: 2026-05-25T09:25:28.147Z (9 days ago)
- Topics: ai-agent, multi-agent, opencode, plugin-system, typescript
- Language: TypeScript
- Size: 215 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Your Legion
[](https://deepwiki.com/whchi/your-legion)
An OpenCode plugin that improves multi-agent work with bounded specialists, per-agent provider/model mapping, and structured context handoff.
Your Legion keeps OpenCode as the execution harness. It injects a small protected agent set, routes each turn to the right specialist, and lets operators choose different providers or models for routing, planning, discovery, documentation lookup, and execution.
Task Context Envelopes keep delegation explicit and compact. Domain Packs are optional, lightweight context packs for project or professional knowledge; trace and doctor commands are troubleshooting tools for validating domain setup after the fact.
## When To Use This
Use Your Legion when:
- You want OpenCode to route work across specialists more consistently.
- You want a simple per-agent provider/model map instead of a role-play agent team.
- You have project or domain knowledge that agents should use selectively.
- You want troubleshooting evidence when a domain-enabled task did not use the expected context.
- You want to compare native OpenCode execution against an orchestrated multi-agent path.
It is not a standalone agent platform or a public domain-pack ecosystem. The goal is a lightweight plugin that improves OpenCode's multi-agent workflow.
## Quick Start
There are two ways to run the CLI:
- **No global install:** use `bunx @whchi/your-legion `. This is the recommended copy-paste form in these docs.
- **Global install:** after `bun install -g @whchi/your-legion`, you may use `your-legion ` directly.
If you have not installed the package globally, commands like `your-legion install` will not exist in your shell.
Install the plugin and restart OpenCode:
```bash
bunx @whchi/your-legion install
```
The installer registers the plugin, writes `~/.config/opencode/legionaries.yaml`, and materializes enabled bundled domain packs under `~/.config/opencode/your-legion/domains/`. The first install enables and writes `coding` by default.
Open `~/.config/opencode/legionaries.yaml` first when tuning the system. The installed model map is the main DX surface: use a reliable model for `orchestrator`, stronger reasoning for `planner`, a coding-capable model for `builder`, and cheaper or reference-oriented models for `explorer` and `librarian`.
After restart, try a small routing check:
```text
Explore where Your Legion builds the runtime agent config.
```
The `orchestrator` should route repo discovery requests to `explorer`. For a clear code change, ask for the change directly; the orchestrator should route execution to `builder`, and `builder` should gather the needed repo context itself.
Use these docs next:
- Install and uninstall details: [`INSTALLATION.md`](./docs/INSTALLATION.md)
- Config schema and field rules: [`CONFIGURATION.md`](./docs/CONFIGURATION.md)
- Domain Pack authoring guide: [`DOMAIN_PACK_AUTHORING.md`](./docs/DOMAIN_PACK_AUTHORING.md)
- Domain observability and validation: [`DOMAIN_OBSERVABILITY.md`](./docs/DOMAIN_OBSERVABILITY.md)
- Orchestrator token benchmark: [`ORCHESTRATOR_BENCHMARK.md`](./docs/ORCHESTRATOR_BENCHMARK.md)
- Copy-paste examples: [`EXAMPLES.md`](./docs/EXAMPLES.md)
- Development notes: [`DEVELOPMENT.md`](./docs/DEVELOPMENT.md)
- Academic references behind the domain/runtime design: [`academic-papers-summary.md`](./docs/academic-papers-summary.md)
## Install
Run the installer without a global install:
```bash
bunx @whchi/your-legion install
```
Or install the CLI globally first:
```bash
bun install -g @whchi/your-legion
your-legion install
```
On first install, the installer enables `coding` by default and writes the bundled `coding` domain pack to `~/.config/opencode/your-legion/domains/coding/`. On reinstall, `install` preserves the existing `legionaries.yaml`, refreshes plugin registration, and materializes any enabled bundled domain pack that is still missing from the global domains directory.
To replace the enabled domain list with all bundled domains:
```bash
bunx @whchi/your-legion install --domains coding,marketing,finance,accounting
```
To add domains without removing existing enabled domains:
```bash
bunx @whchi/your-legion install --add-domains marketing,finance
```
For full setup, manual install, config paths, backups, and uninstall instructions, see [`INSTALLATION.md`](./docs/INSTALLATION.md).
## Configuration
Model mapping, provider selection, reasoning settings, custom-agent enablement, and domain pack enablement are configured in the installed global `~/.config/opencode/legionaries.yaml`. The repo [`legionaries.yaml`](./legionaries.yaml) is the installer template and development fixture. See [`CONFIGURATION.md`](./docs/CONFIGURATION.md) for the full schema and examples.
Minimal usable config:
```yaml
system_agents:
orchestrator:
model: openai/gpt-5.5
explorer:
model: openai/gpt-5.5
librarian:
model: openai/gpt-5.5
planner:
model: openai/gpt-5.5
builder:
model: openai/gpt-5.5
custom_agents: {}
domains:
coding: true
```
Domain packs live under your global OpenCode config:
```text
~/.config/opencode/your-legion/domains/{domain-id}/
├── DOMAIN.md # domain description used in the Domain Catalog
├── workflows/ # optional repeatable procedures
├── decisions/ # optional guardrails and constraints
├── examples/ # optional examples and output patterns
└── skills/ # optional domain-local skill instructions
```
These component folders are optional. A domain should contain the facets that carry real knowledge, not empty folders created for symmetry.
`DOMAIN.md` is the only domain description contract used for routing and component discovery.
Runtime component discovery also comes from `DOMAIN.md`: list domain-root relative paths such as `workflows/campaign-planning.md` or `skills/campaign-brief/SKILL.md`. If a folder or path is not listed in `DOMAIN.md`, it is treated as absent.
Enable a domain pack with:
```yaml
domains:
coding: true
marketing: true
finance: true
accounting: true
```
## Agents
- `orchestrator`: default primary router; clarifies intent, delegates, and reports back without repo exploration
- `planner`: design doc and implementation plan writer with docs-only edit permissions
- `builder`: execution specialist for approved work, including code, tests, UI work, analysis, copy, structured reviews, and code-coupled docs
- `explorer`: read-only known repo/local-file discovery specialist
- `librarian`: read-only third-party documentation and API reference specialist; prefers Context7 MCP for library docs
- `code-reviewer`: bundled YAML custom agent example for read-only review
Custom agent definitions are discovered from bundled package examples and from the active worktree's `src/custom-agents/` directory. Enable one by adding a matching `custom_agents` model entry in the global `legionaries.yaml`.
Domain descriptions and skills are injected into agent prompts as a Domain Catalog with namespaced entries such as `marketing/campaign-brief`. Routing agents pass relevant `Domain refs` and `Domain skills` in the Task Context Envelope; target specialists read the exact configured paths. Your Legion does not register domain skills as top-level harness skills.
Delegations use a compact Task Context Envelope with `Objective`, `Active domains`, `Domain refs`, `Domain skills`, `Context refs`, `Constraints`, `Expected output`, and `Verification`. The orchestrator compares the task with the Domain Catalog and activates every domain whose description materially applies. If no domain is configured or no domain description clearly matches, it should use no-domain delegation: `Active domains: none`, `Domain refs: none`, and `Domain skills: none`.
Your Legion records warn-only domain usage evidence under `~/.config/opencode/your-legion/traces/`. When troubleshooting domain setup, use `bunx @whchi/your-legion doctor --worktree .` for static domain catalog validation, runtime trace validation, and domain usage stats. Use `bunx @whchi/your-legion trace` when you need raw delegation and domain-read events. See [`DOMAIN_OBSERVABILITY.md`](./docs/DOMAIN_OBSERVABILITY.md) for the full validation workflow.
> **NOTICE:** In Your Legion CLI commands, `--worktree` means the OpenCode workspace/project path used to key trace evidence. It does not require a Git worktree.
For a fixed domain-routing smoke test, run `bunx @whchi/your-legion domain-scenarios`, ask the printed prompts in OpenCode, then run `bunx @whchi/your-legion doctor --worktree . --scenarios`. The fixed set covers coding, marketing, finance, accounting, and their mixed-domain pairs.
The paper references behind description-driven domain selection and trace-based runtime evidence are summarized in [`academic-papers-summary.md`](./docs/academic-papers-summary.md).
The bundled domains are `coding`, `marketing`, `finance`, and `accounting`. `coding` is enabled by default on first install. Enabled bundled domains are copied into the global domains directory when their `DOMAIN.md` is missing; existing global domain folders with `DOMAIN.md` are preserved. Use `--add-domains` to add domains on reinstall, `--domains` to replace the enabled list, or edit `legionaries.yaml` directly.
For hands-on examples of custom agents, marketing domain packs, mixed coding plus marketing work, and domain overrides, see [`EXAMPLES.md`](./docs/EXAMPLES.md).
## Routing Model
Your Legion uses direct specialist routing.
- The `orchestrator` classifies each turn into one dominant intent and chooses a concrete subagent.
- Those intents are routing heuristics, not runtime categories or model profiles.
- Multi-step work goes through `planner` first when sequencing is unclear, then `builder` executes approved work.
- Code review is owned by the `/code-review` command by default; the bundled `code-reviewer` custom agent is available for explicit advanced workflows.
- Global `legionaries.yaml` controls model and reasoning settings per agent, plus which domain packs are available. It does not control primary specialist routing.
## Commands
- `bunx @whchi/your-legion install [--domains ] [--add-domains ]`: installs or refreshes the plugin registration. First install writes `legionaries.yaml` with `coding` enabled and materializes enabled bundled domain packs under `~/.config/opencode/your-legion/domains/`. Reinstall without domain flags preserves existing config. `--domains` replaces the enabled domain list; `--add-domains` merges into it.
- `bunx @whchi/your-legion create-domain [--components workflows,decisions,examples,skills] [--enable]`: scaffolds a new global domain pack. By default it creates only `DOMAIN.md`; use `--components` to add selected optional folders and matching placeholder files, and `--enable` to write the domain into `legionaries.yaml`. Existing global domains and bundled domain ids are rejected.
- `bunx @whchi/your-legion doctor [--worktree ] [--scenarios]`: troubleshoots domain setup. By default it validates `DOMAIN.md` declarations, runtime trace evidence, and usage stats; `--scenarios` also verifies the fixed scenario set.
- `bunx @whchi/your-legion trace [--worktree ] [--limit ]`: prints recent domain usage evidence for a workspace/project path.
- `bunx @whchi/your-legion trace-check [--worktree ]`: low-level trace validation for contract warnings and declared domain refs or skills that were not read.
- `bunx @whchi/your-legion domain-scenarios`: prints the fixed domain scenario prompts.
- `bunx @whchi/your-legion domain-scenario-check [--worktree ]`: low-level fixed scenario validation; `doctor --scenarios` is the preferred entrypoint.
## Development
Development and contribution notes live in [`DEVELOPMENT.md`](./docs/DEVELOPMENT.md).