@ionivetech/mugiwara 0.3.0 → 0.5.0

package/README.md

@@ -3,512 +3,308 @@
 [![npm version](https://img.shields.io/npm/v/@ionivetech%2fmugiwara)](https://www.npmjs.com/package/@ionivetech/mugiwara)
 [![License: MIT](https://img.shields.io/github/license/ionivetech/mugiwara)](https://github.com/ionivetech/mugiwara/blob/main/LICENSE)
 
-The Straw Hat crew of AI agents and skills — a complete software development
-workflow for your coding agent.
+Your coding agent becomes a governed engineering team. 15 specialists — triage,
+plan, build, audit, review, heal — with evidence at every step, cost tracking,
+and a process that sizes itself to your work. Pure markdown, zero runtime.
 
-Skills encode the workflows, quality gates, and best practices a senior
-engineering team applies to software, packaged so your agent follows them
-consistently across every phase of development. The crew **auto-activates**:
-give a non-trivial request and the pipeline runs inline in your main
-conversation — with checkpoint reports at every stage, nothing hidden behind a
-subagent click.
+## Quick start
 
-```
-   TRIAGE            PLAN             BUILD            VERIFY            REVIEW            SHIP
- ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
- │ Luffy    │ ──▶ │ Nami     │ ──▶ │ Zoro     │ ──▶ │ Chopper  │ ──▶ │ Robin +  │ ──▶ │ push +   │
- │ 5-way    │     │ waves +  │     │ TDD per  │     │ Sanji +  │     │ Jinbe    │     │ ready PR │
- │ triage   │     │ tasks    │     │ task     │     │ Franky   │     │ review+  │     │ summary  │
- └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
-```
-
-Zero runtime: pure markdown your existing AI agent runs with its own subagent
-machinery — no daemons, no plugins to keep updated, nothing to host. 32 skills,
-15 agents, and per-stage commands, ready for Claude Code, opencode, Gemini CLI,
-Codex, Cursor, Copilot, Kimi, pi, Windsurf, Cline, Kilo Code, and Antigravity.
-
-## Philosophy
-
-- 🧭 **Skills are the product, agents are the engine.** Skills are the
-  user-facing surface — they auto-activate, they ship to any harness, and you
-  never need to learn an agent name. The named agents are opencode-native
-  enforcement underneath: permission isolation, role lenses, parallel review.
-  Pick mugiwara up the same way you'd pick up a skills pack.
-- 🧑‍🚀 **The crew runs in the main thread.** No crew member is dispatched as a
-  hidden subagent. You watch the pipeline happen, you can interrupt any time,
-  and every wave shows a checkpoint report — never a narration of every tool call.
-- ⚖️ **Mode owns autonomy, config owns writing standards.** Whether branch,
-  commit, and PR run automatically is decided by one lever: the mode
-  (guided / semi / auto). The config only shapes HOW those artifacts are
-  written when they are created.
-- 🛡 **Evidence over claims.** No wave passes on assertion — the owning agent
-  shows output. No evidence, not complete.
-- 📦 **No runtime.** Ships markdown only: native skills and agents for
-  Claude Code, opencode, Copilot, Gemini CLI, Codex, Cursor, Kimi, pi,
-  Windsurf, Cline, Kilo Code, and Antigravity.
-
-## The crew — 15 agents
-
-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 |
-|-------|-------------|------|
-| `using-mugiwara` | Front Door | Optional router: explains the crew, routes any request to the right crew member — no agent names to remember |
-| `luffy-orchestrator` | Luffy | Captain: 5-way triage, check-ins, work splitting, decision log, detailed 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, waves-first plans, file-level dependency edges, break points |
-| `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; writes the failure ledger (never fixes code) |
-| `sanji-quality` | Sanji | Discover the stack, then format/lint/test; integration and optional e2e 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 |
-| `jinbe-security` | Jinbe | Security review: STRIDE first, OWASP, secrets, injection, auth, dependencies, untrusted-data doctrine |
-| `brook-healing` | Brook | Reads the blocker ledger, Stop-the-Line root-cause fixes, worker subagents for fast re-verification, ≤3 heal cycles |
-| `skeptic-verifier` | Skeptic | Adversarial verification: doubt every output/plan/verdict, find what's wrong, do NOT validate |
-| `eval-runner` | Eval Runner | Test engineer for the harness itself: task suites, judge-agent rubric comparison |
-| `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 — 32 skills
-
-| Skill | Purpose |
-|-------|---------|
-| `mugiwara-workflow` | The harness entry point: inline execution model, gateway triage, wave pipeline, checkpoint reports, workspace layout, blocker protocol |
-| `mugiwara-orchestration` | Luffy's captain behavior: 5-way classifier, check-ins, work splitting, decision log, detailed closure |
-| `mugiwara-mode` | Runtime levels guided / semi / auto via `.mugiwara/config`: mode owns autonomy, config owns writing standards, 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, waves-first plans with file-level dependency edges, break points, parallel-safe waves + anti-patterns |
-| `mugiwara-execution` | Todo list, sequential tasks inline + parallel worker batches, one commit per logical task, checkpoint-report batching |
-| `mugiwara-checkpoint` | Verify-everything audit of every acceptance criterion — deduped and scoped to the wave's diff |
-| `mugiwara-quality` | Discover the project's real tooling; formatter, linter, unit tests, optional e2e gate (only when the repo has e2e AND changes touch e2e) |
-| `mugiwara-gates` | Coverage ≥90% new / ≥80% modified files, build validation, Definition of Done; optional e2e position after quality |
-| `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` | STRIDE-first security review, OWASP Top 10 mapping, authn/authz, secrets, dependency audit, boundary system, untrusted-data doctrine |
-| `mugiwara-healing` | Reads the ledger, Stop-the-Line + Prove-It root-cause fixes, worker subagents (reviewer/security/re-run), rollback prep |
-| `mugiwara-deprecation` | Sunset & migration discipline: keep-or-retire gate, cutover playbooks, safe schema changes |
-| `mugiwara-frontend` | Anti-slop frontend: audit-first redesigns, component architecture, design systems, state, responsive, WCAG 2.1 AA |
-| `mugiwara-git` | Atomic commits, save-points, multi-commit splitting, bisect/blame debugging |
-| `mugiwara-pr` | Terminal: push + verdict file with a ready PR summary block; never creates a PR, 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 |
-| `mugiwara-eval` | Test the harness itself: task suites, judge-agent rubric comparison, pass/fail per case |
-| `mugiwara-observability` | Trace the crew: structured logs, OTel-compatible spans, session correlation, end-of-mission summary |
-| `mugiwara-resume` | Session resume: rebuild state from `.mugiwara/` after compaction/loss; never restart |
-| `mugiwara-lessons` | Cross-mission memory: actionable lessons ledger, read at triage, written at closure |
-| `mugiwara-writing-skills` | Meta-skill: how mugiwara authors skills — anatomy, ≤120-line rule, progressive disclosure, anti-rationalization |
-| `mugiwara-systematic-debugging` | 4-phase root-cause discipline: reproduce → localize → reduce → fix + guard; stop-the-line, prove-it first |
-| `mugiwara-test-driven-development` | RED-GREEN-REFACTOR, proof-of-when, test pyramid, one test = one behavior |
-| `mugiwara-api-and-interface-design` | Contract-first design, error semantics, boundary validation, backward compatibility, versioning |
-| `mugiwara-doubt-driven-development` | Adversarial fresh-context verification of in-flight decisions: claim → extract → doubt → reconcile → stop |
-| `mugiwara-git-worktrees` | Isolated parallel branches via `git worktree`, branch hygiene, safe cleanup |
-| `mugiwara-context-engineering` | Token/context management: feed selectively, trust-sort sources, progressive disclosure, rules files |
-
-### Every capability, always
-
-Every install ships the full crew — all 32 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.
-
-## How it works
-
-**The workflow auto-activates.** At session start the crew is announced; when
-you give a non-trivial request, the pipeline runs by itself — you do not need
-to call `/using-mugiwara`. It remains an optional explicit router if you want
-to hand-route a mission.
-
-From there the mission runs as a **wave pipeline** owned by one crew member
-per wave, executed inline in your main conversation.
-
-```mermaid
-flowchart TD
-    U[User request] --> G{Luffy triage}
-    G -- exploratory --> B[Usopp brainstorm]
-    G -- clear work --> N[Nami plan]
-    B --> N
-    N --> Z[Zoro execute]
-    Z --> CP[Chopper audit]
-    CP --> SQ[Sanji quality]
-    SQ --> FG[Franky gates]
-    FG --> RJ[Robin + Jinbe review]
-    RJ -- pass --> LC[Luffy closure]
-    RJ -- fail --> BH[Brook heal]
-    BH --> CP
-    LC --> CL[push + ready PR summary]
-```
+```bash
+# Claude Code
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
 
-| Wave | Owner | Skill | Output |
-|------|-------|-------|--------|
-| 0 Triage | Luffy | `mugiwara-orchestration` | 5-way route decision + reason |
-| 1 Brainstorm | Usopp | `mugiwara-brainstorm` | refined direction, options, recommendation |
-| 2 Planning | Nami | `mugiwara-planning` | plan doc: waves, tasks, file-level dependency edges, acceptance |
-| 3 Execution | Zoro | `mugiwara-execution` | implemented tasks with evidence |
-| 4 Checkpoint | Chopper | `mugiwara-checkpoint` | audit report + failure ledger |
-| 5 Quality | Sanji | `mugiwara-quality` | formatter/linter/test results (+ optional e2e) |
-| 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 via worker subagents; loops to Wave 4, max 3 cycles |
-| 9 Closure | Luffy | `mugiwara-orchestration` | detailed summary + push + ready PR summary (see Modes) |
-
-### Checkpoint reports
-
-You see progress as **checkpoint reports**, not a firehose: a wave banner
-(`## Wave N — <crew> (<skill>)`), one compact report per crew member at each
-stage boundary (what ran / result / evidence pointer), a progress summary per
-wave, and a pause when something fails or gets risky. Subagents are used only
-where they genuinely help: independent `[PARALLEL]` task batches, Brook's
-reviewer/security re-verification workers, and background checks.
-
-## Manual stages
-
-Want to drive the stages yourself? Every stage has a slash command that loads
-the skill, runs the crew role inline, and bridges state from `.mugiwara/`:
-
-| Command | Runs | Reads state from |
-|---------|------|------------------|
-| `/mugiwara-plan` | Nami | `.mugiwara/spec/` |
-| `/mugiwara-execute` | Zoro | `.mugiwara/plans/` |
-| `/mugiwara-review` | Robin | `.mugiwara/results/` + diff |
-| `/mugiwara-security` | Jinbe | `.mugiwara/results/` + diff |
-| `/mugiwara-heal` | Brook | `.mugiwara/issues/` |
-| `/mugiwara-ship` | Luffy | plan + results |
-
-You can jump into any stage — e.g. run `/mugiwara-plan` first, then
-`/mugiwara-execute` later when you're ready.
-
-## Modes
-
-The crew runs at one of three autonomy levels, set in `.mugiwara/config`
-(project, overrides global `~/.mugiwara/config`):
+# opencode — add to opencode.json
+{ "plugin": ["@ionivetech/mugiwara"] }
 
+# CLI for any target
+npx @ionivetech/mugiwara@latest --project . --target all --yes
 ```
-mode=guided
-branch=feature/{type}-{issue}-{slug}
-commit=conventional
-base=main
-```
-
-| Level | Plan GO | Branch/commit | Ambiguities | Check-ins |
-|-------|---------|---------------|-------------|-----------|
-| **guided** | ask the user | ask the user | ask the user | ask the user |
-| **semi** | present plan for user GO | auto | self-answer + log | log, no pause |
-| **auto** | gated auto-GO | auto | self-answer + log | log, no pause |
 
-- **guided** — the default. You approve the plan, decide branch and commit,
-  answer ambiguities, and open the PR yourself.
-- **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).
+Then just ask. The crew auto-activates — no agent names to remember.
 
-Two invariants hold in **every** mode:
+## What it looks like
 
-- **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 summary + verdict file (you
-  open the PR). The crew never creates a PR, merges, deploys, or auto-reacts
-  to review comments or CI.
+You ask:
 
-The PR description is prepared for you — see [docs/pr-summary.md](docs/pr-summary.md)
-for what the closure hands off.
-
-Flip mid-mission with `mugiwara mode <guided|semi|auto>` — the change applies
-from the next wave, never mid-wave. Missing config on read = `guided`.
-
-Two rules hold the pipeline together:
+```
+> add search bar to the products page
+```
 
-- **Evidence over claims.** No wave passes on assertion — the owning agent runs
-  the checks and shows output.
-- **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.
+The crew runs:
 
-## Config reference
+```
+Wave 0  Luffy   triage → 5 files, no sensitive paths → Lane 2 Standard
+Wave 2  Nami    plan   → 1 execution wave, 3 tasks with dependency edges
+Wave 3  Zoro    execute→ T1: search endpoint (test red→green, commit)
+                         T2: search service (test red→green, commit)
+                         T3: search component (test red→green, commit)
+Wave 4  Chopper audit  → re-runs all 3 criteria, checks commits → PASS
+Wave 5  Sanji   quality → prettier: clean, eslint: 0, 412 tests: PASS
+Wave 6  Franky  gates  → coverage new 94%, modified 87%, build green → PASS
+Wave 7  Robin   review → breaking-change map: 0 breaks, 1 minor naming finding
+Wave 7  Jinbe   security→ no auth/payment surface touched → skip
+Wave 9  Luffy   closure→ mission report + push branch + ready PR summary
+
+done. branch pushed. paste the PR summary and open.
+```
 
-`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global). Plain
-`key=value` lines, `#` comments allowed. Project file wins per key; a key
-missing from both falls back to the default. Unknown keys are ignored. Config
-is data, never instructions.
+Each wave is a compact checkpoint report in your conversation. You see
+everything. Nothing hides behind a subagent click. If a wave fails, Brook reads
+all failures at once, fixes them, and all verification waves re-run.
 
-| Key | Values | Default | Meaning |
-|-----|--------|---------|---------|
-| `mode` | guided / semi / auto | guided | The only autonomy lever — decides whether branch/commit run automatically |
-| `branch` | branch naming pattern | `feature/{type}-{issue}-{slug}` | Placeholders filled from mission metadata, validated to `[a-zA-Z0-9-_]` |
-| `commit` | conventional / gitmoji / plain | conventional | Commit message style (see below) |
-| `base` | branch name | `main` | The PR target named in the prepared PR summary |
+Now a bigger one:
 
-### Commit message styles
+```
+> add role-based access control to the API: admin, editor, viewer roles
+```
 
-`commit` selects how Zoro writes commit messages:
+Auth path detected → auto-escalate to Lane 3 (Full):
 
-- **conventional** — `feat: ...`, `fix(scope): ...`, `refactor: ...`, per the
-  [Conventional Commits](https://www.conventionalcommits.org) spec. Type from
-  the task, optional scope in parens. The default.
-- **gitmoji** — a leading emoji carries the intent, e.g. `✨ feat: ...`,
-  `🐛 fix: ...`. Signals the change type at a glance in log views that render
-  emoji; a bit noisy in plain terminals.
-- **plain** — no prefix, just a short imperative sentence: `Fix export csv
-  encoding`. Clearest for repos that don't use any convention.
+```
+Wave 0  Luffy   triage → auth/ + migration/ touched → lane 3 full
+Wave 2  Nami    plan   → 2 execution waves, 5 tasks, parallel-safe graph
+Wave 3a Zoro    execute→ T1 migration + T2 middleware + T3 3 parallel endpoint guards
+Wave 4  Chopper audit  → T3-C: viewer can still POST /api/settings → 1 ledger row
+Wave 5  Sanji   quality → 2 integration tests fail after middleware change → 2 rows
+Wave 6  Franky  gates  → coverage 91% / 85%, build green, DoD blocked (3 open rows)
+Wave 7  Robin   review → 1 major: error message format inconsistent → 1 row
+Wave 7  Jinbe   security→ STRIDE: PASS. 0 high. deny-by-default enforced.
+Wave 8  Brook   heal   → reads 4 ledger rows → 3 parallel heal workers → fix all
+Wave 4  Chopper re-audit→ PASS (cycle 2)
+Wave 5  Sanji   re-qual → PASS
+Wave 6  Franky  re-gate → PASS
+Wave 7  Robin   re-rev  → PASS
+Wave 3b Zoro    execute→ T4 admin dashboard RBAC UI + T5 integration tests
+Wave 4  Chopper audit  → PASS
+Wave 9  Luffy   closure→ state.json + mission report + push + PR summary
+
+1 heal cycle. 4 failures from 3 different waves — all fixed at once.
+```
 
-Switch freely per project — it only affects the message format, never the
-one-logical-task-one-commit rule.
+At closure you get a mission report:
 
-## The `.mugiwara/` workspace
+```
+.mugiwara/reports/2026-08-11-rbac.md
 
-Every mission works inside `.mugiwara/` at the repo root:
+Lane full · Mode guided · Actor you · Branch feature/feat-rbac
 
-```
-.mugiwara/
-├── config         # mode + writing standards (gitignored; project overrides global)
-├── spec/          # brainstorm output: YYYY-MM-DD-<mission>.md
-├── 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 + check-in log per mission (deleted at cleanup)
+What changed: 12 files, +340/-82
+Gates: Audit PASS · Quality PASS · Coverage 91%/85% · Security PASS
+State: 12/12 tasks · 0 blockers · 1 heal cycle · 18.5k/20k tokens
 ```
 
-**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, issues, and per-mission decision logs). The
-plan doc and the closure report stay.
+One file. Any reviewer reads it in 30 seconds. That's the governance trail.
+
+## Capabilities
+
+| Capability | What it does |
+|-----------|-------------|
+| **15 specialist agents** | Luffy triages, Nami plans, Zoro builds TDD, Chopper audits, Sanji checks quality, Franky enforces gates, Robin maps breaking changes, Jinbe runs STRIDE, Brook heals failures. Each with role boundaries: auditors read-only, executor no-network. |
+| **Lane sizing** | Process scaled to work size — computed from `git diff` by `scripts/lane.sh`. Typo = 0 waves. Auth migration = full 9-wave pipeline. Sensitive paths auto-escalate. |
+| **9-wave gated pipeline** | Triage → Plan → Execute → Audit → Quality → Gates → Review+Security → Heal → Closure. Each wave gated by evidence. Pipeline runs inline — you watch everything. |
+| **Evidence trail** | No wave passes on a claim. `scripts/evidence.sh` captures command output. Chopper re-runs criteria. Mission report at closure — one file any reviewer reads in 30 seconds. |
+| **State on disk** | `state.json` written at every wave boundary by `scripts/savepoint.sh`. Lane, files, blockers, token budget — all computed, zero model judgement. Resume reads one file. |
+| **Token budget** | Budget per lane. Warns at 1.5×, pauses at 3×. You decide: continue, split, or reduce. Cost surfaced in mission report — governance, not a kill switch. |
+| **Self-healing** | Brook reads entire blocker ledger after all verification waves. Groups failures, spawns parallel heal workers for independent fixes. Max 3 cycles. |
+| **Deterministic tooling** | `savepoint.sh` (state), `lane.sh` (sizing), `evidence.sh` (output capture), `mission-report.sh` (report). Scripts compute what models shouldn't remember. |
+| **Configurable gates** | Coverage thresholds in `.mugiwara/config`: `coverage_new=90`, `coverage_modified=80`. Raise for strict repos, lower for legacy. |
+| **3 autonomy modes** | Guided (ask everything), semi (auto branch/commit, plan needs GO), auto (hands-off except high-risk). All modes end at push + PR summary — no auto-merge. |
+| **3-layer skills** | 26 skills: trigger description (~150 chars) → body (≤120 lines) → 23 reference files (on demand). 5.2k char index budget — loaded every session. |
+| **Multi-actor safe** | Two engineers, one repo. Reset refuses without `--force`. Branch-scoped state. Shared lessons ledger. |
+| **Compliance matrix** | Rule compliance per model/tier/harness. Published with failures — Gemini tier 2 ≠ Claude tier 1. Documented, not hidden. |
+| **12 harnesses** | Claude Code, opencode, Copilot, Gemini, Codex, Cursor, Kimi, pi, Windsurf, Cline, Kilo, Antigravity. 70+ more via skills.sh. Pure markdown, zero runtime. |
+
+## Why this instead of just asking my agent?
+
+Your agent alone has no governance. It forgets context, skips verification, and
+burns tokens on small fixes the same way it does on architecture changes. There's
+no audit trail — when someone asks "what did the agent do?", you have nothing to
+show.
+
+Mugiwara wraps your agent in a team structure with defined roles, evidence gates,
+and cost tracking. The same discipline you'd expect from a senior engineering
+team — in your chat window, running inline, visible at every step.
+
+## The crew
+
+15 personas, 26 skills. Each with a permission boundary.
+
+| Agent | Role | Permission |
+|-------|------|------------|
+| Luffy | Captain — triage, lane sizing, check-ins, closure | — |
+| Nami | Planner — interviews, scans codebase, writes scaled plans | — |
+| Zoro | Executor — TDD per task, commits per logical unit | **no-network** |
+| Chopper | Auditor — re-runs criteria, writes failure ledger, never fixes | **read-only** |
+| Sanji | Quality — format, lint, test. Never weakens configs | — |
+| Franky | Gates — coverage (configurable thresholds), build, DoD | — |
+| Robin | Reviewer — breaking-change map, five-axis, severity tagging | **read-only** |
+| Jinbe | Security — STRIDE, OWASP, secret scan, dependency audit | **read-only** |
+| Brook | Healer — reads ledger, parallel heal workers, max 3 cycles | — |
+| Skeptic | Adversarial verifier — doubts everything, never validates | **read-only** |
+| Usopp | Brainstorm — interrogates ideas, researches, recommends | — |
+| Resume | Continuity — rebuilds from state.json, never restarts | — |
+| Memory | Cross-mission lessons — read at start, write at closure | — |
+
+See [all 15 agents](docs/agents.md) and [all 26 skills](docs/skills.md).
 
 ## Install
 
-### Via your AI agent
+### Claude Code
 
 <details>
-<summary><strong>Claude Code</strong> — agents + skills + SessionStart hook</summary>
-
-**Install**
+<summary><b>Install / Update / Uninstall</b></summary>
 
 ```bash
-/plugin marketplace add ionivetech/mugiwara
-/plugin install mugiwara
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara   # install
+/plugin update mugiwara                                                    # update
+/plugin uninstall mugiwara                                                 # uninstall
 ```
-
-**Update** — re-install from the marketplace (or `mugiwara update` via CLI).
-
-**Uninstall** — `/plugin uninstall mugiwara`, or `mugiwara uninstall` via CLI.
 </details>
 
-<details>
-<summary><strong>opencode</strong> — native skills + agents via plugin</summary>
+### opencode
 
-**Install** — add to `opencode.json`:
+<details>
+<summary><b>Install / Update / Uninstall</b></summary>
 
 ```json
-{ "plugin": ["@ionivetech/mugiwara"] }
+{ "plugin": ["@ionivetech/mugiwara"] }   // add to opencode.json
 ```
 
-Or from the git repo directly:
-
-```json
-{ "plugin": ["mugiwara@git+https://github.com/ionivetech/mugiwara.git"] }
+```bash
+mugiwara update    # update
+# remove the plugin entry from opencode.json to uninstall
 ```
 
-**Update** — bump the package version in the `plugin` array (or `mugiwara update`).
-
-**Uninstall** — remove the entry from the array.
+Restart opencode after install.
 </details>
 
-<details>
-<summary><strong>GitHub Copilot CLI</strong> — same marketplace</summary>
+### GitHub Copilot
 
-**Install**
+<details>
+<summary><b>Install / Update / Uninstall</b></summary>
 
 ```bash
-copilot plugin marketplace add ionivetech/mugiwara
-copilot plugin install mugiwara
+copilot plugin marketplace add ionivetech/mugiwara && copilot plugin install mugiwara
+copilot plugin update mugiwara
+copilot plugin uninstall mugiwara
 ```
-
-> Copilot caveat: skills install and function; the agents are Claude-native
-> `.md` files and are best consumed via the CLI install path, which writes
-> Copilot-native `.instructions.md` skills.
-
-**Update** — `copilot plugin update mugiwara`. **Uninstall** — `copilot plugin uninstall mugiwara`.
 </details>
 
-<details>
-<summary><strong>Gemini CLI</strong> — extension</summary>
+### Gemini CLI · Codex · Cursor
 
-**Install**
+<details>
+<summary><b>Gemini</b></summary>
 
 ```bash
 gemini extensions install https://github.com/ionivetech/mugiwara
+gemini extensions update mugiwara
+gemini extensions remove mugiwara
 ```
-
-**Update** — `gemini extensions update mugiwara`.
-**Uninstall** — `gemini extensions remove mugiwara`.
 </details>
 
 <details>
-<summary><strong>Codex</strong> — plugin</summary>
-
-**Install**
+<summary><b>Codex</b></summary>
 
 ```bash
-codex plugin marketplace add ionivetech/mugiwara
-codex plugin add mugiwara@mugiwara
+codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara
+codex plugin update mugiwara
+codex plugin remove mugiwara
 ```
-
-**Update** — `codex plugin update mugiwara`. **Uninstall** — `codex plugin remove mugiwara`.
 </details>
 
 <details>
-<summary><strong>Cursor</strong> — plugin</summary>
-
-**Install**
+<summary><b>Cursor</b></summary>
 
 ```
-/add-plugin mugiwara
+/add-plugin mugiwara       # install & update
+/remove-plugin mugiwara    # uninstall
 ```
-
-**Update** — re-run `/add-plugin mugiwara`. **Uninstall** — `/remove-plugin mugiwara`.
 </details>
 
-<details>
-<summary><strong>Kimi Code</strong> — plugin</summary>
-
-**Install**
-
-```
-/plugins install https://github.com/ionivetech/mugiwara
-```
-
-**Update** — `/plugins update mugiwara`. **Uninstall** — `/plugins remove mugiwara`.
-</details>
+### Kimi · pi · Windsurf · Cline · Kilo · Antigravity
 
 <details>
-<summary><strong>pi</strong> — package</summary>
-
-**Install**
+<summary><b>All other harnesses</b></summary>
 
 ```bash
-pi install git:github.com/ionivetech/mugiwara
+npx @ionivetech/mugiwara@latest --project . --target all --yes   # install
+mugiwara update                                                    # update
+mugiwara uninstall                                                 # uninstall
 ```
-
-**Update** — `pi update mugiwara`. **Uninstall** — `pi remove mugiwara`.
 </details>
 
-<details>
-<summary><strong>npx / npm / curl / PowerShell</strong> — the mugiwara CLI</summary>
-
-Requires **Node.js >= 20.11**. Bun is optional — only needed to build from source.
-
-**Install**
+### Any agent (skills only)
 
 ```bash
-# run without installing (wizard)
-npx @ionivetech/mugiwara@latest
-
-# 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, run `mugiwara` anywhere
-npm install -g @ionivetech/mugiwara
+npx skills add ionivetech/mugiwara   # 70+ agents via skills.sh
 ```
 
+### One-liner
+
 ```bash
-# curl — macOS / Linux one-liner
+# macOS / Linux
 curl -fsSL https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.sh | bash
-```
-
-```powershell
-# PowerShell — Windows one-liner
+# Windows
 irm https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.ps1 | iex
 ```
 
-**Update** — `mugiwara update` (or `npm update -g @ionivetech/mugiwara`).
+Requires **Node.js >= 20.11**.
 
-**Uninstall** — `mugiwara uninstall` (removes exactly what the manifest recorded; or `npm uninstall -g @ionivetech/mugiwara`).
-</details>
+## Configuration
+
+`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global).
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `mode` | guided | Autonomy: guided / semi / auto |
+| `branch` | `feature/{type}-{issue}-{slug}` | Branch naming |
+| `commit` | conventional | conventional / gitmoji / plain |
+| `base` | main | PR target branch |
+| `coverage_new` | 90 | Coverage threshold for new files |
+| `coverage_modified` | 80 | Coverage threshold for modified files |
+
+[Full config →](docs/config.md)
 
-**Skills only, any agent** — all 32 skills 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):
+## CLI
 
 ```bash
-npx skills add ionivetech/mugiwara
+mugiwara install                                  # wizard (interactive)
+mugiwara install --project . --target all --yes   # non-interactive
+mugiwara update                                   # replace existing files
+mugiwara uninstall                                # remove what manifest recorded
+mugiwara list                                     # show installations
+mugiwara reset --keep-logs                        # wipe mission state, keep lessons
+mugiwara reset --force                            # override multi-actor guard
 ```
 
-## CLI commands and flags
-
-### Commands
-
-| Command | Effect |
-|---------|--------|
-| `mugiwara install` | Install the crew (default; wizard when flags are missing) |
-| `mugiwara update` | Replace installed files, backing up differences to `.mugiwara/backup/<timestamp>/` first |
-| `mugiwara uninstall` | Remove exactly what the install manifest recorded |
-| `mugiwara list` | Show installations (project + global manifests) |
-| `mugiwara skills` | List the installable skills (agentskills.io) + skills.sh install command |
-| `mugiwara --help` | Print usage and flags |
-| `mugiwara --version` | Print the package version |
-
-### Flags
-
-| Flag | Meaning |
-|------|---------|
-| `--global` | Install user-wide (writes to your home directory) |
-| `--project <dir>` | Install into a project directory (default: current directory) |
-| `--target <ids\|all>` | Comma-separated target IDs, or `all`. Valid: `claude, opencode, copilot, gemini, codex, windsurf, cline, kilo, antigravity` |
-| `--yes`, `-y` | Non-interactive. Requires `--global` or `--project`, and `--target` |
-| `--force` | Overwrite files that differ (conflicting files are backed up first) |
-| `--dry-run` | Print the actions without writing anything |
-
-Every install writes `.mugiwara/manifest.json` recording the version, scope,
-targets, and the exact written files — which is what `update` and `uninstall`
-use to operate safely.
-
-## Targets
-
-| Target | Scope | Installs as |
-|--------|-------|-------------|
-| Claude Code | global + project | Native skills (`SKILL.md`) + agents in `.claude/skills` / `.claude/agents` |
-| opencode | global + project | Native skills + agents in `.opencode/skills` / `.opencode/agents` |
-| GitHub Copilot | global + project | Skills as `.instructions.md` files + agents in `instructions/` / `agents/` |
-| Gemini CLI | project only | Markdown rules in `.gemini/mugiwara/` + `GEMINI.md` pointer |
-| Codex | project only | Markdown rules in `.codex/mugiwara/` + `AGENTS.md` pointer |
-| Windsurf | project only | Rules files in `.devin/rules` |
-| Cline | project only | Rules files in `.clinerules` |
-| Kilo Code | project only | Rules files in `.kilo/rules` + `kilo.jsonc` pointer |
-| Antigravity | project only | Rules files in `.agents/rules` |
-
-## Plugin manifests
-
-Mugiwara ships native plugin manifests at the repo root so each harness's own
-installer can pick it up: `.claude-plugin/`, `.opencode/plugins/mugiwara.mjs`,
-`gemini-extension.json` + `GEMINI.md`, `.codex-plugin/plugin.json`,
-`.cursor-plugin/plugin.json`, `.kimi-plugin/plugin.json`, and the `"pi"` entry
-in `package.json`. All manifests are skills-only and mirror `content/` as the
-source of truth. The opencode plugin also registers the 15 agents. Versions
-sync from `package.json` via `bun run sync-version`.
-
-## Contributing
-
-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>
+## When not to use mugiwara
+
+- **Autonomous marathon runs** — the agent disappears for hours. Use superpowers.
+- **Deep per-skill reference encyclopedia** — use agent-skills.
+- **A deployable runtime** — use LangGraph / CrewAI.
+- **One large instruction with no ceremony** — use a mega-prompt.
+
+Mugiwara is for visibility, governance, and cost awareness. If those don't
+matter to you, this is the wrong tool.
+
+## Docs
+
+| Doc | What it covers |
+|-----|---------------|
+| [Getting started](docs/getting-started.md) | First mission, lane 0-3 examples, setup walkthrough |
+| [Workflow](docs/workflow.md) | Full 9-wave pipeline with heal loop detail |
+| [Agents](docs/agents.md) | 15 crew members, roles, permissions, how to summon |
+| [Skills](docs/skills.md) | 26 techniques, 3-layer disclosure model |
+| [Lanes](docs/lanes.md) | Deterministic lane sizing — computed from git diff |
+| [Audit trail](docs/audit-trail.md) | 15 artifact types, how to read as reviewer |
+| [Cost model](docs/cost.md) | Index/body/references layers, cost per lane |
+| [Harness matrix](docs/harness-matrix.md) | Tier 1/2/3 — what differs per harness |
+| [Config](docs/config.md) | All `.mugiwara/config` keys with defaults |
+| [Modes](docs/modes.md) | Guided / semi / auto autonomy levels |
+| [Compliance matrix](docs/compliance-matrix.md) | Rule compliance per model — published with failures |
+| [Comparison](docs/comparison.md) | Positioning. When to use mugiwara vs something else. |
+| [Roadmap](ROADMAP.md) | Now — Next — Then — After |
 
 ## License
 
-MIT. Copyright (c) 2026 ionive. See [LICENSE](LICENSE).
+MIT. Copyright (c) 2026 ionive.