Skip to content

Back to the catalog

Armada
github.comrepo

Armada

Armada is a CLI tool (npm package @rafamacalaba/armada) that turns a repository into a multi-agent "fleet" of 8 specialist AI roles (developer, QA, security, adversary, architect, Commodore orchestrator, etc.) built on opencode. It implements "loop engineering": a contract-driven control loop (contract → dispatch → build → test → review → PR) with maker/checker separation, parallel phase dispatch in isolated git worktrees, evidence-gated transitions, and crash-proof on-disk state, aiming to replace unsupervised one-shot agent prompting with a verified, resumable workflow that lands a reviewed PR.

TL;DR A CLI that orchestrates 8 specialist AI agents through an evidence-gated build/test/review loop to autonomously ship reviewed PRs.
Open original ↗
Document

How to use it

Install globally and scaffold into an existing repo or a new project:

npm install -g @rafamacalaba/armada
cd your-repo && armada init          # detects stack, scaffolds team in place
armada new my-app && cd my-app       # new project via questionnaire
npx @rafamacalaba/armada@latest new my-app   # zero-install trial

Requires Node.js 22+ and an authenticated opencode install; run armada doctor to verify the environment. After armada init you open the repo in opencode, describe the goal in plain language, and the Commodore interviews you to produce armada/REQUIREMENTS.md (phases, dependencies, measurable success criteria) before the loop runs autonomously.

Each feature runs in its own Git worktree via armada voyage <name>; armada fleet gives a dashboard with one row per lane. main stays untouched and every voyage ends in a PR, never a local merge. Slash commands /voyage, /patrol, /fleet, /status are available inside opencode. Re-scaffold from the manifest with armada init --from-armada armada/armada.yaml --restart; init never clobbers an existing opencode.json or AGENTS.md.

Cost lever the summary omits: OpenRouter routing to discounted providers (Novita, StreamLake, Xiaomi) for claimed savings up to 20x. Inspect with armada models --discounts; pin one with armada init --openrouter-provider Novita.

How it works

One detail beyond the summary's "maker/checker" framing: boundaries are enforced by SDK permissions, not prompts. The Commodore cannot edit source at all; security, adversary, and architect roles can only write their own review artifacts (DEFECTS.md, ADVERSARIAL_REVIEW.md, SECURITY_FINDINGS.md under armada/ledgers/<feature>/). State lives in armada/state/ for crash recovery.

Evidence

The only concrete numbers are self-referential (armada builds itself through its own loop): the fleet built armada's session-based state system in ~26 minutes at $0.18, fully autonomous, from blank contract to passing tests. It surfaced a real permission deadlock (Commodore's deny-all-edit rule conflicting with a state-write) and QA caught 3 developer-introduced test failures that the gate looped back and got fixed.

Limits

Numbers are anecdotal dogfooding, not a benchmark — no comparison against one-shot prompting or other agent frameworks despite the "Why armada?" framing. Hard dependency on opencode and OpenRouter/Node 22+ means it is not a standalone tool. Licence is MIT.

Organisations named here

  • Novita
  • StreamLake
  • Xiaomi
  • opencode
  • OpenRouter

Technologies named here

  • armada
  • OpenCode
  • OpenRouter
  • npm
  • Node.js
  • Git worktrees

Techniques named here

  • Loop engineering
  • Maker/checker split
  • Parallel phase dispatch
  • Evidence gating
  • Crash-proof state
  • Per-feature Git worktree isolation

Related in coding-agents