@specverse/engines 5.0.2 → 5.2.0

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

@@ -1,12 +1,14 @@
-import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { createRequire } from "module";
 import { join } from "path";
+const require2 = createRequire(import.meta.url);
 function generateMCPServer(context) {
   const { spec, outputDir } = context;
   const mcpDir = join(outputDir || ".", "tools", "specverse-mcp");
   const srcDir = join(mcpDir, "src");
   if (!existsSync(srcDir)) mkdirSync(srcDir, { recursive: true });
   const distribution = extractMCPDistribution(spec);
-  const version = distribution?.version || spec?.metadata?.version || spec?.version || "5.0.0";
+  const version = distribution?.version || resolveSelfVersion() || spec?.metadata?.version || spec?.version || "5.1.0";
   const description = distribution?.description || "SpecVerse MCP server \u2014 exposes the specverse CLI as MCP tools and the live spec schema + docs as MCP resources.";
   const displayName = distribution?.displayName || "SpecVerse MCP";
   const cliCommands = extractCLITools(spec);
@@ -14,10 +16,20 @@ function generateMCPServer(context) {
   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}
-  ${cliCommands.length} tools (one per CLI command), 2 resources (schema + docs)`;
+  ${cliCommands.length} tools, 5 resources, 6 prompts (derived from @specverse/engines/assets/prompts)`;
+}
+function resolveSelfVersion() {
+  try {
+    const pkgPath = require2.resolve("@specverse/self/package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version || null;
+  } catch {
+    return null;
+  }
 }
 function extractCLITools(spec) {
   const out = [];
@@ -118,9 +130,13 @@ function generatePackageJson(version, description) {
     },
     dependencies: {
       "@modelcontextprotocol/sdk": "^1.17.4",
-      "@specverse/entities": "^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"
     },
@@ -155,13 +171,15 @@ function generateTsconfig() {
   }, null, 2) + "\n";
 }
 function generateServer(displayName, version) {
+  const instructions = SERVER_INSTRUCTIONS;
   return `#!/usr/bin/env node
 /**
  * SpecVerse MCP Server \u2014 stdio transport.
  *
- * Wires the MCP protocol to the generated tool registry + live resources.
- * No handwritten business logic \u2014 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';
@@ -170,13 +188,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 () => ({
@@ -205,10 +231,49 @@ 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 \u2014 backend (Fastify/Prisma), frontend (React/Tailwind), CLI, tools, diagrams.",
+  "",
+  "Before using tools, read these resources to ground yourself in the language:",
+  "- specverse://guide \u2014 canonical user guide (spec language, CLI reference, convention patterns)",
+  "- specverse://ai-guidance \u2014 curated hints for generating valid specs",
+  "- specverse://minimal-example \u2014 one minimal .specly showing every feature in ~100 lines",
+  "- specverse://schema \u2014 the JSON Schema (draft 2020-12) for .specly validation",
+  "- specverse://cli-reference \u2014 every spv CLI subcommand with flags + arguments",
+  "",
+  "Common high-leverage workflows are exposed as MCP prompts (preferred entry point):",
+  "- create: natural-language requirements \u2192 minimal .specly",
+  "- analyse: existing codebase \u2192 .specly that captures what is implemented",
+  "- materialise: .specly \u2192 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() {
   return `/**
  * Thin specverse CLI runner.
@@ -308,11 +373,16 @@ export async function callTool(name: string, args: Record<string, any>) {
 }
 `;
 }
-function generateResources() {
+function generateResources(tools) {
+  const cliReference = buildCliReferenceMarkdown(tools);
   return `/**
- * Resource registry \u2014 exposes the live SpecVerse schema + user guide as
- * MCP resources. Read lazily from @specverse/entities at request time so
- * the contents always match the installed entities version.
+ * Resource registry \u2014 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';
@@ -333,6 +403,13 @@ function resolveEntitiesFile(relative: string): string {
   return join(dirname(pkg), relative);
 }
 
+function resolveSelfFile(relative: string): string {
+  const pkg = require.resolve('@specverse/self/package.json');
+  return join(dirname(pkg), relative);
+}
+
+const CLI_REFERENCE_MARKDOWN = ${JSON.stringify(cliReference)};
+
 export const RESOURCES: Resource[] = [
   {
     uri: 'specverse://schema',
@@ -344,13 +421,43 @@ 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) \u2014 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',
     description: 'The canonical user guide \u2014 spec language, convention patterns, CLI reference.',
     mimeType: 'text/markdown',
     resolve: () => ({
-      text: readFileSync(resolveEntitiesFile('schema/SPECVERSE-COMPLETE-GUIDE.md'), 'utf8'),
+      text: readFileSync(resolveSelfFile('docs/guides/SPECVERSE-COMPLETE-GUIDE.md'), 'utf8'),
+      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',
     }),
   },
@@ -370,6 +477,180 @@ export async function readResource(uri: string) {
 }
 `;
 }
+function buildCliReferenceMarkdown(tools) {
+  const lines = [];
+  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?.properties || {};
+    const required = new Set(tool.inputSchema?.required || []);
+    const positional = new Set(tool.positional);
+    const argEntries = Object.entries(props);
+    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?.type || "string";
+        const desc = (schema?.description || "").replace(/\|/g, "\\|");
+        lines.push(`| \`${name}\` | ${kind} | ${req} | ${type} | ${desc} |`);
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+function generatePrompts() {
+  return `/**
+ * Prompt registry \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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),
+  };
+}
+`;
+}
 export {
   generateMCPServer as default
 };

package/libs/instance-factories/applications/templates/react/runtime-package-json-generator.ts

@@ -38,7 +38,7 @@ export default function generateRuntimePackageJson(context: TemplateContext): st
       "react-dom": "^18.2.0",
       "react-router-dom": "^6.18.0",
       "@tanstack/react-query": "^5.0.0",
-      "@specverse/runtime": "^4.1.0",
+      "@specverse/runtime": "^5.0.0",
       "js-yaml": "^4.1.0",
       "react-hook-form": "^7.48.0",
       "zod": "^3.22.0",

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

@@ -201,6 +201,49 @@ import type { ParserEngine } from '@specverse/types';`,
           }
         }`
   },
+  'validate-bundle': {
+    imports: `import { existsSync, statSync } from 'fs';
+import { resolve } from 'path';`,
+    handler: `const target = resolve(path);
+        if (!existsSync(target)) {
+          console.error('Path not found:', target);
+          process.exit(1);
+        }
+        if (!statSync(target).isDirectory()) {
+          console.error('Expected a bundle directory, got a file:', target);
+          process.exit(1);
+        }
+
+        const { validateBundle } = await import('@specverse/engines/bundles');
+        const report = await validateBundle(target);
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+          if (report.totals.fail > 0) process.exit(1);
+          return;
+        }
+
+        const statusSymbol = (s: 'pass' | 'fail' | 'skip'): string => {
+          if (s === 'pass') return '✓';
+          if (s === 'fail') return '✗';
+          return '–';
+        };
+
+        console.log('Bundle: ' + report.bundle + '  (' + report.path + ')');
+        console.log('');
+        for (const facet of report.facets) {
+          const facetLine = '  ' + statusSymbol(facet.status) + ' ' + facet.facet.padEnd(10) + facet.status + '  (' + facet.duration + 'ms)';
+          console.log(facetLine);
+          for (const issue of facet.issues) {
+            const loc = issue.location ? ' [' + issue.location + ']' : '';
+            console.log('      - ' + issue.severity + ': ' + issue.message + loc);
+          }
+        }
+        console.log('');
+        console.log('Totals: ' + report.totals.pass + ' pass, ' + report.totals.fail + ' fail, ' + report.totals.skip + ' skip  (' + report.duration + 'ms)');
+
+        if (report.totals.fail > 0) process.exit(1);`
+  },
   infer: {
     imports: `import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { EngineRegistry } from '@specverse/entities';
@@ -1127,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(