@mutagent/helix 0.1.0-alpha.14

package/.claude/skills/mutagent-helix/scripts/cli/init.ts

@@ -0,0 +1,382 @@
+/**
+ * scripts/cli/init.ts — @mutagent/helix installer.
+ * Invoked as:  pnpx @mutagent/helix init
+ *
+ * Installs the Helix conductor + the bundled lifecycle-stage skills
+ * (agentspec · diagnostics · evaluator) into the consumer's coding-agent config,
+ * and links CLAUDE.md / AGENTS.md so the host boots Helix.
+ *
+ * Mirrors the @mutagent/diagnostics init discipline:
+ *   - project-local install by DEFAULT (cwd/.claude); --global targets the home dir (W9-fix).
+ *   - the child runs in the USER's invocation dir (no cwd override in the launcher).
+ *   - offline + self-contained: every skill tree is bundled in this package, so init
+ *     copies from the package — no network, no peer-install.
+ *
+ * Flags:
+ *   --global   install into ~/.claude (default is <cwd>/.claude)
+ *   --yes      non-interactive (assume yes); reserved for future multi-platform prompts
+ *   --force    overwrite existing installed skill trees
+ *   --json     emit only the InitDescriptor JSON (no human summary)
+ *   --help     usage
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  cpSync,
+  readdirSync,
+  copyFileSync,
+  writeFileSync,
+  readFileSync,
+} from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { parseArgs } from "node:util";
+import { toCodexAgentToml } from "./codex-transcode.ts";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+type Scope = "project" | "global";
+
+interface SkillInstall {
+  name: string;
+  installed: boolean;
+  skillPath: string;
+  agentsCopied: number;
+}
+
+interface InitDescriptor {
+  package: "@mutagent/helix";
+  scope: Scope;
+  projectRoot: string;
+  claudeRoot: string;
+  skills: SkillInstall[];
+  claudeMdLinked: boolean;
+  agentsMdLinked: boolean;
+  codex: { skills: number; agents: number; skillsDir: string; agentsDir: string };
+  nextAction: "boot";
+  message: string;
+}
+
+// ── Package layout ──────────────────────────────────────────────────────────
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+// .../.claude/skills/mutagent-helix/scripts/cli → up 5 to the package root
+const PKG_ROOT = join(SCRIPT_DIR, "..", "..", "..", "..", "..");
+
+// The conductor skill + the lifecycle skills bundled in this package.
+// helix carries the conductor surface (orchestrator.md + routing.yaml) assembled in.
+const HELIX = "mutagent-helix";
+const LIFECYCLE_SKILLS = [
+  "mutagent-agentspec",
+  "mutagent-builder",
+  "mutagent-evaluator",
+  "mutagent-diagnostics",
+  "mutagent-optimize",
+] as const;
+
+// Source skill-tree path inside the package for a given skill name.
+function skillSrcDir(name: string): string {
+  return name === HELIX
+    ? join(PKG_ROOT, ".claude", "skills", HELIX)
+    : join(PKG_ROOT, name, ".claude", "skills", name);
+}
+
+// Never carry dev-internal surfaces into a consumer, even when init runs from the
+// repo (the published tarball is already scrubbed; this is defense-in-depth).
+const COPY_DENY = [
+  ".meta",
+  ".engineeringrules",
+  "internal",
+  "node_modules",
+  "__tests__",
+  "tests",
+  ".npmignore",
+  ".DS_Store",
+];
+function copyFilter(src: string): boolean {
+  const b = basename(src);
+  if (COPY_DENY.includes(b)) return false;
+  if (b.endsWith(".test.ts") || b.endsWith(".spec.ts")) return false;
+  return true;
+}
+
+// ── Install one skill tree + its agents ──────────────────────────────────────
+function installSkill(
+  name: string,
+  skillsDir: string,
+  agentsDir: string,
+  force: boolean
+): SkillInstall {
+  const src = skillSrcDir(name);
+  const dest = join(skillsDir, name);
+  const result: SkillInstall = {
+    name,
+    installed: false,
+    skillPath: dest,
+    agentsCopied: 0,
+  };
+  if (!existsSync(src)) {
+    console.error(`  ✗ ${name}: source not found in package (${src})`);
+    return result;
+  }
+  if (existsSync(dest) && !force) {
+    console.info(`  • ${name}: already installed (use --force to overwrite) → ${dest}`);
+  } else {
+    mkdirSync(skillsDir, { recursive: true });
+    cpSync(src, dest, { recursive: true, force: true, filter: copyFilter });
+  }
+  result.installed = existsSync(join(dest, "SKILL.md"));
+
+  // Agents: each skill ships its sub-agent contracts at assets/agents/*.md.
+  const agentsSrc = join(src, "assets", "agents");
+  if (existsSync(agentsSrc)) {
+    mkdirSync(agentsDir, { recursive: true });
+    for (const f of readdirSync(agentsSrc)) {
+      if (!f.endsWith(".md")) continue;
+      copyFileSync(join(agentsSrc, f), join(agentsDir, f));
+      result.agentsCopied++;
+    }
+  }
+  console.info(
+    `  ${result.installed ? "✓" : "✗"} ${name} → ${dest}` +
+      (result.agentsCopied ? ` (+${result.agentsCopied} agent${result.agentsCopied > 1 ? "s" : ""})` : "")
+  );
+  return result;
+}
+
+// Copy the orchestrator's deterministic engine scripts into the installed helix
+// skill so `orchestrator.md`'s `<helix-skill>/scripts/*.ts` references resolve
+// (the *sync indexer, render-roster, dispatch/gate, etc.). The engine lands
+// alongside the bundled `scripts/cli/` — cpSync MERGES, never clobbers cli/.
+// Runtime deps (@sinclair/typebox · yaml) are NOT installed here; if the engine
+// is invoked without them the orchestrator degrades to its in-prose path.
+function copyEngineScripts(helixDest: string): void {
+  const src = join(PKG_ROOT, "mutagent-orchestrator", "scripts");
+  if (!existsSync(src)) return;
+  cpSync(src, join(helixDest, "scripts"), { recursive: true, force: true, filter: copyFilter });
+}
+
+// Copy the orchestrator's user-facing reference docs (e.g. references/MONITORING.md
+// — the *dogfood + Slack-setup manual) into the installed helix skill so an operator
+// can read them LOCALLY (`<helix-skill>/references/…`). Same filter as the engine.
+function copyReferences(helixDest: string): void {
+  const src = join(PKG_ROOT, "mutagent-orchestrator", "references");
+  if (!existsSync(src)) return;
+  cpSync(src, join(helixDest, "references"), { recursive: true, force: true, filter: copyFilter });
+}
+
+// Assemble the conductor surface into the installed helix skill so it is
+// self-contained post-install (SKILL.md → ./orchestrator.md, ./routing.yaml,
+// ./scripts/*.ts engine).
+function assembleHelixConductor(skillsDir: string): void {
+  const dest = join(skillsDir, HELIX);
+  const pairs: Array<[string, string]> = [
+    [join(PKG_ROOT, "mutagent-orchestrator", "orchestrator.md"), join(dest, "orchestrator.md")],
+    [join(PKG_ROOT, "mutagent-orchestrator", "routing.yaml"), join(dest, "routing.yaml")],
+  ];
+  for (const [from, to] of pairs) {
+    if (existsSync(from)) copyFileSync(from, to);
+  }
+  copyEngineScripts(dest);
+  copyReferences(dest);
+}
+
+// ── CLAUDE.md / AGENTS.md linkage (non-destructive) ──────────────────────────
+const BOOT_MARKER = "<!-- @mutagent/helix boot -->";
+function helixBootBlock(orchestratorPath: string, extra = ""): string {
+  return `${BOOT_MARKER}
+# Helix — MutagenT ADL conductor
+
+This project has the Helix orchestrator installed. To boot it, read and adopt the agent
+definition at \`${orchestratorPath}\` (run its activation-instructions: persona → system index →
+ADL dashboard), then await a \`*command\`.
+
+Trigger: \`*mutagent\` · \`/mutagent-helix\` · \`boot\`.${extra}
+${BOOT_MARKER}
+`;
+}
+
+// Codex normalizes long output into concise Markdown; this forces literal template stamping.
+const CODEX_DASHBOARD_RULE = `
+
+DASHBOARD RENDERING — HARD RULE (Codex): on \`*mutagent\`/\`boot\`/\`*help\`/\`*status\`, output the
+orchestrator's \`help-display-template\` VERBATIM inside a fenced \`text\` code block. Preserve its
+EXACT shape — the boxed MUTAGENT header (box-drawing chars), every panel (lifecycle · system index ·
+setup/onboarding · state), and the command roster. Replace ONLY the \`{placeholder}\` tokens with
+live values; change NOTHING else. Do NOT summarize, shorten, paraphrase, drop panels, or convert it
+to Markdown headings/tables/bullets unless the operator explicitly asks for a condensed view.`;
+
+// Upsert the managed boot block: create the file, replace the marked block (so a
+// re-run updates routing), or append it — never clobber the user's other content.
+function upsertBootBlock(path: string, block: string): "created" | "updated" | "appended" {
+  if (!existsSync(path)) {
+    writeFileSync(path, block);
+    return "created";
+  }
+  const cur = readFileSync(path, "utf8");
+  const re = new RegExp(`${BOOT_MARKER}[\\s\\S]*?${BOOT_MARKER}\\n?`);
+  if (re.test(cur)) {
+    const next = cur.replace(re, block);
+    if (next !== cur) writeFileSync(path, next);
+    return "updated";
+  }
+  writeFileSync(path, cur.replace(/\s*$/, "") + "\n\n" + block);
+  return "appended";
+}
+
+function linkClaudeAgents(configRoot: string): { claudeMd: boolean; agentsMd: boolean } {
+  mkdirSync(configRoot, { recursive: true });
+  // Runtime-NATIVE boot routing: Claude reads CLAUDE.md → .claude/ ; Codex reads
+  // AGENTS.md → its native .agents/skills/ (+ the literal-dashboard hard rule).
+  const c = upsertBootBlock(
+    join(configRoot, "CLAUDE.md"),
+    helixBootBlock(".claude/skills/mutagent-helix/orchestrator.md")
+  );
+  const a = upsertBootBlock(
+    join(configRoot, "AGENTS.md"),
+    helixBootBlock(".agents/skills/mutagent-helix/orchestrator.md", CODEX_DASHBOARD_RULE)
+  );
+  console.info(`  ✓ CLAUDE.md (${c}) → .claude/skills/mutagent-helix/orchestrator.md`);
+  console.info(
+    `  ✓ AGENTS.md (${a}) → .agents/skills/mutagent-helix/orchestrator.md (+ Codex dashboard hard-rule)`
+  );
+  return { claudeMd: c !== "appended", agentsMd: a !== "appended" };
+}
+
+// ── Install for Codex (always PROJECT-LOCAL, in the dir init runs in) ─────────
+// Codex loads skills from `.agents/skills/` and auto-loads spawnable subagents
+// from project `.codex/agents/*.toml`. We write both: the skill trees (agents
+// ride along intact in assets/agents/) → .agents/skills/, AND each agent .md
+// transcoded to the correct FLAT Codex .toml → .codex/agents/.
+interface CodexInstall {
+  agentsSkillsDir: string;
+  codexAgentsDir: string;
+  skillsInstalled: number;
+  agentsTranscoded: number;
+}
+
+function installCodex(projectRoot: string, force: boolean): CodexInstall {
+  const agentsSkillsDir = join(projectRoot, ".agents", "skills"); // Codex native skill location
+  const codexAgentsDir = join(projectRoot, ".codex", "agents"); // Codex project custom agents
+  let skillsInstalled = 0;
+  let agentsTranscoded = 0;
+
+  // 1) Skills → .agents/skills/<name>/ (same tree, agents intact in assets/agents/)
+  mkdirSync(agentsSkillsDir, { recursive: true });
+  for (const name of [HELIX, ...LIFECYCLE_SKILLS]) {
+    const src = skillSrcDir(name);
+    if (!existsSync(src)) continue;
+    const dest = join(agentsSkillsDir, name);
+    if (!existsSync(dest) || force) {
+      cpSync(src, dest, { recursive: true, force: true, filter: copyFilter });
+    }
+    if (existsSync(join(dest, "SKILL.md"))) skillsInstalled++;
+  }
+  // assemble the conductor surface into the Codex helix skill too
+  const helixDest = join(agentsSkillsDir, HELIX);
+  for (const f of ["orchestrator.md", "routing.yaml"]) {
+    const from = join(PKG_ROOT, "mutagent-orchestrator", f);
+    if (existsSync(from)) copyFileSync(from, join(helixDest, f));
+  }
+  copyEngineScripts(helixDest);
+  copyReferences(helixDest);
+
+  // 2) Agents → .codex/agents/<name>.toml (flat Codex-native transcode, intact)
+  mkdirSync(codexAgentsDir, { recursive: true });
+  for (const name of LIFECYCLE_SKILLS) {
+    const agentsSrc = join(skillSrcDir(name), "assets", "agents");
+    if (!existsSync(agentsSrc)) continue;
+    for (const f of readdirSync(agentsSrc)) {
+      if (!f.endsWith(".md")) continue;
+      const toml = toCodexAgentToml(readFileSync(join(agentsSrc, f), "utf8"));
+      writeFileSync(join(codexAgentsDir, f.replace(/\.md$/, ".toml")), toml);
+      agentsTranscoded++;
+    }
+  }
+  console.info(
+    `  ✓ Codex → ${skillsInstalled} skills in .agents/skills/ · ${agentsTranscoded} agents in .codex/agents/*.toml`
+  );
+  return { agentsSkillsDir, codexAgentsDir, skillsInstalled, agentsTranscoded };
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+function main(): void {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      global: { type: "boolean", default: false },
+      yes: { type: "boolean", default: false },
+      force: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    console.info(
+      `pnpx @mutagent/helix init [--global] [--yes] [--force] [--json]\n` +
+        `  installs the Helix conductor + lifecycle skills (agentspec · builder · evaluator · diagnostics · optimize)\n` +
+        `  and links CLAUDE.md / AGENTS.md. Default scope is project-local (<cwd>/.claude).`
+    );
+    process.exit(0);
+  }
+
+  const scope: Scope = values.global ? "global" : "project";
+  const projectRoot = process.cwd();
+  const configRoot = scope === "global" ? join(homedir(), ".claude") : join(projectRoot, ".claude");
+  const skillsDir = join(configRoot, "skills");
+  const agentsDir = join(configRoot, "agents");
+
+  if (!values.json) {
+    console.info(`\n🧬 Installing @mutagent/helix (${scope}-scope) → ${configRoot}\n`);
+  }
+
+  const skills: SkillInstall[] = [];
+  // Conductor first, then the lifecycle skills.
+  skills.push(installSkill(HELIX, skillsDir, agentsDir, !!values.force));
+  assembleHelixConductor(skillsDir);
+  for (const name of LIFECYCLE_SKILLS) {
+    skills.push(installSkill(name, skillsDir, agentsDir, !!values.force));
+  }
+
+  // CLAUDE/AGENTS linkage lands at the config root (project: <cwd>; global: ~/.claude).
+  const linkRoot = scope === "global" ? configRoot : projectRoot;
+  const { claudeMd, agentsMd } = linkClaudeAgents(linkRoot);
+
+  // Codex install — ALWAYS, project-local (the dir init runs in), alongside Claude.
+  const codex = installCodex(projectRoot, !!values.force);
+
+  const installedCount = skills.filter((s) => s.installed).length;
+  const descriptor: InitDescriptor = {
+    package: "@mutagent/helix",
+    scope,
+    projectRoot,
+    claudeRoot: configRoot,
+    skills,
+    claudeMdLinked: claudeMd || existsSync(join(linkRoot, "CLAUDE.md")),
+    agentsMdLinked: agentsMd || existsSync(join(linkRoot, "AGENTS.md")),
+    codex: {
+      skills: codex.skillsInstalled,
+      agents: codex.agentsTranscoded,
+      skillsDir: codex.agentsSkillsDir,
+      agentsDir: codex.codexAgentsDir,
+    },
+    nextAction: "boot",
+    message:
+      `Installed ${installedCount}/${skills.length} skills (Claude: .claude/ · Codex: .agents/skills/ + ` +
+      `${codex.agentsTranscoded} agents in .codex/agents/). Boot via *mutagent (or /mutagent-helix).`,
+  };
+
+  if (values.json) {
+    console.log(JSON.stringify(descriptor, null, 2));
+  } else {
+    console.info(`\n✅ ${descriptor.message}\n`);
+  }
+
+  // Fail loud if the conductor itself did not install.
+  const helixOk = skills.find((s) => s.name === HELIX)?.installed === true;
+  process.exit(helixOk && installedCount > 0 ? 0 : 1);
+}
+
+main();

package/.claude/skills/mutagent-helix/scripts/cli/run.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# scripts/cli/run.sh — bun→pnpm→npm fallback selector + .sh dispatch (iter-7 T11, R-014-A)
+# Usage: scripts/cli/run.sh <script-path.{ts|sh}> [args...]
+#        scripts/cli/run.sh --selftest
+#
+# This wrapper provides consistent script invocation across operator environments.
+# All agent Bash() calls to TypeScript OR shell scripts MUST go through this wrapper:
+#   Bash("scripts/cli/run.sh scripts/tier0-scan.ts ...")
+#   Bash("scripts/cli/run.sh scripts/fetch/claude-code-transcripts.sh ...")
+#
+# Platform matrix — which tier fires when:
+#   Tier 1 (bun)      : bun is on PATH (local dev, mutagent CI, most operator installs)
+#   Tier 2 (pnpm-tsx) : bun absent, pnpm on PATH (corporate Node setups, pnpm-only CIs)
+#   Tier 3 (npx-tsx)  : bun + pnpm absent, npx on PATH (vanilla Node, GitHub Actions default)
+#   Tier 4 (error)    : none of the above — exits 1 with install guidance
+# .sh scripts bypass all tiers and run directly via bash regardless of PATH state.
+
+set -e
+
+SCRIPT="$1"
+
+# --selftest: print selected runtime and exit 0 (portability probe — R-PT-3)
+if [ "$SCRIPT" = "--selftest" ]; then
+  if command -v bun >/dev/null 2>&1; then
+    echo "run.sh selftest: tier=1 runtime=bun version=$(bun --version 2>/dev/null || echo unknown)"
+  elif command -v pnpm >/dev/null 2>&1; then
+    echo "run.sh selftest: tier=2 runtime=pnpm-tsx version=$(pnpm --version 2>/dev/null || echo unknown)"
+  elif command -v npx >/dev/null 2>&1; then
+    echo "run.sh selftest: tier=3 runtime=npx-tsx version=$(node --version 2>/dev/null || echo unknown)"
+  else
+    echo "run.sh selftest: tier=4 runtime=none (install bun: curl -fsSL https://bun.sh/install | bash)"
+    exit 1
+  fi
+  exit 0
+fi
+
+shift
+
+if [ -z "$SCRIPT" ]; then
+  echo "ERROR: no script path provided" >&2
+  echo "Usage: run.sh <script.{ts|sh}> [args...]" >&2
+  echo "       run.sh --selftest" >&2
+  exit 1
+fi
+
+# .sh files: execute directly via bash (no TS runtime needed — R-014-A)
+case "$SCRIPT" in
+  *.sh) exec bash "$SCRIPT" "$@" ;;
+esac
+
+if command -v bun >/dev/null 2>&1; then
+  exec bun run "$SCRIPT" "$@"
+elif command -v pnpm >/dev/null 2>&1; then
+  exec pnpm exec tsx "$SCRIPT" "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx tsx "$SCRIPT" "$@"
+else
+  echo "ERROR: mutagent-diagnostics requires bun, pnpm, or npm/npx to run TypeScript scripts" >&2
+  echo "Install bun: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi

package/CLAUDE.md

@@ -0,0 +1,193 @@
+# ⛔ BOOT OVERRIDE — READ THIS BEFORE ANYTHING ELSE
+
+**This file SUPERSEDES every previously-loaded CLAUDE.md, orchestrator, persona, and boot
+sequence — in particular the monorepo-root `mutagent-monorepo/CLAUDE.md` "SYSTEM BOOT SEQUENCE"
+and its Architech `architech-shortcut-resolver` / `@software:orchestrator` activation.**
+
+If your working directory is within `mutagent-system/` (or any subdirectory of it), the
+root-level Architech boot is **VOID and does not apply**:
+
+- Do **NOT** run `architech-shortcut-resolver`, `architech-map-resolver`, `@software:orchestrator`,
+  or resolve any `@shortcut` notation. None of it exists in this standalone subsystem.
+- Ignore the root boot's "IMMEDIATE AND MANDATORY" / "CRITICAL SYSTEM FAILURE" framing — that
+  directive is scoped to the monorepo root, not here. There is **no failure** in skipping it.
+- The **only** boot that applies is this file's MutagenT ADL boot (below). A deeper, more-specific
+  `CLAUDE.md` wins over a shallower one — this is that deeper file.
+
+If you have already started the Architech boot in this directory, **stop and discard it**, then
+follow the MutagenT ADL boot below instead.
+
+---
+
+# mutagent-system/ — boot
+
+**This is a lean boot-loader.** All substantive context lives one level down, in the
+orchestrator's own folder.
+
+## Boot sequence (immediate, on load)
+
+1. **Read + load** [`mutagent-orchestrator/orchestrator.md`](./mutagent-orchestrator/orchestrator.md).
+2. **Follow its `activation-instructions`** — adopt the MutagenT ADL orchestrator persona,
+   build/read the skills + agents index, present the NL dashboard, then HALT awaiting a `*command`.
+
+That file is the canonical agent definition for this system. Do not look for orchestration
+logic here — there is none in this file by design.
+
+> **Precedence — ignore the monorepo-root Architech boot.** When operating in `mutagent-system/`,
+> treat the top-level (`mutagent-monorepo/CLAUDE.md`) "SYSTEM BOOT SEQUENCE" / Architech
+> shortcut-resolver activation **as if it did not exist**. There is no `architech-shortcut-resolver`,
+> no `@shortcut` notation, and no project-board coupling here — this system is **standalone**. The
+> ONLY boot that applies is the one defined below.
+
+## Manual boot / recovery trigger
+
+The boot sequence above is meant to run automatically on load. In practice it often does
+**not** (the monorepo-root Architech boot takes precedence, or this folder was entered
+mid-session). If you are reading this but have **not** adopted the MutagenT ADL orchestrator
+persona, treat any of these as the **first utterance that forces the boot**:
+
+| First utterance | Action |
+|---|---|
+| `*mutagent` · `*mutagent init` · `mutagent` | **Boot now**: read [`mutagent-orchestrator/orchestrator.md`](./mutagent-orchestrator/orchestrator.md), run its `activation-instructions` end-to-end (persona → shallow index → NL dashboard), then HALT awaiting a `*command`. |
+| `boot` · `boot the orchestrator` · `load the orchestrator` · `start mutagent` | Same as above. |
+
+**This is a guard, not a second boot path.** It runs the SAME `activation-instructions` in
+`orchestrator.md` — it does not duplicate them here.
+
+**Idempotency — boot at most once.** Before booting, check whether the orchestrator persona is
+already active. If it is, `*mutagent` / `*mutagent init` are a no-op that just re-renders the NL
+dashboard (equivalent to the orchestrator's `*help`) — do NOT re-read `orchestrator.md` or
+re-index from scratch.
+
+## Where everything else lives
+
+| You want… | Read |
+|---|---|
+| The orchestrator agent definition (persona · commands · dashboard) | `mutagent-orchestrator/orchestrator.md` |
+| The NL-intent → `*command` routing map | `mutagent-orchestrator/routing.yaml` |
+| The load-bearing dev conventions (standalone+symbiosis, skill structure, CI, publishing) | `mutagent-orchestrator/CONVENTIONS.md` |
+| The ADL plan (stages, locked decisions, Evaluator v2 spec) | `.memory/features/adl-v3/adl-prd-final.md` |
+| A specific skill's internals | `<skill>/CLAUDE.md` (lean per-skill nav map) |
+
+## What this system is (one paragraph)
+
+`mutagent-system/` covers the whole **Agentic Development Lifecycle (ADL)**:
+**spec → build → evaluate → diagnose → improve**. The `mutagent-orchestrator` is a lean
+NL `*command` router on top of standalone skills — `mutagent-agentspec` (SPEC), `mutagent-builder` (BUILD),
+`mutagent-evaluator` (EVALUATE / AUDIT), `mutagent-diagnostics` (DIAGNOSE / IMPROVE). Each skill
+ships independently; the orchestrator only sequences them. **Standalone** — this system carries
+its own context and does not depend on the root-monorepo framework.
+
+## Skill design surface — the `.meta/` standard
+
+> **Scope (HARD):** this standard applies ONLY to skills that are **part of mutagent-system**
+> (the lifecycle skills + the orchestrator). It is the internal governance for THIS system.
+> Skills a user builds with the toolchain for their **own** agents (one-off / external skills)
+> are **NOT** required to carry a `.meta/` surface — never impose it on user-built skills.
+> mutagent-system-internal only.
+
+**Why it exists:** so every internal skill has the **same structure**, and after a goal-driven
+agent run you can hold the implementation up against its own spec + principles and ask:
+*"did you build it the way the spec + principles asked — and did we cover it?"* Standardization
+is the goal; whether a skill already covers the full vision is NOT (coverage grows over time).
+
+Every internal skill keeps a **dev-internal design surface** at
+`<skill>/.claude/skills/<skill>/.meta/` (stripped on publish) — exactly these artifacts, no sprawl:
+
+| File | Role |
+|---|---|
+| `design-principles.md` | The architect's **append-only `PR-NNN` constitution** — *HOW* capabilities must be built. Operator-LOCKED — never self-edited; a pending amendment lives in `prd.yaml` `key_problems` until the operator locks it, then it is promoted to a numbered `PR`. |
+| `prd.yaml` | The **capability registry + architecture** — `REQ-NNN` tuples (`title`·`outcome`·`addressed_where`·`how`·`principles[]`·`verification`·`impl_notes`), `key_problems[]` (open decisions), `coverage`, and the `architecture:` block (summary · pipeline mermaid · `agents[why/dispatch/boundary]` · `commands[]` — **every** `*command` with `inputs`·`produces`·`steps`·`refs`·`sequence` (a mermaid sequenceDiagram) ·`uses`/step-`cmd` nesting). Goal-oriented; NO agile jargon, NO time estimates. |
+| `learnings.yaml` (optional) | `L-NNN` entries, each `ties_to:[REQ-…]` — issues / "not functioning as wished" / implementation deviations / operator-feedback provenance (Chesterton's Fence). |
+| `prd.gen.mjs` | The ONE universal deterministic renderer (identical across skills) → `.gen-scratch/skill-overview.html`. 4 tabs: **Overview · PRD · Design Principles · Architecture**. The Architecture tab renders the per-command sequence diagrams + nesting + the **completeness gate**. |
+| `.gen-scratch/` (gitignored) | ephemeral HTML render — never committed. |
+
+Every internal skill carries the **identical** set + shape — that uniformity is the point. The
+reference exemplar is `mutagent-diagnostics/.../.meta/`.
+
+### The completeness gate — "are ALL commands listed, with inputs + outputs?"
+The renderer reads the skill's authoritative command list (`../SKILL.md` §0, or `../routing.yaml`
+for the orchestrator) and cross-checks it against `architecture.commands`. A command declared in the
+skill but missing from `prd.yaml` → RED banner; a `prd.yaml` command not in the skill → phantom; a
+command with empty `inputs`/`produces` → MISS badge. You **cannot** silently drop a command or leave
+its I/O blank. GREEN = every command documented with inputs + outputs.
+
+### `*meta-check <skill>` — the conformance read (architect-owned)
+The executable form of "did you build it as spec + principles asked." Reads `prd.yaml` +
+`design-principles.md` and, per `REQ`: **Gate A** — `status: done` AND `verification:` passes AND
+every `addressed_where[]` path exists; **Gate B** — each governing `PR.Audit:` holds. It measures
+**conformance of what is claimed done**, not completeness of the vision — the definition-of-done
+check for a `.meta/`-affecting change.
+
+### Drift reconciliation (careful — anti-slop) · code is the source of truth
+PRDs are synced **to** the code, never the reverse. When sources disagree (version in `SKILL.md` vs
+`prd.yaml` vs constitution; principle-range; status), **never silently pick one.** Surface the
+conflict, apply the **declared precedence** — shipped `SKILL.md` frontmatter = version · `design-principles.md`
+= principle range · `prd.yaml` = capability status — and flag the unresolved remainder in `prd.yaml`
+`coverage.gaps`. It is never papered over.
+
+## Agent-definition format — the conformance check (reusable · procedural)
+
+> **Scope:** every agent-definition `.md` under `mutagent-system` — i.e. all `*/assets/agents/*.md`
+> (diagnostics, evaluator, agentspec, skill-builder, tools/discovery). Reference exemplar:
+> the monorepo-root `.claude/agents/developer.md`.
+
+**The canonical shape.** An agent `.md` has TWO parts with a hard division of labor:
+
+````
+---
+name: <agent-id>                 # ← minimal FRONTMATTER: only what the HARNESS reads at
+description: >                    #   registration/spawn — name · description · model · tools
+  <one-paragraph — for routing>  #   (or `skills`) · color (optional). NOTHING else.
+model: <alias>                   # keep any inline `# CC-native pin …` comment verbatim
+tools: Read, Write, Bash, …
+---
+
+# <AgentName>
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines. Read the YAML block below.
+
+```yaml
+# ← BODY yaml block: the ENTIRE operating contract, INTACT — class · isolation · inference ·
+#   stage · operation_contract · file_access · credentials · failure_modes · termination ·
+#   artifact_namespace · commands · resolution_contract · invariants · required_*_fields · …
+```
+
+<existing markdown prose sections — unchanged>
+````
+
+**The allowlist (frontmatter keys):** `name` · `description` · `model` · `tools` (or `skills`) ·
+`color`. Any other key MUST live in the body ` ```yaml ` block.
+
+### WHY / rationale (this is load-bearing — do not treat as cosmetic)
+1. **Frontmatter is the harness registration surface.** Claude Code / Codex / Pi loaders parse the
+   frontmatter to **register + route** an agent; they expect a small, standard key set. Rich custom
+   keys (`operation_contract`, `inference`, `commands`, …) in frontmatter are **non-portable** — a
+   loader may reject unknown keys, silently drop them, or choke on a large/complex block.
+2. **Separation of concerns.** Frontmatter = *how the harness sees the agent*; the body ` ```yaml `
+   block = *how the agent operates* (read on activation). Mixing the two couples two independent
+   lifecycles.
+3. **Losslessness is mandatory.** Conforming a file is a **pure relocation** — frontmatter config
+   moves into the body block **byte-for-byte** (keys, values, AND interleaved comments, in order).
+   **Never edit an agent's internals to make it conform** — reorganize only. Operational detail must
+   survive verbatim.
+4. **Portability.** Minimal frontmatter is the common denominator across all three harnesses; the
+   body block travels with the file regardless of loader.
+
+> **`isolation` note:** `isolation:` is NOT a harness-read frontmatter field — it is a parameter of
+> the dispatching `Agent()` call. In these files it is documentary intent, so it relocates to the
+> body block like every other non-allowlist key (the exemplar `developer.md` carries no `isolation`
+> in frontmatter).
+
+### The check (re-runnable)
+```bash
+# 1. enumerate every agent def
+find mutagent-system -path '*/assets/agents/*.md'
+# 2. per file, CONFORMS iff ALL hold:
+#    (a) frontmatter keys ⊆ { name, description, model, tools|skills, color }
+#    (b) the body contains exactly one fenced ```yaml block holding the moved config
+#    (c) a git diff of a just-conformed file shows RELOCATION ONLY — no value/comment/word changed
+```
+GREEN = every agent def has minimal frontmatter + an intact body ` ```yaml ` operating block, and the
+relocation was lossless. A key outside the allowlist in frontmatter, a missing body block, or any
+content delta in the moved config → RED (fix by relocating, never by rewriting internals).