@aperant/framework 0.6.2

package/src/cli/install/setting-class.mjs

@@ -0,0 +1,177 @@
+/**
+ * setting-class.mjs — single source of truth for which `.aperant/config.json`
+ * keys are Class A (must NOT silently default in non-TTY) vs Class B
+ * (per-task overridable, safe to default).
+ *
+ * Class A → "affects tracked files, team workflow, or shared artifacts".
+ * Missing-in-non-TTY blocks `apt-tools init` with a `requires_input`
+ * envelope; the user (or their agent) must re-run with the named flag or
+ * `--yes`.
+ *
+ * Class B → "local-only, reversible, per-task overridable". Missing values
+ * are filled from `default` and recorded under `applied_defaults` for
+ * transparency, but never block.
+ *
+ * Each descriptor carries a `classify(value)` helper used by
+ * `schema-migrate.mjs` to detect both the absent-in-existing-config case
+ * and the present-but-no-longer-valid case (e.g. a Class A enum gained or
+ * lost an option between schema versions).
+ *
+ * R1 in spec.md drives the contents below — visibility/runtimes/scanNow as
+ * Class A; autonomyDefault/crossVerificationTools as Class B.
+ *
+ * Exported `parseClassFlags(args)` is intentionally separate from
+ * `parseInstallFlags` (in commands/init.mjs) so the existing parser stays
+ * backward-compatible and this module can be unit-tested in isolation.
+ */
+
+import { RUNTIMES } from './runtime-detect.mjs'
+
+/** @typedef {'present'|'absent'|'invalid'} ClassifyResult */
+
+/**
+ * @typedef {Object} ClassDescriptor
+ * @property {string} key            Dot-path into `.aperant/config.json` (e.g. `share.visibility`).
+ * @property {string} shortKey       Short form used in the `requires_explicit` envelope (e.g. `visibility`).
+ * @property {string|null} flag      CLI flag pair (e.g. `--team`/`--solo`) or null if no flag covers it.
+ * @property {string|number|boolean|string[]} default  Default value applied when no flag was given.
+ * @property {Array<string|number|boolean>|null} options  Allowed values (for enums); null = freeform / array shape.
+ * @property {string} why            One-line user-facing rationale rendered into the envelope.
+ * @property {(value: unknown) => ClassifyResult} classify  `'present'` when value is set + valid, `'absent'` when undefined/null, `'invalid'` otherwise.
+ */
+
+/**
+ * Class A — settings whose value impacts tracked files or team workflow.
+ * Must NOT default silently in non-TTY mode. Missing → block install.
+ */
+export const CLASS_A_SETTINGS = Object.freeze([
+	/** @type {ClassDescriptor} */ ({
+		key: 'share.visibility',
+		shortKey: 'visibility',
+		flag: '--team | --solo',
+		default: 'solo',
+		options: ['solo', 'team'],
+		why: 'Controls whether .aperant/ is gitignored at the project root or governed by the internal allow-list.',
+		classify(value) {
+			if (value === undefined || value === null || value === '') return 'absent'
+			return ['solo', 'team'].includes(/** @type {string} */ (value)) ? 'present' : 'invalid'
+		},
+	}),
+	/** @type {ClassDescriptor} */ ({
+		key: 'runtimes',
+		shortKey: 'runtimes',
+		flag: '--<runtime> | --all',
+		default: ['claude'],
+		options: null, // freeform array of runtime ids
+		why: 'Each selected runtime creates a tracked install root (.claude, .codex, .cursor, …).',
+		classify(value) {
+			if (value === undefined || value === null) return 'absent'
+			if (!Array.isArray(value) || value.length === 0) return 'absent'
+			const ids = new Set(RUNTIMES.map((r) => r.id))
+			return value.every((v) => typeof v === 'string' && ids.has(v)) ? 'present' : 'invalid'
+		},
+	}),
+	/** @type {ClassDescriptor} */ ({
+		key: 'scanNow',
+		shortKey: 'scanNow',
+		flag: null, // no CLI flag — driven by the runtimes selection in R2
+		default: false,
+		options: [true, false],
+		why: 'Triggers /apt:scan after install, which writes shared registry artifacts.',
+		classify(value) {
+			if (value === undefined || value === null) return 'absent'
+			return typeof value === 'boolean' ? 'present' : 'invalid'
+		},
+	}),
+])
+
+/**
+ * Class B — settings safe to default. Always have a `default` applied; the
+ * choice is reported under `applied_defaults` so downstream tooling can
+ * detect unattended installs.
+ */
+export const CLASS_B_SETTINGS = Object.freeze([
+	/** @type {ClassDescriptor} */ ({
+		key: 'autonomy.default',
+		shortKey: 'autonomyDefault',
+		flag: '--autonomy <0..3>',
+		default: 1,
+		options: [0, 1, 2, 3],
+		why: 'Per-task overridable, no tracked-file impact.',
+		classify(value) {
+			if (value === undefined || value === null) return 'absent'
+			return [0, 1, 2, 3].includes(/** @type {number} */ (value)) ? 'present' : 'invalid'
+		},
+	}),
+	/** @type {ClassDescriptor} */ ({
+		key: 'multi_model.cross_verification.tools',
+		shortKey: 'crossVerificationTools',
+		flag: null,
+		default: [],
+		options: null,
+		why: 'Local cross-verification roster; reversible via /apt:setup.',
+		classify(value) {
+			if (value === undefined || value === null) return 'absent'
+			return Array.isArray(value) ? 'present' : 'invalid'
+		},
+	}),
+])
+
+/**
+ * Parse the Class A/B flag surface from `args`. Sits ALONGSIDE
+ * `parseInstallFlags` — the legacy parser already extracts runtimes +
+ * `--target` etc.; this one only adds the new flags introduced by R2.
+ *
+ * Mutual exclusion (`--team` + `--solo`) and out-of-range autonomy throw
+ * `Error` — caller (init.mjs) catches and surfaces the message via the
+ * `requires_input` envelope shape.
+ *
+ * @param {string[]} args
+ * @returns {{ visibility?: 'solo'|'team', autonomy?: 0|1|2|3, accept_new_defaults: boolean, yes: boolean }}
+ */
+export function parseClassFlags(args) {
+	const flagSet = new Set(args.filter((a) => a.startsWith('--')))
+
+	const wantsTeam = flagSet.has('--team')
+	const wantsSolo = flagSet.has('--solo')
+	if (wantsTeam && wantsSolo) {
+		throw new Error('Flags --team and --solo are mutually exclusive — pick one.')
+	}
+	const visibility = wantsTeam ? 'team' : wantsSolo ? 'solo' : undefined
+
+	let autonomy
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === '--autonomy' && args[i + 1] !== undefined) {
+			const raw = args[i + 1]
+			if (raw.startsWith('--')) continue // next token is a flag, not a value — skip
+			const n = Number.parseInt(raw, 10)
+			if (!Number.isInteger(n) || n < 0 || n > 3) {
+				throw new Error(`--autonomy must be an integer 0–3; got "${raw}".`)
+			}
+			autonomy = /** @type {0|1|2|3} */ (n)
+		}
+	}
+
+	return {
+		visibility,
+		autonomy,
+		accept_new_defaults: flagSet.has('--accept-new-defaults'),
+		yes: flagSet.has('--yes'),
+	}
+}
+
+/**
+ * Look up a Class descriptor by `shortKey` or full `key`. Returns null when
+ * the key is not classified (template-internal addition).
+ *
+ * @param {string} keyOrShort
+ * @returns {ClassDescriptor|null}
+ */
+const ALL_SETTINGS = Object.freeze([...CLASS_A_SETTINGS, ...CLASS_B_SETTINGS])
+
+export function findClassDescriptor(keyOrShort) {
+	for (const d of ALL_SETTINGS) {
+		if (d.key === keyOrShort || d.shortKey === keyOrShort) return d
+	}
+	return null
+}

package/src/cli/install/transforms/_shared.mjs

@@ -0,0 +1,332 @@
+/**
+ * install/transforms/_shared.mjs — pure helpers shared by every per-runtime
+ * transform module. Zero filesystem access — exported functions take strings
+ * in and return strings out.
+ *
+ * The transforms layer turns a canonical SKILL.md / agent.md / hook.{js,sh}
+ * into runtime-specific output bytes. Each runtime module composes these
+ * helpers (e.g. codex strips `tools` + `color`, gemini escapes ${var}, etc.).
+ *
+ * Why a hand-rolled frontmatter splitter instead of the `yaml` library for
+ * the PARSE step: we want to preserve exact ordering, comments, and
+ * formatting in the body. We DO use `yaml` for re-serialization when a
+ * transform mutates frontmatter (strip fields, etc.) — that path accepts
+ * shape changes.
+ */
+
+import { basename, dirname } from 'node:path'
+import yaml from 'yaml'
+
+/**
+ * @typedef {Object} ParsedFile
+ * @property {Record<string, unknown>|null} fm  parsed frontmatter (null if none)
+ * @property {string} body                       the post-frontmatter content
+ * @property {string} eol                        '\n' or '\r\n' (preserved on round-trip)
+ * @property {boolean} hasFrontmatter
+ */
+
+/**
+ * @typedef {'skill'|'agent'|'hook-js'|'hook-sh'|'unknown'} FileType
+ */
+
+/**
+ * Color-name → hex map. Covers every color name that appears in canonical
+ * frontmatter today (cyan, magenta, blue, green, yellow, red) plus the
+ * common extras (orange, purple, pink, gray, white, black) for forward
+ * compatibility.
+ *
+ * Hex values are taken from Tailwind 3 default palette (500 shade) which
+ * matches GSD's canonical color map. Runtimes that need hex (OpenCode,
+ * Kilo) consume this directly.
+ */
+export const COLOR_NAME_TO_HEX = Object.freeze({
+	cyan: '#06b6d4',
+	magenta: '#d946ef',
+	blue: '#3b82f6',
+	green: '#22c55e',
+	yellow: '#eab308',
+	red: '#ef4444',
+	orange: '#f97316',
+	purple: '#a855f7',
+	pink: '#ec4899',
+	gray: '#6b7280',
+	grey: '#6b7280',
+	white: '#ffffff',
+	black: '#000000',
+})
+
+/**
+ * Convert a color name to a 7-char hex string. Pass-through if the input
+ * is already a hex value (starts with `#`). Returns null for unknown names
+ * so callers can decide whether to drop the field or default it.
+ *
+ * @param {string|null|undefined} name
+ * @returns {string|null}
+ */
+export function colorNameToHex(name) {
+	if (!name || typeof name !== 'string') return null
+	if (name.startsWith('#')) return name
+	return COLOR_NAME_TO_HEX[name.toLowerCase()] ?? null
+}
+
+/**
+ * Split content into frontmatter + body. Preserves the exact body bytes
+ * (including the trailing leading-newline that follows the closing `---`).
+ *
+ * Returns `{ fm: null, body: content, hasFrontmatter: false, eol: '\n' }`
+ * when there is no `---\n` opener.
+ *
+ * @param {string} content
+ * @returns {ParsedFile}
+ */
+export function parseFrontmatter(content) {
+	const eol = /\r\n/.test(content) ? '\r\n' : '\n'
+	if (
+		!content.startsWith('---' + eol) &&
+		!content.startsWith('---\n') &&
+		!content.startsWith('---\r\n')
+	) {
+		return { fm: null, body: content, hasFrontmatter: false, eol }
+	}
+	// Find closing `---` on its own line.
+	const lines = content.split(/\r?\n/)
+	let endIdx = -1
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i] === '---') {
+			endIdx = i
+			break
+		}
+	}
+	if (endIdx === -1) {
+		return { fm: null, body: content, hasFrontmatter: false, eol }
+	}
+	const fmText = lines.slice(1, endIdx).join('\n')
+	const body = lines.slice(endIdx + 1).join(eol)
+	let fm
+	try {
+		fm = yaml.parse(fmText) ?? {}
+	} catch {
+		// Malformed frontmatter — treat as bodyless.
+		return { fm: null, body: content, hasFrontmatter: false, eol }
+	}
+	if (typeof fm !== 'object' || Array.isArray(fm)) {
+		return { fm: null, body: content, hasFrontmatter: false, eol }
+	}
+	return { fm: /** @type {Record<string, unknown>} */ (fm), body, hasFrontmatter: true, eol }
+}
+
+/**
+ * Serialize a parsed file back to a string. Drops keys whose value is
+ * `undefined` so that `delete fm.tools; serialize(...)` produces clean
+ * output.
+ *
+ * @param {ParsedFile} parsed
+ * @returns {string}
+ */
+export function serializeFrontmatter(parsed) {
+	const { fm, body, hasFrontmatter, eol } = parsed
+	if (!hasFrontmatter || !fm) return body
+	const cleaned = /** @type {Record<string, unknown>} */ ({})
+	for (const [k, v] of Object.entries(fm)) {
+		if (v !== undefined) cleaned[k] = v
+	}
+	const fmText = yaml
+		.stringify(cleaned, { lineWidth: 0, defaultStringType: 'PLAIN' })
+		.replace(/\r?\n$/, '') // yaml adds a trailing newline; we add it back below
+	return `---${eol}${fmText}${eol}---${eol}${body}`
+}
+
+/**
+ * Drop an arbitrary set of fields from the frontmatter object. Returns the
+ * same object (mutated) for callers that want to chain.
+ *
+ * @param {Record<string, unknown>|null|undefined} fm
+ * @param {string[]} fieldNames
+ * @returns {Record<string, unknown>}
+ */
+export function stripFields(fm, fieldNames) {
+	if (!fm) return {}
+	for (const f of fieldNames) {
+		delete fm[f]
+	}
+	return fm
+}
+
+/**
+ * Replace the literal `{{APT_VERSION}}` token with a real semver string.
+ * Used by every transform after frontmatter mutation, and by the canonical
+ * file injector when it needs to substitute at install time.
+ *
+ * @param {string} content
+ * @param {string} version
+ * @returns {string}
+ */
+export function substituteVersion(content, version) {
+	if (!content) return content
+	const versioned = content.split('{{APT_VERSION}}').join(version)
+	return substituteKernelPaths(versioned)
+}
+
+/**
+ * Monorepo-relative `node packages/framework/bin/apt-tools.mjs` invocations
+ * are baked into 194 places across canonical skills/agents. In the Aperant
+ * monorepo itself they resolve fine; in every external project they throw
+ * `MODULE_NOT_FOUND`. Install pipeline rewrites them to the project-local
+ * kernel path that `installKernel()` provisions under `.aperant/deps/`.
+ *
+ * Kept a plain string-replace (not regex) so no escaping surprises and it's
+ * still a no-op for snippets that reference `apt-tools` as a bare word
+ * (which are already portable — rely on the user having the binary on PATH).
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function substituteKernelPaths(content) {
+	if (!content) return content
+	return content
+		.split('node packages/framework/bin/apt-tools.mjs')
+		.join('node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs')
+}
+
+/**
+ * Rewrite slash-command references like `/apt:foo` to `/apt-foo` (or any
+ * other prefix swap). Runtimes that disallow `:` in command names (Codex,
+ * Copilot, Antigravity, Cline, CodeBuddy) need this.
+ *
+ * IMPORTANT: only rewrites in slash-command context (whitespace, line start,
+ * or backtick before). Does NOT touch `apt-tools` (literal binary name) or
+ * URLs that happen to contain `apt:`.
+ *
+ * @param {string} content
+ * @param {string} fromPrefix  e.g. '/apt:'
+ * @param {string} toPrefix    e.g. '/apt-'
+ * @returns {string}
+ */
+export function rewriteCommandRefs(content, fromPrefix = '/apt:', toPrefix = '/apt-') {
+	// Match the prefix when preceded by whitespace, line start, ` (backtick),
+	// `(`, `[`, `"`, or `'`. Captures the command name (alphanumerics + `-`).
+	const escFrom = fromPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	const re = new RegExp(`(^|[\\s\\\`\\(\\[\\"'])${escFrom}([a-zA-Z0-9-]+)`, 'g')
+	return content.replace(re, (_m, lead, cmd) => `${lead}${toPrefix}${cmd}`)
+}
+
+/**
+ * Classify a canonical file by its path/extension so transforms can branch
+ * on file type without hand-rolled checks.
+ *
+ * @param {string} filePath  absolute or relative — only the basename + extension matter
+ * @returns {FileType}
+ */
+export function classifyFileType(filePath) {
+	const lower = filePath.toLowerCase()
+	if (lower.endsWith('.js') || lower.endsWith('.mjs')) return 'hook-js'
+	if (lower.endsWith('.sh')) return 'hook-sh'
+	if (lower.endsWith('skill.md')) return 'skill'
+	if (lower.endsWith('.md')) return 'agent'
+	return 'unknown'
+}
+
+/**
+ * Inject (or substitute) the `apt-skill-version` / `apt-hook-version` header
+ * for a single output file. For markdown, the header lives in YAML frontmatter
+ * (already injected by scripts/inject-version-header.mjs into canonical files,
+ * so this is a no-op for markdown except substitution). For .js/.mjs and .sh,
+ * the header is the topmost line as a comment.
+ *
+ * The `version` argument is substituted in place of the literal
+ * `{{APT_VERSION}}` token throughout the file. If the literal token is not
+ * present and the file is a hook, the header line is prepended.
+ *
+ * @param {string} content
+ * @param {FileType} fileType
+ * @param {string} version
+ * @returns {string}
+ */
+export function injectHeader(content, fileType, version) {
+	const substituted = substituteVersion(content, version)
+	if (fileType === 'skill' || fileType === 'agent') {
+		return substituted
+	}
+	if (fileType === 'hook-js') {
+		// Already-headered: substitution above handled it.
+		if (/^\/\/\s*apt-hook-version\s*:/m.test(substituted)) return substituted
+		return `// apt-hook-version: ${version}\n${substituted}`
+	}
+	if (fileType === 'hook-sh') {
+		if (/^#\s*apt-hook-version\s*:/m.test(substituted)) return substituted
+		// Preserve shebang on first line if present.
+		if (substituted.startsWith('#!')) {
+			const nl = substituted.indexOf('\n')
+			if (nl !== -1) {
+				return (
+					substituted.slice(0, nl + 1) +
+					`# apt-hook-version: ${version}\n` +
+					substituted.slice(nl + 1)
+				)
+			}
+		}
+		return `# apt-hook-version: ${version}\n${substituted}`
+	}
+	return substituted
+}
+
+/**
+ * Convenience: parse + mutate frontmatter via callback + serialize, all in
+ * one call. The callback receives the mutable `fm` object and may return
+ * void or a replacement object. Body is preserved.
+ *
+ * @param {string} content
+ * @param {(fm: Record<string, unknown>) => Record<string, unknown> | void} mutator
+ * @returns {string}
+ */
+export function withFrontmatter(content, mutator) {
+	const parsed = parseFrontmatter(content)
+	if (!parsed.hasFrontmatter || !parsed.fm) return content
+	const result = mutator(parsed.fm)
+	if (result && typeof result === 'object') {
+		return serializeFrontmatter({ ...parsed, fm: result })
+	}
+	return serializeFrontmatter(parsed)
+}
+
+/**
+ * Factory for the "simple" class of runtime transforms: strip frontmatter
+ * fields, optionally rewrite /apt:foo → /apt-foo, and output to
+ * agents/<name>.md (+ commands/<name>.md for skills).
+ *
+ * This covers copilot, antigravity, augment, cline, codebuddy, trae, qwen —
+ * seven near-identical files that differ only in the `strip` list and
+ * whether command references are rewritten.
+ *
+ * @param {Object} opts
+ * @param {string[]} opts.strip           frontmatter fields to remove
+ * @param {boolean} [opts.rewriteCommands] rewrite /apt:foo → /apt-foo (default false)
+ * @returns {(input: import('../pipeline.mjs').TransformInput) => import('../pipeline.mjs').TransformOutput[]}
+ */
+export function createSimpleTransform({ strip, rewriteCommands = false }) {
+	return function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+		const subbed = substituteVersion(canonicalContent, version)
+		const parsed = parseFrontmatter(subbed)
+		let payload = subbed
+		if (parsed.hasFrontmatter && parsed.fm) {
+			stripFields(parsed.fm, strip)
+			payload = serializeFrontmatter(parsed)
+		}
+		if (rewriteCommands) {
+			payload = rewriteCommandRefs(payload, '/apt:', '/apt-')
+		}
+
+		if (fileType === 'skill') {
+			const folder = basename(dirname(canonicalRelPath))
+			return [
+				{ outputPath: `agents/${folder}.md`, content: payload },
+				{ outputPath: `commands/${folder}.md`, content: payload },
+			]
+		}
+		if (fileType === 'agent') {
+			const file = basename(canonicalRelPath, '.md')
+			return [{ outputPath: `agents/${file}.md`, content: payload }]
+		}
+		return []
+	}
+}

package/src/cli/install/transforms/antigravity.mjs

@@ -0,0 +1,15 @@
+/**
+ * install/transforms/antigravity.mjs — Antigravity transform.
+ *
+ * Quirks identical to Copilot conceptually but with different output paths:
+ *   - command-name rewrite (/apt:foo → /apt-foo).
+ *   - frontmatter strips tools+color.
+ *   - output: .antigravity/agents/<name>.md + .antigravity/commands/<name>.md.
+ */
+
+import { createSimpleTransform } from './_shared.mjs'
+
+export const transform = createSimpleTransform({
+	strip: ['tools', 'color'],
+	rewriteCommands: true,
+})

package/src/cli/install/transforms/augment.mjs

@@ -0,0 +1,14 @@
+/**
+ * install/transforms/augment.mjs — Augment transform.
+ *
+ * Quirks:
+ *   - frontmatter strips color+skills.
+ *   - output: .augment/agents/<name>.md + .augment/commands/<name>.md.
+ */
+
+import { createSimpleTransform } from './_shared.mjs'
+
+export const transform = createSimpleTransform({
+	strip: ['color', 'skills'],
+	rewriteCommands: false,
+})

package/src/cli/install/transforms/claude.mjs

@@ -0,0 +1,41 @@
+/**
+ * install/transforms/claude.mjs — Claude Code transform.
+ *
+ * Claude Code is the canonical target — frontmatter is preserved as-is and
+ * the body is left untouched. The only mutation is `{{APT_VERSION}}` →
+ * actual semver. Output paths follow `.claude/skills/<name>/SKILL.md` and
+ * `.claude/agents/<name>.md`, matching the legacy installer that this
+ * pipeline replaces.
+ */
+
+import { basename, dirname } from 'node:path'
+import { substituteVersion } from './_shared.mjs'
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const content = substituteVersion(canonicalContent, version)
+	if (fileType === 'skill') {
+		// canonicalRelPath looks like 'skills/apt-foo/SKILL.md'; preserve
+		// the skill folder name + nested file structure under .claude/skills/.
+		const folder = basename(dirname(canonicalRelPath))
+		return [{ outputPath: `skills/${folder}/SKILL.md`, content }]
+	}
+	if (fileType === 'agent') {
+		// agents/apt-foo.md OR skills/apt-foo.md (top-level agent-skill files
+		// — the legacy installer copied these into .claude/skills/ along
+		// with the dirs). For backward compat we keep them in .claude/skills/
+		// when their canonical path was under skills/, and .claude/agents/
+		// when it was under agents/.
+		const file = basename(canonicalRelPath)
+		const installRoot = canonicalRelPath.startsWith('agents/') ? 'agents' : 'skills'
+		return [{ outputPath: `${installRoot}/${file}`, content }]
+	}
+	if (fileType === 'hook-js' || fileType === 'hook-sh') {
+		const file = basename(canonicalRelPath)
+		return [{ outputPath: `hooks/${file}`, content }]
+	}
+	return []
+}

package/src/cli/install/transforms/cline.mjs

@@ -0,0 +1,15 @@
+/**
+ * install/transforms/cline.mjs — Cline transform.
+ *
+ * Quirks:
+ *   - strips color+skills.
+ *   - command-name rewrite (/apt:foo → /apt-foo).
+ *   - output: .cline/agents/<name>.md + .cline/commands/<name>.md.
+ */
+
+import { createSimpleTransform } from './_shared.mjs'
+
+export const transform = createSimpleTransform({
+	strip: ['color', 'skills'],
+	rewriteCommands: true,
+})

package/src/cli/install/transforms/codebuddy.mjs

@@ -0,0 +1,15 @@
+/**
+ * install/transforms/codebuddy.mjs — CodeBuddy transform.
+ *
+ * Quirks:
+ *   - strips color+skills.
+ *   - command-name rewrite (/apt:foo → /apt-foo).
+ *   - output: .codebuddy/agents/<name>.md + .codebuddy/commands/<name>.md.
+ */
+
+import { createSimpleTransform } from './_shared.mjs'
+
+export const transform = createSimpleTransform({
+	strip: ['color', 'skills'],
+	rewriteCommands: true,
+})

package/src/cli/install/transforms/codex.mjs

@@ -0,0 +1,56 @@
+/**
+ * install/transforms/codex.mjs — Codex transform.
+ *
+ * Codex quirks:
+ *   - frontmatter strips `tools` and `color` (Codex validates strictly and
+ *     rejects unknown/style-only keys).
+ *   - body is wrapped in <codex_agent_role>…</codex_agent_role>.
+ *   - slash-command refs `/apt:foo` rewritten to `/apt-foo` (Codex command
+ *     names disallow `:`).
+ *   - output: .codex/agents/<name>.md AND .codex/commands/<name>.md (some
+ *     skills register both as agent + invocable command).
+ */
+
+import { basename, dirname } from 'node:path'
+import {
+	parseFrontmatter,
+	rewriteCommandRefs,
+	serializeFrontmatter,
+	stripFields,
+	substituteVersion,
+} from './_shared.mjs'
+
+const STRIP = ['tools', 'color']
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const subbed = substituteVersion(canonicalContent, version)
+	const parsed = parseFrontmatter(subbed)
+	let payload
+	if (parsed.hasFrontmatter && parsed.fm) {
+		stripFields(parsed.fm, STRIP)
+		const wrappedBody = `<codex_agent_role>\n${parsed.body}\n</codex_agent_role>\n`
+		payload = serializeFrontmatter({ ...parsed, body: wrappedBody })
+	} else {
+		payload = `<codex_agent_role>\n${subbed}\n</codex_agent_role>\n`
+	}
+	payload = rewriteCommandRefs(payload, '/apt:', '/apt-')
+
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		// Skills emit BOTH an agent definition (for invocation context) and a
+		// command (so the user can type `/apt-foo` directly in Codex).
+		return [
+			{ outputPath: `agents/${folder}.md`, content: payload },
+			{ outputPath: `commands/${folder}.md`, content: payload },
+		]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath, '.md')
+		return [{ outputPath: `agents/${file}.md`, content: payload }]
+	}
+	return []
+}

package/src/cli/install/transforms/copilot.mjs

@@ -0,0 +1,19 @@
+/**
+ * install/transforms/copilot.mjs — GitHub Copilot transform.
+ *
+ * Copilot quirks:
+ *   - command-name rewrite (/apt:foo → /apt-foo) — Copilot's slash-command
+ *     surface mirrors VS Code which also disallows `:`.
+ *   - output: .github/copilot/agents/<name>.md and
+ *     .github/copilot/commands/<name>.md (the install root is .github/copilot
+ *     so paths here are relative to that root).
+ *   - frontmatter: strip `tools` and `color` (Copilot's `chatmode` schema
+ *     doesn't accept either).
+ */
+
+import { createSimpleTransform } from './_shared.mjs'
+
+export const transform = createSimpleTransform({
+	strip: ['tools', 'color'],
+	rewriteCommands: true,
+})