@contractspec/bundle.workspace 1.44.0

package/dist/services/agent-guide/adapters/cursor-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-cli.js","names":["lines: string[]"],"sources":["../../../../src/services/agent-guide/adapters/cursor-cli.ts"],"sourcesContent":["/**\n * Cursor CLI Agent Adapter\n *\n * Formats implementation plans and prompts for Cursor's CLI/background mode.\n * Can also generate .mdc cursor rules files.\n */\n\nimport type { AnyOperationSpec } from '@contractspec/lib.contracts';\nimport type {\n  AgentPrompt,\n  ImplementationPlan,\n} from '@contractspec/lib.contracts/llm';\nimport { AGENT_SYSTEM_PROMPTS } from '@contractspec/lib.contracts/llm';\nimport type { AgentAdapter } from '../types';\n\n/**\n * Cursor CLI adapter implementation.\n * Optimized for Cursor's background/composer mode.\n */\nexport class CursorCLIAdapter implements AgentAdapter {\n  agentType = 'cursor-cli' as const;\n\n  /**\n   * Format an implementation plan for Cursor CLI.\n   * Uses concise format optimized for Cursor's context window.\n   */\n  formatPlan(plan: ImplementationPlan): AgentPrompt {\n    const lines: string[] = [];\n\n    // Compact header\n    lines.push(`# ${plan.target.key}.v${plan.target.version}`);\n    lines.push('');\n    lines.push(`> ${plan.context.goal}`);\n    lines.push('');\n\n    // Files to work on\n    if (plan.fileStructure.length > 0) {\n      lines.push('## Files');\n      lines.push('');\n      for (const file of plan.fileStructure) {\n        lines.push(`- ${file.type}: \\`${file.path}\\` - ${file.purpose}`);\n      }\n      lines.push('');\n    }\n\n    // Compact spec (key sections only)\n    lines.push('## Spec');\n    lines.push('');\n    lines.push(plan.specMarkdown);\n    lines.push('');\n\n    // Steps as simple list\n    lines.push('## Steps');\n    lines.push('');\n    for (const step of plan.steps) {\n      lines.push(`${step.order}. **${step.title}**: ${step.description}`);\n    }\n    lines.push('');\n\n    // Key constraints (compact)\n    const constraints = [\n      ...plan.constraints.policy,\n      ...plan.constraints.security.map((s) => `⚠️ ${s}`),\n    ];\n    if (constraints.length > 0) {\n      lines.push('## Constraints');\n      lines.push('');\n      for (const c of constraints) {\n        lines.push(`- ${c}`);\n      }\n      lines.push('');\n    }\n\n    // PII warning\n    if (plan.constraints.pii.length > 0) {\n      lines.push('## PII Fields');\n      lines.push('');\n      lines.push(\n        `Handle carefully: ${plan.constraints.pii.map((p) => `\\`${p}\\``).join(', ')}`\n      );\n      lines.push('');\n    }\n\n    return {\n      agent: 'cursor-cli',\n      systemPrompt: AGENT_SYSTEM_PROMPTS['cursor-cli'],\n      taskPrompt: lines.join('\\n'),\n    };\n  }\n\n  /**\n   * Generate Cursor rules (.mdc format) for a spec.\n   * Can be saved to .cursor/rules/ to provide persistent context.\n   */\n  generateConfig(spec: AnyOperationSpec): string {\n    const m = spec.meta;\n    const lines: string[] = [];\n\n    // MDC frontmatter\n    lines.push('---');\n    lines.push(`description: Implementation rules for ${m.key}.v${m.version}`);\n    lines.push(`globs: [\"**/${m.key.replace(/\\./g, '/')}/**\"]`);\n    lines.push('alwaysApply: false');\n    lines.push('---');\n    lines.push('');\n\n    // Rule content\n    lines.push(`# ${m.key} Implementation Rules`);\n    lines.push('');\n    lines.push(\n      `This ${m.kind} operation must follow the ContractSpec specification.`\n    );\n    lines.push('');\n\n    lines.push('## Goal');\n    lines.push('');\n    lines.push(m.goal);\n    lines.push('');\n\n    lines.push('## Requirements');\n    lines.push('');\n    lines.push('1. Input/output types MUST match the spec schema exactly');\n    lines.push('2. All error cases MUST be handled');\n\n    if (spec.sideEffects?.emits?.length) {\n      lines.push('3. Events MUST be emitted as specified');\n    }\n\n    lines.push(`4. Auth level: ${spec.policy.auth}`);\n\n    if (spec.policy.idempotent !== undefined) {\n      lines.push(`5. Idempotency: ${spec.policy.idempotent}`);\n    }\n    lines.push('');\n\n    // Error handling\n    if (spec.io.errors && Object.keys(spec.io.errors).length > 0) {\n      lines.push('## Error Cases');\n      lines.push('');\n      for (const [code, err] of Object.entries(spec.io.errors)) {\n        lines.push(`- \\`${code}\\` (HTTP ${err.http ?? 400}): ${err.when}`);\n      }\n      lines.push('');\n    }\n\n    // Events\n    if (spec.sideEffects?.emits?.length) {\n      lines.push('## Events to Emit');\n      lines.push('');\n      for (const e of spec.sideEffects.emits) {\n        if ('ref' in e) {\n          lines.push(`- \\`${e.ref.key}.v${e.ref.version}\\`: ${e.when}`);\n        } else {\n          lines.push(`- \\`${e.key}.v${e.version}\\`: ${e.when}`);\n        }\n      }\n      lines.push('');\n    }\n\n    // PII\n    if (spec.policy.pii?.length) {\n      lines.push('## PII Handling');\n      lines.push('');\n      lines.push('These fields contain PII and must be handled with care:');\n      for (const field of spec.policy.pii) {\n        lines.push(`- \\`${field}\\``);\n      }\n      lines.push('');\n    }\n\n    // Acceptance scenarios\n    if (spec.acceptance?.scenarios?.length) {\n      lines.push('## Acceptance Scenarios');\n      lines.push('');\n      for (const s of spec.acceptance.scenarios) {\n        lines.push(`### ${s.key}`);\n        lines.push(`- Given: ${s.given.join('; ')}`);\n        lines.push(`- When: ${s.when.join('; ')}`);\n        lines.push(`- Then: ${s.then.join('; ')}`);\n        lines.push('');\n      }\n    }\n\n    return lines.join('\\n');\n  }\n\n  /**\n   * Generate a cursor rules file path for a spec.\n   */\n  getCursorRulesPath(spec: AnyOperationSpec): string {\n    const safeName = spec.meta.key.replace(/\\./g, '-');\n    return `.cursor/rules/${safeName}.mdc`;\n  }\n\n  /**\n   * Parse Cursor output to extract generated code.\n   */\n  parseOutput(output: string): { code?: string; errors?: string[] } {\n    // Cursor typically returns code in markdown blocks\n    const codeBlockMatch = output.match(\n      /```(?:typescript|ts|tsx|javascript|js)?\\n([\\s\\S]*?)\\n```/\n    );\n\n    if (codeBlockMatch?.[1]) {\n      return { code: codeBlockMatch[1] };\n    }\n\n    // Return raw output if no code block\n    return { code: output };\n  }\n}\n\n/** Singleton instance */\nexport const cursorCLIAdapter = new CursorCLIAdapter();\n"],"mappings":"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"}

package/dist/services/agent-guide/adapters/generic-mcp.d.ts

@@ -0,0 +1,53 @@
+import { AgentAdapter } from "../types.js";
+import { AnyOperationSpec } from "@contractspec/lib.contracts";
+import { AgentPrompt, ImplementationPlan } from "@contractspec/lib.contracts/llm";
+
+//#region src/services/agent-guide/adapters/generic-mcp.d.ts
+
+/**
+ * Generic MCP adapter implementation.
+ * Works with any MCP-compatible agent (Cline, Aider, etc.).
+ */
+declare class GenericMCPAdapter implements AgentAdapter {
+  agentType: "generic-mcp";
+  /**
+   * Format an implementation plan for generic MCP agents.
+   * Uses a standard markdown format that works across different agents.
+   */
+  formatPlan(plan: ImplementationPlan): AgentPrompt;
+  /**
+   * Format the plan as an MCP resource.
+   * Returns JSON that can be served as an MCP resource.
+   */
+  formatAsResource(plan: ImplementationPlan): {
+    uri: string;
+    mimeType: string;
+    data: string;
+  };
+  /**
+   * Format the plan as an MCP prompt message.
+   */
+  formatAsPromptMessage(plan: ImplementationPlan): {
+    role: 'user' | 'assistant';
+    content: {
+      type: 'text';
+      text: string;
+    };
+  };
+  /**
+   * Generate configuration (generic markdown for any agent).
+   */
+  generateConfig(spec: AnyOperationSpec): string;
+  /**
+   * Parse agent output - generic implementation.
+   */
+  parseOutput(output: string): {
+    code?: string;
+    errors?: string[];
+  };
+}
+/** Singleton instance */
+declare const genericMCPAdapter: GenericMCPAdapter;
+//#endregion
+export { GenericMCPAdapter, genericMCPAdapter };
+//# sourceMappingURL=generic-mcp.d.ts.map

package/dist/services/agent-guide/adapters/generic-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-mcp.d.ts","names":[],"sources":["../../../../src/services/agent-guide/adapters/generic-mcp.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAiPa,cA9NA,iBAAA,YAA6B,YA8Nc,CAAA;;;;;;mBAvNrC,qBAAqB;;;;;yBAoHf;;;;;;;;8BA0BK;;;;;;;;;;uBAiBP;;;;;;;;;;cAwDV,mBAAiB"}

package/dist/services/agent-guide/adapters/generic-mcp.js

@@ -0,0 +1,159 @@
+import { AGENT_SYSTEM_PROMPTS } from "@contractspec/lib.contracts/llm";
+
+//#region src/services/agent-guide/adapters/generic-mcp.ts
+/**
+* Generic MCP adapter implementation.
+* Works with any MCP-compatible agent (Cline, Aider, etc.).
+*/
+var GenericMCPAdapter = class {
+	agentType = "generic-mcp";
+	/**
+	* Format an implementation plan for generic MCP agents.
+	* Uses a standard markdown format that works across different agents.
+	*/
+	formatPlan(plan) {
+		const lines = [];
+		lines.push(`# Implementation Task: ${plan.target.key}.v${plan.target.version}`);
+		lines.push("");
+		lines.push("## Task");
+		lines.push("");
+		lines.push(`Implement the ${plan.target.type} \`${plan.target.key}\` version ${plan.target.version}.`);
+		lines.push("");
+		lines.push("## Context");
+		lines.push("");
+		lines.push(`**Goal:** ${plan.context.goal}`);
+		lines.push("");
+		lines.push(`**Description:** ${plan.context.description}`);
+		lines.push("");
+		if (plan.context.background) {
+			lines.push("**Background:**");
+			lines.push("");
+			lines.push(plan.context.background);
+			lines.push("");
+		}
+		lines.push("## Specification");
+		lines.push("");
+		lines.push(plan.specMarkdown);
+		lines.push("");
+		if (plan.fileStructure.length > 0) {
+			lines.push("## Files");
+			lines.push("");
+			lines.push("| Path | Action | Purpose |");
+			lines.push("|------|--------|---------|");
+			for (const file of plan.fileStructure) lines.push(`| \`${file.path}\` | ${file.type} | ${file.purpose} |`);
+			lines.push("");
+		}
+		lines.push("## Implementation Steps");
+		lines.push("");
+		for (const step of plan.steps) {
+			lines.push(`### Step ${step.order}: ${step.title}`);
+			lines.push("");
+			lines.push(step.description);
+			lines.push("");
+			if (step.acceptanceCriteria.length > 0) {
+				lines.push("**Acceptance Criteria:**");
+				lines.push("");
+				for (const criteria of step.acceptanceCriteria) lines.push(`- ${criteria}`);
+				lines.push("");
+			}
+		}
+		lines.push("## Constraints");
+		lines.push("");
+		if (plan.constraints.policy.length > 0) {
+			lines.push("**Policy:**");
+			for (const p of plan.constraints.policy) lines.push(`- ${p}`);
+			lines.push("");
+		}
+		if (plan.constraints.security.length > 0) {
+			lines.push("**Security:**");
+			for (const s of plan.constraints.security) lines.push(`- ${s}`);
+			lines.push("");
+		}
+		if (plan.constraints.pii.length > 0) {
+			lines.push("**PII Fields (handle with care):**");
+			for (const pii of plan.constraints.pii) lines.push(`- \`${pii}\``);
+			lines.push("");
+		}
+		lines.push("## Verification");
+		lines.push("");
+		lines.push("After implementation, verify:");
+		lines.push("");
+		for (const check of plan.verificationChecklist) lines.push(`- [ ] ${check}`);
+		lines.push("");
+		return {
+			agent: "generic-mcp",
+			systemPrompt: AGENT_SYSTEM_PROMPTS["generic-mcp"],
+			taskPrompt: lines.join("\n")
+		};
+	}
+	/**
+	* Format the plan as an MCP resource.
+	* Returns JSON that can be served as an MCP resource.
+	*/
+	formatAsResource(plan) {
+		return {
+			uri: `spec://${plan.target.key}/v${plan.target.version}/plan`,
+			mimeType: "application/json",
+			data: JSON.stringify({
+				target: plan.target,
+				context: plan.context,
+				fileStructure: plan.fileStructure,
+				steps: plan.steps,
+				constraints: plan.constraints,
+				verificationChecklist: plan.verificationChecklist
+			}, null, 2)
+		};
+	}
+	/**
+	* Format the plan as an MCP prompt message.
+	*/
+	formatAsPromptMessage(plan) {
+		return {
+			role: "user",
+			content: {
+				type: "text",
+				text: this.formatPlan(plan).taskPrompt
+			}
+		};
+	}
+	/**
+	* Generate configuration (generic markdown for any agent).
+	*/
+	generateConfig(spec) {
+		const m = spec.meta;
+		const lines = [];
+		lines.push(`# ${m.key} v${m.version}`);
+		lines.push("");
+		lines.push(`**Type:** ${m.kind}`);
+		lines.push(`**Stability:** ${m.stability}`);
+		lines.push("");
+		lines.push("## Goal");
+		lines.push("");
+		lines.push(m.goal);
+		lines.push("");
+		lines.push("## Description");
+		lines.push("");
+		lines.push(m.description);
+		lines.push("");
+		return lines.join("\n");
+	}
+	/**
+	* Parse agent output - generic implementation.
+	*/
+	parseOutput(output) {
+		const codeBlockMatch = output.match(/```(?:typescript|ts|tsx|javascript|js|python|go|rust)?\n([\s\S]*?)\n```/);
+		if (codeBlockMatch?.[1]) return { code: codeBlockMatch[1] };
+		try {
+			const parsed = JSON.parse(output);
+			if (typeof parsed.code === "string") return { code: parsed.code };
+			if (typeof parsed.errors === "object") return { errors: Array.isArray(parsed.errors) ? parsed.errors : [String(parsed.errors)] };
+		} catch {}
+		return { code: output };
+	}
+};
+/** Singleton instance */
+const genericMCPAdapter = new GenericMCPAdapter();
+
+//#endregion
+export { GenericMCPAdapter, genericMCPAdapter };
+//# sourceMappingURL=generic-mcp.js.map

package/dist/services/agent-guide/adapters/generic-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-mcp.js","names":["lines: string[]"],"sources":["../../../../src/services/agent-guide/adapters/generic-mcp.ts"],"sourcesContent":["/**\n * Generic MCP Agent Adapter\n *\n * Formats implementation plans and prompts for any MCP-compatible agent.\n * Uses standard MCP resource/prompt/tool patterns.\n */\n\nimport type { AnyOperationSpec } from '@contractspec/lib.contracts';\nimport type {\n  AgentPrompt,\n  ImplementationPlan,\n} from '@contractspec/lib.contracts/llm';\nimport { AGENT_SYSTEM_PROMPTS } from '@contractspec/lib.contracts/llm';\nimport type { AgentAdapter } from '../types';\n\n/**\n * Generic MCP adapter implementation.\n * Works with any MCP-compatible agent (Cline, Aider, etc.).\n */\nexport class GenericMCPAdapter implements AgentAdapter {\n  agentType = 'generic-mcp' as const;\n\n  /**\n   * Format an implementation plan for generic MCP agents.\n   * Uses a standard markdown format that works across different agents.\n   */\n  formatPlan(plan: ImplementationPlan): AgentPrompt {\n    const lines: string[] = [];\n\n    // Standard header\n    lines.push(\n      `# Implementation Task: ${plan.target.key}.v${plan.target.version}`\n    );\n    lines.push('');\n\n    // Task description\n    lines.push('## Task');\n    lines.push('');\n    lines.push(\n      `Implement the ${plan.target.type} \\`${plan.target.key}\\` version ${plan.target.version}.`\n    );\n    lines.push('');\n\n    // Context\n    lines.push('## Context');\n    lines.push('');\n    lines.push(`**Goal:** ${plan.context.goal}`);\n    lines.push('');\n    lines.push(`**Description:** ${plan.context.description}`);\n    lines.push('');\n    if (plan.context.background) {\n      lines.push('**Background:**');\n      lines.push('');\n      lines.push(plan.context.background);\n      lines.push('');\n    }\n\n    // Specification\n    lines.push('## Specification');\n    lines.push('');\n    lines.push(plan.specMarkdown);\n    lines.push('');\n\n    // Files\n    if (plan.fileStructure.length > 0) {\n      lines.push('## Files');\n      lines.push('');\n      lines.push('| Path | Action | Purpose |');\n      lines.push('|------|--------|---------|');\n      for (const file of plan.fileStructure) {\n        lines.push(`| \\`${file.path}\\` | ${file.type} | ${file.purpose} |`);\n      }\n      lines.push('');\n    }\n\n    // Steps\n    lines.push('## Implementation Steps');\n    lines.push('');\n    for (const step of plan.steps) {\n      lines.push(`### Step ${step.order}: ${step.title}`);\n      lines.push('');\n      lines.push(step.description);\n      lines.push('');\n      if (step.acceptanceCriteria.length > 0) {\n        lines.push('**Acceptance Criteria:**');\n        lines.push('');\n        for (const criteria of step.acceptanceCriteria) {\n          lines.push(`- ${criteria}`);\n        }\n        lines.push('');\n      }\n    }\n\n    // Constraints\n    lines.push('## Constraints');\n    lines.push('');\n\n    if (plan.constraints.policy.length > 0) {\n      lines.push('**Policy:**');\n      for (const p of plan.constraints.policy) {\n        lines.push(`- ${p}`);\n      }\n      lines.push('');\n    }\n\n    if (plan.constraints.security.length > 0) {\n      lines.push('**Security:**');\n      for (const s of plan.constraints.security) {\n        lines.push(`- ${s}`);\n      }\n      lines.push('');\n    }\n\n    if (plan.constraints.pii.length > 0) {\n      lines.push('**PII Fields (handle with care):**');\n      for (const pii of plan.constraints.pii) {\n        lines.push(`- \\`${pii}\\``);\n      }\n      lines.push('');\n    }\n\n    // Verification\n    lines.push('## Verification');\n    lines.push('');\n    lines.push('After implementation, verify:');\n    lines.push('');\n    for (const check of plan.verificationChecklist) {\n      lines.push(`- [ ] ${check}`);\n    }\n    lines.push('');\n\n    return {\n      agent: 'generic-mcp',\n      systemPrompt: AGENT_SYSTEM_PROMPTS['generic-mcp'],\n      taskPrompt: lines.join('\\n'),\n    };\n  }\n\n  /**\n   * Format the plan as an MCP resource.\n   * Returns JSON that can be served as an MCP resource.\n   */\n  formatAsResource(plan: ImplementationPlan): {\n    uri: string;\n    mimeType: string;\n    data: string;\n  } {\n    return {\n      uri: `spec://${plan.target.key}/v${plan.target.version}/plan`,\n      mimeType: 'application/json',\n      data: JSON.stringify(\n        {\n          target: plan.target,\n          context: plan.context,\n          fileStructure: plan.fileStructure,\n          steps: plan.steps,\n          constraints: plan.constraints,\n          verificationChecklist: plan.verificationChecklist,\n        },\n        null,\n        2\n      ),\n    };\n  }\n\n  /**\n   * Format the plan as an MCP prompt message.\n   */\n  formatAsPromptMessage(plan: ImplementationPlan): {\n    role: 'user' | 'assistant';\n    content: { type: 'text'; text: string };\n  } {\n    const prompt = this.formatPlan(plan);\n    return {\n      role: 'user',\n      content: {\n        type: 'text',\n        text: prompt.taskPrompt,\n      },\n    };\n  }\n\n  /**\n   * Generate configuration (generic markdown for any agent).\n   */\n  generateConfig(spec: AnyOperationSpec): string {\n    const m = spec.meta;\n    const lines: string[] = [];\n\n    lines.push(`# ${m.key} v${m.version}`);\n    lines.push('');\n    lines.push(`**Type:** ${m.kind}`);\n    lines.push(`**Stability:** ${m.stability}`);\n    lines.push('');\n    lines.push('## Goal');\n    lines.push('');\n    lines.push(m.goal);\n    lines.push('');\n    lines.push('## Description');\n    lines.push('');\n    lines.push(m.description);\n    lines.push('');\n\n    return lines.join('\\n');\n  }\n\n  /**\n   * Parse agent output - generic implementation.\n   */\n  parseOutput(output: string): { code?: string; errors?: string[] } {\n    // Try to extract code from markdown code blocks\n    const codeBlockMatch = output.match(\n      /```(?:typescript|ts|tsx|javascript|js|python|go|rust)?\\n([\\s\\S]*?)\\n```/\n    );\n\n    if (codeBlockMatch?.[1]) {\n      return { code: codeBlockMatch[1] };\n    }\n\n    // Check for JSON output\n    try {\n      const parsed = JSON.parse(output);\n      if (typeof parsed.code === 'string') {\n        return { code: parsed.code };\n      }\n      if (typeof parsed.errors === 'object') {\n        return {\n          errors: Array.isArray(parsed.errors)\n            ? parsed.errors\n            : [String(parsed.errors)],\n        };\n      }\n    } catch {\n      // Not JSON, return as-is\n    }\n\n    return { code: output };\n  }\n}\n\n/** Singleton instance */\nexport const genericMCPAdapter = new GenericMCPAdapter();\n"],"mappings":"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"}

package/dist/services/agent-guide/adapters/index.d.ts

@@ -0,0 +1,23 @@
+import { AgentAdapter } from "../types.js";
+import { ClaudeCodeAdapter, claudeCodeAdapter } from "./claude-code.js";
+import { CursorCLIAdapter, cursorCLIAdapter } from "./cursor-cli.js";
+import { GenericMCPAdapter, genericMCPAdapter } from "./generic-mcp.js";
+import { AgentType } from "@contractspec/lib.contracts/llm";
+
+//#region src/services/agent-guide/adapters/index.d.ts
+
+/**
+ * Registry of all available agent adapters.
+ */
+declare const agentAdapters: Record<AgentType, AgentAdapter>;
+/**
+ * Get an adapter for a specific agent type.
+ */
+declare function getAgentAdapter(agent: AgentType): AgentAdapter;
+/**
+ * List all available agent types.
+ */
+declare function listAgentTypes(): AgentType[];
+//#endregion
+export { agentAdapters, getAgentAdapter, listAgentTypes };
+//# sourceMappingURL=index.d.ts.map

package/dist/services/agent-guide/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../../src/services/agent-guide/adapters/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AA6BA;AAWA;cApBa,eAAe,OAAO,WAAW;;;;iBAS9B,eAAA,QAAuB,YAAY;;;;iBAWnC,cAAA,CAAA,GAAkB"}

package/dist/services/agent-guide/adapters/index.js

@@ -0,0 +1,31 @@
+import { ClaudeCodeAdapter, claudeCodeAdapter } from "./claude-code.js";
+import { CursorCLIAdapter, cursorCLIAdapter } from "./cursor-cli.js";
+import { GenericMCPAdapter, genericMCPAdapter } from "./generic-mcp.js";
+
+//#region src/services/agent-guide/adapters/index.ts
+/**
+* Registry of all available agent adapters.
+*/
+const agentAdapters = {
+	"claude-code": claudeCodeAdapter,
+	"cursor-cli": cursorCLIAdapter,
+	"generic-mcp": genericMCPAdapter
+};
+/**
+* Get an adapter for a specific agent type.
+*/
+function getAgentAdapter(agent) {
+	const adapter = agentAdapters[agent];
+	if (!adapter) throw new Error(`Unknown agent type: ${agent}`);
+	return adapter;
+}
+/**
+* List all available agent types.
+*/
+function listAgentTypes() {
+	return Object.keys(agentAdapters);
+}
+
+//#endregion
+export { agentAdapters, getAgentAdapter, listAgentTypes };
+//# sourceMappingURL=index.js.map

package/dist/services/agent-guide/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["agentAdapters: Record<AgentType, AgentAdapter>"],"sources":["../../../../src/services/agent-guide/adapters/index.ts"],"sourcesContent":["/**\n * Agent Adapters\n *\n * Exports all agent-specific adapters for formatting implementation\n * plans and prompts.\n */\n\nexport { ClaudeCodeAdapter, claudeCodeAdapter } from './claude-code';\nexport { CursorCLIAdapter, cursorCLIAdapter } from './cursor-cli';\nexport { GenericMCPAdapter, genericMCPAdapter } from './generic-mcp';\n\nimport type { AgentType } from '@contractspec/lib.contracts/llm';\nimport type { AgentAdapter } from '../types';\nimport { claudeCodeAdapter } from './claude-code';\nimport { cursorCLIAdapter } from './cursor-cli';\nimport { genericMCPAdapter } from './generic-mcp';\n\n/**\n * Registry of all available agent adapters.\n */\nexport const agentAdapters: Record<AgentType, AgentAdapter> = {\n  'claude-code': claudeCodeAdapter,\n  'cursor-cli': cursorCLIAdapter,\n  'generic-mcp': genericMCPAdapter,\n};\n\n/**\n * Get an adapter for a specific agent type.\n */\nexport function getAgentAdapter(agent: AgentType): AgentAdapter {\n  const adapter = agentAdapters[agent];\n  if (!adapter) {\n    throw new Error(`Unknown agent type: ${agent}`);\n  }\n  return adapter;\n}\n\n/**\n * List all available agent types.\n */\nexport function listAgentTypes(): AgentType[] {\n  return Object.keys(agentAdapters) as AgentType[];\n}\n"],"mappings":";;;;;;;;AAoBA,MAAaA,gBAAiD;CAC5D,eAAe;CACf,cAAc;CACd,eAAe;CAChB;;;;AAKD,SAAgB,gBAAgB,OAAgC;CAC9D,MAAM,UAAU,cAAc;AAC9B,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,uBAAuB,QAAQ;AAEjD,QAAO;;;;;AAMT,SAAgB,iBAA8B;AAC5C,QAAO,OAAO,KAAK,cAAc"}

package/dist/services/agent-guide/agent-guide-service.d.ts

@@ -0,0 +1,56 @@
+import { AgentGuideConfig, GuideOptions, GuideResult } from "./types.js";
+import { AnyOperationSpec, OperationSpecRegistry, PresentationRegistry } from "@contractspec/lib.contracts";
+import { AgentType } from "@contractspec/lib.contracts/llm";
+import { FeatureModuleSpec } from "@contractspec/lib.contracts/features";
+
+//#region src/services/agent-guide/agent-guide-service.d.ts
+
+/**
+ * Agent Guide Service
+ *
+ * Main service for generating implementation guidance for AI coding agents.
+ */
+declare class AgentGuideService {
+  private config;
+  constructor(config?: Partial<AgentGuideConfig>);
+  /**
+   * Generate an implementation guide for a spec.
+   */
+  generateGuide(spec: AnyOperationSpec, options?: GuideOptions): GuideResult;
+  /**
+   * Generate a guide for a feature (includes all related specs).
+   */
+  generateFeatureGuide(feature: FeatureModuleSpec, deps: {
+    specs?: OperationSpecRegistry;
+    presentations?: PresentationRegistry;
+  }, options?: GuideOptions): GuideResult;
+  /**
+   * Generate agent-specific configuration (e.g., cursor rules).
+   */
+  generateAgentConfig(spec: AnyOperationSpec, agent?: AgentType): string | undefined;
+  /**
+   * Export a spec in a specific format for an agent.
+   */
+  exportForAgent(spec: AnyOperationSpec, _agent: AgentType, taskType?: 'implement' | 'test' | 'refactor' | 'review', existingCode?: string): string;
+  /**
+   * List available agent types.
+   */
+  listAgentTypes(): AgentType[];
+  /**
+   * Get the default agent type.
+   */
+  getDefaultAgent(): AgentType;
+  /**
+   * Update configuration.
+   */
+  configure(config: Partial<AgentGuideConfig>): void;
+}
+/**
+ * Create a new AgentGuideService instance.
+ */
+declare function createAgentGuideService(config?: Partial<AgentGuideConfig>): AgentGuideService;
+/** Default singleton instance */
+declare const agentGuideService: AgentGuideService;
+//#endregion
+export { AgentGuideService, agentGuideService, createAgentGuideService };
+//# sourceMappingURL=agent-guide-service.d.ts.map

package/dist/services/agent-guide/agent-guide-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide-service.d.ts","names":[],"sources":["../../../src/services/agent-guide/agent-guide-service.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAiFa,cA7CA,iBAAA,CA6CA;EACR,QAAA,MAAA;EAoFK,WAAA,CAAA,MAAA,CAAA,EA/HY,OA+HZ,CA/HoB,gBA+HpB,CAAA;EACE;;;EAqBQ,aAAA,CAAA,IAAA,EA7IV,gBA6IU,EAAA,OAAA,CAAA,EA5IP,YA4IO,CAAA,EA3If,WA2Ie;EAOC;;;EAOM,oBAAA,CAAA,OAAA,EA9Hd,iBA8Hc,EAAA,IAAA,EAAA;IAQX,KAAA,CAAA,EApIF,qBAoIyB;IACpB,aAAA,CAAA,EApIG,oBAoIH;EAAR,CAAA,EAAA,OAAA,CAAA,EAlIE,YAkIF,CAAA,EAjIN,WAiIM;EACR;;AAKH;4BAnDU,0BACE;;;;uBAUF,0BACE;;;;oBAUQ;;;;qBAOC;;;;oBAOD,QAAQ;;;;;iBAQZ,uBAAA,UACL,QAAQ,oBAChB;;cAKU,mBAAiB"}

package/dist/services/agent-guide/agent-guide-service.js

@@ -0,0 +1,147 @@
+import { getAgentAdapter, listAgentTypes } from "./adapters/index.js";
+import { featureToMarkdown, generateImplementationPlan, operationSpecToAgentPrompt, operationSpecToFullMarkdown } from "@contractspec/lib.contracts/llm";
+
+//#region src/services/agent-guide/agent-guide-service.ts
+const DEFAULT_CONFIG = {
+	defaultAgent: "generic-mcp",
+	verbose: false
+};
+/**
+* Agent Guide Service
+*
+* Main service for generating implementation guidance for AI coding agents.
+*/
+var AgentGuideService = class {
+	config;
+	constructor(config = {}) {
+		this.config = {
+			...DEFAULT_CONFIG,
+			...config
+		};
+	}
+	/**
+	* Generate an implementation guide for a spec.
+	*/
+	generateGuide(spec, options = {}) {
+		const adapter = getAgentAdapter(options.agent ?? this.config.defaultAgent);
+		const plan = generateImplementationPlan(spec, {
+			projectRoot: this.config.projectRoot,
+			existingFiles: options.targetPath ? [options.targetPath] : void 0
+		});
+		return {
+			plan,
+			prompt: adapter.formatPlan(plan),
+			markdown: operationSpecToFullMarkdown(spec)
+		};
+	}
+	/**
+	* Generate a guide for a feature (includes all related specs).
+	*/
+	generateFeatureGuide(feature, deps, options = {}) {
+		const adapter = getAgentAdapter(options.agent ?? this.config.defaultAgent);
+		const firstOp = feature.operations?.[0];
+		const spec = firstOp ? deps.specs?.getSpec(firstOp.key, firstOp.version) : void 0;
+		let plan;
+		if (spec) {
+			plan = generateImplementationPlan(spec, { projectRoot: this.config.projectRoot });
+			plan.target = {
+				type: "feature",
+				key: feature.meta.key,
+				version: 1
+			};
+			plan.context.goal = feature.meta.description ?? plan.context.goal;
+		} else plan = {
+			target: {
+				type: "feature",
+				key: feature.meta.key,
+				version: 1
+			},
+			context: {
+				goal: feature.meta.description ?? `Implement feature ${feature.meta.key}`,
+				description: feature.meta.title ?? feature.meta.key,
+				background: ""
+			},
+			specMarkdown: featureToMarkdown(feature, deps),
+			fileStructure: [],
+			steps: [{
+				order: 1,
+				title: "Implement Feature",
+				description: `Implement the ${feature.meta.key} feature`,
+				acceptanceCriteria: []
+			}],
+			constraints: {
+				policy: [],
+				security: [],
+				pii: []
+			},
+			verificationChecklist: []
+		};
+		plan.specMarkdown = featureToMarkdown(feature, deps, {
+			format: "full",
+			includeRelatedSpecs: true,
+			includeRelatedEvents: true,
+			includeRelatedPresentations: true
+		});
+		if (feature.operations?.length) plan.steps = feature.operations.map((op, idx) => ({
+			order: idx + 1,
+			title: `Implement ${op.key}`,
+			description: `Implement operation ${op.key}.v${op.version}`,
+			acceptanceCriteria: [`Operation ${op.key} works as specified`]
+		}));
+		const prompt = adapter.formatPlan(plan);
+		const markdown = featureToMarkdown(feature, deps);
+		return {
+			plan,
+			prompt,
+			markdown
+		};
+	}
+	/**
+	* Generate agent-specific configuration (e.g., cursor rules).
+	*/
+	generateAgentConfig(spec, agent) {
+		return getAgentAdapter(agent ?? this.config.defaultAgent).generateConfig?.(spec);
+	}
+	/**
+	* Export a spec in a specific format for an agent.
+	*/
+	exportForAgent(spec, _agent, taskType = "implement", existingCode) {
+		return operationSpecToAgentPrompt(spec, {
+			taskType,
+			existingCode
+		});
+	}
+	/**
+	* List available agent types.
+	*/
+	listAgentTypes() {
+		return listAgentTypes();
+	}
+	/**
+	* Get the default agent type.
+	*/
+	getDefaultAgent() {
+		return this.config.defaultAgent;
+	}
+	/**
+	* Update configuration.
+	*/
+	configure(config) {
+		this.config = {
+			...this.config,
+			...config
+		};
+	}
+};
+/**
+* Create a new AgentGuideService instance.
+*/
+function createAgentGuideService(config) {
+	return new AgentGuideService(config);
+}
+/** Default singleton instance */
+const agentGuideService = new AgentGuideService();
+
+//#endregion
+export { AgentGuideService, agentGuideService, createAgentGuideService };
+//# sourceMappingURL=agent-guide-service.js.map

package/dist/services/agent-guide/agent-guide-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide-service.js","names":["DEFAULT_CONFIG: AgentGuideConfig","plan: ImplementationPlan"],"sources":["../../../src/services/agent-guide/agent-guide-service.ts"],"sourcesContent":["/**\n * Agent Guide Service\n *\n * Generates implementation plans and prompts for AI coding agents.\n * Bridges ContractSpec specifications with agent-specific formats.\n */\n\nimport type {\n  AnyOperationSpec,\n  OperationSpecRegistry,\n  PresentationRegistry,\n} from '@contractspec/lib.contracts';\nimport type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';\nimport type {\n  AgentType,\n  ImplementationPlan,\n} from '@contractspec/lib.contracts/llm';\nimport {\n  featureToMarkdown,\n  generateImplementationPlan,\n  operationSpecToAgentPrompt,\n  operationSpecToFullMarkdown,\n} from '@contractspec/lib.contracts/llm';\nimport { getAgentAdapter, listAgentTypes } from './adapters';\nimport type { AgentGuideConfig, GuideOptions, GuideResult } from './types';\n\nconst DEFAULT_CONFIG: AgentGuideConfig = {\n  defaultAgent: 'generic-mcp',\n  verbose: false,\n};\n\n/**\n * Agent Guide Service\n *\n * Main service for generating implementation guidance for AI coding agents.\n */\nexport class AgentGuideService {\n  private config: AgentGuideConfig;\n\n  constructor(config: Partial<AgentGuideConfig> = {}) {\n    this.config = { ...DEFAULT_CONFIG, ...config };\n  }\n\n  /**\n   * Generate an implementation guide for a spec.\n   */\n  generateGuide(\n    spec: AnyOperationSpec,\n    options: GuideOptions = {}\n  ): GuideResult {\n    const agent = options.agent ?? this.config.defaultAgent;\n    const adapter = getAgentAdapter(agent);\n\n    // Generate the implementation plan\n    const plan = generateImplementationPlan(spec, {\n      projectRoot: this.config.projectRoot,\n      existingFiles: options.targetPath ? [options.targetPath] : undefined,\n    });\n\n    // Format for the target agent\n    const prompt = adapter.formatPlan(plan);\n\n    // Generate raw markdown for clipboard/export\n    const markdown = operationSpecToFullMarkdown(spec);\n\n    return {\n      plan,\n      prompt,\n      markdown,\n    };\n  }\n\n  /**\n   * Generate a guide for a feature (includes all related specs).\n   */\n  generateFeatureGuide(\n    feature: FeatureModuleSpec,\n    deps: {\n      specs?: OperationSpecRegistry;\n      presentations?: PresentationRegistry;\n    },\n    options: GuideOptions = {}\n  ): GuideResult {\n    const agent = options.agent ?? this.config.defaultAgent;\n    const adapter = getAgentAdapter(agent);\n\n    // Create a composite plan for the feature\n    const firstOp = feature.operations?.[0];\n    const spec = firstOp\n      ? deps.specs?.getSpec(firstOp.key, firstOp.version)\n      : undefined;\n\n    // Generate base plan from first spec or create feature-level plan\n    let plan: ImplementationPlan;\n    if (spec) {\n      plan = generateImplementationPlan(spec, {\n        projectRoot: this.config.projectRoot,\n      });\n      // Override target to indicate it's a feature\n      plan.target = {\n        type: 'feature',\n        key: feature.meta.key,\n        version: 1,\n      };\n      plan.context.goal = feature.meta.description ?? plan.context.goal;\n    } else {\n      // Create a minimal plan for features without specs\n      plan = {\n        target: {\n          type: 'feature',\n          key: feature.meta.key,\n          version: 1,\n        },\n        context: {\n          goal:\n            feature.meta.description ?? `Implement feature ${feature.meta.key}`,\n          description: feature.meta.title ?? feature.meta.key,\n          background: '',\n        },\n        specMarkdown: featureToMarkdown(feature, deps),\n        fileStructure: [],\n        steps: [\n          {\n            order: 1,\n            title: 'Implement Feature',\n            description: `Implement the ${feature.meta.key} feature`,\n            acceptanceCriteria: [],\n          },\n        ],\n        constraints: { policy: [], security: [], pii: [] },\n        verificationChecklist: [],\n      };\n    }\n\n    // Enhance spec markdown with full feature context\n    plan.specMarkdown = featureToMarkdown(feature, deps, {\n      format: 'full',\n      includeRelatedSpecs: true,\n      includeRelatedEvents: true,\n      includeRelatedPresentations: true,\n    });\n\n    // Add steps for each operation\n    if (feature.operations?.length) {\n      plan.steps = feature.operations.map((op, idx) => ({\n        order: idx + 1,\n        title: `Implement ${op.key}`,\n        description: `Implement operation ${op.key}.v${op.version}`,\n        acceptanceCriteria: [`Operation ${op.key} works as specified`],\n      }));\n    }\n\n    const prompt = adapter.formatPlan(plan);\n    const markdown = featureToMarkdown(feature, deps);\n\n    return {\n      plan,\n      prompt,\n      markdown,\n    };\n  }\n\n  /**\n   * Generate agent-specific configuration (e.g., cursor rules).\n   */\n  generateAgentConfig(\n    spec: AnyOperationSpec,\n    agent?: AgentType\n  ): string | undefined {\n    const adapter = getAgentAdapter(agent ?? this.config.defaultAgent);\n    return adapter.generateConfig?.(spec);\n  }\n\n  /**\n   * Export a spec in a specific format for an agent.\n   */\n  exportForAgent(\n    spec: AnyOperationSpec,\n    _agent: AgentType,\n    taskType: 'implement' | 'test' | 'refactor' | 'review' = 'implement',\n    existingCode?: string\n  ): string {\n    return operationSpecToAgentPrompt(spec, { taskType, existingCode });\n  }\n\n  /**\n   * List available agent types.\n   */\n  listAgentTypes(): AgentType[] {\n    return listAgentTypes();\n  }\n\n  /**\n   * Get the default agent type.\n   */\n  getDefaultAgent(): AgentType {\n    return this.config.defaultAgent;\n  }\n\n  /**\n   * Update configuration.\n   */\n  configure(config: Partial<AgentGuideConfig>): void {\n    this.config = { ...this.config, ...config };\n  }\n}\n\n/**\n * Create a new AgentGuideService instance.\n */\nexport function createAgentGuideService(\n  config?: Partial<AgentGuideConfig>\n): AgentGuideService {\n  return new AgentGuideService(config);\n}\n\n/** Default singleton instance */\nexport const agentGuideService = new AgentGuideService();\n"],"mappings":";;;;AA0BA,MAAMA,iBAAmC;CACvC,cAAc;CACd,SAAS;CACV;;;;;;AAOD,IAAa,oBAAb,MAA+B;CAC7B,AAAQ;CAER,YAAY,SAAoC,EAAE,EAAE;AAClD,OAAK,SAAS;GAAE,GAAG;GAAgB,GAAG;GAAQ;;;;;CAMhD,cACE,MACA,UAAwB,EAAE,EACb;EAEb,MAAM,UAAU,gBADF,QAAQ,SAAS,KAAK,OAAO,aACL;EAGtC,MAAM,OAAO,2BAA2B,MAAM;GAC5C,aAAa,KAAK,OAAO;GACzB,eAAe,QAAQ,aAAa,CAAC,QAAQ,WAAW,GAAG;GAC5D,CAAC;AAQF,SAAO;GACL;GACA,QAPa,QAAQ,WAAW,KAAK;GAQrC,UALe,4BAA4B,KAAK;GAMjD;;;;;CAMH,qBACE,SACA,MAIA,UAAwB,EAAE,EACb;EAEb,MAAM,UAAU,gBADF,QAAQ,SAAS,KAAK,OAAO,aACL;EAGtC,MAAM,UAAU,QAAQ,aAAa;EACrC,MAAM,OAAO,UACT,KAAK,OAAO,QAAQ,QAAQ,KAAK,QAAQ,QAAQ,GACjD;EAGJ,IAAIC;AACJ,MAAI,MAAM;AACR,UAAO,2BAA2B,MAAM,EACtC,aAAa,KAAK,OAAO,aAC1B,CAAC;AAEF,QAAK,SAAS;IACZ,MAAM;IACN,KAAK,QAAQ,KAAK;IAClB,SAAS;IACV;AACD,QAAK,QAAQ,OAAO,QAAQ,KAAK,eAAe,KAAK,QAAQ;QAG7D,QAAO;GACL,QAAQ;IACN,MAAM;IACN,KAAK,QAAQ,KAAK;IAClB,SAAS;IACV;GACD,SAAS;IACP,MACE,QAAQ,KAAK,eAAe,qBAAqB,QAAQ,KAAK;IAChE,aAAa,QAAQ,KAAK,SAAS,QAAQ,KAAK;IAChD,YAAY;IACb;GACD,cAAc,kBAAkB,SAAS,KAAK;GAC9C,eAAe,EAAE;GACjB,OAAO,CACL;IACE,OAAO;IACP,OAAO;IACP,aAAa,iBAAiB,QAAQ,KAAK,IAAI;IAC/C,oBAAoB,EAAE;IACvB,CACF;GACD,aAAa;IAAE,QAAQ,EAAE;IAAE,UAAU,EAAE;IAAE,KAAK,EAAE;IAAE;GAClD,uBAAuB,EAAE;GAC1B;AAIH,OAAK,eAAe,kBAAkB,SAAS,MAAM;GACnD,QAAQ;GACR,qBAAqB;GACrB,sBAAsB;GACtB,6BAA6B;GAC9B,CAAC;AAGF,MAAI,QAAQ,YAAY,OACtB,MAAK,QAAQ,QAAQ,WAAW,KAAK,IAAI,SAAS;GAChD,OAAO,MAAM;GACb,OAAO,aAAa,GAAG;GACvB,aAAa,uBAAuB,GAAG,IAAI,IAAI,GAAG;GAClD,oBAAoB,CAAC,aAAa,GAAG,IAAI,qBAAqB;GAC/D,EAAE;EAGL,MAAM,SAAS,QAAQ,WAAW,KAAK;EACvC,MAAM,WAAW,kBAAkB,SAAS,KAAK;AAEjD,SAAO;GACL;GACA;GACA;GACD;;;;;CAMH,oBACE,MACA,OACoB;AAEpB,SADgB,gBAAgB,SAAS,KAAK,OAAO,aAAa,CACnD,iBAAiB,KAAK;;;;;CAMvC,eACE,MACA,QACA,WAAyD,aACzD,cACQ;AACR,SAAO,2BAA2B,MAAM;GAAE;GAAU;GAAc,CAAC;;;;;CAMrE,iBAA8B;AAC5B,SAAO,gBAAgB;;;;;CAMzB,kBAA6B;AAC3B,SAAO,KAAK,OAAO;;;;;CAMrB,UAAU,QAAyC;AACjD,OAAK,SAAS;GAAE,GAAG,KAAK;GAAQ,GAAG;GAAQ;;;;;;AAO/C,SAAgB,wBACd,QACmB;AACnB,QAAO,IAAI,kBAAkB,OAAO;;;AAItC,MAAa,oBAAoB,IAAI,mBAAmB"}

package/dist/services/agent-guide/index.d.ts

@@ -0,0 +1,6 @@
+import { AgentAdapter, AgentGuideConfig, FormatOptions, GuideOptions, GuideResult } from "./types.js";
+import { AgentGuideService, agentGuideService, createAgentGuideService } from "./agent-guide-service.js";
+import { ClaudeCodeAdapter, claudeCodeAdapter } from "./adapters/claude-code.js";
+import { CursorCLIAdapter, cursorCLIAdapter } from "./adapters/cursor-cli.js";
+import { GenericMCPAdapter, genericMCPAdapter } from "./adapters/generic-mcp.js";
+import { agentAdapters, getAgentAdapter, listAgentTypes } from "./adapters/index.js";

package/dist/services/agent-guide/index.js

@@ -0,0 +1,5 @@
+import { ClaudeCodeAdapter, claudeCodeAdapter } from "./adapters/claude-code.js";
+import { CursorCLIAdapter, cursorCLIAdapter } from "./adapters/cursor-cli.js";
+import { GenericMCPAdapter, genericMCPAdapter } from "./adapters/generic-mcp.js";
+import { agentAdapters, getAgentAdapter, listAgentTypes } from "./adapters/index.js";
+import { AgentGuideService, agentGuideService, createAgentGuideService } from "./agent-guide-service.js";

package/dist/services/agent-guide/types.d.ts

@@ -0,0 +1,58 @@
+import { AnyOperationSpec } from "@contractspec/lib.contracts";
+import { AgentPrompt, AgentType, ImplementationPlan } from "@contractspec/lib.contracts/llm";
+
+//#region src/services/agent-guide/types.d.ts
+
+/** Configuration for the agent guide service */
+interface AgentGuideConfig {
+  /** Default agent to use if not specified */
+  defaultAgent: AgentType;
+  /** Project root path */
+  projectRoot?: string;
+  /** Enable verbose logging */
+  verbose?: boolean;
+}
+/** Options for generating an implementation guide */
+interface GuideOptions {
+  /** Target agent type */
+  agent?: AgentType;
+  /** Existing code to consider */
+  existingCode?: string;
+  /** Target file path for implementation */
+  targetPath?: string;
+  /** Include related specs */
+  includeRelated?: boolean;
+}
+/** Options for formatting output */
+interface FormatOptions {
+  /** Output format */
+  format: 'markdown' | 'json' | 'cursor-rules';
+  /** Include system prompt */
+  includeSystemPrompt?: boolean;
+}
+/** Result of generating a guide */
+interface GuideResult {
+  /** The generated plan */
+  plan: ImplementationPlan;
+  /** Formatted prompt for the target agent */
+  prompt: AgentPrompt;
+  /** Raw markdown for clipboard/export */
+  markdown: string;
+}
+/** Adapter interface for specific agent types */
+interface AgentAdapter {
+  /** Agent type this adapter handles */
+  agentType: AgentType;
+  /** Format a plan for this agent */
+  formatPlan(plan: ImplementationPlan): AgentPrompt;
+  /** Generate agent-specific configuration (e.g., cursor rules) */
+  generateConfig?(spec: AnyOperationSpec): string;
+  /** Parse agent output to extract code */
+  parseOutput?(output: string): {
+    code?: string;
+    errors?: string[];
+  };
+}
+//#endregion
+export { AgentAdapter, AgentGuideConfig, FormatOptions, GuideOptions, GuideResult };
+//# sourceMappingURL=types.d.ts.map

package/dist/services/agent-guide/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/services/agent-guide/types.ts"],"sourcesContent":[],"mappings":";;;;;AAsBA;AAYiB,UAtBA,gBAAA,CAsBa;EAQb;EAUA,YAAA,EAtCD,SAsCa;EAEhB;EAGM,WAAA,CAAA,EAAA,MAAA;EAAqB;EAGhB,OAAA,CAAA,EAAA,OAAA;;;UAtCP,YAAA;;UAEP;;;;;;;;;UAUO,aAAA;;;;;;;UAQA,WAAA;;QAET;;UAEE;;;;;UAMO,YAAA;;aAEJ;;mBAGM,qBAAqB;;wBAGhB"}