@ionivetech/mugiwara 0.1.3 → 0.3.0

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

@@ -5,7 +5,24 @@ description: Use at the start of any non-trivial mission to run the Mugiwara cre
 
 # Mugiwara Workflow
 
-The Straw Hat harness: Wave 0 triage + Waves 1-9, with an optional adversarial pass at Wave 4.5. Waves are phases of the mission, not files — Nami writes them into the plan doc, Zoro executes them. The harness always runs through Luffy unless the user summons a crew member directly.
+The Straw Hat harness: Wave 0 triage + Waves 1-9, with an optional adversarial pass at Wave 4.5. Waves are phases of the mission, not files — Nami writes them into the plan doc, Zoro executes them. The main thread runs the harness and embodies each crew role inline (Execution model below); the harness always starts through Luffy unless the user summons a crew member directly.
+
+## Execution model (every harness)
+
+**Inline by default.** The main/primary agent runs the pipeline and plays each crew role itself using that member's skill. Every wave's work is performed in the main conversation so the user sees the process live — no hidden subagent jumps, no click-to-expand. The crew members are personas + skills the main thread embodies, not mandatory dispatch targets.
+
+**Visible wave transitions.** Every wave opens with a main-thread banner `## Wave N — <crew> (<skill>)` and closes with the handoff line `→ Wave N+1 — <crew>` (Wave 9: `→ closure`). No wave starts without its banner; the conversation names who runs now and who takes over next so the user always sees the chain live.
+
+**Auto-activation.** Any non-trivial request fires the harness without the user asking. Check first, before exploring or answering: if the request could benefit from the crew, start Wave 0 triage. The user does not need to invoke `using-mugiwara` explicitly — the workflow starts itself.
+
+**Checkpoint-report presentation.** The banner marks a stage boundary; no wave passes silently. At each boundary the owning crew reports inline — one compact per-crew report: what ran, the result, the evidence pointer. No narration of every tool call. Each wave closes with a short progress summary (done / in-flight / blocked + next handoff). On failure or risk, PAUSE: report the problem and get a continue / retry / escalate decision before proceeding.
+
+1. For each wave, the main thread loads the owning crew member's skill (e.g. `mugiwara-checkpoint` for Wave 4) and performs that role inline: triage, planning, execution, audit, quality, gates, review, closure — all in the main thread.
+2. Dispatch a subagent ONLY when the work is genuinely parallel or background: an independent `[PARALLEL]` task batch (Zoro's WORKER subagents, Wave 3), parallel fixes (Brook, Wave 8), or a long-running check that would stall the conversation. Subagent results return to the main thread as a report; the main thread summarizes the outcome inline with evidence pointers.
+3. Crew members NEVER dispatch another crew member. A crew role that must split work returns the split plan to the main thread, which spawns the workers.
+4. Escalation = "blocked" + ledger row returned to the main thread, which routes it to Luffy/Brook. Never a nested crew dispatch.
+
+Why: crew-inside-crew nesting hides work behind subagent expansion and bloats context. Inline roles keep every wave visible as it happens. Subagents exist to parallelize, not to hide. In any harness — Claude Code, opencode, Codex, Cursor, Gemini — subagent internals sit behind a click; the only way the user sees the process is to run it in the main conversation.
 
 ## Workspace layout
 
@@ -13,23 +30,30 @@ Every mission creates and works inside `.mugiwara/` at the repo root:
 
 ```
 .mugiwara/
+├── config         # runtime mode config: mode/branch/commit/pr key=value (gitignored; project overrides global)
 ├── spec/          # brainstorm output: YYYY-MM-DD-<mission>.md
-├── plans/         # plan doc: YYYY-MM-DD-<mission>.md — single source of truth from Wave 2
-├── results/       # wave results: audit reports, quality/gate reports, test output
+├── plans/         # plan doc: YYYY-MM-DD-<mission>.md — CLEAN, Nami-only, source of truth from Wave 2. No agent names, no log, no closure.
+├── results/       # wave results: audit/quality/gate reports, todos, closure report
 ├── review/        # review + security findings
 ├── issues/        # blocker log: YYYY-MM-DD-<mission>-blockers.md
-└── logs/          # Luffy's decision log
+└── logs/          # Luffy's decision + check-in log: YYYY-MM-DD-<mission>.md (deleted at cleanup)
 ```
 
+The plan doc stays clean: it holds ONLY Nami's execution plan (waves, tasks,
+criteria, risks). Who did what, route decisions, and check-in verdicts go to
+`logs/`; the closure report goes to `results/`. Nothing non-plan pollutes the plan doc.
+
 The owning agent creates the folder it needs on first write. No mission artifacts go outside `.mugiwara/`.
 
 ## Resume
 
-At session start, after context loss, or on any "where were we?" — dispatch `resume-coordinator` (mugiwara-resume) BEFORE Wave 0 triage. It rebuilds the picture from disk (plan, todos, trace, blockers) and reports the resume point. Resume before any wave; never start over. Disk state is truth.
+At session start, after context loss, or on any "where were we?" — embody `resume-coordinator` inline (mugiwara-resume) BEFORE Wave 0 triage. Rebuild the picture from disk (plan, todos, trace, blockers) and report the resume point. Resume before any wave; never start over. Disk state is truth.
 
 ## Wave 0 — Luffy Triage (always first)
 
-Front door: dispatch `using-mugiwara` (easy to remember) — it routes to the right crew member and records the route. For a full triage dispatch `luffy-orchestrator`. NEVER start directly with brainstorming or planning. Luffy classifies every request 5 ways (Trivial / Explicit / Exploratory / Open-ended / Ambiguous) and routes: Trivial and Explicit → Wave 2 directly; Exploratory, Open-ended, and Ambiguous → Wave 1 brainstorm first. The user may summon any crew member directly — Luffy still records the route.
+Front door: embody `using-mugiwara` inline (the router) — it routes to the right crew member and records the route. For a full triage embody `luffy-orchestrator` inline. NEVER start directly with brainstorming or planning. Luffy classifies every request 5 ways (Trivial / Explicit / Exploratory / Open-ended / Ambiguous) and routes: Trivial and Explicit → Wave 2 directly; Exploratory, Open-ended, and Ambiguous → Wave 1 brainstorm first. The user may summon any crew member directly — Luffy still records the route.
+
+Alongside triage, read the mode config per `mugiwara-mode`: `.mugiwara/config` (project) then `~/.mugiwara/config` (global); a key missing from both = `guided`. Lazy-create the project config on first WRITE only, never auto-create on read.
 
 ## Waves
 
@@ -45,7 +69,7 @@ Front door: dispatch `using-mugiwara` (easy to remember) — it routes to the ri
 | 6 Gates | Franky | mugiwara-gates | coverage + build verdict |
 | 7 Review | Robin ∥ Jinbe | mugiwara-review + mugiwara-security | severity-tagged findings |
 | 8 Healing | Brook | mugiwara-healing | fixes, then loop back to Wave 4 |
-| 9 Closure | Luffy | mugiwara-orchestration | closure report appended to plan |
+| 9 Closure | Luffy | mugiwara-orchestration | closure report + push mission branch + PR verdict file handed to user, who opens the PR (terminal gate in every mode) |
 
 Wave 4.5 is optional — Luffy invokes Skeptic after Chopper on high-stakes missions (verdicts, plans, reviews), or parallel to Wave 7 review when he calls for it. Skip means recorded without a pass.
 
@@ -59,29 +83,34 @@ Never silently work around a blocker. Brook reads this ledger at Wave 8 to decid
 
 ## Cleanup
 
-At closure (Wave 9), delete unused intermediate markdown files in `.mugiwara/` — superseded results, review, and issues reports. Keep the plan doc and the closure report.
+At closure (Wave 9), after the terminal step, run the cleanup procedure in `mugiwara-ship`: delete consumed intermediates — superseded results, review, issues reports, the per-mission decision log in `logs/`, and the consumed spec. Keep the plan doc, the closure report, the PR verdict, `config`, and cross-mission state (`logs/lessons.md`, `backup/`, `manifest.json`). List candidates before deleting.
 
 ## Rules
 
 1. Evidence over claims: no wave passes on assertion. The owning agent runs the checks and shows output.
-2. No wave skipped without the reason recorded in the plan doc.
+2. No wave skipped without the reason recorded in the decision log (`.mugiwara/logs/`) — name the wave, owner, and reason at the moment of omission.
 3. Heal loop is bounded: Wave 8 → Wave 4, max 3 cycles. After that, escalate to the human with full history.
-4. Any agent may consult Luffy mid-flight (re-dispatch `luffy-orchestrator`) for decisions and escalations.
-5. Wave 7 runs Robin and Jinbe in parallel.
+4. Any agent may consult Luffy mid-flight (embody `luffy-orchestrator` inline) for decisions and escalations.
+5. Wave 7 runs Robin and Jinbe review passes in parallel — both are inline passes over the same diff, or parallel review subagents for large diffs.
 6. The plan doc (`.mugiwara/plans/YYYY-MM-DD-<mission>.md`) is the single source of truth from Wave 2 onward.
 7. Frontend-touching tasks in Wave 3 must apply `mugiwara-frontend` in the same pass.
-8. One agent may hold many skills (e.g. Usopp holds `mugiwara-brainstorm` + `mugiwara-frontend`; the crew is 11 members); dispatch the agent, not the skill.
+8. One crew member may hold many skills (e.g. Usopp holds `mugiwara-brainstorm` + `mugiwara-frontend`; the crew is 15 members); load the member's skills, embody the role inline.
 9. On session start, context loss, or "where were we?" — resume before any wave via `resume-coordinator` (mugiwara-resume); never start over.
+10. The crew never merges and never deploys — push the branch + hand the verdict file to the user, who opens the PR; PR review is the terminal gate in every mode.
 
 ## Iron Law
 
 EVIDENCE OVER CLAIMS. No wave passes on assertion — the owning agent runs the checks and shows output. A wave that cannot produce evidence is a failed wave.
 
+## Verification gate (every completion claim)
+
+A claim is only as strong as the evidence produced in the same turn that made it. "Done", "passes", and "fixed" each name a command that would prove them — run that command, read its full output, then speak. A result from an earlier run, a guess, or a worker's word for it is not proof; re-run it and diff the work against the tree before reporting. Trust is not a substitute for verification.
+
 ## Red flags
 
 - A wave "passes" on a spoken claim with no command output or file to point at.
 - Heal loop beyond 3 cycles with the same failure still open.
-- A wave skipped with no reason recorded in the plan doc.
+- A wave skipped with no reason recorded in the decision log.
 - Execution starts before triage (Wave 0), or planning before brainstorm when triage routed to Wave 1.
 - Mission artifacts landing outside `.mugiwara/`.
 - Wave order drifts from the table (e.g. quality before checkpoint).

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

@@ -0,0 +1,60 @@
+---
+name: mugiwara-writing-skills
+description: Use when authoring a new mugiwara skill or revising an existing one. Enforces the skill anatomy (name/description 20-500 chars, when-to-use, process, rationalizations, red flags, verification), the 120-line body ceiling, and progressive disclosure of detail into a references/ file. Meta-skill: governs the other skills.
+---
+
+# Writing Mugiwara Skills
+
+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
+
+Every skill is a single `SKILL.md` at `content/skills/<name>/`, plus an optional `references/` folder for pulled-out detail. The name is the directory name; the validator checks that exact match.
+
+| Part | Requirement |
+|------|-------------|
+| name | equals the directory name, `mugiwara-<domain>` |
+| description | one "Use when..." sentence, 20-500 chars, loads the right skill and rejects the wrong ones |
+| body | `# title` + sections below, 120 lines max |
+| references/ | overflow detail, linked from the body |
+
+## When to use
+
+Use this skill the moment you start authoring a new skill file or restructuring an existing one. Skip it only for edits so small they cannot touch anatomy, limits, or wording.
+
+## Process
+
+1. **Confirm the niche.** Grep `content/skills/` for overlap; a new skill must not duplicate an existing one. Name it `mugiwara-<domain>`.
+2. **Write the description first.** One "Use when..." sentence naming the trigger, the behavior, and the boundary of what the skill is not for. Target 60-120 chars; the 500-char cap is a ceiling, not a goal.
+3. **Draft the body as a workflow.** Concrete numbered steps the agent executes, in order, with decisions and branches embedded. Name the skills it reads or dispatches. Use tables for excusable patterns and quick comparisons.
+4. **Cut to the ceiling.** Body must end at 120 lines or fewer. Section-by-section trim: merge subsections, kill throat-clearing, convert prose to tables. `ponytail` and `caveman` instincts apply — the body is command output, not a report.
+5. **Disclose progressively.** If a section exceeds roughly 15-20 lines, move it to `references/<topic>.md`, drop a one-line pointer in the body, and keep the pointer actionable (what to read and why).
+6. **Check the anatomy list.** Each required section present, in order: title, When to use, Process, Rationalizations, Red flags, Verification.
+7. **Validate.** Run `bun scripts/validate-content.ts --check content/skills/<name>/SKILL.md` and leave it exiting 0.
+
+## Rationalizations
+
+| Excuse | Rebuttal |
+|--------|----------|
+| "It's a guide, not a checklist" | A skill the agent cannot execute is decoration. Rewrite every paragraph as a step or a criterion. |
+| "The detail is essential" | Then move it to `references/` and keep the body a decision tree, not a dump. |
+| "More lines mean more coverage" | 120 lines enforce focus. Cover the decision, not the encyclopedia. |
+| "Long description catches more triggers" | A description that matches everything loads on nothing specific and trains the agent to ignore the skill. |
+| "Patterns are the same everywhere, I'll mirror another skill's text" | Wording must be original. Mirror the shape, never the sentences. |
+| "It's fine for now, I'll validate later" | Validation is the last step of the write, not a follow-up task. |
+
+## Red flags
+
+- Body over 120 lines or a description outside 20-500 chars.
+- No "Use when..." trigger sentence, or a description that names no boundary.
+- A section that reads as a lecture instead of steps the agent can run.
+- Required sections missing or out of order.
+- Text copied from another skill, superpowers, or agent-skills.
+- A `references/` file that is unreferenced, or a body so crammed it needed none.
+- An unvalidated file reported as done.
+
+Any of these: revise the skill, re-run validation, and confirm both before reporting.
+
+## Verification
+
+Evidence of a complete skill: the file passes `--check` with exit 0; `wc -l` on the body is at or under 120; the description triggers only its intended cases; every required section is present and original; and any overflow sits in a linked `references/` file.

package/dist/mugiwara.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync, rmSync as rmSync2 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync, rmSync as rmSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join as join7, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -79,7 +79,9 @@ async function confirm(rl, question) {
 }
 
 // src/targets/claude.ts
-import { join } from "node:path";
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // src/frontmatter.ts
 function parseFrontmatter(text) {
@@ -107,6 +109,8 @@ ${body}`;
 }
 
 // src/targets/claude.ts
+var here = dirname(fileURLToPath(import.meta.url));
+var HOOK_SRC = join(here, "..", "..", "hooks", "session-start.ts");
 var target = {
   id: "claude",
   label: "Claude Code",
@@ -126,6 +130,18 @@ var target = {
     if (data.tools)
       fm.tools = data.tools;
     return { relPath: `${data.name}.md`, text: stringifyFrontmatter(fm, body) };
+  },
+  postInstall({ scope, projectDir, home, dryRun }) {
+    const root = scope === "global" ? join(home, ".claude") : join(projectDir, ".claude");
+    const hookFile = join(root, "hooks", "session-start.ts");
+    if (dryRun)
+      return { written: [], notes: [] };
+    if (existsSync(HOOK_SRC) && !existsSync(hookFile)) {
+      mkdirSync(dirname(hookFile), { recursive: true });
+      copyFileSync(HOOK_SRC, hookFile);
+      return { written: [hookFile], notes: [] };
+    }
+    return { written: [], notes: [] };
   }
 };
 
@@ -178,7 +194,7 @@ var target3 = {
 };
 
 // src/targets/generic.ts
-import { existsSync, writeFileSync } from "node:fs";
+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;
@@ -214,7 +230,7 @@ ${body}` };
       const notes = [];
       const written = [];
       const file = join4(projectDir, bootstrapFile);
-      if (!existsSync(file)) {
+      if (!existsSync2(file)) {
         if (!dryRun)
           writeFileSync(file, `${bootstrapPointer}
 `);
@@ -233,7 +249,7 @@ var target4 = makeGeneric({
   label: "Gemini",
   rulesDir: ".gemini/mugiwara",
   bootstrapFile: "GEMINI.md",
-  bootstrapPointer: "Mugiwara crew installed in .gemini/mugiwara/ — read .gemini/mugiwara/mugiwara-workflow.md to run the pipeline."
+  bootstrapPointer: "Mugiwara crew installed in .gemini/mugiwara/ — read .gemini/mugiwara/mugiwara-workflow.md to run the pipeline inline in the main conversation."
 });
 
 // src/targets/codex.ts
@@ -242,7 +258,7 @@ var target5 = makeGeneric({
   label: "Codex",
   rulesDir: ".codex/mugiwara",
   bootstrapFile: "AGENTS.md",
-  bootstrapPointer: "Mugiwara crew installed in .codex/mugiwara/ — read .codex/mugiwara/mugiwara-workflow.md to run the pipeline."
+  bootstrapPointer: "Mugiwara crew installed in .codex/mugiwara/ — read .codex/mugiwara/mugiwara-workflow.md to run the pipeline inline in the main conversation."
 });
 
 // src/targets/windsurf.ts
@@ -290,20 +306,20 @@ var targets = { claude: target, opencode: target2, copilot: target3, gemini: tar
 var TARGET_IDS = Object.keys(targets);
 
 // src/installer.ts
-import { existsSync as existsSync2, mkdirSync, readFileSync, readdirSync, writeFileSync as writeFileSync2, copyFileSync, rmSync } from "node:fs";
-import { dirname, join as join5 } from "node:path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, writeFileSync as writeFileSync2, copyFileSync as copyFileSync2, rmSync } from "node:fs";
+import { dirname as dirname2, join as join5 } from "node:path";
 import { homedir } from "node:os";
 var CONTENT_DIR = join5(import.meta.dirname, "..", "content");
-var pkg = JSON.parse(readFileSync(join5(import.meta.dirname, "..", "package.json"), "utf8"));
+var pkg = JSON.parse(readFileSync2(join5(import.meta.dirname, "..", "package.json"), "utf8"));
 var VERSION = pkg.version;
 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(readFileSync(join5(CONTENT_DIR, "skills", name, "SKILL.md"), "utf8"));
+    const { data, body } = parseFrontmatter(readFileSync2(join5(CONTENT_DIR, "skills", name, "SKILL.md"), "utf8"));
     return { name, data, body };
   });
   const agents = readdirSync(join5(CONTENT_DIR, "agents")).filter((f) => f.endsWith(".md")).map((f) => {
-    const { data, body } = parseFrontmatter(readFileSync(join5(CONTENT_DIR, "agents", f), "utf8"));
+    const { data, body } = parseFrontmatter(readFileSync2(join5(CONTENT_DIR, "agents", f), "utf8"));
     return { name: f.replace(/\.md$/, ""), data, body };
   });
   return { skills, agents };
@@ -316,8 +332,8 @@ function installTo(target10, opts) {
   const backupRoot = join5(scope === "global" ? home : projectDir, ".mugiwara");
   const result = { written: [], skipped: [], backedUp: [], notes: [] };
   const writeOne = (absPath, text) => {
-    if (existsSync2(absPath)) {
-      if (readFileSync(absPath, "utf8") === text) {
+    if (existsSync3(absPath)) {
+      if (readFileSync2(absPath, "utf8") === text) {
         result.skipped.push(absPath);
         return;
       }
@@ -329,13 +345,13 @@ function installTo(target10, opts) {
       const ts = new Date().toISOString().replace(/[:.]/g, "-");
       const backupFile = join5(backupRoot, "backup", ts, absPath.replace(/[^a-zA-Z0-9]+/g, "_"));
       if (!dryRun) {
-        mkdirSync(dirname(backupFile), { recursive: true });
-        copyFileSync(absPath, backupFile);
+        mkdirSync2(dirname2(backupFile), { recursive: true });
+        copyFileSync2(absPath, backupFile);
       }
       result.backedUp.push(absPath);
     }
     if (!dryRun) {
-      mkdirSync(dirname(absPath), { recursive: true });
+      mkdirSync2(dirname2(absPath), { recursive: true });
       writeFileSync2(absPath, text);
     }
     result.written.push(absPath);
@@ -360,7 +376,7 @@ function installTo(target10, opts) {
 function removeInstalled(manifest, { dryRun = false } = {}) {
   const removed = [];
   for (const f of manifest.files) {
-    if (existsSync2(f)) {
+    if (existsSync3(f)) {
       if (!dryRun)
         rmSync(f);
       removed.push(f);
@@ -368,10 +384,10 @@ function removeInstalled(manifest, { dryRun = false } = {}) {
   }
   if (!dryRun) {
     for (const f of manifest.files) {
-      let d = dirname(f);
-      while (existsSync2(d) && readdirSync(d).length === 0) {
+      let d = dirname2(f);
+      while (existsSync3(d) && readdirSync(d).length === 0) {
         rmSync(d, { recursive: true });
-        const parent = dirname(d);
+        const parent = dirname2(d);
         if (parent === d)
           break;
         d = parent;
@@ -382,16 +398,16 @@ function removeInstalled(manifest, { dryRun = false } = {}) {
 }
 
 // src/manifest.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname2, join as join6 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname3, join as join6 } from "node:path";
 function manifestPath({ scope, projectDir, home }) {
   return scope === "global" ? join6(home, ".mugiwara", "manifest.json") : join6(projectDir, ".mugiwara", "manifest.json");
 }
 function readManifest(file) {
-  return existsSync3(file) ? JSON.parse(readFileSync2(file, "utf8")) : null;
+  return existsSync4(file) ? JSON.parse(readFileSync3(file, "utf8")) : null;
 }
 function writeManifest(file, data) {
-  mkdirSync2(dirname2(file), { recursive: true });
+  mkdirSync3(dirname3(file), { recursive: true });
   writeFileSync3(file, JSON.stringify(data, null, 2) + `
 `);
 }
@@ -433,7 +449,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" && !existsSync4(projectDir))
+    if (scope === "project" && !existsSync5(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"))
@@ -541,7 +557,7 @@ 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(readFileSync3(join7(dir, name, "SKILL.md"), "utf8"));
+    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;

package/docs/adoption-guide.md

@@ -0,0 +1,72 @@
+# Adoption Guide
+
+How to take the crew into your workflow without fighting it.
+
+## Pick your harness
+
+The crew ships native skills + agents where the harness supports them, and
+markdown rule files everywhere else.
+
+| Situation | Pick |
+|-----------|------|
+| You live in Claude Code or opencode | Native install — agents + skills + (Claude) session hook |
+| You want the full crew pipeline | Claude Code, opencode |
+| 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.
+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.
+
+## Pick your mode
+
+Modes live in `.mugiwara/config` (project) or `~/.mugiwara/config` (global):
+
+```
+mode=guided
+branch=feature/{type}-{issue}-{slug}
+commit=conventional
+```
+
+| Level | What it asks you |
+|-------|------------------|
+| `guided` | Plan GO, branch, commits, ambiguities, check-ins — everything |
+| `semi` | Plan GO only; branch/commits/ambiguities self-answer and log |
+| `auto` | Nothing, unless a high-risk task exists (auto-GO is gated) |
+
+State-mutating tests against shared state (real DB writes, network, browsers)
+always need your explicit consent — in every mode. That consent is not a knob.
+
+Missing config on read = `guided`. A flip applies from the next wave, never
+mid-wave.
+
+## Fit the crew to your workflow
+
+- **Trivial one-liners** don't need the crew — Luffy routes them straight to
+  execution.
+- **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
+  pipeline, including Skeptic's adversarial pass and Brook's heal loop.
+- **Repos the crew has touched before** read the lessons ledger at triage, so
+  every mission stands on the previous ones.
+
+## The execution model, in one sentence
+
+The crew runs **inline in your main conversation**; subagents are used only for
+independent `[PARALLEL]` task batches and background checks. You see every wave
+as it happens. See [execution-model.md](execution-model.md).
+
+## What the crew will never do
+
+- Merge a PR, or deploy. It pushes the branch and hands you the verdict file —
+  PR review is the terminal gate.
+- Auto-react to review comments or CI.
+- Let a wave pass on a spoken claim — evidence or it didn't happen.
+- Work around a blocker silently — everything lands in the ledger.
+
+## Going further
+
+- [Developer onboarding](developer-onboarding.md) if you want to contribute.
+- [Comparison](comparison.md) if you're weighing mugiwara against alternatives.

package/docs/agent-anatomy.md

@@ -0,0 +1,72 @@
+# Agent Anatomy
+
+Every mugiwara agent is a portable markdown file that names a crew member's
+persona, rules, and output contract. Agents are harness-native where supported
+(Claude Code, opencode) and markdown rule files elsewhere.
+
+## File structure
+
+```
+agents/<name>.md
+```
+
+```markdown
+---
+name: chopper-checkpoint
+description: Dispatch after each execution wave to audit results against the plan - re-runs every acceptance criterion, 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.
+skills: mugiwara-checkpoint
+---
+
+# Chopper — Checkpoint (Auditor)
+
+## Role
+...
+```
+
+## Frontmatter
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | yes | lowercase, hyphen-separated; matches the file name |
+| `description` | yes | ≥20 chars; what this agent does and when to summon it |
+| `skills` | no | the crew skills this member holds, comma-separated |
+
+Harness-specific agents (opencode) may add `mode`, `permission`, `model`, etc.
+in their own installation copy — the content stays portable.
+
+## The body — house style
+
+Agents follow a fixed skeleton so every member reads the same way:
+
+1. **Role** — one paragraph: what the member does and the boundary it never
+   crosses ("Auditor, not fixer", "never implements code").
+2. **Experience** — a one-line persona so the model adopts the right instincts
+   ("QA lead who has caught 'works on my machine' for 20 years").
+3. **When dispatched** — which wave of `mugiwara-workflow` and with what inputs.
+4. **Rules** — numbered, each an action bound to its reason, deferring to the
+   held skill for the full protocol.
+5. **Output** — where the artifact lands (`.mugiwara/results/...`) and how it
+   routes.
+6. **Red flags** — behaviors that mean the member stopped doing its job.
+
+## Agent vs skill
+
+- A **skill** is the reusable playbook ("how to audit a wave").
+- An **agent** is the persona that applies it ("Chopper is the auditor; Chopper
+  never fixes code").
+
+One agent holds many skills (Zoro holds `mugiwara-execution`, `mugiwara-git`,
+`mugiwara-mode`, `mugiwara-testcases`, `mugiwara-backend`). When the crew runs
+inline, the main thread loads the member's skills and embodies the persona.
+
+## Validation
+
+Agents are validated alongside skills on check-in (name, description length,
+sync between `content/` and the repo-root plugin copies). Run:
+
+```bash
+bun run validate
+bun run validate --check-sync
+```
+
+See [developer-onboarding.md](developer-onboarding.md).

package/docs/agents.md

@@ -0,0 +1,51 @@
+# The Crew — 15 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."
+
+| 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 |
+| `zoro-execution` | Zoro | Executor — inline sequential tasks, parallel worker batches, evidence per task | executing an approved plan |
+| `chopper-checkpoint` | Chopper | Auditor — verify-everything, deduped re-runs, failure ledger | auditing a wave's results |
+| `sanji-quality` | Sanji | Quality — discover real tooling, format/lint/test | after checkpoint passes |
+| `franky-gates` | Franky | Gates — coverage, build, Definition of Done, binary verdicts | after quality checks |
+| `robin-reviewer` | Robin | Reviewer — doubt-driven diff review, breaking-change map first | after gates pass |
+| `jinbe-security` | Jinbe | Security — STRIDE, OWASP, secrets, injection, dependencies | security audit of a diff |
+| `brook-healing` | Brook | Healer — reads the ledger, root-cause fixes, ≤3 cycles | any wave produced failures |
+| `skeptic-verifier` | Skeptic | Adversarial verifier — doubts every output, does NOT validate | high-stakes verdicts, plans, reviews |
+| `eval-runner` | Eval Runner | Harness tester — task suites, judge-agent comparison | verifying mugiwara itself works |
+| `resume-coordinator` | Resume Coordinator | Resumer — rebuilds state from `.mugiwara/`, continues never restarts | context loss, new session mid-mission |
+| `memory-keeper` | Memory Keeper | Institutional memory — surfaces past lessons, captures new ones | mission start + closure |
+
+## How to summon
+
+Say a crew member's name in your request:
+
+```
+> Chopper, audit the last wave against the plan
+> Nami, plan this out
+```
+
+Luffy still records the route and its reason, and direct calls do not skip
+check-ins. The harness stays coherent either way.
+
+## Who never does what
+
+- **Luffy** never implements code.
+- **Chopper** never fixes findings — reports them.
+- **Skeptic** never validates — doubts.
+- **Robin/Jinbe** never implement — findings to Brook.
+- Crew members never dispatch each other. Workers are subagents, never crew.
+
+## The crew ships whole
+
+Every install gets all 15 agents and all 32 skills. No project-type selection —
+the harness routes each task to the right specialist.
+
+See [skills.md](skills.md) for the 32 techniques, or
+[workflow.md](workflow.md) for the pipeline.

package/docs/claude-setup.md

@@ -0,0 +1,43 @@
+# Claude Code Setup
+
+Claude Code is a fully supported target — native skills + agents + SessionStart
+hook.
+
+## Install via the marketplace
+
+```bash
+/plugin marketplace add ionivetech/mugiwara
+/plugin install mugiwara
+```
+
+## Install via CLI (global or per project)
+
+```bash
+# global Claude Code install
+npx @ionivetech/mugiwara@latest --global --target claude --yes
+
+# project install
+npx @ionivetech/mugiwara@latest --project ./my-app --target claude --yes
+```
+
+**Update** — re-install from the marketplace (or `mugiwara update` via CLI).
+
+**Uninstall** — `/plugin uninstall mugiwara`, or `mugiwara uninstall` via CLI.
+
+## What you get
+
+- 32 skills in `~/.claude/skills/` (global) or `.claude/skills/` (project).
+- 15 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.
+
+## Use it
+
+```
+> add dark mode to the settings page
+```
+
+The crew runs inline in your main conversation; subagents only for parallel
+batches. At closure the crew pushes the branch and hands you the PR verdict
+file with a ready PR summary block — you open the PR, in every mode.

package/docs/codex-setup.md

@@ -0,0 +1,26 @@
+# Codex Setup
+
+## Install
+
+```bash
+codex plugin marketplace add ionivetech/mugiwara
+codex plugin add mugiwara@mugiwara
+```
+
+Or via the CLI:
+
+```bash
+npx @ionivetech/mugiwara@latest --project ./my-app --target codex --yes
+```
+
+**Update** — `codex plugin update mugiwara`. **Uninstall** — `codex plugin remove mugiwara`.
+
+## What you get
+
+- 32 skills as markdown rules in `.codex/mugiwara/`.
+- An `AGENTS.md` bootstrap pointer (created if missing).
+
+## Notes
+
+Codex is a **project-only** target. Agents are skills-only here — the crew
+pipeline runs through the rule files.