@specverse/engines 5.1.0 → 5.2.0

package/libs/instance-factories/cli/templates/commander/command-generator.ts

@@ -1170,6 +1170,190 @@ import type { ParserEngine } from '@specverse/types';`,
         await manager.processJob(jobId);
         console.log('Job processed successfully');`
   },
+  // === skill subcommands ===
+  'skill.install': {
+    imports: `import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';`,
+    handler: `const requireResolve = createRequire(import.meta.url);
+
+        // 1. Resolve target directory.
+        let targetDir: string;
+        if (options.target) {
+          targetDir = resolve(options.target);
+        } else if (options.global) {
+          targetDir = join(homedir(), '.claude', 'skills', 'specverse');
+        } else {
+          // Default: project-local (current working directory).
+          targetDir = join(process.env.SPECVERSE_USER_CWD || process.cwd(), '.claude', 'skills', 'specverse');
+        }
+        mkdirSync(targetDir, { recursive: true });
+        mkdirSync(join(targetDir, 'reference'), { recursive: true });
+        mkdirSync(join(targetDir, 'workflows'), { recursive: true });
+
+        // 2. Helpers to resolve into installed packages.
+        //    For @specverse/self specifically, we fall back to walking up from
+        //    import.meta.url — handy when running the in-repo bootstrap CLI where
+        //    self can't resolve its own package.json via require.
+        const selfRoot = (() => {
+          try {
+            const pkgJson = requireResolve.resolve('@specverse/self/package.json');
+            return dirname(pkgJson);
+          } catch {
+            let dir = dirname(fileURLToPath(import.meta.url));
+            for (let i = 0; i < 8; i++) {
+              const candidate = join(dir, 'package.json');
+              if (existsSync(candidate)) {
+                try {
+                  const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+                  if (pkg?.name === '@specverse/self') return dir;
+                } catch { /* continue */ }
+              }
+              const parent = dirname(dir);
+              if (parent === dir) break;
+              dir = parent;
+            }
+            return null;
+          }
+        })();
+
+        const resolvePkg = (pkg: string, rel: string): string | null => {
+          if (pkg === '@specverse/self') {
+            return selfRoot ? join(selfRoot, rel) : null;
+          }
+          try {
+            const pkgJson = requireResolve.resolve(pkg + '/package.json');
+            return join(dirname(pkgJson), rel);
+          } catch { return null; }
+        };
+
+        // 3. Copy SKILL.md from @specverse/self.
+        const skillMdSrc = resolvePkg('@specverse/self', 'skills/specverse/SKILL.md');
+        if (!skillMdSrc || !existsSync(skillMdSrc)) {
+          console.error('Cannot locate SKILL.md in @specverse/self — install failed.');
+          process.exit(1);
+        }
+        writeFileSync(join(targetDir, 'SKILL.md'), readFileSync(skillMdSrc, 'utf8'));
+
+        // 4. Copy reference files (schema + ai-guidance + minimal-example + guide).
+        const refCopies: [string, string, string][] = [
+          ['@specverse/entities', 'schema/SPECVERSE-SCHEMA.json', 'reference/schema.json'],
+          ['@specverse/entities', 'schema/SPECVERSE-SCHEMA-AI.yaml', 'reference/ai-guidance.yaml'],
+          ['@specverse/entities', 'schema/MINIMAL-SYNTAX-REFERENCE.specly', 'reference/minimal-example.specly'],
+          ['@specverse/self', 'docs/guides/SPECVERSE-COMPLETE-GUIDE.md', 'reference/guide.md'],
+        ];
+        let refCopied = 0;
+        for (const [pkg, rel, dest] of refCopies) {
+          const src = resolvePkg(pkg, rel);
+          if (src && existsSync(src)) {
+            writeFileSync(join(targetDir, dest), readFileSync(src, 'utf8'));
+            refCopied++;
+          } else {
+            console.warn('  (skipped ' + dest + ' — ' + pkg + '/' + rel + ' not found)');
+          }
+        }
+
+        // 5. Build cli-reference.md from the running CLI's own \`--help\`.
+        // Minimal content — a pointer to the spv help and a static summary.
+        const cliRef = [
+          '# SpecVerse CLI Reference',
+          '',
+          'Run \`spv <command> --help\` for flag details on any command. Common subcommands:',
+          '',
+          '| Command | Purpose |',
+          '|---|---|',
+          '| \`spv init <name>\` | Scaffold a new project (templates: default / full-stack / backend-only / frontend-only) |',
+          '| \`spv validate <spec>\` | Parse + schema-validate a .specly file |',
+          '| \`spv validate-bundle <dir>\` | Validate an entity bundle (for engine extenders) |',
+          '| \`spv infer <spec>\` | Expand a minimal spec to full architecture (controllers / services / events / views) |',
+          '| \`spv realize all <spec>\` | Generate production code from inferred spec + manifest |',
+          '| \`spv gen diagrams <spec>\` | Emit mermaid diagrams (ER, lifecycle, architecture) |',
+          '| \`spv ai template <op> <spec>\` | Dump a canonical workflow prompt filled in for a spec |',
+          '| \`spv smoke\` | Verify the \`spv\` install end-to-end |',
+          '| \`spv skill install [--global\\\\|--project]\` | Reinstall / refresh this skill |',
+          '',
+          'For CI invocations, see the \`SPECVERSE-TOOLING.md\` guide in \`@specverse/self/docs/guides/\`.',
+          '',
+        ].join('\\n');
+        writeFileSync(join(targetDir, 'reference', 'cli-reference.md'), cliRef);
+
+        // 6. Emit one workflow markdown per prompt YAML in @specverse/engines/assets/prompts/core/standard/default.
+        const yamlLib = await import('js-yaml').catch(() => null) as any;
+        const workflowsDir = resolvePkg('@specverse/engines', 'assets/prompts/core/standard/default');
+        let workflowCount = 0;
+        if (yamlLib && workflowsDir && existsSync(workflowsDir)) {
+          const entries = readdirSync(workflowsDir).filter((f: string) => f.endsWith('.prompt.yaml'));
+          for (const entry of entries) {
+            try {
+              const parsed = yamlLib.load(readFileSync(join(workflowsDir, entry), 'utf8')) as any;
+              if (!parsed?.name) continue;
+              const md = buildWorkflowMarkdown(parsed);
+              writeFileSync(join(targetDir, 'workflows', parsed.name + '.md'), md);
+              workflowCount++;
+            } catch (err: any) {
+              console.warn('  (skipped workflow ' + entry + ' — ' + err.message + ')');
+            }
+          }
+        } else {
+          console.warn('  (no workflows emitted — js-yaml or @specverse/engines prompts unavailable)');
+        }
+
+        // 7. Report.
+        console.log('Installed SpecVerse skill → ' + targetDir);
+        console.log('  SKILL.md + ' + refCopied + ' reference file(s) + ' + workflowCount + ' workflow(s)');
+        if (!options.global && !options.target) {
+          console.log('');
+          console.log('Tip: use --global to install to ~/.claude/skills/ for cross-project use.');
+        }
+
+        function buildWorkflowMarkdown(parsed: any): string {
+          const parts: string[] = [];
+          parts.push('# SpecVerse workflow: ' + parsed.name);
+          parts.push('');
+          if (parsed.description) {
+            parts.push('> ' + parsed.description);
+            parts.push('');
+          }
+          const vars = Array.isArray(parsed?.user?.variables) ? parsed.user.variables : [];
+          if (vars.length > 0) {
+            parts.push('## Inputs');
+            parts.push('');
+            parts.push('| Variable | Required | Description |');
+            parts.push('|---|---|---|');
+            for (const v of vars) {
+              const req = v.required === false ? 'no' : 'yes';
+              const desc = (v.description || '').replace(/\\|/g, '\\\\|');
+              parts.push('| \`' + v.name + '\` | ' + req + ' | ' + desc + ' |');
+            }
+            parts.push('');
+          }
+          if (parsed?.system?.role) {
+            parts.push('## Role');
+            parts.push('');
+            parts.push(String(parsed.system.role).trim());
+            parts.push('');
+          }
+          if (parsed?.system?.context) {
+            parts.push('## Instructions');
+            parts.push('');
+            parts.push(String(parsed.system.context).trim());
+            parts.push('');
+          }
+          if (parsed?.user?.template) {
+            parts.push('## Task template');
+            parts.push('');
+            parts.push('When invoking this workflow, fill the variables above into the template below:');
+            parts.push('');
+            parts.push('\`\`\`');
+            parts.push(String(parsed.user.template).trim());
+            parts.push('\`\`\`');
+            parts.push('');
+          }
+          return parts.join('\\n');
+        }`
+  },
 };
 
 function generateLeafCommand(

package/libs/instance-factories/tools/templates/mcp/mcp-server-generator.ts

@@ -12,8 +12,11 @@
  */
 
 import type { TemplateContext } from '@specverse/types';
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+
+const require = createRequire(import.meta.url);
 
 export default function generateMCPServer(context: TemplateContext): string {
   const { spec, outputDir } = context;
@@ -23,7 +26,14 @@ export default function generateMCPServer(context: TemplateContext): string {
   if (!existsSync(srcDir)) mkdirSync(srcDir, { recursive: true });
 
   const distribution = extractMCPDistribution(spec);
-  const version = distribution?.version || spec?.metadata?.version || spec?.version || '5.0.0';
+  // Prefer @specverse/self's real version over the spec's stale component
+  // version label. Falls back to the spec + default.
+  const version =
+    distribution?.version ||
+    resolveSelfVersion() ||
+    spec?.metadata?.version ||
+    spec?.version ||
+    '5.1.0';
   const description = distribution?.description
     || 'SpecVerse MCP server — exposes the specverse CLI as MCP tools and the live spec schema + docs as MCP resources.';
   const displayName = distribution?.displayName || 'SpecVerse MCP';
@@ -34,10 +44,26 @@ export default function generateMCPServer(context: TemplateContext): string {
   writeFileSync(join(mcpDir, 'tsconfig.json'), generateTsconfig());
   writeFileSync(join(srcDir, 'server.ts'), generateServer(displayName, version));
   writeFileSync(join(srcDir, 'cli-runner.ts'), generateCliRunner());
-  writeFileSync(join(srcDir, 'resources.ts'), generateResources());
+  writeFileSync(join(srcDir, 'resources.ts'), generateResources(cliCommands));
   writeFileSync(join(srcDir, 'tools.ts'), generateTools(cliCommands));
+  writeFileSync(join(srcDir, 'prompts.ts'), generatePrompts());
+
+  return `MCP server generated in: ${mcpDir}\n  ${cliCommands.length} tools, 5 resources, 6 prompts (derived from @specverse/engines/assets/prompts)`;
+}
 
-  return `MCP server generated in: ${mcpDir}\n  ${cliCommands.length} tools (one per CLI command), 2 resources (schema + docs)`;
+/**
+ * Read the running @specverse/self install's version from its package.json so
+ * the MCP server reports a real version instead of a stale component label.
+ * Returns null if @specverse/self isn't resolvable (e.g. during in-repo tests).
+ */
+function resolveSelfVersion(): string | null {
+  try {
+    const pkgPath = require.resolve('@specverse/self/package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version || null;
+  } catch {
+    return null;
+  }
 }
 
 // ─── spec extraction ───────────────────────────────────────────────────────
@@ -182,10 +208,13 @@ function generatePackageJson(version: string, description: string): string {
     },
     dependencies: {
       '@modelcontextprotocol/sdk': '^1.17.4',
-      '@specverse/entities': '^5.0.0',
-      '@specverse/self': '^5.0.0',
+      '@specverse/engines': '^5.2.0',
+      '@specverse/entities': '^5.1.0',
+      '@specverse/self': '^5.2.0',
+      'js-yaml': '^4.1.0',
     },
     devDependencies: {
+      '@types/js-yaml': '^4.0.9',
       '@types/node': '^20.19.11',
       typescript: '^5.9.2',
     },
@@ -222,13 +251,15 @@ function generateTsconfig(): string {
 }
 
 function generateServer(displayName: string, version: string): string {
+  const instructions = SERVER_INSTRUCTIONS;
   return `#!/usr/bin/env node
 /**
  * SpecVerse MCP Server — stdio transport.
  *
- * Wires the MCP protocol to the generated tool registry + live resources.
- * No handwritten business logic — everything is derived from the spec
- * (tools from CLI commands) or from @specverse/entities (schema + docs).
+ * Wires the MCP protocol to the generated tool registry + live resources
+ * + canonical workflow prompts. Everything is derived from the spec
+ * (tools from CLI commands, resources from @specverse/entities + @specverse/self,
+ * prompts from @specverse/engines/assets/prompts/core/standard/default).
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -237,13 +268,21 @@ import {
   CallToolRequestSchema,
   ListResourcesRequestSchema,
   ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { TOOLS, callTool } from './tools.js';
 import { RESOURCES, readResource } from './resources.js';
+import { PROMPTS, getPrompt } from './prompts.js';
+
+const INSTRUCTIONS = ${JSON.stringify(instructions)};
 
 const server = new Server(
   { name: ${JSON.stringify(displayName)}, version: ${JSON.stringify(version)} },
-  { capabilities: { tools: {}, resources: {} } },
+  {
+    capabilities: { tools: {}, resources: {}, prompts: {} },
+    instructions: INSTRUCTIONS,
+  },
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -272,11 +311,52 @@ server.setRequestHandler(ReadResourceRequestSchema, async (req: { params: { uri:
   return readResource(req.params.uri);
 });
 
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: PROMPTS.map(p => ({
+    name: p.name,
+    description: p.description,
+    arguments: p.arguments,
+  })),
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req: { params: { name: string; arguments?: Record<string, string> } }) => {
+  const { name, arguments: args } = req.params;
+  return getPrompt(name, args ?? {});
+});
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 `;
 }
 
+const SERVER_INSTRUCTIONS = [
+  'SpecVerse is a declarative specification language. You describe WHAT a system does in a .specly file, and the engines generate HOW — backend (Fastify/Prisma), frontend (React/Tailwind), CLI, tools, diagrams.',
+  '',
+  'Before using tools, read these resources to ground yourself in the language:',
+  '- specverse://guide — canonical user guide (spec language, CLI reference, convention patterns)',
+  '- specverse://ai-guidance — curated hints for generating valid specs',
+  '- specverse://minimal-example — one minimal .specly showing every feature in ~100 lines',
+  '- specverse://schema — the JSON Schema (draft 2020-12) for .specly validation',
+  '- specverse://cli-reference — every spv CLI subcommand with flags + arguments',
+  '',
+  'Common high-leverage workflows are exposed as MCP prompts (preferred entry point):',
+  '- create: natural-language requirements → minimal .specly',
+  '- analyse: existing codebase → .specly that captures what is implemented',
+  '- materialise: .specly → production code',
+  '- realize: generate deployment configs',
+  '- behavior: generate AI behavior function stubs',
+  '- app-demo: interactive spec creation/modification for the runtime interpreter',
+  '',
+  'Tools map 1:1 to the spv CLI. Key distinctions:',
+  '- validate: check a .specly file parses + matches the schema',
+  '- validate-manifest: check an implementation manifest resolves cleanly',
+  '- validate-bundle: check an entity bundle (schema + examples + tests + docs + behaviour facets)',
+  '- infer: expand a minimal .specly to full architecture (controllers / services / events / views)',
+  '- realize: turn inferred spec + manifest into generated code (Fastify / Prisma / React / CLI / tools)',
+  '- init: scaffold a new project from a template',
+].join('\n');
+
+
 function generateCliRunner(): string {
   return `/**
  * Thin specverse CLI runner.
@@ -378,12 +458,16 @@ export async function callTool(name: string, args: Record<string, any>) {
 `;
 }
 
-function generateResources(): string {
+function generateResources(tools: CLITool[]): string {
+  const cliReference = buildCliReferenceMarkdown(tools);
   return `/**
- * Resource registry — exposes the live SpecVerse schema + user guide as
- * MCP resources. Schema is read from @specverse/entities (composed fragment
- * aggregate); guide is read from @specverse/self (canonical home for all
- * user-facing guides).
+ * Resource registry — exposes the canonical SpecVerse reference material as
+ * MCP resources:
+ *   - schema           (JSON Schema draft 2020-12, from @specverse/entities)
+ *   - ai-guidance      (curated LLM hints, from @specverse/entities)
+ *   - minimal-example  (one .specly covering all features, from @specverse/entities)
+ *   - guide            (user guide, from @specverse/self)
+ *   - cli-reference    (derived from the spec at realize time, embedded below)
  */
 import { readFileSync } from 'fs';
 import { createRequire } from 'module';
@@ -409,6 +493,8 @@ function resolveSelfFile(relative: string): string {
   return join(dirname(pkg), relative);
 }
 
+const CLI_REFERENCE_MARKDOWN = ${JSON.stringify(cliReference)};
+
 export const RESOURCES: Resource[] = [
   {
     uri: 'specverse://schema',
@@ -420,6 +506,26 @@ export const RESOURCES: Resource[] = [
       mimeType: 'application/json',
     }),
   },
+  {
+    uri: 'specverse://ai-guidance',
+    name: 'SpecVerse AI Guidance Schema',
+    description: 'YAML schema annotated with examples and LLM guidance for generating valid specs. Read this before authoring or mutating .specly files.',
+    mimeType: 'application/x-yaml',
+    resolve: () => ({
+      text: readFileSync(resolveEntitiesFile('schema/SPECVERSE-SCHEMA-AI.yaml'), 'utf8'),
+      mimeType: 'application/x-yaml',
+    }),
+  },
+  {
+    uri: 'specverse://minimal-example',
+    name: 'SpecVerse Minimal Example',
+    description: 'One complete minimal .specly demonstrating every feature (~100 lines) — component, models, relationships, lifecycle, CURVED controller, service, view, event, manifest, deployment.',
+    mimeType: 'text/x-yaml',
+    resolve: () => ({
+      text: readFileSync(resolveEntitiesFile('schema/MINIMAL-SYNTAX-REFERENCE.specly'), 'utf8'),
+      mimeType: 'text/x-yaml',
+    }),
+  },
   {
     uri: 'specverse://guide',
     name: 'SpecVerse Complete Guide',
@@ -430,6 +536,16 @@ export const RESOURCES: Resource[] = [
       mimeType: 'text/markdown',
     }),
   },
+  {
+    uri: 'specverse://cli-reference',
+    name: 'SpecVerse CLI Reference',
+    description: 'Every spv CLI subcommand with its arguments, flags, and exit codes. Derived from the spec at realize time.',
+    mimeType: 'text/markdown',
+    resolve: () => ({
+      text: CLI_REFERENCE_MARKDOWN,
+      mimeType: 'text/markdown',
+    }),
+  },
 ];
 
 const BY_URI = new Map<string, Resource>(RESOURCES.map(r => [r.uri, r]));
@@ -446,3 +562,193 @@ export async function readResource(uri: string) {
 }
 `;
 }
+
+/**
+ * Build the cli-reference.md content from the parsed CLI tool list.
+ * Embedded as a string constant in the generated resources.ts so the MCP
+ * server doesn't need filesystem access for it at runtime.
+ */
+function buildCliReferenceMarkdown(tools: CLITool[]): string {
+  const lines: string[] = [];
+  lines.push('# SpecVerse CLI Reference');
+  lines.push('');
+  lines.push('Generated from the self-spec at realize time. Every entry here matches an MCP tool exposed by this server (same name, same input schema).');
+  lines.push('');
+  for (const tool of tools) {
+    const cliCmd = tool.cliArgs.join(' ');
+    lines.push(`## \`spv ${cliCmd}\``);
+    lines.push('');
+    lines.push(tool.description);
+    lines.push('');
+    const props = (tool.inputSchema as any)?.properties || {};
+    const required = new Set(((tool.inputSchema as any)?.required || []) as string[]);
+    const positional = new Set(tool.positional);
+    const argEntries = Object.entries(props) as [string, any][];
+    if (argEntries.length > 0) {
+      lines.push('| Name | Kind | Required | Type | Description |');
+      lines.push('|---|---|---|---|---|');
+      for (const [name, schema] of argEntries) {
+        const kind = positional.has(name) ? 'positional' : 'flag';
+        const req = required.has(name) ? 'yes' : 'no';
+        const type = (schema as any)?.type || 'string';
+        const desc = ((schema as any)?.description || '').replace(/\|/g, '\\|');
+        lines.push(`| \`${name}\` | ${kind} | ${req} | ${type} | ${desc} |`);
+      }
+      lines.push('');
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Emit prompts.ts — loads the canonical workflow prompts from
+ * @specverse/engines/assets/prompts/core/standard/default/ at module-init
+ * time. Each YAML prompt becomes one MCP prompt; the declared
+ * {{template variables}} surface as MCP prompt arguments the client fills.
+ * Schema paths ({{aiSchemaPath}}, {{referenceSchemaPath}},
+ * {{referenceExamplePath}}) are auto-filled with package-relative paths so
+ * the caller doesn't have to know where they live on disk.
+ */
+function generatePrompts(): string {
+  return `/**
+ * Prompt registry — reads the canonical workflow prompts from
+ * @specverse/engines/assets/prompts/core/standard/default/ at startup and
+ * serves them as MCP prompts. Each YAML file (create, analyse, materialise,
+ * realize, behavior, app-demo) becomes one invocable prompt.
+ */
+import { readdirSync, readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, join, basename } from 'path';
+import { load as yamlLoad } from 'js-yaml';
+
+const require = createRequire(import.meta.url);
+
+export interface PromptArgument {
+  name: string;
+  description?: string;
+  required: boolean;
+}
+
+export interface Prompt {
+  name: string;
+  description: string;
+  arguments: PromptArgument[];
+  source: any;  // parsed YAML — kept so getPrompt can re-render
+}
+
+function resolveEntitiesFile(relative: string): string {
+  const pkg = require.resolve('@specverse/entities/package.json');
+  return join(dirname(pkg), relative);
+}
+
+function resolveEnginesDir(relative: string): string {
+  const pkg = require.resolve('@specverse/engines/package.json');
+  return join(dirname(pkg), relative);
+}
+
+// Auto-filled template vars — paths into @specverse/entities/schema/
+const SCHEMA_VAR_PATHS: Record<string, string> = {
+  aiSchemaPath: resolveEntitiesFile('schema/SPECVERSE-SCHEMA-AI.yaml'),
+  referenceSchemaPath: resolveEntitiesFile('schema/MINIMAL-SYNTAX-REFERENCE.specly'),
+  referenceExamplePath: resolveEntitiesFile('schema/MINIMAL-SYNTAX-REFERENCE.specly'),
+};
+
+// User-facing vars the server does NOT auto-fill — surfaced as MCP prompt args.
+const USER_FACING = new Set<string>([
+  ...Object.keys(SCHEMA_VAR_PATHS),
+]);
+
+function loadPrompts(): Prompt[] {
+  const promptsDir = resolveEnginesDir('assets/prompts/core/standard/default');
+  const entries = readdirSync(promptsDir).filter(f => f.endsWith('.prompt.yaml'));
+  const prompts: Prompt[] = [];
+  for (const entry of entries) {
+    const full = join(promptsDir, entry);
+    try {
+      const parsed = yamlLoad(readFileSync(full, 'utf8')) as any;
+      if (!parsed?.name) continue;
+      const args = deriveArguments(parsed);
+      prompts.push({
+        name: parsed.name,
+        description: parsed.description || \`SpecVerse \${parsed.name} workflow\`,
+        arguments: args,
+        source: parsed,
+      });
+    } catch (err) {
+      // One bad prompt shouldn't kill the server; skip it.
+      console.error(\`[prompts] skipping \${basename(entry)}: \${(err as Error).message}\`);
+    }
+  }
+  return prompts;
+}
+
+/**
+ * Every SpecVerse prompt YAML declares user.variables[] in the canonical shape
+ * { name, type?, required?, description?, default? }. We surface the declared
+ * list verbatim, filtering out auto-filled schema-path vars.
+ */
+function deriveArguments(parsed: any): PromptArgument[] {
+  const declared = parsed?.user?.variables;
+  if (!Array.isArray(declared)) return [];
+  return declared
+    .filter((v: any) => v && typeof v === 'object' && typeof v.name === 'string')
+    .filter((v: any) => !USER_FACING.has(v.name))
+    .map((v: any) => ({
+      name: v.name,
+      description: v.description || inferVarDescription(v.name, parsed),
+      required: v.required !== false,
+    }));
+}
+
+function inferVarDescription(varName: string, parsed: any): string {
+  // Friendly defaults for the known common vars; fall back to a humanised
+  // version of the variable name.
+  const defaults: Record<string, string> = {
+    requirements: 'Natural-language requirements to extract a specification from',
+    scale: 'Project scale — personal, business, or enterprise',
+    preferredTech: 'Preferred technology stack hint (e.g. "nextjs", "nestjs", "fastify+prisma", "auto")',
+    implementationPath: 'Path to the existing codebase to reverse-engineer into a .specly',
+    specPath: 'Path to an existing .specly file',
+    manifestPath: 'Path to an implementation manifest (manifests/implementation.yaml)',
+    outputDir: 'Output directory for generated artifacts',
+    modelName: 'Name of the model the behavior is attached to',
+    behaviorName: 'Name of the behavior method on the model',
+  };
+  if (defaults[varName]) return defaults[varName];
+  return varName.replace(/([A-Z])/g, ' $1').replace(/^./, c => c.toUpperCase());
+}
+
+function substitute(text: string, values: Record<string, string>): string {
+  return text.replace(/\\{\\{\\s*([a-zA-Z_][a-zA-Z0-9_]*)\\s*\\}\\}/g, (match, name) => {
+    if (name in values) return values[name];
+    if (name in SCHEMA_VAR_PATHS) return SCHEMA_VAR_PATHS[name];
+    return match; // unknown var — leave the placeholder so it's visible
+  });
+}
+
+function renderMessages(prompt: Prompt, args: Record<string, string>): { role: 'user'; content: { type: 'text'; text: string } }[] {
+  const src = prompt.source;
+  const sections: string[] = [];
+  if (src?.system?.role) sections.push(\`[System role]\\n\${substitute(src.system.role, args).trim()}\`);
+  if (src?.system?.context) sections.push(\`[Context]\\n\${substitute(src.system.context, args).trim()}\`);
+  if (src?.user?.template) sections.push(substitute(src.user.template, args).trim());
+  const text = sections.filter(Boolean).join('\\n\\n');
+  return [{ role: 'user', content: { type: 'text', text } }];
+}
+
+export const PROMPTS: Prompt[] = loadPrompts();
+
+const BY_NAME = new Map<string, Prompt>(PROMPTS.map(p => [p.name, p]));
+
+export async function getPrompt(name: string, args: Record<string, string>) {
+  const prompt = BY_NAME.get(name);
+  if (!prompt) {
+    throw new Error(\`Unknown prompt: \${name}\`);
+  }
+  return {
+    description: prompt.description,
+    messages: renderMessages(prompt, args),
+  };
+}
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "SpecVerse toolchain \u2014 parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",