Armada: Turn Any Repository Into a Self-Organizing AI Engineering Team

By Prahlad Menon Published 2026-08-11 4 min read

Why use one coding agent when your repository can have an entire AI engineering team?

Armada turns any code repository into a self-organizing team of eight AI specialists. Instead of relying on a single bot that might mess up your work, this system sets up distinct roles for backend coding, frontend design, security auditing, and quality testing.

The Problem With Solo AI Agents

AI coding agents are fast. They’re also:

Unsupervised — “Build the login page” becomes a framework choice, auth strategy, and color palette decided without you
Unverified — The same agent that wrote the bug declares it fixed (no maker/checker split)
Amnesiac — Kill the terminal, lose the context
Boundaryless — A solo agent rewrites your CI config while fixing a CSS bug
Destructive — Direct edits on your active branch, parallel tasks collide

These aren’t model failures. They’re environment failures.

Loop Engineering

Armada implements loop engineering — replacing one-shot prompting with control loops that prompt agents for you.

contract → dispatch → build → test → review → PR
    ↑                                         |
    └──── evidence gates every transition ────┘

You write the contract (what to build and how to know it works). The fleet runs the loop until a reviewed Pull Request lands in your repo.

The Eight Specialists

Role	Codename	What It Does
You	Admiral	Sets the mission, signs the contract, merges the PR
Orchestrator	Commodore	Co-writes contract, dispatches specialists, gates evidence
Backend	Galleon	Server logic, APIs, databases, backend tests
Frontend	Clipper	UI, styling, responsive pages, client tests
QA	Corvette	E2E tests, screenshots, owns the defect ledger
Adversary	Xebec	Hostile review — hunts edge cases, vulns, UI flaws
Security	Frigate	Auth, permissions, data leaks, dependency audit
Docs	Caravel	READMEs, API docs, changelogs, user manuals
Architect	Bark	Code review, refactoring risk, pattern compliance (read-only)

Boundaries are enforced by SDK permissions, not prompt politeness. The Commodore cannot edit source code. Security, adversary, and architect can only write their own review artifacts.

Why This Works

Maker/checker split — Developers write code. QA and the adversary check it. A maker never passes its own work.

Parallel phases — Independent phases dispatch simultaneously as background subagents with disjoint file scope. Only phases that depend on each other serialize.

Evidence, not reports — Every gate requires proof you can read: a passing test run, a screenshot, a file:line citation. Nothing advances on “trust me.”

Crash-proof state — Every transition writes to disk. Kill the session, reopen, and the loop continues where it left off.

Isolated Feature Voyages

Each feature runs in its own Git worktree (sandbox). Multiple features run simultaneously without colliding:

armada voyage auth-system   # boots a lane for feature "auth-system"
armada voyage dashboard     # boots another lane — runs in parallel
armada fleet                # dashboard: one row per active lane

Features in separate worktrees cannot collide. main stays pristine. Every voyage ends in a PR, never a local merge.

Quick Start

# Install globally
npm install -g @rafamacalaba/armada

# Existing repo — detects your stack, scaffolds the team
cd your-repo && armada init

# New project — questionnaire, scaffold, ready to ship
armada new my-app && cd my-app

# Zero-install trial
npx @rafamacalaba/armada@latest new my-app

Requires Node.js 22+ and an authenticated opencode install.

Real Results

Armada uses itself — the fleet builds Armada’s own features:

Built the session-based state system in ~26 minutes at a cost of $0.18, fully autonomously
Surfaced a real permission deadlock the fleet asked about instead of silently failing
QA caught and self-corrected 3 test failures the developers introduced

Every feature Armada ships was built by Armada.

Save 20x on OpenRouter

Route to discounted providers (Novita, StreamLake, Xiaomi):

# Check live prices and savings
armada models --discounts

# Init with preferred provider
armada init --openrouter-provider Novita

Project Structure

your-repo/
├── opencode.json
├── AGENTS.md
├── armada/
│   ├── armada.yaml           # manifest: re-runnable source of truth
│   ├── REQUIREMENTS.md       # contract: phases + success criteria
│   ├── state/                # restart-proof loop memory
│   ├── ledgers/<feature>/    # DEFECTS.md, reviews, findings
│   ├── e2e/<feature>/        # per-feature E2E evidence
│   └── screenshots/<feature>/ # per-feature visual evidence
└── .opencode/
    ├── agent/                # 8 native agents with SDK-enforced permissions
    └── commands/             # /voyage, /patrol, /fleet, /status

Why This Matters

The current AI coding paradigm is “one smart agent, fingers crossed.” Armada flips this to “specialized team, verified handoffs, evidence-gated delivery.”

It’s the difference between a solo contractor and a proper engineering org — with all the checks and balances that implies.

Links: