@ionivetech/mugiwara 0.5.1 → 0.5.3

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "mugiwara",
+  "interface": {
+    "displayName": "Mugiwara"
+  },
+  "plugins": [
+    {
+      "name": "mugiwara",
+      "source": {
+        "source": "url",
+        "url": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "mugiwara",
+  "owner": {
+    "name": "ionive"
+  },
+  "metadata": {
+    "description": "The Straw Hat crew for AI agents",
+    "version": "0.5.3"
+  },
+  "plugins": [
+    {
+      "name": "mugiwara",
+      "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, healing.",
+      "version": "0.5.3",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,64 @@
+{
+  "name": "mugiwara",
+  "displayName": "Mugiwara",
+  "version": "0.5.3",
+  "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, healing.",
+  "author": {
+    "name": "ionive"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ionivetech/mugiwara",
+  "repository": "https://github.com/ionivetech/mugiwara",
+  "keywords": [
+    "agents",
+    "skills",
+    "workflow",
+    "multi-agent"
+  ],
+  "metadata": {
+    "agents": [
+      "luffy-orchestrator",
+      "usopp-brainstorm",
+      "nami-planner",
+      "zoro-execution",
+      "chopper-checkpoint",
+      "sanji-quality",
+      "franky-gates",
+      "robin-reviewer",
+      "jinbe-security",
+      "brook-healing",
+      "skeptic-verifier",
+      "eval-runner",
+      "resume-coordinator",
+      "memory-keeper"
+    ],
+    "skills": [
+      "mugiwara-agent-security",
+      "mugiwara-backend",
+      "mugiwara-brainstorm",
+      "mugiwara-checkpoint",
+      "mugiwara-claim-audit",
+      "mugiwara-context-budget",
+      "mugiwara-contract-first",
+      "mugiwara-execution",
+      "mugiwara-frontend",
+      "mugiwara-gates",
+      "mugiwara-git",
+      "mugiwara-healing",
+      "mugiwara-lessons",
+      "mugiwara-orchestration",
+      "mugiwara-planning",
+      "mugiwara-pr",
+      "mugiwara-quality",
+      "mugiwara-resume",
+      "mugiwara-review",
+      "mugiwara-root-cause",
+      "mugiwara-security",
+      "mugiwara-ship",
+      "mugiwara-sunset",
+      "mugiwara-testcases",
+      "mugiwara-workflow",
+      "using-mugiwara"
+    ]
+  }
+}

package/.claude-plugin/sync.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+# content/ is the single source of truth. Root agents/ and skills/ are
+# symlinks to it so the Claude Code marketplace plugin (which reads from the
+# plugin root) and the npm package consumers see the same files.
+set -eu
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+
+for pair in "agents:content/agents" "skills:content/skills"; do
+  link="${pair%%:*}"
+  target="${pair#*:}"
+  if [ -L "$ROOT/$link" ]; then
+    echo "ok $link -> $target"
+  else
+    rm -rf "$ROOT/$link"
+    ln -s "$target" "$ROOT/$link"
+    echo "linked $link -> $target"
+  fi
+done

package/.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "mugiwara",
+  "version": "0.5.3",
+  "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, healing.",
+  "author": {
+    "name": "ionive"
+  },
+  "homepage": "https://github.com/ionivetech/mugiwara",
+  "repository": "https://github.com/ionivetech/mugiwara",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "skills",
+    "workflow",
+    "multi-agent"
+  ],
+  "skills": "./content/skills/"
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "mugiwara",
+  "displayName": "Mugiwara",
+  "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, healing.",
+  "version": "0.5.3",
+  "author": {
+    "name": "ionive"
+  },
+  "homepage": "https://github.com/ionivetech/mugiwara",
+  "repository": "https://github.com/ionivetech/mugiwara",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "skills",
+    "workflow",
+    "multi-agent"
+  ],
+  "skills": "./content/skills/"
+}

package/.kimi-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "mugiwara",
+  "version": "0.5.3",
+  "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, healing.",
+  "author": {
+    "name": "ionive"
+  },
+  "homepage": "https://github.com/ionivetech/mugiwara",
+  "repository": "https://github.com/ionivetech/mugiwara",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "skills",
+    "workflow",
+    "multi-agent"
+  ],
+  "skills": "./content/skills/"
+}

package/.opencode/commands/mugiwara.md

@@ -1,11 +1,17 @@
 ---
-description: Run the mugiwara crew workflow for a task
+description: Run the mugiwara crew workflow or switch runtime mode (guided | semi | auto)
 ---
-Mugiwara workflow:
+Mugiwara mode: $ARGUMENTS
 
-1. The crew runs inline in the main conversation. Start any non-trivial task through `using-mugiwara` (embodied inline) to route to the right crew member.
-2. The pipeline flows: Luffy triage -> Usopp brainstorm (when needed) -> Nami planning -> Zoro execution -> Chopper checkpoint -> Sanji quality -> Franky gates -> Robin/Jinbe review -> Brook healing -> Luffy closure.
-3. Subagents are used only for parallel work (Zoro's [PARALLEL] workers, Robin + Jinbe concurrent review, independent re-run checks).
-4. Switch runtime mode with `/mugiwara-mode` (guided | semi | auto). Default is guided.
+Run the crew pipeline inline. To switch autonomy mode:
 
-See skills/mugiwara-workflow for the full pipeline.
+```
+/mugiwara guided    # human decides every GO
+/mugiwara semi      # auto branch + commit, plan needs GO
+/mugiwara auto      # hands-off except high-risk
+/mugiwara           # show current mode
+```
+
+The flip applies from the next wave. Valid modes: guided, semi, auto.
+
+For workflow: embody `using-mugiwara` inline to classify and route. See skills/mugiwara-workflow for the full pipeline.

package/.opencode/commands/using-mugiwara.md

@@ -0,0 +1,26 @@
+---
+description: Front-door router: explain how mugiwara works, classify a mission, or route to the right crew member
+---
+Using Mugiwara: $ARGUMENTS
+
+Mugiwara crew available. The workflow auto-activates for non-trivial requests.
+
+## How it works
+
+- 14 agents: Luffy (triage), Usopp (brainstorm), Nami (plan), Zoro (execute), Chopper (audit), Sanji (quality), Franky (gates), Robin (review), Jinbe (security), Brook (heal), Skeptic (verify), Eval Runner, Resume, Memory
+- 26 skills — one per crew role + domain skills (frontend, backend, git, security)
+- 9-wave pipeline runs inline in the main conversation
+- Evidence over claims at every wave
+- Autonomy modes: guided, semi, auto
+
+## What to do
+
+1. If the user asks how mugiwara works — summarize in 3 lines.
+2. If the user gives a task — classify (Trivial/Explicit/Exploratory/Open-ended/Ambiguous) and route:
+   - Clear, small → route to nami-planner or zoro-execution directly.
+   - Vague, needs direction → route to usopp-brainstorm.
+   - Anything else → route to luffy-orchestrator (full triage).
+   - Specialized: review → robin-reviewer, security → jinbe-security, etc.
+3. Record the route in `.mugiwara/logs/`.
+
+Skills: mugiwara-workflow, mugiwara-orchestration. See skills/mugiwara-workflow for the full pipeline.

package/.opencode/plugins/mugiwara-helpers.mjs

@@ -0,0 +1,90 @@
+// mugiwara helpers — extracted from mugiwara.mjs so the plugin module has a
+// single export. OpenCode's legacy loader calls every exported function as a
+// plugin; keeping helpers in a separate module avoids them being invoked with
+// the plugin context as first argument (same pattern ponytail uses).
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync, lstatSync, renameSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const VALID_MODES = new Set(['guided', 'semi', 'auto']);
+
+export function readMode({ projectDir = process.cwd(), home = homedir() } = {}) {
+  const readValue = (dir) => {
+    const file = join(dir, '.mugiwara', 'config');
+    if (!existsSync(file)) return undefined;
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t || t.startsWith('#')) continue;
+      const [k, v] = line.split('=').map((s) => s.trim());
+      if (k !== 'mode') continue;
+      return VALID_MODES.has(v) ? v : 'INVALID';
+    }
+    return undefined;
+  };
+  const proj = readValue(projectDir);
+  if (proj === 'INVALID') return 'guided';
+  if (proj) return proj;
+  const glob = readValue(home);
+  if (glob === 'INVALID') return 'guided';
+  if (glob) return glob;
+  return 'guided';
+}
+
+export function parseModeChange(promptRaw) {
+  if (typeof promptRaw !== 'string') return null;
+  let prompt = promptRaw.trim();
+  const wrapped = /^(["'`])([\s\S]*)\1$/.exec(prompt);
+  if (wrapped) prompt = wrapped[2].trim();
+  prompt = prompt.toLowerCase();
+  if (!prompt) return null;
+
+  const tplSet = /^(?:set |)mugiwara mode:[ \t]*(\S*)/.exec(prompt);
+  if (tplSet && VALID_MODES.has(tplSet[1])) return tplSet[1];
+
+  const slash = /^\/(?:mugiwara[-\s]?)?mode[ \t]+(\S*)/.exec(prompt);
+  if (slash && VALID_MODES.has(slash[1])) return slash[1];
+
+  const slashMain = /^\/mugiwara[ \t]+(\S*)/.exec(prompt);
+  if (slashMain && VALID_MODES.has(slashMain[1])) return slashMain[1];
+
+  const natural = /^mugiwara mode[ \t]+(\S*)/.exec(prompt);
+  if (natural && VALID_MODES.has(natural[1])) return natural[1];
+
+  return null;
+}
+
+function assertNotSymlink(file) {
+  if (!existsSync(file)) return;
+  try {
+    const st = lstatSync(file);
+    if (st.isSymbolicLink()) throw new Error(`refusing to follow symlink: ${file}`);
+  } catch (e) {
+    if (e.code === 'ENOENT') return;
+    throw e;
+  }
+}
+
+export function applyModeChange(mode, { projectDir = process.cwd(), home = homedir() } = {}) {
+  if (!VALID_MODES.has(mode)) return;
+  const dir = join(projectDir, '.mugiwara');
+  const file = join(dir, 'config');
+  assertNotSymlink(file);
+  mkdirSync(dir, { recursive: true });
+  const lines = [];
+  if (existsSync(file)) {
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+      const t = line.trim();
+      if (t.startsWith('mode=')) continue;
+      lines.push(line);
+    }
+  }
+  lines.push(`mode=${mode}`);
+  const body = lines.filter((l, i) => !(l === '' && (i === lines.length - 1 || i === 0))).join('\n') + '\n';
+  const tmp = join(tmpdir(), `mugiwara-config-${process.pid}-${Date.now()}.tmp`);
+  writeFileSync(tmp, body);
+  renameSync(tmp, file);
+  const log = join(dir, 'logs', `${new Date().toISOString().slice(0, 10)}-mode-flip.md`);
+  mkdirSync(dirname(log), { recursive: true });
+  appendFileSync(log, `| ${new Date().toISOString()} | mode flip | guided/semi/auto -> ${mode} | user |\n`);
+}

package/.opencode/plugins/mugiwara.mjs

@@ -1,59 +1,31 @@
 // mugiwara — OpenCode plugin.
 //
-// Registers the Mugiwara crew (25 skills + 15 agents) with OpenCode from the
-// npm/git package, and announces the crew at session start. No runtime, no
-// deps — reads the markdown source of truth (content/) at config load.
+// Registers skills/agents via config hook (superpowers pattern: one plugin,
+// zero file-copy), announces the crew at session start, and handles runtime
+// mode switching. Helpers live in mugiwara-helpers.mjs — this module has a
+// single export because OpenCode's legacy loader calls every exported function
+// as a plugin (same constraint ponytail documents).
 //
 // Install: add to opencode.json
 //   { "plugin": ["@ionivetech/mugiwara"] }
 // or from the git repo:
 //   { "plugin": ["mugiwara@git+https://github.com/ionivetech/mugiwara.git"] }
 
-import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, appendFileSync, lstatSync, renameSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readMode, parseModeChange, applyModeChange } from './mugiwara-helpers.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const VALID_MODES = new Set(['guided', 'semi', 'auto']);
-
-// Read the runtime mode: `.mugiwara/config` (project) wins over
-// `~/.mugiwara/config` (global) per key; a missing key or a value outside the
-// enum falls back to `guided`. Never creates files on read.
-export function readMode({ projectDir = process.cwd(), home = homedir() } = {}) {
-  const readValue = (dir) => {
-    const file = join(dir, '.mugiwara', 'config');
-    if (!existsSync(file)) return undefined;
-    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
-      const t = line.trim();
-      if (!t || t.startsWith('#')) continue;
-      const [k, v] = t.split('=').map((s) => s.trim());
-      if (k !== 'mode') continue;
-      return VALID_MODES.has(v) ? v : 'INVALID';
-    }
-    return undefined;
-  };
-  const proj = readValue(projectDir);
-  if (proj === 'INVALID') return 'guided';
-  if (proj) return proj;
-  const glob = readValue(home);
-  if (glob === 'INVALID') return 'guided';
-  if (glob) return glob;
-  return 'guided';
-}
-
 const contentDir = join(__dirname, '..', '..', 'content');
 const skillsDir = join(contentDir, 'skills');
 const agentsDir = join(contentDir, 'agents');
 
 const ANNOUNCE =
-  "Mugiwara crew available. The workflow auto-activates for non-trivial requests — no need to call `/using-mugiwara` at session start (it remains an optional router). Run the crew pipeline inline in the main conversation: embody ONE crew role at a time using its skill, wait for its report, then move to the next. Never Task-dispatch a crew member — the crew runs in the main thread; subagents only for [PARALLEL] task batches, concurrent review/security, and independent re-run checks. Progress shows as checkpoint reports at wave/stage boundaries, pausing on failure or risk. Switch mode with `/mugiwara-mode` (guided|semi|auto). See skills/mugiwara-workflow.";
+  "Mugiwara crew available. The workflow auto-activates for non-trivial requests — no need to call `/using-mugiwara` at session start (it is an optional router). Run the crew pipeline inline in the main conversation: embody ONE crew role at a time using its skill, wait for its report, then move to the next. Never Task-dispatch a crew member — the crew runs in the main thread; subagents only for [PARALLEL] task batches, concurrent review/security, and independent re-run checks. Progress shows as checkpoint reports at wave/stage boundaries, pausing on failure or risk. Switch mode with `/mugiwara` (guided|semi|auto). See skills/mugiwara-workflow.";
 
-// OpenCode per-agent tuning. Content stays portable markdown; these knobs
-// (color, temperature, permission, steps) are opencode-only.
 const CREW = {
-  'using-mugiwara': { color: '#84cc16', temperature: 0.2, steps: 10 },
   'luffy-orchestrator': { color: '#ef4444', temperature: 0.2, steps: 15 },
   'usopp-brainstorm': { color: '#f59e0b', temperature: 0.6, steps: 15 },
   'nami-planner': { color: '#f97316', temperature: 0.2, steps: 15 },
@@ -106,73 +78,9 @@ function readAgents() {
   return agents;
 }
 
-// Parse a user prompt for a mugiwara mode change. Returns the new mode or null.
-// Mirrors the caveman plugin pattern: opencode expands `/mugiwara-mode <level>`
-// into the command file's body ("Set mugiwara mode: <level>...") before
-// chat.message fires, so parse the template's first line too. The slash command
-// and natural-language phrase must sit at the START of the prompt — a bare
-// mention mid-message (pasted untrusted content) never flips autonomy.
-export function parseModeChange(promptRaw) {
-  if (typeof promptRaw !== 'string') return null;
-  let prompt = promptRaw.trim();
-  const wrapped = /^(["'`])([\s\S]*)\1$/.exec(prompt);
-  if (wrapped) prompt = wrapped[2].trim();
-  prompt = prompt.toLowerCase();
-  if (!prompt) return null;
-
-  const tpl = /^set mugiwara mode:[ \t]*(\S*)/.exec(prompt);
-  if (tpl && VALID_MODES.has(tpl[1])) return tpl[1];
-
-  const slash = /^\/(mugiwara[-\s]?)mode[ \t]+(\S*)/.exec(prompt);
-  if (slash && VALID_MODES.has(slash[2])) return slash[2];
-
-  const natural = /^mugiwara mode[ \t]+(\S*)/.exec(prompt);
-  if (natural && VALID_MODES.has(natural[1])) return natural[1];
-
-  return null;
-}
-
-// Refuse to follow a symlinked .mugiwara/config — a malicious repo could point
-// it at ~/.bashrc and any mode flip would overwrite the target.
-function assertNotSymlink(file) {
-  if (!existsSync(file)) return;
-  try {
-    const st = lstatSync(file);
-    if (st.isSymbolicLink()) throw new Error(`refusing to follow symlink: ${file}`);
-  } catch (e) {
-    if (e.code === 'ENOENT') return;
-    throw e;
-  }
-}
-
-// Write `.mugiwara/config` (project) and append a decision-log row.
-// Atomic: write a temp file next to the target, then rename over it, so a
-// crash mid-write never truncates the config (keeps branch/commit keys).
-export function applyModeChange(mode, { projectDir = process.cwd(), home = homedir() } = {}) {
-  if (!VALID_MODES.has(mode)) return;
-  const dir = join(projectDir, '.mugiwara');
-  const file = join(dir, 'config');
-  assertNotSymlink(file);
-  mkdirSync(dir, { recursive: true });
-  const lines = [];
-  if (existsSync(file)) {
-    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
-      const t = line.trim();
-      if (t.startsWith('mode=')) continue;
-      lines.push(line);
-    }
-  }
-  lines.push(`mode=${mode}`);
-  const body = lines.filter((l, i) => !(l === '' && (i === lines.length - 1 || i === 0))).join('\n') + '\n';
-  const tmp = join(tmpdir(), `mugiwara-config-${process.pid}-${Date.now()}.tmp`);
-  writeFileSync(tmp, body);
-  renameSync(tmp, file);
-  const log = join(dir, 'logs', `${new Date().toISOString().slice(0, 10)}-mode-flip.md`);
-  mkdirSync(dirname(log), { recursive: true });
-  appendFileSync(log, `| ${new Date().toISOString()} | mode flip | guided/semi/auto -> ${mode} | user |\n`);
-}
-
 export default async () => ({
+  dispose: () => {},
+
   config: (config) => {
     config.skills = config.skills || {};
     config.skills.paths = config.skills.paths || [];
@@ -185,8 +93,6 @@ export default async () => ({
     }
   },
 
-  // Intercept user messages to detect `/mugiwara-mode` and natural-language
-  // mode toggles; write `.mugiwara/config` so the next wave reads the new level.
   'chat.message': async (_input, output) => {
     if (!output) return;
     if (typeof output === 'string') {
@@ -204,9 +110,6 @@ export default async () => ({
     }
   },
 
-  // ponytail-proven hook; appends the announce string to the system prompt.
-  // Dedupes: repeated transforms (model switch/compaction) must not grow the
-  // prompt unbounded — only append once per string content.
   'experimental.chat.system.transform': async (_input, output) => {
     if (!output.system.some((s) => s.includes('Mugiwara crew available'))) {
       if (output.system.length > 0) {

package/AGENTS.md

@@ -0,0 +1,183 @@
+# Mugiwara Development Standards
+
+Rules for working on this repo. Follow these or validation fails.
+
+## Language
+
+**All files must be English.** Skills, agents, docs, scripts, references — no
+exceptions. Comments in source code should be English. This conversation is the
+only place Indonesian is acceptable.
+
+## Trunk-based branching strategy
+
+`main` is always stable and releasable. No commits directly to `main`.
+
+| Branch | Purpose | Lifetime |
+|--------|---------|----------|
+| `main` | Source of truth. Always passes CI. | Permanent |
+| `feat/*`, `fix/*`, `chore/*`, `docs/*`, `refactor/*` | Feature work from main, PR to main | Short-lived, delete after merge |
+| `release/vX.Y.Z` | Created from main for publishing. Archival. | Short-lived, delete after tag |
+
+### Flow
+
+1. Branch from `main`
+2. Work + validate locally
+3. PR to `main` — CI must pass (all gates)
+4. Merge to `main`
+5. Run "Manual Release" workflow on GitHub Actions → creates tag + npm publish + GitHub Release
+6. Release branch (`release/vX.Y.Z`) created from the release commit — archival
+
+### Branch naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Feature | `feat/<description>` | `feat/add-mcp-audit-skill` |
+| Fix | `fix/<description>` | `fix/token-budget-overflow` |
+| Chore | `chore/<description>` | `chore/update-deps` |
+| Docs | `docs/<description>` | `docs/rewrite-readme` |
+| Refactor | `refactor/<description>` | `refactor/split-checkpoint` |
+| Release | `release/vX.Y.Z` | `release/v0.5.0` |
+
+### Version bumping
+
+| Trigger | Bump |
+|---------|------|
+| Bug fix, no new features | `patch` |
+| New feature, backward-compatible | `minor` |
+| Breaking change | `major` |
+
+All version bumps via the Manual Release workflow — never manually edited.
+
+## Validation before commit (CI gates)
+
+All must pass on every PR. Run locally with:
+
+```bash
+bun run gate     # everything CI runs on a PR
+```
+
+### Per-PR gates
+
+```bash
+bun run typecheck                                              # TypeScript
+bun run test                                                   # 70 tests
+bun run build                                                  # dist/
+bun scripts/validate-content.ts --check-manifest --check-docs  # content + manifest + docs drift + budget + section length + description hygiene
+bun scripts/run-evals.ts                                       # behavioral evals
+bun scripts/retrieval-eval.ts                                  # retrieval ranking + floor ratchet
+bun scripts/verify-install.ts                                  # G1: resolve all references/*.md pointers after install
+```
+
+### Pre-release / weekly gates
+
+| Gate | Script | Purpose |
+|------|--------|---------|
+| G3 meta-eval | `bun scripts/gate-selftest.ts` | Prove every gate can fail — catch rotted gates |
+
+### Where each gate runs
+
+| Gate | Pre-commit | Every PR | Pre-release | Weekly |
+|------|:---:|:---:|:---:|:---:|
+| typecheck, test, build | ✅ | ✅ | ✅ | |
+| validate-content (+manifest, docs, sections, descriptions) | ✅ | ✅ | ✅ | |
+| run-evals | | ✅ | ✅ | |
+| retrieval-eval + ratchet | | ✅ | ✅ | |
+| **G1 verify-install** | | ✅ | ✅ | |
+| **G2 computed fixtures** | ✅ | ✅ | ✅ | |
+| **G3 gate-selftest** | | | ✅ | ✅ |
+
+### Gate design
+
+**A gate that cannot fail is not a gate.** Every gate must have a corresponding
+mutation in `scripts/gate-selftest.ts` proving it goes red. Adding a gate
+without adding its mutation is an incomplete change.
+
+**Every production defect adds a gate before the fix merges.** Record the defect
+class, not just the instance. The fix closes one instance — the gate closes the
+class.
+
+No PR merges without all green CI.
+
+## Skill standards
+
+Every skill is `content/skills/<name>/SKILL.md`:
+
+| Rule | Limit | Validated |
+|------|-------|:---:|
+| Frontmatter `name` matches directory | exact match | ✅ |
+| `description` length | 20–220 chars | ✅ |
+| `description` content | trigger keywords + disambiguators only, no procedure | ✅ |
+| Body lines | ≤120 | ✅ |
+| `## Skip when` block | 1–4 bullets, numeric threshold | ✅ |
+| Sections >15–20 lines | move to `references/<topic>.md`, one-line pointer in body | ✅ |
+| Language | **English only** | ✅ |
+
+## Agent standards
+
+Every agent is `content/agents/<name>.md`:
+
+| Rule | Requirement |
+|------|------------|
+| Frontmatter `name` matches filename | exact match (without `.md`) |
+| `description` | pointer line: "Persona for <skill>. <role summary>." |
+| `skills` | list of held skills, comma-separated |
+| `permissions` | optional: `read-only`, `can-write`, `no-network` |
+| Language | **English only** |
+
+## Reference files
+
+Two locations:
+- `references/` — shared, linked from multiple skills. Installed to `_shared/references/` (tier 1) or `.mugiwara/refs/_shared/` (tier 2/3).
+- `content/skills/<name>/references/` — skill-specific
+
+Any `references/*.md` pointer in a skill body must resolve **after install**,
+verified by `scripts/verify-install.ts`. A pointer correct in the repo but
+broken after install is a defect, not a docs nit.
+
+Body → one-line pointer: "Full checklist: `references/checklist.md` — 37 items;
+unchecked boxes are not done." Never just a bare filename.
+
+## State fields
+
+`state.json` is the audit trail. Every field in `state.json` is computed, never
+model-supplied. Every field has a fixture assertion in `test/savepoint.test.ts`
+with a non-trivial expected value. A field that can silently read `0` is worse
+than an absent field — absence is visible, a wrong zero is not.
+
+## Index budget
+
+Combined skill + agent description chars must be ≤5500. Enforced by validator.
+Trimming descriptions = always drop procedure, keep trigger vocabulary.
+
+## Manifest sync
+
+`.claude-plugin/plugin.json` `metadata.skills` and `metadata.agents` must
+set-equal `content/skills/` and `content/agents/`. Enforced by
+`--check-manifest`. If you add/remove/rename a skill or agent, update the
+manifest.
+
+## Docs drift
+
+`docs/skills.md` must mention every skill directory. `docs/agents.md` must
+mention every agent file. Enforced by `--check-docs`.
+
+## Skill count
+
+26 is the ceiling. A new skill replaces an old one — never add to grow.
+
+## Commit style
+
+Conventional Commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.
+
+## Directory map
+
+```
+content/skills/    — 26 skill dirs, each with SKILL.md + optional references/
+content/agents/    — 15 agent .md files
+references/         — shared reference files (definition-of-done, source-grounding, etc.)
+docs/               — user-facing documentation
+scripts/            — validation + tooling scripts
+src/                — CLI TypeScript source
+test/               — vitest tests
+evals/cases/        — eval case JSON files
+```