@claude-flow/cli 3.32.35 → 3.32.36

package/node_modules/@claude-flow/codex/dist/generators/skill-md.js

@@ -1,17 +1,28 @@
 /**
  * @claude-flow/codex - SKILL.md Generator
  *
- * Generates SKILL.md files for OpenAI Codex CLI skills
- * Uses YAML frontmatter for metadata
+ * Custom skills are rendered from typed options. Built-in skills use the
+ * packaged `.agents/skills` trees as their canonical definitions so direct
+ * generation, project initialization, and npm artifacts cannot drift.
  */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const BUILT_IN_SKILL_NAMES = [
+    'swarm-orchestration',
+    'memory-management',
+    'sparc-methodology',
+    'security-audit',
+    'performance-analysis',
+    'github-automation',
+];
+const BUILT_IN_SKILLS_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../.agents/skills');
 /**
- * Generate a SKILL.md file based on the provided options
+ * Generate a SKILL.md file based on the provided options.
  */
 export async function generateSkillMd(options) {
     const { name, description, version = '1.0.0', author = 'rUv', tags, triggers = [], skipWhen = [], scripts = [], references = [], commands = [], } = options;
-    // Derive discovery tags from the skill name when not supplied explicitly.
     const tagList = tags && tags.length > 0 ? tags : name.split('-').filter(Boolean);
-    // Build YAML frontmatter
     const triggerText = triggers.length > 0
         ? `Use when: ${triggers.join(', ')}.`
         : '';
@@ -28,19 +39,9 @@ description: >
   ${triggerText}
   ${skipText}
 ---`;
-    // Build commands section
-    const commandsSection = commands.length > 0
-        ? buildCommandsSection(commands)
-        : '';
-    // Build scripts section
-    const scriptsSection = scripts.length > 0
-        ? buildScriptsSection(scripts)
-        : '';
-    // Build references section
-    const referencesSection = references.length > 0
-        ? buildReferencesSection(references)
-        : '';
-    // Combine all sections
+    const commandsSection = commands.length > 0 ? buildCommandsSection(commands) : '';
+    const scriptsSection = scripts.length > 0 ? buildScriptsSection(scripts) : '';
+    const referencesSection = references.length > 0 ? buildReferencesSection(references) : '';
     return `${frontmatter}
 
 # ${formatSkillName(name)} Skill
@@ -63,9 +64,6 @@ ${referencesSection}
 4. Document any new learnings
 `;
 }
-/**
- * Build the commands section of the SKILL.md
- */
 function buildCommandsSection(commands) {
     const lines = commands.map(cmd => {
         let block = `### ${cmd.name}\n${cmd.description}\n\n\`\`\`bash\n${cmd.command}\n\`\`\``;
@@ -80,9 +78,6 @@ function buildCommandsSection(commands) {
 ${lines.join('\n\n')}
 `;
 }
-/**
- * Build the scripts section
- */
 function buildScriptsSection(scripts) {
     const lines = scripts.map(s => `| \`${s.name}\` | \`${s.path}\` | ${s.description} |`);
     return `
@@ -93,9 +88,6 @@ function buildScriptsSection(scripts) {
 ${lines.join('\n')}
 `;
 }
-/**
- * Build the references section
- */
 function buildReferencesSection(references) {
     const lines = references.map(r => `| \`${r.name}\` | \`${r.path}\` | ${r.description ?? ''} |`);
     return `
@@ -106,846 +98,89 @@ function buildReferencesSection(references) {
 ${lines.join('\n')}
 `;
 }
-/**
- * Format skill name for display (kebab-case to Title Case)
- */
 function formatSkillName(name) {
     return name
         .split('-')
         .map(word => word.charAt(0).toUpperCase() + word.slice(1))
         .join(' ');
 }
+async function readPayloadTree(root) {
+    const payload = {};
+    async function visit(directory) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const absolute = path.join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`Built-in skill payload cannot contain symlinks: ${absolute}`);
+            }
+            if (entry.isDirectory()) {
+                await visit(absolute);
+            }
+            else if (entry.isFile()) {
+                const relative = path.relative(root, absolute);
+                if (relative.startsWith('..') || path.isAbsolute(relative)) {
+                    throw new Error(`Built-in skill payload escapes its root: ${absolute}`);
+                }
+                const payloadPath = relative.split(path.sep).join('/');
+                payload[payloadPath] = await readFile(absolute, 'utf8');
+            }
+        }
+    }
+    await visit(root);
+    return payload;
+}
 /**
- * Generate a skill from a built-in template
+ * Read one canonical built-in tree from the package payload.
  */
 export async function generateBuiltInSkill(skillName) {
-    const skillTemplates = {
-        'swarm-orchestration': {
-            name: 'swarm-orchestration',
-            description: 'Multi-agent swarm coordination for complex tasks. Uses hierarchical topology with specialized agents to break down and execute complex work across multiple files and modules.',
-            triggers: [
-                '3+ files need changes',
-                'new feature implementation',
-                'cross-module refactoring',
-                'API changes with tests',
-                'security-related changes',
-                'performance optimization across codebase',
-                'database schema changes',
-            ],
-            skipWhen: [
-                'single file edits',
-                'simple bug fixes (1-2 lines)',
-                'documentation updates',
-                'configuration changes',
-                'quick exploration',
-            ],
-            commands: [
-                {
-                    name: 'Initialize Swarm',
-                    description: 'Start a new swarm with hierarchical topology (anti-drift)',
-                    command: 'npx ruflo swarm init --topology hierarchical --max-agents 8 --strategy specialized',
-                    example: 'npx ruflo swarm init --topology hierarchical --max-agents 6 --strategy specialized',
-                },
-                {
-                    name: 'Route Task',
-                    description: 'Route a task to the appropriate agents based on task type',
-                    command: 'npx @claude-flow/cli hooks route --task "[task description]"',
-                    example: 'npx @claude-flow/cli hooks route --task "implement OAuth2 authentication flow"',
-                },
-                {
-                    name: 'Spawn Agent',
-                    description: 'Spawn a specific agent type',
-                    command: 'npx @claude-flow/cli agent spawn --type [type] --name [name]',
-                    example: 'npx @claude-flow/cli agent spawn --type coder --name impl-auth',
-                },
-                {
-                    name: 'Monitor Status',
-                    description: 'Check the current swarm status',
-                    command: 'npx @claude-flow/cli swarm status --verbose',
-                },
-                {
-                    name: 'Orchestrate Task',
-                    description: 'Orchestrate a task across multiple agents',
-                    command: 'npx @claude-flow/cli task orchestrate --task "[task]" --strategy adaptive',
-                    example: 'npx @claude-flow/cli task orchestrate --task "refactor auth module" --strategy parallel --max-agents 4',
-                },
-                {
-                    name: 'List Agents',
-                    description: 'List all active agents',
-                    command: 'npx @claude-flow/cli agent list --filter active',
-                },
-            ],
-            scripts: [
-                {
-                    name: 'swarm-start',
-                    path: '.agents/scripts/swarm-start.sh',
-                    description: 'Initialize swarm with default settings',
-                },
-                {
-                    name: 'swarm-monitor',
-                    path: '.agents/scripts/swarm-monitor.sh',
-                    description: 'Real-time swarm monitoring dashboard',
-                },
-            ],
-            references: [
-                {
-                    name: 'Agent Types',
-                    path: 'docs/agents.md',
-                    description: 'Complete list of agent types and capabilities',
-                },
-                {
-                    name: 'Topology Guide',
-                    path: 'docs/topology.md',
-                    description: 'Swarm topology configuration guide',
-                },
-            ],
-        },
-        'memory-management': {
-            name: 'memory-management',
-            description: 'AgentDB memory system with HNSW vector search. Provides 150x-12,500x faster pattern retrieval, persistent storage, and semantic search capabilities for learning and knowledge management.',
-            triggers: [
-                'need to store successful patterns',
-                'searching for similar solutions',
-                'semantic lookup of past work',
-                'learning from previous tasks',
-                'sharing knowledge between agents',
-                'building knowledge base',
-            ],
-            skipWhen: [
-                'no learning needed',
-                'ephemeral one-off tasks',
-                'external data sources available',
-                'read-only exploration',
-            ],
-            commands: [
-                {
-                    name: 'Store Pattern',
-                    description: 'Store a pattern or knowledge item in memory',
-                    command: 'npx @claude-flow/cli memory store --key "[key]" --value "[value]" --namespace patterns',
-                    example: 'npx @claude-flow/cli memory store --key "auth-jwt-pattern" --value "JWT validation with refresh tokens" --namespace patterns',
-                },
-                {
-                    name: 'Semantic Search',
-                    description: 'Search memory using semantic similarity',
-                    command: 'npx @claude-flow/cli memory search --query "[search terms]" --limit 10',
-                    example: 'npx @claude-flow/cli memory search --query "authentication best practices" --limit 5',
-                },
-                {
-                    name: 'Retrieve Entry',
-                    description: 'Retrieve a specific memory entry by key',
-                    command: 'npx @claude-flow/cli memory get --key "[key]" --namespace [namespace]',
-                    example: 'npx @claude-flow/cli memory get --key "auth-jwt-pattern" --namespace patterns',
-                },
-                {
-                    name: 'List Entries',
-                    description: 'List all entries in a namespace',
-                    command: 'npx @claude-flow/cli memory list --namespace [namespace]',
-                    example: 'npx @claude-flow/cli memory list --namespace patterns --limit 20',
-                },
-                {
-                    name: 'Delete Entry',
-                    description: 'Delete a memory entry',
-                    command: 'npx @claude-flow/cli memory delete --key "[key]" --namespace [namespace]',
-                },
-                {
-                    name: 'Initialize HNSW Index',
-                    description: 'Initialize HNSW vector search index',
-                    command: 'npx @claude-flow/cli memory init --enable-hnsw',
-                },
-                {
-                    name: 'Memory Stats',
-                    description: 'Show memory usage statistics',
-                    command: 'npx @claude-flow/cli memory stats',
-                },
-                {
-                    name: 'Export Memory',
-                    description: 'Export memory to JSON',
-                    command: 'npx @claude-flow/cli memory export --output memory-backup.json',
-                },
-            ],
-            scripts: [
-                {
-                    name: 'memory-backup',
-                    path: '.agents/scripts/memory-backup.sh',
-                    description: 'Backup memory to external storage',
-                },
-                {
-                    name: 'memory-consolidate',
-                    path: '.agents/scripts/memory-consolidate.sh',
-                    description: 'Consolidate and optimize memory',
-                },
-            ],
-            references: [
-                {
-                    name: 'HNSW Guide',
-                    path: 'docs/hnsw.md',
-                    description: 'HNSW vector search configuration',
-                },
-                {
-                    name: 'Memory Schema',
-                    path: 'docs/memory-schema.md',
-                    description: 'Memory namespace and schema reference',
-                },
-            ],
-        },
-        'sparc-methodology': {
-            name: 'sparc-methodology',
-            description: 'SPARC development workflow: Specification, Pseudocode, Architecture, Refinement, Completion. A structured approach for complex implementations that ensures thorough planning before coding.',
-            triggers: [
-                'new feature implementation',
-                'complex implementations',
-                'architectural changes',
-                'system redesign',
-                'integration work',
-                'unclear requirements',
-            ],
-            skipWhen: [
-                'simple bug fixes',
-                'documentation updates',
-                'configuration changes',
-                'well-defined small tasks',
-                'routine maintenance',
-            ],
-            commands: [
-                {
-                    name: 'Specification Phase',
-                    description: 'Define requirements, acceptance criteria, and constraints',
-                    command: 'npx @claude-flow/cli hooks route --task "specification: [requirements]"',
-                    example: 'npx @claude-flow/cli hooks route --task "specification: user authentication with OAuth2, MFA, and session management"',
-                },
-                {
-                    name: 'Pseudocode Phase',
-                    description: 'Write high-level pseudocode for the implementation',
-                    command: 'npx @claude-flow/cli hooks route --task "pseudocode: [feature]"',
-                    example: 'npx @claude-flow/cli hooks route --task "pseudocode: OAuth2 login flow with token refresh"',
-                },
-                {
-                    name: 'Architecture Phase',
-                    description: 'Design system structure, interfaces, and dependencies',
-                    command: 'npx @claude-flow/cli hooks route --task "architecture: [design]"',
-                    example: 'npx @claude-flow/cli hooks route --task "architecture: auth module with service layer, repository, and API endpoints"',
-                },
-                {
-                    name: 'Refinement Phase',
-                    description: 'Iterate on the design based on feedback',
-                    command: 'npx @claude-flow/cli hooks route --task "refinement: [feedback]"',
-                    example: 'npx @claude-flow/cli hooks route --task "refinement: add rate limiting and brute force protection"',
-                },
-                {
-                    name: 'Completion Phase',
-                    description: 'Finalize implementation with tests and documentation',
-                    command: 'npx @claude-flow/cli hooks route --task "completion: [final checks]"',
-                    example: 'npx @claude-flow/cli hooks route --task "completion: verify all tests pass, update API docs, security review"',
-                },
-                {
-                    name: 'SPARC Coordinator',
-                    description: 'Spawn SPARC coordinator agent',
-                    command: 'npx @claude-flow/cli agent spawn --type sparc-coord --name sparc-lead',
-                },
-            ],
-            scripts: [
-                {
-                    name: 'sparc-init',
-                    path: '.agents/scripts/sparc-init.sh',
-                    description: 'Initialize SPARC workflow for a new feature',
-                },
-                {
-                    name: 'sparc-review',
-                    path: '.agents/scripts/sparc-review.sh',
-                    description: 'Run SPARC phase review checklist',
-                },
-            ],
-            references: [
-                {
-                    name: 'SPARC Overview',
-                    path: 'docs/sparc.md',
-                    description: 'Complete SPARC methodology guide',
-                },
-                {
-                    name: 'Phase Templates',
-                    path: 'docs/sparc-templates.md',
-                    description: 'Templates for each SPARC phase',
-                },
-            ],
-        },
-        'security-audit': {
-            name: 'security-audit',
-            description: 'Comprehensive security scanning and vulnerability detection. Includes input validation, path traversal prevention, CVE detection, and secure coding pattern enforcement.',
-            triggers: [
-                'authentication implementation',
-                'authorization logic',
-                'payment processing',
-                'user data handling',
-                'API endpoint creation',
-                'file upload handling',
-                'database queries',
-                'external API integration',
-            ],
-            skipWhen: [
-                'read-only operations on public data',
-                'internal development tooling',
-                'static documentation',
-                'styling changes',
-            ],
-            commands: [
-                {
-                    name: 'Full Security Scan',
-                    description: 'Run comprehensive security analysis on the codebase',
-                    command: 'npx @claude-flow/cli security scan --depth full',
-                    example: 'npx @claude-flow/cli security scan --depth full --output security-report.json',
-                },
-                {
-                    name: 'Input Validation Check',
-                    description: 'Check for input validation issues',
-                    command: 'npx @claude-flow/cli security scan --check input-validation',
-                    example: 'npx @claude-flow/cli security scan --check input-validation --path ./src/api',
-                },
-                {
-                    name: 'Path Traversal Check',
-                    description: 'Check for path traversal vulnerabilities',
-                    command: 'npx @claude-flow/cli security scan --check path-traversal',
-                },
-                {
-                    name: 'SQL Injection Check',
-                    description: 'Check for SQL injection vulnerabilities',
-                    command: 'npx @claude-flow/cli security scan --check sql-injection',
-                },
-                {
-                    name: 'XSS Check',
-                    description: 'Check for cross-site scripting vulnerabilities',
-                    command: 'npx @claude-flow/cli security scan --check xss',
-                },
-                {
-                    name: 'CVE Scan',
-                    description: 'Scan dependencies for known CVEs',
-                    command: 'npx @claude-flow/cli security cve --scan',
-                    example: 'npx @claude-flow/cli security cve --scan --severity high',
-                },
-                {
-                    name: 'Security Audit Report',
-                    description: 'Generate full security audit report',
-                    command: 'npx @claude-flow/cli security audit --report',
-                    example: 'npx @claude-flow/cli security audit --report --format markdown --output SECURITY.md',
-                },
-                {
-                    name: 'Threat Modeling',
-                    description: 'Run threat modeling analysis',
-                    command: 'npx @claude-flow/cli security threats --analyze',
-                },
-                {
-                    name: 'Validate Secrets',
-                    description: 'Check for hardcoded secrets',
-                    command: 'npx @claude-flow/cli security validate --check secrets',
-                },
-            ],
-            scripts: [
-                {
-                    name: 'security-scan',
-                    path: '.agents/scripts/security-scan.sh',
-                    description: 'Run full security scan pipeline',
-                },
-                {
-                    name: 'cve-remediate',
-                    path: '.agents/scripts/cve-remediate.sh',
-                    description: 'Auto-remediate known CVEs',
-                },
-            ],
-            references: [
-                {
-                    name: 'Security Checklist',
-                    path: 'docs/security-checklist.md',
-                    description: 'Security review checklist',
-                },
-                {
-                    name: 'OWASP Guide',
-                    path: 'docs/owasp-top10.md',
-                    description: 'OWASP Top 10 mitigation guide',
-                },
-            ],
-        },
-        'performance-analysis': {
-            name: 'performance-analysis',
-            description: 'Performance profiling, benchmarking, and optimization. Includes CPU profiling, memory analysis, latency measurement, and automated optimization suggestions.',
-            triggers: [
-                'slow operations detected',
-                'memory usage issues',
-                'optimization needed',
-                'pre-release performance validation',
-                'database query optimization',
-                'API latency concerns',
-                'bundle size analysis',
-            ],
-            skipWhen: [
-                'early feature development',
-                'documentation updates',
-                'prototyping phase',
-                'configuration changes',
-            ],
-            commands: [
-                {
-                    name: 'Run Benchmark Suite',
-                    description: 'Execute all performance benchmarks',
-                    command: 'npx @claude-flow/cli performance benchmark --suite all',
-                    example: 'npx @claude-flow/cli performance benchmark --suite all --iterations 100 --output bench-results.json',
-                },
-                {
-                    name: 'Profile Code',
-                    description: 'Profile code execution for CPU and memory',
-                    command: 'npx @claude-flow/cli performance profile --target ./src',
-                    example: 'npx @claude-flow/cli performance profile --target ./src/api --duration 60s',
-                },
-                {
-                    name: 'Memory Analysis',
-                    description: 'Analyze memory usage patterns',
-                    command: 'npx @claude-flow/cli performance metrics --metric memory',
-                    example: 'npx @claude-flow/cli performance metrics --metric memory --threshold 100MB',
-                },
-                {
-                    name: 'Latency Analysis',
-                    description: 'Measure and analyze latency',
-                    command: 'npx @claude-flow/cli performance metrics --metric latency',
-                },
-                {
-                    name: 'Optimize Suggestions',
-                    description: 'Get automated optimization suggestions',
-                    command: 'npx @claude-flow/cli performance optimize --analyze',
-                    example: 'npx @claude-flow/cli performance optimize --analyze --apply-safe',
-                },
-                {
-                    name: 'Performance Report',
-                    description: 'Generate performance report',
-                    command: 'npx @claude-flow/cli performance report',
-                    example: 'npx @claude-flow/cli performance report --format html --output perf-report.html',
-                },
-                {
-                    name: 'Compare Benchmarks',
-                    description: 'Compare benchmark results',
-                    command: 'npx @claude-flow/cli performance benchmark --compare baseline.json current.json',
-                },
-                {
-                    name: 'WASM Benchmark',
-                    description: 'Run WASM-specific benchmarks',
-                    command: 'npx @claude-flow/cli performance benchmark --suite wasm',
-                },
-            ],
-            scripts: [
-                {
-                    name: 'perf-baseline',
-                    path: '.agents/scripts/perf-baseline.sh',
-                    description: 'Capture performance baseline',
-                },
-                {
-                    name: 'perf-regression',
-                    path: '.agents/scripts/perf-regression.sh',
-                    description: 'Check for performance regressions',
-                },
-            ],
-            references: [
-                {
-                    name: 'Performance Guide',
-                    path: 'docs/performance.md',
-                    description: 'Performance optimization guide',
-                },
-                {
-                    name: 'Benchmark Reference',
-                    path: 'docs/benchmarks.md',
-                    description: 'Benchmark configuration reference',
-                },
-            ],
-        },
-        'github-automation': {
-            name: 'github-automation',
-            description: 'GitHub workflow automation including PR management, CI/CD, issue tracking, and release management. Integrates with GitHub CLI for seamless automation.',
-            triggers: [
-                'creating pull requests',
-                'setting up CI/CD pipelines',
-                'release management',
-                'issue tracking automation',
-                'branch management',
-                'code review workflows',
-                'repository maintenance',
-            ],
-            skipWhen: [
-                'local-only development',
-                'prototyping without commits',
-                'non-GitHub repositories',
-                'offline work',
-            ],
-            commands: [
-                {
-                    name: 'Create Pull Request',
-                    description: 'Create a new pull request with summary',
-                    command: 'gh pr create --title "[title]" --body "[description]"',
-                    example: 'gh pr create --title "feat: add OAuth2 authentication" --body "## Summary\\n- Implemented OAuth2 flow\\n- Added token refresh\\n\\n## Test Plan\\n- Run auth tests"',
-                },
-                {
-                    name: 'View PR',
-                    description: 'View pull request details',
-                    command: 'gh pr view [number]',
-                    example: 'gh pr view 123 --comments',
-                },
-                {
-                    name: 'Merge PR',
-                    description: 'Merge a pull request',
-                    command: 'gh pr merge [number] --squash',
-                    example: 'gh pr merge 123 --squash --delete-branch',
-                },
-                {
-                    name: 'Run Workflow',
-                    description: 'Trigger a GitHub Actions workflow',
-                    command: 'gh workflow run [workflow]',
-                    example: 'gh workflow run ci.yml --ref feature-branch',
-                },
-                {
-                    name: 'View Workflow Runs',
-                    description: 'List recent workflow runs',
-                    command: 'gh run list --limit 10',
-                },
-                {
-                    name: 'Create Issue',
-                    description: 'Create a new issue',
-                    command: 'gh issue create --title "[title]" --body "[body]"',
-                    example: 'gh issue create --title "Bug: login fails on mobile" --body "## Description\\n..." --label bug',
-                },
-                {
-                    name: 'Create Release',
-                    description: 'Create a new release',
-                    command: 'gh release create [tag] --notes "[notes]"',
-                    example: 'gh release create v1.0.0 --notes "Initial release" --generate-notes',
-                },
-                {
-                    name: 'View Checks',
-                    description: 'View PR check status',
-                    command: 'gh pr checks [number]',
-                    example: 'gh pr checks 123 --watch',
-                },
-                {
-                    name: 'Review PR',
-                    description: 'Submit a PR review',
-                    command: 'gh pr review [number] --approve --body "[comment]"',
-                    example: 'gh pr review 123 --approve --body "LGTM! Great work on the tests."',
-                },
-            ],
-            scripts: [
-                {
-                    name: 'pr-template',
-                    path: '.agents/scripts/pr-template.sh',
-                    description: 'Generate PR from template',
-                },
-                {
-                    name: 'release-prep',
-                    path: '.agents/scripts/release-prep.sh',
-                    description: 'Prepare release with changelog',
-                },
-            ],
-            references: [
-                {
-                    name: 'GitHub CLI Reference',
-                    path: 'docs/gh-cli.md',
-                    description: 'GitHub CLI command reference',
-                },
-                {
-                    name: 'PR Guidelines',
-                    path: 'docs/pr-guidelines.md',
-                    description: 'Pull request best practices',
-                },
-                {
-                    name: 'CI/CD Setup',
-                    path: 'docs/ci-cd.md',
-                    description: 'CI/CD pipeline configuration',
-                },
-            ],
-        },
-    };
-    const template = skillTemplates[skillName];
-    if (!template) {
+    if (!BUILT_IN_SKILL_NAMES.includes(skillName)) {
         throw new Error(`Unknown built-in skill: ${skillName}`);
     }
-    const skillMd = await generateSkillMd(template);
-    // Generate helper scripts
-    const scripts = {};
-    if (template.scripts) {
-        for (const script of template.scripts) {
-            // Use just the script filename, not the full path
-            const scriptFilename = `${script.name}.sh`;
-            scripts[scriptFilename] = generateHelperScript(skillName, script.name);
+    const skillRoot = path.join(BUILT_IN_SKILLS_ROOT, skillName);
+    let skillMd;
+    try {
+        skillMd = await readFile(path.join(skillRoot, 'SKILL.md'), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Built-in skill payload missing: ${skillName}/SKILL.md`);
         }
+        throw error;
     }
-    return {
+    const result = {
         skillMd,
-        scripts,
-        references: {},
+        scripts: await readPayloadTree(path.join(skillRoot, 'scripts')),
+        references: await readPayloadTree(path.join(skillRoot, 'references')),
     };
+    validateBuiltInSkillPayload(skillName, result.skillMd, result.scripts, result.references);
+    return result;
 }
 /**
- * Generate a helper script for a skill
+ * Ensure every skill-local path is contained in and shipped with its tree.
  */
-function generateHelperScript(skillName, scriptName) {
-    const scripts = {
-        'swarm-orchestration': {
-            'swarm-start': `#!/bin/bash
-# Swarm Orchestration - Start Script
-# Initialize swarm with default anti-drift settings
-
-set -e
-
-echo "Initializing hierarchical swarm..."
-npx ruflo swarm init \\
-  --topology hierarchical \\
-  --max-agents 8 \\
-  --strategy specialized
-
-echo "Swarm initialized successfully"
-npx @claude-flow/cli swarm status
-`,
-            'swarm-monitor': `#!/bin/bash
-# Swarm Orchestration - Monitor Script
-# Real-time swarm monitoring
-
-set -e
-
-echo "Starting swarm monitor..."
-npx @claude-flow/cli swarm status --watch --interval 5
-`,
-        },
-        'memory-management': {
-            'memory-backup': `#!/bin/bash
-# Memory Management - Backup Script
-# Export memory to backup file
-
-set -e
-
-BACKUP_DIR="\${BACKUP_DIR:-./.backups}"
-TIMESTAMP=$(date +%Y%m%d_%H%M%S)
-BACKUP_FILE="\${BACKUP_DIR}/memory_\${TIMESTAMP}.json"
-
-mkdir -p "$BACKUP_DIR"
-
-echo "Backing up memory to $BACKUP_FILE..."
-npx @claude-flow/cli memory export --output "$BACKUP_FILE"
-
-echo "Backup complete: $BACKUP_FILE"
-`,
-            'memory-consolidate': `#!/bin/bash
-# Memory Management - Consolidate Script
-# Optimize and consolidate memory
-
-set -e
-
-echo "Running memory consolidation..."
-npx @claude-flow/cli hooks worker dispatch --trigger consolidate
-
-echo "Memory consolidation complete"
-npx @claude-flow/cli memory stats
-`,
-        },
-        'sparc-methodology': {
-            'sparc-init': `#!/bin/bash
-# SPARC Methodology - Init Script
-# Initialize SPARC workflow for a new feature
-
-set -e
-
-FEATURE_NAME="\${1:-new-feature}"
-
-echo "Initializing SPARC workflow for: $FEATURE_NAME"
-
-# Create SPARC documentation directory
-mkdir -p "./docs/sparc/$FEATURE_NAME"
-
-# Create phase files
-touch "./docs/sparc/$FEATURE_NAME/1-specification.md"
-touch "./docs/sparc/$FEATURE_NAME/2-pseudocode.md"
-touch "./docs/sparc/$FEATURE_NAME/3-architecture.md"
-touch "./docs/sparc/$FEATURE_NAME/4-refinement.md"
-touch "./docs/sparc/$FEATURE_NAME/5-completion.md"
-
-echo "SPARC workflow initialized in ./docs/sparc/$FEATURE_NAME"
-`,
-            'sparc-review': `#!/bin/bash
-# SPARC Methodology - Review Script
-# Run SPARC phase review checklist
-
-set -e
-
-FEATURE_DIR="\${1:-.}"
-
-echo "SPARC Phase Review Checklist"
-echo "============================="
-
-for phase in specification pseudocode architecture refinement completion; do
-  if [ -f "$FEATURE_DIR/\${phase}.md" ]; then
-    echo "[x] $phase - found"
-  else
-    echo "[ ] $phase - missing"
-  fi
-done
-`,
-        },
-        'security-audit': {
-            'security-scan': `#!/bin/bash
-# Security Audit - Full Scan Script
-# Run comprehensive security scan pipeline
-
-set -e
-
-echo "Running full security scan..."
-
-# Input validation
-echo "Checking input validation..."
-npx @claude-flow/cli security scan --check input-validation
-
-# Path traversal
-echo "Checking path traversal..."
-npx @claude-flow/cli security scan --check path-traversal
-
-# SQL injection
-echo "Checking SQL injection..."
-npx @claude-flow/cli security scan --check sql-injection
-
-# XSS
-echo "Checking XSS..."
-npx @claude-flow/cli security scan --check xss
-
-# Secrets
-echo "Checking for hardcoded secrets..."
-npx @claude-flow/cli security validate --check secrets
-
-# CVE scan
-echo "Scanning dependencies for CVEs..."
-npx @claude-flow/cli security cve --scan
-
-echo "Security scan complete"
-`,
-            'cve-remediate': `#!/bin/bash
-# Security Audit - CVE Remediation Script
-# Auto-remediate known CVEs
-
-set -e
-
-echo "Scanning for CVEs..."
-npx @claude-flow/cli security cve --scan --severity high
-
-echo "Attempting auto-remediation..."
-npm audit fix
-
-echo "Re-scanning after remediation..."
-npx @claude-flow/cli security cve --scan
-
-echo "CVE remediation complete"
-`,
-        },
-        'performance-analysis': {
-            'perf-baseline': `#!/bin/bash
-# Performance Analysis - Baseline Script
-# Capture performance baseline
-
-set -e
-
-BASELINE_FILE="\${1:-baseline.json}"
-
-echo "Capturing performance baseline..."
-npx @claude-flow/cli performance benchmark \\
-  --suite all \\
-  --iterations 100 \\
-  --output "$BASELINE_FILE"
-
-echo "Baseline saved to $BASELINE_FILE"
-`,
-            'perf-regression': `#!/bin/bash
-# Performance Analysis - Regression Check Script
-# Check for performance regressions
-
-set -e
-
-BASELINE_FILE="\${1:-baseline.json}"
-CURRENT_FILE="current.json"
-THRESHOLD="\${2:-10}"
-
-echo "Running current benchmarks..."
-npx @claude-flow/cli performance benchmark \\
-  --suite all \\
-  --iterations 100 \\
-  --output "$CURRENT_FILE"
-
-echo "Comparing against baseline..."
-npx @claude-flow/cli performance benchmark \\
-  --compare "$BASELINE_FILE" "$CURRENT_FILE" \\
-  --threshold "$THRESHOLD"
-
-rm "$CURRENT_FILE"
-`,
-        },
-        'github-automation': {
-            'pr-template': `#!/bin/bash
-# GitHub Automation - PR Template Script
-# Generate PR from template
-
-set -e
-
-TITLE="\${1:-Update}"
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-echo "Creating PR for branch: $BRANCH"
-
-gh pr create \\
-  --title "$TITLE" \\
-  --body "$(cat <<EOF
-## Summary
-<!-- Describe your changes -->
-
-## Test Plan
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual testing completed
-
-## Checklist
-- [ ] Code follows style guidelines
-- [ ] Documentation updated
-- [ ] No breaking changes
-
-Generated with claude-flow
-EOF
-)"
-
-echo "PR created successfully"
-`,
-            'release-prep': `#!/bin/bash
-# GitHub Automation - Release Prep Script
-# Prepare release with changelog
-
-set -e
-
-VERSION="\${1:-patch}"
-
-echo "Preparing release..."
-
-# Bump version
-npm version "$VERSION" --no-git-tag-version
-
-NEW_VERSION=$(node -p "require('./package.json').version")
-
-echo "Creating release v$NEW_VERSION..."
-gh release create "v$NEW_VERSION" \\
-  --generate-notes \\
-  --draft
-
-echo "Draft release v$NEW_VERSION created"
-`,
-        },
-    };
-    const skillScripts = scripts[skillName];
-    if (skillScripts && skillScripts[scriptName]) {
-        return skillScripts[scriptName];
+export function validateBuiltInSkillPayload(skillName, skillMd, scripts, references) {
+    const localPaths = Array.from(skillMd.matchAll(/`((?:scripts|references)\/[^`\s]+)`/g), (match) => match[1]);
+    for (const localPath of localPaths) {
+        const normalized = path.posix.normalize(localPath.replaceAll('\\', '/'));
+        if (normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+            throw new Error(`Built-in skill path escapes ${skillName}: ${localPath}`);
+        }
+        const slash = normalized.indexOf('/');
+        const directory = normalized.slice(0, slash);
+        const payloadPath = normalized.slice(slash + 1);
+        const payload = directory === 'scripts' ? scripts : references;
+        if (!Object.hasOwn(payload, payloadPath)) {
+            throw new Error(`Built-in skill payload missing: ${skillName}/${normalized}`);
+        }
     }
-    return `#!/bin/bash
-# ${skillName} - ${scriptName}
-# Generated by @claude-flow/codex
-
-set -e
-
-echo "Running ${scriptName}..."
-# Add your script logic here
-`;
 }
 //# sourceMappingURL=skill-md.js.map