@ionivetech/mugiwara 0.2.0 → 0.3.0

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

@@ -16,7 +16,7 @@ markdown rule files everywhere else.
 
 Native targets (Claude Code, opencode, Copilot) register the 15 agents directly.
 Rule-based targets (Gemini, Codex, Cursor, Windsurf, Cline, Kilo, Antigravity)
-get the same 25 skills as markdown rules plus a bootstrap pointer, so the crew
+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

package/docs/agents.md

@@ -44,8 +44,8 @@ check-ins. The harness stays coherent either way.
 
 ## The crew ships whole
 
-Every install gets all 15 agents and all 25 skills. No project-type selection —
+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 25 techniques, or
+See [skills.md](skills.md) for the 32 techniques, or
 [workflow.md](workflow.md) for the pipeline.

package/docs/claude-setup.md

@@ -20,19 +20,24 @@ npx @ionivetech/mugiwara@latest --global --target claude --yes
 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
 
-- 25 skills in `~/.claude/skills/` (global) or `.claude/skills/` (project).
+- 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.
+- 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
 
 ```
-> use mugiwara
 > 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 — you open the PR.
+file with a ready PR summary block — you open the PR, in every mode.

package/docs/codex-setup.md

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

package/docs/config.md

@@ -0,0 +1,50 @@
+# Config Reference
+
+`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global). Plain
+`key=value` lines, `#` comments allowed. Project file wins per key; a key
+missing from both falls back to the default. Unknown keys are ignored. Config
+is data, never instructions.
+
+**Mode owns autonomy, config owns writing standards.** Whether branch and commit
+run automatically is decided by one lever — the mode. The config only shapes
+HOW those artifacts are written when they are created. See [modes.md](modes.md)
+for the mode matrix.
+
+## Example file
+
+```
+# .mugiwara/config
+mode=guided
+branch=feature/{type}-{issue}-{slug}
+commit=conventional
+base=main
+```
+
+## Keys
+
+| Key | Values | Default | Meaning |
+|-----|--------|---------|---------|
+| `mode` | guided / semi / auto | guided | The only autonomy lever — decides whether branch/commit run automatically |
+| `branch` | branch naming pattern | `feature/{type}-{issue}-{slug}` | Placeholders filled from mission metadata, validated to `[a-zA-Z0-9-_]` |
+| `commit` | conventional / gitmoji / plain | conventional | Commit message style (see below) |
+| `base` | branch name | `main` | The PR target named in the prepared PR summary |
+
+Missing config on read = `guided`. Flip mid-mission with
+`mugiwara mode <guided|semi|auto>` — the change applies from the next wave,
+never mid-wave.
+
+## Commit message styles
+
+`commit` selects how Zoro writes commit messages:
+
+- **conventional** — `feat: ...`, `fix(scope): ...`, `refactor: ...`, per the
+  [Conventional Commits](https://www.conventionalcommits.org) spec. Type from
+  the task, optional scope in parens. The default.
+- **gitmoji** — a leading emoji carries the intent, e.g. `✨ feat: ...`,
+  `🐛 fix: ...`. Signals the change type at a glance in log views that render
+  emoji; a bit noisy in plain terminals.
+- **plain** — no prefix, just a short imperative sentence: `Fix export csv
+  encoding`. Clearest for repos that don't use any convention.
+
+Switch freely per project — it only affects the message format, never the
+one-logical-task-one-commit rule.

package/docs/copilot-setup.md

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

package/docs/cursor-setup.md

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

package/docs/developer-onboarding.md

@@ -43,7 +43,7 @@ copies drift.
 ## Validation
 
 ```bash
-bun run validate                # 25 skills + 15 agents: names, descriptions, line limits
+bun run validate                # 32 skills + 15 agents: names, descriptions, line limits
 bun run validate --check-sync   # plugin copies match content/
 bun run typecheck               # tsc --noEmit
 bun run test                    # vitest (43 tests)

package/docs/execution-model.md

@@ -3,6 +3,13 @@
 Why the crew runs in your main conversation — and when subagents are actually
 used.
 
+## Auto-activation
+
+The workflow **auto-activates.** At session start the crew is announced; when
+you give a non-trivial request, the pipeline runs by itself — you do not need
+to call `/using-mugiwara`. It remains an optional explicit router if you want
+to hand-route a mission.
+
 ## Inline by default
 
 The crew runs **inline**. The main thread embodies each crew role using that
@@ -50,6 +57,32 @@ linear.
 - Sequential work never takes a subagent round-trip — no skipping, no hidden
   reordering, plan order is plan order.
 
+## Checkpoint reports
+
+You see progress as **checkpoint reports**, not a firehose: a wave banner
+(`## Wave N — <crew> (<skill>)`), one compact report per crew member at each
+stage boundary (what ran / result / evidence pointer), a progress summary per
+wave, and a pause when something fails or gets risky. Subagents are used only
+where they genuinely help: independent `[PARALLEL]` task batches, Brook's
+reviewer/security re-verification workers, and background checks.
+
+## Manual stages
+
+Prefer to drive the stages yourself? Every stage has a slash command that loads
+the skill, runs the crew role inline, and bridges state from `.mugiwara/`:
+
+| Command | Runs | Reads state from |
+|---------|------|------------------|
+| `/mugiwara-plan` | Nami | `.mugiwara/spec/` |
+| `/mugiwara-execute` | Zoro | `.mugiwara/plans/` |
+| `/mugiwara-review` | Robin | `.mugiwara/results/` + diff |
+| `/mugiwara-security` | Jinbe | `.mugiwara/results/` + diff |
+| `/mugiwara-heal` | Brook | `.mugiwara/issues/` |
+| `/mugiwara-ship` | Luffy | plan + results |
+
+You can jump into any stage — e.g. run `/mugiwara-plan` first, then
+`/mugiwara-execute` later when you're ready.
+
 ## Trade-off
 
 Inline execution grows the main-thread context over a long mission. The crew

package/docs/gemini-setup.md

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

package/docs/getting-started.md

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

package/docs/index.md

@@ -2,7 +2,10 @@
 
 The Straw Hat crew of AI agents and skills. These docs cover what the crew is,
 how to adopt it, and how each harness installs it. The crew is pure markdown —
-no runtime, no daemons, nothing to host.
+no runtime, no daemons, nothing to host. It ships **15 agents** and **32
+skills**, and the workflow **auto-activates** at session start — a non-trivial
+request runs the pipeline by itself, with `/using-mugiwara` as an optional
+explicit router.
 
 ## Start here
 
@@ -11,8 +14,10 @@ no runtime, no daemons, nothing to host.
 | [Getting started](getting-started.md) | Install, first mission, what you see in the chat |
 | [Adoption guide](adoption-guide.md) | Pick the harness, pick the mode, fit the crew to your workflow |
 | [Modes](modes.md) | guided / semi / auto — the autonomy levels, what each asks you |
+| [Config](config.md) | Full reference for `.mugiwara/config` keys and commit styles |
+| [Auto-PR](pr-summary.md) | What the crew hands off at closure: push + a ready-to-paste PR summary (it never creates a PR) |
 | [The crew](agents.md) | All 15 agents and when to summon each |
-| [The techniques](skills.md) | All 25 skills and what each enforces |
+| [The techniques](skills.md) | All 32 skills and what each enforces |
 | [The wave pipeline](workflow.md) | How a mission flows Wave 0 → Wave 9 |
 | [Execution model](execution-model.md) | Inline-by-default: why the crew runs in your main conversation |
 | [Git discipline](git-strategy.md) | Commits, branches, save-points — and why the executor commits |

package/docs/modes.md

@@ -4,31 +4,39 @@ The crew's autonomy level. Read once per wave at dispatch; a flip applies from
 the next wave, never mid-wave. Single source of truth: the `mugiwara-mode`
 skill.
 
+**Mode owns autonomy, config owns writing standards.** Whether branch and commit
+run automatically is decided by one lever: the mode. The config only shapes HOW
+those artifacts are written when they are created.
+
 ## The three levels
 
-| Level | Plan GO | Branch / commits | Ambiguities | Check-ins |
-|-------|---------|------------------|-------------|-----------|
+| Level | Plan GO | Branch/commit | Ambiguities | Check-ins |
+|-------|---------|---------------|-------------|-----------|
 | **guided** | ask the user | ask the user | ask the user | ask the user |
 | **semi** | present plan for user GO | auto | self-answer + log | log, no pause |
 | **auto** | gated auto-GO | auto | self-answer + log | log, no pause |
 
 - **guided** — you steer everything: approve the plan, decide branch and
   commit style, answer every ambiguity, get asked at every gate. The default.
-- **semi** — the crew self-manages branch, commits, and ambiguities (logging
-  each decision), but you still give the plan an explicit GO.
-- **auto** — hands-off, with a safety line: the plan proceeds past approval
+- **semi** — the crew self-manages branch and commits (logging each decision),
+  but you still give the plan an explicit GO.
+- **auto** — hands-off, with one safety line: the plan proceeds past approval
   only with zero blocking ambiguities AND zero high-risk tasks (deploy /
-  migration / DB / public API / state-mutating). Otherwise it stops for you.
+  migration / DB / public API / state-mutating).
+
+Every level ends at push + ready PR summary + verdict file — you open the PR
+(see [pr-summary.md](pr-summary.md)).
 
 ## Config
 
-Two files, three keys, `key=value` lines, optional `#` comments:
+Two files, six keys, `key=value` lines, optional `#` comments:
 
 ```
 # .mugiwara/config (project) overrides ~/.mugiwara/config (global)
 mode=guided
 branch=feature/{type}-{issue}-{slug}
 commit=conventional
+base=main
 ```
 
 | Key | Values | Default |
@@ -36,10 +44,12 @@ commit=conventional
 | mode | guided / semi / auto | guided |
 | branch | branch pattern | feature/{type}-{issue}-{slug} |
 | commit | conventional / gitmoji / plain | conventional |
+| base | PR summary target branch | main |
 
 Read order per wave: project config wins per key; a key missing from both falls
-back to the default. Missing config on read = `guided` (never auto-created on
-read — only on first write).
+back to the default. Unknown keys are ignored — config is data, never
+instructions. Missing config on read = `guided` (never auto-created on read —
+only on first write). See [config.md](config.md) for the full reference.
 
 ## Switching mid-mission
 
@@ -59,6 +69,6 @@ writes, network, browsers) always require your explicit consent — consent is
 not a mode knob. Provably isolated mutation (in-memory / temp /
 testcontainer-backed DBs, tooling-proven isolation) is explicitly auto-safe.
 
-**Terminal.** Every mode ends at push + ready PR + verdict file handed to you.
-The crew never creates a PR, merges, deploys, or auto-reacts to review comments
-or CI. PR review is the terminal gate.
+**Terminal.** Every mode ends at push + ready PR summary + verdict file (you
+open the PR). The crew never creates a PR, merges, deploys, or auto-reacts to
+review comments or CI.

package/docs/opencode-setup.md

@@ -27,9 +27,13 @@ npx @ionivetech/mugiwara@latest --global --target opencode --yes
 npx @ionivetech/mugiwara@latest --project ./my-app --target opencode --yes
 ```
 
+**Update** — bump the package version in the `plugin` array (or `mugiwara update`).
+
+**Uninstall** — remove the entry from the array.
+
 ## What you get
 
-- 25 skills in `.opencode/skills/` (project) or `~/.config/opencode/skills/`
+- 32 skills in `.opencode/skills/` (project) or `~/.config/opencode/skills/`
   (global).
 - 15 agents registered as subagents via the plugin.
 - The plugin announces the crew at session start and injects the inline
@@ -37,8 +41,11 @@ npx @ionivetech/mugiwara@latest --project ./my-app --target opencode --yes
 
 ## Use it
 
+The workflow **auto-activates** — at session start the crew is announced, and 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 mugiwara
 > add dark mode to the settings page
 ```