@ionivetech/mugiwara 0.3.0 → 0.4.0

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

@@ -5,6 +5,11 @@ description: Use when authoring a new mugiwara skill or revising an existing one
 
 # Writing Mugiwara Skills
 
+## Skip when
+
+- Not authoring or revising a mugiwara skill — plain application code change.
+- Skill change is a one-line description fix with no anatomy impact.
+
 A skill is a process workflow the agent runs on cue, not a reference guide. If it reads like a wiki page, it fails. The description decides when the skill loads; the body decides what happens next. Both must justify their size.
 
 ## Skill anatomy

package/dist/mugiwara.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync, rmSync as rmSync2 } from "node:fs";
+import { existsSync as existsSync6, realpathSync, rmSync as rmSync3 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join7, resolve } from "node:path";
+import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // src/args.ts
@@ -14,6 +14,7 @@ var BOOL_FLAGS = {
   "-y": "yes",
   "--force": "force",
   "--dry-run": "dryRun",
+  "--keep-logs": "keepLogs",
   "--help": "help",
   "-h": "help",
   "--version": "version",
@@ -131,6 +132,10 @@ var target = {
       fm.tools = data.tools;
     return { relPath: `${data.name}.md`, text: stringifyFrontmatter(fm, body) };
   },
+  refsDir({ scope, projectDir, home }, skillName) {
+    const root = scope === "global" ? join(home, ".claude") : join(projectDir, ".claude");
+    return join(root, "skills", skillName, "references");
+  },
   postInstall({ scope, projectDir, home, dryRun }) {
     const root = scope === "global" ? join(home, ".claude") : join(projectDir, ".claude");
     const hookFile = join(root, "hooks", "session-start.ts");
@@ -166,6 +171,10 @@ var target2 = {
     if (data.tools)
       fm.tools = data.tools;
     return { relPath: `${data.name}.md`, text: stringifyFrontmatter(fm, body) };
+  },
+  refsDir({ scope, projectDir, home }, skillName) {
+    const root = scope === "global" ? join2(home, ".config", "opencode") : join2(projectDir, ".opencode");
+    return join2(root, "skills", skillName, "references");
   }
 };
 
@@ -190,6 +199,9 @@ var target3 = {
       relPath: `${data.name}.md`,
       text: stringifyFrontmatter({ name: data.name, description: data.description }, body)
     };
+  },
+  refsDir(_opts, skillName) {
+    return join3(_opts.projectDir, ".mugiwara", "refs", skillName);
   }
 };
 
@@ -197,11 +209,13 @@ var target3 = {
 import { existsSync as existsSync2, writeFileSync } from "node:fs";
 import { join as join4 } from "node:path";
 function makeGeneric(opts) {
-  const { id, label, rulesDir, bootstrapFile, bootstrapPointer } = opts;
+  const { id, label, rulesDir, bootstrapFile, bootstrapPointer, tier = bootstrapPointer ? 2 : 3 } = opts;
+  const stubOnly = tier === 3;
   return {
     id,
     label,
     native: false,
+    tier,
     paths({ scope, projectDir }) {
       if (scope === "global")
         throw new Error(`${label} supports project scope only`);
@@ -209,6 +223,27 @@ function makeGeneric(opts) {
       return { skillsDir: dir, agentsDir: dir };
     },
     transformSkill(data, body) {
+      if (stubOnly) {
+        return {
+          relPath: `${data.name}.md`,
+          text: `# ${data.name}
+
+> ${data.description}
+
+## Skip when
+
+Full skill: \`${data.name}\` — read \`.mugiwara/refs/${data.name}.md\` when the crew invokes this role.`
+        };
+      }
+      return { relPath: `${data.name}.md`, text: `# ${data.name}
+
+> ${data.description}
+
+${body}` };
+    },
+    transformSkillFull(data, body) {
+      if (!stubOnly)
+        return null;
       return { relPath: `${data.name}.md`, text: `# ${data.name}
 
 > ${data.description}
@@ -216,6 +251,16 @@ function makeGeneric(opts) {
 ${body}` };
     },
     transformAgent(data, body) {
+      if (stubOnly) {
+        return {
+          relPath: `agent-${data.name}.md`,
+          text: `# Agent: ${data.name}
+
+> ${data.description}
+
+Skills: ${data.skills ?? ""}. Read \`.mugiwara/refs/${data.name}.md\` when embodying this role.`
+        };
+      }
       return { relPath: `agent-${data.name}.md`, text: `# Agent: ${data.name}
 
 > ${data.description}
@@ -224,6 +269,20 @@ Skills used: ${data.skills ?? ""}
 
 ${body}` };
     },
+    transformAgentFull(data, body) {
+      if (!stubOnly)
+        return null;
+      return { relPath: `${data.name}.md`, text: `# Agent: ${data.name}
+
+> ${data.description}
+
+Skills used: ${data.skills ?? ""}
+
+${body}` };
+    },
+    refsDir({ projectDir }) {
+      return join4(projectDir, ".mugiwara", "refs");
+    },
     postInstall({ projectDir, dryRun }) {
       if (!bootstrapFile)
         return { written: [], notes: [] };
@@ -289,7 +348,8 @@ var target8 = makeGeneric({
   "instructions": [
     ".kilo/rules/*.md"
   ]
-}`
+}`,
+  tier: 3
 });
 
 // src/targets/antigravity.ts
@@ -316,14 +376,20 @@ function collectContent() {
   const skillNames = readdirSync(join5(CONTENT_DIR, "skills"), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
   const skills = skillNames.map((name) => {
     const { data, body } = parseFrontmatter(readFileSync2(join5(CONTENT_DIR, "skills", name, "SKILL.md"), "utf8"));
-    return { name, data, body };
+    return { name, data, body, refs: collectRefs(join5(CONTENT_DIR, "skills", name)) };
   });
   const agents = readdirSync(join5(CONTENT_DIR, "agents")).filter((f) => f.endsWith(".md")).map((f) => {
     const { data, body } = parseFrontmatter(readFileSync2(join5(CONTENT_DIR, "agents", f), "utf8"));
-    return { name: f.replace(/\.md$/, ""), data, body };
+    return { name: f.replace(/\.md$/, ""), data, body, refs: [] };
   });
   return { skills, agents };
 }
+function collectRefs(skillDir) {
+  const refsDir = join5(skillDir, "references");
+  if (!existsSync3(refsDir))
+    return [];
+  return readdirSync(refsDir, { recursive: true }).map((f) => String(f)).filter((f) => f.endsWith(".md")).map((rel) => ({ relPath: rel, text: readFileSync2(join5(refsDir, rel), "utf8") }));
+}
 function installTo(target10, opts) {
   const { scope, projectDir, dryRun = false, force = false } = opts;
   const home = opts.home ?? homedir();
@@ -360,11 +426,26 @@ function installTo(target10, opts) {
     const out = target10.transformSkill(s.data, s.body);
     if (out)
       writeOne(join5(dirs.skillsDir, out.relPath), out.text);
+    if (target10.transformSkillFull) {
+      const full = target10.transformSkillFull(s.data, s.body);
+      if (full && target10.refsDir)
+        writeOne(join5(target10.refsDir({ scope, projectDir, home }, s.name), full.relPath), full.text);
+    }
+    if (s.refs.length && target10.refsDir) {
+      const refsRoot = target10.refsDir({ scope, projectDir, home }, s.name);
+      for (const r of s.refs)
+        writeOne(join5(refsRoot, r.relPath), r.text);
+    }
   }
   for (const a of agents) {
     const out = target10.transformAgent(a.data, a.body);
     if (out)
       writeOne(join5(dirs.agentsDir, out.relPath), out.text);
+    if (target10.transformAgentFull) {
+      const full = target10.transformAgentFull(a.data, a.body);
+      if (full && target10.refsDir)
+        writeOne(join5(target10.refsDir({ scope, projectDir, home }, a.name), full.relPath), full.text);
+    }
   }
   if (target10.postInstall) {
     const post = target10.postInstall({ scope, projectDir, home, dryRun, files: result.written });
@@ -412,6 +493,38 @@ function writeManifest(file, data) {
 `);
 }
 
+// src/mission.ts
+import { existsSync as existsSync5, rmSync as rmSync2 } from "node:fs";
+import { join as join7 } from "node:path";
+function resetMission(projectDir, keepLogs) {
+  const root = join7(projectDir, ".mugiwara");
+  if (!existsSync5(root))
+    return { removed: [], kept: [] };
+  const removed = [];
+  const kept = [];
+  for (const dir of ["spec", "plans", "results", "review", "issues"]) {
+    const p = join7(root, dir);
+    if (existsSync5(p)) {
+      rmSync2(p, { recursive: true, force: true });
+      removed.push(dir);
+    }
+  }
+  if (!keepLogs) {
+    const p = join7(root, "logs");
+    if (existsSync5(p)) {
+      rmSync2(p, { recursive: true, force: true });
+      removed.push("logs");
+    }
+  } else if (existsSync5(join7(root, "logs"))) {
+    kept.push("logs");
+  }
+  for (const f of ["config", "manifest.json", "backup"]) {
+    if (existsSync5(join7(root, f)))
+      kept.push(f);
+  }
+  return { removed, kept };
+}
+
 // src/cli.ts
 var str = (v) => typeof v === "string" ? v : undefined;
 var flag = (v) => v === true;
@@ -432,12 +545,22 @@ async function run(argv) {
       return uninstall(flags);
     case "list":
       return list(flags);
-    case "skills":
-      return skills();
+    case "reset":
+      return resetCmd(flags);
     default:
       throw new Error(`Unknown command: ${command}`);
   }
 }
+function resetCmd(flags) {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const { removed, kept } = resetMission(projectDir, flag(flags.keepLogs));
+  if (removed.length)
+    console.log(`removed: ${removed.join(", ")}`);
+  else
+    console.log("nothing to remove.");
+  if (kept.length)
+    console.log(`kept: ${kept.join(", ")}`);
+}
 async function resolveOptions(flags) {
   const interactive = !flag(flags.yes);
   const rl = interactive ? createRl() : null;
@@ -449,7 +572,7 @@ async function resolveOptions(flags) {
       scope = await choose(rl, "Install scope?", ["global (user-wide)", "project (this repo)"]) === 0 ? "global" : "project";
     }
     const projectDir = resolve(str(flags.project) ?? process.cwd());
-    if (scope === "project" && !existsSync5(projectDir))
+    if (scope === "project" && !existsSync6(projectDir))
       throw new Error(`Project dir not found: ${projectDir}`);
     let targetIds = str(flags.target)?.split(",").map((s) => s.trim()) ?? null;
     if (targetIds && targetIds.includes("all"))
@@ -533,7 +656,7 @@ async function uninstall(flags) {
   }
   const removed = removeInstalled(manifest, { dryRun: flag(flags.dryRun) });
   if (!flag(flags.dryRun))
-    rmSync2(file);
+    rmSync3(file);
   console.log(`OK removed ${removed.length} files`);
 }
 function list(flags) {
@@ -553,22 +676,6 @@ function list(flags) {
   if (!found)
     console.log("No mugiwara installation found.");
 }
-function skills() {
-  const dir = join7(CONTENT_DIR, "skills");
-  const names = readdirSync2(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
-  const rows = names.map((name) => {
-    const { data } = parseFrontmatter(readFileSync4(join7(dir, name, "SKILL.md"), "utf8"));
-    return [name, data.description ?? ""];
-  });
-  const w = Math.max(...rows.map((r) => r[0].length)) + 2;
-  console.log(`mugiwara ${VERSION} — ${rows.length} skills (agentskills.io format):
-`);
-  for (const [name, description] of rows)
-    console.log(`  ${name.padEnd(w)}${description}`);
-  console.log(`
-Install skills into any agent via skills.sh:
-  npx skills add ionivetech/mugiwara`);
-}
 function help() {
   console.log(`mugiwara ${VERSION} — the Straw Hat crew for AI agents
 
@@ -577,7 +684,7 @@ Usage:
   mugiwara update        replace existing files (backs up differences first)
   mugiwara uninstall     remove installed files via manifest
   mugiwara list          show installations
-  mugiwara skills        list installable skills (agentskills.io)
+  mugiwara reset         wipe mission state (spec/plans/results/review/issues[/logs])
   mugiwara --help        this help
   mugiwara --version     print version
 
@@ -587,7 +694,8 @@ Flags:
   --target <ids|all>     comma-separated: ${TARGET_IDS.join(", ")}
   --yes, -y              non-interactive (needs --global/--project, --target)
   --force                overwrite differing files (with backup)
-  --dry-run              print actions without writing`);
+  --dry-run              print actions without writing
+  --keep-logs            with reset: keep .mugiwara/logs (lessons ledger survives)`);
 }
 var entry = process.argv[1] !== undefined ? resolve(process.argv[1]) : undefined;
 if (entry !== undefined) {

package/docs/adoption-guide.md

@@ -43,8 +43,8 @@ mid-wave.
 
 ## Fit the crew to your workflow
 
-- **Trivial one-liners** don't need the crew — Luffy routes them straight to
-  execution.
+- **Trivial one-liners** don't need the crew's full pipeline — Luffy routes them
+  to Lane 0 and they run with zero waves. The process scales to the work.
 - **Medium features** run the standard pipeline: triage → plan → execute →
   checkpoint → quality → gates → review → closure.
 - **High-stakes work** (money, security, data, public API) always gets the full

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

@@ -29,6 +29,9 @@ base=main
 | `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.

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                # 32 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.