cyber-aced 0.3.0

package/skills/init-aced/README.md

@@ -0,0 +1,5 @@
+# init-aced
+
+Registers ACED as an SDD plugin for agent-configuration domains (`skill`, `subagent`, `command`, `agents-section`) by writing a role-map entry to `.agents/universal-plugin.json` under `sdd-plugins[]`. Once registered, the conductor resolves the ACED production-chain roles — `aced-scenario-writer` (spec-producer), `aced-spec-validator` (spec-judge), `aced-impl-judge` (impl-judge) — by reading only that one file at runtime (no plugin-directory scanning).
+
+Idempotent: re-running rewrites an old-shape or version-stale entry in place (rewrite-on-init migration). Spec creation itself is owned by the `sdd` plugin's `start-mission` / `spec-gate`; this skill only wires the registry.

package/skills/init-aced/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: init-aced
+description: Use this skill to register ACED as the SDD plugin for agent-configuration domains — writes an aced role-map entry to .agents/universal-plugin.json so the conductor resolves the ACED production-chain roles for skills, subagents, commands, and AGENTS.md sections.
+---
+
+# Init ACED
+
+Register ACED in the project's SDD plugin registry so the conductor resolves the ACED production-chain roles by reading **only** `.agents/universal-plugin.json` — no plugin-directory scanning at runtime (the lockfile pattern).
+
+## Workflow
+
+### 1. Locate the registry file
+
+Look for `.agents/universal-plugin.json` at the project root. If it exists, read and parse it; otherwise create it with `{}`.
+
+**Fail closed on a corrupt file.** If the file exists but contains malformed JSON, **fail with an error and stop — do not overwrite it**. Silently rewriting a corrupt file could destroy valid entries from other plugins; leave the file untouched and let a human repair it.
+
+### 2. Determine the ACED version
+
+Read ACED's own version from its plugin manifest (it ships inside the plugin, so it knows its version for free). Use it as the `version` stamp.
+
+### 3. Write the aced entry (rewrite-on-init migration)
+
+Find the entry where `"name": "aced"` in the `sdd-plugins` array:
+
+- **Not found** → append the canonical entry (create the array if absent).
+- **Found, old shape** (the legacy `scenario-advisor` / `implementer` keys, or the legacy `domains[]` + shared `roles`/`governances`) → **rewrite** it to the `squads[]` shape below.
+- **Found, `squads[]` shape, stale `version`** → rewrite when the recorded version differs (install / upgrade / manual re-run reconciles drift here; the conductor never compares versions at runtime).
+
+Do not reorder or reformat other entries.
+
+**Canonical entry:**
+
+```json
+{
+  "name": "aced",
+  "version": "<aced version>",
+  "squads": [
+    {
+      "artifact-types": ["skill", "subagent", "command", "agents-section"],
+      "roles": {
+        "spec-producer": "aced-scenario-writer",
+        "solution-producer": null,
+        "spec-judge": "aced-spec-validator",
+        "impl-producer": null,
+        "impl-judge": "aced-impl-judge"
+      },
+      "governances": {
+        "oracle-spec": null,
+        "builder-spec": "aced-builder-spec",
+        "builder-impl": "aced-builder-impl",
+        "architect-spec": null,
+        "architect-impl": null
+      }
+    }
+  ]
+}
+```
+
+ACED serves its four agent-config artifact-types with one squad. `impl-producer: null` — writing the agent config is done by the `define-agent` / `define-command` / `improve` skills or the SDD-default impl-producer (the conductor running `impl-producer-governance` via a spawned builder), not a bound impl-producer agent. `solution-producer: null` uses the SDD default. ACED binds its own `builder-spec` (`aced-builder-spec`) and `builder-impl` (`aced-builder-impl`) bars; each remaining `null` governance uses the SDD default actor-gate bar.
+
+**Each squad's `governances` block is required.** Every squad must carry a `governances` map (each binding may be `null`, but the block itself must be present). Reject a payload with a squad missing its `governances` block — fail with an error and **do not write** the file.
+
+### 4. Write the updated file
+
+Write `.agents/universal-plugin.json` back with the updated contents.
+
+### 5. Ensure ACED run output is git-ignored
+
+Run `scripts/ensure-results-ignored.mts` (this skill's own `scripts/` dir) to ensure `.agents/aced/results/` — the shared ACED run-output directory `run` writes to — is git-ignored at the repo root. Idempotent; a non-zero exit means it could not guarantee the ignore (e.g. not inside a git repo) — surface that to the user rather than continuing silently.
+
+### 6. Report
+
+Confirm the `.agents/universal-plugin.json` aced entry is present under `sdd-plugins`, stamped with the ACED version, with a squad serving artifact-types `skill`, `subagent`, `command`, `agents-section`.
+
+Next step: use `sdd:start-mission` (sdd plugin) to scaffold an agent-configuration spec; the conductor resolves the ACED roles automatically.

package/skills/init-aced/scripts/ensure-results-ignored.mts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// ensure-results-ignored — setup/ignore-run-output's deterministic engine. Ensures the ACED
+// run-output directory (.agents/aced/results/) is git-ignored at the repo root, so `run` never
+// commits timestamped, non-deterministic judge output into the tracked tree.
+//
+// Behavior (frozen — see .agents/specs/aced/setup/ignore-run-output/):
+//   1. Resolve the git repo root from the start directory. Not inside a repo -> fail closed, write
+//      nothing.
+//   2. If the results directory is already effectively ignored (git check-ignore on a probe path
+//      succeeds) -> no-op, exit 0, write nothing.
+//   3. Else, if .gitignore is not writable/creatable -> fail closed, before any write.
+//   4. Else append the rule as the LAST line of .gitignore (creating it if absent, preserving every
+//      existing line). Appending last is load-bearing: gitignore's last-match-wins guarantees the
+//      path ends ignored even if an earlier `!`-negation re-included it. There is no post-write
+//      verification branch — the guarantee holds by construction.
+//
+// Idempotent: a second run finds the path already ignored and writes nothing, so exactly one
+// matching rule ever exists. Pure functions are exported for node:test; running the file directly
+// drives the CLI. No deps beyond node:fs, node:path, node:child_process.
+
+import { execFileSync } from 'node:child_process'
+import { accessSync, constants, existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// The rule ensured in .gitignore — the ACED run-output directory.
+export const RESULTS_DIR_RULE = '.agents/aced/results/'
+// A path under the results directory used to probe `git check-ignore` — never created on disk.
+const PROBE_PATH = '.agents/aced/results/.ensure-ignored-probe'
+
+// Resolve the git repo root from `startDir`, or null when it is not inside a git repository.
+export function resolveRepoRoot(startDir: string): string | null {
+	try {
+		const out = execFileSync('git', ['-C', startDir, 'rev-parse', '--show-toplevel'], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		return out.trim()
+	} catch {
+		return null
+	}
+}
+
+// True when `relPath` (repo-relative) is reported ignored by git under `repoRoot`.
+export function isIgnored(repoRoot: string, relPath: string): boolean {
+	try {
+		execFileSync('git', ['-C', repoRoot, 'check-ignore', '-q', relPath], { stdio: 'ignore' })
+		return true
+	} catch {
+		return false
+	}
+}
+
+// True when .gitignore at `repoRoot` can be written — writable if it exists, else the repo root
+// must be writable so the file can be created.
+export function canWriteGitignore(repoRoot: string): boolean {
+	const file = join(repoRoot, '.gitignore')
+	try {
+		if (existsSync(file)) accessSync(file, constants.W_OK)
+		else accessSync(repoRoot, constants.W_OK)
+		return true
+	} catch {
+		return false
+	}
+}
+
+// Append `rule` as the LAST line of .gitignore at `repoRoot`, creating the file (whose content is
+// then just the rule) if absent, and preserving every pre-existing line untouched.
+function appendRuleLast(repoRoot: string, rule: string): void {
+	const file = join(repoRoot, '.gitignore')
+	let content = ''
+	if (existsSync(file)) {
+		content = readFileSync(file, 'utf8')
+		if (content.length > 0 && !content.endsWith('\n')) content += '\n'
+	}
+	content += `${rule}\n`
+	writeFileSync(file, content)
+}
+
+export type EnsureResult = { ok: true; changed: boolean; repoRoot: string } | { ok: false; reason: string }
+
+// The engine's whole behavior, starting from `startDir`. Never throws.
+export function ensureResultsIgnored(startDir: string): EnsureResult {
+	const repoRoot = resolveRepoRoot(startDir)
+	if (!repoRoot) return { ok: false, reason: 'not inside a git repository' }
+
+	if (isIgnored(repoRoot, PROBE_PATH)) return { ok: true, changed: false, repoRoot }
+
+	if (!canWriteGitignore(repoRoot)) return { ok: false, reason: '.gitignore is not writable or creatable' }
+
+	appendRuleLast(repoRoot, RESULTS_DIR_RULE)
+	return { ok: true, changed: true, repoRoot }
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+export function main(argv: string[]): number {
+	const root = flag(argv, '--root') ?? '.'
+	const w = (s: string) => process.stdout.write(`${s}\n`)
+
+	const r = ensureResultsIgnored(root)
+	if (!r.ok) {
+		w(`refused: ${r.reason}`)
+		return 1
+	}
+	w(r.changed ? `${RESULTS_DIR_RULE} appended to .gitignore at ${r.repoRoot}` : `already ignored under ${r.repoRoot}`)
+	return 0
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/list-skills/README.md

@@ -0,0 +1,19 @@
+# list-skills
+
+Internal, non-invokable ACED engine — loaded in-session by the `manage` gateway, not triggered
+directly. It reports what skills are installed.
+
+## What it does
+
+Scans the four fixed skill sources — repo-private (`.agents/skills`), repo-public (`skills/`),
+user-global (`~/.agents/skills`), and the cyberplace package's shipped skills directory — keeping
+only directories that contain a `SKILL.md`. Duplicate names are deduped with **repo taking
+precedence** over global/package. An optional `--grep` glob (`*`/`?`) filters by skill name.
+
+Each surviving skill is reported with its **name**, **foundIn** source, **description**, and
+whether it is **package-managed** (its `skill.json` declares `distribution.install_via:
+"package_manager"`). The report is sorted alphabetically by name and can be printed as text
+(default) or `--format json`.
+
+Read-only — it never writes a `SKILL.md`, manifest, or any other file. Ported from the cyberplace
+CLI's `skill list` command (`packages/cyberplace/src/skill/list.ts`).

package/skills/list-skills/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: list-skills
+description: "Partial Skill: invoke by name only — the ACED manage-gateway skill-inventory engine — loaded in-session by the manage gateway, not user-triggered."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# list-skills
+
+The concrete **discovery engine** for the ACED skill inventory — scans the four fixed skill
+sources, dedupes, filters, and reports what is installed. It is **read-only**: it never writes a
+`SKILL.md`, a manifest, or any other file. Validating or repairing skill content is a different
+engine (`repair-private-skills`); maintaining the per-model runner family is
+`manage-model-runners`. Loaded **in-session** by the `manage` gateway; **not user-invocable**.
+
+## The four sources (scan order, dedupe precedence)
+
+| Source | Location | `foundIn` |
+|---|---|---|
+| Repo-private | `<root>/.agents/skills` | `repo` |
+| Repo-public | `<root>/skills` | `repo` |
+| User-global | `~/.agents/skills` | `global` |
+| Package | the cyberplace package's shipped `skills/` directory | `package` |
+
+A directory counts as a skill only when it contains a `SKILL.md`. A name found in more than one
+source is reported **once** — the earlier-scanned source wins, so `repo` beats `global`/`package`.
+
+## Run the engine
+
+```bash
+node "<skill>/scripts/list-skills.mts" [--root .] [--grep <pattern>] [--format json]
+```
+
+| Flag | Effect |
+|---|---|
+| `--root <path>` | repo root to scan for the two repo sources (default `.`) |
+| `--grep <pattern>` | `*`/`?` glob filter over skill **name** only; omitted = every discovered skill |
+| `--format json` | emit the report as JSON (`name`, `description`, `foundIn`, `packageManaged`); default is a human-readable text list |
+
+Each reported skill carries: **name** (frontmatter `name:`, falling back to the directory name when
+omitted), **foundIn** (`repo` \| `global` \| `package`), **description** (frontmatter
+`description:`), and **packageManaged** (`true` when the skill's `skill.json` declares
+`distribution.install_via: "package_manager"`). The report is sorted **alphabetically by name**.
+
+## Boundaries
+
+Read-only inventory — it inspects `SKILL.md` frontmatter and an optional `skill.json` manifest per
+directory and writes nothing. It does not validate skill content, repair broken frontmatter, or
+touch the per-model runner family; those are separate engines.
+
+When `node` is absent, an agent performs the same scan by hand: walk the four source directories,
+keep only subdirectories with a `SKILL.md`, parse the `name:`/`description:` frontmatter (directory
+name as fallback), dedupe by name keeping the first-scanned (repo-first) copy, apply the glob
+filter if one was given, and sort the result alphabetically by name.

package/skills/list-skills/scripts/list-skills.mts

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// list-skills — the concrete discovery engine for the ACED `manage` gateway's skill inventory. It
+// scans the four fixed skill sources — repo-private (.agents/skills), repo-public (skills/),
+// user-global (~/.agents/skills), and the cyberplace package's shipped skills dir — dedupes by
+// name (repo takes precedence over global/package), applies an optional --grep glob filter, and
+// reports each surviving skill's name, foundIn source, description, and package-managed status.
+//
+// Read-only: it never writes a SKILL.md, a manifest, or any other file. Validating or repairing
+// skill content is a different engine's job; this one only inventories what is installed.
+//
+// Ported from packages/cyberplace/src/skill/list.ts + manifest.ts + hook/package-root.ts, folded
+// into one self-contained file per the repo's node-≥23.6 / no-deps convention (import ONLY
+// node:*). Pure functions are exported for node:test; running the file directly drives the CLI.
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// ── package root (inlined + adapted from hook/package-root.ts) ──
+
+// Walks up from a starting directory until a package.json is found. Mirrors the cyberplace CLI's
+// original getPackageRoot algorithm, used here as the last-resort candidate.
+function walkUpForPackageJson(startDir: string): string | undefined {
+	let dir = startDir
+	while (dir !== dirname(dir)) {
+		if (existsSync(join(dir, 'package.json'))) return dir
+		dir = dirname(dir)
+	}
+	return undefined
+}
+
+// Locates the cyberplace package's root — the source of its shipped `skills/` directory (the
+// "package" scan source). This script is not itself bundled inside cyberplace, so it cannot rely
+// on walking up from its own module location the way the original CLI helper did; instead it
+// tries, in order: an installed dependency under the scanned repo's node_modules, this monorepo's
+// own packages/cyberplace workspace sibling, then falls back to walking up from this module's own
+// file location (covering the case this script is ever vendored inside the package itself).
+// Never throws — an unresolved package root simply yields no "package" source skills.
+export function getPackageRoot(root = '.'): string {
+	const candidates = [join(root, 'node_modules', 'cyberplace'), join(root, 'packages', 'cyberplace')]
+	for (const candidate of candidates) {
+		if (existsSync(join(candidate, 'package.json'))) return candidate
+	}
+	return walkUpForPackageJson(dirname(fileURLToPath(import.meta.url))) ?? root
+}
+
+// ── skill manifest (inlined from skill/manifest.ts) ──
+
+export interface SkillManifest {
+	distribution?: {
+		install_via: string
+		package?: { name: string; bin?: string }
+	}
+}
+
+// Reads a skill directory's skill.json, if present. Returns null when absent or malformed —
+// package-managed status then defaults to false, never throws.
+export function readSkillManifest(skillDir: string): SkillManifest | null {
+	const filePath = join(skillDir, 'skill.json')
+	if (!existsSync(filePath)) return null
+	try {
+		return JSON.parse(readFileSync(filePath, 'utf8')) as SkillManifest
+	} catch {
+		return null
+	}
+}
+
+export function isPackageManaged(manifest: SkillManifest | null): boolean {
+	return manifest?.distribution?.install_via === 'package_manager'
+}
+
+// ── discovery (inlined + extended from skill/list.ts) ──
+
+export type SkillLocation = 'repo' | 'global' | 'package'
+
+export interface SkillSummary {
+	name: string
+	description: string
+	foundIn: SkillLocation
+	packageManaged: boolean
+}
+
+function parseFrontmatter(content: string): { name: string; description: string } {
+	const lines = content.split('\n')
+	let fmCount = 0
+	let name = ''
+	let description = ''
+
+	for (const line of lines) {
+		if (line.trim() === '---') {
+			fmCount++
+			if (fmCount === 2) break
+			continue
+		}
+		if (fmCount !== 1) continue
+
+		const nameMatch = line.match(/^name:\s*(.+)/)
+		if (nameMatch) name = nameMatch[1]!.trim().replace(/^["']|["']$/g, '')
+
+		const descMatch = line.match(/^description:\s*(.+)/)
+		if (descMatch) description = descMatch[1]!.trim().replace(/^["']|["']$/g, '')
+	}
+
+	return { name, description }
+}
+
+// Compile a `*`/`?` glob pattern (name-only, no path separators) into a full-match RegExp.
+export function globToRegExp(pattern: string): RegExp {
+	let regex = ''
+	for (const char of pattern) {
+		if (char === '*') regex += '.*'
+		else if (char === '?') regex += '.'
+		else if (/[.+^${}()|[\]\\]/.test(char)) regex += `\\${char}`
+		else regex += char
+	}
+	return new RegExp(`^${regex}$`)
+}
+
+function collectSkillsFromDir(dir: string, foundIn: SkillLocation): SkillSummary[] {
+	if (!existsSync(dir)) return []
+
+	const results: SkillSummary[] = []
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue
+
+		const skillDir = join(dir, entry.name)
+		const skillFile = join(skillDir, 'SKILL.md')
+		if (!existsSync(skillFile)) continue
+
+		const { name, description } = parseFrontmatter(readFileSync(skillFile, 'utf8'))
+		results.push({
+			name: name || entry.name,
+			description,
+			foundIn,
+			packageManaged: isPackageManaged(readSkillManifest(skillDir)),
+		})
+	}
+
+	return results
+}
+
+export interface ListSkillsOptions {
+	grep?: string
+	home?: string
+	packageRoot?: string
+}
+
+// Scan the four fixed sources, dedupe by name (repo > global > package, matching scan order),
+// apply the optional --grep glob filter, and return the surviving skills sorted alphabetically.
+export function listSkills(root: string, options: ListSkillsOptions = {}): SkillSummary[] {
+	const grep = options.grep ? globToRegExp(options.grep) : undefined
+	const home = options.home ?? homedir()
+	const packageRoot = options.packageRoot ?? getPackageRoot(root)
+
+	const sources: { dir: string; foundIn: SkillLocation }[] = [
+		{ dir: join(root, '.agents', 'skills'), foundIn: 'repo' },
+		{ dir: join(root, 'skills'), foundIn: 'repo' },
+		{ dir: join(home, '.agents', 'skills'), foundIn: 'global' },
+		{ dir: join(packageRoot, 'skills'), foundIn: 'package' },
+	]
+
+	const seen = new Set<string>()
+	const results: SkillSummary[] = []
+
+	for (const { dir, foundIn } of sources) {
+		for (const skill of collectSkillsFromDir(dir, foundIn)) {
+			if (seen.has(skill.name)) continue
+			if (grep && !grep.test(skill.name)) continue
+
+			seen.add(skill.name)
+			results.push(skill)
+		}
+	}
+
+	return results.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+function formatText(skills: SkillSummary[]): string {
+	if (skills.length === 0) return 'No skills found.'
+	return skills
+		.map((s) => `${s.name}  [${s.foundIn}]${s.packageManaged ? ' (package-managed)' : ''}\n  ${s.description}`)
+		.join('\n')
+}
+
+export function main(argv: string[]): number {
+	const root = flag(argv, '--root') ?? '.'
+	const grep = flag(argv, '--grep')
+	const format = flag(argv, '--format') ?? 'text'
+
+	const skills = listSkills(root, { grep })
+
+	if (format === 'json') {
+		process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`)
+	} else {
+		process.stdout.write(`${formatText(skills)}\n`)
+	}
+	return 0
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/manage/README.md

@@ -0,0 +1,35 @@
+# manage
+
+The manage-level front door to ACED — a thin dispatcher for **non-mission** work on the agent-config
+tooling ACED evaluates.
+
+## When to use
+
+Use this skill for work that is neither authoring a config nor scoring one:
+
+- Set up the per-model **runner agents** used to benchmark skills
+- **List** the current model runners
+- **Remove** a model runner
+
+Good triggers: "set up the model runners", "list the runners", "remove the haiku runner". If you
+instead want to *create* an agent or skill, use `define-agent` / `define-skill`; to *score* a config,
+use `run`; to *change what ACED specifies*, use `start-mission`.
+
+## What it does
+
+`manage` classifies the request and **loads the matching engine in the current session** — it spawns
+nothing, opens no change request, invokes no gate, and writes no contract state. When the operation
+is named it takes the fast path; on a bare invocation it asks a menu of at most four options.
+
+Today it routes one group:
+
+| Group | Engine |
+|---|---|
+| **Config runners** — set up / list / remove per-model runner agents | `manage-model-runners` (internal) |
+
+The table grows as more manage-level ACED engines land.
+
+## Boundaries
+
+`manage` never changes what ACED specifies. Authoring redirects to `define-agent` / `define-skill`,
+scoring to the eval-run skills, and a change to ACED's own behavior to `start-mission`.

package/skills/manage/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: manage
+description: Use this skill when doing manage-level (non-mission) ACED work — inspecting or maintaining the agent-config tooling ACED evaluates, such as "set up the per-model runner agents", "list the model runners", "list the installed skills", or "validate/repair the repo-private skills". Routes to the matching engine; it does not author a config (define-agent / define-skill) or change what ACED specifies (start-mission).
+---
+
+# manage
+
+The **manage-level** front door to ACED — the user-facing handler for **non-mission** work on the
+agent-config tooling corpus. Where `define-agent` / `define-skill` **author** a config and `run` /
+`add-scenario` **score** one, `manage` does the work that is neither: **inspect and maintain** the
+tooling ACED evaluates.
+
+`manage` is a **thin dispatcher**: it classifies a manage request and **loads the matching engine in
+the current session**, holding **no production logic**, loading **no governance**, and writing **no
+contract state**. It **opens no CR**, **invokes no gate**, and **performs no behavior change** itself.
+
+> **Manage picks no model.** The model + effort a piece of work needs is set by the **engine you
+> load**. The loaded engine advises; the user switches manually. (`manage` cannot switch the session
+> model itself.)
+
+## Intake
+
+- **Fast path — skip the menu.** When the invocation already **names the operation** — "set up the
+  model runners", "list the runners", "remove the haiku runner" — load the matching engine directly,
+  no menu.
+- **Menu — bare invocation.** When `manage` is invoked with **no operation named**, do not guess. Ask
+  via `AskUserQuestion`, presenting **at most four options** (the tool rejects more than four) and
+  never truncating silently. The route groups today (**Config runners**, **Skill corpus**) fit the
+  four-option rule; as more manage-level engines land, group the menu so a bare invocation still
+  resolves within it.
+
+## The routing table — request → engine
+
+Classification routes a manage request to the **engine** that handles it. The table grows as more
+manage-level ACED engines land:
+
+| Group | Request | Engine (handler) |
+|---|---|---|
+| **Config runners** | set up / list / remove per-model runner agents used to benchmark skills | **`manage-model-runners`** — internal, non-invokable; loaded here |
+| **Skill corpus** | list / inventory the installed skills across the repo, the user-global install, and the shipped package | **`list-skills`** — internal, non-invokable; loaded here |
+| **Skill corpus** | validate / repair repo-private skill metadata under `.agents/skills` | **`repair-private-skills`** — internal, non-invokable; loaded here |
+| **Skill corpus** | list / add / remove / preview the extra skill-scan locations the validate engine uses | **`manage-skill-dirs`** — internal, non-invokable; loaded here |
+
+## Load the engine in-session
+
+When the route resolves, **load the matched engine in the current session** and run it directly —
+**spawn nothing**. Write-capable operations stay **owned by their engine**: `manage-model-runners`
+writes its runner agent-def files and their symlinks; `repair-private-skills` writes only under
+`.agents/skills`; `manage-skill-dirs` writes only `.agents/aced/skill-dirs.toml`; `list-skills` is
+read-only. `manage` only routes.
+
+## Non-mission — the boundary
+
+`manage` maintains and inspects the ACED tooling corpus; it **never changes what ACED specifies**.
+
+- **Opens no CR, invokes no gate, writes no `status` / `approval`.** Those belong to `start-mission`
+  and the internal gates.
+- **Authoring is not manage.** A request to **create or improve** an agent definition or a workflow
+  skill is redirected to **`define-agent`** / **`define-skill`**, not handled here.
+- **Scoring is not manage.** A request to **run or score** a config's eval suite defers to the
+  **eval-run** skills (`run` / `compare` / `report`).
+- **A change to what ACED specifies** — adding or revising ACED's own behavior — is redirected to
+  **`start-mission`**, which opens a CR and runs the mission loop.
+- **Thin classifier.** Classifying loads **no governance** and holds **no production logic** — it
+  only loads the matched engine.

package/skills/manage-model-runners/README.md

@@ -0,0 +1,25 @@
+# manage-model-runners
+
+Internal, non-invokable ACED engine — loaded in-session by the `manage` gateway, not triggered
+directly. It maintains a family of **runner agent definitions, one per model**, at user-global
+`~/.agents/agents/model-runner-<model>.md`.
+
+## What it does
+
+Each runner is a **neutral executor** pinned to a single model, so an ACED skill-under-test can be run
+as a real subagent under that model and its effectiveness / token-cost measured (ACED's eval loop
+otherwise only *simulates* behavior via a judge).
+
+Three **additive** operations:
+
+- **add** — resolve + confirm a target model list (explicit args → `.agents/aced/models.toml` → the
+  known model aliases), then create a runner def for each model that has none. Idempotent.
+- **list** — report the current family (model → path → any effort stamp).
+- **remove** — delete only the runner def(s) the user explicitly names, after confirmation.
+
+It **never auto-removes**: a model absent from a target list is left intact — the user may run
+multiple harnesses, so a runner this engine did not just create is never culled.
+
+One def per model; effort is not a def axis. Because a plain subagent spawn can override `model` but
+not `effort`, an optional `effort:` stamp can be written on a def on request (for a plain-spawn
+runner) without creating model×effort defs.