@torus-engineering/tas-kit 1.11.1 → 1.13.0

package/bin/cli.js

@@ -1,73 +1,91 @@
-#!/usr/bin/env node
-import { install, update } from '../lib/install.js';
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-function printHelp() {
-  console.log(`
-tas-kit — Torus Agentic SDLC Kit installer
-
-Usage:
-  npx @torus-engineering/tas-kit <command> [options]
-
-Commands:
-  install   Copy TAS Kit files into a project (first-time setup)
-  update    Overwrite .claude/ and .tas/ with the latest kit version
-            (preserves CLAUDE.md, tas.yaml, .env.example)
-
-Options:
-  --directory <path>          Target directory (default: current working directory)
-  --yes, -y                   Skip confirmation prompts (uses native hook by default)
-  --security-hook <mode>      Pre-commit hook mode: husky | native | none
-                              Default: interactive prompt on install,
-                                       no-op on update unless specified.
-  --help, -h                  Show this help message
-
-Examples:
-  npx @torus-engineering/tas-kit install
-  npx @torus-engineering/tas-kit install --directory /path/to/my-project
-  npx @torus-engineering/tas-kit install --yes --security-hook=husky
-  npx @torus-engineering/tas-kit install --security-hook=none
-  npx @torus-engineering/tas-kit update
-  npx @torus-engineering/tas-kit update --yes --security-hook=native
-  `.trim());
-}
-
-if (!command || command === '--help' || command === '-h') {
-  printHelp();
-  process.exit(0);
-}
-
-if (command !== 'install' && command !== 'update') {
-  console.error(`Unknown command: "${command}"\n`);
-  printHelp();
-  process.exit(1);
-}
-
-const opts = { directory: process.cwd(), yes: false, securityHook: null };
-
-for (let i = 1; i < args.length; i++) {
-  const a = args[i];
-  if ((a === '--directory' || a === '-d') && args[i + 1]) {
-    opts.directory = args[++i];
-  } else if (a === '--yes' || a === '-y') {
-    opts.yes = true;
-  } else if (a.startsWith('--security-hook=')) {
-    opts.securityHook = a.slice('--security-hook='.length).toLowerCase();
-  } else if (a === '--security-hook' && args[i + 1]) {
-    opts.securityHook = args[++i].toLowerCase();
-  }
-}
-
-if (opts.securityHook && !['husky', 'native', 'none'].includes(opts.securityHook)) {
-  console.error(`Invalid --security-hook value: "${opts.securityHook}"`);
-  console.error(`Expected one of: husky, native, none`);
-  process.exit(1);
-}
-
-const runner = command === 'update' ? update : install;
-runner(opts).catch((err) => {
-  console.error(`\n${command === 'update' ? 'Update' : 'Install'} failed:`, err.message);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { install, update } from '../lib/install.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+tas-kit — Turbo Agentic SDLC Kit installer
+
+Usage:
+  npx @torus-engineering/tas-kit <command> [options]
+
+Commands:
+  install   Copy TAS Kit files into a project (first-time setup)
+  update    Overwrite .tas/ and platform directories with the latest kit version
+            (preserves CLAUDE.md, tas.yaml, .env.example)
+
+Options:
+  --directory <path>          Target directory (default: current working directory)
+  --yes, -y                   Skip confirmation prompts
+  --platform <id,...>         Platform(s) to install: claude-code, cursor, codex, antigravity
+                              Comma-separated for multiple (default: interactive prompt)
+  --security-hook <mode>      Pre-commit hook mode: husky | native | none
+  --help, -h                  Show this help message
+
+Platforms:
+  claude-code    Claude Code CLI (default)
+  cursor         Cursor IDE
+  codex          OpenAI Codex CLI
+  antigravity    Google Antigravity IDE
+
+Examples:
+  npx @torus-engineering/tas-kit install
+  npx @torus-engineering/tas-kit install --platform claude-code,cursor
+  npx @torus-engineering/tas-kit install --platform codex --yes
+  npx @torus-engineering/tas-kit install --yes --security-hook=husky
+  npx @torus-engineering/tas-kit update
+  npx @torus-engineering/tas-kit update --platform cursor
+  `.trim());
+}
+
+if (!command || command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (command !== 'install' && command !== 'update') {
+  console.error(`Unknown command: "${command}"\n`);
+  printHelp();
+  process.exit(1);
+}
+
+const VALID_PLATFORMS = ['claude-code', 'cursor', 'codex', 'antigravity'];
+const opts = { directory: process.cwd(), yes: false, securityHook: null, platforms: [] };
+
+for (let i = 1; i < args.length; i++) {
+  const a = args[i];
+  if ((a === '--directory' || a === '-d') && args[i + 1]) {
+    opts.directory = args[++i];
+  } else if (a === '--yes' || a === '-y') {
+    opts.yes = true;
+  } else if (a.startsWith('--security-hook=')) {
+    opts.securityHook = a.slice('--security-hook='.length).toLowerCase();
+  } else if (a === '--security-hook' && args[i + 1]) {
+    opts.securityHook = args[++i].toLowerCase();
+  } else if (a.startsWith('--platform=')) {
+    opts.platforms = a.slice('--platform='.length).split(',').map(s => s.trim().toLowerCase());
+  } else if (a === '--platform' && args[i + 1]) {
+    opts.platforms = args[++i].split(',').map(s => s.trim().toLowerCase());
+  }
+}
+
+if (opts.securityHook && !['husky', 'native', 'none'].includes(opts.securityHook)) {
+  console.error(`Invalid --security-hook value: "${opts.securityHook}"`);
+  console.error(`Expected one of: husky, native, none`);
+  process.exit(1);
+}
+
+const invalidPlatforms = opts.platforms.filter(p => !VALID_PLATFORMS.includes(p));
+if (invalidPlatforms.length > 0) {
+  console.error(`Invalid platform(s): ${invalidPlatforms.join(', ')}`);
+  console.error(`Valid platforms: ${VALID_PLATFORMS.join(', ')}`);
+  process.exit(1);
+}
+
+const runner = command === 'update' ? update : install;
+runner(opts).catch((err) => {
+  console.error(`\n${command === 'update' ? 'Update' : 'Install'} failed:`, err.message);
+  process.exit(1);
+});

package/lib/adapters/antigravity.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  exists, listFilesRecursive,
+  parseFrontmatter, extractDescription, extractCommandName, extractH1, yamlValue,
+} from './utils.js';
+
+export const PLATFORM_ID = 'antigravity';
+export const PLATFORM_LABEL = 'Antigravity';
+
+export async function install({ tasDir, target }) {
+  const agentsDir = path.join(target, '.agents');
+  await fs.mkdir(agentsDir, { recursive: true });
+  await fs.mkdir(path.join(agentsDir, 'rules'), { recursive: true });
+  await fs.mkdir(path.join(agentsDir, 'skills'), { recursive: true });
+
+  // commands → .agents/<name>.md (Antigravity workflows)
+  const commandsDir = path.join(tasDir, 'commands');
+  if (await exists(commandsDir)) {
+    const files = await listFilesRecursive(commandsDir, '.md');
+    for (const file of files) {
+      await commandToWorkflow(file, agentsDir);
+    }
+    console.log('  [ok] .agents/ (workflows from commands)');
+  }
+
+  // agents → .agents/skills/<name>/SKILL.md
+  const agentsSrc = path.join(tasDir, 'agents');
+  if (await exists(agentsSrc)) {
+    const files = await listFilesRecursive(agentsSrc, '.md');
+    for (const file of files) {
+      await agentToSkill(file, path.join(agentsDir, 'skills'));
+    }
+    console.log('  [ok] .agents/skills/ (agents)');
+  }
+
+  // kit skills → .agents/skills/ (copy as-is, same open standard)
+  const skillsSrc = path.join(tasDir, 'skills');
+  if (await exists(skillsSrc)) {
+    const skillDirs = await fs.readdir(skillsSrc, { withFileTypes: true });
+    for (const d of skillDirs.filter(e => e.isDirectory())) {
+      await fs.cp(
+        path.join(skillsSrc, d.name),
+        path.join(agentsDir, 'skills', d.name),
+        { recursive: true }
+      );
+    }
+    console.log('  [ok] .agents/skills/ (skills)');
+  }
+
+  // rules → .agents/rules/<stack>-<topic>.md
+  const rulesDir = path.join(tasDir, 'rules');
+  if (await exists(rulesDir)) {
+    await convertRules(rulesDir, path.join(agentsDir, 'rules'));
+    console.log('  [ok] .agents/rules/ (from .tas/rules/)');
+  }
+
+  // platform index (not root AGENTS.md — that's the template/system prompt)
+  await generateReadme(agentsDir);
+  console.log('  [ok] .agents/README.md');
+}
+
+async function commandToWorkflow(file, agentsDir) {
+  const content = await fs.readFile(file, 'utf8');
+  const name = extractCommandName(content) || path.basename(file, '.md');
+  // Antigravity workflows: same .md format, stored in .agents/<name>.md
+  await fs.writeFile(path.join(agentsDir, `${name}.md`), content);
+}
+
+async function agentToSkill(file, skillsDir) {
+  const content = await fs.readFile(file, 'utf8');
+  const { frontmatter, body } = parseFrontmatter(content);
+  const name = frontmatter.name || path.basename(file, '.md');
+  const description = frontmatter.description || extractDescription(body, name);
+  const skillDir = path.join(skillsDir, name);
+  await fs.mkdir(skillDir, { recursive: true });
+  // Antigravity SKILL.md: same open standard, drop allowed-tools (platform manages tool access)
+  const skillMd = `---\nname: ${yamlValue(name)}\ndescription: ${yamlValue(description)}\n---\n\n${body}`;
+  await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillMd);
+}
+
+async function convertRules(rulesDir, outDir) {
+  const entries = await fs.readdir(rulesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const stack = entry.name;
+      const files = await listFilesRecursive(path.join(rulesDir, stack), '.md');
+      for (const f of files) {
+        const topic = path.basename(f, '.md');
+        await fs.copyFile(f, path.join(outDir, `${stack}-${topic}.md`));
+      }
+    } else if (entry.name.endsWith('.md')) {
+      await fs.copyFile(path.join(rulesDir, entry.name), path.join(outDir, entry.name));
+    }
+  }
+}
+
+async function generateReadme(agentsDir) {
+  const workflowFiles = (await fs.readdir(agentsDir, { withFileTypes: true }))
+    .filter(e => e.isFile() && e.name.endsWith('.md'))
+    .map(e => `- \`/${e.name.replace('.md', '')}\``);
+
+  const skillDirs = await fs.readdir(path.join(agentsDir, 'skills'), { withFileTypes: true });
+  const skillLines = [];
+  for (const d of skillDirs.filter(e => e.isDirectory())) {
+    const skillFile = path.join(agentsDir, 'skills', d.name, 'SKILL.md');
+    if (!(await exists(skillFile))) continue;
+    const content = await fs.readFile(skillFile, 'utf8');
+    const { frontmatter } = parseFrontmatter(content);
+    if (frontmatter.name) {
+      skillLines.push(`- **${frontmatter.name}**: ${frontmatter.description || ''}`);
+    }
+  }
+
+  const readme = [
+    `# TAS Kit — Antigravity`,
+    ``,
+    `## Workflows`,
+    ``,
+    `Invoke via \`/workflow-name\` in chat:`,
+    ``,
+    ...workflowFiles,
+    ``,
+    `## Skills`,
+    ``,
+    ...skillLines,
+    ``,
+  ].join('\n');
+
+  await fs.writeFile(path.join(agentsDir, 'README.md'), readme);
+}

package/lib/adapters/claude-code.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { copyDir, exists } from './utils.js';
+
+export const PLATFORM_ID = 'claude-code';
+export const PLATFORM_LABEL = 'Claude Code';
+
+export async function install({ tasDir, target }) {
+  const claudeDir = path.join(target, '.claude');
+  await fs.mkdir(claudeDir, { recursive: true });
+
+  await copyDir(path.join(tasDir, 'commands'), path.join(claudeDir, 'commands'));
+  console.log('  [ok] .claude/commands/');
+
+  await copyDir(path.join(tasDir, 'agents'), path.join(claudeDir, 'agents'));
+  console.log('  [ok] .claude/agents/');
+
+  const skillsSrc = path.join(tasDir, 'skills');
+  if (await exists(skillsSrc)) {
+    await copyDir(skillsSrc, path.join(claudeDir, 'skills'));
+    console.log('  [ok] .claude/skills/');
+  }
+
+  const hooksSrc = path.join(tasDir, '_platform', 'hooks');
+  if (await exists(hooksSrc)) {
+    await copyDir(hooksSrc, path.join(claudeDir, 'hooks'));
+    console.log('  [ok] .claude/hooks/');
+  }
+
+  const settingsSrc = path.join(tasDir, '_platform', 'claude-code', 'settings.json');
+  if (await exists(settingsSrc)) {
+    await fs.copyFile(settingsSrc, path.join(claudeDir, 'settings.json'));
+    console.log('  [ok] .claude/settings.json');
+  }
+}

package/lib/adapters/codex.js

@@ -0,0 +1,157 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  exists, listFilesRecursive,
+  parseFrontmatter, extractDescription, extractCommandName, extractH1, yamlValue,
+} from './utils.js';
+
+export const PLATFORM_ID = 'codex';
+export const PLATFORM_LABEL = 'Codex';
+
+export async function install({ tasDir, target }) {
+  const codexDir = path.join(target, '.codex');
+  const skillsOut = path.join(codexDir, 'skills');
+  await fs.mkdir(skillsOut, { recursive: true });
+
+  // commands → skills
+  const commandsDir = path.join(tasDir, 'commands');
+  if (await exists(commandsDir)) {
+    const files = await listFilesRecursive(commandsDir, '.md');
+    for (const file of files) {
+      await commandToSkill(file, skillsOut);
+    }
+    console.log('  [ok] .codex/skills/ (commands)');
+  }
+
+  // agents → skills
+  const agentsDir = path.join(tasDir, 'agents');
+  if (await exists(agentsDir)) {
+    const files = await listFilesRecursive(agentsDir, '.md');
+    for (const file of files) {
+      await agentToSkill(file, skillsOut);
+    }
+    console.log('  [ok] .codex/skills/ (agents)');
+  }
+
+  // skills → skills (copy as-is, same format)
+  const skillsSrc = path.join(tasDir, 'skills');
+  if (await exists(skillsSrc)) {
+    const skillDirs = await fs.readdir(skillsSrc, { withFileTypes: true });
+    for (const d of skillDirs.filter(e => e.isDirectory())) {
+      const src = path.join(skillsSrc, d.name);
+      const dest = path.join(skillsOut, d.name);
+      await fs.cp(src, dest, { recursive: true });
+    }
+    console.log('  [ok] .codex/skills/ (skills)');
+  }
+
+  // rules → skills with references/
+  const rulesDir = path.join(tasDir, 'rules');
+  if (await exists(rulesDir)) {
+    await rulesToSkills(rulesDir, skillsOut);
+    console.log('  [ok] .codex/skills/ (rules)');
+  }
+
+  // platform index (not root AGENTS.md — that's the template/system prompt)
+  await generateReadme(skillsOut, codexDir);
+  console.log('  [ok] .codex/README.md');
+}
+
+async function commandToSkill(file, skillsOut) {
+  const content = await fs.readFile(file, 'utf8');
+  const name = extractCommandName(content) || path.basename(file, '.md');
+  const description = extractDescription(content, name);
+  const skillDir = path.join(skillsOut, name);
+  await fs.mkdir(skillDir, { recursive: true });
+  const skillMd = `---\nname: ${yamlValue(name)}\ndescription: ${yamlValue(description)}\n---\n\n${content}`;
+  await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillMd);
+}
+
+async function agentToSkill(file, skillsOut) {
+  const content = await fs.readFile(file, 'utf8');
+  const { frontmatter, body } = parseFrontmatter(content);
+  const name = frontmatter.name || path.basename(file, '.md');
+  const description = frontmatter.description || extractDescription(body, name);
+  const skillDir = path.join(skillsOut, name);
+  await fs.mkdir(skillDir, { recursive: true });
+  const skillMd = `---\nname: ${yamlValue(name)}\ndescription: ${yamlValue(description)}\n---\n\n${body}`;
+  await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillMd);
+}
+
+async function rulesToSkills(rulesDir, skillsOut) {
+  const stacks = await fs.readdir(rulesDir, { withFileTypes: true });
+  for (const entry of stacks) {
+    if (!entry.isDirectory() && !entry.name.endsWith('.md')) continue;
+
+    if (entry.isDirectory()) {
+      const stack = entry.name;
+      const stackDir = path.join(rulesDir, stack);
+      const files = await listFilesRecursive(stackDir, '.md');
+      if (files.length === 0) continue;
+
+      const skillName = `${stack}-rules`;
+      const skillDir = path.join(skillsOut, skillName);
+      const refsDir = path.join(skillDir, 'references');
+      await fs.mkdir(refsDir, { recursive: true });
+
+      const refList = [];
+      for (const f of files) {
+        const dest = path.join(refsDir, path.basename(f));
+        await fs.copyFile(f, dest);
+        refList.push(`- ${path.basename(f, '.md')}`);
+      }
+
+      const skillMd = [
+        `---`,
+        `name: ${yamlValue(skillName)}`,
+        `description: ${yamlValue(`${stack} coding standards, patterns and security rules`)}`,
+        `---`,
+        ``,
+        `# ${stack} Rules`,
+        ``,
+        `References (loaded on demand):`,
+        ...refList,
+      ].join('\n') + '\n';
+      await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillMd);
+    } else {
+      // top-level .md file (e.g. ado-integration.md)
+      const file = path.join(rulesDir, entry.name);
+      const content = await fs.readFile(file, 'utf8');
+      const name = path.basename(entry.name, '.md') + '-rules';
+      const skillDir = path.join(skillsOut, name);
+      const refsDir = path.join(skillDir, 'references');
+      await fs.mkdir(refsDir, { recursive: true });
+      await fs.copyFile(file, path.join(refsDir, entry.name));
+      const title = extractH1(content) || name;
+      const skillMd = `---\nname: ${yamlValue(name)}\ndescription: ${yamlValue(title)}\n---\n\n# ${title}\n\nSee references/${entry.name}\n`;
+      await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillMd);
+    }
+  }
+}
+
+async function generateReadme(skillsOut, codexDir) {
+  const skillDirs = await fs.readdir(skillsOut, { withFileTypes: true });
+  const skillLines = [];
+  for (const d of skillDirs.filter(e => e.isDirectory())) {
+    const skillFile = path.join(skillsOut, d.name, 'SKILL.md');
+    if (!(await exists(skillFile))) continue;
+    const content = await fs.readFile(skillFile, 'utf8');
+    const { frontmatter } = parseFrontmatter(content);
+    if (frontmatter.name) {
+      skillLines.push(`- **${frontmatter.name}**: ${frontmatter.description || ''}`);
+    }
+  }
+
+  const readme = [
+    `# TAS Kit — Codex`,
+    ``,
+    `## Available Skills`,
+    ``,
+    `Use \`/skills\` to list and invoke skills:`,
+    ``,
+    ...skillLines,
+    ``,
+  ].join('\n');
+
+  await fs.writeFile(path.join(codexDir, 'README.md'), readme);
+}

package/lib/adapters/cursor.js

@@ -0,0 +1,80 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { copyDir, exists, listFilesRecursive, extractH1, yamlValue } from './utils.js';
+
+export const PLATFORM_ID = 'cursor';
+export const PLATFORM_LABEL = 'Cursor';
+
+const HOOKS_JSON = {
+  postToolUse: [
+    {
+      matcher: '^(Write|Edit|MultiEdit)$',
+      hooks: [
+        {
+          type: 'command',
+          command: 'node .tas/_platform/hooks/code-quality.js',
+          description: 'Auto format source files: prettier (TS/JS), ruff/black (Python), dotnet format (C#)',
+        },
+      ],
+    },
+  ],
+  agentLoopEnd: [
+    {
+      hooks: [
+        {
+          type: 'command',
+          command: 'node .tas/_platform/hooks/session-end.js',
+          description: 'Run test suite, check project-status.yaml updated, remind next steps',
+        },
+      ],
+    },
+  ],
+};
+
+export async function install({ tasDir, target }) {
+  const cursorDir = path.join(target, '.cursor');
+  await fs.mkdir(cursorDir, { recursive: true });
+
+  // commands — same format as Claude Code
+  await copyDir(path.join(tasDir, 'commands'), path.join(cursorDir, 'commands'));
+  console.log('  [ok] .cursor/commands/');
+
+  // agents — identical frontmatter format
+  await copyDir(path.join(tasDir, 'agents'), path.join(cursorDir, 'agents'));
+  console.log('  [ok] .cursor/agents/');
+
+  // skills — same open standard
+  const skillsSrc = path.join(tasDir, 'skills');
+  if (await exists(skillsSrc)) {
+    await copyDir(skillsSrc, path.join(cursorDir, 'skills'));
+    console.log('  [ok] .cursor/skills/');
+  }
+
+  // rules → .mdc files with frontmatter
+  const rulesDir = path.join(tasDir, 'rules');
+  const rulesOut = path.join(cursorDir, 'rules');
+  await fs.mkdir(rulesOut, { recursive: true });
+  await convertRulesToMdc(rulesDir, rulesOut);
+  console.log('  [ok] .cursor/rules/ (converted from .tas/rules/)');
+
+  // hooks.json
+  await fs.writeFile(
+    path.join(cursorDir, 'hooks.json'),
+    JSON.stringify(HOOKS_JSON, null, 2) + '\n'
+  );
+  console.log('  [ok] .cursor/hooks.json');
+}
+
+async function convertRulesToMdc(rulesDir, outDir) {
+  if (!(await exists(rulesDir))) return;
+  const files = await listFilesRecursive(rulesDir, '.md');
+  for (const file of files) {
+    const rel = path.relative(rulesDir, file);
+    // flatten: common/code-review.md → common-code-review.mdc
+    const flatName = rel.replace(/[\\/]/g, '-').replace(/\.md$/, '.mdc');
+    const content = await fs.readFile(file, 'utf8');
+    const title = extractH1(content) || path.basename(file, '.md');
+    const mdc = `---\ndescription: ${yamlValue(title)}\nalwaysApply: false\n---\n\n${content}`;
+    await fs.writeFile(path.join(outDir, flatName), mdc);
+  }
+}

package/lib/adapters/index.js

@@ -0,0 +1,20 @@
+export { PLATFORM_ID as CLAUDE_CODE, install as installClaudeCode } from './claude-code.js';
+export { PLATFORM_ID as CURSOR, install as installCursor } from './cursor.js';
+export { PLATFORM_ID as CODEX, install as installCodex } from './codex.js';
+export { PLATFORM_ID as ANTIGRAVITY, install as installAntigravity } from './antigravity.js';
+
+import * as claudeCode from './claude-code.js';
+import * as cursor from './cursor.js';
+import * as codex from './codex.js';
+import * as antigravity from './antigravity.js';
+
+export const PLATFORMS = [
+  { id: claudeCode.PLATFORM_ID, label: claudeCode.PLATFORM_LABEL, install: claudeCode.install },
+  { id: cursor.PLATFORM_ID,     label: cursor.PLATFORM_LABEL,     install: cursor.install },
+  { id: codex.PLATFORM_ID,      label: codex.PLATFORM_LABEL,      install: codex.install },
+  { id: antigravity.PLATFORM_ID, label: antigravity.PLATFORM_LABEL, install: antigravity.install },
+];
+
+export function getPlatform(id) {
+  return PLATFORMS.find(p => p.id === id);
+}

package/lib/adapters/utils.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function exists(p) {
+  return fs.access(p).then(() => true).catch(() => false);
+}
+
+export async function copyDir(src, dest) {
+  await fs.cp(src, dest, { recursive: true });
+}
+
+export async function listFilesRecursive(dir, ext = '') {
+  const results = [];
+  async function walk(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const e of entries) {
+      const full = path.join(current, e.name);
+      if (e.isDirectory()) await walk(full);
+      else if (!ext || e.name.endsWith(ext)) results.push(full);
+    }
+  }
+  await walk(dir);
+  return results;
+}
+
+export function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return { frontmatter: {}, body: content };
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return { frontmatter: {}, body: content };
+  const yaml = content.slice(4, end);
+  const body = content.slice(end + 4).trimStart();
+  const frontmatter = {};
+  for (const line of yaml.split('\n')) {
+    const colon = line.indexOf(':');
+    if (colon > 0) {
+      const key = line.slice(0, colon).trim();
+      let val = line.slice(colon + 1).trim();
+      // handle multiline: only single-line values here
+      val = val.replace(/^["']|["']$/g, '');
+      frontmatter[key] = val;
+    }
+  }
+  return { frontmatter, body };
+}
+
+// Extract description: first non-empty, non-heading line after the H1
+export function extractDescription(content, fallback = '') {
+  const lines = content.split('\n');
+  let pastH1 = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!pastH1) {
+      if (trimmed.startsWith('# ')) pastH1 = true;
+      continue;
+    }
+    if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('|') && !trimmed.startsWith('-')) {
+      return trimmed.replace(/^Role:\s*/i, '').replace(/\*\*/g, '').slice(0, 150);
+    }
+  }
+  return fallback;
+}
+
+// Extract H1 title from markdown
+export function extractH1(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : '';
+}
+
+// Extract command name from first line: "# /tas-dev $ARGUMENTS" → "tas-dev"
+export function extractCommandName(content) {
+  const match = content.match(/^#\s+\/(\S+)/);
+  return match ? match[1] : '';
+}
+
+// Escape a string for use in YAML frontmatter value (single-line)
+export function yamlValue(str) {
+  if (/[:#\[\]{},|>&*!'"\\]/.test(str) || str.includes('\n')) {
+    return `"${str.replace(/"/g, '\\"')}"`;
+  }
+  return str;
+}