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 <command>. This is the recommended copy-paste form in these docs.
• Global install: after bun install -g @whchi/your-legion, you may use your-legion <command> 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:

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:

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
• Config schema and field rules: CONFIGURATION.md
• Domain Pack authoring guide: DOMAIN_PACK_AUTHORING.md
• Domain observability and validation: DOMAIN_OBSERVABILITY.md
• Orchestrator token benchmark: ORCHESTRATOR_BENCHMARK.md
• Copy-paste examples: EXAMPLES.md
• Development notes: DEVELOPMENT.md
• Academic references behind the domain/runtime design: academic-papers-summary.md

Install

Run the installer without a global install:

bunx @whchi/your-legion install

Or install the CLI globally first:

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:

bunx @whchi/your-legion install --domains coding,marketing,finance,accounting

To add domains without removing existing enabled domains:

bunx @whchi/your-legion install --add-domains marketing,finance

For full setup, manual install, config paths, backups, and uninstall instructions, see 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 is the installer template and development fixture. See CONFIGURATION.md for the full schema and examples.

Minimal usable config:

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:

~/.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:

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, or trace --summary for grouped delegation evidence. See 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.

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.

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 <ids>] [--add-domains <ids>]: 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 <domain-id> [--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 <path>] [--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 <path>] [--limit <n>] [--summary]: prints recent domain usage evidence for a workspace/project path; --summary groups declared refs, matching reads, and warnings by delegation.
• bunx @whchi/your-legion trace-check [--worktree <path>]: 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 <path>]: low-level fixed scenario validation; doctor --scenarios is the preferred entrypoint.

Development

Development and contribution notes live in DEVELOPMENT.md.