Mugiwara

Your agent writes the code. Mugiwara proves it.

A governed engineering crew for your AI agent — evidence at every step, and a process that sizes itself to the work. A typo costs nothing. An auth migration gets all nine flow stages. No runtime, no API keys, no servers. Just markdown your agent already knows how to read.

Works on Claude Code, opencode, Copilot, Gemini, and 8 more platforms.

Why this exists

AI agents are fast. They're also unverified. No audit trail. No review. No "who checked this?" when something breaks. Mugiwara wraps your agent in a team structure with role boundaries, evidence gates, and cost tracking — the same discipline you'd expect from a senior engineering team. Zero runtime overhead: every agent, every skill, every rule is static markdown.

→ Full pitch: why mugiwara vs just asking your agent

See the evidence

A closed mission leaves a report you can actually read. This is the exact format mugiwara run mission-report.sh produces:

# Mission: invitation-accepted-flow . 2026-08-11

**Lane** full . **Mode** guided . **Actor** john . **Branch** feature/MKR-412

## What changed

11 files, +340 LOC
Sensitive paths: src/auth/

## Flow stages

| Flow stage | Artifact | Verdict |
|------|----------|---------|
| Execute (Flow 3) | `01-execution.md` | PASS |
| Checkpoint (Flow 4) | `02-audit.md` | PASS |
| Quality (Flow 5) | `03-quality.md` | PASS |
| Gates (Flow 6) | `04-gates.md` | PASS |
| Healing (Flow 8) | `05-healing.md` | PASS |
| Closure (Flow 9) | `06-closure.md` | GO |

## Review & blockers

Review + security files: invitation-accepted-flow-review.md, invitation-accepted-flow-security.md
Findings: 3
Blocker ledger rows: 1

## State

| Field | Value |
|-------|-------|
| Flow stage | 9 |
| Tasks | 6/6 done |
| Blockers open | 0 |
| Heal cycles | 1 |
| Tokens used | 14,200 / 20,000 |

Lanes

Work is sized to the diff — a typo gets no pipeline, an auth migration gets all nine flow stages. Mugiwara itself is free; token usage depends on the lane:

Usage tracked in .mugiwara/state/<mission>/[member].json per mission. Budget warns at 1.5×, pauses at 3×. Lane bases are measured from the skills/agents loaded per lane by scripts/lane-base.ts — the constants fail CI if they drift from content load.

→ Full cost model

30-second try

# opencode — add to opencode.json, then restart
{ "plugin": ["@ionivetech/mugiwara"] }

# Claude Code
/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara

# Any platform via npm
npx @ionivetech/mugiwara@latest install --target all --yes

First run: run mugiwara onboard in your terminal for guided setup (zero-LLM wizard). Then ask something non-trivial:

> add role-based access control: admin, editor, viewer
> audit the auth middleware for security gaps
> review the last PR for breaking changes
> split this feature across the team: payment gateway, ledger, fraud

A Standard lane mission (~13k tokens) produces a branch with test-first commits, an audit report, a security review, and a ready PR summary — visible at every step in your chat.

You ask. The crew routes automatically. No agent names to memorize, no pipeline config to write.

• Full pipeline when the task is big or direction is unclear
• Direct agent when you know exactly what you need — say the name
• Slash commands when you want to drive: /mugiwara-plan, /mugiwara-review, /mugiwara-security, /mugiwara-ship, /mugiwara onboard

→ Full walkthrough · Full workflow walkthrough

What Mugiwara does

All features

→ All 28 features, with how-to-use + scenarios: Every feature · Team collaboration · Full pipeline · Lanes · Modes · Config · Audit trail · Cost

The pipeline

flowchart TB
    L0["Luffy - Triage"] --> L1["Usopp - Brainstorm"] --> L2["Nami - Plan"] --> L3["Zoro - Execute"] --> L4["Chopper - Audit"]
    L4 --> L5["Sanji - Quality"] --> L6["Franky - Gates"]
    L6 --> L7R["Robin - Review"]
    L6 --> L7J["Jinbe - Security"]
    L7R --> L8["Brook - Heal"]
    L7J --> L8
    L8 --> L9["Luffy - Closure"]
    L8 -. "heal ≤3 cycles" .-> L4

→ Full pipeline details

The crew

11 agents (+3 internal). Each has role boundaries — auditors and reviewers are read-only. Call them by name or let the pipeline auto-route.

Internal agents (dispatch-only):

→ Agent details: summoning, boundaries, parameters

Team collaboration

Mugiwara is built for a team sharing one repo. Identity is (mission, member), never branch — so any number of engineers can run parallel work without colliding, and one engineer can juggle several missions.

.mugiwara/
├── state/<mission>/state.json        # solo state
├── state/<mission>/<member>.json     # your team member state
├── continue/<mission>/state.json     # solo resume point
├── continue/<mission>/<member>.json  # your resume point
└── plans/<mission>.md                # ONE shared plan (source of truth)

Quick start for a team:

# Nami writes one plan with a ## Sub-missions table (assignee + branch per member)
/mugiwara-plan                          # guided/semi asks "Solo or team?"

# Each member works on their own branch, resume only their own work
/mugiwara continue                      # list every in-flight mission for YOU
/mugiwara continue payment-gateway      # solo → resume; team → list members
/mugiwara continue payment-gateway patty # resume exactly patty's work

# Coordination radar
mugiwara initiative status plans/<mission>.md          # who's where
mugiwara initiative conflict-check plans/<mission>.md  # shared-file overlap
# In an installed project: read the sub-mission table in the plan doc, and
# `mugiwara status` for computed per-mission position.

Auto mode runs every flow stage autonomously — and never downgrades to guided mid-mission. In a team plan, auto covers your member scope only: resuming your sub-mission runs it to ship, never the other members'.

→ Full collaboration guide with a worked example · Multi-actor reference

When not to use Mugiwara

• Prototyping or spikes — use Lane 4, or skip mugiwara entirely.
• Unattended multi-hour runs — the crew runs inline so you can interrupt it. If you want to walk away, superpowers' subagent-driven-development is built for that.
• Solo scripts with no review path — the audit trail has no audience.
• Harnesses without agent dispatch (Gemini, Codex, tier 3) — you get the workflow and the trail, not enforced role boundaries.

Configuration

Switch mode any time: /mugiwara guided | semi | auto. Or edit .mugiwara/config:

Set via mugiwara onboard or edit directly. Unknown keys ignored. Project config (.mugiwara/config) overrides global (~/.mugiwara/config).

How much does the crew ask you?

In auto, the crew runs every flow stage autonomously — triage, plan, execute, quality, gates, review, heal, closure — and never downgrades to guided mid-mission. Only a genuine blocker or the heal halt pauses.

→ All config keys · Mode details

Quick reference

Install

/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara

{ "plugin": ["@ionivetech/mugiwara"] }

gemini extensions install https://github.com/ionivetech/mugiwara

codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara

copilot plugin install https://github.com/ionivetech/mugiwara

/add-plugin mugiwara

agy plugin install https://github.com/ionivetech/mugiwara

/plugins install https://github.com/ionivetech/mugiwara

pi install git:github.com/ionivetech/mugiwara

npx @ionivetech/mugiwara@latest install --target <id> --yes

npm i -g @ionivetech/mugiwara
mugiwara install --target all --yes

All platforms get the full crew — 11 agents (+3 internal), 26 skills. Enforcement depth varies by harness; see the harness matrix.

→ How the skills stay small: three-layer disclosure

→ Per-platform guides

Update

# opencode — clear the pinned cache, then reinstall (npm update alone does NOT work)
rm -rf ~/.cache/opencode/packages/@ionivetech/mugiwara* && opencode plugin @ionivetech/mugiwara -g

# Claude Code — marketplace
/plugin update mugiwara

# CLI — npm global
npm i -g @ionivetech/mugiwara@latest

OpenCode pins the resolved version in its own package cache, so npm update never touches it. Reinstall with the same command for GitHub-based plugins (Gemini, Codex, Copilot, Cursor, Kimi, Pi, Antigravity).

→ Per-platform guides

CLI

mugiwara install                              # wizard (interactive)
mugiwara install --target all --yes           # non-interactive
mugiwara update --target <id> --yes           # overwrite to latest
mugiwara uninstall                            # remove installed files
mugiwara list                                 # show installations
mugiwara list --check                         # health check
mugiwara reset --keep-logs                    # wipe state, keep lessons

Docs

Start here: Getting started · What mugiwara replaces

Concepts: Workflow · Lanes · Modes · Execution model · Git strategy · Config · Cost · Audit trail · Security

Crew: Agents · Skills

Reference: Agent anatomy · Skill anatomy · Harness matrix · Compliance matrix · Developer onboarding

Install per platform: Overview · Claude · opencode · Gemini · Codex · Copilot · CLI targets

Troubleshooting: Common problems

Roadmap: ROADMAP.md

What is measured, and what is not

Numbers here are produced by bun run gate. Nothing in this table is an estimate.

License

MIT. Copyright (c) 2026 ionivetech.