Your Legion

An OpenCode plugin for multi-agent work you can audit. Most multi-agent setups let the agent that did the work also declare it done; Your Legion separates the maker (builder) from the checker (verifier), records what each delegation declared and what was actually read as trace events, and turns that evidence into pass/fail diagnostics.

The verification core is a completion ledger. A maker that changed files must report a Verification status block, an unverified claim routes through an independent verifier pass, and trace-check fails a run whose ledger says unverified file changes were shipped without one:

- Verification status:
  - Files changed: yes
  - Verifier pass: not-run
  - Status: unverified
  - Reason: test runner unavailable in this environment

$ bunx @whchi/your-legion trace-check --worktree .
verification-report [unverified-file-changes]: maker reported file changes with status unverified and no verifier delegation followed

The per-agent provider/model map serves the same goal: the checker can run on a different model than the maker, so they do not share correlated blind spots (doctor warns when a loop's maker and verifier resolve to the same model).

Around that core, Your Legion keeps OpenCode as the execution harness and adds a small protected specialist set with per-agent provider/model mapping, Task Context Envelopes for explicit compact delegation, Domain Packs for selective expert context, and Legion Loops for recurring maker/checker workflows with durable inboxes. The benchmark protocol is deliberately allowed to conclude that orchestration was not worth it — and the committed 2026-07-04 measured run says exactly that for small tasks (same-provider orchestration was +85–146% tokens for no quality gain; a cheaper mixed-provider map matched native cost once); see ORCHESTRATOR_BENCHMARK.md.

When To Use This

Use Your Legion when:

• You want completion claims backed by a maker/checker ledger and trace evidence, not self-reporting.
• You want the checker on a different provider or model than the maker.
• You want troubleshooting evidence when a domain-enabled task did not use the expected context.
• You want recurring engineering loops with explicit state, maker/checker separation, and diagnostics.
• You have project or domain knowledge that agents should use selectively.
• You want OpenCode to route work across specialists more consistently.
• You want to compare native OpenCode execution against an orchestrated multi-agent path, with the comparison allowed to go either way.

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.

Then check the evidence trail instead of taking the transcript's word for it:

bunx @whchi/your-legion doctor --worktree .
bunx @whchi/your-legion trace-check --worktree .

doctor validates domain declarations, loop catalogs, and runtime trace evidence, and prints usage stats. trace-check fails when a maker reported unverified file changes and no verifier pass followed.

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
• Legion Loop guide: LEGION_LOOPS.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
• Essay influences behind loops and Domain Packs: design-influences.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
  verifier:
    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
• verifier: read-only checker for loop completion claims, maker/checker separation, tests, and evidence
• 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 Scenario, Loop, Loop run, Loop status, Objective, Active domains, Domain refs, Domain skills, Context refs, Constraints, Expected output, Verification, Completion claim, Verification commands, and Verification outcome. The orchestrator uses loop context only for explicit loop runs, compares the task with the Domain Catalog, then passes only the selected loop id, run id, and domain evidence. If no loop applies, it writes Loop: none. 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.

Loop invocation is explicit-only. Use loop-prompt <loop-id> or name a configured loop id for deliberate runs. The orchestrator should not set Loop from task intent, topic, similarity, or the Loop Catalog alone; all other requests use Loop: 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 along two orthogonal axes: agents are work-mode boundaries (how to work — route, plan, build, verify, explore, look up docs), and Domain skills are capability boundaries (what expertise the work needs — coding, marketing, finance, and so on). Agents stay domain-neutral; professional capability is injected as Domain skills, never baked into an agent. Add new expertise as a Domain Pack; reserve new agents for genuinely new work modes.

• 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 [--config-dir <path>] [--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> [--config-dir <path>] [--components workflows,decisions,examples,skills] [--enable]: scaffolds a new global domain pack with DOMAIN.md and updates.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 domain-update <domain-id> --type <decision|correction|workflow|verification|reusable> --title <text> [--config-dir <path>] [--promote-to <path>]: appends a pending reusable knowledge candidate from stdin to the domain's updates.md.
• bunx @whchi/your-legion create-loop <loop-id> [--preset <id>] [--worktree <path>] [--config-dir <path>] [--description <text>] [--objective <text>] [--verification <commands>]: creates a configured Legion Loop and repo-local inbox.
• bunx @whchi/your-legion loops [--config-dir <path>]: lists configured Legion Loops.
• bunx @whchi/your-legion loop-presets: lists quick-start templates such as ci-triage, issue-triage, docs-refresh, and release-check.
• bunx @whchi/your-legion loop-prompt <loop-id> [--worktree <path>] [--config-dir <path>] [--run-id <id>]: generates a ready Task Context Envelope for a loop run.
• bunx @whchi/your-legion loop-runs [--worktree <path>] [--config-dir <path>] [--loop <loop-id>]: groups loop run completion ledger evidence from trace events.
• bunx @whchi/your-legion doctor [--worktree <path>] [--config-dir <path>] [--scenarios]: troubleshoots domain and loop setup. By default it validates DOMAIN.md declarations, loop catalogs, runtime trace evidence, and usage stats; --scenarios verifies the fixed domain scenario set.
• bunx @whchi/your-legion trace [--worktree <path>] [--config-dir <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>] [--config-dir <path>] [--require-evidence]: low-level trace validation for contract warnings, declared domain refs or skills that were not read, and maker/checker ledger integrity (unverified file changes without a following verifier pass fail). --require-evidence additionally fails when no delegation or loop-run-report evidence exists at all.
• bunx @whchi/your-legion routing-contract-eval --fixtures <path> [--config <path>]: evaluates labeled orchestrator envelopes offline against the domain contract and expected agent/loop/domain fields.
• bunx @whchi/your-legion checker-recall-eval --fixtures <path>: scores isolated verifier decisions over planted-defect and clean maker-output fixtures.
• bunx @whchi/your-legion benchmark-summarize --metrics <path>: summarizes an exported benchmark metrics file with cost/time economics first, k≥5 repetition statistics, and token detail second. See ORCHESTRATOR_BENCHMARK.md.
• bunx @whchi/your-legion domain-scenarios: prints the fixed domain scenario prompts.
• bunx @whchi/your-legion domain-scenario-check [--worktree <path>] [--config-dir <path>]: low-level fixed scenario validation; doctor --scenarios is the preferred entrypoint.

Development

Development and contribution notes live in DEVELOPMENT.md.