@mutagent/helix 0.1.0-alpha.14

package/mutagent-agentspec/.claude/skills/mutagent-agentspec/references/workflows/orchestrator-protocol.md

@@ -0,0 +1,302 @@
+# mutagent-agentspec — Orchestrator Protocol
+
+> The runtime FSM for `mutagent-agentspec`. The **parent session IS the domain orchestrator** — it
+> runs the `*spec` interview itself and does **NOT** dispatch a coordinator sub-agent (PR-006). On
+> Claude Code the interview uses **AskUserQuestion**; elsewhere it uses a chat-based multi-choice
+> fallback. `*build` is owned by `mutagent-builder`; `*eval` is a routed handoff to EVALUATE.
+
+---
+
+## Star-command resolution contract (verbatim)
+
+When you encounter a `*<name>` token:
+1. **RESERVED** — `*` marks a command. NOT prose, NOT a file path, NOT an external shortcut.
+   `*command` = THIS skill's semantic map (internal). Never improvise.
+2. **RESOLVE** — look up `<name>` in the `commands:` block in `SKILL.md §0.1`. Not found ⇒ ERROR +
+   ask the operator. NEVER guess.
+3. **BINDING** — read `kind:` + `binds:`:
+   - `kind: script` ⇒ `binds:` a relative script path ⇒ CALL the script via `scripts/cli/run.sh`.
+     Do NOT re-implement it in prose.
+   - `kind: agent-chain` ⇒ `binds:` a workflow file#section ⇒ load + run the steps in order.
+   - `kind: hybrid` ⇒ `binds:` both ⇒ call script(s) for deterministic parts, reason for the rest.
+4. **PRE-GATE** — load any `pre_gate.loads:`.
+5. **EXECUTE** — run the steps IN ORDER. Invent nothing.
+6. `purpose:` / `impact:` explain WHY (not executed). Steps MAY reference other `*commands`.
+
+---
+
+## `*spec` — the guided interview FSM (parent session, full)
+
+**Goal:** walk the operator through the `agentspec.yaml` Definition + Build, emit the spec, and gate
+it with `*validate-spec`. The interview is parent-only (AskUserQuestion cannot run inside a
+sub-agent, PR-006). Every fork is an AskUserQuestion (Claude Code) or a chat multi-choice
+(elsewhere) — never a bare inline prose ask. Capture VERBOSE descriptions on every entry (PR-015) —
+the description is the primary field the implementing LLM reads.
+
+The FSM walks the blocks in order. State accumulates into the in-progress spec object; the operator
+may revise an earlier answer at any point (the spec is the working record).
+
+> **FRAMEWORK-BEFORE-TOOLING ordering (dogfood F3).** The implementation **target** (`build.target_framework`,
+> the **B0** step) is chosen **EARLY — before `context_sources` (D3) and `tools` (D4)** — because the chosen
+> framework/ecosystem SCOPES how each tool binds (an MCP ref vs a CLI vs a framework-native SDK call) and
+> which integration idioms/language are even available (F12). Asking tools first and the target second forced
+> a re-think of every tool binding once the target landed. The FSM therefore runs **D0 → D1 → D2 → B0 → D3 →
+> D4 → D5 → …**: identity + persona + jobs first (they INFORM the target recommendation), then the target,
+> then the framework-scoped tooling questions. The remaining Build steps (B1 runtime, B2 eval-framework) and
+> the Appendix/Meta phases follow as before.
+
+### Phase D — DEFINITION (the interface — WHAT the agent is)
+
+| # | State | Captures | Schema target |
+|---|---|---|---|
+| D0 | **identity** | name · version · description · kind (agent\|skill\|composite). INFER `kind` from the description and PROPOSE it (F2 — see below); do NOT cold-ask. | `definition.identity` |
+| D1 | **persona + system_prompt** | role · verbose persona; then the ACTUAL operative system prompt (full text, not a summary, PR-014) | `definition.persona`, `definition.system_prompt` |
+| D2 | **jobs_to_be_done** | per job: id · verbose what+why description · expected_output | `definition.jobs_to_be_done[]` |
+| **B0** | **target_framework** *(asked HERE — framework-before-tooling, F3)* | the implementation target — a framework (mastra\|deepagents\|pydantic-ai\|langgraph) OR a harness (`harness:claude-code`\|`harness:codex`\|`harness:<other>`) OR a future target (String, PR-005). RECOMMEND one from the Definition so far (D0–D2). Chosen NOW because it scopes D3/D4 tool binding + ecosystem idioms. | `build.target_framework` |
+| D3 | **context_sources** | per source: id · kind (api\|saas\|internal-service\|mcp\|cli) · verbose description · where_from · optional auth_ref. Bind in the chosen target's idiom (B0 is already known). | `definition.context_sources[]` |
+| D4 | **tools** | four buckets — integration (cli\|saas\|mcp, **binding preference resolved by the chosen target** per the revised PR-004 — see below) · code (lang+sandbox) · skills · subagents (verbose, optional tools/model honored verbatim per PR-003). Every entry carries a verbose description (PR-015). **Tooling matches the target's language/ecosystem (F12).** | `definition.tools.{integration,code,skills,subagents}` |
+| D5 | **agent_type** | conversational \| automation \| orchestrator. INFER from the description + jobs and PROPOSE it (F2 — see below); do NOT cold-ask. | `definition.agent_type` |
+| D6 | **triggers** | per trigger: id · kind (a2a\|webhook\|schedule\|queue\|event\|mcp\|manual) · verbose description · optional config. These are the DESIGNED agent's inbound activation events — DISTINCT from the in-system `*monitor` (PR-017). | `definition.triggers[]` |
+| D7 | **modeling** | decision_graph (state · nodes · edges{from,to,condition?}) LangGraph-aligned + freeform workflows | `definition.modeling` |
+| D8 | **sop** | per entry: id · when (trigger condition) · context (what is loaded/required) · verbose procedure · optional on_outcome{success,failure} (PR-016) | `definition.sop[]` |
+| D9 | **evals · success_criteria** | per criterion: id · binary-actionable criterion · type (llm-judge\|code-check) · goal. Append-extensible — you cannot pre-know them all (PR-019). | `definition.evals.success_criteria[]` |
+| D10 | **evals · scenarios** | the SITUATIONS the agent must handle — per scenario: id · verbose description (the situation) · expected_behavior · optional category · optional `edge_case` flag. Probe explicitly for the HARD / adversarial cases a naive spec forgets (dogfood F1). | `definition.evals.scenarios[]` |
+| D11 | **evals · dataset_categories** | the GOLDEN eval-suite slices the `*eval` dataset must cover — per category: id · verbose description (the use-case slice) · `edge_cases[]`. This is the dataset DEFINITION handed to the evaluator (seed, don't duplicate, PR-018; dogfood F2). | `definition.evals.dataset_categories[]` |
+
+#### INFER → PROPOSE → CONFIRM — `identity.kind` (D0) + `agent_type` (D5) (dogfood F2)
+
+> **Don't cold-ask the obvious.** The operator described the agent in D0–D2; both `identity.kind` and
+> `definition.agent_type` are usually DERIVABLE from that description + the jobs. So the interview
+> **INFERS** the value, **PROPOSES** it as the pre-selected default in the AskUserQuestion (Claude Code) /
+> chat multi-choice (elsewhere), and lets the operator **CONFIRM or CORRECT** — it never presents the
+> bare enum with no recommendation. A cold "is this conversational, automation, or orchestrator?" wastes
+> the operator's attention on a call the description already answers.
+
+**`definition.agent_type` inference map** (ship this exact mapping — propose the matching value, with the
+gloss as the rationale shown to the operator):
+
+| The description sounds like… | PROPOSE `agent_type` | Gloss (the WHY shown to the operator) |
+|---|---|---|
+| a chatbot / customer-facing assistant / support agent / conversational helper | `conversational` | a back-and-forth dialog agent |
+| an orchestrator / router / coordinator that delegates to other agents | `orchestrator` | an **a2a-router** — routes agents-to-agents |
+| an automation / pipeline / end-to-end job that runs without a human turn | `automation` | a **one-shot end-to-end** run |
+
+**`definition.identity.kind` inference** (D0): INFER `agent` for a standalone autonomous agent, `skill` for
+a reusable capability invoked by a host runtime, `composite` for a multi-part agent-of-agents; PROPOSE the
+inferred value, operator confirms/corrects.
+
+**Mechanism (both D0 and D5):** read the D0 `description` (+ D2 jobs for D5); pick the best-matching row;
+PROPOSE that value as the DEFAULT option with the gloss as its preview/rationale; the operator confirms it
+or picks another. On a low-confidence inference, still propose the best guess but flag it as a guess.
+
+### Phase B — BUILD (the implementation target — a guided choice)
+
+> **B0 (`target_framework`) is asked EARLY — during Phase D, right after D2 (jobs) and before D3/D4
+> (context + tools)** — per the framework-before-tooling ordering (F3). It is listed here too for the
+> schema-target map, but in the live FSM it has already been captured by the time these rows run. B1
+> (runtime) and B2 (eval-framework) are asked in their Phase-B position as before.
+
+| # | State | Captures | Schema target |
+|---|---|---|---|
+| B0 | **target_framework** *(captured early in Phase D — see D-table; restated here for the schema map)* | the implementation target — a framework (mastra\|deepagents\|pydantic-ai\|langgraph) OR a harness (`harness:claude-code`\|`harness:codex`\|`harness:<other>`) OR a future target (String, PR-005). RECOMMEND one from the Definition (e.g. langgraph for a declarative graph; harness:* for a coding-agent skill). | `build.target_framework` |
+| B1 | **runtime** | the execution runtime the implementation targets (bun\|node\|deno\|python\|shell\|…) — PIN it at spec-time so `*build` implements ONCE (no bash→Bun rebuild, dogfood F4). RECOMMEND from the target: harness:claude-code → bun/node; langgraph/pydantic-ai → python. | `build.runtime` |
+| B2 | **target_eval_framework** | mutagent-evaluator \| export:vitest\|promptfoo\|braintrust | `build.target_eval_framework` |
+
+#### D4 tool-binding — target-conditional, NOT blanket MCP-first (dogfood F5, revised PR-004)
+
+> By D4 the target is already chosen (B0, asked early per F3), so resolve each tool's binding preference
+> FROM the target rather than always reaching for MCP. This is the operator-directed revision of PR-004
+> (see `references/principles.md` PR-004):
+>
+> - **harness target** (`harness:claude-code` / `harness:codex`) → **CLI-first**. Prefer the native CLI
+>   tools the harness binds directly (`gh` / `git` / a framework `cli`); use `tools.integration[].kind: cli`.
+> - **code-framework target** (langgraph / mastra / pydantic-ai / deepagents) → **MCP / Composio / SDK-first**.
+>   Prefer an MCP `ref` (the portable tool layer), a Composio binding, or the framework's native SDK
+>   integration; use `kind: mcp` (or `saas` for a Composio/SDK binding) as appropriate.
+>
+> Propose the target-favored binding for each integration tool; the operator may override per-tool.
+
+#### D4 tooling matches the target's LANGUAGE / ecosystem (dogfood F12)
+
+> Once the target is chosen (B0), bias every tool / integration / SDK choice to that ecosystem's
+> idioms and LANGUAGE — don't propose a cross-language tool the target can't bind natively. Examples:
+>
+> - **TS framework** (mastra / TS harness) → the **TypeScript** ecosystem: prefer the **Vercel AI SDK**,
+>   TS-native MCP clients, and `npm`/`bun` packages. Pin `build.runtime` to bun/node (F4).
+> - **Python framework** (langgraph / pydantic-ai / deepagents) → the **Python** ecosystem: prefer the
+>   provider Python SDKs, `pip`-installable integrations, and Python MCP clients. Pin `build.runtime` to python.
+> - **harness target** → the harness's own tool surface + the language its skills/agents are authored in.
+>
+> The chosen target's language is the constraint; propose tools idiomatic to it, not a generic best-of-breed
+> from another stack. This keeps the binding implementable at `*build` without a language bridge.
+
+### Phase A — APPENDIX (pinned references)
+
+| # | State | Captures | Schema target |
+|---|---|---|---|
+| A0 | **framework_docs** | pin the doc roots for the chosen target (seed from `references/frameworks/doc-pins.md`; the operator may add/override). Crawled FRESH at `*build` (PR-002). | `appendix.framework_docs` |
+| A1 | **references** | decisions · glossary · operator notes | `appendix.references` |
+
+### Phase M — META (identity anchor + loop position) — set by the skill, confirmed by the operator
+
+| # | State | Captures | Schema target |
+|---|---|---|---|
+| M0 | **spec_id + spec_version** | a stable `spec_id` (survives every version, PR-012) + the spec_version | `meta.spec_id`, `meta.spec_version` |
+| M1 | **loop_state** | `stage: spec` at emit-time + an injected `updated_at`; `last_verdict` omitted until the loop runs (PR-010). NO downstream links — the spec is implementation-agnostic (PR-013). | `meta.loop_state` |
+
+### Phase E — EMIT + GATE
+
+1. **Resolve the output directory** (do NOT hard-code a path). Call the output-dir resolver:
+   `scripts/cli/run.sh scripts/config/resolve-spec-dir.ts` — it reads
+   `lifecycle.agentspec.spec_dir` from `<root>/.mutagent/config.yaml` and prints the resolved
+   absolute `dir` + the winning `source` (`flag`|`config`|`default`). **Precedence: flag > config >
+   default.** With ZERO config (no `.mutagent/config.yaml`, or the block/field absent) it returns the
+   DEFAULT `.mutagent/specs` — so `*spec` always runs. Then assemble the accumulated state into a
+   single `agentspec.yaml` at `<resolved-dir>/<spec_id>/agentspec.yaml` (so `*sync` can index the new
+   marker — see the cold-start note below).
+2. Run `*validate-spec <path>` (`scripts/validate/validate-spec.ts`). On FAIL, surface the
+   field-pathed errors, return to the offending phase, fix, re-emit, re-gate. On PASS, the spec is
+   the validated Definition + a trackable subject (a planned, not-yet-built agent is first-class
+   from spec-time, PR-010).
+3. SUGGEST the next stage (`*build`) — but NEVER auto-advance. The transition needs explicit
+   operator intent (PR-009).
+
+> **Cold-start note (PR-010).** `*spec` writes `agentspec.yaml` (under the resolved `spec_dir`, default
+> `.mutagent/specs`) with `meta.loop_state` — the spec IS the subject record. There is no separate
+> registry; Helix reads `meta.loop_state.stage` for loop position and `*sync` learns to index the new
+> marker. This closes the cold-start gap where the indexer only ever saw BUILT artifacts.
+
+> **Output-dir note (config v0.2.0).** WHERE `*spec` writes is resolved by
+> `scripts/config/resolve-spec-dir.ts` — precedence **flag > config > default**. The config field is
+> `lifecycle.agentspec.spec_dir` in `<root>/.mutagent/config.yaml` (the LOCAL install root, found by
+> walking up to the nearest `.mutagent/`). The block is OPTIONAL: with no config the resolver returns
+> the default `.mutagent/specs`, so `*spec` runs with zero config. A relative `spec_dir` is anchored
+> at the config root; an absolute one is honored as-is. The resolver is minimal by design — it reads
+> ONLY `spec_dir` and never cross-imports the orchestrator's config schema (standalone invariant).
+
+---
+
+## `*sync-spec` — reconcile the spec + eval triad against a target (delegated)
+
+> **The canonical spec-reconcile (dogfood F10).** `*sync-spec` FUSES the former `*spec-from-impl`
+> (brownfield reverse-generate) and the former builder-owned `*spec-sync` (drift resync) into ONE
+> operation — because reverse-generate is just *drift from nothing* (empty spec vs code). Cold (no
+> `agentspec.yaml` yet → CONSTRUCT one) and warm (a spec exists but code drifted → RECONCILE the delta)
+> are the SAME op with different starting points.
+>
+> **A THREE-leg triad (def → impl → EVAL), W2I5 · KP-003.** The reconcile keeps the spec leg AND the
+> **eval-criteria leg** in lockstep with the impl (PR-011): when the impl amends, the eval criteria that
+> ground the subject's evaluation can go stale exactly as the spec can. The eval leg's shape follows the
+> subject kind — **eval-suite criteria** for an agent/skill subject, **code-quality criteria** for a code
+> subject. `ai-architect #sync-spec` reconciles both legs; the eval-leg maintenance is the evaluator's:
+> `sync-eval-criteria.ts` `reconcileEvalCriteria` COMPUTES the grown criteria set, and the evaluator session
+> then PERSISTS it with `persist-eval-criteria.ts` `persistEvalCriteria` (the write that bumps the artifact's
+> freshness → returns the eval leg to `in-sync`) — criteria maintenance, NOT judging; the evaluator stays
+> judge-only, EV-051.
+>
+> **AgentSpec owns the entry but NEVER reads code.** It DELEGATES the target-read to builder's
+> `ai-architect #sync-spec` (the single implementation-reader), Helix-mediated via a HandoverBundle
+> (kind:agent — the same mechanism as the discovery agent). `ai-architect` returns a constructed /
+> reconciled draft (spec leg + eval leg); AgentSpec `*validate-spec`-gates the spec and OWNS the result.
+> Generic + subject-agnostic — no connector- or app-specific logic.
+
+**Inputs:** a TARGET ref — a path/repo to the existing implementation (or a cloud agent definition),
+optionally its env/config surface (`.env(.example)`, framework config, manifest/package files, MCP/tool
+registrations), the existing `agentspec.yaml` if one exists (warm reconcile), and the existing
+eval-criteria artifact if one exists (the eval leg — auto-located under `.mutagent/evaluator/living-suite/`
+when not passed).
+
+**Flow (parent-session, same interview discipline as `*spec`):**
+
+1. **Emit the delegation bundle.** AgentSpec builds a `HandoverBundle{ adl_stage: build,
+   subject:{kind:agent, name:"ai-architect"}, intent:{command:"*sync-spec"}, inputs:[ target-ref,
+   existing agentspec.yaml? ] }` and hands it to Helix, which DISPATCHES builder's `ai-architect
+   #sync-spec`. AgentSpec itself reads NO implementation source.
+2. **ai-architect reads the target + drafts the spec** (builder-side, `#sync-spec` mode). It inspects the
+   source — system prompt / persona text, tools + integrations it wires, context sources it reads,
+   sub-agents it dispatches, activation surface (entrypoints / handlers / triggers), and env/integration
+   surface — and PROJECTS it onto the `definition` blocks: `persona` + `system_prompt` (impl's operative
+   text VERBATIM, PR-014), `jobs_to_be_done`, `context_sources`, `tools` (four buckets), `agent_type`
+   (INFER + PROPOSE per F2), `triggers`, `modeling` + `sop`, and seeds `evals` from jobs + observed
+   behavior. INFERs `build.target_framework` + `build.runtime` from the OBSERVED impl (the one case where
+   the target is observed, not chosen). Cold → constructs from scratch; warm → emits the reconcile DELTA
+   against the existing spec. Returns a `HandoverBundle` carrying the draft/reconciled `agentspec.yaml` +
+   a change summary. Read files in full — do not guess from filenames.
+3. **CONFIRM the draft with the operator.** AgentSpec surfaces every INFERRED field as a proposal
+   (AskUserQuestion / chat fallback) — the operator confirms or corrects. A reverse-generated draft is a
+   proposal, never a silent fact; the operator owns the final Definition (the same parent-session,
+   propose-don't-assume discipline as `*spec`).
+4. **Emit + GATE + own.** AgentSpec writes `agentspec.yaml` (with `meta.loop_state.stage: spec`) and runs
+   `*validate-spec`. On FAIL, surface the field-pathed errors, fix the offending block, re-emit, re-gate.
+   On PASS, the reconciled spec is a trackable Definition AgentSpec OWNS — `*build` re-running against it
+   now cascade-updates the impl (def → impl, PR-001). When the sync yields spec WRITES that touch the
+   impl, `ai-engineer` applies them (gated).
+5. **Reconcile the EVAL leg (the third leg, W2I5).** When `ai-architect`'s freshness probe flags the eval
+   leg (`driftedLegs` contains `eval` — the impl amended past the eval criteria), it also drafts an
+   eval-criteria reconcile delta for the applicable leg (eval-suite criteria for an agent/skill subject,
+   code-quality criteria for a code subject). AgentSpec surfaces the delta to the operator (propose,
+   don't assume) exactly as for a spec field, then the **evaluator's criteria-maintenance hook**
+   (`reconcileEvalCriteria`) COMPUTES the grown set under the gate — an append-only upsert that never drops a
+   criterion (EV-053) — and the **evaluator session PERSISTS** `result.criteria` to the located artifact
+   (`persist-eval-criteria.ts` `persistEvalCriteria` → `.mutagent/evaluator/living-suite/<leg>.criteria.json`).
+   The hook COMPUTES; the persist is the WRITE — and that write bumps the artifact's freshness, which is what
+   returns the eval leg to `in-sync`. This is criteria maintenance, NOT judging; the evaluator stays
+   judge-only (EV-051). The spec leg and the eval leg move together so def → impl → eval never falls out of
+   lockstep.
+6. **Re-probe to confirm in-sync (closing self-heal).** After the gated writes land (spec via `ai-engineer`,
+   eval criteria via `persistEvalCriteria`), RE-RUN the freshness probe (`check-sync-spec.ts`) one final time.
+   The procedure only completes when it reports `in-sync` on every leg that drifted (`driftedLegs` empty);
+   `eval` still in `driftedLegs` means the criteria write was skipped or landed stale — the re-probe SURFACES
+   it so the persist can be re-run, rather than closing `*sync-spec` on an unpersisted (still-drifted) leg.
+
+> **Scope (subject-agnostic).** `*sync-spec` reads an arbitrary implementation surface (via
+> `ai-architect`); it embeds NO per-connector / per-app logic. The drift is detected by a deterministic
+> code predicate (`check-sync-spec.ts`, spec + eval legs); the reconcile itself is `ai-architect`
+> reasoning, session-dispatched (Model-B — code detects, the agent reconciles). Builder ALSO reuses
+> `ai-architect #sync-spec` build-internally when it detects drift mid-`*build`.
+
+---
+
+## `*validate-spec` — the schema gate (script)
+
+`kind: script` · `binds: scripts/validate/validate-spec.ts`. Reads a YAML spec path, parses it,
+validates against the frozen `agentspec.v0.1.0` contract (`scripts/contract/agentspec.schema.ts`),
+prints field-pathed errors + exits non-zero on failure, or `[validate-spec] PASS` + exit 0 on
+success. The worked template (`assets/templates/agentspec.yaml.tpl`) is asserted valid by the
+test suite — copy it as a starting point.
+
+---
+
+## `*build` — handoff to BUILD (`mutagent-builder`)
+
+`mutagent-agentspec` validates and emits `agentspec.yaml`. The next explicit operator command is
+`*build`, routed by Helix to `mutagent-builder`. BUILD consumes the validated Definition, reuses
+`ai-architect #sync-spec` build-internally when it detects drift, dispatches `ai-engineer` /
+`ai-architect`, runs TDD + spec implementation coverage, and emits the build report + EVALUATE handoff
+bundle. (The `*sync-spec` COMMAND is now owned by `mutagent-agentspec` — it delegates the same
+`ai-architect #sync-spec` read.)
+
+Agentspec does **not** keep an executable build owner row, build agents, or coverage gate. Its boundary
+ends at a schema-valid spec plus the handoff suggestion.
+
+---
+
+## `*eval` — eval-driven development handoff (OUTLINED — Wave-3)
+
+> A designed FEATURE at the doc/protocol level only — never a code import (PR-018). `mutagent-agentspec`
+> does NOT depend on an evaluator skill to run standalone.
+
+**Shape:** hand the built agent + its `definition.evals.success_criteria` to an evaluator (the ADL
+EVALUATE stage) for eval-driven development. The spec's success_criteria SEED the evaluator's
+eval-matrix (link, don't duplicate). When composed via Helix, `*eval` routes to the evaluator
+skill; standalone, agentspec emits the eval criteria + (optionally) a thin self-contained eval stub.
+The triad (spec ↔ impl ↔ eval) stays in lockstep with auto-spec-correction (PR-011) — the mechanism
+lands with this stage.
+
+---
+
+## Loop position + transitions (PR-009)
+
+The orchestrator KNOWS the next stage and proactively SUGGESTS it + renders loop position (read from
+`meta.loop_state.stage`), but EVERY transition needs explicit operator confirmation. "Auto-orchestrate"
+means suggest, never auto-run. Never auto-advance through a gate.

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

@@ -0,0 +1,116 @@
+/**
+ * scripts/cli/doctor.ts
+ * Runtime probe + JSON health report.
+ * Type A — Pure Script (deterministic environment inspection).
+ *
+ * Detects the JS runtime (bun | pnpm-tsx | npx-tsx | node), reports the SKILL.md version, the
+ * lock-file present in the skill root, and whether git is available. agentspec has NO external
+ * provider deps (no Langfuse/Google), so there is NO required-env-var probe — keeping doctor lean.
+ *
+ * Usage: scripts/cli/run.sh scripts/cli/doctor.ts
+ * Output: { runtime, version, lockFile, gitAvailable, errors[] }
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join, resolve } from "node:path";
+
+export type DoctorRuntime = "bun" | "pnpm-tsx" | "npx-tsx" | "node";
+
+export interface DoctorReport {
+  /** JS runtime executing this skill's scripts. */
+  runtime: DoctorRuntime;
+  /** Skill version string from SKILL.md frontmatter/metadata, or null if unreadable. */
+  version: string | null;
+  /** Lock-file detected in the skill root, or null. */
+  lockFile: string | null;
+  /** Whether `git` is available in PATH. */
+  gitAvailable: boolean;
+  /** Non-fatal warnings. Exit code is still 0. */
+  errors: string[];
+}
+
+/**
+ * Detect the JS runtime executing this script.
+ *   1. Bun: process.versions.bun set under Bun.
+ *   2. pnpm-tsx: npm_config_user_agent starts with "pnpm".
+ *   3. npx-tsx: npm_execpath set (npm/npx).
+ *   4. node: bare node fallback.
+ */
+export function detectJsRuntime(): DoctorRuntime {
+  const versions = process.versions as Record<string, string | undefined>;
+  if (versions.bun) return "bun";
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  if (userAgent.startsWith("pnpm")) return "pnpm-tsx";
+  if (process.env.npm_execpath) return "npx-tsx";
+  return "node";
+}
+
+/**
+ * Read the skill version from SKILL.md (the `version:` key, possibly indented under `metadata:`).
+ * Returns null if SKILL.md is absent or the version field is missing.
+ * SKILL.md lives at <skill-root>/SKILL.md; this script is at <skill-root>/scripts/cli/doctor.ts.
+ */
+export function readSkillVersion(scriptDir: string): string | null {
+  const skillMd = resolve(scriptDir, "../..", "SKILL.md");
+  if (!existsSync(skillMd)) return null;
+  try {
+    const content = readFileSync(skillMd, "utf8");
+    const match = content.match(/^\s*version:\s*["']?([^"'\n\r]+?)["']?\s*$/m);
+    return match ? match[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Detect the first lock file present in `dir`. */
+export function detectLockFile(dir: string): string | null {
+  const candidates = ["bun.lockb", "bun.lock", "pnpm-lock.yaml", "package-lock.json", "yarn.lock"];
+  for (const name of candidates) {
+    if (existsSync(join(dir, name))) return name;
+  }
+  return null;
+}
+
+/** Check whether `git` is available in PATH. */
+export function checkGitAvailable(): boolean {
+  try {
+    execSync("git --version", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run the full doctor probe and return a structured report. Never throws. */
+export function runDoctor(): DoctorReport {
+  const errors: string[] = [];
+  const scriptDir = realpathSync(
+    import.meta.dirname ??
+      import.meta.url.replace(/^file:\/\//, "").replace(/\/[^/]+$/, ""),
+  );
+
+  const runtime = detectJsRuntime();
+  const version = readSkillVersion(scriptDir);
+  const lockFile = detectLockFile(resolve(scriptDir, "../.."));
+  const gitAvailable = checkGitAvailable();
+
+  if (!gitAvailable) {
+    errors.push("git not found in PATH — branch-hygiene operations will fail");
+  }
+  if (version === null) {
+    errors.push("Could not read SKILL.md version");
+  }
+
+  return { runtime, version, lockFile, gitAvailable, errors };
+}
+
+// ── CLI entrypoint ────────────────────────────────────────────────────────────
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const report = runDoctor();
+  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  process.exit(0);
+}

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

@@ -0,0 +1,230 @@
+/**
+ * scripts/cli/init.ts
+ * LEAN cross-platform installer for mutagent-agentspec.
+ * Invoked as: pnpx @mutagent/agentspec init
+ *
+ * Wave-1 keeps this minimal — NO onboarding FSM (that is a later wave). init's whole job:
+ *   1. Detect installed coding-agent platforms via home markers (~/.claude, ~/.codex).
+ *   2. Copy the skill tree into the install target:
+ *        project (DEFAULT) → <cwd>/.claude/skills/mutagent-agentspec  (and .codex)
+ *        global (--global)  → ~/.claude/skills/mutagent-agentspec      (and ~/.codex)
+ *   3. Copy the two shipped sub-agent contracts (assets/agents/*.md) into <target>/.claude/agents.
+ *
+ * cwd discipline: the SOURCE skill dir is resolved from import.meta (correct through any symlink
+ * chain); the install TARGET root is the user's invocation cwd (process.cwd()), NEVER the script
+ * dir — overriding it would install the skill into itself.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  mkdirSync,
+  cpSync,
+  copyFileSync,
+  realpathSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+export type Scope = "project" | "global";
+export type PlatformId = "claude-code" | "codex";
+
+export interface DetectedPlatform {
+  id: PlatformId;
+  label: string;
+  /** Home marker probed to decide whether the platform exists on this machine. */
+  detectionMarker: string;
+  detected: boolean;
+  /** Where the skill tree is installed (follows scope). */
+  skillInstallPath: string;
+  /** Where the sub-agent .md files are installed (follows scope). */
+  agentsInstallPath: string;
+}
+
+export interface PlatformInstallResult {
+  platform: PlatformId;
+  success: boolean;
+  steps: Array<{ step: string; ok: boolean; note: string }>;
+  errors: string[];
+}
+
+/** Resolve install scope from argv. DEFAULT is project-local; `--global` opts into the home dir. */
+export function resolveScope(argv: string[]): Scope {
+  return argv.includes("--global") ? "global" : "project";
+}
+
+/**
+ * Probe the filesystem for installed coding-agent platforms. Detection uses HOME markers (does the
+ * runtime exist on this machine?); the install TARGET follows `scope`:
+ *   project (DEFAULT) → <cwd>/.claude|.codex/…   global → <home>/.claude|.codex/…
+ */
+export function detectInstalledPlatforms(
+  cwd: string = process.cwd(),
+  scope: Scope = "project",
+  home: string = homedir(),
+): DetectedPlatform[] {
+  const claudeRoot = scope === "global" ? join(home, ".claude") : join(cwd, ".claude");
+  const codexRoot = scope === "global" ? join(home, ".codex") : join(cwd, ".codex");
+  return [
+    {
+      id: "claude-code",
+      label: "Claude Code",
+      detectionMarker: join(home, ".claude"),
+      detected: existsSync(join(home, ".claude")),
+      skillInstallPath: join(claudeRoot, "skills", "mutagent-agentspec"),
+      agentsInstallPath: join(claudeRoot, "agents"),
+    },
+    {
+      id: "codex",
+      label: "Codex",
+      detectionMarker: join(home, ".codex"),
+      detected: existsSync(join(home, ".codex")),
+      skillInstallPath: join(codexRoot, "skills", "mutagent-agentspec"),
+      agentsInstallPath: join(codexRoot, "agents"),
+    },
+  ];
+}
+
+/**
+ * Install the skill + its sub-agent contracts to a single platform.
+ * Pure-ish: all filesystem effects are scoped to the platform's install paths; the source dir is
+ * injected so the function is testable against temp trees.
+ */
+export function installToPlatform(
+  platform: DetectedPlatform,
+  skillSourceDir: string,
+  force = false,
+): PlatformInstallResult {
+  const result: PlatformInstallResult = {
+    platform: platform.id,
+    success: false,
+    steps: [],
+    errors: [],
+  };
+
+  // ── Step 1: copy the skill tree ──────────────────────────────────────────────
+  const skillDest = platform.skillInstallPath;
+  try {
+    if (existsSync(skillDest) && !force) {
+      result.steps.push({
+        step: "copy-skill",
+        ok: true,
+        note: `Skill already exists at ${skillDest} (use --force to overwrite).`,
+      });
+    } else {
+      mkdirSync(skillDest, { recursive: true });
+      cpSync(skillSourceDir, skillDest, { recursive: true, force: true });
+      result.steps.push({ step: "copy-skill", ok: true, note: `Copied skill to ${skillDest}.` });
+    }
+  } catch (err) {
+    const msg = `Failed to copy skill to ${skillDest}: ${err instanceof Error ? err.message : String(err)}`;
+    result.steps.push({ step: "copy-skill", ok: false, note: msg });
+    result.errors.push(msg);
+    return result;
+  }
+
+  // ── Step 2: copy the shipped sub-agent contracts ─────────────────────────────
+  const agentsSrc = join(skillSourceDir, "assets", "agents");
+  const agentsDest = platform.agentsInstallPath;
+  try {
+    if (existsSync(agentsSrc)) {
+      const agentFiles = readdirSync(agentsSrc).filter((f) => f.endsWith(".md"));
+      mkdirSync(agentsDest, { recursive: true });
+      for (const f of agentFiles) {
+        copyFileSync(join(agentsSrc, f), join(agentsDest, f));
+      }
+      result.steps.push({
+        step: "install-agents",
+        ok: true,
+        note: `Installed ${agentFiles.length} sub-agent contract(s) to ${agentsDest}.`,
+      });
+    } else {
+      result.steps.push({ step: "install-agents", ok: true, note: "No assets/agents/ — skipped." });
+    }
+  } catch (err) {
+    const msg = `Failed to install agents to ${agentsDest}: ${err instanceof Error ? err.message : String(err)}`;
+    result.steps.push({ step: "install-agents", ok: false, note: msg });
+    result.errors.push(msg);
+  }
+
+  result.success = result.errors.length === 0;
+  return result;
+}
+
+// ── Usage ─────────────────────────────────────────────────────────────────────
+const USAGE = `
+mutagent-agentspec init — cross-platform skill installer
+
+USAGE
+  pnpx @mutagent/agentspec init [--global] [--yes] [--force]
+
+INSTALL SCOPE
+  (default)   PROJECT-LOCAL — install into the directory you ran init in:
+                Claude Code → <cwd>/.claude/…   Codex → <cwd>/.codex/…
+  --global    HOME DIR      — install into ~/.claude/… and ~/.codex/…
+
+OPTIONS
+  --global    Install into the home dir instead of the project (default: project-local)
+  --yes       Non-interactive: install to all detected platforms
+  --force     Overwrite an existing skill install
+  --help      Show this message
+
+After install, open your coding agent and invoke the skill, then *spec to begin.
+`.trim();
+
+// ── CLI entrypoint ──────────────────────────────────────────────────────────────
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const argv = (typeof Bun !== "undefined" ? Bun.argv : process.argv).slice(2);
+
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(USAGE + "\n");
+    process.exit(0);
+  }
+
+  const scope = resolveScope(argv);
+  const force = argv.includes("--force");
+  const cwd = process.cwd();
+
+  // SOURCE skill dir = two levels up from scripts/cli/ (resolved through symlinks).
+  const scriptDir = realpathSync(
+    import.meta.dirname ??
+      import.meta.url.replace(/^file:\/\//, "").replace(/\/[^/]+$/, ""),
+  );
+  const skillDir = resolve(scriptDir, "..", "..");
+
+  const platforms = detectInstalledPlatforms(cwd, scope).filter((p) => p.detected);
+  if (platforms.length === 0) {
+    process.stderr.write(
+      "[init] No coding-agent platforms detected (~/.claude or ~/.codex).\n" +
+        "  Install Claude Code or Codex first, then re-run init.\n",
+    );
+    process.exit(1);
+  }
+
+  process.stdout.write(
+    `[init] Install scope: ${scope}${scope === "project" ? ` (${cwd})` : " (home dir)"}\n`,
+  );
+
+  let anyFailure = false;
+  for (const platform of platforms) {
+    process.stdout.write(`\n[init] Installing to ${platform.label}...\n`);
+    const r = installToPlatform(platform, skillDir, force);
+    for (const step of r.steps) {
+      process.stdout.write(`  ${step.ok ? "ok" : "FAIL"} ${step.step}: ${step.note}\n`);
+    }
+    if (r.success) {
+      process.stdout.write(`[init] ${platform.label}: install complete.\n`);
+      if (platform.id === "claude-code") {
+        process.stdout.write("  Restart your Claude Code session, then invoke *spec.\n");
+      }
+    } else {
+      process.stderr.write(`[init] ${platform.label}: FAILED — ${r.errors.join("; ")}\n`);
+      anyFailure = true;
+    }
+  }
+
+  process.exit(anyFailure ? 1 : 0);
+}