@ionivetech/mugiwara 0.5.1 → 0.5.3

package/GEMINI.md

@@ -0,0 +1,12 @@
+# Mugiwara
+
+The Straw Hat crew of AI agents and skills. 14 specialist agents — Luffy
+orchestrates, Nami plans, Zoro executes, Chopper audits, Brook heals — plus 26
+skills covering brainstorming, planning, execution, checkpointing, quality,
+gates, review, security, and self-healing.
+
+Start any non-trivial mission by loading the `using-mugiwara` skill (or ask "how do I
+use mugiwara?") — it routes you to the right crew member. See
+`content/skills/mugiwara-workflow/SKILL.md` for the full pipeline.
+
+For development standards when working on mugiwara itself, see `AGENTS.md`.

package/README.md

@@ -3,7 +3,7 @@
 [![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)
 
-Your coding agent becomes a governed engineering team. 15 specialists — triage,
+Your coding agent becomes a governed engineering team. 14 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.
 
@@ -11,13 +11,16 @@ and a process that sizes itself to your work. Pure markdown, zero runtime.
 
 ```bash
 # Claude Code
-/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara
 
 # opencode — add to opencode.json
 { "plugin": ["@ionivetech/mugiwara"] }
 
-# CLI for any target
-npx @ionivetech/mugiwara@latest --project . --target all --yes
+# Gemini CLI
+gemini extensions install https://github.com/ionivetech/mugiwara
+
+# Any platform via npm
+npx @ionivetech/mugiwara@latest install --project . --target all --yes
 ```
 
 Then just ask. The crew auto-activates — no agent names to remember.
@@ -99,7 +102,7 @@ One file. Any reviewer reads it in 30 seconds. That's the governance trail.
 
 | 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. |
+| **14 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. |
@@ -127,7 +130,7 @@ team — in your chat window, running inline, visible at every step.
 
 ## The crew
 
-15 personas, 26 skills. Each with a permission boundary.
+14 agents, 26 skills. The front door is the `using-mugiwara` skill — type `/using-mugiwara` or load it from any platform. Each agent has a permission boundary.
 
 | Agent | Role | Permission |
 |-------|------|------------|
@@ -145,93 +148,119 @@ team — in your chat window, running inline, visible at every step.
 | 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).
+See [all 14 agents](docs/agents.md) and [all 26 skills](docs/skills.md).
 
 ## Install
 
-### Claude Code
+Mugiwara installs as a native plugin on every platform. Full details in the per-platform guides.
 
-<details>
-<summary><b>Install / Update / Uninstall</b></summary>
+| Platform | Guide |
+|----------|-------|
+| **Claude Code** | [`/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara`](docs/install-claude.md) |
+| **OpenCode** | [`{ "plugin": ["@ionivetech/mugiwara"] }`](docs/install-opencode.md) |
+| **Gemini CLI** | [`gemini extensions install https://github.com/ionivetech/mugiwara`](docs/install-gemini.md) |
+| **Codex** | [`codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara`](docs/install-codex.md) |
+| **Copilot** | [`copilot plugin install https://github.com/ionivetech/mugiwara`](docs/install-copilot.md) |
+| **Cursor** | [`/add-plugin mugiwara`](docs/install-cursor.md) |
+| **Antigravity** | [`agy plugin install https://github.com/ionivetech/mugiwara`](docs/install-antigravity.md) |
+| **Kimi** | [`/plugins install https://github.com/ionivetech/mugiwara`](docs/install-kimi.md) |
+| **Pi** | [`pi install git:github.com/ionivetech/mugiwara`](docs/install-pi.md) |
+| **Windsurf / Cline / Kilo** | [`npx @ionivetech/mugiwara install --target <id> --yes`](docs/install-cli.md) |
+
+→ **[Full install guide with troubleshooting](docs/install.md)**
+
+### Claude Code
 
 ```bash
-/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara   # install
-/plugin update mugiwara                                                    # update
-/plugin uninstall mugiwara                                                 # uninstall
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara
 ```
-</details>
 
-### opencode
+Update: `/plugin update mugiwara`
+Uninstall: `/plugin uninstall mugiwara`
+
+### OpenCode
 
-<details>
-<summary><b>Install / Update / Uninstall</b></summary>
+Add to `opencode.json`:
 
 ```json
-{ "plugin": ["@ionivetech/mugiwara"] }   // add to opencode.json
+{ "plugin": ["@ionivetech/mugiwara"] }
 ```
 
-```bash
-mugiwara update    # update
-# remove the plugin entry from opencode.json to uninstall
-```
+Update: replace the plugin entry version, or `npm update @ionivetech/mugiwara`
+Uninstall: remove the plugin entry from `opencode.json`.
 
 Restart opencode after install.
-</details>
 
-### GitHub Copilot
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/ionivetech/mugiwara
+```
 
-<details>
-<summary><b>Install / Update / Uninstall</b></summary>
+Update: `gemini extensions update mugiwara`
+Uninstall: `gemini extensions remove mugiwara`
+
+### Codex
 
 ```bash
-copilot plugin marketplace add ionivetech/mugiwara && copilot plugin install mugiwara
-copilot plugin update mugiwara
-copilot plugin uninstall mugiwara
+codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara
 ```
-</details>
 
-### Gemini CLI · Codex · Cursor
+Update: `codex plugin update mugiwara`
+Uninstall: `codex plugin remove mugiwara`
 
-<details>
-<summary><b>Gemini</b></summary>
+### GitHub Copilot
 
 ```bash
-gemini extensions install https://github.com/ionivetech/mugiwara
-gemini extensions update mugiwara
-gemini extensions remove mugiwara
+copilot plugin install https://github.com/ionivetech/mugiwara
+```
+
+Update: reinstall with the same command.
+Uninstall: `copilot plugin uninstall mugiwara`
+
+### Cursor
+
 ```
-</details>
+/add-plugin mugiwara
+```
+
+Update: re-run `/add-plugin mugiwara`.
+Uninstall: `/remove-plugin mugiwara`
 
-<details>
-<summary><b>Codex</b></summary>
+### Antigravity
 
 ```bash
-codex plugin marketplace add ionivetech/mugiwara && codex plugin add mugiwara@mugiwara
-codex plugin update mugiwara
-codex plugin remove mugiwara
+agy plugin install https://github.com/ionivetech/mugiwara
 ```
-</details>
 
-<details>
-<summary><b>Cursor</b></summary>
+Update: reinstall with the same command.
+Uninstall: `agy plugin uninstall mugiwara`
+
+### Kimi
 
 ```
-/add-plugin mugiwara       # install & update
-/remove-plugin mugiwara    # uninstall
+/plugins install https://github.com/ionivetech/mugiwara
 ```
-</details>
 
-### Kimi · pi · Windsurf · Cline · Kilo · Antigravity
+Update: reinstall.
+Uninstall: `/plugins remove mugiwara`
+
+### Pi
+
+```bash
+pi install git:github.com/ionivetech/mugiwara
+```
 
-<details>
-<summary><b>All other harnesses</b></summary>
+### Windsurf · Cline · Kilo · Codex CLI
 
 ```bash
-npx @ionivetech/mugiwara@latest --project . --target all --yes   # install
-mugiwara update                                                    # update
-mugiwara uninstall                                                 # uninstall
+npx @ionivetech/mugiwara@latest install --project . --target all --yes
 ```
-</details>
+
+Substitute `all` with a specific target: `windsurf`, `cline`, `kilo`, `codex`, etc.
+
+Update: `mugiwara update`
+Uninstall: `mugiwara uninstall`
 
 ### Any agent (skills only)
 
@@ -292,8 +321,9 @@ matter to you, this is the wrong tool.
 | Doc | What it covers |
 |-----|---------------|
 | [Getting started](docs/getting-started.md) | First mission, lane 0-3 examples, setup walkthrough |
+| [Install](docs/install.md) | Per-platform guides: Claude Code, OpenCode, Gemini, Codex, Copilot, Cursor, Antigravity, Kimi, Pi, CLI |
 | [Workflow](docs/workflow.md) | Full 9-wave pipeline with heal loop detail |
-| [Agents](docs/agents.md) | 15 crew members, roles, permissions, how to summon |
+| [Agents](docs/agents.md) | 14 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 |

package/content/agents/luffy-orchestrator.md

@@ -1,7 +1,7 @@
 ---
 name: luffy-orchestrator
 description: Persona for mugiwara-orchestration + mugiwara-workflow. Captain: triage, check-ins, closure.
-skills: mugiwara-workflow, mugiwara-orchestration, mugiwara-ship, mugiwara-pr, mugiwara-context-budget
+skills: using-mugiwara, mugiwara-workflow, mugiwara-orchestration, mugiwara-ship, mugiwara-pr, mugiwara-context-budget
 ---
 
 # Luffy — Orchestrator (Captain)

package/content/agents/zoro-execution.md

@@ -2,7 +2,7 @@
 name: zoro-execution
 description: Persona for mugiwara-execution. Executes plan: sequential inline + parallel worker batches. No network: code only, no remote calls.
 permissions: read-write code, no-network
-skills: mugiwara-execution, mugiwara-backend, mugiwara-git, mugiwara-proof-order, mugiwara-contract-first, mugiwara-testcases
+skills: mugiwara-execution, mugiwara-backend, mugiwara-git, mugiwara-contract-first, mugiwara-testcases
 ---
 
 # Zoro — Execution (Dispatcher)

package/content/skills/mugiwara-execution/SKILL.md

@@ -59,12 +59,9 @@ A delegation prompt shorter than ~30 lines is too short — beef it up. Thin pro
 
 ## TDD discipline
 
-The test's proof value comes from WHEN it runs, not that it exists. A test that passes on first run has proven nothing — it never demonstrated it could catch the bug.
+Full TDD discipline: `references/tdd.md` — RED-GREEN-REFACTOR, test pyramid, rationalizations, red flags — 89 lines.
 
-1. **Proof order matters:** the failing test comes first, and you must SEE it fail for the intended reason (the feature is missing, not a typo or a wrong assertion). Only then write the minimal implementation that turns it green.
-2. **No grace for untested code:** production code written before its test is not salvageable "as reference" — discard it and redo it test-first.
-3. **Each test targets one behavior**, names it plainly, and asserts on real behavior rather than mocks where reasonably possible.
-4. **Green is a floor, not a finish**: refactor while the test stays green; never silence a failing test by deleting or weakening it.
+The test's proof value comes from WHEN it runs, not that it exists. A test that passes on first run has proven nothing.
 
 ## User tests as the oracle (per `mugiwara-testcases`)
 

package/content/skills/{mugiwara-proof-order/SKILL.md → mugiwara-execution/references/tdd.md}

@@ -1,17 +1,14 @@
----
-name: mugiwara-proof-order
-description: Use when writing code — TDD, RED-GREEN-REFACTOR, test-driven. Proof value from WHEN the test runs, not that it exists. One test = one behavior.
----
-
 # Test-Driven Development
 
+Full TDD discipline: `references/tdd.md` — 5 sections, 89 lines.
+
+A test proves nothing by existing. It proves nothing by passing. Its entire value lives in WHEN it runs and HOW it fails. TDD is the discipline that makes that proof real.
+
 ## Skip when
 
 - No production code written: docs, config, or pure dependency bump.
 - Refactor already fully covered by existing passing tests (record the reason).
 
-A test proves nothing by existing. It proves nothing by passing. Its entire value lives in WHEN it runs and HOW it fails. TDD is the discipline that makes that proof real.
-
 ## When to use
 
 Every task that writes production code — feature, bug fix, refactor, new function. The moment code leaves your keyboard, its test must already have failed first.

package/content/skills/using-mugiwara/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: using-mugiwara
+description: Use at session start or on any task — explains how the crew works, classifies missions, routes to the right specialist. Front door to the Straw Hat crew.
+---
+
+# Using Mugiwara (Front Door)
+
+## Skip when
+
+- Lane 0 direct work: typo, rename, or single-file fix under 20 LOC.
+- User explicitly declined the crew for this request.
+
+Mugiwara is a governed engineering team in your coding agent. 14 specialists — triage, brainstorm, plan, execute, audit, quality, gates, review, security, heal — with evidence at every step and cost tracking. Runs inline in the main conversation.
+
+## How it works
+
+1. The crew auto-activates for non-trivial requests. You do NOT need to call `using-mugiwara` at session start — it's an optional router.
+2. The pipeline: Luffy triage → Usopp brainstorm → Nami plan → Zoro execute → Chopper audit → Sanji quality → Franky gates → Robin/Jinbe review → Brook heal → Luffy closure.
+3. Every wave runs inline in the main thread. Subagents only for [PARALLEL] task batches.
+4. Evidence over claims — no wave passes on assertion. Checks must be re-run.
+5. Autonomy modes: `/mugiwara guided|semi|auto`. Flip applies next wave.
+6. Workspace: `.mugiwara/` at repo root — plans, results, issues, logs, state.
+
+## Crew
+
+| Agent | Role |
+|-------|------|
+| Luffy | Captain — triage, check-ins, closure |
+| Usopp | Brainstorm — research, explore, recommend |
+| Nami | Planner — interview, scan, write scaled plans |
+| Zoro | Executor — TDD per task, commit per logical unit |
+| Chopper | Auditor — re-run criteria, failure ledger (read-only) |
+| Sanji | Quality — format, lint, test |
+| Franky | Gates — coverage, build, DoD |
+| Robin | Reviewer — breaking-change map (read-only) |
+| Jinbe | Security — STRIDE, OWASP, secret scan (read-only) |
+| Brook | Healer — reads ledger, fixes failures |
+| Skeptic | Adversarial verifier (read-only) |
+| Resume | Continuity — rebuild from state.json |
+
+## What to do
+
+1. If the user asks how mugiwara works — summarize in 3 lines.
+2. If the user gives a task — classify: Trivial / Explicit / Exploratory / Open-ended / Ambiguous.
+3. Route:
+   - Clear, small → Nami (plan) or Zoro (execute).
+   - Vague, needs direction → Usopp (brainstorm).
+   - Anything else → Luffy (full triage + check-ins).
+   - Review → Robin. Security → Jinbe. Audit → Chopper. Heal → Brook.
+4. Record the route in `.mugiwara/logs/`.
+
+Full pipeline: see skills/mugiwara-workflow.

package/dist/mugiwara.js

@@ -152,6 +152,36 @@ var target = {
 
 // src/targets/opencode.ts
 import { join as join2 } from "node:path";
+var CREW = {
+  "luffy-orchestrator": { color: "#ef4444", temperature: 0.2, steps: 15 },
+  "usopp-brainstorm": { color: "#f59e0b", temperature: 0.6, steps: 15 },
+  "nami-planner": { color: "#f97316", temperature: 0.2, steps: 15 },
+  "zoro-execution": { color: "#22c55e", temperature: 0.1, steps: 30 },
+  "chopper-checkpoint": { color: "#3b82f6", temperature: 0.1, permission: { edit: "deny" }, steps: 15 },
+  "sanji-quality": { color: "#a855f7", temperature: 0.1, permission: { edit: "deny" }, steps: 10 },
+  "franky-gates": { color: "#06b6d4", temperature: 0.1, permission: { edit: "deny" }, steps: 10 },
+  "robin-reviewer": { color: "#8b5cf6", temperature: 0.2, permission: { edit: "deny" }, steps: 15 },
+  "jinbe-security": { color: "#6366f1", temperature: 0.2, permission: { edit: "deny" }, steps: 15 },
+  "brook-healing": { color: "#ec4899", temperature: 0.1, steps: 20 },
+  "skeptic-verifier": { color: "#64748b", temperature: 0.1, permission: { edit: "deny" }, steps: 12 },
+  "eval-runner": { color: "#14b8a6", temperature: 0.2, steps: 15 },
+  "resume-coordinator": { color: "#d97706", temperature: 0.2, steps: 10 },
+  "memory-keeper": { color: "#d946ef", temperature: 0.2, steps: 8 }
+};
+function agentFrontmatter(name, description) {
+  const crew = CREW[name];
+  const lines = [`description: ${description}`, `mode: all`];
+  if (crew) {
+    lines.push(`color: '${crew.color}'`, `temperature: ${crew.temperature}`, `steps: ${crew.steps}`);
+    if (crew.permission) {
+      lines.push("permission:");
+      for (const [k, v] of Object.entries(crew.permission))
+        lines.push(`  ${k}: ${v}`);
+    }
+  }
+  return lines.join(`
+`);
+}
 var target2 = {
   id: "opencode",
   label: "opencode",
@@ -167,10 +197,11 @@ var target2 = {
     };
   },
   transformAgent(data, body) {
-    const fm = { name: data.name, description: data.description };
-    if (data.tools)
-      fm.tools = data.tools;
-    return { relPath: `${data.name}.md`, text: stringifyFrontmatter(fm, body) };
+    const fm = agentFrontmatter(data.name, data.description);
+    return { relPath: `${data.name}.md`, text: `---
+${fm}
+---
+${body}` };
   },
   refsDir({ scope, projectDir, home }, skillName) {
     const root = scope === "global" ? join2(home, ".config", "opencode") : join2(projectDir, ".opencode");

package/docs/adoption-guide.md

@@ -14,7 +14,7 @@ markdown rule files everywhere else.
 | You want skills-only, any tool | `npx skills add ionivetech/mugiwara` (agentskills.io layout) |
 | You only use one niche tool | Its per-harness guide (index → install by harness) |
 
-Native targets (Claude Code, opencode, Copilot) register the 15 agents directly.
+Native targets (Claude Code, opencode, Copilot) register the 14 agents directly.
 Rule-based targets (Gemini, Codex, Cursor, Windsurf, Cline, Kilo, Antigravity)
 get the same 32 skills as markdown rules plus a bootstrap pointer, so the crew
 is still steered even where subagents don't exist.

package/docs/agents.md

@@ -1,12 +1,14 @@
-# The Crew — 15 Agents
+# The Crew — 14 Agents
 
 Every agent is a focused specialist. The main thread embodies each role inline
 using its skill; you can also summon any member directly. "Dispatch" below
 means "route the mission to this role."
 
+The front door is the `using-mugiwara` skill — load it for crew overview.
+Slash command: `/using-mugiwara`.
+
 | Agent | Crew member | Role | Summon for |
 |-------|-------------|------|------------|
-| `using-mugiwara` | Front Door | Router — classifies and routes, never implements | "how do I use mugiwara?", any new mission |
 | `luffy-orchestrator` | Luffy | Captain — 5-way triage, check-ins, decisions, closure | mission start, wave boundaries, escalations |
 | `usopp-brainstorm` | Usopp | Critical friend — interrogates, researches, no rubber-stamps | vague ideas, direction, options |
 | `nami-planner` | Nami | Planner — interview-first, full-context scan, scaled plans | turning an idea into an execution plan |
@@ -44,7 +46,7 @@ check-ins. The harness stays coherent either way.
 
 ## The crew ships whole
 
-Every install gets all 15 agents and all 26 skills. No project-type selection —
+Every install gets all 14 agents and all 26 skills. No project-type selection —
 the harness routes each task to the right specialist.
 
 See [skills.md](skills.md) for the 26 techniques, or

package/docs/claude-setup.md

@@ -27,7 +27,7 @@ npx @ionivetech/mugiwara@latest --project ./my-app --target claude --yes
 ## What you get
 
 - 32 skills in `~/.claude/skills/` (global) or `.claude/skills/` (project).
-- 15 agents in `~/.claude/agents/` or `.claude/agents/`.
+- 14 agents in `~/.claude/agents/` or `.claude/agents/`.
 - A SessionStart hook that announces the crew and auto-activates the workflow —
   a non-trivial request runs the pipeline by itself. `/using-mugiwara` is an
   optional explicit router if you want to hand-route a mission.

package/docs/developer-onboarding.md

@@ -45,7 +45,7 @@ resolve to `content/` and never diverge.
 ## Validation
 
 ```bash
-bun run validate                # 32 skills + 15 agents: names, descriptions, skip gates, line limits
+bun run validate                # 26 skills + 14 agents: names, descriptions, skip gates, line limits
 bun run validate --check-sync   # symlinks resolve to content/, never diverge
 bun run typecheck               # tsc --noEmit
 bun run test                    # vitest

package/docs/getting-started.md

@@ -150,7 +150,7 @@ six. See [audit-trail.md](audit-trail.md) for the full artifact map.
 
 ## 6. Next steps
 
-- Meet the [crew](agents.md) — 15 agents with permission boundaries.
+- Meet the [crew](agents.md) — 14 agents with permission boundaries.
 - Browse the [skills](skills.md) — 26 skills with the 3-layer disclosure model.
 - Understand the [lanes](lanes.md) — how work is sized before it runs.
 - Set your [mode](modes.md) — guided/semi/auto.

package/docs/index.md

@@ -19,7 +19,7 @@ claim.
 | [Modes](modes.md) | guided / semi / auto — the autonomy levels, what each asks you |
 | [Config](config.md) | Full reference for `.mugiwara/config` keys and commit styles |
 | [Auto-PR](pr-summary.md) | What the crew hands off at closure: push + a ready-to-paste PR summary (it never creates a PR) |
-| [The crew](agents.md) | All 15 agents and when to summon each |
+| [The crew](agents.md) | All 14 agents and when to summon each |
 | [The techniques](skills.md) | All 32 skills and what each enforces |
 | [The wave pipeline](workflow.md) | How a mission flows Wave 0 → Wave 9 |
 | [Execution model](execution-model.md) | Inline-by-default: why the crew runs in your main conversation |

package/docs/install-antigravity.md

@@ -0,0 +1,45 @@
+# Antigravity Install
+
+Mugiwara installs as an Antigravity plugin from this repo.
+
+## Prerequisites
+
+- [Antigravity](https://antigravity.google) installed
+
+## Install
+
+```bash
+agy plugin install https://github.com/ionivetech/mugiwara
+```
+
+## How it works
+
+Antigravity reads `.agents/plugins/marketplace.json` and installs the plugin
+from the repo root. Skills and agents are auto-discovered.
+
+## Verify
+
+Ask:
+
+```
+what mugiwara crew members are available?
+```
+
+## Update
+
+Reinstall with the same command:
+
+```bash
+agy plugin install https://github.com/ionivetech/mugiwara
+```
+
+## Uninstall
+
+```bash
+agy plugin uninstall mugiwara
+```
+
+## Configuration
+
+After install, configure mugiwara in `.mugiwara/config` (project) or
+`~/.mugiwara/config` (global). See [docs/config.md](config.md).

package/docs/install-claude.md

@@ -0,0 +1,75 @@
+# Claude Code Install
+
+Mugiwara is a full Claude Code native plugin with agents, skills, and a
+session-start hook.
+
+## Prerequisites
+
+- [Claude Code](https://claude.ai/code) installed
+- Node.js >= 20.11
+
+## Install
+
+```bash
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara
+```
+
+## How it works
+
+Claude Code clones the repo and reads from:
+
+- `skills/` and `agents/` — symlinks to `content/skills/` and
+  `content/agents/`. Claude Code auto-discovers all 26 skills and 14 agents.
+- `hooks/hooks.json` — defines a SessionStart hook that runs
+  `hooks/session-start.ts`, injecting the crew announce header at every
+  session start.
+
+The hook announces: "Mugiwara crew available. The workflow auto-activates
+for non-trivial requests..."
+
+## Verify
+
+Ask:
+
+```
+what mugiwara crew members are available?
+```
+
+Or start any task — the crew auto-activates at session start.
+
+## Update
+
+```
+/plugin update mugiwara
+```
+
+## Uninstall
+
+```
+/plugin uninstall mugiwara
+```
+
+## Configuration
+
+After install, configure mugiwara in `.mugiwara/config` (project) or
+`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+
+Switch autonomy mode with `/mugiwara-mode guided|semi|auto`.
+
+## Troubleshooting
+
+### Plugin not showing up
+
+1. Verify marketplace is registered: `/plugin marketplace list`
+2. If not, re-run the marketplace add command
+3. Check Claude Code is up to date
+
+### Skills not found
+
+1. Check that `skills/` and `agents/` symlinks resolve correctly
+2. Reinstall: `/plugin uninstall mugiwara` then reinstall
+
+### Hook not running
+
+The session-start hook requires Claude Code plugin hook support. Ensure
+you're on a recent Claude Code version.