skillmaxxing 0.1.0

package/dist/discover/rank.js

@@ -0,0 +1,63 @@
+import { tokenize } from '../util/similarity.js';
+/**
+ * Deterministic lexical + metadata ranking. Embeddings are intentionally NOT
+ * abstracted here yet (review SG2: a one-implementation interface is YAGNI) -- a
+ * ranking strategy can be added when a second implementation actually exists.
+ */
+function scoreCandidate(intentTokens, c) {
+    const nameLower = c.name.toLowerCase();
+    const nameTokens = new Set(tokenize(c.name));
+    const tagTokens = new Set(c.tags.flatMap(tokenize));
+    const descTokens = new Set(tokenize(c.description));
+    let score = 0;
+    for (const t of intentTokens) {
+        if (nameTokens.has(t))
+            score += 3;
+        else if (nameLower.includes(t))
+            score += 2; // partial name hit
+        if (tagTokens.has(t))
+            score += 2;
+        if (descTokens.has(t))
+            score += 1;
+    }
+    return score;
+}
+function originRank(origin) {
+    return origin === 'local' ? 0 : origin === 'index' ? 1 : 2;
+}
+/**
+ * Rank candidates against the user's intent, de-duplicating same-named skills
+ * across sources (the highest-scoring wins; the rest become `alternates`).
+ * Fully deterministic: equal inputs always produce equal output ordering.
+ */
+export function rankCandidates(intent, candidates) {
+    const intentTokens = [...new Set(tokenize(intent))];
+    const groups = new Map();
+    for (const c of candidates) {
+        const key = c.name.toLowerCase();
+        const arr = groups.get(key);
+        if (arr)
+            arr.push(c);
+        else
+            groups.set(key, [c]);
+    }
+    const ranked = [];
+    for (const group of groups.values()) {
+        const scored = group
+            .map((c) => ({ c, s: scoreCandidate(intentTokens, c) }))
+            .sort((a, b) => b.s - a.s ||
+            originRank(a.c.origin) - originRank(b.c.origin) ||
+            a.c.source.localeCompare(b.c.source));
+        const primary = scored[0];
+        ranked.push({
+            ...primary.c,
+            installed: group.some((c) => c.installed),
+            score: primary.s,
+            alternates: scored.slice(1).map((x) => x.c),
+        });
+    }
+    ranked.sort((a, b) => b.score - a.score ||
+        Number(b.installed) - Number(a.installed) ||
+        a.name.localeCompare(b.name));
+    return ranked;
+}

package/dist/discover/types.js

@@ -0,0 +1 @@
+export {};

package/dist/eval/runner.js

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { scoreExact, scoreNormalized, scoreSuccessSignal } from './scorers.js';
+import { runSandboxed } from '../util/exec.js';
+import { makeTempDir, cleanTempDir } from '../util/git.js';
+async function scoreCodeExec(task, output, opts) {
+    const dir = makeTempDir('eval');
+    try {
+        fs.writeFileSync(path.join(dir, 'output'), output);
+        const [cmd, ...args] = task.command;
+        const res = await runSandboxed(cmd, args, {
+            cwd: dir,
+            skillId: opts.skillId,
+            allowExec: opts.allowExec,
+            timeoutMs: 30_000,
+        });
+        const okExit = res.ok;
+        const okStdout = task.expect === undefined || res.stdout.trim() === task.expect.trim();
+        const score = okExit && okStdout ? 1 : 0;
+        return { score, detail: okExit ? undefined : `exit ${res.code}${res.timedOut ? ' (timeout)' : ''}` };
+    }
+    finally {
+        cleanTempDir(dir);
+    }
+}
+/**
+ * Score a set of rollout outputs against an eval manifest. Deterministic scorers
+ * run here; `agent-judge` tasks are returned as pending judgments (with output +
+ * rubric) for the host agent to score — keeping the CLI model-agnostic (KTD7/KTD8).
+ */
+export async function scoreRollouts(manifest, outputs, opts = {}) {
+    const outById = new Map(outputs.map((o) => [o.taskId, o.output]));
+    const perTask = [];
+    const pendingJudgments = [];
+    const missing = [];
+    for (const task of manifest.tasks) {
+        const raw = outById.get(task.id);
+        if (task.scorer === 'agent-judge') {
+            perTask.push({ taskId: task.id, scorer: task.scorer, score: 0, passed: false, pending: true });
+            pendingJudgments.push({ taskId: task.id, rubric: task.rubric ?? '', output: raw ?? '' });
+            continue;
+        }
+        // A missing rollout output is NOT a score of 0 — that would silently tank the
+        // aggregate and mislead the gate (review: missing != failure). Flag it and
+        // exclude it from the aggregate so the caller re-rolls it out.
+        if (raw === undefined) {
+            missing.push(task.id);
+            perTask.push({ taskId: task.id, scorer: task.scorer, score: 0, passed: false, pending: false, detail: 'no rollout output' });
+            continue;
+        }
+        const output = raw;
+        let score = 0;
+        let detail;
+        if (task.scorer === 'exact') {
+            score = scoreExact(output, task.expect ?? '');
+        }
+        else if (task.scorer === 'normalized') {
+            score = scoreNormalized(output, task.expect ?? '');
+        }
+        else if (task.scorer === 'success-signal') {
+            score = scoreSuccessSignal(output, task.expect);
+        }
+        else if (task.scorer === 'code-exec') {
+            const r = await scoreCodeExec(task, output, opts);
+            score = r.score;
+            detail = r.detail;
+        }
+        perTask.push({
+            taskId: task.id,
+            scorer: task.scorer,
+            score,
+            passed: score >= 1,
+            pending: false,
+            detail,
+        });
+    }
+    const missingSet = new Set(missing);
+    const scored = perTask.filter((r) => !r.pending && !missingSet.has(r.taskId));
+    const aggregate = scored.length > 0 ? scored.reduce((sum, r) => sum + r.score, 0) / scored.length : null;
+    return { perTask, aggregate, pendingJudgments, missing };
+}

package/dist/eval/schema.js

@@ -0,0 +1,78 @@
+import * as fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+/**
+ * One eval format shared by create scaffolds and the optimize loop (R7). Each
+ * task self-declares its scorer (the per-task scorer menu): deterministic where
+ * possible, `agent-judge` (rubric-scored by the host agent) where the skill
+ * produces prose/judgment that has no exact answer. The CLI stays model-agnostic
+ * — it scores deterministic tasks and defers `agent-judge` to the host agent.
+ */
+export const SCORER_TYPES = [
+    'exact',
+    'normalized',
+    'code-exec',
+    'success-signal',
+    'agent-judge',
+];
+/** Return a human-readable error if the manifest is invalid, or null if valid. */
+export function validateManifest(m) {
+    if (!m || typeof m !== 'object')
+        return 'manifest must be an object';
+    const man = m;
+    if (typeof man.skill !== 'string' || !man.skill)
+        return 'manifest.skill must be a non-empty string';
+    if (!Array.isArray(man.tasks) || man.tasks.length === 0) {
+        return 'manifest.tasks must be a non-empty array'; // optimize cannot run on an empty set (AE3)
+    }
+    const ids = new Set();
+    for (const [i, task] of man.tasks.entries()) {
+        if (!task || typeof task !== 'object')
+            return `task ${i} must be an object`;
+        if (typeof task.id !== 'string' || !task.id)
+            return `task ${i} missing id`;
+        if (ids.has(task.id))
+            return `duplicate task id "${task.id}"`;
+        ids.add(task.id);
+        if (typeof task.input !== 'string')
+            return `task "${task.id}" missing input`;
+        if (!SCORER_TYPES.includes(task.scorer)) {
+            return `task "${task.id}" has invalid scorer "${task.scorer}"`;
+        }
+        if ((task.scorer === 'exact' || task.scorer === 'normalized') &&
+            typeof task.expect !== 'string') {
+            return `task "${task.id}" (${task.scorer}) requires expect`;
+        }
+        if (task.scorer === 'code-exec' && (!Array.isArray(task.command) || task.command.length === 0)) {
+            return `task "${task.id}" (code-exec) requires a command array`;
+        }
+        if (task.scorer === 'agent-judge' && typeof task.rubric !== 'string') {
+            return `task "${task.id}" (agent-judge) requires a rubric`;
+        }
+    }
+    if (man.heldOut) {
+        for (const id of man.heldOut) {
+            if (!ids.has(id))
+                return `heldOut references unknown task "${id}"`;
+        }
+    }
+    return null;
+}
+/** Parse a YAML/JSON eval manifest string. Throws on invalid content (hard-fail). */
+export function parseEvalManifest(raw) {
+    let data;
+    try {
+        data = parseYaml(raw);
+    }
+    catch (e) {
+        throw new Error(`eval manifest is not valid YAML/JSON: ${e instanceof Error ? e.message : e}`);
+    }
+    const err = validateManifest(data);
+    if (err)
+        throw new Error(`invalid eval manifest: ${err}`);
+    return data;
+}
+/** Load and validate an eval manifest from disk. Throws on missing/invalid. */
+export function loadEvalManifest(manifestPath) {
+    const raw = fs.readFileSync(manifestPath, 'utf-8');
+    return parseEvalManifest(raw);
+}

package/dist/eval/scorers.js

@@ -0,0 +1,19 @@
+/** Deterministic scorers. The host agent never decides pass/fail for these. */
+function normalize(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/** Exact match after trimming trailing/leading whitespace. */
+export function scoreExact(output, expect) {
+    return output.trim() === expect.trim() ? 1 : 0;
+}
+/** Case-insensitive, whitespace-collapsed match. */
+export function scoreNormalized(output, expect) {
+    return normalize(output) === normalize(expect) ? 1 : 0;
+}
+/**
+ * Success-signal scorer: the rollout emits a deterministic signal token. Passes
+ * when the output equals the expected signal (default "PASS").
+ */
+export function scoreSuccessSignal(output, expect = 'PASS') {
+    return output.trim() === expect.trim() ? 1 : 0;
+}

package/dist/lock/global.js

@@ -0,0 +1,53 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { ensureDir } from '../util/fs.js';
+const LOCK_DIR = path.join(os.homedir(), '.skillmax');
+const LOCK_PATH = path.join(LOCK_DIR, 'skill-lock.json');
+function empty() {
+    return { version: 1, skills: {} };
+}
+export function readGlobalLock() {
+    try {
+        const raw = fs.readFileSync(LOCK_PATH, 'utf-8');
+        const data = JSON.parse(raw);
+        if (data.version !== 1)
+            return empty();
+        return data;
+    }
+    catch {
+        return empty();
+    }
+}
+export function writeGlobalLock(lock) {
+    ensureDir(LOCK_DIR);
+    // Sort skill keys for merge-friendliness before any team use (review C5/U13):
+    // independent additions then produce diffs that don't collide on unrelated keys.
+    const sorted = { version: 1, skills: {} };
+    for (const key of Object.keys(lock.skills).sort()) {
+        sorted.skills[key] = lock.skills[key];
+    }
+    const tmp = LOCK_PATH + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(sorted, null, 2) + '\n');
+    fs.renameSync(tmp, LOCK_PATH);
+}
+export function addGlobalLockEntry(name, entry) {
+    const lock = readGlobalLock();
+    const now = new Date().toISOString();
+    const existing = lock.skills[name];
+    lock.skills[name] = {
+        ...entry,
+        installedAt: existing?.installedAt ?? now,
+        updatedAt: now,
+        agents: [...new Set([...(existing?.agents ?? []), ...entry.agents])],
+    };
+    writeGlobalLock(lock);
+}
+export function removeGlobalLockEntry(name) {
+    const lock = readGlobalLock();
+    delete lock.skills[name];
+    writeGlobalLock(lock);
+}
+export function getGlobalLockEntry(name) {
+    return readGlobalLock().skills[name];
+}

package/dist/lock/project.js

@@ -0,0 +1,67 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+const LOCK_FILENAME = 'skills-lock.json';
+function empty() {
+    return { version: 1, skills: {} };
+}
+export function projectLockPath(projectDir) {
+    return path.join(projectDir, LOCK_FILENAME);
+}
+export function readProjectLock(projectDir) {
+    try {
+        const raw = fs.readFileSync(projectLockPath(projectDir), 'utf-8');
+        const data = JSON.parse(raw);
+        if (data.version !== 1)
+            return empty();
+        return data;
+    }
+    catch {
+        return empty();
+    }
+}
+export function writeProjectLock(projectDir, lock) {
+    const sorted = {};
+    for (const key of Object.keys(lock.skills).sort()) {
+        sorted[key] = lock.skills[key];
+    }
+    lock.skills = sorted;
+    const tmp = projectLockPath(projectDir) + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(lock, null, 2) + '\n');
+    fs.renameSync(tmp, projectLockPath(projectDir));
+}
+export function addProjectLockEntry(projectDir, name, entry) {
+    const lock = readProjectLock(projectDir);
+    lock.skills[name] = entry;
+    writeProjectLock(projectDir, lock);
+}
+export function removeProjectLockEntry(projectDir, name) {
+    const lock = readProjectLock(projectDir);
+    delete lock.skills[name];
+    writeProjectLock(projectDir, lock);
+}
+export function computeSkillHash(dir) {
+    const hash = crypto.createHash('sha256');
+    const files = collectFiles(dir).sort();
+    for (const file of files) {
+        const rel = path.relative(dir, file);
+        hash.update(rel);
+        hash.update(fs.readFileSync(file));
+    }
+    return hash.digest('hex').substring(0, 16);
+}
+function collectFiles(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git' || entry.name === 'node_modules')
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectFiles(full));
+        }
+        else {
+            results.push(full);
+        }
+    }
+    return results;
+}

package/dist/optimize/budget.js

@@ -0,0 +1,22 @@
+/**
+ * Edit budget as a "learning rate" (KTD14): the max number of edits allowed in a
+ * step, optionally annealed across steps so later steps make smaller changes.
+ * Bounded changes prevent catastrophic skill drift.
+ */
+export function editBudget(step, totalSteps, opts = {}) {
+    const base = opts.base ?? 4;
+    const min = opts.min ?? 2;
+    const scheduler = opts.scheduler ?? 'cosine';
+    if (totalSteps <= 1 || scheduler === 'constant')
+        return base;
+    const t = Math.min(Math.max(step, 0), totalSteps) / totalSteps; // 0..1
+    let value;
+    if (scheduler === 'linear') {
+        value = base - (base - min) * t;
+    }
+    else {
+        // cosine annealing from base → min
+        value = min + (base - min) * 0.5 * (1 + Math.cos(Math.PI * t));
+    }
+    return Math.max(min, Math.round(value));
+}

package/dist/optimize/buffer.js

@@ -0,0 +1,33 @@
+/** Stable fingerprint for an edit (op + target + content). */
+export function editFingerprint(edit) {
+    return `${edit.op} ${edit.target ?? ''} ${edit.content ?? ''}`;
+}
+/**
+ * Rejected-edit buffer (KTD14): remembers edits that failed the gate so they are
+ * not re-proposed within an epoch. This is what prevents the optimizer from
+ * oscillating on the same circular edits -- a mechanism most systems omit.
+ */
+export class RejectedEditBuffer {
+    seen = new Set();
+    add(edit) {
+        this.seen.add(editFingerprint(edit));
+    }
+    addAll(edits) {
+        for (const e of edits)
+            this.add(e);
+    }
+    has(edit) {
+        return this.seen.has(editFingerprint(edit));
+    }
+    /** Return only edits not already in the buffer. */
+    filterNew(edits) {
+        return edits.filter((e) => !this.has(e));
+    }
+    /** Reset at an epoch boundary. */
+    reset() {
+        this.seen.clear();
+    }
+    get size() {
+        return this.seen.size;
+    }
+}

package/dist/optimize/diff.js

@@ -0,0 +1,89 @@
+/** Protected region markers — step-level edits may not modify content inside (KTD14). */
+export const SLOW_UPDATE_START = '<!-- SLOW_UPDATE_START -->';
+export const SLOW_UPDATE_END = '<!-- SLOW_UPDATE_END -->';
+function slowUpdateSpan(content) {
+    const s = content.indexOf(SLOW_UPDATE_START);
+    if (s === -1)
+        return null;
+    const e = content.indexOf(SLOW_UPDATE_END, s);
+    if (e === -1)
+        return null;
+    return { start: s, end: e + SLOW_UPDATE_END.length };
+}
+/** True if `index` falls within the protected slow-update region. */
+export function isProtectedIndex(content, index) {
+    const span = slowUpdateSpan(content);
+    return span !== null && index >= span.start && index < span.end;
+}
+/** Apply a single edit. Rejects edits that target the protected slow-update region. */
+export function applyEdit(content, edit) {
+    if (edit.op === 'append') {
+        const span = slowUpdateSpan(content);
+        // append goes to end; if a slow-update region ends the doc, insert before it
+        if (span && span.end >= content.trimEnd().length) {
+            const before = content.slice(0, span.start);
+            const region = content.slice(span.start);
+            return { ok: true, content: `${before.trimEnd()}\n${edit.content ?? ''}\n\n${region}` };
+        }
+        return { ok: true, content: `${content.replace(/\s*$/, '')}\n${edit.content ?? ''}\n` };
+    }
+    if (!edit.target) {
+        return { ok: false, content, reason: `${edit.op} requires a target` };
+    }
+    // Find the first occurrence OUTSIDE the protected slow-update region. An anchor
+    // that also appears inside the region must not cause the whole edit to be
+    // dropped when a valid occurrence exists outside it (review: dual-occurrence).
+    let idx = content.indexOf(edit.target);
+    while (idx !== -1 && isProtectedIndex(content, idx)) {
+        idx = content.indexOf(edit.target, idx + 1);
+    }
+    if (idx === -1) {
+        const anywhere = content.includes(edit.target);
+        return {
+            ok: false,
+            content,
+            reason: anywhere
+                ? 'target only occurs within the protected slow-update region'
+                : `target not found: ${truncate(edit.target)}`,
+        };
+    }
+    if (edit.op === 'replace') {
+        return { ok: true, content: content.slice(0, idx) + (edit.content ?? '') + content.slice(idx + edit.target.length) };
+    }
+    if (edit.op === 'delete') {
+        return { ok: true, content: content.slice(0, idx) + content.slice(idx + edit.target.length) };
+    }
+    if (edit.op === 'insert_after') {
+        const at = idx + edit.target.length;
+        return { ok: true, content: content.slice(0, at) + (edit.content ?? '') + content.slice(at) };
+    }
+    return { ok: false, content, reason: `unknown op: ${edit.op}` };
+}
+/** Apply a list of edits in order, collecting which applied and which were rejected. */
+export function applyEdits(content, edits) {
+    let current = content;
+    const applied = [];
+    const rejected = [];
+    for (const edit of edits) {
+        const res = applyEdit(current, edit);
+        if (res.ok) {
+            current = res.content;
+            applied.push(edit);
+        }
+        else {
+            rejected.push({ edit, reason: res.reason ?? 'rejected' });
+        }
+    }
+    return { content: current, applied, rejected };
+}
+/** Replace (or create) the slow-update region's contents — epoch-level only. */
+export function setSlowUpdate(content, guidance) {
+    const block = `${SLOW_UPDATE_START}\n${guidance}\n${SLOW_UPDATE_END}`;
+    const span = slowUpdateSpan(content);
+    if (span)
+        return content.slice(0, span.start) + block + content.slice(span.end);
+    return `${content.replace(/\s*$/, '')}\n\n${block}\n`;
+}
+function truncate(s) {
+    return s.length > 40 ? s.slice(0, 39) + '…' : s;
+}

package/dist/optimize/loop.js

@@ -0,0 +1,49 @@
+/**
+ * Validation gate (KTD14 / SkillOpt): accept a candidate only if its score is
+ * STRICTLY greater than the current score. Promotion to live additionally
+ * requires no held-out regression (see noHeldOutRegression) and human approval.
+ */
+export function gate(currentScore, candidateScore, bestScore) {
+    if (candidateScore > currentScore) {
+        if (candidateScore > bestScore)
+            return { action: 'accept_new_best' };
+        return { action: 'accept' };
+    }
+    return { action: 'reject' };
+}
+/**
+ * No held-out task may regress (pass→fail / lower score). Overfitting guard: a
+ * candidate that improves overall but breaks a held-out task is rejected.
+ */
+export function noHeldOutRegression(current, candidate, heldOutIds) {
+    for (const id of heldOutIds) {
+        const before = current[id] ?? 0;
+        const after = candidate[id] ?? 0;
+        if (after < before)
+            return false;
+    }
+    return true;
+}
+/**
+ * Select which edits to apply this step: drop edits already in the rejected
+ * buffer, prioritize failure-driven edits over success-driven ones, then by
+ * support count, and cap at the edit budget. Deterministic and stable.
+ */
+export function selectEdits(edits, budget, buffer) {
+    const fresh = buffer ? buffer.filterNew(edits) : edits;
+    const ranked = fresh
+        .map((e, i) => ({ e, i }))
+        .sort((a, b) => {
+        const aFail = a.e.sourceType === 'failure' ? 0 : 1;
+        const bFail = b.e.sourceType === 'failure' ? 0 : 1;
+        if (aFail !== bFail)
+            return aFail - bFail; // failures first
+        const aSup = a.e.supportCount ?? 0;
+        const bSup = b.e.supportCount ?? 0;
+        if (aSup !== bSup)
+            return bSup - aSup; // higher support first
+        return a.i - b.i; // stable
+    })
+        .map((x) => x.e);
+    return ranked.slice(0, Math.max(0, budget));
+}

package/dist/plugin/guidance.js

@@ -0,0 +1,30 @@
+/**
+ * Standing guidance injected at session start (Hermes "Layer A" nudge, adapted
+ * to coding agents). This is what makes the agent self-evolving WITHOUT the user
+ * invoking anything: the agent is continuously aware it should crystallize and
+ * improve skills as it works. The background hook (Layer B) is the safety net
+ * that fires when the agent forgets.
+ */
+export const SKILLS_GUIDANCE = [
+    'Skill Maxing is active: you can make yourself permanently better at this codebase.',
+    '',
+    'After you finish a non-trivial task — a multi-step workflow, a tricky fix, or a',
+    'procedure you would repeat — crystallize it as a reusable skill:',
+    '  skillmaxxing skillify --draft <draft.json>   # then review and: --commit <name>',
+    '',
+    'When you USE a skill and find it outdated, wrong, or missing a step, improve it',
+    'immediately instead of working around it:',
+    '  skillmaxxing optimize <action> ...           # eval-gated; promotes only on a strict win',
+    '',
+    'Rules of thumb:',
+    '- Prefer UPDATING an existing skill over creating a near-duplicate (search first).',
+    '- New and changed skills are recorded trusted:false until the user approves them.',
+    '- Keep it conservative: one high-value skill beats five shallow ones.',
+].join('\n');
+/** Shorter reminder used by the Stop hook in nudge mode after substantive work. */
+export const REFLECT_NUDGE = [
+    'You just completed a substantial chunk of work. Before moving on, consider:',
+    'is any of it a reusable workflow worth saving as a skill (skillmaxxing skillify),',
+    'or did you use a skill that should be improved (skillmaxxing optimize)?',
+    'Prefer updating an existing skill over creating a new one. Skip if nothing is reusable.',
+].join(' ');

package/dist/plugin/reflect.js

@@ -0,0 +1,63 @@
+import { spawn } from 'node:child_process';
+/** Env flag set on the spawned reflector so its own Stop hook no-ops (no recursion). */
+export const REFLECT_ENV = 'SKILLMAX_REFLECT';
+export function isReflecting() {
+    return process.env[REFLECT_ENV] === '1';
+}
+export function buildReflectionPrompt(transcriptPath) {
+    return [
+        'You are the Skill Maxing background reflector. Review the coding session transcript at:',
+        `  ${transcriptPath}`,
+        '',
+        'Decide whether the session contains EITHER:',
+        '  (a) a reusable workflow worth saving as a new skill, or',
+        '  (b) a skill that was used and turned out incomplete/outdated/wrong.',
+        '',
+        'If neither, do nothing and exit — most sessions should produce no skill.',
+        'If one applies, take exactly ONE action, conservatively:',
+        '  - First search existing skills: `skillmaxxing discover "<capability>" --json`.',
+        '  - PREFER updating an existing skill over creating a near-duplicate.',
+        '  - To create: write a draft JSON (name, description, body, optional scripts and a real',
+        '    eval scaffold) then `skillmaxxing skillify --draft <file>` and `--commit <name>`.',
+        '  - To improve: run the eval-gated `skillmaxxing optimize` loop.',
+        '',
+        'New/changed skills are recorded trusted:false for the user to review. Do NOT modify',
+        'project source code. Do NOT install or execute untrusted skills. One skill at most.',
+    ].join('\n');
+}
+/**
+ * Spawn the reflector detached so the user's session is never blocked. Returns
+ * true if a process was launched. Tools are restricted to skill management.
+ */
+export function runReflectionDetached(opts) {
+    const prompt = buildReflectionPrompt(opts.transcriptPath);
+    const env = { ...process.env, [REFLECT_ENV]: '1' };
+    let command;
+    let args;
+    if (opts.agent === 'claude') {
+        command = 'claude';
+        args = [
+            '-p',
+            prompt,
+            '--allowedTools',
+            'Read,Glob,Grep,Write,Edit,Bash(skillmaxxing:*),Bash(skill-maxing:*),Bash(skillmax:*),Bash(npx:*)',
+        ];
+    }
+    else {
+        command = 'codex';
+        args = ['exec', prompt];
+    }
+    try {
+        const child = spawn(command, args, {
+            cwd: opts.cwd,
+            env,
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false; // reflector binary missing or spawn failed — never break the user's session
+    }
+}