@ionivetech/mugiwara 0.4.0 → 0.5.0

package/docs/getting-started.md

@@ -20,9 +20,19 @@ Pick your harness — every major one is supported. The two easiest:
 /plugin install mugiwara
 ```
 
-Everything else (Copilot, Gemini, Codex, Cursor, Windsurf, Cline, Kilo,
-Antigravity, pi) has a one-command install. See the [install guides](index.md#install-by-harness)
-or the CLI:
+| Harness | Install command |
+|---------|----------------|
+| Claude Code | `/plugin marketplace add ionivetech/mugiwara` then `/plugin install mugiwara` |
+| opencode | `{ "plugin": ["@ionivetech/mugiwara"] }` in `opencode.json` |
+| GitHub Copilot | `copilot plugin marketplace add ionivetech/mugiwara` then `copilot plugin install mugiwara` |
+| Gemini CLI | `gemini extensions install https://github.com/ionivetech/mugiwara` |
+| Codex | `codex plugin marketplace add ionivetech/mugiwara` then `codex plugin add mugiwara@mugiwara` |
+| Cursor | `/add-plugin mugiwara` |
+| Kimi Code | `/plugins install https://github.com/ionivetech/mugiwara` |
+| pi | `pi install git:github.com/ionivetech/mugiwara` |
+| Windsurf, Cline, Kilo, Antigravity | `npx @ionivetech/mugiwara@latest --project . --target <id> --yes` |
+
+Or the CLI for any target:
 
 ```bash
 npx @ionivetech/mugiwara@latest --project ./my-app --target all --yes
@@ -32,45 +42,76 @@ Requires **Node.js >= 20.11**. Bun is optional (build-from-source only).
 
 ## 2. Start a mission
 
-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:
+The workflow **auto-activates** at session start. The crew announces itself,
+then give any non-trivial request.
+
+### Small: lane 0–1
+
+```
+> fix the date formatting bug in src/utils/format.ts
+```
+
+Luffy routes it to **Lane 1** (Lean). Zoro reproduces and fixes, Sanji runs
+format + lint + tests. Two waves, visible as compact checkpoint reports. No
+nine-wave ceremony for a one-file bug.
+
+That's lane sizing: the process scales to the work. A typo (Lane 0) runs zero
+waves — the fix happens directly.
+
+### Medium: lane 2
+
+```
+> add a search bar to the products page
+```
+
+Touches frontend + API. Luffy routes to **Lane 2** (Standard). Nami plans 1
+wave with 3-5 tasks, Zoro executes test-first, Chopper audits every criterion,
+Sanji and Franky gate, Robin and Jinbe review.
+
+### Large: lane 3
 
 ```
-> add dark mode to the settings page
+> add role-based access control to the API
 ```
 
-`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 — as compact **checkpoint
-reports** (a wave banner, one report per crew member at each stage boundary,
-and a pause when something fails):
+Touches auth — Luffy routes to **Lane 3** (Full). All 9 waves run. Nami plans
+the migration, Zoro executes, Chopper audits, Sanji tests, Franky gates, Robin
+reviews the diff with a breaking-change map, Jinbe runs STRIDE + OWASP, Brook
+heals any failures (max 3 cycles), Luffy closes with a mission report + push +
+ready PR summary.
 
 ```
-  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
+  Wave 0  Luffy   triage → route: full pipe (auth/ touched)
+  Wave 2  Nami    plan   → .mugiwara/plans/2026-08-10-rbac.md (2 waves, 5 tasks)
+  Wave 3  Zoro    execute→ 5 tasks, evidence per task
+  Wave 4  Chopper audit  → PASS: all criteria met, commit hygiene clean
+  Wave 5  Sanji   quality → PASS: lint 0, 312 tests green
+  Wave 6  Franky  gates  → PASS: new 94%, modified 87%, build green
+  Wave 7  Robin   review → 2 minor findings (batched)
+  Wave 7  Jinbe   security→ PASS: STRIDE clean, 0 high
+  Wave 9  Luffy   closure→ mission report + push + ready PR summary
 ```
 
-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.
+The crew runs **inline** in your main conversation — every wave reports as a
+compact checkpoint. Subagents only for parallel task batches.
+
+Prefer to drive stages yourself? Every stage has a slash command:
+`/mugiwara-plan`, `/mugiwara-execute`, `/mugiwara-review`,
+`/mugiwara-security`, `/mugiwara-heal`, `/mugiwara-ship`. Jump into any stage.
 
 ## 3. What you do during a mission
 
-Almost nothing, in the default mode:
+Almost nothing in `guided` mode:
 
 - Answer Nami's clarifying questions (one batched round before planning).
-- Give the plan an explicit GO when presented (or switch to `semi`/`auto`).
+- Give the plan an explicit GO when presented.
 - Review Brook's rollback note if a risky fix is proposed.
-- 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.
+- In every mode, **open the PR at the end** — the crew pushes the branch and
+  hands you a verdict file with a ready PR summary. The crew never creates a
+  PR, merges, or deploys.
+
+Switch to `semi` or `auto` if you want the crew to self-manage branch, commits,
+and ambiguities. See [modes](modes.md).
 
 ## 4. The `.mugiwara/` workspace
 
@@ -78,19 +119,40 @@ Every mission writes to `.mugiwara/` at the repo root:
 
 ```
 .mugiwara/
-├── config         # mode/branch/commit settings (gitignored)
-├── spec/          # brainstorm output
-├── plans/         # the clean execution plan (source of truth from Wave 2)
-├── results/       # audit, quality, gate, closure reports
-├── review/        # review + security findings
-├── issues/        # blocker ledger
-└── logs/          # decision + check-in log (deleted at cleanup)
+├── config          # mode, branch, commit, base, coverage thresholds
+├── state.json      # computed at every wave boundary by scripts/savepoint.sh
+├── spec/           # brainstorm output
+├── plans/          # clean execution plan (source of truth from Wave 2)
+├── results/        # audit, quality, gate, closure reports + evidence logs
+├── reports/        # human-readable mission reports
+├── review/         # review + security findings
+├── issues/         # blocker ledger
+├── refs/           # full skill/agent bodies for glob-loading harnesses
+└── logs/           # decision log + cross-mission lessons
 ```
 
-## 5. Next steps
+**Savepoint** runs at every wave boundary — `state.json` carries lane, wave,
+files, blockers, heal cycle, and token budget. Resume reads one file instead of
+six. See [audit-trail.md](audit-trail.md) for the full artifact map.
+
+## 5. Configuration
+
+`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global):
+
+| Key | Default | What it controls |
+|-----|---------|-----------------|
+| `mode` | guided | Autonomy: guided/semi/auto |
+| `branch` | `feature/{type}-{issue}-{slug}` | Branch naming pattern |
+| `commit` | conventional | Commit style: conventional/gitmoji/plain |
+| `base` | main | PR target branch |
+| `coverage_new` | 90 | Coverage % for new files |
+| `coverage_modified` | 80 | Coverage % for modified files |
+
+## 6. Next steps
 
-- 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).
+- Meet the [crew](agents.md) — 15 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.
+- Read the [audit trail](audit-trail.md) — every artifact and how to review it.
+- See the [compliance matrix](compliance-matrix.md) — rule compliance per model.

package/docs/harness-matrix.md

@@ -0,0 +1,41 @@
+# Harness Matrix
+
+What actually differs per harness tier. Every skill and agent file ships to every harness, but behavior differs in three tiers.
+
+| Tier | Harnesses | Skills | Agents | `references/` | Scope |
+|------|-----------|--------|--------|:---:|-------|
+| **1** | Claude Code, opencode | Native, auto-trigger per skill | Real, dispatchable | Yes | global + project |
+| **2** | Gemini, Codex, Copilot | Full body in rules dir + bootstrap pointer | Markdown only | Yes | project only |
+| **3** | Windsurf, Cline, Kilo, Antigravity | Stub; body in `.mugiwara/refs/` | Stub | Yes | project only |
+
+## Behavioral differences
+
+### Tier 1 — Full
+
+- Skills auto-trigger when `description` frontmatter matches the task.
+- Agents are dispatchable subagents with isolation.
+- Progressive disclosure works: description → body → `references/`.
+- Global scope supported — install once, use in every project.
+
+### Tier 2 — Skills only
+
+- Agent files are markdown — the main thread embodies the persona, no subagent dispatch.
+- Skills load as rules files; the model chooses which to read per task.
+- **Project scope only** — `generic.ts` throws on global scope.
+- `references/` files are copied to `.mugiwara/refs/` and reachable.
+
+### Tier 3 — Stubs
+
+- Rule directories get **stub files** — the frontmatter and a pointer to `.mugiwara/refs/`.
+- Full body is loaded only when the agent opens the reference file.
+- Saves ~40k tokens of glob-load. Trade: the model must decide to open the ref.
+- **Project scope only.**
+- `references/` files are copied to `.mugiwara/refs/` — depth is available, just not auto-loaded.
+- Wave-boundary state flush: savepoint writes `state.json` so the model has computed state to resume from.
+
+## What's the same everywhere
+
+- All 32 (→ 26) skill directories ship to every harness.
+- All 15 agent markdown files ship to every harness.
+- `references/` files are always copied.
+- The workflow, lane sizing, and evidence discipline are identical — the difference is in how the model loads them.

package/docs/lanes.md

@@ -1,40 +1,82 @@
 # 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 crew sizes a mission before it runs. Lane is computed from the diff by
+`scripts/lane.sh` — deterministic, not estimated.
 
 ## The lanes
 
-| Lane | Picks when | Waves | Budget |
-|------|-----------|-------|--------|
+| Lane | Picks when | Waves | Token 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 |
+| **2 · Standard** | feature, 3-8 files | plan → execute → audit → review | ~10k |
+| **3 · Full** | architecture, migration, 9+ files, or auth/payment/API touched | all 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 lane is computed
 
-## How Luffy sizes
+`scripts/lane.sh <base-ref>` runs `git diff --name-only` against the base ref
+and applies deterministic rules:
 
-Size from the diff:
+| Diff | Lane |
+|------|------|
+| 0 files changed | Direct |
+| 1 file, <20 LOC added | Direct |
+| 1 file, ≥20 LOC added | Lean |
+| 2 files | Lean |
+| 3–8 files | Standard |
+| 9+ files | Full |
 
-- 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).
+**Sensitive path escalation.** Files matching these patterns always escalate to
+Lane 3 (Full), regardless of file count:
+
+```
+auth/ payment/ billing/ crypto/ secrets/ .env
+migration/ .sql schema. .prisma .terraform .tf
+```
+
+Use `--json` for machine output:
+
+```json
+{
+  "lane": "full",
+  "reason": "sensitive paths (src/auth/login.ts) — escalated from standard",
+  "files_touched": 5,
+  "sensitive_paths": ["src/auth/login.ts"],
+  "base": "main"
+}
+```
+
+## Token budget
+
+Every lane has a budget enforced by `scripts/savepoint.sh` at each wave
+boundary. The harness sets `MUGIWARA_TOKENS` env var with estimated tokens
+consumed.
+
+| Status | Condition | Action |
+|--------|-----------|--------|
+| ok | tokens < 1.5× budget | Continue |
+| warn | tokens ≥ 1.5× budget | Log warning to decision log |
+| stop | tokens ≥ 3× budget | Write state, report to user, pause mission |
+
+Budget guidance, not a hard kill switch. The model decides whether to stop —
+savepoint just writes the status to `state.json`.
 
 ## 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.
+Lane **escalates when work outgrows the estimate.** At every wave boundary,
+`scripts/savepoint.sh` re-checks the diff. If files grew or a sensitive path
+appeared, lane rises. A lane **never auto-drops.** Under-process costs more
+than over-process.
+
+Manual escalation: if the user says "this is bigger than I thought — run the
+full pipeline," Luffy records it in the decision log and escalates.
+
+## SPIKE lane (Lane 4)
+
+Exploratory missions start at Lane 4. Usopp brainstorms, then the mission is
+re-triaged into the right lane. A spike that stays a spike (no code change
+decided) ends at Wave 1.
 
-The lane is decided by Luffy at triage, per mission — it is not stored in
+Lane is computed per mission by `scripts/lane.sh`, not stored in
 `.mugiwara/config`.

package/docs/skill-anatomy.md

@@ -1,23 +1,20 @@
 # Skill Anatomy
 
-Every mugiwara skill is a single portable `SKILL.md` file. No code, no runtime —
-just frontmatter plus a playbook the agent follows. This is the format skills
-ship in for Claude Code, opencode, Copilot, Cursor, Gemini, and 70+ other tools
-via the agentskills.io layout.
+Every mugiwara skill is a single `SKILL.md` file. No code, no runtime — just
+frontmatter plus a playbook the agent follows.
 
 ## File structure
 
 ```
 skills/<skill-name>/SKILL.md
-skills/<skill-name>/references/<topic>.md   # optional: overflow detail, linked from the body
+skills/<skill-name>/references/<topic>.md   # optional: overflow detail
 ```
 
 ```markdown
 ---
 name: mugiwara-checkpoint
-description: Use after an execution wave to audit results against the plan. Runs every acceptance criterion as a command or file inspect, verifies commit hygiene and parallel-file safety, classifies failures honestly, appends ledger rows, and issues a Definition-of-Done verdict. Auditor only - never fixes code.
+description: Use after an execution wave to audit results against the plan.
 ---
-
 # Checkpoint (Chopper)
 
 <playbook body>
@@ -27,57 +24,48 @@ description: Use after an execution wave to audit results against the plan. Runs
 
 | Field | Required | Notes |
 |-------|----------|-------|
-| `name` | yes | lowercase, hyphen-separated, matches the folder name, ≤64 chars |
-| `description` | yes | 20–500 chars; what it does AND when to trigger. Front-load the trigger keywords. Skills without a description are filtered out. |
-| `license`, `compatibility`, `metadata` | no | optional extras |
-
-## The playbook body
-
-The body is the actual behavior. Well-formed mugiwara skills follow a house
-style:
-
-1. **Title + one-line identity** — `# Checkpoint (Chopper)`, then what the role
-   is and is not.
-2. **Skip when** — required. ≤4 bullets, numeric threshold, telling the agent
-   when this skill does not apply (e.g. "no UI code touched", "<3 files").
-   Without it the content validator fails the build. A skipped skill is
-   recorded in the decision log, never silent.
-3. **The protocol** — numbered steps, exact commands, exact file paths.
-4. **Decision tables** — where a judgment is needed, a table of signal → action.
-5. **The iron law** — one memorable line that states the non-negotiable
-   ("TRUST NOTHING; VERIFY EVERYTHING").
-6. **Common rationalizations** — the excuses to reject, and the correct reply.
-7. **Red flags** — conditions that mean "stop, this isn't done," each ending
-   with what to do.
-
-### Style rules that keep skills effective
-
-- **Evidence over claims.** A skill says what to run, never what to assume.
-- **Concrete, never aspirational.** Exact paths, exact commands; "works
-  correctly" is banned as an acceptance criterion.
-- **Boundaries are explicit.** Auditor skills say "never edit code"; executor
-  skills say "never report done without command output."
-- **≤120 lines.** Skills that grow past that get split, not stretched.
-- **Progressive disclosure.** Keep the trigger-scannable description and the
-  decision tree in the body; when a section exceeds roughly 15–20 lines, move
-  the detail to a `references/<topic>.md` file and drop a one-line pointer in
-  the body saying what to read and why.
-
-## How skills reference each other
-
-Skills cross-reference by name: an agent's frontmatter lists its held skills
-(`skills: mugiwara-checkpoint`), and skills defer to each other (e.g.
-`mugiwara-quality` defers to `mugiwara-mode` for the consent contract). Content
-is the single source of truth; harnesses copy it verbatim.
+| `name` | yes | lowercase, hyphen-separated, matches folder name, ≤64 chars |
+| `description` | yes | 20–500 chars; trigger conditions + disambiguators only. Front-load trigger keywords. |
+| `license`/`compatibility`/`metadata` | no | optional |
+
+## Playbook body
+
+1. **Title + one-line identity** — role name and what it does/doesn't do.
+2. **Skip when** — required. ≤4 bullets, numeric threshold. Validator fails
+   build without it.
+3. **Protocol** — numbered steps, exact commands, exact file paths.
+4. **Decision tables** — signal → action.
+5. **Iron law** — one memorable non-negotiable line.
+6. **Common rationalizations** — excuses + correct reply.
+7. **Red flags** — stop conditions + what to do.
+
+## Style rules
+
+- **Evidence over claims.** Say what to run, never what to assume.
+- **Concrete, never aspirational.** Exact paths, exact commands.
+- **≤120 lines.** Grow beyond → split or move to `references/`.
+- **Progressive disclosure.** Sections >15–20 lines move to
+  `references/<topic>.md`; body gets a one-line pointer saying what to read
+  and why.
+- **220-char description ceiling.** Descriptions carry trigger vocabulary, not
+  procedure. Procedure belongs in the body.
+
+## Three-layer discipline
+
+| Stays in body | Moves to references |
+|---------------|---------------------|
+| Skip when, red flags, rationalizations | Worked examples |
+| "Never do X" rules | Long checklists |
+| Step order, decision trees | Reference tables, edge cases, templates |
+
+Test: body = what changes behavior on every run. References = what you open
+after deciding to do the work.
 
 ## Validation
 
-Every skill is validated on check-in: name matches folder, description 20–500
-chars, body ≤120 lines, no duplicate names, and a `## Skip when` block with
-1–4 bullets. Run:
-
 ```bash
 bun run validate
 ```
 
-See [developer-onboarding.md](developer-onboarding.md).
+Checks: name matches folder, description 20–500 chars, body ≤120 lines, no
+duplicate names, `## Skip when` block with 1–4 bullets.

package/docs/skills.md

@@ -1,73 +1,55 @@
-# The Techniques — 32 Skills
+# The Techniques — 26 Skills
 
 Each skill is a portable markdown playbook — the "how to" the crew follows when
-it embodies a role. Skills are the actual content; agents are the personas.
+it embodies a role.
 
 ## Core pipeline
 
-| Skill | Enforces |
-|-------|----------|
-| `mugiwara-workflow` | The harness entry point: inline execution model, gateway triage, wave pipeline, workspace layout, blocker protocol, cleanup |
-| `mugiwara-orchestration` | Luffy's captain behavior: 5-way classifier, check-ins, work splitting, decision log, closure |
-| `mugiwara-brainstorm` | Usopp's critical sparring: interrogate, research facts, cut over-engineering, recommend |
-| `mugiwara-planning` | Interview-first, full-context scan, wave plans with parallel/sequential markers + anti-patterns |
-| `mugiwara-execution` | Todo list, sequential tasks inline + parallel worker batches, 6-field delegation for parallel work, one commit per logical task |
-| `mugiwara-checkpoint` | Verify-everything audit — deduped and scoped to the wave's diff; failure rows to the blocker ledger |
-| `mugiwara-quality` | Discover the project's real tooling; formatter, linter, unit tests under the consent matrix |
-| `mugiwara-gates` | Coverage ≥90% new / ≥80% modified, build validation, Definition of Done |
-| `mugiwara-review` | Doubt-driven review: breaking-change analysis, five-axis, severity-tagged findings |
-| `mugiwara-security` | STRIDE-first security review, OWASP Top 10 mapping, authn/authz, secrets, dependency audit, untrusted-data doctrine |
+| Skill | Teaches |
+|-------|---------|
+| `mugiwara-workflow` | Harness entry: inline execution, gateway triage, wave pipeline, workspace, blocker protocol, cleanup |
+| `mugiwara-orchestration` | Captain: 5-way classifier, check-ins, work splitting, decision log, closure |
+| `mugiwara-brainstorm` | Critical sparring: interrogate, research facts, cut over-engineering, recommend |
+| `mugiwara-planning` | Interview-first, full-context scan, wave plans with parallel/sequential markers |
+| `mugiwara-execution` | Todo list, sequential inline + parallel worker batches, 6-field delegation, one commit per task |
+| `mugiwara-checkpoint` | Verify-everything audit — deduped re-runs scoped to wave diff; failure rows to blocker ledger |
+| `mugiwara-quality` | Discover project tooling; formatter, linter, unit tests under consent matrix |
+| `mugiwara-gates` | Coverage ≥90% new / ≥80% modified, build, Definition of Done |
+| `mugiwara-review` | Doubt-driven review: breaking-change map, five-axis, severity-tagged findings |
+| `mugiwara-security` | STRIDE-first security review, OWASP Top 10, authn/authz, secrets, untrusted-data |
 | `mugiwara-healing` | Reads the ledger, Stop-the-Line + Prove-It root-cause fixes, rollback prep |
 
 ## Mission control
 
-| Skill | Enforces |
-|-------|----------|
-| `mugiwara-mode` | Runtime levels guided / semi / auto: mode owns autonomy, config owns writing standards, consent invariants, gated auto-GO, push + ready-PR terminal |
+| Skill | Teaches |
+|-------|---------|
 | `mugiwara-git` | Atomic commits, save-points, multi-commit splitting, bisect/blame debugging |
-| `mugiwara-testcases` | User-test intake (ATDD): immutable-gold rule, declarative-AC routing, consent, failure adjudication |
-| `mugiwara-pr` | Terminal: push + verdict file with a ready PR summary block; never creates a PR, stop-at-PR invariant |
+| `mugiwara-testcases` | User-test intake: immutable-gold rule, declarative-AC routing, consent, failure adjudication |
+| `mugiwara-pr` | Terminal: push + verdict file with ready PR summary; never creates a PR |
 | `mugiwara-ship` | GO/NO-GO ship gate: pre-launch checklist, feature flags, rollback plan |
-| `mugiwara-deprecation` | Sunset & migration discipline: keep-or-retire gate, cutover playbooks, safe schema changes |
-| `mugiwara-resume` | Session resume: rebuild state from `.mugiwara/` after compaction/loss; never restart |
+| `mugiwara-sunset` | Sunset & migration: keep-or-retire gate, cutover playbooks, safe schema changes |
+| `mugiwara-resume` | Session resume: rebuild state from `.mugiwara/state.json`; never restart |
 | `mugiwara-lessons` | Cross-mission memory: actionable lessons ledger, read at triage, written at closure |
-| `mugiwara-observability` | Trace the crew: structured logs, OTel-compatible spans, session correlation, end-of-mission summary |
 
 ## Engineering practice
 
-| Skill | Enforces |
-|-------|----------|
-| `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 |
+| Skill | Teaches |
+|-------|---------|
+| `mugiwara-proof-order` | RED-GREEN-REFACTOR — proof value from WHEN the test runs, not that it exists |
+| `mugiwara-root-cause` | 4-phase: reproduce → localize → reduce → fix + guard; stop-the-line |
+| `mugiwara-contract-first` | Contract-first design, error semantics, boundary validation, backward compatibility |
+| `mugiwara-claim-audit` | Adversarial verification: CLAIM → EXTRACT → DOUBT → RECONCILE → STOP |
+| `mugiwara-context-budget` | Token/context management: feed selectively, trust-sort sources, the window is a budget |
 
-## Domain & advanced
+## Domain
 
-| Skill | Enforces |
-|-------|----------|
-| `mugiwara-frontend` | Anti-slop frontend: audit-first redesigns, design-system extraction, slop list |
-| `mugiwara-backend` | Backend/server code: repo standards first, API design, data integrity, error handling, security |
-| `mugiwara-agent-security` | Secure the agent layer: prompt injection, memory poisoning, excessive agency, secrets, sandboxing |
-| `mugiwara-dynamic-workflow` | Runtime workflow patterns: fan-out-and-synthesize, tournament, loop-until-done, classify-and-act |
-| `mugiwara-eval` | Test the harness itself: task suites, judge-agent rubric comparison, pass/fail per case |
+| Skill | Teaches |
+|-------|---------|
+| `mugiwara-frontend` | Anti-slop frontend: audit-first redesigns, design-system extraction, WCAG 2.1 AA |
+| `mugiwara-backend` | Backend/server code: repo standards first, source-backed code, data integrity |
+| `mugiwara-agent-security` | Agent layer: prompt injection, memory poisoning, excessive agency, MCP trust, sandboxing |
 
-## Anatomy of a skill
+## Anatomy
 
-Every skill is a single `SKILL.md` with frontmatter + a playbook body:
-
-```markdown
----
-name: mugiwara-checkpoint
-description: Use after an execution wave to audit results against the plan. ...
----
-
-# Checkpoint (Chopper)
-
-<playbook: protocol, rules, red flags, iron law>
-```
-
-See [skill-anatomy.md](skill-anatomy.md) for the details.
+Every skill is a `SKILL.md` with frontmatter + playbook body. See
+[skill-anatomy.md](skill-anatomy.md).

package/evals/cases/positive-refactor-existing-tests.json

@@ -1,6 +1,6 @@
 {
   "name": "positive-refactor-existing-tests",
-  "skill": "mugiwara-test-driven-development",
+  "skill": "mugiwara-testcases",
   "type": "positive",
   "task": "Refactor a function in src/util/parse.ts to reduce nesting. The existing tests already cover it fully.",
   "rubric": [

package/evals/cases/routing-bug-one-file.json

@@ -1,6 +1,6 @@
 {
   "name": "routing-bug-one-file",
-  "skill": "mugiwara-systematic-debugging",
+  "skill": "mugiwara-root-cause",
   "task": "There is a bug in src/utils/format.ts where dates render one month off. It is a single-file bug. How should the agent approach this?",
   "rubric": [
     "picks a debugging skill over a planning/brainstorm skill",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ionivetech/mugiwara",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, self-healing. Installs into Claude Code, opencode, Copilot, Gemini, Codex, Cursor, Kimi, pi, Windsurf, Cline, Kilo, Antigravity.",
   "type": "module",
   "license": "MIT",
@@ -18,11 +18,11 @@
     "src",
     "content",
     "docs",
+    "references",
     "evals",
+    "scripts",
     ".opencode",
     "hooks",
-    "scripts/install.sh",
-    "scripts/install.ps1",
     "README.md",
     "LICENSE"
   ],
@@ -39,8 +39,9 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "build": "bun build src/cli.ts --outfile dist/mugiwara.js --target node --format esm",
-    "validate": "bun scripts/validate-content.ts",
+    "validate": "bun scripts/validate-content.ts --check-manifest --check-docs",
     "evals": "bun scripts/run-evals.ts",
+    "retrieval-eval": "bun scripts/retrieval-eval.ts",
     "sync-version": "bun scripts/sync-version.ts",
     "prepack": "bun run build && bun run sync-version"
   },