@ionivetech/mugiwara 0.6.5 → 0.6.6

package/src/onboard.ts

@@ -0,0 +1,207 @@
+// src/onboard.ts — zero-LLM onboarding wizard (6 questions, writes .mugiwara/config).
+// Runs on every platform via the `mugiwara onboard` CLI command. No LLM, no network.
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRl, choose, confirm, type Rl } from './prompt.ts';
+
+// Canonical key order for the written config. Keys the wizard does not ask
+// about (auto_commit, delegate_threshold, heal_max_cycles, verbosity) are
+// preserved from an existing config, never reset to defaults.
+const DEFAULT_ORDER = [
+  'mode', 'branch', 'commit', 'auto_commit', 'coverage_new', 'coverage_modified',
+  'review_depth', 'quality_depth', 'delegate_threshold', 'heal_max_cycles', 'verbosity',
+];
+
+// Defaults for keys the wizard does not ask about — used only when the key is
+// absent from an existing config (fresh install). Existing values always win.
+const DEFAULTS: Record<string, string> = {
+  auto_commit: 'on',
+  delegate_threshold: '60',
+  heal_max_cycles: '3',
+  verbosity: 'normal',
+};
+
+const BRANCH_PRESETS: Record<number, string> = {
+  1: 'feature/{type}-{issue}-{slug}',
+  2: 'feature/{slug}',
+  3: 'feat/{slug}',
+};
+
+const COMMIT_PRESETS: Record<number, string> = {
+  1: 'conventional',
+  2: 'gitmoji',
+  3: 'plain',
+};
+
+export function parseConfig(lines: string[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t || t.startsWith('#')) continue;
+    const eq = t.indexOf('=');
+    if (eq === -1) continue;
+    const k = t.slice(0, eq).trim();
+    const v = t.slice(eq + 1).trim();
+    if (!map.has(k)) map.set(k, v);
+  }
+  return map;
+}
+
+export function buildConfig(existing: Map<string, string>, updates: Record<string, string>): string {
+  const merged = new Map(existing);
+  for (const [k, v] of Object.entries(updates)) merged.set(k, v);
+  const lines: string[] = [];
+  for (const k of DEFAULT_ORDER) {
+    const v = merged.get(k) ?? DEFAULTS[k];
+    if (v === undefined) continue;
+    lines.push(`${k}=${v}`);
+    merged.delete(k);
+  }
+  for (const [k, v] of merged) lines.push(`${k}=${v}`);
+  return lines.join('\n') + '\n';
+}
+
+async function askFreeText(rl: Rl, prompt: string): Promise<string> {
+  for (;;) {
+    const v = (await rl.question(prompt)).trim();
+    if (v) return v;
+    console.log('  Cannot be empty.');
+  }
+}
+
+// Same guard the runtime helpers use: a symlinked config must never be
+// overwritten through the wizard (the target file is not ours to write).
+function assertNotSymlink(file: string): void {
+  if (!existsSync(file)) return;
+  try {
+    if (lstatSync(file).isSymbolicLink()) throw new Error(`refusing to follow symlink: ${file}`);
+  } catch (e) {
+    if ((e as { code?: string }).code === 'ENOENT') return;
+    throw e;
+  }
+}
+
+export async function runOnboard(projectDir: string): Promise<void> {
+  if (!process.stdin.isTTY) {
+    throw new Error('Not a terminal. Run `mugiwara onboard` in a terminal, or edit .mugiwara/config directly.');
+  }
+  const mugiwaraDir = join(projectDir, '.mugiwara');
+  const configPath = join(mugiwaraDir, 'config');
+  assertNotSymlink(configPath);
+  const existing = parseConfig(existsSync(configPath) ? readFileSync(configPath, 'utf8').split(/\r?\n/) : []);
+
+  const rl = createRl();
+  try {
+    console.log('');
+    console.log('╔══════════════════════════════════════╗');
+    console.log('║   Mugiwara Onboarding Wizard         ║');
+    console.log('╚══════════════════════════════════════╝');
+    console.log('');
+
+    if (existing.size > 0) {
+      const redo = await confirm(rl, 'Existing .mugiwara/config found. Re-onboard?');
+      if (!redo) {
+        console.log('Onboarding cancelled. Config preserved.');
+        return;
+      }
+      console.log('');
+    }
+
+    // Q1 — branch pattern
+    const branchChoice = await choose(rl, 'Q1 — Branch naming pattern:', [
+      'Trunk-based — feature/{type}-{issue}-{slug}',
+      'GitFlow — feature/{slug}',
+      'GitHub Flow — feat/{slug}',
+      'Custom — enter your own pattern',
+    ]);
+    let branch: string;
+    if (branchChoice === 3) {
+      branch = await askFreeText(rl, '  Branch pattern (placeholders: {type} {issue} {slug}, e.g. {issue}-{slug}): ');
+    } else {
+      branch = BRANCH_PRESETS[branchChoice + 1];
+    }
+
+    // Q2 — autonomy mode
+    const modeIdx = await choose(rl, 'Q2 — Autonomy mode:', [
+      'guided — ask before every wave transition',
+      'semi — auto-advance through waves, pause on failures',
+      'auto — full auto-pilot',
+    ]);
+    const mode = ['guided', 'semi', 'auto'][modeIdx];
+
+    // Q3 — review depth
+    const reviewIdx = await choose(rl, 'Q3 — Code review depth:', [
+      'full — breaking-change map, five-axis review, <=3 cycles',
+      'standard — five-axis review, 1 cycle',
+      'quick — diff-only, no caller-map',
+    ]);
+    const reviewDepth = ['full', 'standard', 'quick'][reviewIdx];
+
+    // Q4 — quality depth
+    const qualityIdx = await choose(rl, 'Q4 — Quality check depth:', [
+      'full — format, lint, typecheck, test, build',
+      'standard — lint, typecheck, test',
+      'quick — test only',
+    ]);
+    const qualityDepth = ['full', 'standard', 'quick'][qualityIdx];
+
+    // Q5 — coverage
+    const covIdx = await choose(rl, 'Q5 — Test coverage threshold:', [
+      '90/80 — new code 90%, modified 80%',
+      '80/70 — new code 80%, modified 70%',
+      'custom — enter your own values',
+      'none — 0/0, no coverage enforcement',
+    ]);
+    let coverageNew = 90;
+    let coverageModified = 80;
+    if (covIdx === 1) { coverageNew = 80; coverageModified = 70; }
+    else if (covIdx === 2) {
+      coverageNew = Number.parseInt(await askFreeText(rl, '  Coverage for new code (%): '), 10) || 0;
+      coverageModified = Number.parseInt(await askFreeText(rl, '  Coverage for modified code (%): '), 10) || 0;
+    } else if (covIdx === 3) { coverageNew = 0; coverageModified = 0; }
+
+    // Q6 — commit style
+    const commitChoice = await choose(rl, 'Q6 — Commit style:', [
+      'Conventional Commits — feat:, fix:, chore:, docs:',
+      'Gitmoji — emoji-prefixed conventional',
+      'Plain — no prefix, imperative sentence',
+      'Custom template — enter your own (placeholders: {type} {issue} {title})',
+    ]);
+    let commit: string;
+    if (commitChoice === 3) {
+      commit = await askFreeText(rl, '  Commit template (e.g. {issue}: {title}): ');
+    } else {
+      commit = COMMIT_PRESETS[commitChoice + 1];
+    }
+
+    // ---- Write config ----
+    if (!existsSync(mugiwaraDir)) mkdirSync(mugiwaraDir, { recursive: true });
+    const body = buildConfig(existing, {
+      mode,
+      branch,
+      commit,
+      coverage_new: String(coverageNew),
+      coverage_modified: String(coverageModified),
+      review_depth: reviewDepth,
+      quality_depth: qualityDepth,
+    });
+    writeFileSync(configPath, `# .mugiwara/config — written by mugiwara onboard on ${new Date().toISOString().slice(0, 10)}\n${body}`);
+
+    // ---- Summary ----
+    console.log('╔══════════════════════════════════════╗');
+    console.log('║   Onboarding Complete                ║');
+    console.log('╚══════════════════════════════════════╝');
+    console.log('');
+    console.log(`  Branch pattern:   ${branch}`);
+    console.log(`  Autonomy mode:    ${mode}`);
+    console.log(`  Review depth:     ${reviewDepth}`);
+    console.log(`  Quality depth:    ${qualityDepth}`);
+    console.log(`  Coverage:         ${coverageNew}/${coverageModified}`);
+    console.log(`  Commit style:     ${commit}`);
+    console.log('');
+    console.log(`  Config written:   ${configPath}`);
+    console.log('');
+  } finally {
+    rl.close();
+  }
+}

package/src/run.ts

@@ -0,0 +1,82 @@
+// src/run.ts
+// `mugiwara run <script> [args...]` — runs a bundled harness script against the
+// current project.
+//
+// Why this exists: the skills tell the crew to run `scripts/savepoint.sh`, but
+// the installer only ever copied `content/` and `references/` into a project.
+// That path resolved against the project's cwd, where the file does not exist,
+// so every savepoint / lane / evidence / mission-report call silently did
+// nothing. Resolving from the package root fixes it for every install target at
+// once.
+import { existsSync, readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// src/ during dev, dist/ once bundled — scripts/ sits beside both
+export const SCRIPTS_DIR = join(here, '..', 'scripts');
+
+/** Scripts a project is meant to call. Anything else stays internal tooling. */
+export const RUNNABLE = ['savepoint.sh', 'lane.sh', 'evidence.sh', 'mission-report.sh'] as const;
+
+/**
+ * Locate a POSIX shell. Windows has none natively, but Git for Windows ships
+ * one and mugiwara is git-backed anyway — savepoint reads git to compute state,
+ * so a git-less machine cannot run a mission regardless.
+ */
+export function findBash(): string | null {
+  const explicit = process.env.MUGIWARA_BASH?.trim();
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const candidates =
+    process.platform === 'win32'
+      ? [
+          'C:\\Program Files\\Git\\bin\\bash.exe',
+          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+          join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Git', 'bin', 'bash.exe'),
+        ]
+      : // /bin/bash is not universal on Linux — Alpine and other busybox-based
+        // images ship /bin/sh only. Probing beats assuming: an assumed path
+        // spawns ENOENT, which surfaces as a stack trace instead of the
+        // actionable "no bash found" message below.
+        ['/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash', '/opt/homebrew/bin/bash'];
+  for (const p of candidates) {
+    if (p && existsSync(p)) return p;
+  }
+  // last resort: whatever is on PATH (Git Bash, WSL, MSYS, a nonstandard prefix)
+  const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['bash'], {
+    encoding: 'utf8',
+  });
+  const first = probe.stdout?.split(/\r?\n/).find((l) => l.trim());
+  return first?.trim() || null;
+}
+
+/** Platform-correct remedy for a missing bash — "install Git for Windows" is wrong advice on Linux. */
+export function noBashMessage(): string {
+  const remedy =
+    process.platform === 'win32'
+      ? 'Install Git for Windows (which ships bash)'
+      : 'Install bash with your package manager (e.g. `apk add bash`, `apt install bash`)';
+  return `no bash found. ${remedy}, or set MUGIWARA_BASH to a bash executable.`;
+}
+
+export function runScript(name: string, args: string[], projectDir: string): number {
+  // no path separators: `run` takes a script name, never an arbitrary path
+  if (!/^[a-z0-9-]+\.sh$/.test(name)) {
+    throw new Error(`invalid script name "${name}" (expected one of: ${RUNNABLE.join(', ')})`);
+  }
+  const script = join(SCRIPTS_DIR, name);
+  if (!existsSync(script)) {
+    const have = existsSync(SCRIPTS_DIR) ? readdirSync(SCRIPTS_DIR).filter((f) => f.endsWith('.sh')) : [];
+    throw new Error(`script not found: ${name}${have.length ? ` (available: ${have.join(', ')})` : ''}`);
+  }
+  const bash = findBash();
+  if (!bash) throw new Error(noBashMessage());
+  const r = spawnSync(bash, [script, ...args], {
+    cwd: resolve(projectDir),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (r.error) throw r.error;
+  return r.status ?? 1;
+}

package/src/targets/claude.ts

@@ -1,5 +1,5 @@
 // src/targets/claude.ts
-import { existsSync, readFileSync, mkdirSync, copyFileSync, chmodSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, chmodSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stringifyFrontmatter, type FrontmatterData } from '../frontmatter.ts';
@@ -19,6 +19,128 @@ function toolsFromScope(scope?: string): string | undefined {
   return undefined;
 }
 
+/**
+ * Register the copied hooks in settings.json.
+ *
+ * Copying hook files into .claude/hooks/ is not enough — Claude Code only runs
+ * a hook that settings.json names. Without this the CLI install left three
+ * dead files on disk while the plugin install (which reads hooks/hooks.json
+ * itself) worked, so the two install paths silently disagreed.
+ *
+ * Idempotent: an entry whose command already points at our hook is left alone,
+ * and unrelated user hooks are never touched.
+ */
+const SCRIPTS_SRC = join(here, '..', '..', 'scripts');
+
+/** Copy the harness shell scripts (and their shared lib) next to the hooks. */
+function copyScripts(dstDir: string): string[] {
+  if (!existsSync(SCRIPTS_SRC)) return [];
+  const written: string[] = [];
+  const copyDir = (src: string, dst: string): void => {
+    if (!existsSync(src)) return;
+    for (const f of readdirSync(src)) {
+      // install.sh is the npx bootstrap, not a harness script — never shipped
+      // into a project. initiative.ts ships too: `mugiwara initiative` runs it.
+      if ((!f.endsWith('.sh') && f !== 'initiative.ts') || f === 'install.sh') continue;
+      const to = join(dst, f);
+      mkdirSync(dst, { recursive: true });
+      copyFileSync(join(src, f), to);
+      chmodSync(to, 0o755);
+      written.push(to);
+    }
+  };
+  copyDir(SCRIPTS_SRC, dstDir);
+  copyDir(join(SCRIPTS_SRC, 'lib'), join(dstDir, 'lib'));
+  return written;
+}
+
+type HookEntry = { type: string; command: string; timeout?: number };
+type HookGroup = { matcher?: string; hooks: HookEntry[] };
+
+function wireSettings(root: string, hooksDir: string): { written: string[]; notes: string[] } {
+  const file = join(root, 'settings.json');
+  const events: Record<string, { file: string; timeout: number; matcher?: string }> = {
+    SessionStart: { file: 'session-start.js', timeout: 10 },
+    UserPromptSubmit: { file: 'mugiwara-mode-tracker.js', timeout: 5 },
+    Stop: { file: 'auto-savepoint.js', timeout: 20 },
+    SubagentStop: { file: 'pipeline-guard.js', timeout: 15 },
+    // matcher scopes the marker to crew invocations — without it the hook would
+    // fire on every tool call in the session for no benefit
+    PostToolUse: { file: 'engagement-marker.js', timeout: 5, matcher: 'Task|Skill' },
+  };
+
+  let settings: Record<string, unknown> = {};
+  if (existsSync(file)) {
+    try {
+      settings = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>;
+    } catch {
+      // a hand-broken settings.json is the user's to fix — never overwrite it
+      return { written: [], notes: [`${file} is not valid JSON — add the mugiwara hooks manually`] };
+    }
+  }
+  const hooks = (settings.hooks ?? {}) as Record<string, HookGroup[]>;
+  let changed = false;
+  for (const [event, spec] of Object.entries(events)) {
+    const command = join(hooksDir, spec.file);
+    if (!existsSync(command)) continue;
+    const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const already = groups.some((g) => g.hooks?.some((h) => h.command?.includes(spec.file)));
+    if (already) continue;
+    const group: HookGroup = { hooks: [{ type: 'command', command: JSON.stringify(command), timeout: spec.timeout }] };
+    if (spec.matcher) group.matcher = spec.matcher;
+    groups.push(group);
+    hooks[event] = groups;
+    changed = true;
+  }
+  if (!changed) return { written: [], notes: [] };
+  settings.hooks = hooks;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  // NOT reported as `written`: the manifest is an uninstall delete-list, and
+  // settings.json belongs to the user — we only merged into it. It is un-merged
+  // by unwireSettings instead.
+  return { written: [], notes: [`hooks registered in ${file}`] };
+}
+
+/**
+ * Remove only the hook entries mugiwara added, leaving every other setting and
+ * any user-authored hook untouched. Identified by their command pointing into
+ * our hooks dir.
+ */
+function unwireSettings(root: string): { changed: string[]; notes: string[] } {
+  const file = join(root, 'settings.json');
+  if (!existsSync(file)) return { changed: [], notes: [] };
+  let settings: Record<string, unknown>;
+  try {
+    settings = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return { changed: [], notes: [`${file} is not valid JSON — left untouched`] };
+  }
+  const hooks = settings.hooks as Record<string, HookGroup[]> | undefined;
+  if (!hooks) return { changed: [], notes: [] };
+
+  const ours = new Set(['session-start.js', 'mugiwara-mode-tracker.js', 'auto-savepoint.js', 'pipeline-guard.js', 'engagement-marker.js']);
+  const isOurs = (h: HookEntry): boolean =>
+    [...ours].some((f) => h.command?.includes(join('hooks', f)) || h.command?.includes(`hooks/${f}`));
+
+  let changed = false;
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = groups
+      .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isOurs(h)) }))
+      .filter((g) => g.hooks.length > 0);
+    if (kept.length !== groups.length || kept.some((g, i) => g.hooks.length !== groups[i]?.hooks?.length)) {
+      changed = true;
+    }
+    if (kept.length) hooks[event] = kept;
+    else { delete hooks[event]; changed = true; }
+  }
+  if (!changed) return { changed: [], notes: [] };
+  if (!Object.keys(hooks).length) delete settings.hooks;
+  // an emptied settings.json still belongs to the user — rewrite, never remove
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { changed: [file], notes: [] };
+}
+
 export const target: Target = {
   id: 'claude',
   label: 'Claude Code',
@@ -55,7 +177,9 @@ export const target: Target = {
     if (dryRun) return { written: [], notes: [] };
     if (existsSync(HOOKS_SRC)) {
       for (const f of readdirSync(HOOKS_SRC)) {
-        if (!f.endsWith('.ts')) continue;
+        // .js is what settings.json runs (node-only, no bun needed); .ts ships
+        // beside it as the readable source. hooks.json is for plugin installs.
+        if (!/\.(ts|js|json)$/.test(f)) continue;
         const dst = join(root, 'hooks', f);
         if (!existsSync(dst)) {
           mkdirSync(dirname(dst), { recursive: true });
@@ -66,6 +190,15 @@ export const target: Target = {
           written.push(dst);
         }
       }
+      // The Stop hook shells out to savepoint.sh, resolved beside its own
+      // directory. A plugin install already has <plugin>/scripts/; a CLI
+      // install needs the shell scripts copied next to the hooks or the hook
+      // finds nothing and mission state stays empty — the exact bug this
+      // whole path exists to fix.
+      written.push(...copyScripts(join(root, 'scripts')));
+      const wired = wireSettings(root, join(root, 'hooks'));
+      written.push(...wired.written);
+      notes.push(...wired.notes);
     }
     // Port the /mugiwara commands into the installed .claude dir.
     if (existsSync(COMMANDS_SRC)) {
@@ -81,4 +214,9 @@ export const target: Target = {
     }
     return { written, notes };
   },
+  postUninstall({ scope, projectDir, home, dryRun }) {
+    if (dryRun) return { changed: [], notes: [] };
+    const root = scope === 'global' ? join(home, '.claude') : join(projectDir, '.claude');
+    return unwireSettings(root);
+  },
 };

package/src/targets/copilot.ts

@@ -12,10 +12,29 @@ export const target: Target = {
     const root = scope === 'global' ? join(home, '.copilot') : join(projectDir, '.github');
     return { skillsDir: join(root, 'instructions'), agentsDir: join(root, 'agents') };
   },
+  // Copilot injects EVERY matching instruction file into EVERY request — so
+  // the full corpus (26 files, ~27k tokens) was per-request cost, not
+  // per-session. Ship a routing stub here and park the full body in the
+  // per-skill refs dir, which the agent reads on demand. applyTo stays '**/*'
+  // so the routing line is always present; it is a few lines, not a skill.
   transformSkill(data: FrontmatterData, body: string) {
+    void body;
     return {
       relPath: `${data.name}.instructions.md`,
-      text: stringifyFrontmatter({ description: data.description, applyTo: '**/*' }, body),
+      text: stringifyFrontmatter(
+        { description: data.description, applyTo: '**/*' },
+        `# ${data.name}
+
+> ${data.description}
+
+Full skill: read \`.mugiwara/refs/${data.name}/${data.name}.md\` when the crew invokes this role.`,
+      ),
+    };
+  },
+  transformSkillFull(data: FrontmatterData, body: string) {
+    return {
+      relPath: `${data.name}.md`,
+      text: stringifyFrontmatter({ description: data.description }, body),
     };
   },
   transformAgent(data: FrontmatterData, body: string) {

package/src/targets/generic.ts

@@ -31,7 +31,7 @@ export function makeGeneric(opts: {
         // tokens at session start. The agent reads the full file on demand.
         return {
           relPath: `${data.name}.md`,
-          text: `# ${data.name}\n\n> ${data.description}\n\n## Skip when\n\nFull skill: \`${data.name}\` — read \`.mugiwara/refs/${data.name}.md\` when the crew invokes this role.`,
+          text: `# ${data.name}\n\n> ${data.description}\n\n## Skip when\n\nFull skill: \`${data.name}\` — read \`.mugiwara/refs/${data.name}/${data.name}.md\` when the crew invokes this role.`,
         };
       }
       return { relPath: `${data.name}.md`, text: `# ${data.name}\n\n> ${data.description}\n\n${body}` };
@@ -44,7 +44,7 @@ export function makeGeneric(opts: {
       if (stubOnly) {
         return {
           relPath: `agent-${data.name}.md`,
-          text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills: ${data.skills ?? ''}. Read \`.mugiwara/refs/${data.name}.md\` when embodying this role.\n\nOnly zoro-execution and brook-healing may modify source code.\nReturn your output to luffy-orchestrator; do not choose the next step.`,
+          text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills: ${data.skills ?? ''}. Read \`.mugiwara/refs/${data.name}/${data.name}.md\` when embodying this role.\n\nOnly zoro-execution and brook-healing may modify source code.\nReturn your output to luffy-orchestrator; do not choose the next step.`,
         };
       }
       return { relPath: `agent-${data.name}.md`, text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills used: ${data.skills ?? ''}\n\n${body}` };
@@ -53,10 +53,15 @@ export function makeGeneric(opts: {
       if (!stubOnly) return null;
       return { relPath: `${data.name}.md`, text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills used: ${data.skills ?? ''}\n\n${body}` };
     },
-    refsDir({ projectDir }: { scope: Scope; projectDir: string; home: string }) {
+    refsDir({ projectDir }: { scope: Scope; projectDir: string; home: string }, skillName: string) {
       // Keep reference detail outside the rules dir so the harness never
       // glob-loads it; the skill names the path and the agent reads on demand.
-      return join(projectDir, '.mugiwara', 'refs');
+      // Per-skill subdir is load-bearing, not tidiness: a flat refs dir let
+      // same-named references collide (agent-security/checklist.md vs
+      // frontend/checklist.md, contract-first/process.md vs
+      // root-cause/process.md) and first-writer-wins silently served the
+      // wrong document to the skill that asked for it.
+      return join(projectDir, '.mugiwara', 'refs', skillName);
     },
     postInstall({ projectDir, dryRun }) {
       if (!bootstrapFile) return { written: [], notes: [] };

package/src/targets/opencode.ts

@@ -33,7 +33,6 @@ const CREW: Record<string, CrewConfig> = {
   'eval-runner': { color: '#14b8a6', temperature: 0.2, steps: 15 },
   'resume-coordinator': { color: '#d97706', temperature: 0.2, steps: 10 },
   'memory-keeper': { color: '#d946ef', temperature: 0.2, steps: 8 },
-  'onboarding-guide': { color: '#0ea5e9', temperature: 0.3, steps: 15 },
 };
 
 // Crew colors from the wave-banners table (single source of truth). Returns

package/content/agents/onboarding-guide.md

@@ -1,124 +0,0 @@
----
-name: onboarding-guide
-description: Persona for using-mugiwara. Onboarding wizard: host-native question flow, writes config only. No network.
-skills: using-mugiwara, mugiwara-orchestration
-write-scope: artifacts
-permissions: read-only
----
-# Onboarding Guide
-## Role
-
-Runs the onboarding wizard via host-native question tool (opencode `question`,
-Claude Code `AskUserQuestion`, Copilot `askQuestion` when present), or plain
-conversation otherwise. Writes `.mugiwara/config` only. No network. First-run
-specialist; knows the full config surface, explains each option inline.
-Dispatched by `/mugiwara onboard`, first-run detection, or re-onboard reset.
-
-## Rules
-
-1. Never modify the questions — fixed and validated (9 questions).
-2. Never skip a question; all 9 answered before writing config.
-3. Host question tool when present (opencode `question`, Claude Code `AskUserQuestion`,
-   Copilot `askQuestion`): one per call, options + free-type, next-next until done.
-   No tool → conversation: numbered choices + "type your own answer".
-4. Write `.mugiwara/config` only after all 9 answers. Never write
-   `.mugiwara/onboard.json`; delete a stale copy if one exists.
-5. Print a config summary after completion so user can verify.
-6. All prompts static — no network, no LLM-generated questions.
-7. CLI users: point to `bun scripts/onboard.ts` (terminal wizard for non-interactive hosts).
-
-## The 9 Questions
-
-### Phase 1: Project Context
-
-**Q1 — Project type:**
-```
-[1] Web application
-[2] Mobile application
-[3] CLI tool
-[4] Library/SDK
-[5] Backend service / API
-[6] Other
-```
-
-**Q2 — Primary language:**
-```
-[1] TypeScript
-[2] JavaScript
-[3] Python
-[4] Go
-[5] Rust
-[6] Java
-[7] Other
-```
-
-**Q3 — Team size:**
-```
-[1] Solo
-[2] 2–5
-[3] 6–15
-[4] 16+
-```
-
-**Q4 — Git workflow:**
-```
-[1] Trunk-based (feature/{type}-{issue}-{slug})
-[2] GitFlow (feature/{slug})
-[3] GitHub Flow (feat/{slug})
-[4] Other (feature/{slug})
-```
-
-**Q5 — CI/CD platform:**
-```
-[1] GitHub Actions
-[2] GitLab CI
-[3] CircleCI
-[4] Jenkins
-[5] None / manual
-[6] Other
-```
-
-### Phase 2: Mugiwara Preferences
-
-**Q6 — Autonomy mode:**
-```
-[1] guided — ask before every wave transition
-[2] semi — auto-advance through waves, pause on failures
-[3] auto — full auto-pilot
-```
-
-**Q7 — Code review depth:**
-```
-[1] full — breaking-change map, five-axis review, ≤3 cycles
-[2] standard — five-axis review, 1 cycle
-[3] quick — diff-only, no caller-map
-```
-
-**Q8 — Quality check depth:**
-```
-[1] full — format, lint, typecheck, test, build
-[2] standard — lint, typecheck, test
-[3] quick — test only
-```
-
-**Q9 — Test coverage threshold:**
-```
-[1] 90/80 — new code 90%, modified 80%
-[2] 80/70 — new code 80%, modified 70%
-[3] custom — enter your own values
-[4] none — 0/0, no coverage enforcement
-```
-## Output
-
-After all 9 answers: write `.mugiwara/config` (mode, branch, coverage,
-review_depth, quality_depth). Commit style defaults to `conventional`; CLI
-wizard (`bun scripts/onboard.ts`) also writes `commit` and can set a
-custom style. Print a summary of chosen values before exit.
-
-## Before you start
-
-Dispatched by Luffy only; check `.mugiwara/logs/` routing log, existing config, confirm project root with Luffy.
-
-## Return to Luffy
-
-Report: config written with timestamp, all 9 answers, warnings (custom coverage). Luffy uses this for wave 0 routing.