@ionivetech/mugiwara 0.5.5 → 0.6.1

package/README.md

@@ -4,10 +4,12 @@
 [![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)
 
-**Ship quality code, not just fast code.** Mugiwara gives your AI agent a
-governed engineering team — 14 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.
+**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 waves. 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.
 
@@ -21,22 +23,63 @@ every agent, every skill, every rule is static markdown.
 
 → [Full pitch: why mugiwara vs just asking your agent](docs/concepts/comparison.md)
 
-## Capabilities
-
-| Feature | What you get |
-|---------|-------------|
-| **Zero runtime** | Pure markdown. No servers, no API keys, no dependencies beyond your agent. |
-| **14 specialist agents** | Each with tuned temperature, step limits, and role boundaries. Read-only auditors. |
-| **26 skills** | Portable playbooks: TDD execution, STRIDE security, 4-phase debugging, contract-first API design |
-| **Deterministic lane sizing** | Work auto-sized from `git diff`. Typo = instant fix. Auth migration = full 9-wave pipeline. |
-| **9-wave gated pipeline** | Triage → Brainstorm → Plan → Execute → Audit → Quality → Gates → Review+Security → Heal → Closure |
-| **Evidence trail** | `.mugiwara/` workspace on disk: plans, audit reports, blocker ledger, mission reports. Reviewer reads in 30s. |
-| **Self-healing** | Brook reads all failures at once, fixes root causes, re-runs verification. ≤3 cycles. |
-| **3 autonomy modes** | Guided (human steers) / Semi (auto branch+commit) / Auto (hands-off). Switch mid-session. |
-| **12 platforms** | Native plugins for Claude Code, opencode, Copilot, Gemini, Codex, Cursor, Kimi, Pi, Antigravity. CLI for Windsurf, Cline, Kilo. |
-| **Cost aware** | Token budget per lane. Warn at 1.5×, pause at 3×. Cost surfaced in every mission report. |
-| **Multi-actor safe** | Two engineers, one repo. Reset refuses without `--force`. Branch-scoped state. |
-| **Compliance matrix** | Rule compliance per model published with failures. Gemini tier 2 ≠ Claude tier 1. Documented, not hidden. |
+## See the evidence
+
+A closed mission leaves a report you can actually read. This is the exact
+format `scripts/mission-report.sh` produces:
+
+    # Mission: invitation-accepted-flow . 2026-08-11
+
+    **Lane** full . **Mode** guided . **Actor** farid . **Branch** feature/MKR-412
+
+    ## What changed
+
+    11 files, +340 LOC
+    Sensitive paths: src/auth/
+
+    ## Waves
+
+    | Wave | Artifact | Verdict |
+    |------|----------|---------|
+    | Execute (Wave 3) | `01-execution.md` | PASS |
+    | Checkpoint (Wave 4) | `02-audit.md` | PASS |
+    | Quality (Wave 5) | `03-quality.md` | PASS |
+    | Gates (Wave 6) | `04-gates.md` | PASS |
+    | Healing (Wave 8) | `05-healing.md` | PASS |
+    | Closure (Wave 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 |
+    |-------|-------|
+    | Wave | 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 waves. Mugiwara itself is free; token usage depends on the 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×.
+
+→ [Full cost model](docs/concepts/cost.md)
 
 ## 30-second try
 
@@ -51,109 +94,256 @@ every agent, every skill, every rule is static markdown.
 npx @ionivetech/mugiwara@latest install --target all --yes
 ```
 
-Then ask something non-trivial. The crew auto-activates:
+First run: `/mugiwara onboard` for guided setup. 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 (~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. See it work: [docs/getting-started.md](docs/getting-started.md).
-
-## How it works
+at every step in your chat.
 
 You ask. The crew routes automatically. **No agent names to memorize, no
-pipeline config to write.** The work is sized from your git diff (typo = instant
-fix; auth migration = full 9-wave pipeline).
-
-| You say | What happens |
-|---------|-------------|
-| `add search bar to products page` | Luffy triages → Nami plans 3 tasks → Zoro executes TDD → Chopper audits → Sanji runs tests → Franky gates coverage → Robin reviews → code pushed, PR summary ready |
-| `Brook, fix the failing login test` | Healer reads failure ledger, root-cause fixes, proves fix ≤3 cycles. No pipeline overhead |
-| `Jinbe, audit auth middleware` | Security specialist runs STRIDE + OWASP. Read-only — never touches code |
-| `/mugiwara semi` | Switches to semi-autonomous mode: auto branch + commit, plan still needs your GO |
-
-- **Full pipeline** when the task is big or direction is unclear — Luffy figures it out
-- **Direct agent** when you know exactly what you need — just say the name
-- **Slash commands** when you want to drive:`/mugiwara-plan`, `/mugiwara-review`, `/mugiwara-security`, `/mugiwara-ship`
+pipeline config to write.**
+
+| 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 walkthrough](docs/getting-started.md) · [Full workflow walkthrough](docs/concepts/workflow.md)
+
+## What Mugiwara does
+
+### All features
+
+| Feature                  | What you get                                                                           |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| **Lane sizing**          | Work auto-sized from `git diff`. Typo = instant fix. Auth migration = full pipeline.   |
+| **Evidence trail**       | `.mugiwara/` workspace: plans, audit reports, quality reports, review findings, blocker ledger. |
+| **Self-healing**         | Brook reads all failures at once, fixes root causes, re-runs verification. ≤3 cycles.  |
+| **Resume from anywhere** | Session lost? Rebuilds from `.mugiwara/state.json`. Continues, never restarts.         |
+| **12 platforms**         | Claude Code, opencode, Copilot, Gemini, Codex, Cursor, Kimi, Pi, Antigravity + CLI.    |
+
+→ All 19 features, with how-to-use + scenarios: [Every feature](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)
+
+## The pipeline
+
+```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
+```
 
-[Full workflow walkthrough →](docs/concepts/workflow.md)
+→ [Full pipeline details](docs/concepts/workflow.md)
 
 ## The crew
 
-14 specialists. Each has a role boundary (read-only for auditors/reviewers), a
-temperature, and a step limit. Call them by name or let the pipeline auto-route.
-
-| Agent | Role | Permission |
-|-------|------|:---:|
-| `luffy-orchestrator` | Captain — triage, check-ins, closure | — |
-| `nami-planner` | Planner — interviews, full scan, scaled plans | — |
-| `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 | — |
-| `franky-gates` | Gates — coverage, build, DoD verdict | — |
-| `robin-reviewer` | Reviewer — breaking-change map | **read-only** |
-| `jinbe-security` | Security — STRIDE, OWASP, secret scan | **read-only** |
-| `brook-healing` | Healer — reads ledger, root-cause fixes ≤3 cycles | — |
-| `usopp-brainstorm` | Critical friend — interrogates, researches | — |
-| `skeptic-verifier` | Adversarial verifier — doubts, never validates | **read-only** |
-| `eval-runner` | Harness tester — task suites | — |
-| `resume-coordinator` | Resumer — rebuilds from state.json | — |
-| `memory-keeper` | Institutional memory — past lessons | — |
-
-> The names are One Piece characters — just code names for specialist roles.
-> Agents are identified by their function (Orchestrator, Planner, Auditor, etc.),
-> not by their theme. The theme makes them memorable; the boundaries make them
-> safe.
+12 agents (+3 internal). Each has role boundaries — auditors
+and reviewers are read-only. Call them by name or let the pipeline auto-route.
+
+| 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
+## When not to use Mugiwara
 
-Mugiwara itself is free. Token usage depends on mission lane:
+- **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.
 
-| Lane | Waves | Typical tokens |
-|------|:-----:|:--------------:|
-| Direct (typo) | 0 | ~0 |
-| Lean (small bug) | 2 | ~4k |
-| Standard (feature) | 5–7 | ~10k |
-| Full (architecture) | 9–11 | ~20k |
+## Configuration
 
-Usage tracked in `.mugiwara/state.json` per mission. Budget warns at 1.5×,
-pauses at 3×. See [cost model](docs/concepts/cost.md) for per-model pricing reference.
+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)
 
-→ [Full cost model and token budget](docs/concepts/cost.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/)                           |
 
 ## Install
 
-<details open>
-<summary><b>Native plugins</b> — one-command install</summary>
-
-| Platform | Command |
-|----------|---------|
-| **Claude Code** | `/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara` |
-| **OpenCode** | Add `{ "plugin": ["@ionivetech/mugiwara"] }` to `opencode.json` |
-| **Gemini CLI** | `gemini extensions install https://github.com/ionivetech/mugiwara` |
-| **Codex** | `codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara` |
-| **Copilot** | `copilot plugin install https://github.com/ionivetech/mugiwara` |
-| **Cursor** | `/add-plugin mugiwara` |
-| **Antigravity** | `agy plugin install https://github.com/ionivetech/mugiwara` |
-| **Kimi** | `/plugins install https://github.com/ionivetech/mugiwara` |
-| **Pi** | `pi install git:github.com/ionivetech/mugiwara` |
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
+```
+
+Uninstall: `/plugin uninstall mugiwara`
+
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
+
+Add to `opencode.json`:
+
+```json
+{ "plugin": ["@ionivetech/mugiwara"] }
+```
+
+Update: `rm -rf ~/.cache/opencode/packages/@ionivetech/mugiwara* && opencode plugin @ionivetech/mugiwara -g` ([details](docs/install/opencode.md#update))
+
+Uninstall: remove `"@ionivetech/mugiwara"` from `opencode.json` plugins array
+
+</details>
+
+<details>
+<summary><b>Gemini CLI</b></summary>
+
+```bash
+gemini extensions install https://github.com/ionivetech/mugiwara
+```
+
+Uninstall: `gemini extensions uninstall mugiwara`
 
 </details>
 
 <details>
-<summary><b>CLI install</b> — Windsurf, Cline, Kilo, and more</summary>
+<summary><b>Codex</b></summary>
+
+```bash
+codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara
+```
+
+Uninstall: `codex plugin remove mugiwara@mugiwara`
+
+</details>
+
+<details>
+<summary><b>GitHub Copilot</b></summary>
+
+```bash
+copilot plugin install https://github.com/ionivetech/mugiwara
+```
+
+Uninstall: `copilot plugin uninstall mugiwara`
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+```bash
+/add-plugin mugiwara
+```
+
+Uninstall: `/remove-plugin mugiwara`
+
+</details>
+
+<details>
+<summary><b>Antigravity</b></summary>
+
+```bash
+agy plugin install https://github.com/ionivetech/mugiwara
+```
+
+Uninstall: `agy plugin uninstall mugiwara`
+
+</details>
+
+<details>
+<summary><b>Kimi</b></summary>
+
+```bash
+/plugins install https://github.com/ionivetech/mugiwara
+```
+
+Uninstall: `/plugins uninstall mugiwara`
+
+</details>
+
+<details>
+<summary><b>Pi</b></summary>
+
+```bash
+pi install git:github.com/ionivetech/mugiwara
+```
+
+Uninstall: `pi uninstall mugiwara`
+
+</details>
+
+<details>
+<summary><b>Windsurf / Cline / Kilo</b> — CLI install</summary>
 
 ```bash
 npx @ionivetech/mugiwara@latest install --target <id> --yes
-# or all targets
-npx @ionivetech/mugiwara@latest install --target all --yes
 ```
 
-Targets: `windsurf`, `cline`, `kilo`, `codex`. See [install/cli](docs/install/cli.md) for interactive wizard.
+Uninstall: `npx @ionivetech/mugiwara@latest uninstall`
+
+Targets: `windsurf`, `cline`, `kilo`, `codex`.
 
 </details>
 
@@ -163,69 +353,63 @@ Targets: `windsurf`, `cline`, `kilo`, `codex`. See [install/cli](docs/install/cl
 ```bash
 npm i -g @ionivetech/mugiwara
 mugiwara install --target all --yes
-mugiwara update --target all --yes
-mugiwara uninstall
 ```
 
+Uninstall: `mugiwara uninstall`
+
 </details>
 
-All platforms get the full crew — 14 agents, 26 skills. No per-platform feature gaps.
+All platforms get the full crew — 12 agents (+3 internal), 26 skills.
+Enforcement depth varies by harness; see the [harness matrix](docs/reference/harness-matrix.md).
 
-→ [Per-platform guides with update/verify/troubleshooting](docs/install/index.md)
+→ [Per-platform guides](docs/install/index.md)
 
 ## Update
 
 ```bash
-# npm-based (opencode, CLI targets)
-npm update @ionivetech/mugiwara
+# 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
 
-# marketplace-based (Claude, Codex)
+# Claude Code — marketplace
 /plugin update mugiwara
 
-# GitHub-based (Copilot, Gemini, Cursor, Antigravity, Kimi)
-# Reinstall with the same install command — pulls latest release
+# CLI — npm global
+npm i -g @ionivetech/mugiwara@latest
 ```
 
-→ [Full update reference per platform](docs/install/index.md)
+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](docs/install/index.md)
 
 ## CLI
 
 ```bash
-mugiwara install                                  # wizard (interactive)
-npx @ionivetech/mugiwara@latest install --yes     # non-interactive (project + all)
-mugiwara update --target <id> --yes               # overwrite to latest
-mugiwara uninstall                                # remove installed files
-mugiwara list                                     # show installations
-mugiwara list --check                             # health check (missing files)
-mugiwara reset --keep-logs                        # wipe state, keep lessons
+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
 ```
 
-## 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 |
-
-→ [All config keys](docs/concepts/config.md) · [Mode details](docs/concepts/modes.md)
-
 ## Docs
 
-Getting started & concepts: **[Getting started](docs/getting-started.md)** · [What mugiwara replaces](docs/concepts/comparison.md) · [Execution model](docs/concepts/execution-model.md) · [Git strategy](docs/concepts/git-strategy.md)
+**Start here:** [Getting started](docs/getting-started.md) · [What mugiwara replaces](docs/concepts/comparison.md)
+
+**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)
 
-Crew & techniques: **[Agents](docs/concepts/agents.md)** · [Skills](docs/concepts/skills.md) · [Workflow](docs/concepts/workflow.md) · [Lanes](docs/concepts/lanes.md) · [Modes](docs/concepts/modes.md)
+**Crew:** [Agents](docs/concepts/agents.md) · [Skills](docs/concepts/skills.md)
 
-Operations: [Config](docs/concepts/config.md) · [Audit trail](docs/concepts/audit-trail.md) · [Cost](docs/concepts/cost.md) · [Harness matrix](docs/reference/harness-matrix.md) · [Compliance](docs/reference/compliance-matrix.md) · [Troubleshooting](docs/troubleshooting.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)
 
-Deep dives: [Agent anatomy](docs/reference/agent-anatomy.md) · [Skill anatomy](docs/reference/skill-anatomy.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)
 
-Install per platform: **[Install 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)
 
-Roadmap: [ROADMAP.md](ROADMAP.md)
+**Roadmap:** [ROADMAP.md](ROADMAP.md)
 
 ## License
 

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
 

package/content/agents/chopper-checkpoint.md

@@ -1,12 +1,22 @@
 ---
 name: chopper-checkpoint
-description: Persona for mugiwara-checkpoint. Audit results against the plan, never fixes code. Read-only: no code edits, no file writes outside .mugiwara/results/.
+description: Persona for mugiwara-checkpoint. Audit results against the plan. Read-only.
 permissions: read-only, can-write: .mugiwara/results/ .mugiwara/issues/
-skills: mugiwara-checkpoint
+skills: mugiwara-checkpoint, mugiwara-orchestration
+write-scope: artifacts
 ---
 
 # Chopper — Checkpoint (Auditor)
 
+## 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
 
 Audits execution against the plan. Trusts nothing; re-verifies everything — efficiently. Does not fix — findings only.
@@ -35,7 +45,11 @@ Wave 4 of `mugiwara-workflow`, with the plan doc and Zoro's execution report.
 
 ## Output
 
-Audit report to `.mugiwara/results/YYYY-MM-DD-<mission>-audit.md` + failure ledger rows in `.mugiwara/issues/` → summarized inline in the conversation (Luffy on PASS, Brook on FAIL).
+Audit report to `.mugiwara/results/<mission>/02-audit.md` + failure ledger rows in `.mugiwara/issues/` → summarized inline in the conversation (Luffy on PASS, Brook on FAIL).
+
+## 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