skilldiff 0.1.0

package/dist/scripts/spike.js

@@ -0,0 +1,176 @@
+// T1 SPIKE — go/no-go for skilldiff (harness-adapter edition)
+//
+// Verifies the two feasibility gates from the design doc before any real code:
+//   1. An installed harness CLI (claude / cursor-agent / codex), run headless,
+//      emits a parseable JSON event stream with tool-use events from a fixture repo.
+//   2. `git show <base>:<skill path>` fetches the old skill version (baseline).
+//
+// Run: npm run spike [path-to-fixture]
+// Requires: at least one harness CLI installed + logged in (its own subscription
+// is fine — no ANTHROPIC_API_KEY needed).
+import { spawn } from "node:child_process";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { ADAPTERS } from "./adapters.js";
+function which(cmd) {
+    try {
+        return execFileSync("which", [cmd], { encoding: "utf8" }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function pickAdapter() {
+    const forEnv = process.env.SKILLDIFF_HARNESS;
+    if (forEnv) {
+        const found = ADAPTERS.find((a) => a.name === forEnv);
+        if (!found) {
+            console.error(`SKILLDIFF_HARNESS=${forEnv} is not one of: ${ADAPTERS.map((a) => a.name).join(", ")}`);
+            process.exit(2);
+        }
+        if (!which(found.cmd)) {
+            console.error(`${found.cmd} not found in PATH`);
+            process.exit(2);
+        }
+        return found;
+    }
+    for (const a of ADAPTERS) {
+        if (which(a.cmd))
+            return a;
+    }
+    console.error("No harness CLI found. Install one of: claude, cursor-agent, codex");
+    process.exit(2);
+}
+function runHarness(adapter, cwd, prompt) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(adapter.cmd, [...adapter.baseArgs, prompt], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const traces = [];
+        let stderr = "";
+        let buf = "";
+        child.stdout.on("data", (chunk) => {
+            buf += chunk.toString();
+            let idx;
+            while ((idx = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, idx).trim();
+                buf = buf.slice(idx + 1);
+                if (!line)
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue; // non-JSON noise lines are expected from some harnesses
+                }
+                traces.push(...adapter.extractToolUses(parsed));
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("close", (code) => resolvePromise({ traces, stderr, code }));
+        child.on("error", (err) => {
+            stderr += String(err);
+            resolvePromise({ traces, stderr, code: -1 });
+        });
+    });
+}
+// Gate 2: fetch the old skill version from a base ref into a temp copy
+async function baselineFetch(repoPath, baseRef, skillPaths) {
+    try {
+        execFileSync("git", ["rev-parse", "--verify", baseRef], { cwd: repoPath });
+        const dest = await mkdtemp(join(tmpdir(), "skilldiff-baseline-"));
+        execFileSync("git", ["checkout", baseRef, "--", ...skillPaths], { cwd: repoPath });
+        // restore repo to HEAD immediately — we only wanted the files
+        execFileSync("git", ["checkout", "HEAD", "--", ...skillPaths], { cwd: repoPath });
+        void dest;
+        console.log(`  baseline fetch OK: ${skillPaths.length} path(s) from ${baseRef}`);
+        return true;
+    }
+    catch (err) {
+        console.error(`  baseline fetch FAILED: ${err.message}`);
+        return false;
+    }
+}
+export async function runSpike(fixturePathArg) {
+    const adapter = pickAdapter();
+    console.log(`Spike harness: ${adapter.name} (${which(adapter.cmd)})`);
+    const fixtureRepo = resolve(fixturePathArg ?? (await makeMinimalFixture()));
+    console.log(`Spike fixture: ${fixtureRepo}`);
+    // ---- Gate 1: tool trace capture ------------------------------------
+    console.log(`\n[Gate 1] headless ${adapter.name} run + tool-use trace capture`);
+    const prompt = "Read the file NOTES.md in this repo and follow the instructions in it exactly.";
+    try {
+        const { traces, stderr, code } = await runHarness(adapter, fixtureRepo, prompt);
+        if (stderr.trim())
+            console.log(`  harness stderr: ${stderr.trim().slice(0, 500)}`);
+        if (code !== 0 && traces.length === 0) {
+            console.error(`  Gate 1: FAIL — harness exited ${code} with no tool events captured`);
+            if (stderr.trim())
+                console.error(`  stderr: ${stderr.trim().slice(0, 1000)}`);
+            process.exit(3);
+        }
+        const readCall = traces.find((t) => t.tool.toLowerCase().includes("read"));
+        const writeCall = traces.find((t) => /write|edit/i.test(t.tool));
+        console.log(`  captured ${traces.length} tool events:`, traces.map((t) => t.tool));
+        if (readCall && writeCall) {
+            console.log("  Gate 1: PASS (Read + Write observed — assertions are feasible)");
+        }
+        else {
+            console.log("  Gate 1: PARTIAL — traces captured but expected tools missing");
+            process.exit(3);
+        }
+    }
+    catch (err) {
+        console.error(`  Gate 1: FAIL — ${err.message}`);
+        process.exit(3);
+    }
+    // ---- Gate 2: baseline fetch ----------------------------------------
+    console.log("\n[Gate 2] git baseline fetch (old skill version)");
+    try {
+        execFileSync("git", ["init"], { cwd: fixtureRepo });
+        execFileSync("git", ["add", "-A"], { cwd: fixtureRepo });
+        execFileSync("git", ["-c", "user.email=spike@skilldiff", "-c", "user.name=spike", "commit", "-m", "init"], { cwd: fixtureRepo });
+        // modify the skill, then try fetching the old one from HEAD~1
+        const skillPath = join(fixtureRepo, ".claude", "skills", "notes-helper", "SKILL.md");
+        await writeFile(skillPath, "---\nname: notes-helper\n---\n\nCHANGED instructions.");
+        execFileSync("git", ["add", "-A"], { cwd: fixtureRepo });
+        execFileSync("git", ["-c", "user.email=spike@skilldiff", "-c", "user.name=spike", "commit", "-m", "change skill"], { cwd: fixtureRepo });
+        const oldContent = execFileSync("git", ["show", "HEAD~1:.claude/skills/notes-helper/SKILL.md"], { cwd: fixtureRepo }).toString();
+        const ok = oldContent.includes("ORIGINAL");
+        console.log(`  git show of old skill: ${ok ? "OK (original content retrieved)" : "MISMATCH"}`);
+        console.log(ok ? "  Gate 2: PASS" : "  Gate 2: FAIL");
+        process.exit(ok ? 0 : 4);
+    }
+    catch (err) {
+        console.error(`  Gate 2: FAIL — ${err.message}`);
+        process.exit(4);
+    }
+}
+async function makeMinimalFixture() {
+    const dir = await mkdtemp(join(tmpdir(), "skilldiff-fixture-"));
+    const skillDir = join(dir, ".claude", "skills", "notes-helper");
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(join(skillDir, "SKILL.md"), [
+        "---",
+        "name: notes-helper",
+        "description: Helps take and organize notes",
+        "---",
+        "",
+        "# notes-helper",
+        "",
+        "When asked to take a note: create or update NOTES.md with the content,",
+        "then confirm what you wrote.",
+        "",
+        "ORIGINAL instructions for baseline comparison.",
+    ].join("\n"));
+    await writeFile(join(dir, "NOTES.md"), "Instructions: use the notes-helper skill to append 'SPIKE RAN OK' to this file.");
+    console.log(`  created minimal fixture at ${dir}`);
+    return dir;
+}
+// direct execution support: `tsx scripts/spike.ts`
+if (import.meta.url === `file://${process.argv[1]}`) {
+    await runSpike(process.argv[2]);
+}

package/dist/src/assertions.d.ts

@@ -0,0 +1,33 @@
+import type { Expectations } from "./scenario.js";
+/** Normalized tool name — harnesses name the same tool differently. */
+export declare function normalizeToolName(tool: string): string;
+/** Everything observable from one agent run. Produced by the runner. */
+export interface RunTrace {
+    toolCalls: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+    }>;
+    /** File paths changed/created relative to fixture root. */
+    filesChanged: string[];
+    /** Full command strings that were executed (from bash-like tool calls). */
+    commandsRun: string[];
+    /** The agent's final text output. */
+    output: string;
+    /** Non-fatal problems encountered during the run (e.g. harness truncation). */
+    warnings: string[];
+}
+export interface AssertionResult {
+    kind: AssertionKind;
+    /** What was being asserted (the expected value or pattern). */
+    expected: string;
+    pass: boolean;
+    /** Human-readable explanation of what actually happened. */
+    actual: string;
+}
+type AssertionKind = "files_changed" | "commands_run" | "tool_calls" | "must_not" | "output_contains";
+export declare function evaluateAssertions(trace: RunTrace, expect: Expectations): AssertionResult[];
+export declare function summarize(results: AssertionResult[]): {
+    passed: number;
+    failed: number;
+};
+export {};

package/dist/src/assertions.js

@@ -0,0 +1,101 @@
+// skilldiff v0.1 — the 5 assertion kinds, evaluated against a run trace.
+// All matching is partial (substring / set membership) per design-decisions.md.
+/** Normalized tool name — harnesses name the same tool differently. */
+export function normalizeToolName(tool) {
+    const t = tool.toLowerCase();
+    if (/read|view_file|open_file/.test(t))
+        return "read";
+    if (/write|create_file|new_file|edit|str_replace|update_file|multiedit/.test(t))
+        return "write";
+    if (/bash|exec_command|shell|command_execution/.test(t))
+        return "bash";
+    if (/glob|ls_dir|list_dir|find/.test(t))
+        return "glob";
+    if (/grep|search/.test(t))
+        return "grep";
+    if (/spawn|task|subagent/.test(t))
+        return "spawn";
+    return t;
+}
+function partialMatch(haystacks, needle) {
+    const n = needle.toLowerCase();
+    return haystacks.some((h) => h.toLowerCase().includes(n));
+}
+export function evaluateAssertions(trace, expect) {
+    const results = [];
+    // files_changed
+    for (const expected of expect.files_changed ?? []) {
+        const pass = partialMatch(trace.filesChanged, expected);
+        results.push({
+            kind: "files_changed",
+            expected,
+            pass,
+            actual: trace.filesChanged.length > 0 ? `changed: [${trace.filesChanged.join(", ")}]` : "no files changed",
+        });
+    }
+    // commands_run
+    for (const expected of expect.commands_run ?? []) {
+        const pass = partialMatch(trace.commandsRun, expected);
+        results.push({
+            kind: "commands_run",
+            expected,
+            pass,
+            actual: trace.commandsRun.length > 0 ? `ran: [${trace.commandsRun.join("; ")}]` : "no commands run",
+        });
+    }
+    // tool_calls
+    for (const expected of expect.tool_calls ?? []) {
+        const called = trace.toolCalls.map((tc) => normalizeToolName(tc.tool));
+        const pass = called.includes(normalizeToolName(expected));
+        results.push({
+            kind: "tool_calls",
+            expected,
+            pass,
+            actual: called.length > 0 ? `called: [${called.join(", ")}]` : "no tool calls",
+        });
+    }
+    // must_not — inverted lookups over the same observables
+    const mn = expect.must_not ?? {};
+    for (const forbidden of mn.files_changed ?? []) {
+        const violated = partialMatch(trace.filesChanged, forbidden);
+        results.push({
+            kind: "must_not",
+            expected: `files_changed does not include ${forbidden}`,
+            pass: !violated,
+            actual: violated ? `VIOLATED — ${forbidden} was changed` : `changed: [${trace.filesChanged.join(", ") || "none"}]`,
+        });
+    }
+    for (const forbidden of mn.commands_run ?? []) {
+        const violated = partialMatch(trace.commandsRun, forbidden);
+        results.push({
+            kind: "must_not",
+            expected: `commands_run does not include ${forbidden}`,
+            pass: !violated,
+            actual: violated ? `VIOLATED — ran: ${forbidden}` : `ran: [${trace.commandsRun.join("; ") || "none"}]`,
+        });
+    }
+    for (const forbidden of mn.tool_calls ?? []) {
+        const violated = trace.toolCalls.map((tc) => normalizeToolName(tc.tool)).includes(normalizeToolName(forbidden));
+        results.push({
+            kind: "must_not",
+            expected: `tool_calls does not include ${forbidden}`,
+            pass: !violated,
+            actual: violated ? `VIOLATED — called ${forbidden}` : "ok",
+        });
+    }
+    // output_contains
+    for (const expected of expect.output_contains ?? []) {
+        const pass = trace.output.toLowerCase().includes(expected.toLowerCase());
+        results.push({
+            kind: "output_contains",
+            expected,
+            pass,
+            actual: trace.output ? `output: "${trace.output.slice(0, 200)}"` : "(no output)",
+        });
+    }
+    return results;
+}
+export function summarize(results) {
+    const passed = results.filter((r) => r.pass).length;
+    return { passed, failed: results.length - passed };
+}

package/dist/src/baseline.d.ts

@@ -0,0 +1,14 @@
+export interface SkillVersion {
+    /** Temp directory containing the skill files at this version. */
+    dir: string;
+    /** The files successfully retrieved (repo-relative paths). */
+    files: string[];
+}
+export declare function gitRefExists(repoPath: string, ref: string): boolean;
+/**
+ * Fetch skill files as of `baseRef` into a temp directory.
+ * Missing files at that ref are skipped and reported in `files` (only found ones listed).
+ */
+export declare function fetchSkillVersion(repoPath: string, baseRef: string, skillPaths: string[]): Promise<SkillVersion>;
+/** Clean up a fetched version's temp dir (best effort). */
+export declare function cleanupSkillVersion(version: SkillVersion): Promise<void>;

package/dist/src/baseline.js

@@ -0,0 +1,58 @@
+// skilldiff v0.1 — baseline fetch: retrieve the OLD version of skill files
+// from a git ref (base branch / commit) without touching the working tree.
+//
+// Design doc decision: `git show <base>:<path>` into a temp copy.
+// Gate 2 of the spike validated exactly this mechanism.
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+function gitShow(repoPath, ref, filePath) {
+    try {
+        return execFileSync("git", ["show", `${ref}:${filePath}`], {
+            cwd: repoPath,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+    }
+    catch {
+        return null; // file did not exist at that ref
+    }
+}
+export function gitRefExists(repoPath, ref) {
+    try {
+        execFileSync("git", ["rev-parse", "--verify", ref], { cwd: repoPath });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Fetch skill files as of `baseRef` into a temp directory.
+ * Missing files at that ref are skipped and reported in `files` (only found ones listed).
+ */
+export async function fetchSkillVersion(repoPath, baseRef, skillPaths) {
+    if (!gitRefExists(repoPath, baseRef)) {
+        throw new Error(`git ref '${baseRef}' not found in ${repoPath}`);
+    }
+    const dir = await mkdtemp(join(tmpdir(), "skilldiff-baseline-"));
+    const files = [];
+    for (const skillPath of skillPaths) {
+        const content = gitShow(repoPath, baseRef, skillPath);
+        if (content === null)
+            continue;
+        const dest = join(dir, skillPath);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, content);
+        files.push(skillPath);
+    }
+    if (files.length === 0) {
+        await rm(dir, { recursive: true, force: true });
+        throw new Error(`none of the skill paths exist at ref '${baseRef}': ${skillPaths.join(", ")}`);
+    }
+    return { dir, files };
+}
+/** Clean up a fetched version's temp dir (best effort). */
+export async function cleanupSkillVersion(version) {
+    await rm(version.dir, { recursive: true, force: true }).catch(() => { });
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// skilldiff CLI — entry point
+// Commands:
+//   spike            go/no-go harness validation
+//   run <scenario>   run a behavior-diff scenario (recorded or live)
+import { resolve } from "node:path";
+function usage() {
+    console.error(`Usage:
+  skilldiff init [dir]              discover skills, emit starter scenarios
+  skilldiff run <scenario.yaml> [--old recorded.json] [--new recorded.json]
+                 [--live] [--base <git-ref>]
+  skilldiff spike [fixture-path]
+  skilldiff --version`);
+    process.exit(1);
+}
+const [command, ...args] = process.argv.slice(2);
+switch (command) {
+    case "spike": {
+        const { runSpike } = await import("../scripts/spike.js");
+        await runSpike(args[0]);
+        break;
+    }
+    case "run": {
+        const scenarioPath = args[0];
+        if (!scenarioPath)
+            usage();
+        let oldTrace;
+        let newTrace;
+        let live = false;
+        let base;
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--old")
+                oldTrace = args[++i];
+            else if (args[i] === "--new")
+                newTrace = args[++i];
+            else if (args[i] === "--live")
+                live = true;
+            else if (args[i] === "--base")
+                base = args[++i];
+            else
+                usage();
+        }
+        const { loadScenario } = await import("./scenario.js");
+        const { runScenario } = await import("./runner.js");
+        const scenario = await loadScenario(scenarioPath);
+        const result = await runScenario(scenario, {
+            oldTrace: oldTrace ? resolve(oldTrace) : undefined,
+            newTrace: newTrace ? resolve(newTrace) : undefined,
+            live,
+            base,
+        });
+        console.log(result.report);
+        process.exit(result.passed ? 0 : 1);
+        break;
+    }
+    case "init": {
+        const { runInit, printInitSummary } = await import("./init.js");
+        const result = await runInit(resolve(args[0] ?? process.cwd()));
+        printInitSummary(result);
+        break;
+    }
+    case "--version":
+    case "-v":
+        console.log("skilldiff 0.1.0");
+        break;
+    default:
+        console.error(`Unknown command: ${command ?? "(none)"}`);
+        usage();
+}

package/dist/src/discover.d.ts

@@ -0,0 +1,22 @@
+export interface DiscoveredSkill {
+    /** Repo-relative path to SKILL.md */
+    path: string;
+    /** Skill name from frontmatter, or directory name. */
+    name: string;
+    /** Description from frontmatter, if present. */
+    description: string;
+}
+/** Discover SKILL.md files in conventional locations under repoRoot. */
+export declare function discoverSkills(repoRoot: string): Promise<DiscoveredSkill[]>;
+/**
+ * Infer a starter prompt for a skill.
+ * Strategy: ask the agent to read the skill's own SKILL.md and follow it —
+ * works generically for any skill, exercises the read path by construction.
+ */
+export declare function inferPrompt(skill: DiscoveredSkill): string;
+/**
+ * Build a starter scenario object for one discovered skill.
+ * Expectations start minimal (tool_calls: [read]) and grow as the user
+ * learns the skill's real behavior — init prints guidance on this.
+ */
+export declare function buildStarterScenario(skill: DiscoveredSkill): Record<string, unknown>;

package/dist/src/discover.js

@@ -0,0 +1,104 @@
+// skilldiff v0.1 — skill auto-discovery for `skilldiff init`.
+// Scans a repo for SKILL.md files in conventional locations and infers a
+// starter scenario (name, skillPaths, prompt, expect) from each one.
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+function parseFrontmatter(text) {
+    const fm = {};
+    const match = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (!match)
+        return fm;
+    for (const line of match[1].split("\n")) {
+        const idx = line.indexOf(":");
+        if (idx > 0) {
+            fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+        }
+    }
+    return fm;
+}
+async function findSkillFilesInDir(baseDir, skillsDir, depth = 0, out = []) {
+    if (depth > 3)
+        return out; // skills are shallow: <skills>/<name>/SKILL.md
+    let entries;
+    try {
+        entries = await readdir(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        const skillMd = join(skillsDir, entry.name, "SKILL.md");
+        try {
+            const s = await stat(skillMd);
+            if (s.isFile())
+                out.push(skillMd);
+            else
+                await findSkillFilesInDir(baseDir, join(skillsDir, entry.name), depth + 1, out);
+        }
+        catch {
+            // not a skill dir; recurse one level (handles skills/<category>/<name>/SKILL.md)
+            await findSkillFilesInDir(baseDir, join(skillsDir, entry.name), depth + 1, out);
+        }
+    }
+    return out;
+}
+/** Discover SKILL.md files in conventional locations under repoRoot. */
+export async function discoverSkills(repoRoot) {
+    const candidateRoots = [
+        join(repoRoot, ".claude", "skills"),
+        join(repoRoot, "skills"),
+        join(repoRoot, ".agents", "skills"),
+    ];
+    const found = new Map();
+    for (const root of candidateRoots) {
+        const files = await findSkillFilesInDir(repoRoot, root);
+        for (const file of files) {
+            const rel = relative(repoRoot, file).split("\\").join("/");
+            if (found.has(rel))
+                continue;
+            let text = "";
+            try {
+                text = await readFile(file, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const fm = parseFrontmatter(text);
+            const dirName = rel.split("/").slice(-2, -1)[0] ?? "skill";
+            found.set(rel, {
+                path: rel,
+                name: fm.name || dirName,
+                description: fm.description || "",
+            });
+        }
+    }
+    return [...found.values()];
+}
+/**
+ * Infer a starter prompt for a skill.
+ * Strategy: ask the agent to read the skill's own SKILL.md and follow it —
+ * works generically for any skill, exercises the read path by construction.
+ */
+export function inferPrompt(skill) {
+    return (`You have a skill named "${skill.name}". Read the file ${skill.path} in this repo ` +
+        `and follow its instructions exactly.` +
+        (skill.description ? ` (${skill.description})` : ""));
+}
+/**
+ * Build a starter scenario object for one discovered skill.
+ * Expectations start minimal (tool_calls: [read]) and grow as the user
+ * learns the skill's real behavior — init prints guidance on this.
+ */
+export function buildStarterScenario(skill) {
+    return {
+        name: skill.name,
+        skillPaths: [skill.path],
+        fixture: "./", // TODO: point at a real fixture repo; "." works for self-testing
+        prompt: inferPrompt(skill),
+        expect: {
+            tool_calls: ["read"],
+        },
+    };
+}

package/dist/src/init.d.ts

@@ -0,0 +1,9 @@
+import { type DiscoveredSkill } from "./discover.js";
+export declare function runInit(repoRoot: string, outDir?: string): Promise<{
+    created: string[];
+    skills: DiscoveredSkill[];
+}>;
+export declare function printInitSummary(result: {
+    created: string[];
+    skills: DiscoveredSkill[];
+}): void;

package/dist/src/init.js

@@ -0,0 +1,66 @@
+// skilldiff v0.1 — `skilldiff init`: scan the repo for skills and emit
+// starter scenario YAMLs so users get value in under a minute.
+import { writeFile, mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { discoverSkills, buildStarterScenario } from "./discover.js";
+function scenarioToYaml(scenario) {
+    const lines = [];
+    lines.push(`name: ${scenario.name}`);
+    lines.push(`skillPaths:`);
+    for (const p of scenario.skillPaths)
+        lines.push(`  - ${p}`);
+    lines.push(`fixture: ${scenario.fixture}`);
+    lines.push(`prompt: >-`);
+    lines.push(`  ${scenario.prompt.replace(/\n+/g, " ")}`);
+    lines.push(`expect:`);
+    const expect = scenario.expect;
+    lines.push(`  tool_calls:`);
+    for (const t of expect.tool_calls)
+        lines.push(`    - ${t}`);
+    return lines.join("\n") + "\n";
+}
+export async function runInit(repoRoot, outDir = "skilldiff") {
+    const skills = await discoverSkills(repoRoot);
+    if (skills.length === 0) {
+        return { created: [], skills };
+    }
+    const absOutDir = resolve(outDir); // resolve against cwd, NOT repoRoot
+    await mkdir(absOutDir, { recursive: true });
+    const created = [];
+    for (const skill of skills) {
+        const file = join(absOutDir, `${skill.name}.scenario.yaml`);
+        const yaml = scenarioToYaml(buildStarterScenario(skill));
+        await writeFile(file, yaml);
+        created.push(file);
+    }
+    return { created, skills };
+}
+export function printInitSummary(result) {
+    if (result.skills.length === 0) {
+        console.log("No SKILL.md files found in conventional locations:");
+        console.log("  .claude/skills/, skills/, .agents/skills/");
+        console.log("\nTo test a skill elsewhere, write a scenario manually:");
+        console.log("  https://github.com/scs0209/skilldiff#quickstart");
+        return;
+    }
+    console.log(`Found ${result.skills.length} skill(s):\n`);
+    for (const skill of result.skills) {
+        console.log(`  ${skill.name}${skill.description ? ` — ${skill.description}` : ""}`);
+        console.log(`    ${skill.path}`);
+    }
+    console.log(`\nCreated starter scenarios:`);
+    for (const file of result.created) {
+        console.log(`  ${file}`);
+    }
+    console.log(`
+Next steps:
+  1. Point 'fixture' in each scenario at a small repo the skill can safely
+     operate on (a temp copy of a real project works well).
+  2. Strengthen 'expect' once you've seen the skill's real behavior — start
+     with what it MUST do, then add must_not for what it must NEVER do.
+  3. Try a live run:
+       skilldiff run <scenario>.yaml --live
+  4. Capture traces for CI (recorded mode):
+       skilldiff run <scenario>.yaml --live --save-trace traces/
+`);
+}

package/dist/src/report.d.ts

@@ -0,0 +1,7 @@
+import type { RunTrace, AssertionResult } from "./assertions.js";
+export interface SideResult {
+    label: string;
+    trace: RunTrace;
+    assertions: AssertionResult[];
+}
+export declare function formatReport(scenarioName: string, sides: SideResult[]): string;