@ionivetech/mugiwara 0.1.3 → 0.3.0

package/README.md

@@ -2,75 +2,96 @@
 
 [![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.
+The Straw Hat crew of AI agents and skills — a complete software development
+workflow for your coding agent.
 
-Zero runtime: pure markdown your existing AI agent runs with its own subagent
-machinery — no daemons, no plugins to keep updated, nothing to host.
+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.
 
-## Why Mugiwara
+```
+   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  │
+ └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
+```
 
-- 🧭 **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.
-- 🔁 **Wave pipeline.** brainstorm → plan → execute → audit → quality → gates
-  → review → security → heal → closure. Failure loops back through healing
-  (max 3 cycles), never ships broken.
+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.
-- ⚡ **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.
+- 📦 **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
+## 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 |
 |-------|-------------|------|
-| `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 |
+| `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, wave structure, anti-patterns, parallel-safe plans |
-| `zoro-execution` | Zoro | Execute plans: todo list first, parallel/sequential subagent dispatch, evidence per task |
+| `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 tests only with consent |
+| `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: OWASP, secrets, injection, auth, dependencies, untrusted-data doctrine |
-| `brook-healing` | Brook | Reads the blocker ledger, Stop-the-Line root-cause fixes, ≤3 heal cycles |
+| `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, fix the skill not the eval |
+| `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 — 21 skills
+## The techniques — 32 skills
 
 | Skill | Purpose |
 |-------|---------|
-| `mugiwara-workflow` | The harness entry point: 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-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, 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-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` | 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-frontend` | Anti-slop frontend: audit-first redesigns, design-system extraction, slop list |
+| `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-ship` | GO/NO-GO ship gate: pre-launch checklist, feature flags, rollback plan |
+| `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 |
@@ -78,78 +99,179 @@ subagent machinery and may call the crew's shared skills.
 | `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 21 skills and 15 agents, including
+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
 
-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.
+**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
-    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] --> 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]
 ```
 
-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 |
 | 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, 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 |
+| 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; loops back to Wave 4, max 3 cycles |
-| 9 Closure | Luffy | `mugiwara-orchestration` | closure report appended to the plan |
+| 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`):
+
+```
+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).
+
+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 summary + verdict file (you
+  open the PR). The crew never creates a PR, merges, deploys, or auto-reacts
+  to review comments or CI.
+
+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:
 
 - **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 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.
+
+## Config reference
+
+`.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.
+
+| 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 |
+
+### Commit message styles
+
+`commit` selects how Zoro writes commit messages:
 
-### The `.mugiwara/` workspace
+- **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.
+
+Switch freely per project — it only affects the message format, never the
+one-logical-task-one-commit rule.
+
+## The `.mugiwara/` workspace
 
 Every mission works inside `.mugiwara/` at the repo root:
 
 ```
 .mugiwara/
+├── config         # mode + writing standards (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)
 ```
 
 **Blocker protocol:** any crew member that hits a blocker appends a row
@@ -158,330 +280,235 @@ Every mission works inside `.mugiwara/` at the repo root:
 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.
-
-The owning agent creates the folder it needs on first write. Mission artifacts
-never land outside `.mugiwara/`.
+files (consumed results, review, issues, and per-mission decision logs). The
+plan doc and the closure report stay.
 
 ## Install
 
-Requires **Node.js >= 20.11**. Bun is optional — you only need it to build
-from source.
+### Via your AI agent
 
-### npx
+<details>
+<summary><strong>Claude Code</strong> — agents + skills + SessionStart hook</summary>
 
-```bash
-# npx — run without installing (recommended)
-npx @ionivetech/mugiwara@latest
+**Install**
 
-# 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
+```bash
+/plugin marketplace add ionivetech/mugiwara
+/plugin install mugiwara
 ```
 
-### npm — global install
+**Update** — re-install from the marketplace (or `mugiwara update` via CLI).
 
-```bash
-# npm — global install, run `mugiwara` anywhere
-npm install -g @ionivetech/mugiwara
-```
+**Uninstall** — `/plugin uninstall mugiwara`, or `mugiwara uninstall` via CLI.
+</details>
 
-### curl — macOS / Linux
+<details>
+<summary><strong>opencode</strong> — native skills + agents via plugin</summary>
 
-```bash
-# curl — macOS/Linux one-liner
-curl -fsSL https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.sh | bash
+**Install** — add to `opencode.json`:
+
+```json
+{ "plugin": ["@ionivetech/mugiwara"] }
 ```
 
-### PowerShell — Windows
+Or from the git repo directly:
 
-```powershell
-# PowerShell — Windows one-liner
-irm https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.ps1 | iex
+```json
+{ "plugin": ["mugiwara@git+https://github.com/ionivetech/mugiwara.git"] }
 ```
 
-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.
+**Update** — bump the package version in the `plugin` array (or `mugiwara update`).
+
+**Uninstall** — remove the entry from the array.
+</details>
 
-### skills.sh — skills only, any agent
+<details>
+<summary><strong>GitHub Copilot CLI</strong> — same marketplace</summary>
 
-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:
+**Install**
 
 ```bash
-npx skills add ionivetech/mugiwara
+copilot plugin marketplace add ionivetech/mugiwara
+copilot plugin install 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.
-
-### Requirements
-
-| Dependency | Required for | Version |
-|------------|--------------|---------|
-| Node.js | running the CLI and the built artifact | >= 20.11 |
-| Bun | building from source, running tests | optional |
+> 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.
 
-## Quickstart
+**Update** — `copilot plugin update mugiwara`. **Uninstall** — `copilot plugin uninstall mugiwara`.
+</details>
 
-```console
-$ npx @ionivetech/mugiwara@latest --global --target claude --yes
-mugiwara — installing crew for: claude
-  ✓ claude    15 agents, 21 skills → ~/.claude/skills + ~/.claude/agents
-  ✓ manifest  wrote ~/.mugiwara/manifest.json
-  ✓ done      24 files written
+<details>
+<summary><strong>Gemini CLI</strong> — extension</summary>
 
-$ # now just ask your Claude Code session
-> add dark mode to the settings page
+**Install**
 
-  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
+```bash
+gemini extensions install https://github.com/ionivetech/mugiwara
 ```
 
-You never drive the sequence — you answer Nami's clarifying questions up front
-and review Brook's rollback note if a fix is risky.
+**Update** — `gemini extensions update mugiwara`.
+**Uninstall** — `gemini extensions remove mugiwara`.
+</details>
 
-## Commands and flags
+<details>
+<summary><strong>Codex</strong> — plugin</summary>
 
-### 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 (project root, or `~` for global) |
-| `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 |
+**Install**
 
 ```bash
-# non-interactive install requires scope + target, or it errors out
-npx @ionivetech/mugiwara@latest --project ./app --target claude --yes
-
-# 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
+codex plugin marketplace add ionivetech/mugiwara
+codex plugin add mugiwara@mugiwara
 ```
 
-### Install manifest
+**Update** — `codex plugin update mugiwara`. **Uninstall** — `codex plugin remove mugiwara`.
+</details>
 
-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.
+<details>
+<summary><strong>Cursor</strong> — plugin</summary>
 
-## 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`.
+**Install**
 
-| 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` |
+```
+/add-plugin mugiwara
+```
 
-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.
+**Update** — re-run `/add-plugin mugiwara`. **Uninstall** — `/remove-plugin mugiwara`.
+</details>
 
-## Claude Code plugin install
+<details>
+<summary><strong>Kimi Code</strong> — plugin</summary>
 
-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`.
+**Install**
 
-```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
+/plugins install https://github.com/ionivetech/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).
+**Update** — `/plugins update mugiwara`. **Uninstall** — `/plugins remove mugiwara`.
+</details>
 
-## FAQ / troubleshooting
+<details>
+<summary><strong>pi</strong> — package</summary>
 
-**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.
+**Install**
 
-**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.
+```bash
+pi install git:github.com/ionivetech/mugiwara
+```
 
-**Does it work on Windows?** Yes — PowerShell one-liner
-(`irm ...install.ps1 | iex`), and the CLI itself runs anywhere Node >= 20.11
-does.
+**Update** — `pi update mugiwara`. **Uninstall** — `pi remove mugiwara`.
+</details>
 
-**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.
+<details>
+<summary><strong>npx / npm / curl / PowerShell</strong> — the mugiwara CLI</summary>
 
-**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.
+Requires **Node.js >= 20.11**. Bun is optional — only needed to build from source.
 
-**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.
+**Install**
 
-**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.
+```bash
+# run without installing (wizard)
+npx @ionivetech/mugiwara@latest
 
-## Development
+# non-interactive: global Claude Code install, no prompts
+npx @ionivetech/mugiwara@latest --global --target claude --yes
 
-### Prerequisites
+# non-interactive: project install for opencode + GitHub Copilot
+npx @ionivetech/mugiwara@latest --project ./my-app --target opencode,copilot --yes
 
-- **Bun** — the build and test toolchain
-- **Node.js >= 20.11** — the built artifact runs on plain Node
+# npm — global install, run `mugiwara` anywhere
+npm install -g @ionivetech/mugiwara
+```
 
 ```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
+# curl — macOS / Linux one-liner
+curl -fsSL https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.sh | bash
 ```
 
-`bun run build` runs automatically on `npm pack` / `npm publish` (via
-`prepack`).
+```powershell
+# PowerShell — Windows one-liner
+irm https://raw.githubusercontent.com/ionivetech/mugiwara/main/scripts/install.ps1 | iex
+```
 
-### Project layout
+**Update** — `mugiwara update` (or `npm update -g @ionivetech/mugiwara`).
 
-```
-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
+**Uninstall** — `mugiwara uninstall` (removes exactly what the manifest recorded; or `npm uninstall -g @ionivetech/mugiwara`).
+</details>
+
+**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):
+
+```bash
+npx skills add ionivetech/mugiwara
 ```
 
-### Adding a skill
+## CLI commands and flags
 
-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`.
+### Commands
 
-### Adding an agent
+| 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 |
 
-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`.
+### Flags
 
-## Content schema
+| 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 skill and agent is a single markdown file with **flat frontmatter** — no
-nested fields:
+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.
 
-```yaml
----
-name: mugiwara-example
-description: Use when <trigger condition> — <what it does, how it behaves>.
----
+## Targets
 
-<body>
-```
+| 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` |
 
-| 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 |
+## Plugin manifests
 
-Run `bun run validate` before opening a PR — it checks all of this and exits
-non-zero on any violation.
+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. 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)