stoa-mcp 0.1.0

package/dist/storage/roles-refine.js

@@ -0,0 +1,223 @@
+/**
+ * Role Refine Pipeline.
+ * Runs a 3-stage refinement pipeline that transforms raw role definitions
+ * into precise, bounded, guardrail-ready specifications.
+ *
+ * Stage 1 — Sharpen Identity: Rewrite the role persona to be specific and unambiguous.
+ * Stage 2 — Define Boundaries: Generate explicit boundary rules (file scope, tech limits, escalation).
+ * Stage 3 — Suggest Guardrails: Print 2–4 guardrail suggestions to stdout only (no file writes).
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { spawn } from "child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const SPAWN_TIMEOUT_MS = 300_000;
+function rolesDir() {
+    return join(process.cwd(), ".stoa", "roles");
+}
+// ── Stage names ──────────────────────────────────────────────────────
+const STAGE_LABELS = [
+    "Stage 1: Sharpen Identity",
+    "Stage 2: Define Boundaries",
+    "Stage 3: Suggest Guardrails",
+];
+// ── Pure prompt builders ─────────────────────────────────────────────
+/**
+ * Build the Stage 1 prompt: Sharpen Identity.
+ * Rewrites the role persona to be specific, unambiguous, and self-contained.
+ * @param seed - The raw role markdown content.
+ * @returns The full prompt string for Stage 1.
+ */
+export function buildStage1Prompt(seed) {
+    return [
+        "You are a technical writing editor specializing in agent role definitions for software engineering teams.",
+        "",
+        "Rewrite the following role definition so it is specific, unambiguous, and self-contained.",
+        "The output must make it clear:",
+        "- What the role does (primary responsibilities)",
+        "- What its primary decisions are (what it chooses, prioritizes, or trades off)",
+        "- What communication style it uses (tone, verbosity, formality)",
+        "",
+        "Remove vague language. Replace subjective terms with concrete descriptions.",
+        "Preserve the original intent and any technical details.",
+        "Output only the rewritten role definition in markdown format — no preamble, no commentary.",
+        "Keep the original heading (# line) intact.",
+        "",
+        "---",
+        "",
+        seed,
+    ].join("\n");
+}
+/**
+ * Build the Stage 2 prompt: Define Boundaries.
+ * Generates explicit boundary rules covering file scope, technology limits, and escalation triggers.
+ * @param stage1Output - The sharpened role definition from Stage 1.
+ * @returns The full prompt string for Stage 2.
+ */
+export function buildStage2Prompt(stage1Output) {
+    return [
+        "You are a technical writing editor specializing in agent role definitions for software engineering teams.",
+        "",
+        "The following is a sharpened role definition. Append a `## Boundaries` section at the end.",
+        "The section must cover three areas:",
+        "",
+        "1. **File Scope** — Which directories and file types the role is authorized to read or modify.",
+        "   Use advisory language (e.g. \"Focus on: [...]\", \"Avoid: [...]\").",
+        "",
+        "2. **Technology Limits** — Specific libraries, languages, frameworks, or APIs the role should and should not use.",
+        "",
+        "3. **Escalation Triggers** — Conditions under which the role should pause and ask for human input",
+        "   rather than proceed autonomously (e.g. breaking changes, security-sensitive operations, ambiguous requirements).",
+        "",
+        "Each sub-area should be a subsection (### heading) within ## Boundaries.",
+        "Be specific and actionable — no vague advice.",
+        "Output the complete role definition with the new section appended — no preamble, no commentary.",
+        "",
+        "---",
+        "",
+        stage1Output,
+    ].join("\n");
+}
+/**
+ * Build the Stage 3 prompt: Suggest Guardrails.
+ * Generates 2–4 guardrail rule suggestions based on the sharpened identity and defined boundaries.
+ * @param stage2Output - The role definition with boundaries from Stage 2.
+ * @returns The full prompt string for Stage 3.
+ */
+export function buildStage3Prompt(stage2Output) {
+    return [
+        "You are a technical writing editor specializing in software engineering guardrails and coding standards.",
+        "",
+        "Given the following role definition (with identity and boundaries), suggest 2–4 guardrail rules",
+        "that would make this role safer and more reliable when operating autonomously.",
+        "",
+        "For each guardrail:",
+        "- Give it a short, descriptive title",
+        "- Write 3–5 checklist items (- [ ]) that are concrete and verifiable",
+        "- Include at least one BAD and one GOOD code/config example where relevant",
+        "",
+        "Format the output as markdown with each guardrail as a ## heading.",
+        "This output is advisory — it will be shown to a human for review.",
+        "Do not include any preamble or commentary outside the guardrail definitions.",
+        "",
+        "---",
+        "",
+        stage2Output,
+    ].join("\n");
+}
+// ── Execution helpers ────────────────────────────────────────────────
+async function executeStage(prompt, mode, model, apiKey) {
+    if (mode === "api") {
+        const client = new Anthropic({
+            apiKey: apiKey || process.env.ANTHROPIC_API_KEY,
+        });
+        const response = await client.messages.create({
+            model,
+            max_tokens: 4096,
+            messages: [{ role: "user", content: prompt }],
+        });
+        const textBlock = response.content.find((block) => block.type === "text");
+        return textBlock ? textBlock.text : "";
+    }
+    // claude-code mode — pipe prompt via stdin (the -p flag hangs as subprocess)
+    return new Promise((resolve, reject) => {
+        const child = spawn("claude", ["--print"], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let resolved = false;
+        let dataTimer = null;
+        const finish = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(overallTimer);
+            if (dataTimer)
+                clearTimeout(dataTimer);
+            child.kill();
+            resolve(stdout.trim());
+        };
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+            if (dataTimer)
+                clearTimeout(dataTimer);
+            dataTimer = setTimeout(finish, 2000);
+        });
+        child.on("close", () => {
+            finish();
+        });
+        const overallTimer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                if (dataTimer)
+                    clearTimeout(dataTimer);
+                child.kill("SIGKILL");
+                reject(new Error(`Claude Code timed out after ${SPAWN_TIMEOUT_MS / 1000}s`));
+            }
+        }, SPAWN_TIMEOUT_MS);
+        child.on("error", (err) => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(overallTimer);
+                if (dataTimer)
+                    clearTimeout(dataTimer);
+                reject(err);
+            }
+        });
+        // Write prompt to stdin and close it
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+}
+/**
+ * Run the 3-stage role refinement pipeline.
+ *
+ * - clipboard: Builds all 3 stage prompts and returns them via onStageComplete callback.
+ *   Does not call any AI API. Does not modify files.
+ * - api: Executes all 3 stages via Anthropic API. Writes stage 1+2 output to file.
+ *   Stage 3 output is returned but not written.
+ * - claude-code: Executes via Claude Code CLI. Writes stage 1+2 output to file.
+ *   Stage 3 output is returned but not written.
+ *
+ * @param options - Pipeline configuration including name, mode, and optional model/apiKey.
+ * @returns The prompts used and the final output.
+ * @throws If the role file does not exist.
+ */
+export async function refinePipeline(options) {
+    const filePath = join(rolesDir(), `${options.name}.md`);
+    if (!existsSync(filePath)) {
+        throw new Error(`Role not found: .stoa/roles/${options.name}.md`);
+    }
+    const seed = readFileSync(filePath, "utf-8");
+    const model = options.model ?? "claude-sonnet-4-6";
+    const builders = [buildStage1Prompt, buildStage2Prompt, buildStage3Prompt];
+    const prompts = [];
+    if (options.mode === "clipboard") {
+        // Clipboard mode: build prompts sequentially, no AI calls, no file writes
+        let currentInput = seed;
+        for (let i = 0; i < builders.length; i++) {
+            const prompt = builders[i](currentInput);
+            prompts.push(prompt);
+            options.onStageComplete?.(i, STAGE_LABELS[i], prompt);
+            // In clipboard mode, the "output" of each stage is the prompt itself
+            // (user will paste it manually). Chain the seed forward unchanged.
+            currentInput = prompt;
+        }
+        return { prompts, finalOutput: "" };
+    }
+    // api or claude-code mode
+    let currentInput = seed;
+    for (let i = 0; i < builders.length; i++) {
+        const prompt = builders[i](currentInput);
+        prompts.push(prompt);
+        currentInput = await executeStage(prompt, options.mode, model, options.apiKey);
+        options.onStageComplete?.(i, STAGE_LABELS[i], currentInput);
+        // After stage 2, write the result back to the role file (stages 1+2 combined)
+        if (i === 1) {
+            writeFileSync(filePath, currentInput, "utf-8");
+        }
+    }
+    // Stage 3 output is NOT written to any file — it's advisory only
+    return { prompts, finalOutput: currentInput };
+}
+//# sourceMappingURL=roles-refine.js.map

package/dist/storage/roles-refine.js.map

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

package/dist/storage/roles.d.ts

@@ -0,0 +1,6 @@
+export declare function listRoles(): string[];
+export declare function addRole(displayName: string): void;
+export declare function showRole(slug: string): string;
+export declare function removeRole(slug: string): void;
+export declare function loadRole(slug: string): string;
+//# sourceMappingURL=roles.d.ts.map

package/dist/storage/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/storage/roles.ts"],"names":[],"mappings":"AAQA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAOpC;AAED,wBAAgB,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAUjD;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQ7C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/storage/roles.js

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { toSlug } from "../utils/slug.js";
+function rolesDir() {
+    return join(process.cwd(), ".stoa", "roles");
+}
+export function listRoles() {
+    if (!existsSync(rolesDir()))
+        return [];
+    return readdirSync(rolesDir())
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .map((f) => f.replace(/\.md$/, ""));
+}
+export function addRole(displayName) {
+    const slug = toSlug(displayName);
+    const filePath = join(rolesDir(), `${slug}.md`);
+    if (existsSync(filePath)) {
+        throw new Error(`Role already exists: ${slug}`);
+    }
+    mkdirSync(rolesDir(), { recursive: true });
+    writeFileSync(filePath, `# ${displayName}\n\nYou are a ${displayName}.\n`, "utf-8");
+}
+export function showRole(slug) {
+    const filePath = join(rolesDir(), `${slug}.md`);
+    if (!existsSync(filePath)) {
+        throw new Error(`Role not found: ${slug}`);
+    }
+    return readFileSync(filePath, "utf-8");
+}
+export function removeRole(slug) {
+    const filePath = join(rolesDir(), `${slug}.md`);
+    if (!existsSync(filePath)) {
+        throw new Error(`Role not found: ${slug}`);
+    }
+    unlinkSync(filePath);
+}
+export function loadRole(slug) {
+    return showRole(slug);
+}
+//# sourceMappingURL=roles.js.map

package/dist/storage/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/storage/roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,SAAS,QAAQ;IACf,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,OAAO,WAAW,CAAC,QAAQ,EAAE,CAAC;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SAChC,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,WAAmB;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IAEhD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,SAAS,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,aAAa,CAAC,QAAQ,EAAE,KAAK,WAAW,iBAAiB,WAAW,KAAK,EAAE,OAAO,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IAEhD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IAEhD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,UAAU,CAAC,QAAQ,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}

package/dist/storage/scenarios-refine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Scenario Refine Pipeline.
+ * Runs a 3-stage refinement pipeline that transforms raw scenario hints from
+ * a spec into structured, validated scenario definitions.
+ *
+ * Stage 1 — Structure: Normalize scenario hints into canonical { given, expected } format.
+ * Stage 2 — Edge Cases: Print advisory edge-case suggestions to stdout (no file writes).
+ * Stage 3 — Validation Commands: Attach a shell snippet to each scenario for verification.
+ */
+/**
+ * Build the Stage 1 prompt: Structure.
+ * Transforms raw scenario hints into canonical { given, expected } format.
+ * @param scenarioHints - JSON string of raw scenario hints from the spec.
+ * @param specTitle - The task/spec title for context.
+ * @returns The full prompt string for Stage 1.
+ */
+export declare function buildStructurePrompt(scenarioHints: string, specTitle: string): string;
+/**
+ * Build the Stage 2 prompt: Edge Cases.
+ * Generates advisory edge-case suggestions based on structured scenarios.
+ * @param structuredScenarios - JSON string of structured scenarios from Stage 1.
+ * @param specTitle - The task/spec title for context.
+ * @returns The full prompt string for Stage 2.
+ */
+export declare function buildEdgeCasesPrompt(structuredScenarios: string, specTitle: string): string;
+/**
+ * Build the Stage 3 prompt: Validation Commands.
+ * Generates a shell command for each scenario to validate expected outcomes.
+ * @param structuredScenarios - JSON string of structured scenarios from Stage 1.
+ * @param specTitle - The task/spec title for context.
+ * @returns The full prompt string for Stage 3.
+ */
+export declare function buildValidationCommandPrompt(structuredScenarios: string, specTitle: string): string;
+/**
+ * Run the 3-stage scenario refinement pipeline.
+ *
+ * 1. Reads `.stoa/specs/<taskName>.json` for scenario hints.
+ * 2. Stage 1: Structure — normalizes hints into { given, expected }.
+ * 3. Stage 2: Edge Cases — prints advisory suggestions to stdout.
+ * 4. Stage 3: Validation Commands — attaches a bash snippet to each scenario.
+ * 5. Writes final output to `.stoa/scenarios/<taskName>.json` (api/cli mode only).
+ *
+ * @param taskName - The task name (matches the spec filename without extension).
+ * @param mode - Execution mode: "api", "clipboard", or "cli".
+ */
+export declare function generateScenarios(taskName: string, mode: "api" | "clipboard" | "cli"): Promise<void>;
+//# sourceMappingURL=scenarios-refine.d.ts.map

package/dist/storage/scenarios-refine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios-refine.d.ts","sourceRoot":"","sources":["../../src/storage/scenarios-refine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8CH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAoBrF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,mBAAmB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmB3F;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,mBAAmB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAqBnG;AAuGD;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,KAAK,GAAG,WAAW,GAAG,KAAK,GAChC,OAAO,CAAC,IAAI,CAAC,CA0Hf"}

package/dist/storage/scenarios-refine.js

@@ -0,0 +1,311 @@
+/**
+ * Scenario Refine Pipeline.
+ * Runs a 3-stage refinement pipeline that transforms raw scenario hints from
+ * a spec into structured, validated scenario definitions.
+ *
+ * Stage 1 — Structure: Normalize scenario hints into canonical { given, expected } format.
+ * Stage 2 — Edge Cases: Print advisory edge-case suggestions to stdout (no file writes).
+ * Stage 3 — Validation Commands: Attach a shell snippet to each scenario for verification.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { spawn } from "child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+const SPAWN_TIMEOUT_MS = 300_000;
+// ── Stage labels ─────────────────────────────────────────────────────
+const STAGE_LABELS = [
+    "Stage 1: Structure",
+    "Stage 2: Edge Cases",
+    "Stage 3: Validation Commands",
+];
+// ── Pure prompt builders ─────────────────────────────────────────────
+/**
+ * Build the Stage 1 prompt: Structure.
+ * Transforms raw scenario hints into canonical { given, expected } format.
+ * @param scenarioHints - JSON string of raw scenario hints from the spec.
+ * @param specTitle - The task/spec title for context.
+ * @returns The full prompt string for Stage 1.
+ */
+export function buildStructurePrompt(scenarioHints, specTitle) {
+    return [
+        "You are a QA engineer specializing in test scenario design.",
+        "",
+        "Given the following raw scenario hints from a task specification,",
+        "normalize each one into a structured JSON array of objects with exactly two fields:",
+        '- "given": A clear description of the initial condition or setup.',
+        '- "expected": A clear description of the expected outcome or behavior.',
+        "",
+        "Rules:",
+        "- Preserve the original intent of each scenario.",
+        "- If a hint has a title but no given/expected split, infer them from the title.",
+        "- If a hint is vague, make it concrete and testable.",
+        "- Output ONLY a valid JSON array — no preamble, no commentary.",
+        "",
+        `Task: ${specTitle}`,
+        "",
+        "Scenario hints:",
+        scenarioHints,
+    ].join("\n");
+}
+/**
+ * Build the Stage 2 prompt: Edge Cases.
+ * Generates advisory edge-case suggestions based on structured scenarios.
+ * @param structuredScenarios - JSON string of structured scenarios from Stage 1.
+ * @param specTitle - The task/spec title for context.
+ * @returns The full prompt string for Stage 2.
+ */
+export function buildEdgeCasesPrompt(structuredScenarios, specTitle) {
+    return [
+        "You are a QA engineer specializing in edge-case discovery.",
+        "",
+        "Given the following structured test scenarios for a task,",
+        "suggest additional edge cases that are NOT already covered.",
+        "",
+        "Rules:",
+        "- Output a plain numbered list of edge-case descriptions.",
+        "- Each item should be a single sentence describing the edge case.",
+        "- Focus on boundary conditions, error paths, and unusual inputs.",
+        "- Do NOT output JSON — just a numbered list.",
+        "- Do NOT repeat scenarios already covered.",
+        "",
+        `Task: ${specTitle}`,
+        "",
+        "Existing scenarios:",
+        structuredScenarios,
+    ].join("\n");
+}
+/**
+ * Build the Stage 3 prompt: Validation Commands.
+ * Generates a shell command for each scenario to validate expected outcomes.
+ * @param structuredScenarios - JSON string of structured scenarios from Stage 1.
+ * @param specTitle - The task/spec title for context.
+ * @returns The full prompt string for Stage 3.
+ */
+export function buildValidationCommandPrompt(structuredScenarios, specTitle) {
+    return [
+        "You are a DevOps engineer writing validation scripts.",
+        "",
+        "Given the following structured test scenarios for a task,",
+        "generate a single bash command (or short pipeline) for each scenario",
+        "that can be run to validate whether the expected outcome holds.",
+        "",
+        "Rules:",
+        "- Output a valid JSON array of objects, one per scenario, in the same order as the input.",
+        '- Each object must have: "given", "expected", "validationCommand".',
+        '- "validationCommand" is a single bash string that tests the expected behavior.',
+        "- Commands should be self-contained and runnable from the project root.",
+        "- Use common CLI tools (grep, jq, curl, test, diff, etc.).",
+        "- Output ONLY a valid JSON array — no preamble, no commentary.",
+        "",
+        `Task: ${specTitle}`,
+        "",
+        "Scenarios:",
+        structuredScenarios,
+    ].join("\n");
+}
+// ── Execution helper ─────────────────────────────────────────────────
+async function executeStage(prompt, mode, model, apiKey) {
+    if (mode === "api") {
+        const client = new Anthropic({
+            apiKey: apiKey || process.env.ANTHROPIC_API_KEY,
+        });
+        const response = await client.messages.create({
+            model,
+            max_tokens: 4096,
+            messages: [{ role: "user", content: prompt }],
+        });
+        const textBlock = response.content.find((block) => block.type === "text");
+        return textBlock ? textBlock.text : "";
+    }
+    // cli mode — pipe prompt via stdin (the -p flag hangs as subprocess)
+    return new Promise((resolve, reject) => {
+        const child = spawn("claude", ["--print"], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let resolved = false;
+        let dataTimer = null;
+        const finish = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(overallTimer);
+            if (dataTimer)
+                clearTimeout(dataTimer);
+            child.kill();
+            resolve(stdout.trim());
+        };
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+            if (dataTimer)
+                clearTimeout(dataTimer);
+            dataTimer = setTimeout(finish, 2000);
+        });
+        child.on("close", () => {
+            finish();
+        });
+        const overallTimer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                if (dataTimer)
+                    clearTimeout(dataTimer);
+                child.kill("SIGKILL");
+                reject(new Error(`Claude Code timed out after ${SPAWN_TIMEOUT_MS / 1000}s`));
+            }
+        }, SPAWN_TIMEOUT_MS);
+        child.on("error", (err) => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(overallTimer);
+                if (dataTimer)
+                    clearTimeout(dataTimer);
+                reject(err);
+            }
+        });
+        // Write prompt to stdin and close it
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+}
+// ── JSON extraction helper ───────────────────────────────────────────
+function extractFirstJsonArray(raw) {
+    const start = raw.indexOf("[");
+    if (start === -1)
+        return null;
+    let depth = 0;
+    for (let i = start; i < raw.length; i++) {
+        if (raw[i] === "[")
+            depth++;
+        else if (raw[i] === "]")
+            depth--;
+        if (depth === 0) {
+            try {
+                const parsed = JSON.parse(raw.slice(start, i + 1));
+                if (Array.isArray(parsed))
+                    return parsed;
+            }
+            catch {
+                return null;
+            }
+            return null;
+        }
+    }
+    return null;
+}
+// ── Pipeline ─────────────────────────────────────────────────────────
+/**
+ * Run the 3-stage scenario refinement pipeline.
+ *
+ * 1. Reads `.stoa/specs/<taskName>.json` for scenario hints.
+ * 2. Stage 1: Structure — normalizes hints into { given, expected }.
+ * 3. Stage 2: Edge Cases — prints advisory suggestions to stdout.
+ * 4. Stage 3: Validation Commands — attaches a bash snippet to each scenario.
+ * 5. Writes final output to `.stoa/scenarios/<taskName>.json` (api/cli mode only).
+ *
+ * @param taskName - The task name (matches the spec filename without extension).
+ * @param mode - Execution mode: "api", "clipboard", or "cli".
+ */
+export async function generateScenarios(taskName, mode) {
+    const baseDir = process.cwd();
+    const specPath = join(baseDir, ".stoa", "specs", `${taskName}.json`);
+    if (!existsSync(specPath)) {
+        process.stderr.write(`Error: Spec file not found: .stoa/specs/${taskName}.json\n`);
+        process.exit(1);
+    }
+    const specRaw = readFileSync(specPath, "utf-8");
+    const spec = JSON.parse(specRaw);
+    // Extract scenario hints — look for scenarios field from Stage 5 output
+    const scenarioHints = spec.scenarios ?? [];
+    const specTitle = spec.title ?? taskName;
+    if (scenarioHints.length === 0) {
+        process.stderr.write(`Warning: No scenario hints found in spec. The pipeline will generate from the spec context.\n`);
+    }
+    const hintsJson = JSON.stringify(scenarioHints, null, 2);
+    // ── Clipboard mode ──────────────────────────────────────────────
+    if (mode === "clipboard") {
+        const prompts = [
+            { label: STAGE_LABELS[0], prompt: buildStructurePrompt(hintsJson, specTitle) },
+            { label: STAGE_LABELS[1], prompt: buildEdgeCasesPrompt(hintsJson, specTitle) },
+            { label: STAGE_LABELS[2], prompt: buildValidationCommandPrompt(hintsJson, specTitle) },
+        ];
+        for (const { label, prompt } of prompts) {
+            const line = "─".repeat(40);
+            process.stdout.write(`\n${line}\n`);
+            process.stdout.write(`${label}\n`);
+            process.stdout.write(`${line}\n`);
+            process.stdout.write(`${prompt}\n`);
+        }
+        // Copy last prompt to clipboard
+        try {
+            const { execFileSync } = await import("node:child_process");
+            const allPrompts = prompts.map((p) => `--- ${p.label} ---\n${p.prompt}`).join("\n\n");
+            execFileSync("pbcopy", { input: allPrompts });
+            process.stdout.write(`\nPrompts copied to clipboard.\n`);
+        }
+        catch {
+            // Clipboard copy failed silently — prompts are already on stdout
+        }
+        return;
+    }
+    // ── API or CLI mode ─────────────────────────────────────────────
+    const model = "claude-sonnet-4-6";
+    const execMode = mode === "cli" ? "cli" : "api";
+    // Stage 1: Structure
+    process.stderr.write(`${STAGE_LABELS[0]}...\n`);
+    const stage1Prompt = buildStructurePrompt(hintsJson, specTitle);
+    const stage1Raw = await executeStage(stage1Prompt, execMode, model);
+    const stage1Parsed = extractFirstJsonArray(stage1Raw);
+    const structured = [];
+    if (stage1Parsed) {
+        for (const item of stage1Parsed) {
+            const obj = item;
+            if (typeof obj.given === "string" && typeof obj.expected === "string") {
+                structured.push({ given: obj.given, expected: obj.expected });
+            }
+        }
+    }
+    if (structured.length === 0) {
+        process.stderr.write("Error: Stage 1 produced no valid structured scenarios.\n");
+        process.exit(1);
+    }
+    process.stderr.write(`  → ${structured.length} scenarios structured.\n`);
+    // Stage 2: Edge Cases (advisory only — print to stdout, no writes)
+    process.stderr.write(`${STAGE_LABELS[1]}...\n`);
+    const structuredJson = JSON.stringify(structured, null, 2);
+    const stage2Prompt = buildEdgeCasesPrompt(structuredJson, specTitle);
+    const stage2Raw = await executeStage(stage2Prompt, execMode, model);
+    const line = "─".repeat(40);
+    process.stdout.write(`\n${line}\n`);
+    process.stdout.write(`Suggested Edge Cases (advisory only):\n`);
+    process.stdout.write(`${line}\n`);
+    process.stdout.write(`${stage2Raw}\n`);
+    // Stage 3: Validation Commands
+    process.stderr.write(`${STAGE_LABELS[2]}...\n`);
+    const stage3Prompt = buildValidationCommandPrompt(structuredJson, specTitle);
+    const stage3Raw = await executeStage(stage3Prompt, execMode, model);
+    const stage3Parsed = extractFirstJsonArray(stage3Raw);
+    const finalScenarios = [];
+    if (stage3Parsed) {
+        for (let i = 0; i < stage3Parsed.length; i++) {
+            const obj = stage3Parsed[i];
+            const base = structured[i] ?? { given: "", expected: "" };
+            finalScenarios.push({
+                given: typeof obj.given === "string" ? obj.given : base.given,
+                expected: typeof obj.expected === "string" ? obj.expected : base.expected,
+                validationCommand: typeof obj.validationCommand === "string" ? obj.validationCommand : "",
+            });
+        }
+    }
+    else {
+        // Fallback: use structured scenarios with empty validation commands
+        for (const s of structured) {
+            finalScenarios.push({ ...s, validationCommand: "" });
+        }
+    }
+    // Write output
+    const outPath = join(baseDir, ".stoa", "scenarios", `${taskName}.json`);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, JSON.stringify(finalScenarios, null, 2) + "\n", "utf-8");
+    process.stderr.write(`\nWritten: .stoa/scenarios/${taskName}.json (${finalScenarios.length} scenarios)\n`);
+}
+//# sourceMappingURL=scenarios-refine.js.map