@mutagent/helix 0.1.0-alpha.14

package/.claude/skills/mutagent-helix/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: mutagent-helix
+description: |
+  Helix — the MutagenT Agentic Development Lifecycle (ADL) conductor. Drives a skill or agent
+  through the full lifecycle — spec → build → evaluate → diagnose → improve — by sequencing a set
+  of standalone lifecycle-stage skills and adjudicating the gates between them. Helix is a
+  natural-language *command router: it indexes the system, tracks where you are in the loop, hands
+  each stage to its owning skill, and keeps every apply (a code change, a platform update)
+  approval-gated. First invocation auto-detects setup and guides onboarding; subsequent
+  invocations render the ADL dashboard and await a *command (or free text, which routes through the
+  intent layer). Ships the lifecycle-stage skills it conducts: mutagent-agentspec (① SPEC — a
+  guided interview that emits a portable agentspec.yaml), mutagent-builder (② BUILD — implement the
+  validated spec into the target framework/harness), mutagent-evaluator (③ EVALUATE — mine criteria
+  from traces, judge, validate the judge, build datasets; judge only, never fixes), and
+  mutagent-diagnostics (④ DIAGNOSE — RCA + ranked remedies from real traces). The ⑤ IMPROVE stage
+  routes to mutagent-optimize (published separately as @mutagent/optimize) — the session-conducted,
+  bounded eval-driven optimize loop (Build → Eval → Diagnose → Improve ↻) whose one apply-gate at
+  convergence goes through the shared `mutagent-cli apply`. Helix never executes a stage's inner
+  work — it routes. Two invariants hold the loop
+  together: judge-never-fix (the evaluator decides; failures route to diagnostics) and
+  explicit-and-gated (no stage auto-advances; the operator stays in control).
+license: Apache-2.0. See LICENSE for complete terms.
+compatibility: Designed for Claude Code, Codex, Cursor, and similar coding-agent runtimes; works with git, gh CLI, jq, curl, and Bun/pnpm/npm runtimes.
+metadata:
+  author: mutagent
+  version: "0.1.0-alpha.0"
+---
+
+# Helix — the MutagenT ADL conductor
+
+> **The full agent definition lives in [`orchestrator.md`](./orchestrator.md)** (bundled alongside
+> this file). That is the canonical Helix persona + activation-instructions + the complete
+> `*command` roster + the dashboard template. Read it first; this SKILL.md is the operator-facing
+> contract and setup map.
+
+## §0 · Setup (first invocation)
+
+If you have just installed `@mutagent/helix` and have not yet onboarded:
+
+```bash
+pnpx @mutagent/helix init      # installs Helix + the lifecycle skills, links CLAUDE.md / AGENTS.md
+```
+
+`init` installs the conductor and the lifecycle-stage skills (agentspec · builder · evaluator ·
+diagnostics) into your coding agent's `.claude/` (project-local by default; `--global` for the home dir), and
+links `CLAUDE.md` / `AGENTS.md` so the host boots Helix. Then open your coding agent and invoke the
+conductor.
+
+## §1 · Triggers
+
+| You type | Helix does |
+|---|---|
+| `/mutagent-helix` · `*mutagent` · `boot` | Boot the conductor: adopt the Helix persona (per `orchestrator.md`), build the shallow system index, render the ADL dashboard, then HALT awaiting a `*command`. |
+| free text (e.g. "diagnose the failures") | Routes through the NL intent layer (`routing.yaml`) to the owning stage's `*command`. |
+
+## §2 · What Helix is
+
+Helix is the **only layer that knows the whole system at once**. It sequences the Agentic
+Development Lifecycle as a flexible DAG — you can enter at any stage and Helix routes onward — and
+hands each stage to the standalone skill that owns it. It owns sequencing, the system topology
+index, cross-stage handoff (a shared contract bundle + file-based handover), and gate adjudication
+— **never** the work inside a stage.
+
+```
+spec ──▶ build ──▶ evaluate ──▶ diagnose ──▶ improve ──▶ (loop back to build)
+ │         │          │            │            │
+agentspec  builder     evaluator    diagnostics  optimize (gated apply) ↻
+(① SPEC)   (② BUILD)   (③ EVALUATE) (④ DIAGNOSE) (⑤ IMPROVE)
+```
+
+## §3 · The `*command` roster
+
+| Command | Stage | Owning skill | What it does |
+|---|---|---|---|
+| `*sync` · `*status` · `*onboard` · `*help` | conductor | Helix | Index the system · report where you are in the loop · onboard/configure · render the dashboard. |
+| `*spec` · `*validate-spec` | ① SPEC | mutagent-agentspec | Guided interview → portable, validated `agentspec.yaml`. |
+| `*build` · `*sync-spec` | ② BUILD | mutagent-builder | Implement the validated spec; resync `agentspec.yaml` from implementation drift. |
+| `*evaluate` · `*audit` (+ `*discover` · `*validate` · `*review` · `*build-dataset` · `*derive-dataset`) | ③ EVALUATE | mutagent-evaluator | Mine criteria from real traces → judge → validate the judge → datasets. **Judge only — never fixes.** |
+| `*diagnose` | ④ DIAGNOSE | mutagent-diagnostics | Root-cause routed failures on real evidence → ranked remedies, handed to the gated ⑤ IMPROVE. |
+| `*improve` · `*optimize` | ⑤ IMPROVE | mutagent-optimize | The session-conducted, bounded eval-driven optimize loop (Build → Eval → Diagnose → Improve ↻): confirm once at entry, ONE apply-gate at convergence — the write goes through the shared `mutagent-cli apply`. Utterances: "optimize this agent/skill" · "run the improve/optimize loop" · "apply the fix/remedy" · "next iteration" · "make it better" · "keep improving". |
+
+The evaluator `*discover/*validate/*review/*build-dataset/*derive-dataset` commands are **forward-intents**.
+`*build` is an owned BUILD route to `mutagent-builder`; `*sync-spec` is a SPEC route to
+`mutagent-agentspec` (which delegates the code-read to builder's `ai-architect #sync-spec`). Helix
+gates/forwards; it does not execute a stage's inner work.
+
+## §4 · The skills Helix conducts (bundled)
+
+| Skill | ADL stage | Invoke directly |
+|---|---|---|
+| [`mutagent-agentspec`](../mutagent-agentspec/SKILL.md) | ① SPEC | `/mutagent-agentspec` |
+| [`mutagent-builder`](../mutagent-builder/SKILL.md) | ② BUILD | `/mutagent-builder` |
+| [`mutagent-evaluator`](../mutagent-evaluator/SKILL.md) | ③ EVALUATE | `/mutagent-evaluator` |
+| [`mutagent-diagnostics`](../mutagent-diagnostics/SKILL.md) | ④ DIAGNOSE | `/mutagent-diagnostics` |
+| [`mutagent-optimize`](../mutagent-optimize/SKILL.md) | ⑤ IMPROVE | `/mutagent-optimize` |
+
+`mutagent-optimize` is published independently as `@mutagent/optimize` and installed alongside
+(it is not yet part of the `helix init` bundled set); Helix's `*improve` route targets it either way.
+
+Each is a **sealed, standalone** skill (it never references a sibling in source) and is also
+published independently under its own `@mutagent/*` name. Helix is the only layer that knows about
+all of them; it talks to each via its public skill contract, never by reaching into its source.
+
+## §5 · Invariants (do not regress)
+
+- **Judge, never fix.** The evaluator decides pass/fail; failures route to diagnostics, which
+  proposes the remedies the gated ⑤ IMPROVE stage (mutagent-optimize → the shared `mutagent-cli
+  apply`) applies. Decision stays independent of remediation.
+- **Explicit and gated.** No stage auto-advances. Every apply (PR · REST · CLI install) requires
+  explicit operator approval. Helix never auto-applies a remedy.
+- **Routing only.** Helix sequences stages and adjudicates gates; it never performs a stage's inner
+  work.
+- **Standalone.** The system carries its own context — no external framework coupling.

package/.claude/skills/mutagent-helix/scripts/cli/codex-transcode.ts

@@ -0,0 +1,143 @@
+/**
+ * codex-transcode.ts — convert a Claude-Code agent `.md` (YAML frontmatter + body)
+ * into a Codex-native project custom-agent `.toml`.
+ *
+ * Codex auto-loads spawnable subagents from `.codex/agents/*.toml` (project scope).
+ * The correct format is FLAT top-level keys (NOT `[agent]` tables) — matching the
+ * native `moni-thor.toml`:
+ *
+ *   name = "<name>"
+ *   description = "<one-line>"
+ *   developer_instructions = """
+ *   ```yaml
+ *   <the EXCESS frontmatter — everything except name/description>
+ *   ```
+ *
+ *   <the agent .md body, verbatim>
+ *   """
+ *
+ * The OLD diagnostics transcode was malformed: it collapsed `description: >` block
+ * scalars to ">", mangled nested frontmatter into invalid TOML, and used `[agent]`
+ * tables. This version is lossless + intact: name/description become structured TOML
+ * keys; ALL other frontmatter is preserved verbatim inside a ```yaml``` block; the
+ * body is preserved verbatim; the whole thing parses as valid TOML.
+ */
+
+export interface ParsedAgentMd {
+  name: string;
+  /** one-line, block-scalars flattened */
+  description: string;
+  /** the frontmatter MINUS the name + description lines, verbatim */
+  excessFrontmatter: string;
+  /** the markdown after the frontmatter, verbatim */
+  body: string;
+}
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?$/;
+
+/** Is a line a top-level YAML key (`key:` at column 0, not a list item)? */
+function isTopLevelKey(line: string): boolean {
+  return /^[^\s#][^:]*:/.test(line);
+}
+
+/**
+ * Parse a Claude agent .md: split frontmatter/body, extract name + description
+ * (flattening `>`/`|` block scalars and inline values), and return the remaining
+ * frontmatter verbatim.
+ */
+export function parseAgentMd(md: string): ParsedAgentMd {
+  const m = md.match(FM_RE);
+  if (!m) {
+    // No frontmatter — treat the whole thing as the body with a derived name.
+    return { name: "agent", description: "", excessFrontmatter: "", body: md };
+  }
+  const fm = m[1] ?? "";
+  const body = m[2] ?? "";
+  const lines = fm.split(/\r?\n/);
+
+  let name = "";
+  let description = "";
+  const excess: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s?(.*)$/);
+    if (keyMatch && isTopLevelKey(line)) {
+      const key = keyMatch[1]!;
+      const rawVal = keyMatch[2] ?? "";
+
+      if (key === "name" || key === "description") {
+        const isBlock = rawVal.trim() === ">" || rawVal.trim() === "|";
+        let value: string;
+        if (isBlock) {
+          // consume following MORE-indented lines as the scalar body
+          const parts: string[] = [];
+          let j = i + 1;
+          for (; j < lines.length; j++) {
+            const l = lines[j]!;
+            if (l.trim() === "") { parts.push(""); continue; }
+            if (/^\s+/.test(l)) { parts.push(l.trim()); }
+            else break;
+          }
+          i = j - 1;
+          value = parts.join(" ").replace(/\s+/g, " ").trim();
+        } else {
+          // strip an inline trailing comment ONLY when the value isn't quoted
+          value = rawVal.trim();
+          value = value.replace(/\s+#.*$/, "").trim();
+          value = value.replace(/^["']|["']$/g, "");
+        }
+        if (key === "name") name = value;
+        else description = value;
+        continue; // do NOT add name/description to excess
+      }
+    }
+    excess.push(line);
+  }
+
+  // drop leading/trailing blank lines from excess
+  const excessFrontmatter = excess.join("\n").replace(/^\n+|\n+$/g, "");
+  return { name: name || "agent", description, excessFrontmatter, body: body.replace(/^\n+/, "") };
+}
+
+/** Escape a value for a TOML basic (single-line) string. */
+function tomlBasic(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/[\r\n]+/g, " ");
+}
+
+/**
+ * Make content safe inside a TOML multi-line LITERAL string ('''...''').
+ * Literal strings do NO escape processing — perfect for markdown bodies full of
+ * backslashes (e.g. table cells `a \| b`) that a basic `"""` string would reject.
+ * The only thing a literal string can't contain is `'''`; we verified the bundled
+ * agents have none, but guard anyway by inserting a zero-width break.
+ */
+function tomlLiteral(s: string): string {
+  return s.replace(/'''/g, "''​'");
+}
+
+/**
+ * Transcode a Claude agent `.md` → the Codex project custom-agent `.toml` string.
+ * Lossless: every frontmatter field + the full body is preserved.
+ */
+export function toCodexAgentToml(md: string): string {
+  const { name, description, excessFrontmatter, body } = parseAgentMd(md);
+
+  const blocks: string[] = [];
+  if (excessFrontmatter.trim()) {
+    blocks.push("```yaml\n" + excessFrontmatter + "\n```");
+  }
+  if (body.trim()) blocks.push(body.trimEnd());
+  const instructions = tomlLiteral(blocks.join("\n\n"));
+
+  const lines = [
+    `name = "${tomlBasic(name)}"`,
+    `description = "${tomlBasic(description)}"`,
+    "",
+    "developer_instructions = '''",
+    instructions,
+    "'''",
+    "",
+  ];
+  return lines.join("\n");
+}

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

@@ -0,0 +1,111 @@
+/**
+ * scripts/cli/doctor.ts — @mutagent/helix runtime probe.
+ * Invoked as:  pnpx @mutagent/helix doctor
+ *
+ * Reports what Helix sees: which skills are installed in the consumer's .claude,
+ * how many agents are present, and whether CLAUDE.md / AGENTS.md are linked.
+ * Read-only — never writes. Mirrors the diagnostics doctor discipline.
+ *
+ * Flags:
+ *   --global   probe ~/.claude (default is <cwd>/.claude)
+ *   --json     emit only the DoctorReport JSON
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseArgs } from "node:util";
+
+interface SkillProbe {
+  name: string;
+  present: boolean;
+  hasSkillMd: boolean;
+}
+
+interface DoctorReport {
+  package: "@mutagent/helix";
+  scope: "project" | "global";
+  claudeRoot: string;
+  skills: SkillProbe[];
+  agentCount: number;
+  claudeMd: boolean;
+  agentsMd: boolean;
+  healthy: boolean;
+}
+
+const EXPECTED_SKILLS = [
+  "mutagent-helix",
+  "mutagent-agentspec",
+  "mutagent-builder",
+  "mutagent-evaluator",
+  "mutagent-diagnostics",
+] as const;
+
+function main(): void {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      global: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const scope = values.global ? "global" : "project";
+  const configRoot = scope === "global" ? join(homedir(), ".claude") : join(process.cwd(), ".claude");
+  const skillsDir = join(configRoot, "skills");
+  const agentsDir = join(configRoot, "agents");
+  const linkRoot = scope === "global" ? configRoot : process.cwd();
+
+  const skills: SkillProbe[] = EXPECTED_SKILLS.map((name) => {
+    const dir = join(skillsDir, name);
+    return {
+      name,
+      present: existsSync(dir),
+      hasSkillMd: existsSync(join(dir, "SKILL.md")),
+    };
+  });
+
+  const agentCount = existsSync(agentsDir)
+    ? readdirSync(agentsDir).filter((f) => f.endsWith(".md")).length
+    : 0;
+  const claudeMd = existsSync(join(linkRoot, "CLAUDE.md"));
+  const agentsMd = existsSync(join(linkRoot, "AGENTS.md"));
+  const healthy = skills.every((s) => s.hasSkillMd) && agentCount > 0;
+
+  const report: DoctorReport = {
+    package: "@mutagent/helix",
+    scope,
+    claudeRoot: configRoot,
+    skills,
+    agentCount,
+    claudeMd,
+    agentsMd,
+    healthy,
+  };
+
+  if (values.json) {
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(healthy ? 0 : 1);
+  }
+
+  console.info(`\n🧬 @mutagent/helix doctor (${scope}-scope) — ${configRoot}\n`);
+  for (const s of skills) {
+    console.info(`  ${s.hasSkillMd ? "✓" : "✗"} ${s.name}${s.hasSkillMd ? "" : s.present ? " (no SKILL.md)" : " (missing)"}`);
+  }
+  console.info(`  ${agentCount > 0 ? "✓" : "✗"} agents: ${agentCount} installed`);
+  console.info(`  ${claudeMd ? "✓" : "•"} CLAUDE.md ${claudeMd ? "linked" : "not found"}`);
+  console.info(`  ${agentsMd ? "✓" : "•"} AGENTS.md ${agentsMd ? "linked" : "not found"}`);
+  // Codex side (project-local)
+  const aSkills = join(process.cwd(), ".agents", "skills");
+  const cAgents = join(process.cwd(), ".codex", "agents");
+  const codexSkills = existsSync(aSkills)
+    ? readdirSync(aSkills).filter((d) => existsSync(join(aSkills, d, "SKILL.md"))).length
+    : 0;
+  const codexAgents = existsSync(cAgents) ? readdirSync(cAgents).filter((f) => f.endsWith(".toml")).length : 0;
+  console.info(`  ${codexSkills > 0 ? "✓" : "•"} Codex: ${codexSkills} skills (.agents/skills) · ${codexAgents} agents (.codex/agents/*.toml)`);
+  console.info(`\n${healthy ? "✅ healthy — boot with *mutagent" : "⚠ incomplete — run: pnpx @mutagent/helix init"}\n`);
+  process.exit(healthy ? 0 : 1);
+}
+
+main();