@ionivetech/mugiwara 0.5.4 → 0.6.0

package/README.md

@@ -1,184 +1,207 @@
 # Mugiwara
 
 [![npm version](https://img.shields.io/npm/v/@ionivetech%2fmugiwara)](https://www.npmjs.com/package/@ionivetech/mugiwara)
+[![npm downloads](https://img.shields.io/npm/dm/@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)
 
-Your coding agent becomes a governed engineering team. 14 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.
+**Ship quality code, not just fast code.** Mugiwara gives your AI agent a
+governed engineering team — 12 specialists who plan, build, audit, review, and
+heal — with evidence at every step. No runtime, no API keys, no servers. Just
+markdown your agent already knows how to read.
 
-## Quick start
+Works on Claude Code, opencode, Copilot, Gemini, and 8 more platforms.
 
-```bash
-# Claude Code
-/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara
+## Why this exists
 
-# opencode — add to opencode.json
-{ "plugin": ["@ionivetech/mugiwara"] }
+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.
 
-# Gemini CLI
-gemini extensions install https://github.com/ionivetech/mugiwara
+→ [Full pitch: why mugiwara vs just asking your agent](docs/concepts/comparison.md)
 
-# Any platform via npm
-npx @ionivetech/mugiwara@latest install --project . --target all --yes
-```
+## What Mugiwara does
 
-Then just ask. The crew auto-activates — no agent names to remember.
+### 9-wave pipeline
 
-## What it looks like
+```mermaid
+flowchart TB
+    L0["Luffy<br>Triage"] --> L1["Usopp<br>Brainstorm"] --> L2["Nami<br>Plan"] --> L3["Zoro<br>Execute"] --> L4["Chopper<br>Audit"]
+    L4 --> L5["Sanji<br>Quality"] --> L6["Franky<br>Gates"]
+    L6 --> L7R["Robin<br>Review"]
+    L6 --> L7J["Jinbe<br>Security"]
+    L7R --> L8["Brook<br>Heal"]
+    L7J --> L8
+    L8 --> L9["Luffy<br>Closure"]
+    L8 -. "heal ≤3 cycles" .-> L4
+```
 
-You ask:
+→ [Full pipeline details](docs/concepts/workflow.md)
 
-```
-> add search bar to the products page
-```
+### All features
 
-The crew runs:
+| Feature                     | What you get                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------- |
+| **Lane sizing**             | Work auto-sized from `git diff`. Typo = instant fix. Auth migration = full pipeline.            |
+| **Team initiatives**        | Sub-missions with assignee + branch, shared plan doc, status tracking per sub-mission.          |
+| **Sonar-style quality**     | Duplication %, complexity, maintainability rating (A–E), code attributes, per-condition gate.   |
+| **STRIDE + OWASP security** | Threat modeling, secret scan, injection check, SCA license, hotspot review.                     |
+| **Self-healing**            | Brook reads all failures at once, fixes root causes, re-runs verification. ≤3 cycles.           |
+| **3 autonomy modes**        | guided (ask) / semi (auto branch+commit) / auto (hands-off). Flip mid-session.                  |
+| **Configurable depth**      | `review_depth` + `quality_depth`: full / standard / quick. Set per project.                     |
+| **Resume from anywhere**    | Session lost? Rebuilds from `.mugiwara/state.json`. Continues, never restarts.                  |
+| **Onboarding wizard**       | 10 questions — project type, team size, mode, depth. `/mugiwara onboard`.                       |
+| **Evidence trail**          | `.mugiwara/` workspace: plans, audit reports, quality reports, review findings, blocker ledger. |
+| **12 platforms**            | Claude Code, opencode, Copilot, Gemini, Codex, Cursor, Kimi, Pi, Antigravity + CLI.             |
+| **Cost tracking**           | Token budget per lane. Warn at 1.5×, pause at 3×. Surfaced in mission reports.                  |
+| **Multi-actor safe**        | Branch-scoped state. Two engineers, one repo. Reset refuses without `--force`.                  |
 
-```
-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.
-```
+→ [Every feature, explained with how-to-use + scenarios](docs/concepts/features.md) · [Full pipeline](docs/concepts/workflow.md) · [Lanes](docs/concepts/lanes.md) · [Modes](docs/concepts/modes.md) · [Config](docs/concepts/config.md) · [Audit trail](docs/concepts/audit-trail.md) · [Cost](docs/concepts/cost.md)
 
-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.
+## 30-second try
 
-Now a bigger one:
+```bash
+# opencode — add to opencode.json, then restart
+{ "plugin": ["@ionivetech/mugiwara"] }
 
-```
-> add role-based access control to the API: admin, editor, viewer roles
+# Claude Code
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
+
+# Any platform via npm
+npx @ionivetech/mugiwara@latest install --target all --yes
 ```
 
-Auth path detected → auto-escalate to Lane 3 (Full):
+First run: `/mugiwara onboard` for guided setup. Then ask something non-trivial:
 
 ```
-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.
+> 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
 ```
 
-At closure you get a mission report:
+A Standard lane mission (~10k 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.
 
-```
-.mugiwara/reports/2026-08-11-rbac.md
+→ [Full walkthrough](docs/getting-started.md)
 
-Lane full · Mode guided · Actor you · Branch feature/feat-rbac
+## How it works
 
-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
-```
+You ask. The crew routes automatically. **No agent names to memorize, no
+pipeline config to write.**
 
-One file. Any reviewer reads it in 30 seconds. That's the governance trail.
-
-## Capabilities
-
-| Capability | What it does |
-|-----------|-------------|
-| **14 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.
+| You say                                        | What happens                                                                                                                                                                             |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `add search bar to products page`              | Luffy triages → Nami plans 3 tasks → Zoro executes TDD → Chopper audits → Sanji runs quality → Franky gates → Robin reviews → code pushed, PR summary ready                              |
+| `split payment system: gateway, ledger, fraud` | Nami interviews team → writes initiative plan with sub-missions + assignees → each dev works in own branch → `mugiwara initiative status` shows progress → all done → initiative closure |
+| `Brook, fix the failing login test`            | Healer reads failure ledger, root-cause fixes, proves fix ≤3 cycles                                                                                                                      |
+| `Jinbe, audit auth middleware`                 | STRIDE + OWASP + dependency audit. Read-only — never touches code                                                                                                                        |
+| `/mugiwara auto`                               | Switches to full autonomy from the next wave                                                                                                                                             |
+
+- **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 workflow walkthrough](docs/concepts/workflow.md)
 
 ## The crew
 
-14 agents, 26 skills. The front door is the `using-mugiwara` skill — type `/using-mugiwara` or load it from any platform. Each agent has 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 14 agents](docs/agents.md) and [all 26 skills](docs/skills.md).
+12 user-facing specialists (+3 internal). Each has role boundaries — auditors
+and reviewers are read-only. Call them by name or let the pipeline auto-route.
 
-## Install
+| Agent                | Role                                                                                    |  Permission   |
+| -------------------- | --------------------------------------------------------------------------------------- | :-----------: |
+| `luffy-orchestrator` | Captain — triage, check-ins, closure                                                    |       —       |
+| `usopp-brainstorm`   | Critical friend — interrogates, researches, recommends                                  |       —       |
+| `nami-planner`       | Planner — interviews, full scan, scaled plans, team initiatives                         |       —       |
+| `zoro-execution`     | Executor — TDD per task, evidence per commit                                            |       —       |
+| `chopper-checkpoint` | Auditor — re-runs criteria, failure ledger                                              | **read-only** |
+| `sanji-quality`      | Quality — format, lint, test, duplication, complexity, maintainability, code attributes |       —       |
+| `franky-gates`       | Gates — coverage, build, DoD, per-condition sonar gate                                  |       —       |
+| `robin-reviewer`     | Reviewer — breaking-change map, reliability rating, code attribute deep review          | **read-only** |
+| `jinbe-security`     | Security — STRIDE, OWASP, hotspots, SCA license, secret scan, responsibility            | **read-only** |
+| `brook-healing`      | Healer — reads ledger, root-cause fixes ≤3 cycles                                       |       —       |
+| `onboarding-guide`   | Onboarding wizard — 10Q guided setup, writes config                                     |       —       |
+| `resume-coordinator` | Resumer — rebuilds state from `.mugiwara/`, continues never restarts                    |       —       |
+
+**Internal agents** (dispatch-only):
+
+| Agent              | Role                                                  | Used by                        |
+| ------------------ | ----------------------------------------------------- | ------------------------------ |
+| `skeptic-verifier` | Adversarial verifier — doubts every claim             | Wave 4.5, high-stakes missions |
+| `eval-runner`      | Harness tester — task suites, judge rubric            | `bun scripts/run-evals.ts`     |
+| `memory-keeper`    | Lessons ledger — surface at start, capture at closure | Wave 0 (read), Wave 9 (write)  |
+
+→ [Agent details: summoning, boundaries, parameters](docs/concepts/agents.md)
+
+## How much it costs
+
+Mugiwara itself is free. Token usage depends on mission lane:
+
+| Lane                | Waves | Typical tokens |
+| ------------------- | :---: | :------------: |
+| Direct (typo)       |   0   |       ~0       |
+| Lean (small bug)    |   2   |      ~4k       |
+| Standard (feature)  |  5–7  |      ~10k      |
+| Full (architecture) | 9–11  |      ~20k      |
+
+Usage tracked in `.mugiwara/state.json` per mission. Budget warns at 1.5×,
+pauses at 3×.
 
-Mugiwara installs as a native plugin on every platform. Full details in the per-platform guides.
+→ [Full cost model](docs/concepts/cost.md)
 
-| Platform | Guide |
-|----------|-------|
-| **Claude Code** | [`/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara`](docs/install-claude.md) |
-| **OpenCode** | [`{ "plugin": ["@ionivetech/mugiwara"] }`](docs/install-opencode.md) |
-| **Gemini CLI** | [`gemini extensions install https://github.com/ionivetech/mugiwara`](docs/install-gemini.md) |
-| **Codex** | [`codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara`](docs/install-codex.md) |
-| **Copilot** | [`copilot plugin install https://github.com/ionivetech/mugiwara`](docs/install-copilot.md) |
-| **Cursor** | [`/add-plugin mugiwara`](docs/install-cursor.md) |
-| **Antigravity** | [`agy plugin install https://github.com/ionivetech/mugiwara`](docs/install-antigravity.md) |
-| **Kimi** | [`/plugins install https://github.com/ionivetech/mugiwara`](docs/install-kimi.md) |
-| **Pi** | [`pi install git:github.com/ionivetech/mugiwara`](docs/install-pi.md) |
-| **Windsurf / Cline / Kilo** | [`npx @ionivetech/mugiwara install --target <id> --yes`](docs/install-cli.md) |
+## 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                 |
+| `base`              | main                            | PR target branch                               |
+| `coverage_new`      | 90                              | Coverage threshold for new files (%)           |
+| `coverage_modified` | 80                              | Coverage threshold for modified files (%)      |
+| `review_depth`      | full                            | full / standard / quick — Robin's review depth |
+| `quality_depth`     | full                            | full / standard / quick — Sanji's check depth  |
+
+Set via `/mugiwara onboard` or edit directly. Unknown keys ignored. Project
+config (`.mugiwara/config`) overrides global (`~/.mugiwara/config`).
+
+→ [All config keys](docs/concepts/config.md) · [Mode details](docs/concepts/modes.md)
+
+## Quick reference
+
+| Need                    | Command / Doc                            |
+| ----------------------- | ---------------------------------------- |
+| First-time setup        | `/mugiwara onboard`                      |
+| Plan a feature          | `/mugiwara-plan` or just describe it     |
+| Review a PR diff        | `/mugiwara-review` or "review this PR"   |
+| Security audit          | `/mugiwara-security` or "Jinbe, audit X" |
+| Ship gate check         | `/mugiwara-ship`                         |
+| See initiative progress | `mugiwara initiative status <plan>`      |
+| Resume a mission        | `/mugiwara resume plan <name>`           |
+| Switch mode             | `/mugiwara guided\|semi\|auto`           |
+| Check gate locally      | `bun run gate`                           |
+| All docs                | [docs/](docs/)                           |
 
-→ **[Full install guide with troubleshooting](docs/install.md)**
+## Install
 
-### Claude Code
+<details>
+<summary><b>Claude Code</b></summary>
 
 ```bash
-/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
 ```
 
-Update: `/plugin update mugiwara`
 Uninstall: `/plugin uninstall mugiwara`
 
-### OpenCode
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
 
 Add to `opencode.json`:
 
@@ -186,155 +209,155 @@ Add to `opencode.json`:
 { "plugin": ["@ionivetech/mugiwara"] }
 ```
 
-Update: replace the plugin entry version, or `npm update @ionivetech/mugiwara`
-Uninstall: remove the plugin entry from `opencode.json`.
+Uninstall: remove `"@ionivetech/mugiwara"` from `opencode.json` plugins array
 
-Restart opencode after install.
+</details>
 
-### Gemini CLI
+<details>
+<summary><b>Gemini CLI</b></summary>
 
 ```bash
 gemini extensions install https://github.com/ionivetech/mugiwara
 ```
 
-Update: `gemini extensions update mugiwara`
-Uninstall: `gemini extensions remove mugiwara`
+Uninstall: `gemini extensions uninstall mugiwara`
 
-### Codex
+</details>
+
+<details>
+<summary><b>Codex</b></summary>
 
 ```bash
 codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara
 ```
 
-Update: `codex plugin update mugiwara`
-Uninstall: `codex plugin remove mugiwara`
+Uninstall: `codex plugin remove mugiwara@mugiwara`
+
+</details>
 
-### GitHub Copilot
+<details>
+<summary><b>GitHub Copilot</b></summary>
 
 ```bash
 copilot plugin install https://github.com/ionivetech/mugiwara
 ```
 
-Update: reinstall with the same command.
 Uninstall: `copilot plugin uninstall mugiwara`
 
-### Cursor
+</details>
 
-```
+<details>
+<summary><b>Cursor</b></summary>
+
+```bash
 /add-plugin mugiwara
 ```
 
-Update: re-run `/add-plugin mugiwara`.
 Uninstall: `/remove-plugin mugiwara`
 
-### Antigravity
+</details>
+
+<details>
+<summary><b>Antigravity</b></summary>
 
 ```bash
 agy plugin install https://github.com/ionivetech/mugiwara
 ```
 
-Update: reinstall with the same command.
 Uninstall: `agy plugin uninstall mugiwara`
 
-### Kimi
+</details>
 
-```
+<details>
+<summary><b>Kimi</b></summary>
+
+```bash
 /plugins install https://github.com/ionivetech/mugiwara
 ```
 
-Update: reinstall.
-Uninstall: `/plugins remove mugiwara`
+Uninstall: `/plugins uninstall mugiwara`
+
+</details>
 
-### Pi
+<details>
+<summary><b>Pi</b></summary>
 
 ```bash
 pi install git:github.com/ionivetech/mugiwara
 ```
 
-### Windsurf · Cline · Kilo · Codex CLI
+Uninstall: `pi uninstall mugiwara`
+
+</details>
+
+<details>
+<summary><b>Windsurf / Cline / Kilo</b> — CLI install</summary>
 
 ```bash
-npx @ionivetech/mugiwara@latest install --project . --target all --yes
+npx @ionivetech/mugiwara@latest install --target <id> --yes
 ```
 
-Substitute `all` with a specific target: `windsurf`, `cline`, `kilo`, `codex`, etc.
+Uninstall: `npx @ionivetech/mugiwara@latest uninstall`
 
-Update: `mugiwara update`
-Uninstall: `mugiwara uninstall`
+Targets: `windsurf`, `cline`, `kilo`, `codex`.
 
-### Any agent (skills only)
+</details>
+
+<details>
+<summary><b>Global CLI</b> — shorter commands after first install</summary>
 
 ```bash
-npx skills add ionivetech/mugiwara   # 70+ agents via skills.sh
+npm i -g @ionivetech/mugiwara
+mugiwara install --target all --yes
 ```
 
-### One-liner
+Uninstall: `mugiwara uninstall`
 
-```bash
-# 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
-```
+</details>
 
-Requires **Node.js >= 20.11**.
+All platforms get the full crew — 12 agents, 26 skills (+3 internal agents).
+No per-platform feature gaps.
 
-## Configuration
+→ [Per-platform guides](docs/install/index.md)
 
-`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global).
+## Update
 
-| 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 |
+```bash
+npm update @ionivetech/mugiwara                           # npm-based
+/plugin update mugiwara                                   # marketplace-based
+# Reinstall with same install command                     # GitHub-based
+```
 
-[Full config →](docs/config.md)
+→ [Full update reference](docs/install/index.md)
 
 ## CLI
 
 ```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
+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
 ```
 
-## When not to use mugiwara
+## Docs
 
-- **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.
+**Start here:** [Getting started](docs/getting-started.md) · [What mugiwara replaces](docs/concepts/comparison.md)
 
-Mugiwara is for visibility, governance, and cost awareness. If those don't
-matter to you, this is the wrong tool.
+**Concepts:** [Workflow](docs/concepts/workflow.md) · [Lanes](docs/concepts/lanes.md) · [Modes](docs/concepts/modes.md) · [Execution model](docs/concepts/execution-model.md) · [Git strategy](docs/concepts/git-strategy.md) · [Config](docs/concepts/config.md) · [Cost](docs/concepts/cost.md) · [Audit trail](docs/concepts/audit-trail.md)
 
-## Docs
+**Crew:** [Agents](docs/concepts/agents.md) · [Skills](docs/concepts/skills.md)
+
+**Reference:** [Agent anatomy](docs/reference/agent-anatomy.md) · [Skill anatomy](docs/reference/skill-anatomy.md) · [Harness matrix](docs/reference/harness-matrix.md) · [Compliance matrix](docs/reference/compliance-matrix.md) · [Developer onboarding](docs/reference/developer-onboarding.md)
+
+**Install per platform:** [Overview](docs/install/index.md) · [Claude](docs/install/claude.md) · [opencode](docs/install/opencode.md) · [Gemini](docs/install/gemini.md) · [Codex](docs/install/codex.md) · [Copilot](docs/install/copilot.md) · [CLI targets](docs/install/cli.md)
+
+**Troubleshooting:** [Common problems](docs/troubleshooting.md)
 
-| Doc | What it covers |
-|-----|---------------|
-| [Getting started](docs/getting-started.md) | First mission, lane 0-3 examples, setup walkthrough |
-| [Install](docs/install.md) | Per-platform guides: Claude Code, OpenCode, Gemini, Codex, Copilot, Cursor, Antigravity, Kimi, Pi, CLI |
-| [Workflow](docs/workflow.md) | Full 9-wave pipeline with heal loop detail |
-| [Agents](docs/agents.md) | 14 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 |
+**Roadmap:** [ROADMAP.md](ROADMAP.md)
 
 ## License
 
-MIT. Copyright (c) 2026 ionive.
+MIT. Copyright (c) 2026 ionivetech.

package/content/agents/brook-healing.md

@@ -1,11 +1,21 @@
 ---
 name: brook-healing
-description: Persona for mugiwara-healing. Root-cause healer: reads entire blocker ledger, triages + groups failures, spawns parallel heal workers for independent fixes, max 3 cycles.
-skills: mugiwara-healing, mugiwara-git, mugiwara-sunset, mugiwara-root-cause
+description: Persona for mugiwara-healing. Root-cause healer: reads blocker ledger, triages failures, spawns parallel heal workers, max 3 cycles.
+skills: mugiwara-healing, mugiwara-git, mugiwara-sunset, mugiwara-root-cause, mugiwara-orchestration
+write-scope: source
 ---
 
 # Brook — Healing (Musician)
 
+## Before you start
+
+1. Read `.mugiwara/state.json` for this branch.
+2. No active mission → announce `## Wave 0 — Luffy (triage)`, classify the request, size the lane (`scripts/lane.sh`), read the mode, write the decision log, run `scripts/savepoint.sh`.
+3. Mission owned by another actor → stop, report the owner, ask.
+4. `base_sha` no longer an ancestor of HEAD → report drift, ask before continuing.
+5. Not a git repo → lane defaults to `standard`, state in-memory; say so once.
+6. Announce `→ Wave N — <crew>`. **If triage routed elsewhere, say so and stop.** Being summoned is not authorisation to do another crew member's job.
+
 ## Role
 
 Self-healing: repairs what failed in earlier waves, minimally, and proves each fix. Reads the failure ledger and works it down.
@@ -31,7 +41,11 @@ Wave 8 of `mugiwara-workflow`, with failure inputs from Chopper/Sanji/Franky/Rob
 
 ## Output
 
-Fixed list + escalated list in `.mugiwara/results/<mission>-healing.md` → summarized inline → back to Wave 4 (Chopper) for re-audit.
+Fixed list + escalated list in `.mugiwara/results/<mission>/05-healing.md` → summarized inline → back to Wave 4 (Chopper) for re-audit.
+
+## Return to Luffy
+
+Your output returns to Luffy. You do not choose the next step and you do not dispatch another crew member. Any decision outside your role — scope, lane, whether to build, who runs next — is Luffy's, always.
 
 ## Red flags