@alex.botez/elaborate 1.0.0

package/dist/skill/adapter.js

@@ -0,0 +1,278 @@
+/**
+ * Skill adapter — shell interface to the durable session workflow.
+ *
+ * Translates shell arguments into durable execute calls and returns JSON to stdout.
+ * Bundled alongside SKILL.md into a single deployable artifact.
+ *
+ * Commands:
+ *   start                    Create session or resume, return current prompt
+ *   response --message="..."    Answer pending prompt with user message (or pipe text to stdin)
+ *   inference --data='{...}'  Answer pending infer with extraction data (or pipe JSON to stdin)
+ *   status                   Query session state
+ *
+ * All output is JSON to stdout. Errors: { error: "..." } + exit code 1.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Suspend, execute } from "../durable/index.js";
+import { createSession, ArtifactAggregate, createFilePersistence, archiveSession, archiveCorrupted, CorruptedSessionError } from "../phases/index.js";
+import { isDeviationError } from "../interview/index.js";
+import { createLogger, noopLogger } from "./log.js";
+function getArg(args, prefix) {
+    const match = args.find((a) => a.startsWith(`${prefix}=`));
+    if (match)
+        return match.slice(prefix.length + 1);
+    const idx = args.indexOf(prefix);
+    if (idx !== -1 && idx + 1 < args.length)
+        return args[idx + 1];
+    return undefined;
+}
+let logger = noopLogger;
+function output(data) {
+    console.log(JSON.stringify(data));
+}
+function error(message) {
+    logger.error({ event: "error" }, message);
+    output({ error: message });
+    process.exit(1);
+}
+/** Oneshot resolver: resolves one matching response, suspends everything else. No response = suspend all. */
+function createResolver(response) {
+    return async (prompt) => {
+        if (response && prompt.id === response.id)
+            return response.value;
+        throw new Suspend(prompt.id, prompt);
+    };
+}
+/** prompt → target: user, infer → target: agent */
+function formatPrompt(prompt) {
+    if (prompt.type === "prompt") {
+        return {
+            message: prompt.request.message,
+            target: "user",
+            schema: {},
+        };
+    }
+    return {
+        message: prompt.request.message,
+        target: "agent",
+        schema: (prompt.request.schema ?? {}),
+    };
+}
+const END_OUTPUT = {
+    message: "This session is complete.",
+    target: "end",
+    schema: {},
+};
+/** Bridge session title from aggregate purpose to persistence. */
+function bridgeTitle(agg, persistence) {
+    const purpose = agg.data.purpose?.statement;
+    if (purpose)
+        persistence.setTitle(purpose);
+}
+/** Execute workflow; output END on completion, or the suspended prompt on Suspend. */
+async function handle(cwd, persistence, workflow, resolver, agg, opts) {
+    try {
+        const result = await execute(persistence, workflow, resolver);
+        logFidelity(result.fidelity);
+        if (agg.userConcern)
+            persistence.setUserConcern(agg.userConcern);
+        bridgeTitle(agg, persistence);
+        archiveSession(cwd);
+        output(END_OUTPUT);
+    }
+    catch (e) {
+        if (e instanceof Suspend) {
+            if (!e.value || typeof e.value !== "object" || !("type" in e.value)) {
+                throw new Error(`Suspend at ${e.id} carried non-Prompt value`);
+            }
+            const prompt = e.value;
+            logger.info({
+                event: "suspend",
+                id: e.id,
+                type: prompt.type,
+                promptMessage: prompt.request.message,
+                ...("schema" in prompt.request ? { schema: prompt.request.schema } : {}),
+            });
+            bridgeTitle(agg, persistence);
+            const out = formatPrompt(prompt);
+            if (opts?.includeContext)
+                out.context = agg.summarize();
+            if (opts?.existingSession)
+                out.existingSession = true;
+            output(out);
+            return;
+        }
+        throw e;
+    }
+}
+/** Log per-extraction debug details and a summary warning when mismatches occurred. */
+function logFidelity(result) {
+    if (result.mismatched === 0)
+        return;
+    for (const d of result.details) {
+        logger.info({
+            event: "fidelity:mismatch",
+            id: d.id,
+            expectedKeys: d.expectedKeys,
+            actualKeys: d.actualKeys,
+            missingKeys: d.missingKeys,
+        });
+    }
+    logger.error({
+        event: "fidelity:summary",
+        checked: result.checked,
+        mismatched: result.mismatched,
+    }, `Extraction fidelity: ${result.mismatched}/${result.checked} extractions had missing keys`);
+}
+function requireSuspendedId(persistence) {
+    const id = persistence.suspendedId();
+    if (!id)
+        error("No pending prompt. Run 'start' first.");
+    return id;
+}
+async function handleStart(cwd, persistence, args) {
+    const isNew = args.includes("--new");
+    let existingSession = false;
+    try {
+        if (persistence.hasSession()) {
+            if (persistence.status() === "completed" || isNew) {
+                archiveSession(cwd);
+            }
+            else {
+                existingSession = true;
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof CorruptedSessionError && isNew) {
+            // --new on a corrupt session: archive with timestamp and proceed fresh.
+            const archived = archiveCorrupted(cwd);
+            logger.info({ event: "recover:archive-corrupted", archived });
+        }
+        else {
+            throw e;
+        }
+    }
+    const agg = new ArtifactAggregate();
+    const workflow = createSession(agg);
+    const resolver = createResolver();
+    await handle(cwd, persistence, workflow, resolver, agg, existingSession ? { includeContext: true, existingSession: true } : undefined);
+}
+async function handleResponse(cwd, persistence, args) {
+    let message = getArg(args, "--message");
+    if (message === undefined) {
+        if (process.stdin.isTTY) {
+            error("Missing message. Provide --message argument or pipe text to stdin.");
+        }
+        message = await readStdin();
+        if (!message.trim()) {
+            error("No message received on stdin.");
+        }
+    }
+    const id = requireSuspendedId(persistence);
+    logger.info({ event: "resolve", id, type: "prompt", message });
+    const agg = new ArtifactAggregate();
+    const workflow = createSession(agg);
+    const resolver = createResolver({ id, value: message });
+    await handle(cwd, persistence, workflow, resolver, agg);
+}
+async function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+async function handleInference(cwd, persistence, args) {
+    let dataStr = getArg(args, "--data");
+    if (dataStr === undefined) {
+        if (process.stdin.isTTY) {
+            error("Missing data. Provide --data argument or pipe JSON to stdin.");
+        }
+        dataStr = await readStdin();
+        if (!dataStr.trim()) {
+            error("No data received on stdin.");
+        }
+    }
+    let data;
+    try {
+        data = JSON.parse(dataStr);
+    }
+    catch {
+        error("Invalid JSON in --data argument.");
+    }
+    const id = requireSuspendedId(persistence);
+    logger.info({ event: "resolve", id, type: "infer", data });
+    const agg = new ArtifactAggregate();
+    const workflow = createSession(agg);
+    const resolver = createResolver({ id, value: data });
+    await handle(cwd, persistence, workflow, resolver, agg);
+}
+function handleStatus(persistence) {
+    if (!persistence.hasSession()) {
+        output({ active: false });
+        return;
+    }
+    const status = persistence.status();
+    const title = persistence.title();
+    output({
+        active: true,
+        phase: persistence.phase() ?? "unknown",
+        sessionId: persistence.sessionId(),
+        ...(title ? { title } : {}),
+        ...(status === "failed" ? { status: "failed" } : {}),
+    });
+}
+async function main() {
+    const skillDir = typeof __dirname !== "undefined"
+        ? __dirname
+        : dirname(fileURLToPath(import.meta.url));
+    // Drop a .debug file next to the bundle to attach a debugger on launch
+    if (existsSync(join(skillDir, ".debug"))) {
+        const inspector = await import("node:inspector");
+        inspector.default.open(9229, "127.0.0.1", true);
+    }
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const cwd = process.cwd();
+    const persistence = createFilePersistence(cwd);
+    logger = createLogger(skillDir, cwd, {
+        sessionId: () => persistence.sessionId(),
+    });
+    try {
+        switch (command) {
+            case "start":
+                await handleStart(cwd, persistence, args.slice(1));
+                break;
+            case "response":
+                await handleResponse(cwd, persistence, args.slice(1));
+                break;
+            case "inference":
+                await handleInference(cwd, persistence, args.slice(1));
+                break;
+            case "status":
+                handleStatus(persistence);
+                break;
+            default:
+                error(`Unknown command: ${command ?? "(none)"}\n\nUsage:\n  elaborate start [--new]             Create session (--new: archive existing)\n  elaborate response --message="..."  Process stakeholder message\n  elaborate inference --data='{...}'  Provide extraction results\n  elaborate status                    Query session state`);
+        }
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        logger.error({ event: "error", class: err.constructor.name }, err.message);
+        if (err instanceof CorruptedSessionError) {
+            error(`${err.message}\n\nRun 'elaborate start --new' to archive the corrupt file and start fresh.`);
+        }
+        if (isDeviationError(err)) {
+            output({ error: "deviation_exhausted", deviation: err.name, response: err.response });
+            process.exit(1);
+        }
+        error(err.message);
+    }
+}
+main();
+//# sourceMappingURL=adapter.js.map

package/dist/skill/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/skill/adapter.ts"],"names":[],"mappings":"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"}

package/dist/skill/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Skill layer — public barrel.
+ *
+ * The skill is consumed primarily via the `bin` entry (`dist/skill/adapter.js`),
+ * not via library import. This barrel exists for toolkit-shape symmetry and
+ * surfaces only the logger interface for testability and any future
+ * programmatic adapter use. `adapter.ts` itself self-invokes `main()` and is
+ * not designed for library consumption.
+ */
+export { createLogger, noopLogger } from "./log.js";
+export type { Logger, LogContext } from "./log.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/skill/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skill/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/skill/index.js

@@ -0,0 +1,11 @@
+/**
+ * Skill layer — public barrel.
+ *
+ * The skill is consumed primarily via the `bin` entry (`dist/skill/adapter.js`),
+ * not via library import. This barrel exists for toolkit-shape symmetry and
+ * surfaces only the logger interface for testability and any future
+ * programmatic adapter use. `adapter.ts` itself self-invokes `main()` and is
+ * not designed for library consumption.
+ */
+export { createLogger, noopLogger } from "./log.js";
+//# sourceMappingURL=index.js.map

package/dist/skill/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skill/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/skill/log.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Opt-in structured logging for the adapter layer.
+ *
+ * Enabled by a `.log` marker file in the skill directory. When active, appends
+ * structured JSONL entries to `.elaborate/log.jsonl`. When inactive, returns a
+ * no-op logger (null-object pattern).
+ *
+ * Observation boundary: the logger captures adapter-level and framework-observable
+ * events without injecting into the durable replay loop. See ADR: logging.
+ */
+export type LogContext = Record<string, unknown>;
+export interface Logger {
+    info(fields: Record<string, unknown>, message?: string): void;
+    error(fields: Record<string, unknown>, message?: string): void;
+}
+export declare const noopLogger: Logger;
+export declare function createLogger(markerDir: string, logDir: string, context: LogContext | null): Logger;
+//# sourceMappingURL=log.d.ts.map

package/dist/skill/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/skill/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChE;AAED,eAAO,MAAM,UAAU,EAAE,MAGxB,CAAC;AAWF,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,GAAG,IAAI,GACzB,MAAM,CA+BR"}

package/dist/skill/log.js

@@ -0,0 +1,53 @@
+/**
+ * Opt-in structured logging for the adapter layer.
+ *
+ * Enabled by a `.log` marker file in the skill directory. When active, appends
+ * structured JSONL entries to `.elaborate/log.jsonl`. When inactive, returns a
+ * no-op logger (null-object pattern).
+ *
+ * Observation boundary: the logger captures adapter-level and framework-observable
+ * events without injecting into the durable replay loop. See ADR: logging.
+ */
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const noopLogger = {
+    info() { },
+    error() { },
+};
+function resolveContext(ctx) {
+    if (!ctx)
+        return {};
+    const resolved = {};
+    for (const [key, value] of Object.entries(ctx)) {
+        resolved[key] = typeof value === "function" ? value() : value;
+    }
+    return resolved;
+}
+export function createLogger(markerDir, logDir, context) {
+    const markerPath = join(markerDir, ".log");
+    if (!existsSync(markerPath))
+        return noopLogger;
+    const logPath = join(logDir, ".elaborate", "log.jsonl");
+    mkdirSync(dirname(logPath), { recursive: true });
+    function write(level, fields, message) {
+        const entry = {
+            v: 1,
+            ts: new Date().toISOString(),
+            level,
+            ...resolveContext(context),
+            ...fields,
+        };
+        if (message !== undefined)
+            entry.msg = message;
+        appendFileSync(logPath, JSON.stringify(entry) + "\n");
+    }
+    return {
+        info(fields, message) {
+            write("info", fields, message);
+        },
+        error(fields, message) {
+            write("error", fields, message);
+        },
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/skill/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/skill/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAS1C,MAAM,CAAC,MAAM,UAAU,GAAW;IAChC,IAAI,KAAI,CAAC;IACT,KAAK,KAAI,CAAC;CACX,CAAC;AAEF,SAAS,cAAc,CAAC,GAAsB;IAC5C,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,QAAQ,CAAC,GAAG,CAAC,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAChE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,SAAiB,EACjB,MAAc,EACd,OAA0B;IAE1B,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAE/C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IACxD,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEjD,SAAS,KAAK,CACZ,KAAuB,EACvB,MAA+B,EAC/B,OAAgB;QAEhB,MAAM,KAAK,GAA4B;YACrC,CAAC,EAAE,CAAC;YACJ,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,KAAK;YACL,GAAG,cAAc,CAAC,OAAO,CAAC;YAC1B,GAAG,MAAM;SACV,CAAC;QACF,IAAI,OAAO,KAAK,SAAS;YAAE,KAAK,CAAC,GAAG,GAAG,OAAO,CAAC;QAC/C,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IACxD,CAAC;IAED,OAAO;QACL,IAAI,CAAC,MAAM,EAAE,OAAO;YAClB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,KAAK,CAAC,MAAM,EAAE,OAAO;YACnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@alex.botez/elaborate",
+  "version": "1.0.0",
+  "description": "Agent skill that runs a Socratic interview inside your coding agent — turning vague ideas into structured intent",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexbot/elaborate.git"
+  },
+  "homepage": "https://github.com/alexbot/elaborate#readme",
+  "bugs": {
+    "url": "https://github.com/alexbot/elaborate/issues"
+  },
+  "exports": {
+    "./durable": {
+      "types": "./dist/durable/index.d.ts",
+      "import": "./dist/durable/index.js"
+    },
+    "./interview": {
+      "types": "./dist/interview/index.d.ts",
+      "import": "./dist/interview/index.js"
+    },
+    "./phases": {
+      "types": "./dist/phases/index.d.ts",
+      "import": "./dist/phases/index.js"
+    },
+    "./skill": {
+      "types": "./dist/skill/index.d.ts",
+      "import": "./dist/skill/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:skill": "node scripts/build-skill.mjs",
+    "deploy:skill": "node scripts/build-skill.mjs && node -e \"const fs=require('fs');fs.mkdirSync('.claude/skills/elaborate/scripts',{recursive:true});fs.copyFileSync('skills/elaborate/SKILL.md','.claude/skills/elaborate/SKILL.md');fs.copyFileSync('skills/elaborate/scripts/elaborate.cjs','.claude/skills/elaborate/scripts/elaborate.cjs');fs.copyFileSync('skills/elaborate/scripts/elaborate.cjs.map','.claude/skills/elaborate/scripts/elaborate.cjs.map')\" && echo Deployed to .claude/skills/elaborate/",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "eval": "vitest run --config vitest.eval.config.ts",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "ai",
+    "agent-skill",
+    "claude-code",
+    "discovery",
+    "elaboration",
+    "interview",
+    "project-scoping",
+    "requirements",
+    "socratic",
+    "specification"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^3.0.71",
+    "@ai-sdk/google": "^3.0.64",
+    "@ai-sdk/openai": "^3.0.53",
+    "@openrouter/ai-sdk-provider": "^2.9.0",
+    "@types/node": "^20.0.0",
+    "ai": "^6.0.168",
+    "esbuild": "^0.27.4",
+    "eslint": "^9.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.0.0",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "dependencies": {
+    "yaml": "^2.8.3",
+    "zod": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/skills/elaborate/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: elaborate
+description: "Facilitates project elaboration through Socratic dialog. Transforms vague project ideas into structured intent. Activates when someone mentions project planning, what should I build, scope definition, or goal clarification."
+---
+
+# Elaborate: Project Elaboration
+
+## Who you are
+
+You are an experienced interviewer helping a user scope their project. Your job is to surface what the user needs — especially what they haven't articulated yet. You ask questions. You don't provide solutions. The user decides.
+
+You carry a notebook: a small CLI tool with a structured interview flow drawn in it. The notebook tracks where you are in the interview, what's been discussed, and what to ask next. You don't memorize the process — you consult the notebook at each step.
+
+The notebook drives structure. You drive the conversation. Your expertise is semantic: understanding what the user means, extracting intent, and spotting ambiguity. The notebook handles sequencing and state.
+
+## Interview protocol
+
+Follow this exactly. The notebook commands are not optional. Run each command verbatim — do not modify, skip, or reorder any flags or arguments.
+
+**Before the first exchange**, open the notebook:
+
+```bash
+node "${CLAUDE_SKILL_DIR:-.}/scripts/elaborate.cjs" start
+```
+
+This either starts a new interview or resumes an existing one. On resume, the response may include a `context` field — a structured summary of what was captured so far. Fields: `purpose`, `advantage`, `measurement` (strings), `goals`, `stakeholders`, `inScope`, `outOfScope`, `constraints` (headline arrays), `assumptionCount`, `findingCount` (numbers). Use it to briefly orient the user ("Last time we discussed…") before presenting the next question. Keep the recap short; the user doesn't need every detail, just enough to re-engage. Only reference what appears in the context summary — do not embellish with details from memory or inference.
+
+**On each user message**, consult the notebook:
+
+```bash
+echo '<user message>' | node "${CLAUDE_SKILL_DIR:-.}/scripts/elaborate.cjs" response
+```
+
+Parse the JSON response and follow the `target` field:
+
+- **`target: "agent"`** — The notebook needs your expertise. Read `message` for the task and `schema` for the expected output fields. Complete the task described in `message` and report back by piping the JSON to stdin:
+  ```bash
+  echo '<extracted JSON>' | node "${CLAUDE_SKILL_DIR:-.}/scripts/elaborate.cjs" inference
+  ```
+  Parse the response. If `target` is still `"agent"`, repeat. Multiple extractions per turn are normal — the user sees none of this.
+
+- **`target: "user"`** — Present `message` to the user as-is. The message may begin with a bracketed progress indicator (e.g., `[3/7 Goals · constraints]`) — always include it verbatim. Wait for their response.
+
+- **`target: "end"`** — The interview is complete.
+
+If the response contains an `error` field instead of `target`, something went wrong. The format is `{ error: "<message>" }` for general errors (missing arguments, no pending prompt, corrupt state) or `{ error: "deviation_exhausted", deviation: "<class>", response: "<text>" }` when the respondent repeatedly did not answer a question. Tell the user the interview hit a problem and stop — do not retry the command.
+
+## Your responsibilities
+
+You and the notebook are two halves of one system:
+
+- **You** handle all semantic work: extracting meaning, detecting contradictions, composing context-appropriate questions, generating suggested answers. You never decide what comes next in the process.
+- **The notebook** handles all process decisions: what to ask, when to transition, how to handle gaps. It never interprets natural language.
+
+The notebook computes nothing semantic. You compute nothing procedural. It directs; you execute. Your outputs become its inputs for the next decision.
+
+## Agent task guidance
+
+When the notebook sends `target: "agent"`, follow the task in `message` and return the fields in `schema`. Tasks vary — extraction, composition, classification, and others. The `message` contains task-specific instructions; follow them.
+
+These principles apply to every agent task:
+
+1. Use only information from the conversation and the context provided in the task message. Do not fill gaps from your own domain knowledge.
+2. Partial or empty results are always better than guessed results. The notebook handles incomplete data gracefully — leave fields empty rather than fabricating plausible values.
+3. When the task references artifacts or context you cannot verify, work with what you have. Do not invent details to compensate for missing context.
+
+## What not to do
+
+- Never skip the notebook. Don't improvise the interview flow, even if you think you know what comes next.
+- Never self-resolve ambiguity. If something is unclear, surface it to the user — don't fill in your own interpretation.
+- Never show intermediate steps. The user sees only `target: "user"` messages, never extraction tasks.
+- Never retry a failed extraction. Report what you have and let the notebook decide.
+
+## Session continuity
+
+Interview state lives in `.elaborate/session.yaml` in the project directory. It survives IDE restarts.
+
+When you run `start`, the notebook checks for an existing session:
+
+- **No session** — starts a fresh interview.
+- **Completed session** — automatically archives it (renamed to `.elaborate/<slug>_<sessionId>.yaml`) and starts fresh.
+- **Active session (suspended/running)** — returns the pending prompt with `existingSession: true` and a `context` summary. Ask the user whether they want to continue this interview or start a new one. If they want to continue, present the pending question. If they want to start new, run:
+  ```bash
+  node "${CLAUDE_SKILL_DIR:-.}/scripts/elaborate.cjs" start --new
+  ```
+  This archives the existing session and begins a fresh interview.
+- **Corrupt session** — if the session file is unreadable, `start --new` archives the corrupt file and starts fresh. Without `--new`, a corrupt session produces an error with recovery instructions.
+
+You can query session state at any time without affecting the interview:
+
+```bash
+node "${CLAUDE_SKILL_DIR:-.}/scripts/elaborate.cjs" status
+```
+
+Returns `{ active: false }` if no session exists, or `{ active: true, phase, sessionId, title?, status? }` for an active session. The `status` field appears only when the session has failed.
+
+Archived sessions accumulate in `.elaborate/` alongside the active `session.yaml`. Their filenames include a human-readable slug derived from the session's purpose when available (e.g., `track-reading-habits_sess_2026-03-18_abc123.yaml`).