Mugiwara

Your agent writes the code. Mugiwara proves it.

A governed engineering crew for your AI agent — evidence at every step, a process that sizes itself to the work, and cost you can actually see. 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.

The problem

An AI agent can write 400 lines in five minutes. It says "tests pass" — and leaves nothing you can open, read, or attach to a PR. Review becomes a formality, and a formality is worse than no review, because it launders the change through a human name.

Mugiwara makes the work provable: every change carries a trail a human can review, and the process sizes itself to the work.

What you get back

Every mission closes with one file. This is what your reviewer reads:

# Mission: invitation-accepted-flow
2026-09-03 · farid · branch `feature/MKR-412` · lane **full** · mode guided

## Verdict
**GO** — all gates passed. 1 finding deferred with an owner.

## What changed
11 files, +340 / -82.
Sensitive paths touched: `src/auth/invitation.ts`, `migrations/004.sql`

## Gates
| Gate | Verdict | Evidence |
|---|---|---|
| Checkpoint (Flow 4) | PASS | `flows/04-audit.md` |
| Quality (Flow 5) | PASS | `flows/05-quality.md` |
| Coverage (Flow 6) | PASS | new 94% / modified 87% |
| Security (Flow 7) | PASS | STRIDE, 0 high -> `review/security.md` |

## Cost
Used **8,781** of 12,000 tokens (73%). Lane `lean`. 1 heal cycle.

Generated from fixture test/fixtures/report-sample.md — 2026-09-03.

The process fits the work

| Your change | Lane | What runs | |---|---|---| | Typo, one file | Direct | nothing — just fix it | | Small bug | Lean | execute -> quality | | A feature | Standard | plan -> execute -> audit -> quality -> review | | Touches auth/, payments/, migrations | Full | all 9 flow stages + security review | | Requirements still fuzzy | Spike | brainstorm first, then re-size |

The lane is computed from git diff — never guessed by the model — and it only ever rises. Once a mission touches a sensitive path it cannot drop back, even if that file is reverted.

What is Mugiwara? (30 seconds)

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 Straw Hat crew: a team of named roles (Luffy, Nami, Zoro, Chopper, …) that triages, plans, executes, audits, reviews, and heals your work — with a ruled pipeline, evidence at every gate, and a cost governor that keeps spend visible and bounded.

Three things it does for you:

| You get | Meaning | |---|---| | Evidence, not claims | Every flow stage re-runs checks and shows output. "Done" = proof. | | Process that sizes itself | A typo costs nothing. An auth migration gets the full pipeline. | | Visible cost | Per-lane budgets, a live slop governor, and a mugiwara cost ledger. |

It runs inline in your chat — you watch every step. No hidden subagents, no black box.

→ Why mugiwara vs just asking your agent

Quick start (5 minutes)

Add the plugin, then just ask something non-trivial:

# 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 writes .mugiwara/config with defaults. Then ask:

> 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

You ask. The crew routes automatically. No agent names to memorize, no pipeline config to write. 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 say | What happens | | ---------------------------------------------- | ------------------------------------------------------- | | add search bar to products page | Luffy triages → Nami plans → Zoro executes TDD → Chopper audits → Sanji quality → Franky gates → Robin reviews → pushed, PR summary ready | | split payment system: gateway, ledger, fraud | Nami writes one plan split into sub-missions, each with its own branch + done-criteria → each dev resumes only their own → all mergeable | | Brook, fix the failing login test | Healer reads the failure ledger, root-cause fixes, proves it ≤3 cycles | | Jinbe, audit auth middleware | STRIDE + OWASP + dependency audit. Read-only — never touches code |

→ Full walkthrough

How it works (the short version)

Four ideas explain almost everything:

1. The crew pipeline

A mission runs as flow stages, each owned by one crew member — triage → brainstorm → plan → execute → audit → quality → gates → review → heal → closure. Every stage reports a compact checkpoint you can read in your chat.

→ Full pipeline · The crew

2. Lanes — process sizes itself

Work is sized to the diff. A typo gets no pipeline; an auth migration gets all nine stages. Lanes: direct / lean / standard / full / spike.

| Lane | Flow stages | Typical tokens | Budget | | ---- | :---: | :---: | :---: | | Direct (typo) | 0 | ~0 | — | | Lean (small bug) | 2 | ~8k | 12k | | Standard (feature) | 5–7 | ~13k | 25k | | Full (architecture) | 9–11 | ~22k | 50k |

→ Lanes

3. Modes — how much you participate

guided (approve every step), semi (approve the plan, then auto), auto (full autonomy within your scope).

→ Modes

4. Cost Governor — what is safe to spend

Per-lane budgets, a live slop governor that flags wasted cost and attributes it to the crew member that caused it, and a mugiwara cost ledger.

→ Cost model

Adaptive execution

Three decisions stay independent: your control mode (how much you approve), the execution posture (how work runs — inline / parallel / context-relief / phase / team), and the Cost Governor (what is safe to spend). The crew picks the posture from evidence at each flow boundary; a Full-lane mission can be Guided and inline, a Lean mission can be Auto and sequential. Inline stays the default.

→ Adaptive execution

What Mugiwara does

| Feature | One line | |---|---| | Lane sizing | Work auto-sized from git diff — typo instant, auth full pipeline | | Evidence gates | Every flow stage re-runs checks with evidence; archive fails on missing | | Team split | One plan, per-(mission, member) state + resume, zero collisions | | Resume | Rebuilds from .mugiwara/ state — continues, never restarts | | 12 platforms | Claude, opencode, Copilot, Gemini, Codex, Cursor, Kimi, Pi, and 5 more |

→ All 29 features: Every feature

Team collaboration

Built for a team sharing one repo. Identity is (mission, member), never branch — so any number of engineers run parallel work without colliding.

/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
mugiwara status                         # computed per-mission position

Auto mode runs your member scope only — resuming your sub-mission runs it to ship, never the other members'.

→ 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.
• 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:

| Key | Default | What | |---|---|---| | mode | guided | guided / semi / auto | | branch | feature/{type}-{issue}-{slug} | Branch naming | | commit | conventional | conventional / gitmoji / plain / template | | auto_commit | on | off disables commit+push in guided/semi | | coverage_new | 85 | Coverage threshold for new files (%) | | coverage_modified | 90 | Coverage threshold for modified files (%) | | delegate_threshold | 60 | % of budget at which remaining tasks dispatch to workers | | heal_max_cycles | 3 | Max heal-loop cycles before human escalation | | verbosity | normal | normal / full — how much the crew echoes |

Project config (.mugiwara/config) overrides global (~/.mugiwara/config).

→ All config keys

Quick reference

| Need | Command / Doc | |---|---| | Review a PR diff | /mugiwara-review or "review this PR" | | Security audit | /mugiwara-security or "Jinbe, audit X" | | Resume a mission | /mugiwara continue <mission> [member] | | See mission position | mugiwara status | | See cost + live slop | mugiwara cost | | Close out a mission | mugiwara archive <mission> | | Switch mode | /mugiwara guided\|semi\|auto | | All docs | docs/ |

Install

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

Uninstall: /plugin uninstall mugiwara

Add to opencode.json:

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

Update: rm -rf ~/.cache/opencode/packages/@ionivetech/mugiwara* && opencode plugin @ionivetech/mugiwara -g (details) Uninstall: remove "@ionivetech/mugiwara" from the plugins array

See per-platform guides — each has a one-line install and uninstall.

npx @ionivetech/mugiwara@latest install --target <id> --yes   # windsurf, cline, kilo, codex
npm i -g @ionivetech/mugiwara && mugiwara install --target all --yes

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

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 [--check]                       # show / health-check installations
mugiwara status                               # computed mission state
mugiwara continue [mission] [member]          # resume / list in-flight (read-only)
mugiwara cost [--mission <id>] [--json]       # cost ledger, avoided work, live slop
mugiwara archive <mission>                    # fold the trail into report.md
mugiwara clean [--all] [--before <date>]      # batch-archive closed missions
mugiwara blame <path>                         # provenance on the last commit touching path
mugiwara handoff <mission>                    # engineer-to-engineer handoff report
mugiwara sign <mission> [--verify]            # optional report attestation
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 · Provenance · Policy as code · Closure tools · Permissions

Crew: Agents · Skills · Adaptive execution

Reference: Adoption guide · Glossary · Harness matrix · Compliance matrix

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

Troubleshooting: Common problems

What is measured, and what is not

| Claim | Status | |---|---| | Retrieval routing rank-1 | 95.9%, 216 probes, offline, in CI | | Reference pointers resolve | 320/320, 9 targets, in CI | | Index size published vs measured | doc-gated — validator fails on drift, in CI | | Lane constants match content load | verified, in CI | | Write-scope enforcement | opencode only — rules-based elsewhere | | Cross-harness mission behavior | 12/12 platforms, in CI | | Outcome vs other approaches | not measured |

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

License

MIT. Copyright (c) 2026 ionivetech.