@ionivetech/mugiwara 0.4.0 → 0.5.1

package/README.md

@@ -3,448 +3,308 @@
 [![npm version](https://img.shields.io/npm/v/@ionivetech%2fmugiwara)](https://www.npmjs.com/package/@ionivetech/mugiwara)
 [![License: MIT](https://img.shields.io/github/license/ionivetech/mugiwara)](https://github.com/ionivetech/mugiwara/blob/main/LICENSE)
 
-**The Straw Hat crew of AI agents and skills.** A complete software
-development workflow for your coding agent — triage, planning, execution,
-verification, review, and shipping — with the discipline of a senior
-engineering team.
-
-Mugiwara is pure markdown. No daemons, no servers, no plugin to babysit. Your
-existing coding agent reads the skills and runs them itself. It works across
-12 coding agents — Claude Code, opencode, Gemini CLI, Codex, Cursor, Copilot,
-Kimi, pi, Windsurf, Cline, Kilo Code, and Antigravity — and installs into
-70+ more as plain skills.
-
-```
-   TRIAGE            PLAN             BUILD            VERIFY            REVIEW            SHIP
- ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
- │ Luffy    │ ──▶ │ Nami     │ ──▶ │ Zoro     │ ──▶ │ Chopper  │ ──▶ │ Robin +  │ ──▶ │ push +   │
- │ 5-way    │     │ waves +  │     │ TDD per  │     │ Sanji +  │     │ Jinbe    │     │ ready PR │
- │ triage   │     │ tasks    │     │ task     │     │ Franky   │     │ review+  │     │ summary  │
- └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
-   ↰ exploratory → Usopp brainstorms            fail → Brook heals ↺ Wave 4
-```
-
-## Why mugiwara
-
-- **It just starts.** Give a non-trivial request — "add dark mode to the
-  settings page" — and the crew runs the pipeline in your main conversation,
-  with a compact checkpoint report at every stage. Nothing hides behind a
-  subagent click; you can interrupt any time.
-- **The work is sized before it runs.** A one-file typo runs zero waves. An
-  architecture change runs all nine. Luffy routes each mission to a lane, so a
-  tiny fix never pays the price of a big feature — and a sensitive change never
-  sneaks through the lean path.
-- **Evidence over claims.** No wave passes on a spoken "it works." The owning
-  agent runs the checks and shows output. Every skill also knows when it does
-  *not* apply — and says so, out loud.
-- **It remembers.** Mission state lives in `.mugiwara/` — plans, results, a
-  failure ledger, and a lessons file. Lose context mid-mission and the crew
-  rebuilds from disk instead of restarting.
-- **You stay in control.** The crew pushes the branch and hands you a
-  ready-to-paste PR summary. It never creates a PR, merges, or deploys on its
-  own. Three autonomy levels — guided, semi, auto — decide how much it does
-  without asking.
+Your coding agent becomes a governed engineering team. 15 specialists — triage,
+plan, build, audit, review, heal — with evidence at every step, cost tracking,
+and a process that sizes itself to your work. Pure markdown, zero runtime.
 
 ## Quick start
 
-Install into your harness in one command, then just ask:
-
 ```bash
 # Claude Code
 /plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
 
-# opencode
-{ "plugin": ["@ionivetech/mugiwara"] }   # add to opencode.json
+# opencode — add to opencode.json
+{ "plugin": ["@ionivetech/mugiwara"] }
 
-# or via CLI for any target
-npx @ionivetech/mugiwara@latest --project ./my-app --target all --yes
+# CLI for any target
+npx @ionivetech/mugiwara@latest --project . --target all --yes
 ```
 
-```text
-> add dark mode to the settings page
-```
+Then just ask. The crew auto-activates — no agent names to remember.
 
-The crew announces itself at session start and routes the request. See
-[docs/getting-started.md](docs/getting-started.md) for the full walkthrough.
-
----
-
-## The crew — 15 agents
-
-Each agent is a focused specialist. The main thread embodies each role inline
-using its skill; you can also summon any member directly by name. "Dispatch"
-means *route the mission to this role* — crew members never dispatch each other.
-
-| Agent | Crew member | Role | Summon for |
-|-------|-------------|------|------------|
-| `using-mugiwara` | Front Door | Router — classifies and routes, never implements | any new mission |
-| `luffy-orchestrator` | Luffy | Captain — 5-way triage, lane sizing, check-ins, closure | mission start, escalations |
-| `usopp-brainstorm` | Usopp | Critical friend — interrogates ideas, researches, no rubber-stamps | vague ideas, direction, options |
-| `nami-planner` | Nami | Planner — interview-first, full-context scan, scaled plans | turning an idea into a plan |
-| `zoro-execution` | Zoro | Executor — todo list first, inline tasks, parallel worker batches, evidence per task | executing an approved plan |
-| `chopper-checkpoint` | Chopper | Auditor — re-verifies every acceptance criterion, writes the failure ledger, never fixes | auditing a wave's results |
-| `sanji-quality` | Sanji | Quality — discovers real tooling, format / lint / test | after checkpoint passes |
-| `franky-gates` | Franky | Gates — coverage, build, Definition of Done, binary verdicts | after quality checks |
-| `robin-reviewer` | Robin | Reviewer — doubt-driven diff review, breaking-change map first | after gates pass |
-| `jinbe-security` | Jinbe | Security — STRIDE, OWASP, secrets, injection, auth, dependencies | security audit of a diff |
-| `brook-healing` | Brook | Healer — reads the ledger, root-cause fixes, proves each fix, ≤3 cycles | any wave produced failures |
-| `skeptic-verifier` | Skeptic | Adversarial verifier — doubts every output, never validates | high-stakes verdicts, plans, reviews |
-| `eval-runner` | Eval Runner | Harness tester — task suites, rubric comparison, pass/fail | verifying mugiwara itself works |
-| `resume-coordinator` | Resume Coordinator | Resumer — rebuilds from `.mugiwara/`, continues never restarts | context loss, new session mid-mission |
-| `memory-keeper` | Memory Keeper | Institutional memory — surfaces past lessons, captures new ones | mission start + closure |
-
-Say a name and the role embodies itself:
+## What it looks like
 
-```
-> Chopper, audit the last wave against the plan
-> Nami, plan this out
-```
+You ask:
 
-Luffy still records the route and its reason, and direct calls do not skip
-check-ins. See [docs/agents.md](docs/agents.md).
-
----
-
-## The techniques — 32 skills
-
-Skills are the actual product: portable markdown playbooks that tell the agent
-*how* to do each phase well. Agents are the personas; skills are the
-knowledge. Every skill declares **when to use it** and **when to skip it**.
-
-### The pipeline
-
-| Skill | Used when |
-|-------|-----------|
-| `mugiwara-workflow` | starting any non-trivial mission — the harness entry point |
-| `mugiwara-orchestration` | triaging a new mission, coordinating waves, closing out |
-| `mugiwara-brainstorm` | exploring a vague idea or architecture choice before planning |
-| `mugiwara-planning` | turning an approved idea or spec into an execution plan |
-| `mugiwara-execution` | executing an approved wave-structured plan |
-| `mugiwara-checkpoint` | auditing a wave's results against the plan, criterion by criterion |
-| `mugiwara-healing` | earlier waves produced failures — test, gate, review, or security findings |
-| `mugiwara-resume` | a mission was interrupted, context lost, or a new session starts mid-mission |
-| `mugiwara-mode` | reading or changing the autonomy level (guided / semi / auto) |
-
-### Engineering practice
-
-| Skill | Used when |
-|-------|-----------|
-| `mugiwara-test-driven-development` | writing code during execution — RED-GREEN-REFACTOR |
-| `mugiwara-testcases` | a mission declares user-provided test cases or acceptance criteria |
-| `mugiwara-systematic-debugging` | a bug, crash, or unexplained regression needs root-cause discipline |
-| `mugiwara-api-and-interface-design` | designing or reviewing an API, interface, or inter-service contract |
-| `mugiwara-doubt-driven-development` | an in-flight decision is cheap to verify now but costly to reverse later |
-| `mugiwara-context-engineering` | working in a large codebase, long session, or near the context limit |
-| `mugiwara-git` | committing, splitting commits, or debugging via git history |
-| `mugiwara-git-worktrees` | running parallel branches without polluting the working tree |
-| `mugiwara-deprecation` | retiring code or steering users onto a replacement |
-| `mugiwara-frontend` | any frontend implementation or redesign — anti-slop, WCAG 2.1 AA |
-| `mugiwara-backend` | implementing or reviewing backend/server code |
-| `mugiwara-agent-security` | reviewing the agent layer itself — injection, poisoning, excessive agency |
-
-### Verification & review
-
-| Skill | Used when |
-|-------|-----------|
-| `mugiwara-quality` | running format / lint / test after checkpoint passes |
-| `mugiwara-gates` | enforcing coverage, build, and Definition of Done |
-| `mugiwara-review` | reviewing the diff adversarially after gates pass |
-| `mugiwara-security` | running the security audit of a diff or system |
-| `mugiwara-ship` | running the pre-launch gate before anything reaches users |
-
-### Team & meta
-
-| Skill | Used when |
-|-------|-----------|
-| `mugiwara-pr` | pushing the branch and preparing the PR material at closure |
-| `mugiwara-lessons` | reading/writing the cross-mission lessons ledger |
-| `mugiwara-observability` | tracing how the crew ran a mission |
-| `mugiwara-dynamic-workflow` | a mission has many subtasks, needs comparison, or risks agent bias |
-| `mugiwara-eval` | verifying a mugiwara skill or agent actually works |
-| `mugiwara-writing-skills` | authoring or revising a mugiwara skill |
-
-Every install ships the full set — no project-type selection. The harness
-routes each task to the right skill, and a skill with nothing to do says so and
-steps aside. See [docs/skills.md](docs/skills.md) for the anatomy and
-[docs/skill-anatomy.md](docs/skill-anatomy.md) for the format spec.
-
----
-
-## How mugiwara works
-
-### Auto-activation
-
-At session start the crew is announced. Give a non-trivial request and the
-pipeline runs by itself — no command to remember. `/using-mugiwara` remains an
-optional router if you want to hand-route a mission.
-
-### Sizing: the lanes
-
-At Wave 0, Luffy sizes the request and picks a lane. The lane decides how many
-waves run:
-
-| Lane | Picks when | Waves |
-|------|-----------|-------|
-| **0 · Direct** | typo, rename, one file under 20 lines | none |
-| **1 · Lean** | bug in 1-2 files, under 50 lines | execute → quality |
-| **2 · Standard** | feature, 3-8 files | plan → execute → checkpoint → review |
-| **3 · Full** | architecture, migration, auth/payment, API | all 9 waves |
-| **4 · Spike** | exploratory, needs direction | brainstorm → re-triage |
-
-The lane escalates when the work outgrows the estimate (the diff balloons, a
-sensitive path appears, failures repeat) — but never shrinks on its own.
-Under-process costs more than over-process.
-
-### The wave pipeline
-
-```mermaid
-flowchart TD
-    U[User request] --> G{Luffy triage}
-    G -- exploratory --> B[Usopp brainstorm]
-    G -- clear work --> N[Nami plan]
-    B --> N
-    N --> Z[Zoro execute]
-    Z --> CP[Chopper audit]
-    CP --> SQ[Sanji quality]
-    SQ --> FG[Franky gates]
-    FG --> RJ[Robin + Jinbe review]
-    RJ -- pass --> LC[Luffy closure]
-    RJ -- fail --> BH[Brook heal]
-    BH --> CP
-    LC --> CL[push + ready PR summary]
+```
+> add search bar to the products page
 ```
 
-| Wave | Owner | Skill | Output |
-|------|-------|-------|--------|
-| 0 Triage | Luffy | `mugiwara-orchestration` | route + lane + reason |
-| 1 Brainstorm | Usopp | `mugiwara-brainstorm` | refined direction, options, recommendation |
-| 2 Planning | Nami | `mugiwara-planning` | plan doc: waves, tasks, dependency edges, acceptance |
-| 3 Execution | Zoro | `mugiwara-execution` | implemented tasks with evidence |
-| 4 Checkpoint | Chopper | `mugiwara-checkpoint` | audit report + failure ledger |
-| 5 Quality | Sanji | `mugiwara-quality` | formatter / linter / test results |
-| 6 Gates | Franky | `mugiwara-gates` | coverage + build verdict |
-| 7 Review | Robin ∥ Jinbe | `mugiwara-review` + `mugiwara-security` | severity-tagged findings |
-| 8 Healing | Brook | `mugiwara-healing` | fixes; loops to Wave 4, max 3 cycles |
-| 9 Closure | Luffy | `mugiwara-orchestration` | summary + push + ready PR summary |
-
-**You see progress, not a firehose.** Each wave opens with a banner
-(`## Wave N — <crew> (<skill>)`), closes with a compact checkpoint report (what
-ran / result / evidence pointer), and pauses when something fails or gets
-risky. Subagents appear only where they genuinely help: parallel task batches
-and independent re-verification.
-
-### What a mission looks like
-
-Small and specific:
+The crew runs:
 
 ```
-> fix the date formatting bug in src/utils/format.ts
+Wave 0  Luffy   triage → 5 files, no sensitive paths → Lane 2 Standard
+Wave 2  Nami    plan   → 1 execution wave, 3 tasks with dependency edges
+Wave 3  Zoro    execute→ T1: search endpoint (test red→green, commit)
+                         T2: search service (test red→green, commit)
+                         T3: search component (test red→green, commit)
+Wave 4  Chopper audit  → re-runs all 3 criteria, checks commits → PASS
+Wave 5  Sanji   quality → prettier: clean, eslint: 0, 412 tests: PASS
+Wave 6  Franky  gates  → coverage new 94%, modified 87%, build green → PASS
+Wave 7  Robin   review → breaking-change map: 0 breaks, 1 minor naming finding
+Wave 7  Jinbe   security→ no auth/payment surface touched → skip
+Wave 9  Luffy   closure→ mission report + push branch + ready PR summary
+
+done. branch pushed. paste the PR summary and open.
 ```
 
-Luffy routes it to **Lane 1** and the crew runs two waves — Zoro reproduces and
-fixes, then Sanji formats and tests — all visible as checkpoint reports. No
-nine-wave ceremony for a one-file bug.
+Each wave is a compact checkpoint report in your conversation. You see
+everything. Nothing hides behind a subagent click. If a wave fails, Brook reads
+all failures at once, fixes them, and all verification waves re-run.
 
-Big and sensitive:
+Now a bigger one:
 
 ```
-> add role-based access control to the API
+> add role-based access control to the API: admin, editor, viewer roles
 ```
 
-That touches auth, so Luffy routes it to **Lane 3**. Nami plans the migration
-waves, Zoro executes test-first, Chopper re-verifies every criterion, Sanji and
-Franky gate it, Robin and Jinbe review, Brook heals anything that fails, and
-Luffy closes with a ready PR summary. Every wave reports inline.
-
-That is the point of mugiwara: **the process scales to the work, and you can
-see all of it.**
-
-### The workspace
-
-Every mission works inside `.mugiwara/` at the repo root:
+Auth path detected → auto-escalate to Lane 3 (Full):
 
 ```
-.mugiwara/
-├── config         # mode + writing standards (gitignored)
-├── spec/          # brainstorm output
-├── plans/         # plan docs — clean, Nami-only, source of truth from Wave 2
-├── results/       # wave results: audits, test output, gate verdicts
-├── review/        # review + security findings
-├── issues/        # blocker + failure ledger
-├── refs/          # full skill/agent bodies for glob-loading harnesses
-└── logs/          # decision + check-in log per mission (deleted at cleanup)
+Wave 0  Luffy   triage → auth/ + migration/ touched → lane 3 full
+Wave 2  Nami    plan   → 2 execution waves, 5 tasks, parallel-safe graph
+Wave 3a Zoro    execute→ T1 migration + T2 middleware + T3 3 parallel endpoint guards
+Wave 4  Chopper audit  → T3-C: viewer can still POST /api/settings → 1 ledger row
+Wave 5  Sanji   quality → 2 integration tests fail after middleware change → 2 rows
+Wave 6  Franky  gates  → coverage 91% / 85%, build green, DoD blocked (3 open rows)
+Wave 7  Robin   review → 1 major: error message format inconsistent → 1 row
+Wave 7  Jinbe   security→ STRIDE: PASS. 0 high. deny-by-default enforced.
+Wave 8  Brook   heal   → reads 4 ledger rows → 3 parallel heal workers → fix all
+Wave 4  Chopper re-audit→ PASS (cycle 2)
+Wave 5  Sanji   re-qual → PASS
+Wave 6  Franky  re-gate → PASS
+Wave 7  Robin   re-rev  → PASS
+Wave 3b Zoro    execute→ T4 admin dashboard RBAC UI + T5 integration tests
+Wave 4  Chopper audit  → PASS
+Wave 9  Luffy   closure→ state.json + mission report + push + PR summary
+
+1 heal cycle. 4 failures from 3 different waves — all fixed at once.
 ```
 
-Two rules hold it together:
+At closure you get a mission report:
 
-1. **Evidence over claims.** No wave passes on assertion — the owning agent
-   runs the checks and shows output.
-2. **The plan is the source of truth.** From Wave 2 on, the plan doc holds the
-   clean execution plan; the decision log holds the who-and-why trace. A
-   skipped wave is recorded, never silent.
+```
+.mugiwara/reports/2026-08-11-rbac.md
+
+Lane full · Mode guided · Actor you · Branch feature/feat-rbac
 
-### Manual stages
+What changed: 12 files, +340/-82
+Gates: Audit PASS · Quality PASS · Coverage 91%/85% · Security PASS
+State: 12/12 tasks · 0 blockers · 1 heal cycle · 18.5k/20k tokens
+```
 
-Prefer to drive the stages yourself? Every stage has a slash command that loads
-the skill, runs the role inline, and bridges state from `.mugiwara/`:
+One file. Any reviewer reads it in 30 seconds. That's the governance trail.
+
+## Capabilities
+
+| Capability | What it does |
+|-----------|-------------|
+| **15 specialist agents** | Luffy triages, Nami plans, Zoro builds TDD, Chopper audits, Sanji checks quality, Franky enforces gates, Robin maps breaking changes, Jinbe runs STRIDE, Brook heals failures. Each with role boundaries: auditors read-only, executor no-network. |
+| **Lane sizing** | Process scaled to work size — computed from `git diff` by `scripts/lane.sh`. Typo = 0 waves. Auth migration = full 9-wave pipeline. Sensitive paths auto-escalate. |
+| **9-wave gated pipeline** | Triage → Plan → Execute → Audit → Quality → Gates → Review+Security → Heal → Closure. Each wave gated by evidence. Pipeline runs inline — you watch everything. |
+| **Evidence trail** | No wave passes on a claim. `scripts/evidence.sh` captures command output. Chopper re-runs criteria. Mission report at closure — one file any reviewer reads in 30 seconds. |
+| **State on disk** | `state.json` written at every wave boundary by `scripts/savepoint.sh`. Lane, files, blockers, token budget — all computed, zero model judgement. Resume reads one file. |
+| **Token budget** | Budget per lane. Warns at 1.5×, pauses at 3×. You decide: continue, split, or reduce. Cost surfaced in mission report — governance, not a kill switch. |
+| **Self-healing** | Brook reads entire blocker ledger after all verification waves. Groups failures, spawns parallel heal workers for independent fixes. Max 3 cycles. |
+| **Deterministic tooling** | `savepoint.sh` (state), `lane.sh` (sizing), `evidence.sh` (output capture), `mission-report.sh` (report). Scripts compute what models shouldn't remember. |
+| **Configurable gates** | Coverage thresholds in `.mugiwara/config`: `coverage_new=90`, `coverage_modified=80`. Raise for strict repos, lower for legacy. |
+| **3 autonomy modes** | Guided (ask everything), semi (auto branch/commit, plan needs GO), auto (hands-off except high-risk). All modes end at push + PR summary — no auto-merge. |
+| **3-layer skills** | 26 skills: trigger description (~150 chars) → body (≤120 lines) → 23 reference files (on demand). 5.2k char index budget — loaded every session. |
+| **Multi-actor safe** | Two engineers, one repo. Reset refuses without `--force`. Branch-scoped state. Shared lessons ledger. |
+| **Compliance matrix** | Rule compliance per model/tier/harness. Published with failures — Gemini tier 2 ≠ Claude tier 1. Documented, not hidden. |
+| **12 harnesses** | Claude Code, opencode, Copilot, Gemini, Codex, Cursor, Kimi, pi, Windsurf, Cline, Kilo, Antigravity. 70+ more via skills.sh. Pure markdown, zero runtime. |
+
+## Why this instead of just asking my agent?
+
+Your agent alone has no governance. It forgets context, skips verification, and
+burns tokens on small fixes the same way it does on architecture changes. There's
+no audit trail — when someone asks "what did the agent do?", you have nothing to
+show.
+
+Mugiwara wraps your agent in a team structure with defined roles, evidence gates,
+and cost tracking. The same discipline you'd expect from a senior engineering
+team — in your chat window, running inline, visible at every step.
+
+## The crew
+
+15 personas, 26 skills. Each with a permission boundary.
+
+| Agent | Role | Permission |
+|-------|------|------------|
+| Luffy | Captain — triage, lane sizing, check-ins, closure | — |
+| Nami | Planner — interviews, scans codebase, writes scaled plans | — |
+| Zoro | Executor — TDD per task, commits per logical unit | **no-network** |
+| Chopper | Auditor — re-runs criteria, writes failure ledger, never fixes | **read-only** |
+| Sanji | Quality — format, lint, test. Never weakens configs | — |
+| Franky | Gates — coverage (configurable thresholds), build, DoD | — |
+| Robin | Reviewer — breaking-change map, five-axis, severity tagging | **read-only** |
+| Jinbe | Security — STRIDE, OWASP, secret scan, dependency audit | **read-only** |
+| Brook | Healer — reads ledger, parallel heal workers, max 3 cycles | — |
+| Skeptic | Adversarial verifier — doubts everything, never validates | **read-only** |
+| Usopp | Brainstorm — interrogates ideas, researches, recommends | — |
+| Resume | Continuity — rebuilds from state.json, never restarts | — |
+| Memory | Cross-mission lessons — read at start, write at closure | — |
+
+See [all 15 agents](docs/agents.md) and [all 26 skills](docs/skills.md).
 
-| Command | Runs | Reads state from |
-|---------|------|------------------|
-| `/mugiwara-plan` | Nami | `.mugiwara/spec/` |
-| `/mugiwara-execute` | Zoro | `.mugiwara/plans/` |
-| `/mugiwara-review` | Robin | `.mugiwara/results/` + diff |
-| `/mugiwara-security` | Jinbe | `.mugiwara/results/` + diff |
-| `/mugiwara-heal` | Brook | `.mugiwara/issues/` |
-| `/mugiwara-ship` | Luffy | plan + results |
+## Install
 
-Jump in at any stage — plan today, execute tomorrow.
+### Claude Code
 
----
+<details>
+<summary><b>Install / Update / Uninstall</b></summary>
 
-## Modes & autonomy
+```bash
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara   # install
+/plugin update mugiwara                                                    # update
+/plugin uninstall mugiwara                                                 # uninstall
+```
+</details>
 
-Three autonomy levels, set in `.mugiwara/config`:
+### opencode
 
-| Level | Plan GO | Branch/commit | Ambiguities | Check-ins |
-|-------|---------|---------------|-------------|-----------|
-| **guided** | ask the user | ask the user | ask the user | ask the user |
-| **semi** | present plan for user GO | auto | self-answer + log | log, no pause |
-| **auto** | gated auto-GO | auto | self-answer + log | log, no pause |
+<details>
+<summary><b>Install / Update / Uninstall</b></summary>
 
-- **guided** — the default. You approve the plan, decide branch and commits,
-  answer ambiguities, and open the PR yourself.
-- **semi** — the crew self-manages branch, commits, and ambiguities (logging
-  each decision), but the plan still needs your explicit GO.
-- **auto** — hands-off, with one safety line: the plan proceeds only with zero
-  blocking ambiguities AND zero high-risk tasks (deploy / migration / DB /
-  public API / state-mutating).
+```json
+{ "plugin": ["@ionivetech/mugiwara"] }   // add to opencode.json
+```
 
-Two invariants hold in every mode:
+```bash
+mugiwara update    # update
+# remove the plugin entry from opencode.json to uninstall
+```
 
-- **Consent.** State-mutating tests against shared state (real DB writes,
-  network, browsers) always require your explicit consent. Provably isolated
-  mutation is auto-safe.
-- **Terminal.** Every mode ends at push + ready PR summary + verdict file. The
-  crew never creates a PR, merges, deploys, or auto-reacts to review comments.
+Restart opencode after install.
+</details>
 
-Flip mid-mission with `mugiwara mode <guided|semi|auto>`. The PR description is
-prepared for you — see [docs/pr-summary.md](docs/pr-summary.md).
+### GitHub Copilot
 
----
+<details>
+<summary><b>Install / Update / Uninstall</b></summary>
 
-## Configuration
+```bash
+copilot plugin marketplace add ionivetech/mugiwara && copilot plugin install mugiwara
+copilot plugin update mugiwara
+copilot plugin uninstall mugiwara
+```
+</details>
 
-`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global). Plain
-`key=value` lines, `#` comments allowed.
+### Gemini CLI · Codex · Cursor
 
-| Key | Values | Default | Meaning |
-|-----|--------|---------|---------|
-| `mode` | guided / semi / auto | guided | How much the crew does without asking |
-| `branch` | pattern | `feature/{type}-{issue}-{slug}` | Branch naming |
-| `commit` | conventional / gitmoji / plain | conventional | Commit message style |
-| `base` | branch name | `main` | The PR target in the prepared summary |
+<details>
+<summary><b>Gemini</b></summary>
 
-Commit styles: `conventional` (`feat: ...`, `fix(scope): ...`), `gitmoji`
-(`✨ feat: ...`), or `plain` (`Fix export csv encoding`). See
-[docs/config.md](docs/config.md).
+```bash
+gemini extensions install https://github.com/ionivetech/mugiwara
+gemini extensions update mugiwara
+gemini extensions remove mugiwara
+```
+</details>
 
----
+<details>
+<summary><b>Codex</b></summary>
 
-## Install
+```bash
+codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara
+codex plugin update mugiwara
+codex plugin remove mugiwara
+```
+</details>
 
-### Via your coding agent
+<details>
+<summary><b>Cursor</b></summary>
 
-| Harness | Install |
-|---------|---------|
-| Claude Code | `/plugin marketplace add ionivetech/mugiwara` then `/plugin install mugiwara` |
-| opencode | add `{ "plugin": ["@ionivetech/mugiwara"] }` to `opencode.json` |
-| GitHub Copilot | `copilot plugin marketplace add ionivetech/mugiwara` then `copilot plugin install mugiwara` |
-| Gemini CLI | `gemini extensions install https://github.com/ionivetech/mugiwara` |
-| Codex | `codex plugin marketplace add ionivetech/mugiwara` then `codex plugin add mugiwara@mugiwara` |
-| Cursor | `/add-plugin mugiwara` |
-| Kimi Code | `/plugins install https://github.com/ionivetech/mugiwara` |
-| pi | `pi install git:github.com/ionivetech/mugiwara` |
+```
+/add-plugin mugiwara       # install & update
+/remove-plugin mugiwara    # uninstall
+```
+</details>
 
-### Via the CLI
+### Kimi · pi · Windsurf · Cline · Kilo · Antigravity
 
-Requires **Node.js >= 20.11**.
+<details>
+<summary><b>All other harnesses</b></summary>
 
 ```bash
-# run without installing (wizard)
-npx @ionivetech/mugiwara@latest
-
-# non-interactive: global Claude Code install
-npx @ionivetech/mugiwara@latest --global --target claude --yes
+npx @ionivetech/mugiwara@latest --project . --target all --yes   # install
+mugiwara update                                                    # update
+mugiwara uninstall                                                 # uninstall
+```
+</details>
 
-# project install for several harnesses
-npx @ionivetech/mugiwara@latest --project ./my-app --target opencode,copilot --yes
+### Any agent (skills only)
 
-# global install, run `mugiwara` anywhere
-npm install -g @ionivetech/mugiwara
+```bash
+npx skills add ionivetech/mugiwara   # 70+ agents via skills.sh
 ```
 
+### One-liner
+
 ```bash
-# macOS / Linux one-liner
+# macOS / Linux
 curl -fsSL https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.sh | bash
-
 # Windows
 irm https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.ps1 | iex
 ```
 
-### Skills only, any agent
-
-All 32 skills ship in the standard [agentskills.io](https://agentskills.io)
-layout, so you can install just the skills into 70+ agents via
-[skills.sh](https://skills.sh):
-
-```bash
-npx skills add ionivetech/mugiwara
-```
-
-Update — `mugiwara update` or re-run your harness's install command. Uninstall
-— `mugiwara uninstall` removes exactly what the manifest recorded.
-
----
-
-## CLI reference
-
-| Command | Effect |
-|---------|--------|
-| `mugiwara install` | Install the crew (default; wizard when flags are missing) |
-| `mugiwara update` | Replace installed files, backing up differences first |
-| `mugiwara uninstall` | Remove exactly what the install manifest recorded |
-| `mugiwara list` | Show installations (project + global manifests) |
-| `mugiwara reset` | Wipe mission state (`--keep-logs` preserves the lessons ledger) |
-| `mugiwara --help` / `--version` | Help / version |
+Requires **Node.js >= 20.11**.
 
-| Flag | Meaning |
-|------|---------|
-| `--global` | Install user-wide |
-| `--project <dir>` | Install into a project directory |
-| `--target <ids\|all>` | Comma-separated target IDs, or `all` |
-| `--yes`, `-y` | Non-interactive |
-| `--force` | Overwrite differing files (with backup) |
-| `--dry-run` | Print actions without writing |
-| `--keep-logs` | With `reset`: keep `.mugiwara/logs` (lessons ledger) |
+## Configuration
 
-Every install writes `.mugiwara/manifest.json` recording the version, scope,
-targets, and exact written files — which is what `update` and `uninstall` use
-to operate safely.
+`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global).
 
----
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `mode` | guided | Autonomy: guided / semi / auto |
+| `branch` | `feature/{type}-{issue}-{slug}` | Branch naming |
+| `commit` | conventional | conventional / gitmoji / plain |
+| `base` | main | PR target branch |
+| `coverage_new` | 90 | Coverage threshold for new files |
+| `coverage_modified` | 80 | Coverage threshold for modified files |
 
-## Comparing
+[Full config →](docs/config.md)
 
-Mugiwara is a skills pack with a named crew and a gated pipeline. For an honest
-side-by-side against superpowers, agent-skills, frameworks, and mega-prompts —
-including a measured benchmark — see [docs/comparison.md](docs/comparison.md).
+## CLI
 
-## Docs & roadmap
+```bash
+mugiwara install                                  # wizard (interactive)
+mugiwara install --project . --target all --yes   # non-interactive
+mugiwara update                                   # replace existing files
+mugiwara uninstall                                # remove what manifest recorded
+mugiwara list                                     # show installations
+mugiwara reset --keep-logs                        # wipe mission state, keep lessons
+mugiwara reset --force                            # override multi-actor guard
+```
 
-- [Docs index](docs/index.md) — adoption guide, installs, crew & skill references
-- [Troubleshooting](docs/troubleshooting.md) — common problems and fixes
-- [Roadmap](ROADMAP.md) — what is planned next
+## When not to use mugiwara
+
+- **Autonomous marathon runs** — the agent disappears for hours. Use superpowers.
+- **Deep per-skill reference encyclopedia** — use agent-skills.
+- **A deployable runtime** — use LangGraph / CrewAI.
+- **One large instruction with no ceremony** — use a mega-prompt.
+
+Mugiwara is for visibility, governance, and cost awareness. If those don't
+matter to you, this is the wrong tool.
+
+## Docs
+
+| Doc | What it covers |
+|-----|---------------|
+| [Getting started](docs/getting-started.md) | First mission, lane 0-3 examples, setup walkthrough |
+| [Workflow](docs/workflow.md) | Full 9-wave pipeline with heal loop detail |
+| [Agents](docs/agents.md) | 15 crew members, roles, permissions, how to summon |
+| [Skills](docs/skills.md) | 26 techniques, 3-layer disclosure model |
+| [Lanes](docs/lanes.md) | Deterministic lane sizing — computed from git diff |
+| [Audit trail](docs/audit-trail.md) | 15 artifact types, how to read as reviewer |
+| [Cost model](docs/cost.md) | Index/body/references layers, cost per lane |
+| [Harness matrix](docs/harness-matrix.md) | Tier 1/2/3 — what differs per harness |
+| [Config](docs/config.md) | All `.mugiwara/config` keys with defaults |
+| [Modes](docs/modes.md) | Guided / semi / auto autonomy levels |
+| [Compliance matrix](docs/compliance-matrix.md) | Rule compliance per model — published with failures |
+| [Comparison](docs/comparison.md) | Positioning. When to use mugiwara vs something else. |
+| [Roadmap](ROADMAP.md) | Now — Next — Then — After |
 
 ## License
 
-MIT. Copyright (c) 2026 ionive. See [LICENSE](LICENSE).
+MIT. Copyright (c) 2026 ionive.