@ionivetech/mugiwara 0.5.5 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@
 [![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
+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.
 
@@ -21,22 +21,43 @@ 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. |
+## What Mugiwara does
+
+### 9-wave 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 pipeline details](docs/concepts/workflow.md)
+
+### All features
+
+| 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`.                  |
+
+→ [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)
 
 ## 30-second try
 
@@ -51,61 +72,67 @@ 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).
+at every step in your chat.
+
+→ [Full walkthrough](docs/getting-started.md)
 
 ## How it works
 
 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).
+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 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 |
+| 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 — 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`
+- **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)
+→ [Full workflow walkthrough](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 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.
+
+| 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)
 
@@ -113,119 +140,223 @@ temperature, and a step limit. Call them by name or let the pipeline auto-route.
 
 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 |
+| 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×. See [cost model](docs/concepts/cost.md) for per-model pricing reference.
+pauses at 3×.
+
+→ [Full cost model](docs/concepts/cost.md)
+
+## Configuration
+
+Switch mode any time: `/mugiwara guided | semi | auto`. Or edit `.mugiwara/config`:
 
-→ [Full cost model and token budget](docs/concepts/cost.md)
+| 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/)                           |
 
 ## 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>CLI install</b> — Windsurf, Cline, Kilo, and more</summary>
+<summary><b>OpenCode</b></summary>
+
+Add to `opencode.json`:
+
+```json
+{ "plugin": ["@ionivetech/mugiwara"] }
+```
+
+Uninstall: remove `"@ionivetech/mugiwara"` from `opencode.json` plugins array
+
+</details>
+
+<details>
+<summary><b>Gemini CLI</b></summary>
 
 ```bash
-npx @ionivetech/mugiwara@latest install --target <id> --yes
-# or all targets
-npx @ionivetech/mugiwara@latest install --target all --yes
+gemini extensions install https://github.com/ionivetech/mugiwara
 ```
 
-Targets: `windsurf`, `cline`, `kilo`, `codex`. See [install/cli](docs/install/cli.md) for interactive wizard.
+Uninstall: `gemini extensions uninstall mugiwara`
 
 </details>
 
 <details>
-<summary><b>Global CLI</b> — shorter commands after first install</summary>
+<summary><b>Codex</b></summary>
 
 ```bash
-npm i -g @ionivetech/mugiwara
-mugiwara install --target all --yes
-mugiwara update --target all --yes
-mugiwara uninstall
+codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara
 ```
 
+Uninstall: `codex plugin remove mugiwara@mugiwara`
+
 </details>
 
-All platforms get the full crew — 14 agents, 26 skills. No per-platform feature gaps.
+<details>
+<summary><b>GitHub Copilot</b></summary>
 
-→ [Per-platform guides with update/verify/troubleshooting](docs/install/index.md)
+```bash
+copilot plugin install https://github.com/ionivetech/mugiwara
+```
 
-## Update
+Uninstall: `copilot plugin uninstall mugiwara`
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
 
 ```bash
-# npm-based (opencode, CLI targets)
-npm update @ionivetech/mugiwara
+/add-plugin mugiwara
+```
+
+Uninstall: `/remove-plugin mugiwara`
 
-# marketplace-based (Claude, Codex)
-/plugin update mugiwara
+</details>
+
+<details>
+<summary><b>Antigravity</b></summary>
 
-# GitHub-based (Copilot, Gemini, Cursor, Antigravity, Kimi)
-# Reinstall with the same install command — pulls latest release
+```bash
+agy plugin install https://github.com/ionivetech/mugiwara
 ```
 
-→ [Full update reference per platform](docs/install/index.md)
+Uninstall: `agy plugin uninstall mugiwara`
 
-## CLI
+</details>
+
+<details>
+<summary><b>Kimi</b></summary>
 
 ```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
+/plugins install https://github.com/ionivetech/mugiwara
 ```
 
-## Configuration
+Uninstall: `/plugins uninstall mugiwara`
 
-Switch mode any time: `/mugiwara guided | semi | auto`. Or edit `.mugiwara/config`:
+</details>
 
-| 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 |
+<details>
+<summary><b>Pi</b></summary>
 
-→ [All config keys](docs/concepts/config.md) · [Mode details](docs/concepts/modes.md)
+```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
+```
+
+Uninstall: `npx @ionivetech/mugiwara@latest uninstall`
+
+Targets: `windsurf`, `cline`, `kilo`, `codex`.
+
+</details>
+
+<details>
+<summary><b>Global CLI</b> — shorter commands after first install</summary>
+
+```bash
+npm i -g @ionivetech/mugiwara
+mugiwara install --target all --yes
+```
+
+Uninstall: `mugiwara uninstall`
+
+</details>
+
+All platforms get the full crew — 12 agents, 26 skills (+3 internal agents).
+No per-platform feature gaps.
+
+→ [Per-platform guides](docs/install/index.md)
+
+## Update
+
+```bash
+npm update @ionivetech/mugiwara                           # npm-based
+/plugin update mugiwara                                   # marketplace-based
+# Reinstall with same install command                     # GitHub-based
+```
+
+→ [Full update reference](docs/install/index.md)
+
+## CLI
+
+```bash
+mugiwara install                              # wizard (interactive)
+mugiwara install --target all --yes           # non-interactive
+mugiwara update --target <id> --yes           # overwrite to latest
+mugiwara uninstall                            # remove installed files
+mugiwara list                                 # show installations
+mugiwara list --check                         # health check
+mugiwara reset --keep-logs                    # wipe state, keep lessons
+```
 
 ## Docs
 
-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
 

package/content/agents/eval-runner.md

@@ -1,11 +1,22 @@
 ---
 name: eval-runner
 description: Persona for docs/evals.md. Harness tester: task suites, judge-agent rubric, pass/fail per case.
+internal: true
 skills: mugiwara-orchestration
+write-scope: artifacts
 ---
 
 # Eval-Runner — Test Engineer (for the Harness)
 
+## 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
 
 Test engineer for the harness itself. Writes task suites, runs them, judges rubric-comparison, reports pass/fail per case. Verifies skills and agents actually work. Files failures — never fixes the skill under test.
@@ -27,14 +38,18 @@ Harness test engineer who fixes the skill, not the eval. Abilities: rubric judgi
 2. At least one case per skill; full suite run per release.
 3. Judge with a FRESH agent, never the implementer of the case's skill.
 4. A failing case means fix the SKILL, never the eval.
-5. Write the pass/fail table to `.mugiwara/results/<mission>-eval.md`.
+5. Write the pass/fail table to `.mugiwara/results/<mission>/eval.md`.
 6. Route failures to `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` (category `eval-fail`) → Brook.
 7. Ranking/selection cases → tournament judging (`mugiwara-orchestration` (adversarial verification)): pairwise, fresh judge per match.
 8. Never assert on host-agent behavior — only that the skill's instructions produce the intended workflow.
 
 ## Output
 
-Pass/fail table with evidence in `.mugiwara/results/<mission>-eval.md` → summarized inline (Luffy); failing cases route via the blocker ledger to Brook.
+Pass/fail table with evidence in `.mugiwara/results/<mission>/eval.md` → summarized inline (Luffy); failing cases route via the blocker ledger to Brook.
+
+## 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/franky-gates.md

@@ -1,14 +1,24 @@
 ---
 name: franky-gates
-description: Persona for mugiwara-gates. Coverage + build + DoD gates. Binary verdicts, no negotiation.
-skills: mugiwara-gates, mugiwara-ship, mugiwara-testcases
+description: Persona for mugiwara-gates. Granular sonar gate, coverage + build + DoD. Binary verdicts, no negotiation.
+skills: mugiwara-gates, mugiwara-ship, mugiwara-testcases, mugiwara-orchestration
+write-scope: artifacts
 ---
 
 # Franky — Gates (Shipwright)
 
+## 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
 
-Guards the quality gates and, at release time, the ship gate. Binary verdicts only — PASS/FAIL, GO/NO-GO — each backed by evidence.
+Guards granular quality gate: vulnerabilities, bugs, code smells, duplications, security hotspots — each with threshold. Guards ship gate at release. Binary verdicts only — PASS/FAIL, GO/NO-GO — each backed by evidence.
 
 ## Experience
 
@@ -25,11 +35,15 @@ Wave 6 of `mugiwara-workflow` (after Sanji's report passes) and again at release
 3. At release, run `mugiwara-ship`: pre-launch checklist, feature flags, staged rollout, mandatory rollback plan.
 4. When user ACs are declared (per `mugiwara-testcases`), the coverage thresholds (90/80) apply only to unit-level new/modified code; the user-AC verdict governs ship-readiness. An e2e user suite adding ~0% coverage is not a gate failure. The user-AC verdict must come from the quality wave evidence, never asserted.
 5. Ship verdict is binary with evidence; a critical finding or a missing rollback plan → NO-GO.
-6. Write verdicts and evidence to `.mugiwara/results/`.
+6. Write verdicts and evidence to `.mugiwara/results/<mission>/04-gates.md`.
 
 ## Output
 
-Gate verdict + ship-gate verdict with evidence in `.mugiwara/results/` → summarized inline (Robin/Jinbe on pass, Brook on fail).
+Gate verdict + ship-gate verdict with evidence in `.mugiwara/results/<mission>/04-gates.md` → summarized inline (Robin/Jinbe 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