@ionivetech/mugiwara 0.1.3 → 0.2.0

package/README.md

@@ -2,11 +2,6 @@
 
 [![npm version](https://img.shields.io/npm/v/@ionivetech%2fmugiwara)](https://www.npmjs.com/package/@ionivetech/mugiwara)
 [![License: MIT](https://img.shields.io/github/license/ionivetech/mugiwara)](https://github.com/ionivetech/mugiwara/blob/main/LICENSE)
-[![npm downloads](https://img.shields.io/npm/dm/@ionivetech%2fmugiwara)](https://www.npmjs.com/package/@ionivetech/mugiwara)
-[![CI](https://img.shields.io/github/actions/workflow/status/ionivetech/mugiwara/ci.yml?branch=main&label=ci)](https://github.com/ionivetech/mugiwara/actions)
-[![TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6)](https://github.com/ionivetech/mugiwara)
-[![Bun](https://img.shields.io/badge/bundler-Bun-black)](https://bun.sh)
-[![GitHub](https://img.shields.io/badge/GitHub-ionivetech%2Fmugiwara-181717?logo=github)](https://github.com/ionivetech/mugiwara)
 
 The Straw Hat crew of AI agents and skills.
 
@@ -18,8 +13,8 @@ machinery — no daemons, no plugins to keep updated, nothing to host.
 - 🧭 **A named crew.** Ten specialist agents — Luffy orchestrates, Nami plans,
   Zoro executes, Chopper audits, Brook heals — each with a narrow job.
 - 📦 **No runtime.** Ships markdown only: native skills and agents for
-  Claude Code, opencode, Copilot, Gemini CLI, Codex, Windsurf, Cline,
-  Kilo Code, and Antigravity.
+  Claude Code, opencode, Copilot, Gemini CLI, Codex, Cursor, Kimi, pi,
+  Windsurf, Cline, Kilo Code, and Antigravity.
 - 🔁 **Wave pipeline.** brainstorm → plan → execute → audit → quality → gates
   → review → security → heal → closure. Failure loops back through healing
   (max 3 cycles), never ships broken.
@@ -32,8 +27,9 @@ machinery — no daemons, no plugins to keep updated, nothing to host.
 
 ### The crew — 15 agents
 
-Each agent is a focused specialist. Agents are dispatched by your AI tool's
-subagent machinery and may call the crew's shared skills.
+Each agent is a focused specialist. The main thread embodies each crew role
+inline using its skill; agents may also be summoned directly by your AI tool's
+agent machinery and may call the crew's shared skills.
 
 | Agent | Crew member | Role |
 |-------|-------------|------|
@@ -41,8 +37,8 @@ subagent machinery and may call the crew's shared skills.
 | `luffy-orchestrator` | Luffy | Main gateway: 5-way triage, background check-ins, work splitting, decision log, closure |
 | `usopp-brainstorm` | Usopp | Critical brainstorming friend: facts over hype, options + trade-offs, no over-engineering |
 | `nami-planner` | Nami | Interview-first planner: full-context scan, wave structure, anti-patterns, parallel-safe plans |
-| `zoro-execution` | Zoro | Execute plans: todo list first, parallel/sequential subagent dispatch, evidence per task |
-| `chopper-checkpoint` | Chopper | Verify-everything audit of wave results; writes the failure ledger (never fixes code) |
+| `zoro-execution` | Zoro | Execute plans inline: todo list first, sequential tasks in the main thread, parallel batches via worker subagents, evidence per task |
+| `chopper-checkpoint` | Chopper | Verify-everything audit of wave results (deduped + scoped re-runs); writes the failure ledger (never fixes code) |
 | `sanji-quality` | Sanji | Discover the stack, then format/lint/test; integration tests only with consent |
 | `franky-gates` | Franky | Binary gates: coverage ≥90/80, build exit 0, Definition of Done |
 | `robin-reviewer` | Robin | Doubt-driven diff review: breaking-change first, five-axis, severity-tagged findings |
@@ -53,24 +49,28 @@ subagent machinery and may call the crew's shared skills.
 | `resume-coordinator` | Resume Coordinator | Rebuild the picture from `.mugiwara/` state after context loss; continue, never restart |
 | `memory-keeper` | Memory Keeper | Institutional memory: surface past lessons at mission start, capture new ones at closure |
 
-### The techniques — 21 skills
+### The techniques — 25 skills
 
 | Skill | Purpose |
 |-------|---------|
-| `mugiwara-workflow` | The harness entry point: gateway triage, wave pipeline, workspace layout, blocker protocol, cleanup |
+| `mugiwara-workflow` | The harness entry point: inline execution model, gateway triage, wave pipeline, workspace layout, blocker protocol, cleanup |
 | `mugiwara-orchestration` | Luffy's captain behavior: 5-way classifier, check-ins, work splitting, decision log, closure |
+| `mugiwara-mode` | Runtime levels guided / semi / auto via `.mugiwara/config`: branch + commit style, consent invariants, gated auto-GO, push + ready-PR terminal |
 | `mugiwara-brainstorm` | Usopp's critical sparring: interrogate, research facts, cut over-engineering, recommend |
 | `mugiwara-planning` | Interview-first, full-context scan, wave plans with parallel/sequential markers + anti-patterns |
-| `mugiwara-execution` | Todo list, parallel batches + sequential chains, 6-field subagent delegation, one task one commit |
-| `mugiwara-checkpoint` | Verify-everything audit of every acceptance criterion; failure rows to the blocker ledger |
-| `mugiwara-quality` | Discover the project's real tooling; formatter, linter, unit + consent-gated integration tests |
-| `mugiwara-gates` | Coverage ≥90% new / ≥80% modified files, build validation, Definition of Done |
+| `mugiwara-execution` | Todo list, sequential tasks inline + parallel worker batches, 6-field delegation for parallel work, one commit per logical task |
+| `mugiwara-checkpoint` | Verify-everything audit of every acceptance criterion — deduped and scoped to the wave's diff; failure rows to the blocker ledger |
+| `mugiwara-quality` | Discover the project's real tooling; formatter, linter, unit tests, declared user suites under the consent matrix |
+| `mugiwara-gates` | Coverage ≥90% new / ≥80% modified files, build validation, Definition of Done; user-AC verdict overrides thresholds |
+| `mugiwara-testcases` | User-test intake (ATDD): accepted formats, immutable-gold rule, declarative-AC routing, consent, failure adjudication |
 | `mugiwara-review` | Doubt-driven review: breaking-change analysis, five-axis, severity-tagged findings |
 | `mugiwara-security` | OWASP-driven security review, untrusted-data doctrine, severity by exploitability × impact |
 | `mugiwara-healing` | Reads the ledger, Stop-the-Line + Prove-It root-cause fixes, rollback prep |
+| `mugiwara-deprecation` | Sunset & migration discipline: keep-or-retire gate, cutover playbooks, safe schema changes |
 | `mugiwara-frontend` | Anti-slop frontend: audit-first redesigns, design-system extraction, slop list |
 | `mugiwara-git` | Atomic commits, save-points, multi-commit splitting, bisect/blame debugging |
 | `mugiwara-ship` | GO/NO-GO ship gate: pre-launch checklist, feature flags, rollback plan |
+| `mugiwara-pr` | CI/CD loop terminal: one verdict file + one comment + one check-run on the ready PR via `gh`, stop-at-PR invariant |
 | `mugiwara-dynamic-workflow` | Runtime workflow patterns: fan-out-and-synthesize, tournament, loop-until-done, classify-and-act, adversarial verification |
 | `mugiwara-agent-security` | Secure the agent layer: prompt injection, memory poisoning, excessive agency, secret handling, sandboxing |
 | `mugiwara-backend` | Backend/server code: repo standards first, API design, data integrity, error handling, correctness, performance, server-side security |
@@ -81,7 +81,7 @@ subagent machinery and may call the crew's shared skills.
 
 ### Every capability, always
 
-Every install ships the full crew — all 21 skills and 15 agents, including
+Every install ships the full crew — all 25 skills and 15 agents, including
 the anti-slop `mugiwara-frontend`, `mugiwara-backend`, and `mugiwara-agent-security`
 skills. No project-type selection: you get every capability, and the harness
 routes each task to the right skill.
@@ -94,24 +94,25 @@ feeds the **Luffy gateway**, which classifies the request (trivial / explicit /
 exploratory / open-ended / ambiguous) and routes it: exploratory ideas go to
 Usopp's brainstorm, clear work goes straight to Nami's planning. You can also
 summon any crew member directly. From there the mission runs as a **wave
-pipeline** owned by one crew member per wave.
+pipeline** owned by one crew member per wave, executed inline in your main
+conversation.
 
 ```mermaid
 flowchart TD
-    A[User request] --> F[using-mugiwara<br/>front door]
-    F --> B{Luffy gateway<br/>5-way triage}
-    B -- exploratory --> C[Usopp brainstorm<br/>.mugiwara/spec/]
-    B -- clear work --> D[Nami plan<br/>.mugiwara/plans/]
-    C --> D
-    D --> E[Zoro execute<br/>parallel / sequential]
-    E --> F[Chopper audit<br/>failure ledger]
-    F --> G[Sanji quality]
-    G --> H[Franky gates]
-    H --> I[Robin + Jinbe review<br/>parallel]
-    I -- pass --> J[Luffy closure<br/>ship gate]
-    I -- fail --> K[Brook heal<br/>max 3 cycles]
-    K --> F
-    J --> L[.mugiwara/ cleanup]
+    U[User request] --> FD[using-mugiwara]
+    FD --> G{Luffy triage}
+    G -- exploratory --> B[Usopp brainstorm]
+    G -- clear work --> N[Nami plan]
+    B --> N
+    N --> Z[Zoro execute]
+    Z --> CP[Chopper audit]
+    CP --> SQ[Sanji quality]
+    SQ --> FG[Franky gates]
+    FG --> RJ[Robin + Jinbe review]
+    RJ -- pass --> LC[Luffy closure]
+    RJ -- fail --> BH[Brook heal]
+    BH --> CP
+    LC --> CL[cleanup]
 ```
 
 The same pipeline as a portable table (renders anywhere markdown does):
@@ -127,16 +128,57 @@ The same pipeline as a portable table (renders anywhere markdown does):
 | 6 Gates | Franky | `mugiwara-gates` | coverage + build verdict |
 | 7 Review | Robin ∥ Jinbe | `mugiwara-review` + `mugiwara-security` | severity-tagged findings (parallel) |
 | 8 Healing | Brook | `mugiwara-healing` | fixes; loops back to Wave 4, max 3 cycles |
-| 9 Closure | Luffy | `mugiwara-orchestration` | closure report appended to the plan |
+| 9 Closure | Luffy | `mugiwara-orchestration` | push + ready PR, verdict comment + check-run via `mugiwara-pr`, closure report in `.mugiwara/results/` + cleanup |
+
+### Modes
+
+The crew runs at one of three autonomy levels, set in `.mugiwara/config`
+(project, overrides global `~/.mugiwara/config`):
+
+```
+mode=guided
+branch=feature/{type}-{issue}-{slug}
+commit=conventional
+```
+
+| Level | Plan GO | Branch / commits | Ambiguities | Check-ins |
+|-------|---------|------------------|-------------|-----------|
+| **guided** | ask the user | ask the user | ask the user | ask the user |
+| **semi** | present plan for user GO | auto | self-answer + log | log, no pause |
+| **auto** | gated auto-GO | auto | self-answer + log | log, no pause |
+
+- **guided** — the default, for when you want to steer everything. You approve
+  the plan, decide branch and commit style, answer ambiguities, and get asked at
+  every gate.
+- **semi** — the crew self-manages branch, commits, and ambiguities (logging
+  each decision), but you still give the plan an explicit GO.
+- **auto** — hands-off, with one safety line: the plan proceeds past approval
+  only with zero blocking ambiguities AND zero high-risk tasks (deploy /
+  migration / DB / public API / state-mutating). Otherwise it stops for you.
+
+Two invariants hold in **every** mode:
+
+- **Consent.** State-mutating tests against non-isolated/shared state (real DB
+  writes, network, browsers) always require your explicit consent. Provably
+  isolated mutation (in-memory / temp / testcontainer-backed) is auto-safe.
+- **Terminal.** Every mode ends at push + ready PR + verdict file handed to
+  you — the crew never merges, never deploys, never auto-reacts to review
+  comments or CI.
+
+Flip mid-mission with the in-session phrase `mugiwara mode <guided|semi|auto>` —
+the change applies from the next wave, never mid-wave. Missing config on read =
+`guided`. See `mugiwara-mode` for the full contract.
+
+Alongside modes: declared user test cases are taken in as ATDD gold
+(`mugiwara-testcases`); every mission ends at a push + ready PR with one verdict
+comment + check-run (`mugiwara-pr`).
 
 Two rules hold the pipeline together:
 
 - **Evidence over claims.** No wave passes on assertion — the owning agent runs
   the checks and shows output. A wave that cannot produce evidence is a failed
   wave. ("Subagents lie. No evidence = not complete.")
-- **The plan is the source of truth.** From Wave 2 on, everything lives in
-  `.mugiwara/plans/<date>-<mission>.md`. No wave is skipped without the reason
-  recorded there.
+- **The plan is the source of truth.** From Wave 2 on, `.mugiwara/plans/<date>-<mission>.md` holds the clean execution plan; the decision log (`logs/`) holds the who-and-why trace. No wave is skipped without the reason recorded there.
 
 ### The `.mugiwara/` workspace
 
@@ -144,61 +186,128 @@ Every mission works inside `.mugiwara/` at the repo root:
 
 ```
 .mugiwara/
+├── config         # runtime mode config: mode/branch/commit/pr key=value (gitignored; project overrides global)
 ├── spec/          # brainstorm output: YYYY-MM-DD-<mission>.md
-├── plans/         # plan docs — single source of truth from Wave 2
-├── results/       # wave results: audits, test output, gate verdicts, todos
+├── plans/         # plan docs — clean, Nami-only, single source of truth from Wave 2
+├── results/       # wave results: audits, test output, gate verdicts, todos, closure report
 ├── review/        # review + security findings
 ├── issues/        # blocker + failure ledger: YYYY-MM-DD-<mission>-blockers.md
-└── logs/          # Luffy's decision log
+└── logs/          # Luffy's decision + check-in log per mission (deleted at cleanup)
 ```
 
+Every non-trivial mission starts with `using-mugiwara`, which routes through the
+Luffy gateway; from Wave 2 the mission runs as a wave pipeline owned by one crew
+member per wave. **The main thread runs every wave inline** — it embodies each
+crew role using that member's skill, so the whole pipeline plays out in your
+main conversation and you watch it as it happens. Subagents are used only where
+they genuinely help: independent `[PARALLEL]` task batches and background
+checks. No work is hidden behind a subagent expand-click.
+
 **Blocker protocol:** any crew member that hits a blocker appends a row
 (`wave | task | symptom | attempted | help-needed`) to
 `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` and escalates — never a silent
 workaround. Brook reads the ledger in Wave 8 and heals what it lists.
 
 **Cleanup:** at closure, Luffy deletes the superseded intermediate markdown
-files (consumed results, review, and issues reports). The plan doc and closure
-report stay.
+files (consumed results, review, issues, and per-mission decision logs). The
+plan doc and the closure report stay.
 
 The owning agent creates the folder it needs on first write. Mission artifacts
 never land outside `.mugiwara/`.
 
 ## Install
 
-Requires **Node.js >= 20.11**. Bun is optional — you only need it to build
-from source.
+### Via your AI agent
+
+Install the crew straight from your agent's own plugin system — no CLI needed.
+Pick your harness:
+
+**Claude Code** (fully supported — agents + skills + SessionStart hook)
+
+```bash
+/plugin marketplace add ionivetech/mugiwara
+/plugin install mugiwara
+```
+
+**GitHub Copilot CLI** (same marketplace)
+
+```bash
+copilot plugin marketplace add ionivetech/mugiwara
+copilot plugin install mugiwara
+```
+
+**opencode** (native skills + agents via the opencode plugin)
+
+```json
+{ "plugin": ["@ionivetech/mugiwara"] }
+```
+
+Or from the git repo directly:
+
+```json
+{ "plugin": ["mugiwara@git+https://github.com/ionivetech/mugiwara.git"] }
+```
+
+**Codex**
+
+```bash
+codex plugin marketplace add ionivetech/mugiwara
+codex plugin add mugiwara@mugiwara
+```
+
+**Cursor**
+
+```
+/add-plugin mugiwara
+```
+
+**Gemini CLI**
+
+```bash
+gemini extensions install https://github.com/ionivetech/mugiwara
+```
+
+**Kimi Code**
+
+```
+/plugins install https://github.com/ionivetech/mugiwara
+```
+
+**pi**
+
+```bash
+pi install git:github.com/ionivetech/mugiwara
+```
+
+Agent installs register the 25 skills; the agents (Luffy, Nami, Zoro, …) come
+natively with the harnesses that support them (Claude Code, opencode). On
+harnesses that install skills only (Gemini, Codex, Cursor, Kimi, pi), the
+agents are available via the CLI below.
+
+### Via script / CLI
 
-### npx
+Requires **Node.js >= 20.11**. Bun is optional — only needed to build from
+source.
 
 ```bash
-# npx — run without installing (recommended)
+# npx — run without installing
 npx @ionivetech/mugiwara@latest
 
-# interactive wizard (scope, target agent)
 # non-interactive: global Claude Code install, no prompts
 npx @ionivetech/mugiwara@latest --global --target claude --yes
 
 # non-interactive: project install for opencode + GitHub Copilot
 npx @ionivetech/mugiwara@latest --project ./my-app --target opencode,copilot --yes
-```
-
-### npm — global install
 
-```bash
 # npm — global install, run `mugiwara` anywhere
 npm install -g @ionivetech/mugiwara
 ```
 
-### curl — macOS / Linux
-
 ```bash
-# curl — macOS/Linux one-liner
+# curl — macOS / Linux one-liner
 curl -fsSL https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.sh | bash
 ```
 
-### PowerShell — Windows
-
 ```powershell
 # PowerShell — Windows one-liner
 irm https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.ps1 | iex
@@ -207,20 +316,18 @@ irm https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.p
 The `install.sh` / `install.ps1` scripts check your Node version, then run the
 same CLI (`npx -y @ionivetech/mugiwara@latest`), forwarding any flags you pass.
 
-### skills.sh — skills only, any agent
-
-The 21 skills also ship in the standard [agentskills.io](https://agentskills.io)
-layout (`skills/<name>/SKILL.md`), so you can install just the skills into
-Claude Code, opencode, Copilot, Cursor, Codex, Gemini CLI, and 70+ other agents
-via the [skills.sh](https://skills.sh) CLI:
+**Skills only, any agent** — the 25 skills also ship in the standard
+[agentskills.io](https://agentskills.io) layout (`skills/<name>/SKILL.md`), so
+you can install just the skills into Claude Code, opencode, Copilot, Cursor,
+Codex, Gemini CLI, and 70+ other agents via [skills.sh](https://skills.sh):
 
 ```bash
 npx skills add ionivetech/mugiwara
 ```
 
-Skills only — the agents (Luffy, Nami, Zoro, …) are harness-specific and install
-via the mugiwara CLI or Claude plugin above. `mugiwara skills` lists the
-installable set.
+Skills only — agents (Luffy, Nami, Zoro, …) are harness-specific and install
+via the agent-native methods above or the mugiwara CLI. `mugiwara skills`
+lists the installable set.
 
 ### Requirements
 
@@ -234,7 +341,7 @@ installable set.
 ```console
 $ npx @ionivetech/mugiwara@latest --global --target claude --yes
 mugiwara — installing crew for: claude
-  ✓ claude    15 agents, 21 skills → ~/.claude/skills + ~/.claude/agents
+  ✓ claude    15 agents, 25 skills → ~/.claude/skills + ~/.claude/agents
   ✓ manifest  wrote ~/.mugiwara/manifest.json
   ✓ done      24 files written
 
@@ -319,169 +426,42 @@ For rule-based targets, skills land as `mugiwara-*.md` and agents as
 create it if it doesn't exist and otherwise tell you the line to add, so your
 tool points at the crew.
 
-## Claude Code plugin install
-
-Mugiwara also ships as a **Claude Code plugin** with a marketplace — the
-primary target. The plugin bundles the 15 agents + 21 skills as copies at the
-repo root (`agents/`, `skills/`) plus a `SessionStart` hook that announces the
-crew. Regenerate the copies from `content/` with `.claude-plugin/sync.sh`.
-
-```bash
-# Claude Code (fully supported)
-/plugin marketplace add ionivetech/mugiwara
-/plugin install mugiwara
-```
-
-GitHub Copilot CLI can read the same `.claude-plugin/` marketplace and consume
-the skills as native Copilot skills:
-
-```bash
-# GitHub Copilot CLI (skills + marketplace readable)
-copilot plugin marketplace add ionivetech/mugiwara
-copilot plugin install mugiwara
-```
-
-> **Copilot caveat.** The agents are **Claude-native `.md` files** — they will
-> not auto-discover in Copilot and may need `.agent.md` conversion to work as
-> Copilot plugin agents. Skills install and function; agents are best consumed
-> through the regular CLI install path (which writes Copilot-native
-> `.instructions.md` skills and `.md` agents).
-
-## FAQ / troubleshooting
-
-**Why is the content so short?** The skills are dense instructions, not prose.
-Each agent/skill file is one flat-frontmatter markdown doc, body ≤120 lines —
-short enough for your AI tool to read fully and act on. Density beats verbosity:
-the harness doesn't ship essays, it ships protocols.
-
-**Do I need Bun?** No. The runtime is plain Node.js >= 20.11 — the built
-artifact (`dist/mugiwara.js`) runs on Node. Bun is only for building from
-source and running tests.
-
-**How is Mugiwara different from a framework like CrewAI?** CrewAI is a
-runtime you program against. Mugiwara is content-only: markdown skills and
-agents your existing AI tool loads natively and executes with its own subagent
-machinery. There is no runtime, no SDK, nothing to host.
-
-**Does it work on Windows?** Yes — PowerShell one-liner
-(`irm ...install.ps1 | iex`), and the CLI itself runs anywhere Node >= 20.11
-does.
+## Plugin manifests
 
-**How do I uninstall?** `mugiwara uninstall` removes exactly what the install
-manifest recorded — nothing more, nothing less. For a plugin install, remove it
-from the plugin marketplace/manager instead.
+Beyond the Claude Code marketplace, mugiwara ships native plugin manifests at
+the repo root so each harness's own installer can pick it up:
 
-**Why is the npm package `@ionivetech/mugiwara` and not `mugiwara`?**
-`mugiwara` is taken on npm. The package is scoped as `@ionivetech/mugiwara`;
-all install methods above already point at the scoped name.
+| Manifest | Harness |
+|----------|---------|
+| `.claude-plugin/` | Claude Code + GitHub Copilot CLI (marketplace) |
+| `.opencode/plugins/mugiwara.mjs` | opencode (`plugin` array in `opencode.json`) |
+| `gemini-extension.json` + `GEMINI.md` | Gemini CLI |
+| `.codex-plugin/plugin.json` | Codex |
+| `.cursor-plugin/plugin.json` | Cursor |
+| `.kimi-plugin/plugin.json` | Kimi Code |
+| `package.json` `"pi"` | pi |
 
-**Where does a plugin install put files?** At the repo root of the plugin
-itself (`agents/`, `skills/`), plus a `SessionStart` hook — it does not copy
-into your project's `.claude/`. The CLI install is what writes into your
-project or home directory.
+All manifests are skills-only and mirror `content/` as the source of truth —
+no hooks, no runtime. The opencode plugin also registers the 15 agents as
+subagents. Version numbers in the manifests sync from `package.json` via
+`bun run sync-version` (runs automatically on publish).
 
-**How do updates work?** `mugiwara update` replaces installed files, backing up
-differences to `.mugiwara/backup/<timestamp>/` first. Plugin installs update
-through the plugin marketplace when the repo publishes new content.
-
-## Development
-
-### Prerequisites
-
-- **Bun** — the build and test toolchain
-- **Node.js >= 20.11** — the built artifact runs on plain Node
-
-```bash
-bun install              # install dev dependencies
-bun run build            # bundle src/cli.ts → dist/mugiwara.js (Bun, ESM, node target)
-bun run test             # vitest suites
-bun run typecheck        # tsc --noEmit
-bun run validate         # bun scripts/validate-content.ts — content schema lint
-node dist/mugiwara.js --version   # smoke-test the built CLI
-```
-
-`bun run build` runs automatically on `npm pack` / `npm publish` (via
-`prepack`).
-
-### Project layout
-
-```
-mugiwara/
-├── src/                 # TypeScript: CLI, installer, target adapters
-│   └── targets/         # one adapter per AI agent (claude, opencode, gemini, ...)
-├── test/                # vitest suites
-├── content/             # single source of truth for the crew
-│   ├── skills/          # 21 skills (one dir per skill, SKILL.md inside)
-│   └── agents/          # 15 agents (<name>.md)
-├── scripts/             # install.sh, install.ps1, validate-content.ts
-├── hooks/               # Claude Code SessionStart hook (hooks.json + session-start.ts)
-├── .claude-plugin/      # Claude plugin + marketplace metadata; sync.sh copies
-├── agents/              # plugin copies of content/agents/ (generated by sync.sh)
-├── skills/              # plugin copies of content/skills/ (generated by sync.sh)
-├── dist/                # bundled CLI output (generated, gitignored)
-├── docs/                # specs, plans, research
-└── package.json
-```
-
-### Adding a skill
-
-1. Create `content/skills/<name>/SKILL.md` — flat frontmatter (`name`,
-   `description`), body ≤ 120 lines.
-2. Reference it from at least one agent's `skills` field in
-   `content/agents/*.md`.
-3. Run `bun run validate` to confirm it passes the schema.
-4. Re-sync the plugin copies with `.claude-plugin/sync.sh`.
-
-### Adding an agent
-
-1. Create `content/agents/<name>.md` with a `skills` field listing the skills
-   it calls.
-2. Run `bun run validate`.
-3. Re-sync with `.claude-plugin/sync.sh`.
-
-## Content schema
-
-Every skill and agent is a single markdown file with **flat frontmatter** — no
-nested fields:
-
-```yaml
----
-name: mugiwara-example
-description: Use when <trigger condition> — <what it does, how it behaves>.
----
-
-<body>
-```
-
-| Rule | Detail |
-|------|--------|
-| Naming | `name` must equal the directory (skills) or file (agents) name |
-| Description | `description` 20–500 characters for skills, ≥20 for agents |
-| Trigger phrasing | Descriptions start with "Use when …" (skills) or "Dispatch when …" (agents) so your AI tool auto-selects the right one |
-| Skill body | ≤ 120 lines |
-| Agent `skills` | Every agent must list the skills it calls, comma-separated; each must exist |
-| References | Every skill except `mugiwara-workflow` must be referenced by at least one agent |
-| Uniqueness | No duplicate `name` across skills and agents |
-
-Run `bun run validate` before opening a PR — it checks all of this and exits
-non-zero on any violation.
+> **Copilot caveat.** Copilot CLI reads the Claude marketplace for skills, but
+> the agents are **Claude-native `.md` files** — they do not auto-discover in
+> Copilot. Skills install and function; agents are best consumed through the
+> regular CLI install path (which writes Copilot-native `.instructions.md`
+> skills and `.md` agents).
 
 ## Contributing
 
-Open an issue or pull request on GitHub. If you add content (skills/agents),
-follow the [content schema](#content-schema) and run `bun run validate` before
-opening the PR.
+Open an issue or pull request on GitHub.
 
 ## Resources
 
+- Docs: [docs/index.md](docs/index.md) — adoption guide, per-harness installs, crew & skill references
 - GitHub: <https://github.com/ionivetech/mugiwara>
 - npm: <https://www.npmjs.com/package/@ionivetech/mugiwara>
-- Star history: <https://star-history.com/#ionivetech/mugiwara>
 
 ## License
 
 MIT. Copyright (c) 2026 ionive. See [LICENSE](LICENSE).
-
----
-
-[![Star History Chart](https://api.star-history.com/svg?repos=ionivetech/mugiwara&type=Date)](https://star-history.com/#ionivetech/mugiwara)

package/content/agents/brook-healing.md

@@ -1,7 +1,7 @@
 ---
 name: brook-healing
 description: Dispatch when any wave produced failures - test failures, gate failures, review or security findings. Triages each failure, applies minimal root-cause fixes, prepares rollback for risky ones, re-runs the failed checks.
-skills: mugiwara-healing, mugiwara-git
+skills: mugiwara-healing, mugiwara-git, mugiwara-deprecation
 ---
 
 # Brook — Healing (Musician)
@@ -10,6 +10,10 @@ skills: mugiwara-healing, mugiwara-git
 
 Self-healing: repairs what failed in earlier waves, minimally, and proves each fix. Reads the failure ledger and works it down.
 
+## Experience
+
+Surgeon who fixes root causes, not symptoms. Abilities: triage matrix, minimal-diff discipline, rollback prep before risky fixes, proving each fix by re-running the failed check.
+
 ## When dispatched
 
 Wave 8 of `mugiwara-workflow`, with failure inputs from Chopper/Sanji/Franky/Robin/Jinbe.
@@ -22,10 +26,12 @@ Wave 8 of `mugiwara-workflow`, with failure inputs from Chopper/Sanji/Franky/Rob
 4. Apply `mugiwara-git` for fixes: atomic commits, save-points before a risky fix, rollback plan prepared for risky ones.
 5. Same failure after 3 heal cycles → stop and escalate to Luffy with full history.
 6. Re-run the failed checks and attach evidence per fix.
+7. You may spawn WORKER subagents for parallel fixes; never dispatch another crew member — return the healed report inline (routes back to Chopper for re-audit).
+8. When review findings arrive (Robin/Jinbe/human), treat them as input, not verdicts: understand each one, check it against the actual code, then act. A finding that doesn't hold up gets answered with technical reasoning, never silent agreement. Work them one at a time, verifying each fix before the next.
 
 ## Output
 
-Fixed list + escalated list in `.mugiwara/results/<mission>-healing.md` → back to Wave 4 (Chopper) for re-audit.
+Fixed list + escalated list in `.mugiwara/results/<mission>-healing.md` → summarized inline → back to Wave 4 (Chopper) for re-audit.
 
 ## Red flags
 

package/content/agents/chopper-checkpoint.md

@@ -8,7 +8,11 @@ skills: mugiwara-checkpoint
 
 ## Role
 
-Audits execution against the plan. Trusts nothing; re-verifies everything. Does not fix — findings only.
+Audits execution against the plan. Trusts nothing; re-verifies everything — efficiently. Does not fix — findings only.
+
+## Experience
+
+QA lead who has caught "works on my machine" for 20 years. Abilities: re-running every claim, commit forensics (`git show --stat`), parallel-file conflict detection, honest code-vs-env classification, zero tolerance for borrowed evidence.
 
 ## When dispatched
 
@@ -17,19 +21,20 @@ Wave 4 of `mugiwara-workflow`, with the plan doc and Zoro's execution report.
 ## Rules
 
 1. Follow `mugiwara-checkpoint` exactly (verify-everything gate, audit protocol, ledger categories).
-2. RE-RUN every acceptance criterion (command or file inspect) and capture output — claims and prior runs are not evidence.
+2. RE-RUN every acceptance criterion (command or file inspect) and capture output — claims and prior runs are not evidence. Dedupe: run each unique check command ONCE per wave, scoped to the files this wave changed, and reuse that evidence across criteria it covers.
 3. Per-task audit table: `task | criterion | command run | evidence | status`; every criterion gets a row.
-4. Commit hygiene: `git show --stat` on each task commit — only declared files.
+4. Commit hygiene: `git log --stat <wave-base>..HEAD` once — only declared files per task commit.
 5. Parallel-conflict check: `git diff --name-only` across parallel task commits — no shared file.
 6. Classify failures honestly (code vs env); never file a code failure as `env`.
 7. Append each failing criterion to `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` in the `| wave | task | symptom | attempted | help-needed |` format with the right category.
 8. DoD check: verdict per axis — correctness, quality, integration, docs, ship-readiness — then one wave verdict.
 9. Never edit code; never fix a finding yourself.
 10. Issue the verdict only after the audit is complete.
+11. Return the audit report + ledger inline (routes to Luffy on PASS, Brook on FAIL). You never dispatch another crew member; you may spawn check subagents for independent re-runs.
 
 ## Output
 
-Audit report to `.mugiwara/results/YYYY-MM-DD-<mission>-audit.md` + failure ledger rows in `.mugiwara/issues/` → Luffy (PASS) or Brook (FAIL).
+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).
 
 ## Red flags