@ionivetech/mugiwara 0.2.0 → 0.4.0

package/docs/comparison.md

@@ -1,63 +1,185 @@
 # Comparison
 
-How mugiwara fits against the alternatives.
+How mugiwara fits against the alternatives — and an honest benchmark.
 
-## Mugiwara vs. plain skills (agent-skills / skills.sh)
+## The landscape
 
-The [agent-skills](https://github.com/addyosmani/agent-skills) ecosystem ships
-standalone skills that an agent picks up on demand. Mugiwara ships the same
-portable `SKILL.md` format — and also ships:
+| Tool | What it is | Harnesses |
+|------|-----------|-----------|
+| **mugiwara** | Crew (15 agents) + pipeline (9 waves, gated) + 32 skills + lane sizing | 12 harnesses + 70+ via skills.sh |
+| **superpowers** | Skills-only methodology with auto-trigger + subagent-driven development | 11 harnesses |
+| **agent-skills** (addyosmani) | 24 skills + 8 slash commands + 4 personas, Google engineering culture | 70+ via skills.sh |
+| **anthropics/skills** | Official demo skills — creative/docs/document skills, not a dev pipeline | Claude Code |
+| **mattpocock/skills** | Small composable engineering skills, mostly user-invoked | Claude Code + Codex + any |
+| **agent frameworks** (LangGraph, CrewAI, …) | Code: graphs, nodes, runtimes to host | one per framework |
+| **mega-prompt** | One big instruction | any |
 
-- **A named crew** — personas (Luffy, Nami, Zoro, …) on top of the skills, so
-  the pipeline has a defined owner per wave instead of "whichever skill fires."
-- **A pipeline, not a pile** — ordered waves (triage → plan → execute →
-  checkpoint → quality → gates → review → heal → closure) with gates between.
-- **Evidence discipline** — no wave passes on a claim; the owning role runs the
-  checks and shows output.
-- **A workspace contract** — `.mugiwara/` holds plan, results, ledger, and
-  logs, so a mission survives context loss.
+## Mugiwara vs. skills packs (superpowers, agent-skills)
 
-You can still install just the skills (`npx skills add ionivetech/mugiwara`).
+Both are markdown skills an agent picks up on demand. Mugiwara ships the same
+portable `SKILL.md` format — and adds what a pile of skills cannot:
+
+- **A named crew, not a pile.** 15 personas (Luffy, Nami, Zoro, …) each own a
+  wave, so the pipeline has a defined owner and handoff instead of "whichever
+  skill fires first."
+- **A gated pipeline, not loose triggers.** Ordered waves
+  (triage → plan → execute → checkpoint → quality → gates → review → heal →
+  closure) with a verify-everything gate between and a bounded heal loop.
+  Superpowers has a gated workflow too (`spec → plan → build → verify →
+  review`); agent-skills exposes gates as slash commands but does not chain
+  them into one pipeline.
+- **Sizing (lane routing).** Work is sized before it runs: a one-file typo runs
+  zero waves, an auth change always runs all nine. No other pack scales the
+  process to the work — they run the same ceremony (or lack of it) for every
+  task. Mugiwara's auto-lane also means **trivial fixes are handled natively**,
+  not "don't use it for small stuff."
+- **Skip gates.** Every mugiwara skill declares when it does *not* apply, so a
+  docs-only change skips Jinbe's security audit instead of burning a wave.
+- **Workspace + resume.** `.mugiwara/` holds plan, results, ledger, and logs,
+  so a mission survives context loss and resumes instead of restarting.
+- **A single source of truth.** `content/` is the only physical copy; every
+  harness reads the same files (symlinks), so there is no drift between
+  "Claude version" and "Cursor version."
+
+### Against superpowers specifically
+
+Superpowers is excellent at deep autonomous work: its subagent-driven
+development dispatches a fresh subagent per task with two-stage review, and
+runs for hours. Differences:
+
+- **Visibility.** Mugiwara runs inline by default — you watch every wave in the
+  main conversation. Superpowers hides work behind subagent dispatch.
+- **Crew depth.** Mugiwara ships 15 agents (auditor, security, gates, healing,
+  memory) vs. superpowers' review-first model. A standalone security wave with
+  STRIDE + OWASP and a dedicated healer are mugiwara-specific.
+- **Wider surface.** Mugiwara adds domain skills (frontend anti-slop, backend,
+  agent-security) and meta-controls (mode, resume, lessons) beyond the
+  build-loop superpowers centers on.
+
+### Against agent-skills specifically
+
+agent-skills has the strongest SDLC breadth (19/21 categories in the audit
+baseline) and carries Google's engineering culture (Hyrum's Law, test pyramid,
+Chesterton's Fence). Differences:
+
+- **Pipeline vs. commands.** agent-skills gates are per-skill; the agent must
+  chain them by hand. Mugiwara chains them into one auto-running pipeline.
+- **Healing.** agent-skills reports; mugiwara's Brook reads the failure ledger
+  and fixes root causes in a bounded loop — the loop agent-skills lacks.
+- **Sizing.** agent-skills runs its full process on any change; mugiwara routes
+  to a lane first.
 
 ## Mugiwara vs. agent frameworks (LangGraph, CrewAI, …)
 
 Framework crews are code: graphs, nodes, runtimes to host. Mugiwara is:
 
-- **Zero runtime** — pure markdown; your existing agent's own subagent
-  machinery does the work. Nothing to deploy, nothing to keep updated.
-- **Harness-native** — installs into Claude Code, opencode, Copilot, Gemini,
-  Codex, Cursor, and 70+ tools rather than forcing one runtime.
-- **Inline** — the pipeline runs in your main conversation (see
-  [execution-model.md](execution-model.md)); frameworks hide the work behind
-  their own execution graph.
+- **Zero runtime.** Pure markdown; your existing agent's own machinery does the
+  work. A tiny Node CLI exists only to install and uninstall. Nothing to
+  deploy, nothing to keep updated.
+- **Harness-native.** The same crew installs into 12 harnesses instead of
+  forcing one runtime.
+- **Inline.** The pipeline runs in your main conversation; frameworks hide the
+  work behind their execution graph.
+
+Frameworks win when you need API-driven crews, deployable graphs, or
+deterministic orchestration in code. If your team runs agents as a service,
+pick a framework; if you want your existing coding agent to work *better*, pick
+mugiwara.
+
+## Mugiwara vs. a mega-prompt
+
+A mega-prompt is one big instruction. Mugiwara:
+
+- **Splits by specialization** — 32 focused skills + 15 personas instead of one
+  document trying to be everything.
+- **Sizes** — lanes mean small tasks skip the pipeline instead of paying the
+  mega-prompt's full cost every time.
+- **Gates + heals** — verifiable gates catch drift; a bounded heal loop fixes
+  root causes instead of re-running the same prompt.
 
-## Mugiwara vs. a single mega-prompt
+## What they all share
 
-A mega-prompt gives you one big instruction. Mugiwara:
+Every option above — including mugiwara — is **prose an agent chooses to
+follow**. Markdown cannot force a model to comply. What differs is how much
+structure the prose builds to catch drift: mugiwara's answer is the wave gates,
+the skip gates, the lane sizing, and the workspace contract.
 
-- **Splits by specialization** — 25 focused skills + 15 personas instead of one
-  document that tries to be everything, so each phase has a tight contract.
-- **Is gated** — every wave has a verifiable gate and a recorded reason, so
-  drift is caught early.
-- **Heals** — a bounded 3-cycle heal loop reads the failure ledger and fixes
-  root causes, instead of re-running the same mega-prompt.
+## Benchmark
 
-## When NOT to use mugiwara
+Measured against `content/` at the audit baseline (Aug 2026). Token figures are
+estimates (chars ÷ 4); skill counts are exact.
 
-- **One-line fixes** — Luffy routes trivia straight to execution; you don't
-  need the crew for a typo.
-- **You want a framework runtime** — if you need orchestration in code,
-  deployable graphs, or API-driven crews, a framework is the right tool.
-- **You want the crew to merge/deploy** — mugiwara deliberately stops at push +
-  PR. Human review is the terminal gate.
+### Size & density
+
+| Metric | mugiwara | superpowers | agent-skills |
+|--------|:--------:|:-----------:|:------------:|
+| Skills | **32** | 14 | 24 |
+| Index size (all descriptions loaded) | ~2.0k tok | ~0.5k tok | ~1.7k tok |
+| Avg skill size | **~1.2k tok** | ~2.3k tok | ~3.1k tok |
+| Avg skill length | **~80 lines** | ~227 lines | ~305 lines |
+| Skills with a skip gate | **32/32** | 0/14 | 11/24 |
+
+Mugiwara ships the most skills with the smallest average footprint — the
+biggest pack with the densest per-skill content.
+
+### Process & capability
+
+| Dimension | mugiwara | superpowers | agent-skills |
+|-----------|:--------:|:-----------:|:------------:|
+| Ordered pipeline | ✅ 9 waves + gates | ✅ spec→plan→build→verify | ⚠️ per-command |
+| Lane sizing (work scales process) | ✅ 0–4 | ❌ | ❌ |
+| Named crew / agents | ✅ 15 | ❌ | ⚠️ 4 personas |
+| Auto-activation | ✅ | ✅ | ⚠️ per-command |
+| Evidence gates on every wave | ✅ | ✅ | ✅ |
+| Skip gates per skill | ✅ 32/32 | ❌ | ⚠️ 11/24 |
+| Self-healing loop | ✅ bounded 3-cycle | ⚠️ review-block | ❌ |
+| Session resume from disk | ✅ | ⚠️ worktree-based | ❌ |
+| Cross-mission memory (lessons) | ✅ | ❌ | ❌ |
+| Security review as a first-class wave | ✅ STRIDE+OWASP | ⚠️ via review | ⚠️ security skill |
+| Workspace contract | ✅ `.mugiwara/` | ⚠️ worktrees | ❌ |
+| Slash commands (manual stages) | ✅ 6 | ✅ | ✅ 8 |
+| Agent-layer security skill | ✅ | ❌ | ❌ |
+
+### Harness / portability
+
+| Metric | mugiwara | superpowers | agent-skills |
+|--------|:--------:|:-----------:|:------------:|
+| Native install targets | 12 | 11 | ~15 |
+| Skills-only via skills.sh | ✅ 70+ | ✅ | ✅ |
+| Tiered emission (stub for glob-loading harnesses) | ✅ | ❌ | ❌ |
+| Static token load on rules-dir harnesses | **~4.8k** (stubs) | n/a | n/a |
+
+### Where mugiwara is *not* the best fit
+
+- **Deep autonomous marathon runs.** If you want an agent to disappear for
+  hours on a subagent-driven build with minimal visibility, superpowers'
+  `subagent-driven-development` is built for exactly that.
+- **Google-culture reference depth.** agent-skills' source-cited engineering
+  practices (Hyrum's Law, test pyramid, review norms) are richer per skill.
+- **A runtime service.** If you need API-driven, deployable agent crews, use a
+  framework.
 
 ## Summary
 
-| | Mugiwara | Plain skills | Framework crews | Mega-prompt |
-|---|----------|--------------|-----------------|-------------|
-| Runtime | none | none | yes | none |
-| Pipeline | ordered waves + gates | on-demand | graph | linear |
-| Visibility | inline in your chat | inline | behind the graph | inline |
-| Evidence gates | yes | no | configurable | no |
-| Self-healing | yes (3-cycle loop) | no | configurable | no |
-| Harnesses | 12+ | 70+ | one per framework | any |
+| | Mugiwara | Superpowers | Agent-skills | Frameworks | Mega-prompt |
+|---|----------|-------------|--------------|------------|-------------|
+| Skills | 32 | 14 | 24 | — | 1 |
+| Pipeline | 9 waves + gates | gated workflow | per-command | graph | linear |
+| Lane sizing | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Named crew | 15 | — | 4 personas | code | — |
+| Skip gates | 32/32 | 0/14 | 11/24 | — | — |
+| Self-healing | ✅ | ⚠️ | ❌ | configurable | ❌ |
+| Session resume | ✅ | ⚠️ | ❌ | — | ❌ |
+| Lessons memory | ✅ | ❌ | ❌ | — | ❌ |
+| Visibility | inline | subagent-heavy | inline | behind graph | inline |
+| Runtime | none | none | none | yes | none |
+| Harnesses | 12+ / 70+ | 11 | 70+ | 1 | any |
+
+**Bottom line.** Mugiwara is the only option that scales the process to the
+work (lane routing), ships a named gated crew with a bounded heal loop, and
+keeps the full pipeline visible inline — while carrying the most skills at the
+lowest average cost. Where it trades ground: marathon subagent autonomy
+(superpowers) and per-skill reference depth (agent-skills).
+
+*Benchmark figures are estimates from the audit baseline (Aug 2026); mugiwara
+skill counts are exact, competitor counts from their READMEs.*

package/docs/config.md

@@ -0,0 +1,53 @@
+# 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.
+
+**Mode owns autonomy, config owns writing standards.** Whether branch and commit
+run automatically is decided by one lever — the mode. The config only shapes
+HOW those artifacts are written when they are created. See [modes.md](modes.md)
+for the mode matrix.
+
+## Example file
+
+```
+# .mugiwara/config
+mode=guided
+branch=feature/{type}-{issue}-{slug}
+commit=conventional
+base=main
+```
+
+## Keys
+
+| 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 |
+
+The mission **lane** (how many waves run) is decided by Luffy at triage — see
+[lanes.md](lanes.md). Config holds autonomy and writing standards only.
+
+Missing config on read = `guided`. Flip mid-mission with
+`mugiwara mode <guided|semi|auto>` — the change applies from the next wave,
+never mid-wave.
+
+## Commit message styles
+
+`commit` selects how Zoro writes commit messages:
+
+- **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.

package/docs/copilot-setup.md

@@ -13,9 +13,11 @@ copilot plugin install mugiwara
 npx @ionivetech/mugiwara@latest --project ./my-app --target copilot --yes
 ```
 
+**Update** — `copilot plugin update mugiwara`. **Uninstall** — `copilot plugin uninstall mugiwara`.
+
 ## What you get
 
-- 25 skills as `.instructions.md` files in `.github/` (project) or
+- 32 skills as `.instructions.md` files in `.github/` (project) or
   `~/.copilot/` (global).
 - Agents as markdown files in `instructions/` / `agents/`.
 

package/docs/cursor-setup.md

@@ -12,9 +12,11 @@ Or via the CLI:
 npx @ionivetech/mugiwara@latest --project ./my-app --target cursor --yes
 ```
 
+**Update** — re-run `/add-plugin mugiwara`. **Uninstall** — `/remove-plugin mugiwara`.
+
 ## What you get
 
-- 25 skills as markdown rule files.
+- 32 skills as markdown rule files.
 - The `.cursor-plugin/plugin.json` manifest.
 
 ## Notes

package/docs/developer-onboarding.md

@@ -18,35 +18,39 @@ bun install
 ```
 mugiwara/
 ├── content/            # single source of truth: skills/ + agents/ markdown
-├── agents/             # synced copy of content/agents (plugin copies at repo root)
-├── skills/             # synced copy of content/skills
+├── agents/             # symlink → content/agents (Claude Code plugin reads plugin root)
+├── skills/             # symlink → content/skills
 ├── src/                # CLI, installer, targets, frontmatter parser
 ├── scripts/            # validate-content, sync-version, run-evals, install scripts
 ├── test/               # vitest suite
 ├── .opencode/plugins/  # opencode plugin (registers crew at config load)
-├── .claude-plugin/     # Claude Code marketplace + sync.sh
+├── .claude-plugin/     # Claude Code marketplace + sync.sh (symlink guard)
 └── docs/               # these docs
 ```
 
 ## The source of truth
 
-`content/` is canonical. The repo-root `agents/` and `skills/` copies are
-generated for harnesses that read the repo directly:
+`content/` is the only physical source. The repo-root `agents/` and `skills/`
+are **symlinks** into it, so harnesses that read the plugin root (Claude Code
+marketplace) see the same files — there is no copy to drift. On a fresh clone
+where the symlinks are missing, recreate them:
 
 ```bash
 sh .claude-plugin/sync.sh
 ```
 
-Always edit `content/`, then sync. `bun run validate --check-sync` fails if the
-copies drift.
+Always edit `content/`. `bun run validate --check-sync` verifies the symlinks
+resolve to `content/` and never diverge.
 
 ## Validation
 
 ```bash
-bun run validate                # 25 skills + 15 agents: names, descriptions, line limits
-bun run validate --check-sync   # plugin copies match content/
+bun run validate                # 32 skills + 15 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 (43 tests)
+bun run test                    # vitest
+bun run evals                   # eval suite valid (structure + coverage gates)
+bun run evals --run             # optional: execute cases against a model CLI (MUGIWARA_EVAL_CMD)
 ```
 
 ## Editing a skill or agent
@@ -55,8 +59,7 @@ bun run test                    # vitest (43 tests)
 2. Respect the house style (see [skill-anatomy.md](skill-anatomy.md) and
    [agent-anatomy.md](agent-anatomy.md)): evidence over claims, exact commands,
    red flags, ≤120-line skill bodies.
-3. `sh .claude-plugin/sync.sh`
-4. `bun run validate && bun run typecheck && bun run test`
+3. `bun run validate && bun run typecheck && bun run test`
 
 ## Adding a new skill or agent
 
@@ -64,7 +67,8 @@ bun run test                    # vitest (43 tests)
 2. If it's an agent, list its held skills in frontmatter; give it a
    `description` ≥20 chars.
 3. If it's a skill, pick a folder name that matches `name`; description 20–500
-   chars; body ≤120 lines.
+   chars; body ≤120 lines; include a `## Skip when` block (1–4 bullets, numeric
+   thresholds) so the skill knows when it does not apply.
 4. Update the crew/technique tables in `README.md` and the docs (`agents.md`,
    `skills.md`).
 5. Sync + validate + test.

package/docs/enforcement.md

@@ -0,0 +1,38 @@
+# Enforcement
+
+A markdown harness cannot force a model to comply with prose — that is the
+ceiling of every skills pack, mugiwara included. Mugiwara is a skills pack, not
+a plugin with hooks: it ships markdown the agent reads and follows. What keeps
+the pipeline honest is the skills themselves, not a CLI.
+
+## Skip gates
+
+Every skill carries a `## Skip when` block: ≤4 bullets, numeric thresholds,
+telling the agent when the skill does not apply. The content validator
+(`bun run validate`) fails the build when a skill lacks the block, so the gate
+cannot rot. A skipped skill is recorded in the decision log, never silent.
+
+## Evidence over claims
+
+Every skill enforces the iron law: a wave passes only on command output or a
+file the agent can point at. "Subagents lie. No evidence = not complete." This
+is prose the agent follows, checked by no tool — the honest limit.
+
+## Capability tiers
+
+How skills load differs per harness:
+
+| Tier | Harnesses | Skill loading |
+|------|-----------|---------------|
+| 1 | Claude Code, opencode | progressive — read by trigger, not all at once |
+| 2 | Copilot, Gemini, Codex | bootstrap pointer → the model chooses what to read |
+| 3 | Windsurf, Cline, Kilo, Antigravity | rules dirs glob-load — skills ship as stubs, full bodies in `.mugiwara/refs/` |
+
+On tier 3, skills ship as small stubs (routing + pointer) so glob-loading
+harnesses stop eating ~40k tokens; the full body lives in `.mugiwara/refs/`,
+read on demand. Tier 3 also uses **wave-boundary state flush**: the full
+mission state is written to `.mugiwara/` at each wave so the next wave resumes
+without the previous context — the portable substitute for subagent isolation.
+
+**Honest limit.** Mugiwara cannot force an agent to follow a skill. That is
+true on every tier and every harness. It is a skills pack, not a supervisor.

package/docs/execution-model.md

@@ -3,6 +3,13 @@
 Why the crew runs in your main conversation — and when subagents are actually
 used.
 
+## Auto-activation
+
+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.
+
 ## Inline by default
 
 The crew runs **inline**. The main thread embodies each crew role using that
@@ -50,6 +57,32 @@ linear.
 - Sequential work never takes a subagent round-trip — no skipping, no hidden
   reordering, plan order is plan order.
 
+## 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
+
+Prefer 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.
+
 ## Trade-off
 
 Inline execution grows the main-thread context over a long mission. The crew

package/docs/gemini-setup.md

@@ -12,9 +12,12 @@ Or via the CLI:
 npx @ionivetech/mugiwara@latest --project ./my-app --target gemini --yes
 ```
 
+**Update** — `gemini extensions update mugiwara`.
+**Uninstall** — `gemini extensions remove mugiwara`.
+
 ## What you get
 
-- 25 skills as markdown rules in `.gemini/mugiwara/`.
+- 32 skills as markdown rules in `.gemini/mugiwara/`.
 - A `GEMINI.md` bootstrap pointer (created if missing).
 
 ## Notes

package/docs/getting-started.md

@@ -32,7 +32,10 @@ Requires **Node.js >= 20.11**. Bun is optional (build-from-source only).
 
 ## 2. Start a mission
 
-Once installed, just ask. No agent names to remember — say what you want built:
+The workflow **auto-activates**: at session start the crew is announced, and
+when you give a non-trivial request the pipeline runs by itself — no need to
+call `/using-mugiwara`. It remains an optional explicit router if you want to
+hand-route a mission. Just ask, no agent names to remember:
 
 ```
 > add dark mode to the settings page
@@ -40,7 +43,9 @@ Once installed, just ask. No agent names to remember — say what you want built
 
 `using-mugiwara` (the front door) routes your request, Luffy classifies it, and
 the wave pipeline runs. Because the crew runs **inline** in your main
-conversation, you watch every wave as it happens:
+conversation, you watch every wave as it happens — as compact **checkpoint
+reports** (a wave banner, one report per crew member at each stage boundary,
+and a pause when something fails):
 
 ```
   Wave 0  Luffy   triage → route: plan (requirements mostly clear)
@@ -51,6 +56,11 @@ conversation, you watch every wave as it happens:
   Wave 9  Luffy   closure→ report appended to plan, intermediate files cleaned
 ```
 
+Prefer 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/`:
+`/mugiwara-plan`, `/mugiwara-execute`, `/mugiwara-review`, `/mugiwara-security`,
+`/mugiwara-heal`, `/mugiwara-ship`. You can jump into any stage.
+
 ## 3. What you do during a mission
 
 Almost nothing, in the default mode:
@@ -58,8 +68,9 @@ Almost nothing, in the default mode:
 - Answer Nami's clarifying questions (one batched round before planning).
 - Give the plan an explicit GO when presented (or switch to `semi`/`auto`).
 - Review Brook's rollback note if a risky fix is proposed.
-- Open the PR at the end — the crew pushes the branch and hands you the verdict
-  file; the crew never merges or deploys.
+- In every mode, open the PR at the end — the crew pushes the branch and hands
+  you the verdict file with a ready PR summary block. The crew never merges,
+  deploys, or creates a PR itself.
 
 ## 4. The `.mugiwara/` workspace
 
@@ -81,4 +92,5 @@ Every mission writes to `.mugiwara/` at the repo root:
 - Learn the [execution model](execution-model.md) — why everything is visible.
 - Set your [mode](modes.md) — `guided` asks at every gate, `semi`/`auto`
   self-answer.
+- Read the [config reference](config.md) — branch/commit/PR writing standards.
 - Meet the [crew](agents.md).

package/docs/index.md

@@ -1,8 +1,14 @@
 # Mugiwara Docs
 
 The Straw Hat crew of AI agents and skills. These docs cover what the crew is,
-how to adopt it, and how each harness installs it. The crew is pure markdown —
-no runtime, no daemons, nothing to host.
+how to adopt it, and how each harness installs it. The crew is markdown plus a
+small Node CLI (`mugiwara`) — no daemons, nothing to host. It ships **15
+agents** and **32 skills**, and the workflow **auto-activates** at session
+start — a non-trivial request runs the pipeline by itself, with
+`/using-mugiwara` as an optional explicit router. Work is **sized to a lane**
+before it runs: small fixes skip the pipeline, sensitive changes run the full
+nine waves, and every wave passes only on **evidence**, never on a spoken
+claim.
 
 ## Start here
 
@@ -11,10 +17,14 @@ no runtime, no daemons, nothing to host.
 | [Getting started](getting-started.md) | Install, first mission, what you see in the chat |
 | [Adoption guide](adoption-guide.md) | Pick the harness, pick the mode, fit the crew to your workflow |
 | [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 techniques](skills.md) | All 25 skills and what each enforces |
+| [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 |
+| [Lanes & sizing](lanes.md) | How Luffy sizes work at triage: Lane 0–4, escalation, budget |
+| [Enforcement](enforcement.md) | Skip gates, evidence over claims, and capability tiers |
 | [Git discipline](git-strategy.md) | Commits, branches, save-points — and why the executor commits |
 
 ## Install by harness
@@ -36,6 +46,7 @@ no runtime, no daemons, nothing to host.
 |-----|----------------|
 | [Skill anatomy](skill-anatomy.md) | How a mugiwara skill file is structured |
 | [Agent anatomy](agent-anatomy.md) | How a mugiwara agent file is structured |
+| [Troubleshooting](troubleshooting.md) | Common problems and how to fix them |
 | [Developer onboarding](developer-onboarding.md) | Repo layout, validation, tests, contributing |
 
 ## Resources

package/docs/lanes.md

@@ -0,0 +1,40 @@
+# Lanes & Sizing
+
+The crew sizes a mission before it runs. At Wave 0, Luffy sizes the request
+and picks a lane. The lane decides how many waves run — so a one-file typo does
+not pay for the full nine-wave pipeline.
+
+## The lanes
+
+| Lane | Picks when | Waves | Budget |
+|------|-----------|-------|--------|
+| **0 · Direct** | typo, rename, 1 file <20 LOC | none | ~0 |
+| **1 · Lean** | bug in 1-2 files, <50 LOC | execute → quality | ~4k |
+| **2 · Standard** | feature, 3-8 files | plan → execute → checkpoint → review | ~10k |
+| **3 · Full** | architecture, migration, auth/payment, API | 9 waves | ~20k |
+| **4 · Spike** | exploratory, needs direction | brainstorm → re-triage | ~3k |
+
+Budget is a guidance, not a meter: at ~1.5× estimated tokens warn, at 3× stop,
+write the state to `.mugiwara/` and report how to continue — never silently
+run on.
+
+## How Luffy sizes
+
+Size from the diff:
+
+- 1 file <20 LOC → Lane 0 (Direct).
+- 1-2 files → Lane 1 (Lean).
+- 3-8 files → Lane 2 (Standard).
+- 9+ files, or the diff touches `auth/`, `payment/`, `migrations/`, or
+  `security/` → Lane 3 (Full).
+- Exploratory, needs direction → Lane 4 (Spike).
+
+## Escalation
+
+The lane **escalates when the work outgrows the estimate** — the diff grew, a
+sensitive path got touched mid-mission, or failures repeat. Escalation is
+automatic; a lane **never auto-drops**. Under-process is more expensive than
+over-process.
+
+The lane is decided by Luffy at triage, per mission — it is not stored in
+`.mugiwara/config`.