legioni

A team of AI coding agents that coordinates your work and learns from every task.

Requires opencode.

How you use it

# one-time install (needed for promote, install, upgrade-team)
npm install -g legioni

cd your-project
legioni init        # detects stack, compiles agents

Or without installing anything:

cd your-project
npx legioni init

Then start opencode and type your task:

opencode
@orchestrator add a truncate(text, max_len, suffix='...') function with tests

That's it. The orchestrator plans the work, delegates to specialist agents, and loops until tests pass. You watch.

orchestrator  →  architect     →  plan.md
              →  implementer   →  code + tests
              →  reviewer      →  passes or fails
              →  test-strategist → edge cases + full suite
              ←  done: code is written, tested, and reviewed

After the session, the agents propose lessons from what they learned:

legioni promote    # review each lesson, approve or reject
legioni install    # recompile agents with the approved lessons

Next task, those lessons are active. The team gets better each time.

Tested on real projects

| Project | Language | Tests | What happened | |---|---|---|---| | Apache Commons Compress | Java / Maven | 1890 | All pass, reviewer ran real mvn test | | Apache Commons Text | Java / Maven | 1890 | All pass, orchestrator fixed corrupted existing code, reviewer verified | | truncate function | Python / pytest | 13 | Architect's spec had arithmetic errors, reviewer caught them, implementer fixed | | slugify + Unicode | Python / pytest | 50 | Implementer missed Nordic letters, reviewer failed it, implementer fixed on cycle 2. Lesson promoted. Next project, caught on first pass. |

What it looks like

$ legioni init
Running project recon ... done
  → .legioni/project.md
Compiling team → opencode agents ... done
  → ~/.config/opencode/agent/architect.md
  → ~/.config/opencode/agent/implementer.md
  → ~/.config/opencode/agent/orchestrator.md
  → ~/.config/opencode/agent/reviewer.md
  → ~/.config/opencode/agent/test-strategist.md
  → ~/.config/opencode/agent/db-expert.md
legioni init complete.

On a real project, recon detects your stack:

# .legioni/project.md (auto-generated)
## Stack
- Language: Java
- Framework: Maven

## Commands
- Build: `mvn compile`
- Test: `mvn test`
- Targeted test: `mvn test -Dtest=<TestClass>`

After a session, agents stage lesson candidates:

$ legioni promote
Reading staged lessons from .legioni/lessons.staging.*.md ...

────────────────────────────────────────────────────────────
Role: reviewer   Slug: [nordic-char-limitation-in-nfkd]
────────────────────────────────────────────────────────────
Situation: Reviewing a Unicode normalization implementation
that used pure NFKD + ASCII encoding.
Decision: Flagged as failure because ø, Ø, æ, Æ have no
NFKD decomposition — they get dropped entirely.
Why: A manual transliteration table is needed before NFKD.
────────────────────────────────────────────────────────────
Promote? [y/n/q] y
  → Promoted to ~/.legioni/lessons/reviewer/[nordic-...].md

────────────────────────────────────────────────────────────
Role: orchestrator   Slug: [task-brief-precision]
────────────────────────────────────────────────────────────
Situation: The codebase had no Hex class — the complete
class had to be created from scratch.
Decision: Wrote a detailed task brief with acceptance
criteria covering null handling and hex alphabet.
────────────────────────────────────────────────────────────
Promote? [y/n/q] n

Commands

| Command | What it does | |---|---| | legioni init | Setup. Scaffolds team store, picks provider, detects stack, compiles agents. | | legioni install | Recompile agents after promoting lessons or changing config. | | legioni update | Re-detect stack and recompile. Use when the project changed. | | legioni promote | Review staged lesson candidates interactively. | | legioni upgrade-team | Diff defaults against your team store and upgrade changed roles. | | legioni config set-provider | Change model provider (interactive menu). | | legioni config set-model <role> <model> | Override the model for one role. Run legioni install after. | | legioni config list | Show current provider and model assignments. |

How it works

Legioni is a compile-time tool: it reads your config, resolves models, and writes the final agent files that opencode uses. OpenCode never reads ~/.legioni/config.json directly — it only reads the compiled agent files in ~/.config/opencode/agents/.

1. legioni init copies role definitions into ~/.legioni/roles/. The store is portable across machines.
2. legioni install reads each role, appends promoted lessons, applies model overrides, writes agent files to ~/.config/opencode/agents/. Always run this after any config change, otherwise subagents keep using stale models.
3. legioni config set-provider changes the provider and runs install automatically. legioni config set-model does not — you must run legioni install yourself.
4. If you edit ~/.legioni/config.json by hand, run legioni install to apply the changes. Until you do, opencode sees the old models.
5. legioni init also detects your stack and writes .legioni/project.md, registered in opencode.json.
6. During a session, agents write workspace artifacts (plan, review, test results) and stage lesson candidates.
7. legioni promote lets you review and promote lessons. They get injected into agent prompts on next compile.
8. legioni upgrade-team syncs your store with newer defaults from legioni releases.

License

MIT