@ionivetech/mugiwara 0.2.0 → 0.4.0

package/README.md

@@ -3,104 +3,203 @@
 [![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.
-
-Zero runtime: pure markdown your existing AI agent runs with its own subagent
-machinery — no daemons, no plugins to keep updated, nothing to host.
-
-## Why Mugiwara
-
-- 🧭 **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, 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.
-- 🛡 **Evidence over claims.** No wave passes on assertion — the owning agent
-  shows output. No evidence, not complete.
-- ⚡ **One-command install.** `npx`, `npm -g`, curl, or PowerShell — interactive
-  wizard or fully scriptable with flags.
-- 🧪 **Everything validated.** Coverage gates, build gates, OWASP security
-  review, doubt-driven diff review, Definition of Done.
-
-### 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 | Start here: routes any request to the right crew member — no agent names to remember |
-| `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 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 |
-| `jinbe-security` | Jinbe | Security review: OWASP, secrets, injection, auth, dependencies, untrusted-data doctrine |
-| `brook-healing` | Brook | Reads the blocker ledger, Stop-the-Line root-cause fixes, ≤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, fix the skill not the eval |
-| `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 — 25 skills
-
-| Skill | Purpose |
-|-------|---------|
-| `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, 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 |
-| `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 |
-
-### Every capability, always
-
-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.
-
-## How it works
-
-Every mission starts with `using-mugiwara` — the easy-to-remember front door
-that routes you to the right crew member (no agent names to memorize). It
-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, executed inline in your main
-conversation.
+**The Straw Hat crew of AI agents and skills.** A complete software
+development workflow for your coding agent — triage, planning, execution,
+verification, review, and shipping — with the discipline of a senior
+engineering team.
+
+Mugiwara is pure markdown. No daemons, no servers, no plugin to babysit. Your
+existing coding agent reads the skills and runs them itself. It works across
+12 coding agents — Claude Code, opencode, Gemini CLI, Codex, Cursor, Copilot,
+Kimi, pi, Windsurf, Cline, Kilo Code, and Antigravity — and installs into
+70+ more as plain skills.
+
+```
+   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  │
+ └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
+   ↰ exploratory → Usopp brainstorms            fail → Brook heals ↺ Wave 4
+```
+
+## Why mugiwara
+
+- **It just starts.** Give a non-trivial request — "add dark mode to the
+  settings page" — and the crew runs the pipeline in your main conversation,
+  with a compact checkpoint report at every stage. Nothing hides behind a
+  subagent click; you can interrupt any time.
+- **The work is sized before it runs.** A one-file typo runs zero waves. An
+  architecture change runs all nine. Luffy routes each mission to a lane, so a
+  tiny fix never pays the price of a big feature — and a sensitive change never
+  sneaks through the lean path.
+- **Evidence over claims.** No wave passes on a spoken "it works." The owning
+  agent runs the checks and shows output. Every skill also knows when it does
+  *not* apply — and says so, out loud.
+- **It remembers.** Mission state lives in `.mugiwara/` — plans, results, a
+  failure ledger, and a lessons file. Lose context mid-mission and the crew
+  rebuilds from disk instead of restarting.
+- **You stay in control.** The crew pushes the branch and hands you a
+  ready-to-paste PR summary. It never creates a PR, merges, or deploys on its
+  own. Three autonomy levels — guided, semi, auto — decide how much it does
+  without asking.
+
+## Quick start
+
+Install into your harness in one command, then just ask:
+
+```bash
+# Claude Code
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
+
+# opencode
+{ "plugin": ["@ionivetech/mugiwara"] }   # add to opencode.json
+
+# or via CLI for any target
+npx @ionivetech/mugiwara@latest --project ./my-app --target all --yes
+```
+
+```text
+> add dark mode to the settings page
+```
+
+The crew announces itself at session start and routes the request. See
+[docs/getting-started.md](docs/getting-started.md) for the full walkthrough.
+
+---
+
+## The crew — 15 agents
+
+Each agent is a focused specialist. The main thread embodies each role inline
+using its skill; you can also summon any member directly by name. "Dispatch"
+means *route the mission to this role* — crew members never dispatch each other.
+
+| Agent | Crew member | Role | Summon for |
+|-------|-------------|------|------------|
+| `using-mugiwara` | Front Door | Router — classifies and routes, never implements | any new mission |
+| `luffy-orchestrator` | Luffy | Captain — 5-way triage, lane sizing, check-ins, closure | mission start, escalations |
+| `usopp-brainstorm` | Usopp | Critical friend — interrogates ideas, researches, no rubber-stamps | vague ideas, direction, options |
+| `nami-planner` | Nami | Planner — interview-first, full-context scan, scaled plans | turning an idea into a plan |
+| `zoro-execution` | Zoro | Executor — todo list first, inline tasks, parallel worker batches, evidence per task | executing an approved plan |
+| `chopper-checkpoint` | Chopper | Auditor — re-verifies every acceptance criterion, writes the failure ledger, never fixes | auditing a wave's results |
+| `sanji-quality` | Sanji | Quality — discovers real tooling, format / lint / test | after checkpoint passes |
+| `franky-gates` | Franky | Gates — coverage, build, Definition of Done, binary verdicts | after quality checks |
+| `robin-reviewer` | Robin | Reviewer — doubt-driven diff review, breaking-change map first | after gates pass |
+| `jinbe-security` | Jinbe | Security — STRIDE, OWASP, secrets, injection, auth, dependencies | security audit of a diff |
+| `brook-healing` | Brook | Healer — reads the ledger, root-cause fixes, proves each fix, ≤3 cycles | any wave produced failures |
+| `skeptic-verifier` | Skeptic | Adversarial verifier — doubts every output, never validates | high-stakes verdicts, plans, reviews |
+| `eval-runner` | Eval Runner | Harness tester — task suites, rubric comparison, pass/fail | verifying mugiwara itself works |
+| `resume-coordinator` | Resume Coordinator | Resumer — rebuilds from `.mugiwara/`, continues never restarts | context loss, new session mid-mission |
+| `memory-keeper` | Memory Keeper | Institutional memory — surfaces past lessons, captures new ones | mission start + closure |
+
+Say a name and the role embodies itself:
+
+```
+> Chopper, audit the last wave against the plan
+> Nami, plan this out
+```
+
+Luffy still records the route and its reason, and direct calls do not skip
+check-ins. See [docs/agents.md](docs/agents.md).
+
+---
+
+## The techniques — 32 skills
+
+Skills are the actual product: portable markdown playbooks that tell the agent
+*how* to do each phase well. Agents are the personas; skills are the
+knowledge. Every skill declares **when to use it** and **when to skip it**.
+
+### The pipeline
+
+| Skill | Used when |
+|-------|-----------|
+| `mugiwara-workflow` | starting any non-trivial mission — the harness entry point |
+| `mugiwara-orchestration` | triaging a new mission, coordinating waves, closing out |
+| `mugiwara-brainstorm` | exploring a vague idea or architecture choice before planning |
+| `mugiwara-planning` | turning an approved idea or spec into an execution plan |
+| `mugiwara-execution` | executing an approved wave-structured plan |
+| `mugiwara-checkpoint` | auditing a wave's results against the plan, criterion by criterion |
+| `mugiwara-healing` | earlier waves produced failures — test, gate, review, or security findings |
+| `mugiwara-resume` | a mission was interrupted, context lost, or a new session starts mid-mission |
+| `mugiwara-mode` | reading or changing the autonomy level (guided / semi / auto) |
+
+### Engineering practice
+
+| Skill | Used when |
+|-------|-----------|
+| `mugiwara-test-driven-development` | writing code during execution — RED-GREEN-REFACTOR |
+| `mugiwara-testcases` | a mission declares user-provided test cases or acceptance criteria |
+| `mugiwara-systematic-debugging` | a bug, crash, or unexplained regression needs root-cause discipline |
+| `mugiwara-api-and-interface-design` | designing or reviewing an API, interface, or inter-service contract |
+| `mugiwara-doubt-driven-development` | an in-flight decision is cheap to verify now but costly to reverse later |
+| `mugiwara-context-engineering` | working in a large codebase, long session, or near the context limit |
+| `mugiwara-git` | committing, splitting commits, or debugging via git history |
+| `mugiwara-git-worktrees` | running parallel branches without polluting the working tree |
+| `mugiwara-deprecation` | retiring code or steering users onto a replacement |
+| `mugiwara-frontend` | any frontend implementation or redesign — anti-slop, WCAG 2.1 AA |
+| `mugiwara-backend` | implementing or reviewing backend/server code |
+| `mugiwara-agent-security` | reviewing the agent layer itself — injection, poisoning, excessive agency |
+
+### Verification & review
+
+| Skill | Used when |
+|-------|-----------|
+| `mugiwara-quality` | running format / lint / test after checkpoint passes |
+| `mugiwara-gates` | enforcing coverage, build, and Definition of Done |
+| `mugiwara-review` | reviewing the diff adversarially after gates pass |
+| `mugiwara-security` | running the security audit of a diff or system |
+| `mugiwara-ship` | running the pre-launch gate before anything reaches users |
+
+### Team & meta
+
+| Skill | Used when |
+|-------|-----------|
+| `mugiwara-pr` | pushing the branch and preparing the PR material at closure |
+| `mugiwara-lessons` | reading/writing the cross-mission lessons ledger |
+| `mugiwara-observability` | tracing how the crew ran a mission |
+| `mugiwara-dynamic-workflow` | a mission has many subtasks, needs comparison, or risks agent bias |
+| `mugiwara-eval` | verifying a mugiwara skill or agent actually works |
+| `mugiwara-writing-skills` | authoring or revising a mugiwara skill |
+
+Every install ships the full set — no project-type selection. The harness
+routes each task to the right skill, and a skill with nothing to do says so and
+steps aside. See [docs/skills.md](docs/skills.md) for the anatomy and
+[docs/skill-anatomy.md](docs/skill-anatomy.md) for the format spec.
+
+---
+
+## How mugiwara works
+
+### Auto-activation
+
+At session start the crew is announced. Give a non-trivial request and the
+pipeline runs by itself — no command to remember. `/using-mugiwara` remains an
+optional router if you want to hand-route a mission.
+
+### Sizing: the lanes
+
+At Wave 0, Luffy sizes the request and picks a lane. The lane decides how many
+waves run:
+
+| Lane | Picks when | Waves |
+|------|-----------|-------|
+| **0 · Direct** | typo, rename, one file under 20 lines | none |
+| **1 · Lean** | bug in 1-2 files, under 50 lines | execute → quality |
+| **2 · Standard** | feature, 3-8 files | plan → execute → checkpoint → review |
+| **3 · Full** | architecture, migration, auth/payment, API | all 9 waves |
+| **4 · Spike** | exploratory, needs direction | brainstorm → re-triage |
+
+The lane escalates when the work outgrows the estimate (the diff balloons, a
+sensitive path appears, failures repeat) — but never shrinks on its own.
+Under-process costs more than over-process.
+
+### The wave pipeline
 
 ```mermaid
 flowchart TD
-    U[User request] --> FD[using-mugiwara]
-    FD --> G{Luffy triage}
+    U[User request] --> G{Luffy triage}
     G -- exploratory --> B[Usopp brainstorm]
     G -- clear work --> N[Nami plan]
     B --> N
@@ -112,355 +211,239 @@ flowchart TD
     RJ -- pass --> LC[Luffy closure]
     RJ -- fail --> BH[Brook heal]
     BH --> CP
-    LC --> CL[cleanup]
+    LC --> CL[push + ready PR summary]
 ```
 
-The same pipeline as a portable table (renders anywhere markdown does):
-
 | Wave | Owner | Skill | Output |
 |------|-------|-------|--------|
-| 0 Triage | Luffy | `mugiwara-orchestration` | 5-way route decision + reason |
+| 0 Triage | Luffy | `mugiwara-orchestration` | route + lane + reason |
 | 1 Brainstorm | Usopp | `mugiwara-brainstorm` | refined direction, options, recommendation |
-| 2 Planning | Nami | `mugiwara-planning` | plan doc: waves, tasks, acceptance criteria |
+| 2 Planning | Nami | `mugiwara-planning` | plan doc: waves, tasks, 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 |
+| 5 Quality | Sanji | `mugiwara-quality` | formatter / linter / test results |
 | 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` | push + ready PR, verdict comment + check-run via `mugiwara-pr`, closure report in `.mugiwara/results/` + cleanup |
+| 7 Review | Robin ∥ Jinbe | `mugiwara-review` + `mugiwara-security` | severity-tagged findings |
+| 8 Healing | Brook | `mugiwara-healing` | fixes; loops to Wave 4, max 3 cycles |
+| 9 Closure | Luffy | `mugiwara-orchestration` | summary + push + ready PR summary |
+
+**You see progress, not a firehose.** Each wave opens with a banner
+(`## Wave N — <crew> (<skill>)`), closes with a compact checkpoint report (what
+ran / result / evidence pointer), and pauses when something fails or gets
+risky. Subagents appear only where they genuinely help: parallel task batches
+and independent re-verification.
 
-### Modes
+### What a mission looks like
 
-The crew runs at one of three autonomy levels, set in `.mugiwara/config`
-(project, overrides global `~/.mugiwara/config`):
+Small and specific:
 
 ```
-mode=guided
-branch=feature/{type}-{issue}-{slug}
-commit=conventional
+> fix the date formatting bug in src/utils/format.ts
 ```
 
-| 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.
+Luffy routes it to **Lane 1** and the crew runs two waves — Zoro reproduces and
+fixes, then Sanji formats and tests — all visible as checkpoint reports. No
+nine-wave ceremony for a one-file bug.
 
-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.
+Big and sensitive:
 
-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`).
+```
+> add role-based access control to the API
+```
 
-Two rules hold the pipeline together:
+That touches auth, so Luffy routes it to **Lane 3**. Nami plans the migration
+waves, Zoro executes test-first, Chopper re-verifies every criterion, Sanji and
+Franky gate it, Robin and Jinbe review, Brook heals anything that fails, and
+Luffy closes with a ready PR summary. Every wave reports inline.
 
-- **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, `.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.
+That is the point of mugiwara: **the process scales to the work, and you can
+see all of it.**
 
-### The `.mugiwara/` workspace
+### The workspace
 
 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 — clean, Nami-only, single source of truth from Wave 2
-├── results/       # wave results: audits, test output, gate verdicts, todos, closure report
+├── config         # mode + writing standards (gitignored)
+├── spec/          # brainstorm output
+├── plans/         # plan docs — clean, Nami-only, source of truth from Wave 2
+├── results/       # wave results: audits, test output, gate verdicts
 ├── 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)
+├── issues/        # blocker + failure ledger
+├── refs/          # full skill/agent bodies for glob-loading harnesses
+└── logs/          # 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.
+Two rules hold it together:
 
-**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.
+1. **Evidence over claims.** No wave passes on assertion — the owning agent
+   runs the checks and shows output.
+2. **The plan is the source of truth.** From Wave 2 on, the plan doc holds the
+   clean execution plan; the decision log holds the who-and-why trace. A
+   skipped wave is recorded, never silent.
 
-**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.
+### Manual stages
 
-The owning agent creates the folder it needs on first write. Mission artifacts
-never land outside `.mugiwara/`.
-
-## Install
+Prefer to drive the stages yourself? Every stage has a slash command that loads
+the skill, runs the role inline, and bridges state from `.mugiwara/`:
 
-### Via your AI agent
+| 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 |
 
-Install the crew straight from your agent's own plugin system — no CLI needed.
-Pick your harness:
+Jump in at any stage — plan today, execute tomorrow.
 
-**Claude Code** (fully supported — agents + skills + SessionStart hook)
+---
 
-```bash
-/plugin marketplace add ionivetech/mugiwara
-/plugin install mugiwara
-```
+## Modes & autonomy
 
-**GitHub Copilot CLI** (same marketplace)
+Three autonomy levels, set in `.mugiwara/config`:
 
-```bash
-copilot plugin marketplace add ionivetech/mugiwara
-copilot plugin install mugiwara
-```
+| 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 |
 
-**opencode** (native skills + agents via the opencode plugin)
+- **guided** — the default. You approve the plan, decide branch and commits,
+  answer ambiguities, and open the PR yourself.
+- **semi** — the crew self-manages branch, commits, and ambiguities (logging
+  each decision), but the plan still needs your explicit GO.
+- **auto** — hands-off, with one safety line: the plan proceeds only with zero
+  blocking ambiguities AND zero high-risk tasks (deploy / migration / DB /
+  public API / state-mutating).
 
-```json
-{ "plugin": ["@ionivetech/mugiwara"] }
-```
+Two invariants hold in every mode:
 
-Or from the git repo directly:
+- **Consent.** State-mutating tests against shared state (real DB writes,
+  network, browsers) always require your explicit consent. Provably isolated
+  mutation is auto-safe.
+- **Terminal.** Every mode ends at push + ready PR summary + verdict file. The
+  crew never creates a PR, merges, deploys, or auto-reacts to review comments.
 
-```json
-{ "plugin": ["mugiwara@git+https://github.com/ionivetech/mugiwara.git"] }
-```
+Flip mid-mission with `mugiwara mode <guided|semi|auto>`. The PR description is
+prepared for you — see [docs/pr-summary.md](docs/pr-summary.md).
 
-**Codex**
+---
 
-```bash
-codex plugin marketplace add ionivetech/mugiwara
-codex plugin add mugiwara@mugiwara
-```
+## Configuration
 
-**Cursor**
+`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global). Plain
+`key=value` lines, `#` comments allowed.
 
-```
-/add-plugin mugiwara
-```
-
-**Gemini CLI**
-
-```bash
-gemini extensions install https://github.com/ionivetech/mugiwara
-```
+| Key | Values | Default | Meaning |
+|-----|--------|---------|---------|
+| `mode` | guided / semi / auto | guided | How much the crew does without asking |
+| `branch` | pattern | `feature/{type}-{issue}-{slug}` | Branch naming |
+| `commit` | conventional / gitmoji / plain | conventional | Commit message style |
+| `base` | branch name | `main` | The PR target in the prepared summary |
 
-**Kimi Code**
+Commit styles: `conventional` (`feat: ...`, `fix(scope): ...`), `gitmoji`
+(`✨ feat: ...`), or `plain` (`Fix export csv encoding`). See
+[docs/config.md](docs/config.md).
 
-```
-/plugins install https://github.com/ionivetech/mugiwara
-```
+---
 
-**pi**
+## Install
 
-```bash
-pi install git:github.com/ionivetech/mugiwara
-```
+### Via your coding agent
 
-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.
+| Harness | Install |
+|---------|---------|
+| Claude Code | `/plugin marketplace add ionivetech/mugiwara` then `/plugin install mugiwara` |
+| opencode | add `{ "plugin": ["@ionivetech/mugiwara"] }` to `opencode.json` |
+| GitHub Copilot | `copilot plugin marketplace add ionivetech/mugiwara` then `copilot plugin install mugiwara` |
+| Gemini CLI | `gemini extensions install https://github.com/ionivetech/mugiwara` |
+| Codex | `codex plugin marketplace add ionivetech/mugiwara` then `codex plugin add mugiwara@mugiwara` |
+| Cursor | `/add-plugin mugiwara` |
+| Kimi Code | `/plugins install https://github.com/ionivetech/mugiwara` |
+| pi | `pi install git:github.com/ionivetech/mugiwara` |
 
-### Via script / CLI
+### Via the CLI
 
-Requires **Node.js >= 20.11**. Bun is optional — only needed to build from
-source.
+Requires **Node.js >= 20.11**.
 
 ```bash
-# npx — run without installing
+# run without installing (wizard)
 npx @ionivetech/mugiwara@latest
 
-# non-interactive: global Claude Code install, no prompts
+# non-interactive: global Claude Code install
 npx @ionivetech/mugiwara@latest --global --target claude --yes
 
-# non-interactive: project install for opencode + GitHub Copilot
+# project install for several harnesses
 npx @ionivetech/mugiwara@latest --project ./my-app --target opencode,copilot --yes
 
-# npm — global install, run `mugiwara` anywhere
+# global install, run `mugiwara` anywhere
 npm install -g @ionivetech/mugiwara
 ```
 
 ```bash
-# curl — macOS / Linux one-liner
+# macOS / Linux one-liner
 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
 ```
 
-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 only, any agent
 
-**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):
+All 32 skills ship in the standard [agentskills.io](https://agentskills.io)
+layout, so you can install just the skills into 70+ agents via
+[skills.sh](https://skills.sh):
 
 ```bash
 npx skills add ionivetech/mugiwara
 ```
 
-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
-
-| Dependency | Required for | Version |
-|------------|--------------|---------|
-| Node.js | running the CLI and the built artifact | >= 20.11 |
-| Bun | building from source, running tests | optional |
+Update — `mugiwara update` or re-run your harness's install command. Uninstall
+— `mugiwara uninstall` removes exactly what the manifest recorded.
 
-## Quickstart
+---
 
-```console
-$ npx @ionivetech/mugiwara@latest --global --target claude --yes
-mugiwara — installing crew for: claude
-  ✓ claude    15 agents, 25 skills → ~/.claude/skills + ~/.claude/agents
-  ✓ manifest  wrote ~/.mugiwara/manifest.json
-  ✓ done      24 files written
-
-$ # now just ask your Claude Code session
-> add dark mode to the settings page
-
-  Wave 0  Luffy   triage → route: plan (requirements mostly clear)
-  Wave 2  Nami    plan   → .mugiwara/plans/2026-08-10-dark-mode.md (3 waves)
-  Wave 3  Zoro    execute→ 3 tasks, evidence shown per task
-  Wave 4  Chopper audit  → FAIL: toggle does not persist (ledger written)
-  Wave 8  Brook   heal   → fixed persistence + tests, looped back → PASS
-  Wave 9  Luffy   closure→ report appended to plan, intermediate files cleaned
-```
-
-You never drive the sequence — you answer Nami's clarifying questions up front
-and review Brook's rollback note if a fix is risky.
-
-## Commands and flags
-
-### Commands
+## CLI reference
 
 | 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 (project root, or `~` for global) |
+| `mugiwara update` | Replace installed files, backing up differences 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
+| `mugiwara reset` | Wipe mission state (`--keep-logs` preserves the lessons ledger) |
+| `mugiwara --help` / `--version` | Help / version |
 
 | 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 |
+| `--global` | Install user-wide |
+| `--project <dir>` | Install into a project directory |
+| `--target <ids\|all>` | Comma-separated target IDs, or `all` |
+| `--yes`, `-y` | Non-interactive |
+| `--force` | Overwrite differing files (with backup) |
+| `--dry-run` | Print actions without writing |
+| `--keep-logs` | With `reset`: keep `.mugiwara/logs` (lessons ledger) |
 
-```bash
-# non-interactive install requires scope + target, or it errors out
-npx @ionivetech/mugiwara@latest --project ./app --target claude --yes
+Every install writes `.mugiwara/manifest.json` recording the version, scope,
+targets, and exact written files — which is what `update` and `uninstall` use
+to operate safely.
 
-# preview what an install would write, without touching the disk
-npx @ionivetech/mugiwara@latest --global --target all --yes --dry-run
+---
 
-# global installs skip targets that only support project scope (with a note)
-npx @ionivetech/mugiwara@latest --global --target all --yes
-```
+## Comparing
+
+Mugiwara is a skills pack with a named crew and a gated pipeline. For an honest
+side-by-side against superpowers, agent-skills, frameworks, and mega-prompts —
+including a measured benchmark — see [docs/comparison.md](docs/comparison.md).
+
+## Docs & roadmap
 
-### Install manifest
-
-Every install writes `.mugiwara/manifest.json` (in the project dir, or `~` for
-global). The manifest records the version, scope, targets, and the exact
-list of written files — which is what `update` and `uninstall` use to operate
-safely.
-
-## Targets
-
-All nine supported targets. **Native** targets get first-class skills and
-agents; the rest get markdown rule files the tool picks up from a conventions
-directory. Targets marked *project only* are skipped (with a note) when you
-install with `--global`.
-
-| Target | Scope | Installs as |
-|--------|-------|-------------|
-| Claude Code | global + project | Native skills (`SKILL.md`) + agents in `.claude/skills` / `.claude/agents` (`~/.claude` globally) |
-| opencode | global + project | Native skills + agents in `.opencode/skills` / `.opencode/agents` (`~/.config/opencode` globally) |
-| GitHub Copilot | global + project | Skills as `.instructions.md` files + agents in `instructions/` / `agents/` (`.github` project, `~/.copilot` global) |
-| 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` |
-
-For rule-based targets, skills land as `mugiwara-*.md` and agents as
-`agent-<name>.md`. Targets with a bootstrap file (`Gemini`, `Codex`, `Kilo`)
-create it if it doesn't exist and otherwise tell you the line to add, so your
-tool points at the crew.
-
-## Plugin manifests
-
-Beyond the Claude Code marketplace, mugiwara ships native plugin manifests at
-the repo root so each harness's own installer can pick it up:
-
-| 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 |
-
-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).
-
-> **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.
-
-## 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>
+- [Docs index](docs/index.md) — adoption guide, installs, crew & skill references
+- [Troubleshooting](docs/troubleshooting.md) — common problems and fixes
+- [Roadmap](ROADMAP.md) — what is planned next
 
 ## License