thachvd-kit 1.0.36 → 1.0.37

package/bin/cli.js

@@ -1,1735 +1,1785 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const prompts = require('prompts');
-const pc = require('picocolors');
-const packageJson = require('../package.json');
-const mattSkills = require('./matt-skills');
-const {
-    QUALITY_FLOOR_SECTION,
-    AGENT_RULES_SECTION,
-    CONVENTIONS_STANDARDS_SECTION,
-    FAST_PATH_SECTION,
-    GETTING_STARTED_FAST_PATH_SECTION,
-    TOOL_ROUTING_SECTION
-} = require('./policy');
-
-const sourceDir = path.resolve(__dirname, '..');
-const targetDir = process.cwd();
-const CODEBASE_MEMORY_PACKAGE = 'codebase-memory-mcp';
-const CODEBASE_MEMORY_BINARY = 'codebase-memory-mcp';
-const RTK_INSTALL_COMMAND = 'cargo install --git https://github.com/rtk-ai/rtk --branch master rtk';
-
-const FRAMEWORK_CHOICES = [
-    'vue', 'react', 'next', 'nuxt', 'svelte', 'angular',
-    'laravel', 'cakephp', 'symfony', 'codeigniter',
-    'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs',
-    'rails', 'spring', 'aspnet',
-    'tauri', 'axum', 'actix', 'flutter', 'react-native'
-];
-
-const LANGUAGE_CHOICES = ['typescript', 'javascript', 'python', 'go', 'php', 'rust', 'java', 'ruby', 'swift', 'kotlin', 'csharp', 'cpp'];
-const PROJECT_TYPE_CHOICES = ['web-app', 'api', 'mobile', 'desktop', 'cli', 'fullstack'];
-const DATABASE_CHOICES = ['postgres', 'mysql', 'sqlite', 'mongodb', 'redis', 'dynamodb', 'none'];
-const PACKAGE_MANAGER_CHOICES = ['npm', 'pnpm', 'yarn', 'bun', 'pip', 'uv', 'go mod', 'cargo', 'composer', 'auto-detect'];
-const TEST_FRAMEWORK_CHOICES = ['jest', 'vitest', 'pytest', 'go test', 'phpunit', 'pest', 'rspec', 'junit', 'auto-detect'];
-const CLOUD_CHOICES = ['aws', 'gcp', 'azure', 'vercel', 'fly', 'railway', 'none'];
-const FRONTEND_FRAMEWORKS = ['vue', 'react', 'next', 'nuxt', 'svelte', 'angular'];
-const BACKEND_FRAMEWORKS = ['laravel', 'cakephp', 'symfony', 'codeigniter', 'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs', 'rails', 'spring', 'aspnet', 'axum', 'actix'];
-const MOBILE_DESKTOP_FRAMEWORKS = ['tauri', 'flutter', 'react-native'];
-const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'build', 'coverage', '.next', '.nuxt', '.turbo', '.cache', 'storage', 'tmp']);
-
-function printHelp() {
-    console.log(`
-${pc.bold('Usage:')}
-  thachvd-kit init [--yes]
-  thachvd-kit upgrade [--dry-run]
-  thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
-  thachvd-kit setup [--yes] [--no-install-skills]
-  thachvd-kit doctor
-  thachvd-kit prompt
-  thachvd-kit skills install [--dry-run]
-  thachvd-kit skills check
-  thachvd-kit skills update [--dry-run]
-  thachvd-kit --version
-  thachvd-kit --help
-
-${pc.bold('Commands:')}
-  init      Generate project context files and documentation (new projects)
-  upgrade   Safely add/update thachvd-kit's managed policy blocks in an existing project (does not rescan or regenerate)
-  global    Patch a managed tool-routing block into the current user's Antigravity/Codex global instructions
-  setup     Install/configure MCP, Matt Pocock skills, and recommended local tooling
-  doctor    Check project context and local integrations
-  prompt    Print the saved project-indexing prompt again
-  skills    Install, check, or update the promoted Matt Pocock skill set
-
-${pc.bold('Options:')}
-  --yes     Overwrite generated files or accept setup defaults
-  --no-setup-mcp  Skip MCP setup (legacy init compatibility)
-  --no-setup-hook Skip the Claude Code Definition-of-Done Stop hook during setup
-  --no-install-rtk Skip auto-installing rtk via cargo during setup
-  --no-index      Skip auto-indexing the repository with codebase-memory-mcp during setup
-  --no-install-skills Skip installing Matt Pocock skills during setup
-  --dry-run Preview a change without writing it (upgrade/global/skills install/skills update)
-  --antigravity-only Limit global to the Antigravity global instructions
-  --codex-only    Limit global to the Codex global instructions
-  --version Show the installed CLI version
-  --help    Show this help message
-
-${pc.bold('What gets generated:')}
-  AGENTS.md   Shared instructions for Codex, Antigravity, Claude Code, and Cursor
-  CLAUDE.md   Claude Code entry file that imports AGENTS.md
-  GEMINI.md   Antigravity entry file that points to AGENTS.md
-  .cursorrules Cursor entry file that points to AGENTS.md
-  .agent/docs/ Project context, architecture, workflow, tooling, and durable onboarding prompt
-
-${pc.bold('Workflow:')}
-  Matt Pocock's promoted skills (installed under .agents/skills/) are the
-  workflow layer. Use the matching skill when a specialized workflow is
-  useful; if unsure which one, use /ask-matt. Do not invoke a heavyweight
-  skill for a localized, obvious change.
-
-${pc.bold('Tip:')}
-  Run thachvd-kit setup to install the promoted skill set and configure
-  local tooling, then thachvd-kit doctor to verify the machine.
-`);
-}
-
-function formatScanPreviewLines(scanned) {
-    return [
-        ['App root', scanned.app_root || '.'],
-        ['Project type', scanned.project_type || 'unknown'],
-        ['Primary language', scanned.primary_language || 'unknown'],
-        ['Frameworks', (scanned.frameworks || []).join(', ') || 'no framework'],
-        ['Database', scanned.database || 'none'],
-        ['Package manager', scanned.package_manager || 'auto-detect'],
-        ['Test framework', scanned.test_framework || 'auto-detect'],
-        ['Cloud', scanned.cloud || 'none'],
-        ['Infrastructure', (scanned.infrastructure || []).join(', ') || 'none'],
-        ['CI/CD', scanned.ci_cd || 'none']
-    ];
-}
-
-async function askQuestions(questions) {
-    return prompts(questions, {
-        onCancel: () => {
-            console.log(pc.yellow('\nCancelled.'));
-            process.exit(130);
-        }
-    });
-}
-
-function fileExists(...parts) {
-    return fs.existsSync(path.join(targetDir, ...parts));
-}
-
-function fileExistsAt(baseDir, ...parts) {
-    return fs.existsSync(path.join(baseDir, ...parts));
-}
-
-function readJsonIfExists(...parts) {
-    const fullPath = path.join(targetDir, ...parts);
-    if (!fs.existsSync(fullPath)) return null;
-    try {
-        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-    } catch {
-        return null;
-    }
-}
-
-function readJsonIfExistsAt(baseDir, ...parts) {
-    const fullPath = path.join(baseDir, ...parts);
-    if (!fs.existsSync(fullPath)) return null;
-    try {
-        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-    } catch {
-        return null;
-    }
-}
-
-function readTextIfExists(...parts) {
-    const fullPath = path.join(targetDir, ...parts);
-    if (!fs.existsSync(fullPath)) return '';
-    try {
-        return fs.readFileSync(fullPath, 'utf8');
-    } catch {
-        return '';
-    }
-}
-
-function readTextIfExistsAt(baseDir, ...parts) {
-    const fullPath = path.join(baseDir, ...parts);
-    if (!fs.existsSync(fullPath)) return '';
-    try {
-        return fs.readFileSync(fullPath, 'utf8');
-    } catch {
-        return '';
-    }
-}
-
-function detectPackageManager(baseDir = targetDir) {
-    if (fileExistsAt(baseDir, 'pnpm-lock.yaml')) return 'pnpm';
-    if (fileExistsAt(baseDir, 'yarn.lock')) return 'yarn';
-    if (fileExistsAt(baseDir, 'bun.lockb') || fileExistsAt(baseDir, 'bun.lock')) return 'bun';
-    if (fileExistsAt(baseDir, 'package-lock.json')) return 'npm';
-    if (fileExistsAt(baseDir, 'uv.lock')) return 'uv';
-    if (fileExistsAt(baseDir, 'poetry.lock')) return 'pip';
-    if (fileExistsAt(baseDir, 'requirements.txt') || fileExistsAt(baseDir, 'pyproject.toml')) return 'pip';
-    if (fileExistsAt(baseDir, 'go.mod')) return 'go mod';
-    if (fileExistsAt(baseDir, 'Cargo.toml')) return 'cargo';
-    if (fileExistsAt(baseDir, 'composer.json')) return 'composer';
-    return 'auto-detect';
-}
-
-function uniq(values) {
-    return Array.from(new Set(values.filter(Boolean)));
-}
-
-function detectAppRoot(baseDir) {
-    const candidates = [baseDir];
-    const queue = [{ dir: baseDir, depth: 0 }];
-
-    while (queue.length > 0) {
-        const { dir, depth } = queue.shift();
-        if (depth >= 2) continue;
-        let entries = [];
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        } catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory()) continue;
-            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
-            const nextDir = path.join(dir, entry.name);
-            candidates.push(nextDir);
-            queue.push({ dir: nextDir, depth: depth + 1 });
-        }
-    }
-
-    const scoreCandidate = dir => {
-        let score = 0;
-        if (fileExistsAt(dir, 'composer.json')) score += 5;
-        if (fileExistsAt(dir, 'package.json')) score += 4;
-        if (fileExistsAt(dir, 'Cargo.toml')) score += 4;
-        if (fileExistsAt(dir, 'go.mod')) score += 4;
-        if (fileExistsAt(dir, 'pyproject.toml') || fileExistsAt(dir, 'requirements.txt')) score += 4;
-        if (fileExistsAt(dir, 'artisan')) score += 5;
-        if (fileExistsAt(dir, 'bin', 'cake') || fileExistsAt(dir, 'app', 'Config', 'core.php')) score += 5;
-        if (fileExistsAt(dir, 'src-tauri', 'tauri.conf.json') || fileExistsAt(dir, 'src-tauri', 'tauri.conf.json5')) score += 5;
-        if (fileExistsAt(dir, 'manage.py')) score += 4;
-        if (fileExistsAt(dir, 'Gemfile')) score += 4;
-        if (fileExistsAt(dir, 'pom.xml') || fileExistsAt(dir, 'build.gradle') || fileExistsAt(dir, 'build.gradle.kts')) score += 4;
-        if (fileExistsAt(dir, 'app', 'View') || fileExistsAt(dir, 'resources', 'views') || fileExistsAt(dir, 'templates') || fileExistsAt(dir, 'app', 'views')) score += 2;
-        return score;
-    };
-
-    const ranked = candidates
-        .map(dir => ({ dir, score: scoreCandidate(dir) }))
-        .filter(item => item.score > 0)
-        .sort((a, b) => (b.score - a.score) || (a.dir.length - b.dir.length));
-
-    return ranked[0]?.dir || baseDir;
-}
-
-function repoHasAny(baseDir, relativePaths, maxDepth = 3) {
-    const queue = [{ dir: baseDir, depth: 0 }];
-    while (queue.length > 0) {
-        const { dir, depth } = queue.shift();
-        for (const relativePath of relativePaths) {
-            if (fileExistsAt(dir, ...relativePath)) return true;
-        }
-        if (depth >= maxDepth) continue;
-        let entries = [];
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        } catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory()) continue;
-            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
-            queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
-        }
-    }
-    return false;
-}
-
-function evidenceIf(condition, label, weight = 1) {
-    return condition ? { label, weight } : null;
-}
-
-function buildDetection(id, evidence, meta = {}) {
-    const hits = evidence.filter(Boolean);
-    const score = hits.reduce((sum, hit) => sum + hit.weight, 0);
-    return {
-        id,
-        score,
-        evidence: hits.map(hit => hit.label),
-        ...meta
-    };
-}
-
-function confidenceLabel(score) {
-    if (score >= 6) return 'high';
-    if (score >= 3) return 'medium';
-    return 'low';
-}
-
-function hasDependency(depNames, ...names) {
-    return names.some(name => depNames.has(name));
-}
-
-function hasComposerDependency(composerDepNames, ...names) {
-    return names.some(name => composerDepNames.has(name));
-}
-
-function hasRootFile(rootEntries, ...filenames) {
-    return filenames.some(name => rootEntries.has(name));
-}
-
-function textMatches(text, pattern) {
-    return Boolean(text && pattern.test(text));
-}
-
-const LANGUAGE_DETECTORS = [
-    {
-        id: 'typescript',
-        detect: ctx => buildDetection('typescript', [
-            evidenceIf(ctx.fileExists('tsconfig.json'), 'found tsconfig.json', 4),
-            evidenceIf(hasDependency(ctx.depNames, 'typescript', 'ts-node', 'tsx'), 'package.json -> typescript toolchain', 2)
-        ])
-    },
-    {
-        id: 'javascript',
-        detect: ctx => buildDetection('javascript', [
-            evidenceIf(ctx.fileExists('package.json'), 'found package.json', 2),
-            evidenceIf(ctx.depNames.size > 0, 'package.json -> JavaScript dependency graph', 1)
-        ])
-    },
-    {
-        id: 'python',
-        detect: ctx => buildDetection('python', [
-            evidenceIf(ctx.fileExists('requirements.txt'), 'found requirements.txt', 3),
-            evidenceIf(ctx.fileExists('pyproject.toml'), 'found pyproject.toml', 2),
-            evidenceIf(textMatches(ctx.pyprojectText, /\[tool\.(poetry|uv|hatch|pdm)\]/i), 'pyproject.toml -> Python tool section', 2)
-        ])
-    },
-    {
-        id: 'go',
-        detect: ctx => buildDetection('go', [
-            evidenceIf(ctx.fileExists('go.mod'), 'found go.mod', 4)
-        ])
-    },
-    {
-        id: 'php',
-        detect: ctx => buildDetection('php', [
-            evidenceIf(ctx.fileExists('composer.json'), 'found composer.json', 4),
-            evidenceIf(ctx.composerDepNames.size > 0, 'composer.json -> PHP dependency graph', 1)
-        ])
-    },
-    {
-        id: 'rust',
-        detect: ctx => buildDetection('rust', [
-            evidenceIf(ctx.fileExists('Cargo.toml'), 'found Cargo.toml', 4),
-            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 5)
-        ])
-    },
-    {
-        id: 'java',
-        detect: ctx => buildDetection('java', [
-            evidenceIf(ctx.fileExists('pom.xml'), 'found pom.xml', 4),
-            evidenceIf(ctx.fileExists('build.gradle') || ctx.fileExists('build.gradle.kts'), 'found Gradle build file', 3)
-        ])
-    },
-    {
-        id: 'ruby',
-        detect: ctx => buildDetection('ruby', [
-            evidenceIf(ctx.fileExists('Gemfile'), 'found Gemfile', 4),
-            evidenceIf(ctx.fileExists('config.ru'), 'found config.ru', 1)
-        ])
-    },
-    {
-        id: 'csharp',
-        detect: ctx => buildDetection('csharp', [
-            evidenceIf(ctx.rootEntries.some(name => name.endsWith('.sln') || name.endsWith('.csproj')), 'found .sln/.csproj', 4),
-            evidenceIf(ctx.fileExists('Program.cs'), 'found Program.cs', 1)
-        ])
-    }
-];
-
-const FRAMEWORK_DETECTORS = [
-    {
-        id: 'next',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('next', [
-            evidenceIf(hasDependency(ctx.depNames, 'next'), 'package.json -> next', 4),
-            evidenceIf(ctx.fileExists('next.config.js') || ctx.fileExists('next.config.mjs') || ctx.fileExists('next.config.ts'), 'found next.config.*', 3),
-            evidenceIf(ctx.fileExists('app') || ctx.fileExists('pages'), 'found app/ or pages/', 1)
-        ])
-    },
-    {
-        id: 'react',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('react', [
-            evidenceIf(hasDependency(ctx.depNames, 'react'), 'package.json -> react', 4),
-            evidenceIf(hasDependency(ctx.depNames, 'react-dom'), 'package.json -> react-dom', 2)
-        ])
-    },
-    {
-        id: 'vue',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('vue', [
-            evidenceIf(hasDependency(ctx.depNames, 'vue'), 'package.json -> vue', 4)
-        ])
-    },
-    {
-        id: 'nuxt',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('nuxt', [
-            evidenceIf(hasDependency(ctx.depNames, 'nuxt'), 'package.json -> nuxt', 4),
-            evidenceIf(ctx.fileExists('nuxt.config.ts') || ctx.fileExists('nuxt.config.js'), 'found nuxt.config.*', 3)
-        ])
-    },
-    {
-        id: 'svelte',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('svelte', [
-            evidenceIf(hasDependency(ctx.depNames, 'svelte', '@sveltejs/kit'), 'package.json -> svelte', 4)
-        ])
-    },
-    {
-        id: 'angular',
-        kind: 'frontend',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('angular', [
-            evidenceIf(hasDependency(ctx.depNames, '@angular/core'), 'package.json -> @angular/core', 4),
-            evidenceIf(ctx.fileExists('angular.json'), 'found angular.json', 3)
-        ])
-    },
-    {
-        id: 'express',
-        kind: 'backend',
-        language: 'javascript',
-        projectType: 'api',
-        detect: ctx => buildDetection('express', [
-            evidenceIf(hasDependency(ctx.depNames, 'express'), 'package.json -> express', 4)
-        ])
-    },
-    {
-        id: 'nestjs',
-        kind: 'backend',
-        language: 'javascript',
-        projectType: 'api',
-        detect: ctx => buildDetection('nestjs', [
-            evidenceIf(hasDependency(ctx.depNames, '@nestjs/core'), 'package.json -> @nestjs/core', 4)
-        ])
-    },
-    {
-        id: 'fastapi',
-        kind: 'backend',
-        language: 'python',
-        projectType: 'api',
-        detect: ctx => buildDetection('fastapi', [
-            evidenceIf(textMatches(ctx.requirementsText, /\bfastapi\b/i) || textMatches(ctx.pyprojectText, /\bfastapi\b/i), 'Python deps -> fastapi', 4)
-        ])
-    },
-    {
-        id: 'django',
-        kind: 'backend',
-        language: 'python',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('django', [
-            evidenceIf(textMatches(ctx.requirementsText, /\bdjango\b/i) || textMatches(ctx.pyprojectText, /\bdjango\b/i), 'Python deps -> django', 4),
-            evidenceIf(ctx.fileExists('manage.py'), 'found manage.py', 2),
-            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
-        ])
-    },
-    {
-        id: 'flask',
-        kind: 'backend',
-        language: 'python',
-        projectType: 'api',
-        detect: ctx => buildDetection('flask', [
-            evidenceIf(textMatches(ctx.requirementsText, /\bflask\b/i) || textMatches(ctx.pyprojectText, /\bflask\b/i), 'Python deps -> flask', 4)
-        ])
-    },
-    {
-        id: 'laravel',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('laravel', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'laravel/framework'), 'composer.json -> laravel/framework', 4),
-            evidenceIf(ctx.fileExists('artisan'), 'found artisan', 3),
-            evidenceIf(ctx.fileExists('resources', 'views'), 'found resources/views', 1)
-        ])
-    },
-    {
-        id: 'cakephp',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('cakephp', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'cakephp/cakephp'), 'composer.json -> cakephp/cakephp', 4),
-            evidenceIf(ctx.fileExists('bin', 'cake'), 'found bin/cake', 3),
-            evidenceIf(ctx.fileExists('config', 'app.php'), 'found config/app.php', 2),
-            evidenceIf(ctx.fileExists('app', 'Config', 'core.php'), 'found app/Config/core.php (CakePHP legacy)', 3),
-            evidenceIf(ctx.fileExists('app', 'Controller', 'AppController.php'), 'found app/Controller/AppController.php', 2),
-            evidenceIf(ctx.fileExists('app', 'Model', 'AppModel.php'), 'found app/Model/AppModel.php', 2),
-            evidenceIf(ctx.fileExists('lib', 'Cake'), 'found lib/Cake', 3),
-            evidenceIf(ctx.fileExists('cake', 'console', 'cake'), 'found cake/console/cake', 3),
-            evidenceIf(ctx.fileExists('app', 'View'), 'found app/View', 2),
-            evidenceIf(textMatches(ctx.viewFilesText, /\.ctp$/im), 'found .ctp view templates', 2)
-        ])
-    },
-    {
-        id: 'symfony',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('symfony', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'symfony/framework-bundle'), 'composer.json -> symfony/framework-bundle', 4),
-            evidenceIf(ctx.fileExists('bin', 'console'), 'found bin/console', 2),
-            evidenceIf(ctx.fileExists('config', 'bundles.php'), 'found config/bundles.php', 1),
-            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
-        ])
-    },
-    {
-        id: 'codeigniter',
-        kind: 'backend',
-        language: 'php',
-        projectType: 'api',
-        detect: ctx => buildDetection('codeigniter', [
-            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'codeigniter4/framework'), 'composer.json -> codeigniter4/framework', 4),
-            evidenceIf(ctx.fileExists('spark'), 'found spark', 2),
-            evidenceIf(ctx.fileExists('app', 'Config', 'App.php'), 'found app/Config/App.php', 1)
-        ])
-    },
-    {
-        id: 'gin',
-        kind: 'backend',
-        language: 'go',
-        projectType: 'api',
-        detect: ctx => buildDetection('gin', [
-            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gin-gonic\/gin\b/i), 'go.mod -> github.com/gin-gonic/gin', 4)
-        ])
-    },
-    {
-        id: 'fiber',
-        kind: 'backend',
-        language: 'go',
-        projectType: 'api',
-        detect: ctx => buildDetection('fiber', [
-            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gofiber\/fiber\b/i), 'go.mod -> github.com/gofiber/fiber', 4)
-        ])
-    },
-    {
-        id: 'echo',
-        kind: 'backend',
-        language: 'go',
-        projectType: 'api',
-        detect: ctx => buildDetection('echo', [
-            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/labstack\/echo\b/i), 'go.mod -> github.com/labstack/echo', 4)
-        ])
-    },
-    {
-        id: 'rails',
-        kind: 'backend',
-        language: 'ruby',
-        projectType: 'web-app',
-        detect: ctx => buildDetection('rails', [
-            evidenceIf(textMatches(ctx.gemfileText, /^\s*gem\s+["']rails["']/im), 'Gemfile -> rails', 4),
-            evidenceIf(ctx.fileExists('bin', 'rails'), 'found bin/rails', 2),
-            evidenceIf(ctx.fileExists('app', 'views'), 'found app/views', 1)
-        ])
-    },
-    {
-        id: 'spring',
-        kind: 'backend',
-        language: 'java',
-        projectType: 'api',
-        detect: ctx => buildDetection('spring', [
-            evidenceIf(textMatches(ctx.pomText, /spring-boot/i) || textMatches(ctx.gradleText, /spring-boot/i), 'Java build -> spring-boot', 4)
-        ])
-    },
-    {
-        id: 'aspnet',
-        kind: 'backend',
-        language: 'csharp',
-        projectType: 'api',
-        detect: ctx => buildDetection('aspnet', [
-            evidenceIf(textMatches(ctx.csprojText, /Microsoft\.NET\.Sdk\.Web/i), '.csproj -> Microsoft.NET.Sdk.Web', 4),
-            evidenceIf(textMatches(ctx.programCsText, /WebApplication\.CreateBuilder/i), 'Program.cs -> WebApplication.CreateBuilder', 2)
-        ])
-    },
-    {
-        id: 'tauri',
-        kind: 'desktop',
-        language: 'rust',
-        projectType: 'desktop',
-        detect: ctx => buildDetection('tauri', [
-            evidenceIf(hasDependency(ctx.depNames, '@tauri-apps/api'), 'package.json -> @tauri-apps/api', 4),
-            evidenceIf(ctx.fileExists('src-tauri', 'tauri.conf.json') || ctx.fileExists('src-tauri', 'tauri.conf.json5'), 'found src-tauri/tauri.conf.*', 4),
-            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 2)
-        ])
-    },
-    {
-        id: 'axum',
-        kind: 'backend',
-        language: 'rust',
-        projectType: 'api',
-        detect: ctx => buildDetection('axum', [
-            evidenceIf(textMatches(ctx.cargoText, /\baxum\b/i), 'Cargo.toml -> axum', 4)
-        ])
-    },
-    {
-        id: 'actix',
-        kind: 'backend',
-        language: 'rust',
-        projectType: 'api',
-        detect: ctx => buildDetection('actix', [
-            evidenceIf(textMatches(ctx.cargoText, /\bactix-web\b/i), 'Cargo.toml -> actix-web', 4)
-        ])
-    },
-    {
-        id: 'flutter',
-        kind: 'mobile',
-        projectType: 'mobile',
-        detect: ctx => buildDetection('flutter', [
-            evidenceIf(textMatches(ctx.pubspecText, /^\s*flutter\s*:/im), 'pubspec.yaml -> flutter', 4)
-        ])
-    },
-    {
-        id: 'react-native',
-        kind: 'mobile',
-        projectType: 'mobile',
-        detect: ctx => buildDetection('react-native', [
-            evidenceIf(hasDependency(ctx.depNames, 'react-native', 'expo'), 'package.json -> react-native/expo', 4)
-        ])
-    }
-];
-
-function scanProject() {
-    const appRoot = detectAppRoot(targetDir);
-    const pkg = readJsonIfExistsAt(appRoot, 'package.json') || {};
-    const composer = readJsonIfExistsAt(appRoot, 'composer.json') || {};
-    const rootEntries = fs.existsSync(appRoot) ? fs.readdirSync(appRoot) : [];
-    const rootCsproj = rootEntries.find(name => name.endsWith('.csproj')) || '';
-    const deps = {
-        ...(pkg.dependencies || {}),
-        ...(pkg.devDependencies || {}),
-        ...(pkg.peerDependencies || {})
-    };
-    const depNames = new Set(Object.keys(deps));
-    const composerDeps = {
-        ...(composer.require || {}),
-        ...(composer['require-dev'] || {})
-    };
-    const composerDepNames = new Set(Object.keys(composerDeps));
-    const ctx = {
-        pkg,
-        composer,
-        depNames,
-        composerDepNames,
-        rootEntries,
-        fileExists: (...parts) => fileExistsAt(appRoot, ...parts),
-        requirementsText: readTextIfExistsAt(appRoot, 'requirements.txt'),
-        pyprojectText: readTextIfExistsAt(appRoot, 'pyproject.toml'),
-        goModText: readTextIfExistsAt(appRoot, 'go.mod'),
-        pubspecText: readTextIfExistsAt(appRoot, 'pubspec.yaml'),
-        gemfileText: readTextIfExistsAt(appRoot, 'Gemfile'),
-        pomText: readTextIfExistsAt(appRoot, 'pom.xml'),
-        gradleText: `${readTextIfExistsAt(appRoot, 'build.gradle')}\n${readTextIfExistsAt(appRoot, 'build.gradle.kts')}`,
-        cargoText: `${readTextIfExistsAt(appRoot, 'Cargo.toml')}\n${readTextIfExistsAt(appRoot, 'src-tauri', 'Cargo.toml')}`,
-        csprojText: rootCsproj ? readTextIfExistsAt(appRoot, rootCsproj) : '',
-        programCsText: readTextIfExistsAt(appRoot, 'Program.cs'),
-        viewFilesText: fs.existsSync(path.join(appRoot, 'app', 'View'))
-            ? fs.readdirSync(path.join(appRoot, 'app', 'View'), { recursive: true }).join('\n')
-            : ''
-    };
-
-    const languageDetections = LANGUAGE_DETECTORS
-        .map(detector => detector.detect(ctx))
-        .filter(result => result.score >= 2)
-        .sort((a, b) => b.score - a.score);
-
-    const frameworkDetails = FRAMEWORK_DETECTORS
-        .map(detector => {
-            const result = detector.detect(ctx);
-            if (result.score < 3) return null;
-            return {
-                ...result,
-                kind: detector.kind,
-                language: detector.language,
-                projectType: detector.projectType,
-                confidence: confidenceLabel(result.score)
-            };
-        })
-        .filter(Boolean)
-        .sort((a, b) => b.score - a.score);
-
-    const frameworkLanguageScores = frameworkDetails.reduce((acc, item) => {
-        if (!item.language) return acc;
-        acc[item.language] = (acc[item.language] || 0) + item.score;
-        return acc;
-    }, {});
-    const primaryLanguage = Object.keys(frameworkLanguageScores).sort((a, b) => frameworkLanguageScores[b] - frameworkLanguageScores[a])[0]
-        || languageDetections[0]?.id
-        || 'typescript';
-    const frameworks = uniq(frameworkDetails.map(item => item.id)).filter(name => FRAMEWORK_CHOICES.includes(name));
-    const infrastructure = [];
-    let projectType = '';
-    let database = 'none';
-    let testFramework = 'auto-detect';
-    let cloud = 'none';
-    let ciCd = 'none';
-
-    if (frameworkDetails.some(item => item.projectType === 'desktop')) projectType = 'desktop';
-    else if (frameworkDetails.some(item => item.projectType === 'mobile')) projectType = 'mobile';
-    else if (frameworkDetails.some(item => item.kind === 'frontend') && frameworkDetails.some(item => item.kind === 'backend')) projectType = 'fullstack';
-    else if (frameworkDetails.some(item => item.projectType === 'web-app')) projectType = 'web-app';
-    else if (frameworkDetails.some(item => item.kind === 'backend')) projectType = 'api';
-    else if (frameworkDetails.some(item => item.kind === 'frontend')) projectType = 'web-app';
-    else if (fileExistsAt(appRoot, 'package.json') && pkg.bin) projectType = 'cli';
-    else if (['php', 'python', 'go', 'java', 'ruby', 'csharp', 'rust'].includes(primaryLanguage)) projectType = 'api';
-
-    if (hasDependency(depNames, 'pg', 'postgres', '@prisma/client') || /postgres/i.test(JSON.stringify(pkg))) database = 'postgres';
-    else if (hasDependency(depNames, 'mysql', 'mysql2')) database = 'mysql';
-    else if (hasDependency(depNames, 'sqlite3', 'better-sqlite3', 'rusqlite')) database = 'sqlite';
-    else if (hasDependency(depNames, 'mongodb', 'mongoose')) database = 'mongodb';
-    else if (hasDependency(depNames, 'redis', 'ioredis')) database = 'redis';
-    else if (hasDependency(depNames, '@aws-sdk/client-dynamodb')) database = 'dynamodb';
-
-    if (hasDependency(depNames, 'vitest')) testFramework = 'vitest';
-    else if (hasDependency(depNames, 'jest')) testFramework = 'jest';
-    else if (hasDependency(depNames, 'pytest') || textMatches(ctx.requirementsText, /\bpytest\b/i) || textMatches(ctx.pyprojectText, /\bpytest\b/i)) testFramework = 'pytest';
-    else if (hasComposerDependency(composerDepNames, 'phpunit/phpunit')) testFramework = 'phpunit';
-    else if (hasComposerDependency(composerDepNames, 'pestphp/pest')) testFramework = 'pest';
-    else if (fileExistsAt(appRoot, 'go.mod')) testFramework = 'go test';
-    else if (textMatches(ctx.gemfileText, /^\s*gem\s+["']rspec["']/im)) testFramework = 'rspec';
-
-    if (repoHasAny(targetDir, [['Dockerfile'], ['docker-compose.yml'], ['docker-compose.yaml']])) {
-        infrastructure.push('docker');
-    }
-
-    if (repoHasAny(targetDir, [['vercel.json']])) {
-        cloud = 'vercel';
-        infrastructure.push('vercel');
-    } else if (repoHasAny(targetDir, [['fly.toml']])) {
-        cloud = 'fly';
-        infrastructure.push('fly');
-    } else if (repoHasAny(targetDir, [['railway.json'], ['railway.toml']])) {
-        cloud = 'railway';
-        infrastructure.push('railway');
-    }
-
-    if (repoHasAny(targetDir, [['.github', 'workflows'], ['.gitlab-ci.yml'], ['.circleci', 'config.yml'], ['Jenkinsfile']], 2)) {
-        if (repoHasAny(targetDir, [['.github', 'workflows']], 2)) ciCd = 'github-actions';
-        else if (repoHasAny(targetDir, [['.gitlab-ci.yml']], 2)) ciCd = 'gitlab-ci';
-        else if (repoHasAny(targetDir, [['.circleci', 'config.yml']], 2)) ciCd = 'circleci';
-        else if (repoHasAny(targetDir, [['Jenkinsfile']], 2)) ciCd = 'jenkins';
-    }
-
-    const scanEvidence = [
-        ...(languageDetections[0] ? [`language:${languageDetections[0].id} => ${languageDetections[0].evidence.join('; ')}`] : []),
-        ...frameworkDetails.map(item => `${item.id} [${item.confidence}] => ${item.evidence.join('; ')}`)
-    ];
-
-    return {
-        project_name: path.basename(targetDir),
-        app_root: path.relative(targetDir, appRoot) || '.',
-        description: pkg.description || composer.description || 'A software project',
-        project_type: PROJECT_TYPE_CHOICES.includes(projectType) ? projectType : 'web-app',
-        primary_language: LANGUAGE_CHOICES.includes(primaryLanguage) ? primaryLanguage : 'typescript',
-        frameworks,
-        framework_details: frameworkDetails,
-        scan_evidence: scanEvidence,
-        database: DATABASE_CHOICES.includes(database) ? database : 'none',
-        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager(appRoot)) ? detectPackageManager(appRoot) : 'auto-detect',
-        uses_docker: infrastructure.includes('docker'),
-        cloud,
-        infrastructure: uniq(infrastructure),
-        ci_cd: ciCd,
-        test_framework: TEST_FRAMEWORK_CHOICES.includes(testFramework) ? testFramework : 'auto-detect',
-        code_style: 'project-standard',
-        architecture_notes: '<!-- Add notes -->',
-        current_phase: 'Initial setup',
-        next_phase: '-',
-        known_issues: '<!-- None yet -->'
-    };
-}
-// --- File Generators ---
-
-function generateSharedAgentsMd(data) {
-    return `# AGENTS.md
-
-Shared operating instructions for Codex, Antigravity, Claude Code, and Cursor.
-
-## Startup
-
-1. Read this file first.
-2. Read \`.agent/docs/project.md\` for detected stack, commands, and routing.
-3. Read \`.agent/docs/workflow.md\` for the task flow before editing.
-4. Read \`.agent/docs/architecture.md\` and \`.agent/docs/conventions.md\` before planning code changes.
-5. Read \`.agent/docs/tooling.md\` when the task needs MCP, RTK, or browser verification.
-
-If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
-
-## Workflow
-
-Matt Pocock's promoted skills (installed under \`.agents/skills/\` by \`thachvd-kit setup\`) are the workflow layer. Use the matching skill when a specialized workflow is useful:
-
-- Clear, localized change: inspect -> edit -> focused verification. Do not force a heavyweight skill.
-- Ambiguous feature or design: \`/grill-with-docs\`, then optionally \`/to-spec\` for a durable contract.
-- Normal feature: \`/grill-with-docs\` -> \`/to-spec\` -> \`/implement\`.
-- Large feature needing decomposition: add \`/to-tickets\` before \`/implement\`.
-- Huge, multi-session uncertainty: \`/wayfinder\`.
-- Bug or failing behavior: \`/diagnosing-bugs\`.
-- Test-driven implementation: \`/tdd\` (skip the ceremony for trivial config/text changes).
-- Architecture survey: \`/improve-codebase-architecture\`; use \`/codebase-design\` as the design vocabulary.
-- Pre-completion review: \`/code-review\` once when code risk warrants it.
-
-If unsure which skill fits, use \`/ask-matt\`.
-
-Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, use the matching planning skill above instead.
-
-See \`.agent/docs/workflow.md\` for the full route matrix. This kit does not implement a second workflow engine; it only installs and checks the promoted skill set (\`thachvd-kit skills install|check|update\`).
-
-${QUALITY_FLOOR_SECTION}
-
-${AGENT_RULES_SECTION}
-
-## Shared Knowledge
-
-- Project context: \`.agent/docs/\`
-- Tooling setup: \`.agent/docs/tooling.md\`
-- Matt Pocock skills: promoted set installed under \`.agents/skills/\` via \`thachvd-kit skills install\`
-- RTK: recommended local CLI for compact command output
-- Antigravity and Cursor entry rules: \`GEMINI.md\` and \`.cursorrules\`
-`;
-}
-
-function generateIndexProjectPrompt() {
-    return `# Project Indexing Prompt
-
-Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
-Use the project's Matt Pocock skills for workflow (see AGENTS.md; run /ask-matt if unsure which fits) and use codebase-memory MCP for structural code discovery when available.
-Ask me what this project does and any important conventions I want preserved.
-Then scan this repository and refine the generated context docs with factual rules.
-Do not implement product code during onboarding.
-`;
-}
-
-function printProjectPrompt() {
-    const promptPath = path.join(targetDir, '.agent', 'docs', 'index-project-prompt.md');
-    if (!fs.existsSync(promptPath)) {
-        console.error(pc.yellow('No saved project prompt found. Run thachvd-kit init first.'));
-        process.exitCode = 1;
-        return;
-    }
-    console.log(fs.readFileSync(promptPath, 'utf8'));
-}
-
-function generateSharedClaudeMd() {
-    return `@AGENTS.md
-
-## Claude Code
-
-This repository uses AGENTS.md as the shared cross-agent entry file. Follow the imported instructions and keep Claude-specific notes here only when they cannot apply to Codex or Antigravity.
-`;
-}
-
-function generateSharedGeminiMd() {
-    return `# GEMINI.md
-
-Antigravity entry file for this project.
-
-Read AGENTS.md first, then follow the shared docs under .agent/docs/.
-`;
-}
-
-function generateSharedCursorrules(data) {
-    return `# Cursor Rules
-
-This repository uses AGENTS.md as the shared cross-agent entry file. Follow the instructions in AGENTS.md and keep Cursor-specific notes here only when they cannot apply to Codex, Antigravity, or Claude Code.
-
-Read AGENTS.md first, then follow the shared docs under .agent/docs/.
-
----
-
-${generateSharedAgentsMd(data).trimEnd()}
-`;
-}
-
-function resolveCommands(data) {
-    const frameworks = data.frameworks || [];
-    const primaryLang = data.primary_language || 'javascript';
-    const pkgManager = data.package_manager || 'npm';
-    const testFramework = data.test_framework || 'auto-detect';
-
-    const isPython = primaryLang === 'python';
-    const isGo = primaryLang === 'go';
-    const isRust = primaryLang === 'rust';
-    const isPhp = primaryLang === 'php';
-
-    let install = 'npm install';
-    let dev = 'npm run dev';
-    let build = 'npm run build';
-    let test = 'npm test';
-    let lint = 'npm run lint';
-
-    if (pkgManager === 'pnpm') { install = 'pnpm install'; dev = 'pnpm dev'; build = 'pnpm build'; test = 'pnpm test'; lint = 'pnpm lint'; }
-    else if (pkgManager === 'yarn') { install = 'yarn'; dev = 'yarn dev'; build = 'yarn build'; test = 'yarn test'; lint = 'yarn lint'; }
-    else if (pkgManager === 'bun') { install = 'bun install'; dev = 'bun dev'; build = 'bun run build'; test = 'bun test'; lint = 'bun run lint'; }
-    else if (isPython) { install = 'pip install -r requirements.txt'; dev = 'python manage.py runserver'; build = '# no build step'; test = 'pytest'; lint = 'ruff check .'; }
-    else if (isGo) { install = 'go mod download'; dev = 'go run .'; build = 'go build ./...'; test = 'go test ./...'; lint = 'golangci-lint run'; }
-    else if (isRust) { install = 'cargo build'; dev = 'cargo run'; build = 'cargo build --release'; test = 'cargo test'; lint = 'cargo clippy'; }
-    else if (isPhp) {
-        install = 'composer install';
-        build = '# no build step';
-        test = testFramework === 'pest' ? './vendor/bin/pest' : './vendor/bin/phpunit';
-        const isCakePHP = frameworks.some(f => f.toLowerCase().includes('cakephp'));
-        const isSymfony = frameworks.some(f => f.toLowerCase().includes('symfony'));
-        const isCodeIgniter = frameworks.some(f => f.toLowerCase().includes('codeigniter'));
-        if (isCakePHP) {
-            dev = 'bin/cake server';
-            lint = './vendor/bin/phpcs';
-        } else if (isSymfony) {
-            dev = 'bin/console server:run';
-            lint = './vendor/bin/phpcs';
-        } else if (isCodeIgniter) {
-            dev = 'php spark serve';
-            lint = './vendor/bin/phpcs';
-        } else {
-            dev = 'php artisan serve';
-            lint = 'php artisan pint';
-        }
-    }
-
-    if (testFramework === 'vitest') test = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : pkgManager === 'bun' ? 'bun run' : 'npx'} vitest`;
-    else if (testFramework === 'jest') test = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : 'npx'} jest`;
-
-    return { install, dev, build, test, lint };
-}
-
-function generateProjectDoc(data) {
-    const commands = resolveCommands(data);
-    const evidence = (data.scan_evidence || []).length > 0
-        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
-        : '- TODO: refine scan evidence by inspecting the project.';
-
-    return `# Project Rules
-
-Generated by thachvd-kit on ${new Date().toISOString().split('T')[0]}.
-
-## Summary
-
-- Name: ${data.project_name}
-- Description: ${data.description}
-- Type: ${data.project_type}
-- App root: ${data.app_root || '.'}
-
-## Stack
-
-- Language: ${data.primary_language}
-- Frameworks: ${(data.frameworks || []).join(', ') || 'none'}
-- Database: ${data.database || 'none'}
-- Infrastructure: ${(data.infrastructure || []).join(', ') || 'none'}
-- Package manager: ${data.package_manager || 'auto-detect'}
-- Test framework: ${data.test_framework || 'auto-detect'}
-
-## Commands
-
-- Install: \`${commands.install}\`
-- Dev: \`${commands.dev}\`
-- Build: \`${commands.build}\`
-- Test: \`${commands.test}\`
-- Lint: \`${commands.lint}\`
-
-## Available Integrations
-
-Use these integrations when available. Run thachvd-kit doctor to check the current machine.
-
-| MCP | When to Use |
-|-----|-------------|
-| \`codebase-memory-mcp\` | Explore symbols, trace call chains, architecture, and impact |
-| \`context7\` | Look up library/framework docs, API signatures, migration guides |
-| \`playwright\` | Verify UI behavior, take screenshots, test forms and navigation |
-| \`rtk\` | Recommended proxy for noisy git, tests, builds, and package commands |
-
-> Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
-
-## Scan Evidence
-
-${evidence}
-`;
-}
-
-function generateArchitectureDoc(data) {
-    const appRootLine = data.app_root && data.app_root !== '.'
-        ? `- App root is currently detected as \`${data.app_root}\`.`
-        : '- App root is the repository root unless refined below.';
-    const evidence = (data.scan_evidence || []).length > 0
-        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
-        : '- TODO: refine architecture by scanning source directories.';
-
-    return `# Architecture Notes
-
-## Current Map
-
-${appRootLine}
-- TODO: refine major directories and responsibilities.
-- TODO: refine main entry points, routing, state boundaries, and integration boundaries.
-
-## Detected Evidence
-
-${evidence}
-
-## AI Maintenance Rule
-
-Before non-trivial implementation work, inspect this file. If it is stale or still contains TODO items relevant to the task, update it from the code before editing product code.
-`;
-}
-
-function generateConventionsDoc() {
-    return `# Coding Conventions
-
-${CONVENTIONS_STANDARDS_SECTION}
-
-${QUALITY_FLOOR_SECTION}
-
-## Verification
-
-- Run the focused test or lint command that matches the touched area.
-- If no automated check exists, document the manual verification performed.
-- For UI/web changes, prioritize using Playwright MCP to automatically verify client-side behavior and capture screenshots.
-- Do not claim completion without verification evidence.
-`;
-}
-
-function generateWorkflowDoc() {
-    return `# Agent Workflow
-
-This project uses Matt Pocock's promoted skills (installed under .agents/skills/ by \`thachvd-kit setup\`) as the workflow layer. thachvd-kit only provides project context, the skill manifest, and integration setup; it is not a second workflow engine.
-
-## Before Every Task
-
-1. Read AGENTS.md and the relevant files under .agent/docs/.
-2. Use the promoted skill that matches the request, or run /ask-matt if unsure which one fits.
-3. Use codebase-memory MCP for structural discovery when available.
-4. Make changes only after the required planning gate for that situation.
-5. Verify the change and request review before completion.
-
-## Route Matrix
-
-| Situation | Skill | Gate |
-|---|---|---|
-| Question or research only | direct answer or research | no product-code edits |
-| Clear, localized change | fast path (no skill) | inspect -> edit -> focused verify |
-| Ambiguous feature or design | /grill-with-docs, then optionally /to-spec | durable contract before implementation when useful |
-| Normal feature | /grill-with-docs -> /to-spec -> /implement | spec agreed before implementation |
-| Large feature needing decomposition | /grill-with-docs -> /to-spec -> /to-tickets -> /implement | tickets agreed before implementation |
-| Huge, multi-session uncertainty | /wayfinder | shared decision map before implementation |
-| Bug or failing behavior | /diagnosing-bugs | reproduce -> root cause -> regression protection -> fix -> verify |
-| Test-driven implementation | /tdd | red -> green -> refactor per slice |
-| Architecture survey | /improve-codebase-architecture (+ /codebase-design vocabulary) | findings reviewed before large refactors |
-| Pre-merge | /code-review | blocking findings resolved |
-
-Not sure which row applies? Run /ask-matt instead of guessing.
-
-## Standard Feature Flow
-
-/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> /implement (with /tdd where it helps) -> /code-review.
-
-${FAST_PATH_SECTION}
-
-## Documentation Maintenance
-
-- Update architecture.md when structure or boundaries change.
-- Update conventions.md when repeated project patterns become clear.
-- Update project.md when stack, scripts, or test tooling changes.
-- Keep AGENTS.md concise and put project-specific detail under .agent/docs/.
-`;
-}
-
-function generateGettingStartedDoc() {
-    return `# Getting Started
-
-thachvd-kit creates project context. Matt Pocock's promoted skills own the development workflow.
-
-## Setup
-
-1. Run \`thachvd-kit init\` in the repository.
-2. Open or print \`.agent/docs/index-project-prompt.md\` with \`thachvd-kit prompt\`.
-3. Run \`thachvd-kit setup\` (installs the promoted skill set by default; add \`--no-install-skills\` to skip) and RTK.
-4. Inside the AI client, run \`/setup-matt-pocock-skills\` once to configure the issue tracker, triage labels, and doc layout.
-5. Run \`thachvd-kit doctor\` and restart the AI client.
-
-## Standard Flow
-
-1. \`/grill-with-docs\` for unclear requirements or design.
-2. \`/to-spec\` when a durable implementation contract is useful.
-3. \`/to-tickets\` for large work that benefits from decomposition.
-4. \`/implement\`, with \`/tdd\` where red-green-refactor helps.
-5. \`/code-review\` once before completion.
-
-Not sure which skill fits? Run \`/ask-matt\`.
-
-## Bug Flow
-
-Use \`/diagnosing-bugs\`: reproduce the symptom, inspect the path with codebase-memory MCP, test hypotheses, add regression protection, fix the root cause, and verify.
-
-${GETTING_STARTED_FAST_PATH_SECTION}
-`;
-}
-
-function resolveToolingSetup(data) {
-    const primaryLang = data.primary_language || 'javascript';
-    const packageManager = data.package_manager || 'npm';
-    const isPython = primaryLang === 'python';
-    const runner = packageManager === 'pnpm'
-        ? 'pnpm dlx'
-        : packageManager === 'yarn'
-            ? 'yarn dlx'
-            : packageManager === 'bun'
-                ? 'bunx'
-                : 'npx';
-    const playwrightCommand = isPython
-        ? 'pip install playwright && playwright install chromium'
-        : `${runner} playwright install`;
-
-    return { runner, playwrightCommand };
-}
-
-function generateToolingDoc(data) {
-    const { runner, playwrightCommand } = resolveToolingSetup(data);
-
-    return `# Optional Tooling
-
-Run \`thachvd-kit doctor\` to check the current machine.
-
-## Matt Pocock Skills
-
-Matt Pocock's promoted engineering and productivity skills are the workflow layer for this project, installed project-locally under \`.agents/skills/\` (never globally):
-
-- Install the promoted set: \`thachvd-kit skills install\` (\`--dry-run\` to preview the command without running it)
-- Check what is installed: \`thachvd-kit skills check\` (read-only)
-- Update the promoted set: \`thachvd-kit skills update\` (re-adds each skill individually for safety, so it is slower than install — one network clone per skill)
-- The full manifest lives in \`bin/matt-skills.js\` (\`PROMOTED_SKILLS\`); it mirrors upstream's \`skills/engineering/\` + \`skills/productivity/\` catalog and never includes \`in-progress\`, \`misc\`, or \`deprecated\` skills.
-- After the first install, run \`/setup-matt-pocock-skills\` once inside the AI client to configure the issue tracker, triage labels, and generated docs location. thachvd-kit does not simulate that skill.
-- Unsure which skill fits a task? Run \`/ask-matt\`.
-
-${TOOL_ROUTING_SECTION}
-
-## Codebase Memory MCP
-
-Use \`codebase-memory-mcp\` for symbol search, call paths, architecture, and impact analysis.
-
-- Install: \`npm install -g codebase-memory-mcp\`
-- Index a repository: \`codebase-memory-mcp cli index_repository --repo-path .\`
-- Keep local index state out of git unless the team explicitly chooses a shared snapshot.
-
-## RTK
-
-RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands.
-
-- Install: \`cargo install --git https://github.com/rtk-ai/rtk --branch master rtk\`
-- Examples: \`rtk git status\`, \`rtk npm test\`, \`rtk git log\`.
-- If it is unavailable, run the underlying command directly.
-
-## Playwright
-
-- Check: \`${runner} playwright --version\`
-- Browser install: \`${playwrightCommand}\`
-- Use the project's existing Playwright scripts when available.
-`;
-}
-
-async function writeGeneratedFile(relativePath, content, assumeYes) {
-    const outputPath = path.join(targetDir, relativePath);
-    const exists = fs.existsSync(outputPath);
-    if (exists && !assumeYes) {
-        const response = await prompts({
-            type: 'confirm',
-            name: 'overwrite',
-            message: `File ${pc.bold(relativePath)} already exists. Do you want to overwrite it?`,
-            initial: false
-        });
-        if (response.overwrite === undefined) {
-            console.log(pc.yellow('\nCancelled.'));
-            process.exit(130);
-        }
-        if (!response.overwrite) return false;
-    }
-
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-    fs.writeFileSync(outputPath, content, 'utf8');
-    return true;
-}
-
-function homePath(...parts) {
-    const home = process.env.USERPROFILE || process.env.HOME;
-    return home ? path.join(home, ...parts) : null;
-}
-
-function printMattSkillsSetupReminder() {
-    console.log(`  Run ${pc.bold('/setup-matt-pocock-skills')} once inside your AI client to configure the issue tracker, triage labels, and generated docs location.`);
-}
-
-function runDoctor() {
-    console.log(pc.bold(pc.cyan('thachvd-kit doctor')));
-    const requiredFiles = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.cursorrules',
-        path.join('.agent', 'docs', 'project.md'), path.join('.agent', 'docs', 'workflow.md')];
-    for (const relativePath of requiredFiles) {
-        const ok = fs.existsSync(path.join(targetDir, relativePath));
-        console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${relativePath}`);
-    }
-
-    const tools = [
-        [CODEBASE_MEMORY_BINARY, `npm install -g ${CODEBASE_MEMORY_PACKAGE}`],
-        ['rtk', `recommended: ${RTK_INSTALL_COMMAND}`]
-    ];
-    console.log(`\n${pc.bold('Local integrations (RTK recommended)')}`);
-    for (const [binary, hint] of tools) {
-        const ok = commandExists(binary);
-        console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${binary}${ok ? '' : ` - ${hint}`}`);
-    }
-
-    console.log(`\n${pc.bold('Matt Pocock skills')}`);
-    const skillStatus = mattSkills.checkSkills(targetDir);
-    if (skillStatus.missing.length === 0) {
-        console.log(`  ${pc.green('OK')} promoted skill set installed (${skillStatus.total}/${skillStatus.total})`);
-    } else {
-        console.log(`  ${pc.yellow('WARN')} ${skillStatus.missing.length} promoted skill(s) missing`);
-        console.log(`       Run: ${pc.bold('thachvd-kit skills install')}`);
-    }
-    const setupSkillOk = mattSkills.isSkillInstalled(targetDir, mattSkills.SETUP_SKILL_NAME);
-    console.log(`  ${setupSkillOk ? pc.green('OK') : pc.yellow('WARN')} ${mattSkills.SETUP_SKILL_NAME} available`);
-    const contextMdExists = fs.existsSync(path.join(targetDir, 'CONTEXT.md'));
-    const docsAdrExists = fs.existsSync(path.join(targetDir, 'docs', 'adr'));
-    console.log(`  ${pc.dim('-')} CONTEXT.md ${contextMdExists ? 'detected' : 'not created yet (informational only)'}`);
-    console.log(`  ${pc.dim('-')} docs/adr ${docsAdrExists ? 'detected' : 'not created yet (informational only)'}`);
-
-    console.log(`\n${pc.bold('Next step')}`);
-    console.log('  Run thachvd-kit prompt to print the saved project-indexing prompt.');
-}
-
-async function runSetup(args) {
-    const skipMcpSetup = args.includes('--no-setup-mcp');
-    const skipHookSetup = args.includes('--no-setup-hook');
-    const skipRtkInstall = args.includes('--no-install-rtk');
-    const skipIndex = args.includes('--no-index');
-    const skipSkillsInstall = args.includes('--no-install-skills');
-    console.log(pc.bold(pc.cyan('thachvd-kit setup')));
-    if (!skipSkillsInstall) {
-        console.log(pc.bold('Matt Pocock skills'));
-        const skillStatus = mattSkills.checkSkills(targetDir);
-        if (skillStatus.missing.length === 0) {
-            // Already fully installed: `setup` only ensures presence, it
-            // never re-installs or updates on its own. Explicit
-            // `thachvd-kit skills update` is required for that.
-            console.log(`  ${pc.green('OK')} promoted skill set already installed (${skillStatus.total}/${skillStatus.total})`);
-        } else {
-            const skillsResult = mattSkills.installSkills(targetDir);
-            const skillsMarker = skillsResult.ok ? pc.green('OK') : pc.yellow('WARN');
-            console.log(`  ${skillsMarker} ${skillsResult.message}`);
-        }
-        printMattSkillsSetupReminder();
-    } else {
-        console.log(`${pc.bold('Matt Pocock skills')}\n  ${pc.dim('skipped (--no-install-skills)')}`);
-    }
-    if (!skipMcpSetup) {
-        console.log(pc.bold('MCP setup'));
-        for (const result of setupMcpServers({ install: true })) {
-            const marker = result.ok ? pc.green('OK') : pc.yellow('WARN');
-            console.log(`  ${marker} ${result.message}`);
-        }
-        if (!skipIndex) {
-            const indexResult = indexRepository();
-            const marker = indexResult.ok ? pc.green('OK') : pc.yellow('WARN');
-            console.log(`  ${marker} ${indexResult.message}`);
-        }
-    }
-    if (!skipHookSetup) {
-        console.log(`\n${pc.bold('Claude Code Definition-of-Done hook')}`);
-        const claudeProjectSettings = path.join(targetDir, '.claude', 'settings.json');
-        const result = mergeClaudeProjectHooks(claudeProjectSettings);
-        const marker = result.ok ? pc.green('OK') : pc.yellow('WARN');
-        console.log(`  ${marker} ${result.message}`);
-        console.log('  This hook only checks for plan/review/verification evidence; it never prescribes which skill produces it.');
-    }
-    console.log(`\n${pc.bold('RTK (recommended)')}`);
-    const rtkResult = ensureRtkInstalled(!skipRtkInstall);
-    const rtkMarker = rtkResult.ok ? pc.green('OK') : pc.yellow('WARN');
-    console.log(`  ${rtkMarker} ${rtkResult.message}`);
-    console.log('\nRestart your AI client after installing plugins or changing MCP configuration.');
-    console.log('Your onboarding prompt is saved at .agent/docs/index-project-prompt.md. Run thachvd-kit prompt to print it again.');
-}
-
-function commandExists(command) {
-    const checker = process.platform === 'win32' ? 'where' : 'command';
-    const args = process.platform === 'win32' ? [command] : ['-v', command];
-    const result = spawnSync(checker, args, { encoding: 'utf8', shell: process.platform !== 'win32' });
-    return result.status === 0;
-}
-
-function ensureGlobalNpmPackage(binaryName, packageName, install = false) {
-    if (commandExists(binaryName)) {
-        return { ok: true, message: `${binaryName} already installed` };
-    }
-    if (!install) {
-        return { ok: false, message: `${binaryName} is missing; run: npm install -g ${packageName}` };
-    }
-    if (!commandExists('npm')) {
-        return { ok: false, message: `npm not found; run: npm install -g ${packageName}` };
-    }
-    const result = spawnSync('npm', ['install', '-g', packageName], {
-        encoding: 'utf8',
-        stdio: 'pipe',
-        shell: process.platform === 'win32'
-    });
-    if (result.status !== 0) {
-        return { ok: false, message: `failed to install ${binaryName}; run: npm install -g ${packageName}` };
-    }
-    return { ok: true, message: `installed ${binaryName}` };
-}
-
-function ensureCodebaseMemoryCli(install = false) {
-    return ensureGlobalNpmPackage(CODEBASE_MEMORY_BINARY, CODEBASE_MEMORY_PACKAGE, install);
-}
-
-function ensureRtkInstalled(install = false) {
-    if (commandExists('rtk')) {
-        return { ok: true, message: 'rtk already installed' };
-    }
-    if (!install) {
-        return { ok: false, message: `rtk is missing; run: ${RTK_INSTALL_COMMAND}` };
-    }
-    if (!commandExists('cargo')) {
-        return { ok: false, message: `cargo not found; install Rust, then run: ${RTK_INSTALL_COMMAND}` };
-    }
-    console.log(pc.dim('  Installing rtk via cargo (compiles from source; this can take a few minutes)...'));
-    const result = spawnSync('cargo', ['install', '--git', 'https://github.com/rtk-ai/rtk', '--branch', 'master', 'rtk'], {
-        encoding: 'utf8',
-        stdio: 'inherit',
-        shell: process.platform === 'win32'
-    });
-    if (result.status !== 0) {
-        return { ok: false, message: `failed to install rtk; run: ${RTK_INSTALL_COMMAND}` };
-    }
-    return { ok: true, message: 'installed rtk' };
-}
-
-function indexRepository() {
-    if (!commandExists(CODEBASE_MEMORY_BINARY)) {
-        return { ok: false, message: `${CODEBASE_MEMORY_BINARY} is not installed; skipped indexing` };
-    }
-    console.log(pc.dim(`  Running ${CODEBASE_MEMORY_BINARY} cli index_repository --repo-path . (first index of a large repo can take a while)...`));
-    const result = spawnSync(CODEBASE_MEMORY_BINARY, ['cli', 'index_repository', '--repo-path', '.'], {
-        cwd: targetDir,
-        encoding: 'utf8',
-        stdio: 'inherit',
-        shell: process.platform === 'win32'
-    });
-    if (result.status !== 0) {
-        return { ok: false, message: `indexing failed; run manually: ${CODEBASE_MEMORY_BINARY} cli index_repository --repo-path .` };
-    }
-    return { ok: true, message: 'indexed repository with codebase-memory-mcp' };
-}
-
-function readJsonFile(filePath) {
-    if (!fs.existsSync(filePath)) return {};
-    try {
-        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    } catch {
-        return null;
-    }
-}
-
-function writeJsonFile(filePath, data) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
-}
-
-function mergeMcpJson(filePath, withType = false) {
-    const data = readJsonFile(filePath);
-    if (data === null) {
-        return { ok: false, message: `${filePath} is not valid JSON; skipped` };
-    }
-    data.mcpServers = data.mcpServers || {};
-    const baseServers = {
-        'codebase-memory-mcp': { command: CODEBASE_MEMORY_BINARY, args: [] },
-        playwright: { command: 'playwright-mcp' },
-        context7: { command: 'context7-mcp' }
-    };
-    if (data.permissions && Array.isArray(data.permissions.allow)) {
-        const requiredPermissions = [
-            "mcp__context7__resolve-library-id",
-            "mcp__context7__query-docs"
-        ];
-        for (const perm of requiredPermissions) {
-            if (!data.permissions.allow.includes(perm)) {
-                data.permissions.allow.push(perm);
-            }
-        }
-    }
-    for (const [name, server] of Object.entries(baseServers)) {
-        if (!data.mcpServers[name]) {
-            data.mcpServers[name] = withType ? { type: 'stdio', ...server } : server;
-        }
-    }
-    writeJsonFile(filePath, data);
-    const tools = Object.keys(baseServers).join(', ');
-    return { ok: true, message: `configured ${tools} MCP in ${filePath}` };
-}
-
-function appendMcpTomlIfMissing(filePath) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
-    const blocks = [];
-    if (!/\[mcp_servers\.context7\]/.test(existing)) {
-        blocks.push(`[mcp_servers.context7]
-command = "context7-mcp"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (!/\[mcp_servers\.codebase-memory-mcp\]/.test(existing)) {
-        blocks.push(`[mcp_servers.codebase-memory-mcp]
-command = "${CODEBASE_MEMORY_BINARY}"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (!/\[mcp_servers\.playwright\]/.test(existing)) {
-        blocks.push(`[mcp_servers.playwright]
-command = "playwright-mcp"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (blocks.length === 0) {        return { ok: true, message: `already configured ${filePath}` };
-    }
-    const separator = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
-    fs.writeFileSync(filePath, existing + separator + blocks.join('\n'), 'utf8');
-    return { ok: true, message: `configured codebase-memory-mcp, context7, playwright MCP in ${filePath}` };
-}
-
-const DOD_HOOK_MARKER = 'feature/refactor Definition-of-Done gate';
-
-function generateDodStopHookPrompt() {
-    return `Input JSON (Stop hook payload): $ARGUMENTS\n\nCheck this project's ${DOD_HOOK_MARKER}. This kit does not define its own workflow steps or require any specific workflow skill; it only verifies that evidence of the gate exists, however that evidence was produced (a documented planning/review skill, a manual process, or anything equivalent). Use the \`last_assistant_message\` field as the authoritative final response. Use \`transcript_path\` only for additional context because the transcript may not contain the final response yet.\n\nVerification is never optional: every change, fast path included, requires semantic evidence in the final response or visible transcript that focused tests or equivalent verification actually ran and passed (for example test/build output, or a described manual verification). Do not require a specific command; judge the evidence on its meaning.\n\nFor any change that is not a verified fast path (see below), completion additionally requires evidence of:\n- Plan: a plan was written and explicitly approved by the human before implementation started.\n- Review: the change was reviewed (correctness, simplicity, architecture, security, performance) and blocking issues were resolved.\n\nFast-path eligibility is based on risk and contract surface, not file count. A change is fast path only when it is localized, mechanically obvious, low-risk, and has no meaningful public API, schema, auth/security, data-integrity, payment, concurrency, dependency, CI/release, or architectural risk, with focused verification available. A source file plus its own focused test can still be fast path; a one-file auth, payment, schema, security, or concurrency change is not fast path no matter how small. A verified fast-path change is exempt from the Plan and Review evidence only when the final response states FAST_PATH: simple-fix, its reason, and its narrow scope — Verification evidence is still mandatory in that case, not optional.\n\nSteps:\n1. If the input JSON has \`stop_hook_active: true\`, allow stopping immediately (already checked once this cycle; never block twice in a row).\n2. Inspect the changed files and the \`last_assistant_message\` field.\n3. If no source files changed or the final response does not claim the task is done/complete, allow stopping.\n4. If the final response explicitly contains FAST_PATH: simple-fix, first check the claim against the risk criteria above, not file count. If it actually touches one of those risk areas regardless of file count, the FAST_PATH claim is invalid; treat it as a full feature/refactor change and continue to step 5. Otherwise, look for semantic evidence that focused verification actually ran and passed. If that evidence is present, allow stopping. If it is missing, block with {"ok": false, "reason": "Missing Verification evidence: ..."}.\n5. If the final response claims completion for a change that is not a verified fast path, check all three gates: (a) a plan was written and explicitly approved by the human before implementation started; (b) the change was reviewed and blocking issues were resolved; (c) tests or equivalent verification ran and passed. If any one of the three is missing, block naming exactly that gate; a generic statement that the task was simple, or that it touched only one file, is not enough on its own.\n6. Return exactly JSON: {"ok": true} to allow stopping, or {"ok": false, "reason": "..."} to block.\n\nWhen blocking, name exactly which gate is missing without prescribing which skill or workflow must produce it.`;
-}
-
-function isDefinitionOfDoneHook(hook) {
-    const prompt = hook && typeof hook.prompt === 'string' ? hook.prompt : '';
-    return prompt.includes(DOD_HOOK_MARKER);
-}
-
-function mergeClaudeProjectHooks(filePath) {
-    const data = readJsonFile(filePath);
-    if (data === null) {
-        return { ok: false, message: `${filePath} is not valid JSON; skipped hook setup` };
-    }
-    if (!data.hooks || typeof data.hooks !== 'object') data.hooks = {};
-    if (!Array.isArray(data.hooks.Stop)) data.hooks.Stop = [];
-
-    let primaryHook = null;
-    let definitionHookCount = 0;
-    for (const entry of data.hooks.Stop) {
-        for (const hook of Array.isArray(entry?.hooks) ? entry.hooks : []) {
-            if (isDefinitionOfDoneHook(hook)) {
-                definitionHookCount++;
-                if (!primaryHook) primaryHook = hook;
-            }
-        }
-    }
-
-    if (primaryHook) {
-        primaryHook.prompt = generateDodStopHookPrompt();
-        primaryHook.timeout = 60;
-        primaryHook.statusMessage = 'Checking feature/refactor Definition-of-Done gate...';
-
-        if (definitionHookCount > 1) {
-            data.hooks.Stop = data.hooks.Stop
-                .map(entry => ({
-                    ...entry,
-                    hooks: (Array.isArray(entry?.hooks) ? entry.hooks : [])
-                        .filter(hook => !isDefinitionOfDoneHook(hook) || hook === primaryHook)
-                }))
-                .filter(entry => entry.hooks.length > 0);
-        }
-
-        writeJsonFile(filePath, data);
-        return {
-            ok: true,
-            message: definitionHookCount > 1
-                ? `consolidated Definition-of-Done Stop hooks in ${filePath}`
-                : `updated Definition-of-Done Stop hook in ${filePath}`
-        };
-    }
-
-    data.hooks.Stop.push({
-        hooks: [
-            {
-                type: 'agent',
-                prompt: generateDodStopHookPrompt(),
-                timeout: 60,
-                statusMessage: 'Checking feature/refactor Definition-of-Done gate...'
-            }
-        ]
-    });
-    writeJsonFile(filePath, data);
-    return { ok: true, message: `configured Definition-of-Done Stop hook in ${filePath}` };
-}
-
-function setupMcpServers(options = {}) {
-    const install = options.install === true;
-    const results = [];
-    results.push(ensureCodebaseMemoryCli(install));
-    results.push(ensureGlobalNpmPackage('context7-mcp', '@upstash/context7-mcp', install));
-    results.push(ensureGlobalNpmPackage('playwright-mcp', '@playwright/mcp', install));
-
-    const codexConfig = homePath('.codex', 'config.toml');
-    if (codexConfig) results.push(appendMcpTomlIfMissing(codexConfig));
-
-    const geminiConfig = homePath('.gemini', 'config', 'mcp_config.json');
-    if (geminiConfig) results.push(mergeMcpJson(geminiConfig, false));
-
-    const antigravityIdeConfig = homePath('.gemini', 'antigravity-ide', 'mcp_config.json');
-    if (antigravityIdeConfig) results.push(mergeMcpJson(antigravityIdeConfig, false));
-
-    const antigravityConfig = homePath('.gemini', 'antigravity', 'mcp_config.json');
-    if (antigravityConfig && fs.existsSync(path.dirname(antigravityConfig))) {
-        results.push(mergeMcpJson(antigravityConfig, false));
-    }
-
-    const claudeConfig = homePath('.claude.json');
-    if (claudeConfig) results.push(mergeMcpJson(claudeConfig, true));
-
-    const claudeSettings = homePath('.claude', 'settings.json');
-    if (claudeSettings) results.push(mergeMcpJson(claudeSettings, true));
-
-    return results;
-}
-
-function runSkillsCommand(args) {
-    const subcommand = args[0];
-    const dryRun = args.includes('--dry-run');
-
-    if (subcommand === 'install') {
-        console.log(pc.bold(pc.cyan('thachvd-kit skills install')));
-        const result = mattSkills.installSkills(targetDir, { dryRun });
-        console.log(`  ${result.ok ? pc.green('OK') : pc.yellow('WARN')} ${result.message}`);
-        if (!dryRun && result.ok) printMattSkillsSetupReminder();
-        if (!result.ok) process.exitCode = 1;
-        return;
-    }
-
-    if (subcommand === 'check') {
-        console.log(pc.bold(pc.cyan('thachvd-kit skills check')));
-        const status = mattSkills.checkSkills(targetDir);
-        for (const name of mattSkills.PROMOTED_SKILLS) {
-            const installed = status.installed.includes(name);
-            console.log(`  ${installed ? pc.green('OK') : pc.yellow('WARN')} ${name}`);
-        }
-        console.log(`\n  ${status.installed.length}/${status.total} promoted skills installed in ${mattSkills.SKILLS_RELATIVE_DIR}`);
-        if (status.missing.length > 0) {
-            console.log(`  Run: ${pc.bold('thachvd-kit skills install')}`);
-        }
-        return;
-    }
-
-    if (subcommand === 'update') {
-        console.log(pc.bold(pc.cyan('thachvd-kit skills update')));
-        const result = mattSkills.updateSkills(targetDir, { dryRun });
-        if (dryRun) {
-            for (const item of result.results) console.log(`  ${pc.dim('would run')} ${item.command}`);
-        } else {
-            for (const item of result.results) console.log(`  ${item.ok ? pc.green('OK') : pc.yellow('WARN')} ${item.name}`);
-        }
-        console.log(`\n  ${result.ok ? pc.green('OK') : pc.yellow('WARN')} ${result.message}`);
-        if (!result.ok) process.exitCode = 1;
-        return;
-    }
-
-    console.error(pc.red(`Unknown skills subcommand: ${subcommand || '(none)'}`));
-    console.error('Usage: thachvd-kit skills install|check|update [--dry-run]');
-    process.exit(1);
-}
-
-// --- Main CLI ---
-
-async function main() {
-    // Note: 'upgrade' and 'global' are handled directly by bin/entry.js
-    // (bin/upgrade.js / bin/global.js) before this module is even required,
-    // so they never reach here.
-    const rawArgs = process.argv.slice(2);
-    const command = rawArgs[0] && !rawArgs[0].startsWith('-') ? rawArgs[0] : 'init';
-    const args = command === 'init' ? rawArgs.slice(rawArgs[0] === 'init' ? 1 : 0) : rawArgs.slice(1);
-
-    if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
-        console.log(packageJson.version);
-        return;
-    }
-
-    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
-        printHelp();
-        return;
-    }
-
-    if (command === 'doctor') {
-        runDoctor();
-        return;
-    }
-
-    if (command === 'prompt') {
-        printProjectPrompt();
-        return;
-    }
-
-    if (command === 'setup') {
-        await runSetup(rawArgs.slice(1));
-        return;
-    }
-
-    if (command === 'skills') {
-        runSkillsCommand(rawArgs.slice(1));
-        return;
-    }
-
-    if (command !== 'init') {
-        console.error(pc.red(`Unknown command: ${command}`));
-        printHelp();
-        process.exit(1);
-    }
-
-    const assumeYes = args.includes('--yes') || args.includes('-y');
-    const skipMcpSetup = args.includes('--no-setup-mcp') || process.env.THACHVD_KIT_SKIP_MCP_SETUP === '1';
-
-    console.log(pc.bold(pc.cyan('='.repeat(50))));
-    console.log('  ' + pc.bold('thachvd-kit') + ' - AI Project Bootstrap');
-    console.log('  Generates shared agent rules and configures MCP tooling');
-    console.log(pc.bold(pc.cyan('='.repeat(50))));
-
-    console.log(pc.dim('  Scanning current project files for a baseline...\n'));
-    const scanned = scanProject();
-
-    console.log(`  ${pc.bold('Detected context:')}`);
-    formatScanPreviewLines(scanned).forEach(([label, value]) => {
-        console.log(`    - ${label}: ${value}`);
-    });
-    console.log('');
-    if ((scanned.scan_evidence || []).length > 0) {
-        console.log(`  ${pc.bold('Evidence:')}`);
-        scanned.scan_evidence.forEach(line => console.log(`    - ${line}`));
-        console.log('');
-    }
-
-    // Combine data
-    const data = {
-        project_name: scanned?.project_name || path.basename(targetDir),
-        description: scanned?.description || 'A software project',
-        project_type: scanned?.project_type || 'web-app',
-        primary_language: scanned?.primary_language || 'typescript',
-        frameworks: scanned?.frameworks || [],
-        database: scanned?.database || 'none',
-        uses_docker: scanned?.uses_docker ?? true,
-        cloud: scanned?.cloud || 'none',
-        package_manager: scanned?.package_manager || 'auto-detect',
-        test_framework: scanned?.test_framework || 'auto-detect'
-    };
-
-    data.database = data.database || scanned?.database || 'none';
-    data.uses_docker = typeof data.uses_docker === 'boolean' ? data.uses_docker : (scanned?.uses_docker ?? true);
-    data.cloud = data.cloud || scanned?.cloud || 'none';
-    data.package_manager = data.package_manager || scanned?.package_manager || 'auto-detect';
-    data.test_framework = data.test_framework || scanned?.test_framework || 'auto-detect';
-    data.framework_details = scanned?.framework_details || [];
-    data.scan_evidence = scanned?.scan_evidence || [];
-    data.app_root = scanned?.app_root || '.';
-
-    data.infrastructure = [];
-    if (data.uses_docker) data.infrastructure.push('docker');
-    if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
-
-    const shouldSetupMcp = args.includes('--setup-mcp') && !skipMcpSetup;
-
-    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
-
-    // Shared entry files are written after the .agent folder is available.
-
-    console.log(`  ${pc.green('OK')} Project context generation enabled; run thachvd-kit setup to install the promoted Matt Pocock skill set`);
-
-
-    const generatedFiles = [
-        ['AGENTS.md', generateSharedAgentsMd(data)],
-        ['CLAUDE.md', generateSharedClaudeMd()],
-        ['GEMINI.md', generateSharedGeminiMd()],
-        ['.cursorrules', generateSharedCursorrules(data)],
-        [path.join('.agent', 'docs', 'project.md'), generateProjectDoc(data)],
-        [path.join('.agent', 'docs', 'architecture.md'), generateArchitectureDoc(data)],
-        [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc()],
-        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()],
-        [path.join('.agent', 'docs', 'tooling.md'), generateToolingDoc(data)],
-        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()],
-        [path.join('.agent', 'docs', 'index-project-prompt.md'), generateIndexProjectPrompt()]
-    ];
-
-    for (const [relativePath, content] of generatedFiles) {
-        const wrote = await writeGeneratedFile(relativePath, content, assumeYes);
-        if (wrote) console.log(`  ${pc.green('OK')} Generated ${pc.bold(relativePath)}`);
-        else console.log(`  ${pc.yellow('~')} Skipped ${pc.bold(relativePath)}`);
-    }
-
-    if (shouldSetupMcp) {
-        console.log(`\n${pc.bold(pc.cyan('Configuring MCP'))}`);
-        for (const result of setupMcpServers()) {
-            const marker = result.ok ? pc.green('OK') : pc.yellow('~');
-            console.log(`  ${marker} ${result.message}`);
-        }
-    }
-
-    console.log(`\n${pc.bold(pc.green('Done!'))}
-
-  ${pc.bold('Project:')} ${data.project_name}
-  ${pc.bold('Stack:')}   ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
-
-  ${pc.bold('Generated:')}
-    - ${pc.bold('AGENTS.md')} shared entry for Codex, Antigravity, Claude Code, and Cursor
-    - ${pc.bold('CLAUDE.md')} Claude Code entry that imports AGENTS.md
-    - ${pc.bold('GEMINI.md')} Antigravity entry
-    - ${pc.bold('.cursorrules')} Cursor entry
-    - ${pc.bold('.agent/docs/')} scan-based project rules and local operating notes
-    - ${pc.bold('.agent/docs/index-project-prompt.md')} durable onboarding prompt
-
-  ${pc.bold('MCP/tooling setup:')}
-    - Matt Pocock's promoted skills (.agents/skills/) are the workflow layer
-    - Run ${pc.bold('thachvd-kit setup')} to install them and configure codebase-memory MCP and recommended RTK
-
-  ${pc.bold('Next steps:')}
-    1. Run ${pc.bold('thachvd-kit prompt')} and paste the saved prompt into your AI editor
-    2. Run ${pc.bold('thachvd-kit setup')} to install the promoted skill set and RTK
-    3. Run ${pc.bold('thachvd-kit doctor')} to verify the machine
-    4. Re-run ${pc.bold('thachvd-kit prompt')} whenever you need the onboarding prompt again
-
-  ${pc.bold('Onboarding prompt saved to .agent/docs/index-project-prompt.md:')}
-${pc.dim('---')}
-${generateIndexProjectPrompt().trim()}
-${pc.dim('---')}
-`);
-}
-
-main().catch(err => {
-    console.error(pc.red('\nError during init:'), err);
-    process.exit(1);
-});
-
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const prompts = require('prompts');
+const pc = require('picocolors');
+const packageJson = require('../package.json');
+const mattSkills = require('./matt-skills');
+const nativeSkills = require('./native-skills');
+const {
+    QUALITY_FLOOR_SECTION,
+    AGENT_RULES_SECTION,
+    CONVENTIONS_STANDARDS_SECTION,
+    FAST_PATH_SECTION,
+    GETTING_STARTED_FAST_PATH_SECTION,
+    TOOL_ROUTING_SECTION
+} = require('./policy');
+
+const sourceDir = path.resolve(__dirname, '..');
+const targetDir = process.cwd();
+const CODEBASE_MEMORY_PACKAGE = 'codebase-memory-mcp';
+const CODEBASE_MEMORY_BINARY = 'codebase-memory-mcp';
+const RTK_INSTALL_COMMAND = 'cargo install --git https://github.com/rtk-ai/rtk --branch master rtk';
+
+const FRAMEWORK_CHOICES = [
+    'vue', 'react', 'next', 'nuxt', 'svelte', 'angular',
+    'laravel', 'cakephp', 'symfony', 'codeigniter',
+    'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs',
+    'rails', 'spring', 'aspnet',
+    'tauri', 'axum', 'actix', 'flutter', 'react-native'
+];
+
+const LANGUAGE_CHOICES = ['typescript', 'javascript', 'python', 'go', 'php', 'rust', 'java', 'ruby', 'swift', 'kotlin', 'csharp', 'cpp'];
+const PROJECT_TYPE_CHOICES = ['web-app', 'api', 'mobile', 'desktop', 'cli', 'fullstack'];
+const DATABASE_CHOICES = ['postgres', 'mysql', 'sqlite', 'mongodb', 'redis', 'dynamodb', 'none'];
+const PACKAGE_MANAGER_CHOICES = ['npm', 'pnpm', 'yarn', 'bun', 'pip', 'uv', 'go mod', 'cargo', 'composer', 'auto-detect'];
+const TEST_FRAMEWORK_CHOICES = ['jest', 'vitest', 'pytest', 'go test', 'phpunit', 'pest', 'rspec', 'junit', 'auto-detect'];
+const CLOUD_CHOICES = ['aws', 'gcp', 'azure', 'vercel', 'fly', 'railway', 'none'];
+const FRONTEND_FRAMEWORKS = ['vue', 'react', 'next', 'nuxt', 'svelte', 'angular'];
+const BACKEND_FRAMEWORKS = ['laravel', 'cakephp', 'symfony', 'codeigniter', 'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs', 'rails', 'spring', 'aspnet', 'axum', 'actix'];
+const MOBILE_DESKTOP_FRAMEWORKS = ['tauri', 'flutter', 'react-native'];
+const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'build', 'coverage', '.next', '.nuxt', '.turbo', '.cache', 'storage', 'tmp']);
+
+function printHelp() {
+    console.log(`
+${pc.bold('Usage:')}
+  thachvd-kit init [--yes]
+  thachvd-kit upgrade [--dry-run]
+  thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
+  thachvd-kit setup [--yes] [--no-install-skills]
+  thachvd-kit doctor
+  thachvd-kit prompt
+  thachvd-kit skills install [--dry-run]
+  thachvd-kit skills check
+  thachvd-kit skills update [--dry-run]
+  thachvd-kit --version
+  thachvd-kit --help
+
+${pc.bold('Commands:')}
+  init      Generate project context files and documentation (new projects)
+  upgrade   Safely add/update thachvd-kit's managed policy blocks in an existing project (does not rescan or regenerate)
+  global    Patch a managed tool-routing block into the current user's Antigravity/Codex global instructions
+  setup     Install/configure MCP, Matt Pocock skills, and recommended local tooling
+  doctor    Check project context and local integrations
+  prompt    Print the saved project-indexing prompt again
+  skills    Install, check, or update the promoted Matt Pocock skill set
+
+${pc.bold('Options:')}
+  --yes     Overwrite generated files or accept setup defaults
+  --no-setup-mcp  Skip MCP setup (legacy init compatibility)
+  --no-setup-hook Skip the Claude Code Definition-of-Done Stop hook during setup
+  --no-install-rtk Skip auto-installing rtk via cargo during setup
+  --no-index      Skip auto-indexing the repository with codebase-memory-mcp during setup
+  --no-install-skills Skip installing Matt Pocock and thachvd-kit native skills during setup
+  --dry-run Preview a change without writing it (upgrade/global/skills install/skills update)
+  --antigravity-only Limit global to the Antigravity global instructions
+  --codex-only    Limit global to the Codex global instructions
+  --version Show the installed CLI version
+  --help    Show this help message
+
+${pc.bold('What gets generated:')}
+  AGENTS.md   Shared instructions for Codex, Antigravity, Claude Code, and Cursor
+  CLAUDE.md   Claude Code entry file that imports AGENTS.md
+  GEMINI.md   Antigravity entry file that points to AGENTS.md
+  .cursorrules Cursor entry file that points to AGENTS.md
+  .agent/docs/ Project context, architecture, workflow, tooling, and durable onboarding prompt
+
+${pc.bold('Workflow:')}
+  Matt Pocock's promoted skills plus thachvd-kit's native worktree/SDD skills
+  form the workflow layer. Use /using-git-worktrees only when isolation is
+  intended; choose /implement or /subagent-driven-development as alternative
+  executors for a plan, then finish with /code-review and
+  /finishing-a-development-branch.
+  Unsure which planning or implementation skill fits? Use /ask-matt.
+
+${pc.bold('Tip:')}
+  Run thachvd-kit setup to install the promoted skill set and configure
+  local tooling, then thachvd-kit doctor to verify the machine.
+`);
+}
+
+function formatScanPreviewLines(scanned) {
+    return [
+        ['App root', scanned.app_root || '.'],
+        ['Project type', scanned.project_type || 'unknown'],
+        ['Primary language', scanned.primary_language || 'unknown'],
+        ['Frameworks', (scanned.frameworks || []).join(', ') || 'no framework'],
+        ['Database', scanned.database || 'none'],
+        ['Package manager', scanned.package_manager || 'auto-detect'],
+        ['Test framework', scanned.test_framework || 'auto-detect'],
+        ['Cloud', scanned.cloud || 'none'],
+        ['Infrastructure', (scanned.infrastructure || []).join(', ') || 'none'],
+        ['CI/CD', scanned.ci_cd || 'none']
+    ];
+}
+
+async function askQuestions(questions) {
+    return prompts(questions, {
+        onCancel: () => {
+            console.log(pc.yellow('\nCancelled.'));
+            process.exit(130);
+        }
+    });
+}
+
+function fileExists(...parts) {
+    return fs.existsSync(path.join(targetDir, ...parts));
+}
+
+function fileExistsAt(baseDir, ...parts) {
+    return fs.existsSync(path.join(baseDir, ...parts));
+}
+
+function readJsonIfExists(...parts) {
+    const fullPath = path.join(targetDir, ...parts);
+    if (!fs.existsSync(fullPath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function readJsonIfExistsAt(baseDir, ...parts) {
+    const fullPath = path.join(baseDir, ...parts);
+    if (!fs.existsSync(fullPath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function readTextIfExists(...parts) {
+    const fullPath = path.join(targetDir, ...parts);
+    if (!fs.existsSync(fullPath)) return '';
+    try {
+        return fs.readFileSync(fullPath, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+function readTextIfExistsAt(baseDir, ...parts) {
+    const fullPath = path.join(baseDir, ...parts);
+    if (!fs.existsSync(fullPath)) return '';
+    try {
+        return fs.readFileSync(fullPath, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+function detectPackageManager(baseDir = targetDir) {
+    if (fileExistsAt(baseDir, 'pnpm-lock.yaml')) return 'pnpm';
+    if (fileExistsAt(baseDir, 'yarn.lock')) return 'yarn';
+    if (fileExistsAt(baseDir, 'bun.lockb') || fileExistsAt(baseDir, 'bun.lock')) return 'bun';
+    if (fileExistsAt(baseDir, 'package-lock.json')) return 'npm';
+    if (fileExistsAt(baseDir, 'uv.lock')) return 'uv';
+    if (fileExistsAt(baseDir, 'poetry.lock')) return 'pip';
+    if (fileExistsAt(baseDir, 'requirements.txt') || fileExistsAt(baseDir, 'pyproject.toml')) return 'pip';
+    if (fileExistsAt(baseDir, 'go.mod')) return 'go mod';
+    if (fileExistsAt(baseDir, 'Cargo.toml')) return 'cargo';
+    if (fileExistsAt(baseDir, 'composer.json')) return 'composer';
+    return 'auto-detect';
+}
+
+function uniq(values) {
+    return Array.from(new Set(values.filter(Boolean)));
+}
+
+function detectAppRoot(baseDir) {
+    const candidates = [baseDir];
+    const queue = [{ dir: baseDir, depth: 0 }];
+
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        if (depth >= 2) continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
+            const nextDir = path.join(dir, entry.name);
+            candidates.push(nextDir);
+            queue.push({ dir: nextDir, depth: depth + 1 });
+        }
+    }
+
+    const scoreCandidate = dir => {
+        let score = 0;
+        if (fileExistsAt(dir, 'composer.json')) score += 5;
+        if (fileExistsAt(dir, 'package.json')) score += 4;
+        if (fileExistsAt(dir, 'Cargo.toml')) score += 4;
+        if (fileExistsAt(dir, 'go.mod')) score += 4;
+        if (fileExistsAt(dir, 'pyproject.toml') || fileExistsAt(dir, 'requirements.txt')) score += 4;
+        if (fileExistsAt(dir, 'artisan')) score += 5;
+        if (fileExistsAt(dir, 'bin', 'cake') || fileExistsAt(dir, 'app', 'Config', 'core.php')) score += 5;
+        if (fileExistsAt(dir, 'src-tauri', 'tauri.conf.json') || fileExistsAt(dir, 'src-tauri', 'tauri.conf.json5')) score += 5;
+        if (fileExistsAt(dir, 'manage.py')) score += 4;
+        if (fileExistsAt(dir, 'Gemfile')) score += 4;
+        if (fileExistsAt(dir, 'pom.xml') || fileExistsAt(dir, 'build.gradle') || fileExistsAt(dir, 'build.gradle.kts')) score += 4;
+        if (fileExistsAt(dir, 'app', 'View') || fileExistsAt(dir, 'resources', 'views') || fileExistsAt(dir, 'templates') || fileExistsAt(dir, 'app', 'views')) score += 2;
+        return score;
+    };
+
+    const ranked = candidates
+        .map(dir => ({ dir, score: scoreCandidate(dir) }))
+        .filter(item => item.score > 0)
+        .sort((a, b) => (b.score - a.score) || (a.dir.length - b.dir.length));
+
+    return ranked[0]?.dir || baseDir;
+}
+
+function repoHasAny(baseDir, relativePaths, maxDepth = 3) {
+    const queue = [{ dir: baseDir, depth: 0 }];
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        for (const relativePath of relativePaths) {
+            if (fileExistsAt(dir, ...relativePath)) return true;
+        }
+        if (depth >= maxDepth) continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
+            queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+    }
+    return false;
+}
+
+function evidenceIf(condition, label, weight = 1) {
+    return condition ? { label, weight } : null;
+}
+
+function buildDetection(id, evidence, meta = {}) {
+    const hits = evidence.filter(Boolean);
+    const score = hits.reduce((sum, hit) => sum + hit.weight, 0);
+    return {
+        id,
+        score,
+        evidence: hits.map(hit => hit.label),
+        ...meta
+    };
+}
+
+function confidenceLabel(score) {
+    if (score >= 6) return 'high';
+    if (score >= 3) return 'medium';
+    return 'low';
+}
+
+function hasDependency(depNames, ...names) {
+    return names.some(name => depNames.has(name));
+}
+
+function hasComposerDependency(composerDepNames, ...names) {
+    return names.some(name => composerDepNames.has(name));
+}
+
+function hasRootFile(rootEntries, ...filenames) {
+    return filenames.some(name => rootEntries.has(name));
+}
+
+function textMatches(text, pattern) {
+    return Boolean(text && pattern.test(text));
+}
+
+const LANGUAGE_DETECTORS = [
+    {
+        id: 'typescript',
+        detect: ctx => buildDetection('typescript', [
+            evidenceIf(ctx.fileExists('tsconfig.json'), 'found tsconfig.json', 4),
+            evidenceIf(hasDependency(ctx.depNames, 'typescript', 'ts-node', 'tsx'), 'package.json -> typescript toolchain', 2)
+        ])
+    },
+    {
+        id: 'javascript',
+        detect: ctx => buildDetection('javascript', [
+            evidenceIf(ctx.fileExists('package.json'), 'found package.json', 2),
+            evidenceIf(ctx.depNames.size > 0, 'package.json -> JavaScript dependency graph', 1)
+        ])
+    },
+    {
+        id: 'python',
+        detect: ctx => buildDetection('python', [
+            evidenceIf(ctx.fileExists('requirements.txt'), 'found requirements.txt', 3),
+            evidenceIf(ctx.fileExists('pyproject.toml'), 'found pyproject.toml', 2),
+            evidenceIf(textMatches(ctx.pyprojectText, /\[tool\.(poetry|uv|hatch|pdm)\]/i), 'pyproject.toml -> Python tool section', 2)
+        ])
+    },
+    {
+        id: 'go',
+        detect: ctx => buildDetection('go', [
+            evidenceIf(ctx.fileExists('go.mod'), 'found go.mod', 4)
+        ])
+    },
+    {
+        id: 'php',
+        detect: ctx => buildDetection('php', [
+            evidenceIf(ctx.fileExists('composer.json'), 'found composer.json', 4),
+            evidenceIf(ctx.composerDepNames.size > 0, 'composer.json -> PHP dependency graph', 1)
+        ])
+    },
+    {
+        id: 'rust',
+        detect: ctx => buildDetection('rust', [
+            evidenceIf(ctx.fileExists('Cargo.toml'), 'found Cargo.toml', 4),
+            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 5)
+        ])
+    },
+    {
+        id: 'java',
+        detect: ctx => buildDetection('java', [
+            evidenceIf(ctx.fileExists('pom.xml'), 'found pom.xml', 4),
+            evidenceIf(ctx.fileExists('build.gradle') || ctx.fileExists('build.gradle.kts'), 'found Gradle build file', 3)
+        ])
+    },
+    {
+        id: 'ruby',
+        detect: ctx => buildDetection('ruby', [
+            evidenceIf(ctx.fileExists('Gemfile'), 'found Gemfile', 4),
+            evidenceIf(ctx.fileExists('config.ru'), 'found config.ru', 1)
+        ])
+    },
+    {
+        id: 'csharp',
+        detect: ctx => buildDetection('csharp', [
+            evidenceIf(ctx.rootEntries.some(name => name.endsWith('.sln') || name.endsWith('.csproj')), 'found .sln/.csproj', 4),
+            evidenceIf(ctx.fileExists('Program.cs'), 'found Program.cs', 1)
+        ])
+    }
+];
+
+const FRAMEWORK_DETECTORS = [
+    {
+        id: 'next',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('next', [
+            evidenceIf(hasDependency(ctx.depNames, 'next'), 'package.json -> next', 4),
+            evidenceIf(ctx.fileExists('next.config.js') || ctx.fileExists('next.config.mjs') || ctx.fileExists('next.config.ts'), 'found next.config.*', 3),
+            evidenceIf(ctx.fileExists('app') || ctx.fileExists('pages'), 'found app/ or pages/', 1)
+        ])
+    },
+    {
+        id: 'react',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('react', [
+            evidenceIf(hasDependency(ctx.depNames, 'react'), 'package.json -> react', 4),
+            evidenceIf(hasDependency(ctx.depNames, 'react-dom'), 'package.json -> react-dom', 2)
+        ])
+    },
+    {
+        id: 'vue',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('vue', [
+            evidenceIf(hasDependency(ctx.depNames, 'vue'), 'package.json -> vue', 4)
+        ])
+    },
+    {
+        id: 'nuxt',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('nuxt', [
+            evidenceIf(hasDependency(ctx.depNames, 'nuxt'), 'package.json -> nuxt', 4),
+            evidenceIf(ctx.fileExists('nuxt.config.ts') || ctx.fileExists('nuxt.config.js'), 'found nuxt.config.*', 3)
+        ])
+    },
+    {
+        id: 'svelte',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('svelte', [
+            evidenceIf(hasDependency(ctx.depNames, 'svelte', '@sveltejs/kit'), 'package.json -> svelte', 4)
+        ])
+    },
+    {
+        id: 'angular',
+        kind: 'frontend',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('angular', [
+            evidenceIf(hasDependency(ctx.depNames, '@angular/core'), 'package.json -> @angular/core', 4),
+            evidenceIf(ctx.fileExists('angular.json'), 'found angular.json', 3)
+        ])
+    },
+    {
+        id: 'express',
+        kind: 'backend',
+        language: 'javascript',
+        projectType: 'api',
+        detect: ctx => buildDetection('express', [
+            evidenceIf(hasDependency(ctx.depNames, 'express'), 'package.json -> express', 4)
+        ])
+    },
+    {
+        id: 'nestjs',
+        kind: 'backend',
+        language: 'javascript',
+        projectType: 'api',
+        detect: ctx => buildDetection('nestjs', [
+            evidenceIf(hasDependency(ctx.depNames, '@nestjs/core'), 'package.json -> @nestjs/core', 4)
+        ])
+    },
+    {
+        id: 'fastapi',
+        kind: 'backend',
+        language: 'python',
+        projectType: 'api',
+        detect: ctx => buildDetection('fastapi', [
+            evidenceIf(textMatches(ctx.requirementsText, /\bfastapi\b/i) || textMatches(ctx.pyprojectText, /\bfastapi\b/i), 'Python deps -> fastapi', 4)
+        ])
+    },
+    {
+        id: 'django',
+        kind: 'backend',
+        language: 'python',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('django', [
+            evidenceIf(textMatches(ctx.requirementsText, /\bdjango\b/i) || textMatches(ctx.pyprojectText, /\bdjango\b/i), 'Python deps -> django', 4),
+            evidenceIf(ctx.fileExists('manage.py'), 'found manage.py', 2),
+            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
+        ])
+    },
+    {
+        id: 'flask',
+        kind: 'backend',
+        language: 'python',
+        projectType: 'api',
+        detect: ctx => buildDetection('flask', [
+            evidenceIf(textMatches(ctx.requirementsText, /\bflask\b/i) || textMatches(ctx.pyprojectText, /\bflask\b/i), 'Python deps -> flask', 4)
+        ])
+    },
+    {
+        id: 'laravel',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('laravel', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'laravel/framework'), 'composer.json -> laravel/framework', 4),
+            evidenceIf(ctx.fileExists('artisan'), 'found artisan', 3),
+            evidenceIf(ctx.fileExists('resources', 'views'), 'found resources/views', 1)
+        ])
+    },
+    {
+        id: 'cakephp',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('cakephp', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'cakephp/cakephp'), 'composer.json -> cakephp/cakephp', 4),
+            evidenceIf(ctx.fileExists('bin', 'cake'), 'found bin/cake', 3),
+            evidenceIf(ctx.fileExists('config', 'app.php'), 'found config/app.php', 2),
+            evidenceIf(ctx.fileExists('app', 'Config', 'core.php'), 'found app/Config/core.php (CakePHP legacy)', 3),
+            evidenceIf(ctx.fileExists('app', 'Controller', 'AppController.php'), 'found app/Controller/AppController.php', 2),
+            evidenceIf(ctx.fileExists('app', 'Model', 'AppModel.php'), 'found app/Model/AppModel.php', 2),
+            evidenceIf(ctx.fileExists('lib', 'Cake'), 'found lib/Cake', 3),
+            evidenceIf(ctx.fileExists('cake', 'console', 'cake'), 'found cake/console/cake', 3),
+            evidenceIf(ctx.fileExists('app', 'View'), 'found app/View', 2),
+            evidenceIf(textMatches(ctx.viewFilesText, /\.ctp$/im), 'found .ctp view templates', 2)
+        ])
+    },
+    {
+        id: 'symfony',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('symfony', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'symfony/framework-bundle'), 'composer.json -> symfony/framework-bundle', 4),
+            evidenceIf(ctx.fileExists('bin', 'console'), 'found bin/console', 2),
+            evidenceIf(ctx.fileExists('config', 'bundles.php'), 'found config/bundles.php', 1),
+            evidenceIf(ctx.fileExists('templates'), 'found templates/', 1)
+        ])
+    },
+    {
+        id: 'codeigniter',
+        kind: 'backend',
+        language: 'php',
+        projectType: 'api',
+        detect: ctx => buildDetection('codeigniter', [
+            evidenceIf(hasComposerDependency(ctx.composerDepNames, 'codeigniter4/framework'), 'composer.json -> codeigniter4/framework', 4),
+            evidenceIf(ctx.fileExists('spark'), 'found spark', 2),
+            evidenceIf(ctx.fileExists('app', 'Config', 'App.php'), 'found app/Config/App.php', 1)
+        ])
+    },
+    {
+        id: 'gin',
+        kind: 'backend',
+        language: 'go',
+        projectType: 'api',
+        detect: ctx => buildDetection('gin', [
+            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gin-gonic\/gin\b/i), 'go.mod -> github.com/gin-gonic/gin', 4)
+        ])
+    },
+    {
+        id: 'fiber',
+        kind: 'backend',
+        language: 'go',
+        projectType: 'api',
+        detect: ctx => buildDetection('fiber', [
+            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/gofiber\/fiber\b/i), 'go.mod -> github.com/gofiber/fiber', 4)
+        ])
+    },
+    {
+        id: 'echo',
+        kind: 'backend',
+        language: 'go',
+        projectType: 'api',
+        detect: ctx => buildDetection('echo', [
+            evidenceIf(textMatches(ctx.goModText, /\bgithub\.com\/labstack\/echo\b/i), 'go.mod -> github.com/labstack/echo', 4)
+        ])
+    },
+    {
+        id: 'rails',
+        kind: 'backend',
+        language: 'ruby',
+        projectType: 'web-app',
+        detect: ctx => buildDetection('rails', [
+            evidenceIf(textMatches(ctx.gemfileText, /^\s*gem\s+["']rails["']/im), 'Gemfile -> rails', 4),
+            evidenceIf(ctx.fileExists('bin', 'rails'), 'found bin/rails', 2),
+            evidenceIf(ctx.fileExists('app', 'views'), 'found app/views', 1)
+        ])
+    },
+    {
+        id: 'spring',
+        kind: 'backend',
+        language: 'java',
+        projectType: 'api',
+        detect: ctx => buildDetection('spring', [
+            evidenceIf(textMatches(ctx.pomText, /spring-boot/i) || textMatches(ctx.gradleText, /spring-boot/i), 'Java build -> spring-boot', 4)
+        ])
+    },
+    {
+        id: 'aspnet',
+        kind: 'backend',
+        language: 'csharp',
+        projectType: 'api',
+        detect: ctx => buildDetection('aspnet', [
+            evidenceIf(textMatches(ctx.csprojText, /Microsoft\.NET\.Sdk\.Web/i), '.csproj -> Microsoft.NET.Sdk.Web', 4),
+            evidenceIf(textMatches(ctx.programCsText, /WebApplication\.CreateBuilder/i), 'Program.cs -> WebApplication.CreateBuilder', 2)
+        ])
+    },
+    {
+        id: 'tauri',
+        kind: 'desktop',
+        language: 'rust',
+        projectType: 'desktop',
+        detect: ctx => buildDetection('tauri', [
+            evidenceIf(hasDependency(ctx.depNames, '@tauri-apps/api'), 'package.json -> @tauri-apps/api', 4),
+            evidenceIf(ctx.fileExists('src-tauri', 'tauri.conf.json') || ctx.fileExists('src-tauri', 'tauri.conf.json5'), 'found src-tauri/tauri.conf.*', 4),
+            evidenceIf(ctx.fileExists('src-tauri', 'Cargo.toml'), 'found src-tauri/Cargo.toml', 2)
+        ])
+    },
+    {
+        id: 'axum',
+        kind: 'backend',
+        language: 'rust',
+        projectType: 'api',
+        detect: ctx => buildDetection('axum', [
+            evidenceIf(textMatches(ctx.cargoText, /\baxum\b/i), 'Cargo.toml -> axum', 4)
+        ])
+    },
+    {
+        id: 'actix',
+        kind: 'backend',
+        language: 'rust',
+        projectType: 'api',
+        detect: ctx => buildDetection('actix', [
+            evidenceIf(textMatches(ctx.cargoText, /\bactix-web\b/i), 'Cargo.toml -> actix-web', 4)
+        ])
+    },
+    {
+        id: 'flutter',
+        kind: 'mobile',
+        projectType: 'mobile',
+        detect: ctx => buildDetection('flutter', [
+            evidenceIf(textMatches(ctx.pubspecText, /^\s*flutter\s*:/im), 'pubspec.yaml -> flutter', 4)
+        ])
+    },
+    {
+        id: 'react-native',
+        kind: 'mobile',
+        projectType: 'mobile',
+        detect: ctx => buildDetection('react-native', [
+            evidenceIf(hasDependency(ctx.depNames, 'react-native', 'expo'), 'package.json -> react-native/expo', 4)
+        ])
+    }
+];
+
+function scanProject() {
+    const appRoot = detectAppRoot(targetDir);
+    const pkg = readJsonIfExistsAt(appRoot, 'package.json') || {};
+    const composer = readJsonIfExistsAt(appRoot, 'composer.json') || {};
+    const rootEntries = fs.existsSync(appRoot) ? fs.readdirSync(appRoot) : [];
+    const rootCsproj = rootEntries.find(name => name.endsWith('.csproj')) || '';
+    const deps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+        ...(pkg.peerDependencies || {})
+    };
+    const depNames = new Set(Object.keys(deps));
+    const composerDeps = {
+        ...(composer.require || {}),
+        ...(composer['require-dev'] || {})
+    };
+    const composerDepNames = new Set(Object.keys(composerDeps));
+    const ctx = {
+        pkg,
+        composer,
+        depNames,
+        composerDepNames,
+        rootEntries,
+        fileExists: (...parts) => fileExistsAt(appRoot, ...parts),
+        requirementsText: readTextIfExistsAt(appRoot, 'requirements.txt'),
+        pyprojectText: readTextIfExistsAt(appRoot, 'pyproject.toml'),
+        goModText: readTextIfExistsAt(appRoot, 'go.mod'),
+        pubspecText: readTextIfExistsAt(appRoot, 'pubspec.yaml'),
+        gemfileText: readTextIfExistsAt(appRoot, 'Gemfile'),
+        pomText: readTextIfExistsAt(appRoot, 'pom.xml'),
+        gradleText: `${readTextIfExistsAt(appRoot, 'build.gradle')}\n${readTextIfExistsAt(appRoot, 'build.gradle.kts')}`,
+        cargoText: `${readTextIfExistsAt(appRoot, 'Cargo.toml')}\n${readTextIfExistsAt(appRoot, 'src-tauri', 'Cargo.toml')}`,
+        csprojText: rootCsproj ? readTextIfExistsAt(appRoot, rootCsproj) : '',
+        programCsText: readTextIfExistsAt(appRoot, 'Program.cs'),
+        viewFilesText: fs.existsSync(path.join(appRoot, 'app', 'View'))
+            ? fs.readdirSync(path.join(appRoot, 'app', 'View'), { recursive: true }).join('\n')
+            : ''
+    };
+
+    const languageDetections = LANGUAGE_DETECTORS
+        .map(detector => detector.detect(ctx))
+        .filter(result => result.score >= 2)
+        .sort((a, b) => b.score - a.score);
+
+    const frameworkDetails = FRAMEWORK_DETECTORS
+        .map(detector => {
+            const result = detector.detect(ctx);
+            if (result.score < 3) return null;
+            return {
+                ...result,
+                kind: detector.kind,
+                language: detector.language,
+                projectType: detector.projectType,
+                confidence: confidenceLabel(result.score)
+            };
+        })
+        .filter(Boolean)
+        .sort((a, b) => b.score - a.score);
+
+    const frameworkLanguageScores = frameworkDetails.reduce((acc, item) => {
+        if (!item.language) return acc;
+        acc[item.language] = (acc[item.language] || 0) + item.score;
+        return acc;
+    }, {});
+    const primaryLanguage = Object.keys(frameworkLanguageScores).sort((a, b) => frameworkLanguageScores[b] - frameworkLanguageScores[a])[0]
+        || languageDetections[0]?.id
+        || 'typescript';
+    const frameworks = uniq(frameworkDetails.map(item => item.id)).filter(name => FRAMEWORK_CHOICES.includes(name));
+    const infrastructure = [];
+    let projectType = '';
+    let database = 'none';
+    let testFramework = 'auto-detect';
+    let cloud = 'none';
+    let ciCd = 'none';
+
+    if (frameworkDetails.some(item => item.projectType === 'desktop')) projectType = 'desktop';
+    else if (frameworkDetails.some(item => item.projectType === 'mobile')) projectType = 'mobile';
+    else if (frameworkDetails.some(item => item.kind === 'frontend') && frameworkDetails.some(item => item.kind === 'backend')) projectType = 'fullstack';
+    else if (frameworkDetails.some(item => item.projectType === 'web-app')) projectType = 'web-app';
+    else if (frameworkDetails.some(item => item.kind === 'backend')) projectType = 'api';
+    else if (frameworkDetails.some(item => item.kind === 'frontend')) projectType = 'web-app';
+    else if (fileExistsAt(appRoot, 'package.json') && pkg.bin) projectType = 'cli';
+    else if (['php', 'python', 'go', 'java', 'ruby', 'csharp', 'rust'].includes(primaryLanguage)) projectType = 'api';
+
+    if (hasDependency(depNames, 'pg', 'postgres', '@prisma/client') || /postgres/i.test(JSON.stringify(pkg))) database = 'postgres';
+    else if (hasDependency(depNames, 'mysql', 'mysql2')) database = 'mysql';
+    else if (hasDependency(depNames, 'sqlite3', 'better-sqlite3', 'rusqlite')) database = 'sqlite';
+    else if (hasDependency(depNames, 'mongodb', 'mongoose')) database = 'mongodb';
+    else if (hasDependency(depNames, 'redis', 'ioredis')) database = 'redis';
+    else if (hasDependency(depNames, '@aws-sdk/client-dynamodb')) database = 'dynamodb';
+
+    if (hasDependency(depNames, 'vitest')) testFramework = 'vitest';
+    else if (hasDependency(depNames, 'jest')) testFramework = 'jest';
+    else if (hasDependency(depNames, 'pytest') || textMatches(ctx.requirementsText, /\bpytest\b/i) || textMatches(ctx.pyprojectText, /\bpytest\b/i)) testFramework = 'pytest';
+    else if (hasComposerDependency(composerDepNames, 'phpunit/phpunit')) testFramework = 'phpunit';
+    else if (hasComposerDependency(composerDepNames, 'pestphp/pest')) testFramework = 'pest';
+    else if (fileExistsAt(appRoot, 'go.mod')) testFramework = 'go test';
+    else if (textMatches(ctx.gemfileText, /^\s*gem\s+["']rspec["']/im)) testFramework = 'rspec';
+
+    if (repoHasAny(targetDir, [['Dockerfile'], ['docker-compose.yml'], ['docker-compose.yaml']])) {
+        infrastructure.push('docker');
+    }
+
+    if (repoHasAny(targetDir, [['vercel.json']])) {
+        cloud = 'vercel';
+        infrastructure.push('vercel');
+    } else if (repoHasAny(targetDir, [['fly.toml']])) {
+        cloud = 'fly';
+        infrastructure.push('fly');
+    } else if (repoHasAny(targetDir, [['railway.json'], ['railway.toml']])) {
+        cloud = 'railway';
+        infrastructure.push('railway');
+    }
+
+    if (repoHasAny(targetDir, [['.github', 'workflows'], ['.gitlab-ci.yml'], ['.circleci', 'config.yml'], ['Jenkinsfile']], 2)) {
+        if (repoHasAny(targetDir, [['.github', 'workflows']], 2)) ciCd = 'github-actions';
+        else if (repoHasAny(targetDir, [['.gitlab-ci.yml']], 2)) ciCd = 'gitlab-ci';
+        else if (repoHasAny(targetDir, [['.circleci', 'config.yml']], 2)) ciCd = 'circleci';
+        else if (repoHasAny(targetDir, [['Jenkinsfile']], 2)) ciCd = 'jenkins';
+    }
+
+    const scanEvidence = [
+        ...(languageDetections[0] ? [`language:${languageDetections[0].id} => ${languageDetections[0].evidence.join('; ')}`] : []),
+        ...frameworkDetails.map(item => `${item.id} [${item.confidence}] => ${item.evidence.join('; ')}`)
+    ];
+
+    return {
+        project_name: path.basename(targetDir),
+        app_root: path.relative(targetDir, appRoot) || '.',
+        description: pkg.description || composer.description || 'A software project',
+        project_type: PROJECT_TYPE_CHOICES.includes(projectType) ? projectType : 'web-app',
+        primary_language: LANGUAGE_CHOICES.includes(primaryLanguage) ? primaryLanguage : 'typescript',
+        frameworks,
+        framework_details: frameworkDetails,
+        scan_evidence: scanEvidence,
+        database: DATABASE_CHOICES.includes(database) ? database : 'none',
+        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager(appRoot)) ? detectPackageManager(appRoot) : 'auto-detect',
+        uses_docker: infrastructure.includes('docker'),
+        cloud,
+        infrastructure: uniq(infrastructure),
+        ci_cd: ciCd,
+        test_framework: TEST_FRAMEWORK_CHOICES.includes(testFramework) ? testFramework : 'auto-detect',
+        code_style: 'project-standard',
+        architecture_notes: '<!-- Add notes -->',
+        current_phase: 'Initial setup',
+        next_phase: '-',
+        known_issues: '<!-- None yet -->'
+    };
+}
+// --- File Generators ---
+
+function generateSharedAgentsMd(data) {
+    return `# AGENTS.md
+
+Shared operating instructions for Codex, Antigravity, Claude Code, and Cursor.
+
+## Startup
+
+1. Read this file first.
+2. Read \`.agent/docs/project.md\` for detected stack, commands, and routing.
+3. Read \`.agent/docs/workflow.md\` for the task flow before editing.
+4. Read \`.agent/docs/architecture.md\` and \`.agent/docs/conventions.md\` before planning code changes.
+5. Read \`.agent/docs/tooling.md\` when the task needs MCP, RTK, or browser verification.
+
+If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
+
+## Workflow
+
+Matt Pocock's promoted skills (installed under \`.agents/skills/\` by \`thachvd-kit setup\`) are the workflow layer. Use the matching skill when a specialized workflow is useful:
+
+- Clear, localized change: inspect -> edit -> focused verification. Do not force a heavyweight skill.
+- Ambiguous feature or design: \`/grill-with-docs\`, then optionally \`/to-spec\` for a durable contract.
+- Normal feature: \`/grill-with-docs\` -> \`/to-spec\` -> \`/implement\`.
+- Large feature needing decomposition: add \`/to-tickets\` before \`/implement\`.
+- Huge, multi-session uncertainty: \`/wayfinder\`.
+- Bug or failing behavior: \`/diagnosing-bugs\`.
+- Test-driven implementation: \`/tdd\` (skip the ceremony for trivial config/text changes).
+- Architecture survey: \`/improve-codebase-architecture\`; use \`/codebase-design\` as the design vocabulary.
+- Pre-completion review: \`/code-review\` once when code risk warrants it.
+
+If unsure which skill fits, use \`/ask-matt\`.
+
+Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, use the matching planning skill above instead.
+
+See \`.agent/docs/workflow.md\` for the full route matrix. This kit does not implement a second workflow engine; it only installs and checks the promoted skill set (\`thachvd-kit skills install|check|update\`).
+
+${QUALITY_FLOOR_SECTION}
+
+${AGENT_RULES_SECTION}
+
+## Shared Knowledge
+
+- Project context: \`.agent/docs/\`
+- Tooling setup: \`.agent/docs/tooling.md\`
+- Matt Pocock skills: promoted set installed under \`.agents/skills/\` via \`thachvd-kit skills install\`
+- RTK: recommended local CLI for compact command output
+- Antigravity and Cursor entry rules: \`GEMINI.md\` and \`.cursorrules\`
+`;
+}
+
+function generateIndexProjectPrompt() {
+    return `# Project Indexing Prompt
+
+Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
+Use the project's Matt Pocock skills for workflow (see AGENTS.md; run /ask-matt if unsure which fits) and use codebase-memory MCP for structural code discovery when available.
+Ask me what this project does and any important conventions I want preserved.
+Then scan this repository and refine the generated context docs with factual rules.
+Do not implement product code during onboarding.
+`;
+}
+
+function printProjectPrompt() {
+    const promptPath = path.join(targetDir, '.agent', 'docs', 'index-project-prompt.md');
+    if (!fs.existsSync(promptPath)) {
+        console.error(pc.yellow('No saved project prompt found. Run thachvd-kit init first.'));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(fs.readFileSync(promptPath, 'utf8'));
+}
+
+function generateSharedClaudeMd() {
+    return `@AGENTS.md
+
+## Claude Code
+
+This repository uses AGENTS.md as the shared cross-agent entry file. Follow the imported instructions and keep Claude-specific notes here only when they cannot apply to Codex or Antigravity.
+`;
+}
+
+function generateSharedGeminiMd() {
+    return `# GEMINI.md
+
+Antigravity entry file for this project.
+
+Read AGENTS.md first, then follow the shared docs under .agent/docs/.
+`;
+}
+
+function generateSharedCursorrules(data) {
+    return `# Cursor Rules
+
+This repository uses AGENTS.md as the shared cross-agent entry file. Follow the instructions in AGENTS.md and keep Cursor-specific notes here only when they cannot apply to Codex, Antigravity, or Claude Code.
+
+Read AGENTS.md first, then follow the shared docs under .agent/docs/.
+
+---
+
+${generateSharedAgentsMd(data).trimEnd()}
+`;
+}
+
+function resolveCommands(data) {
+    const frameworks = data.frameworks || [];
+    const primaryLang = data.primary_language || 'javascript';
+    const pkgManager = data.package_manager || 'npm';
+    const testFramework = data.test_framework || 'auto-detect';
+
+    const isPython = primaryLang === 'python';
+    const isGo = primaryLang === 'go';
+    const isRust = primaryLang === 'rust';
+    const isPhp = primaryLang === 'php';
+
+    let install = 'npm install';
+    let dev = 'npm run dev';
+    let build = 'npm run build';
+    let test = 'npm test';
+    let lint = 'npm run lint';
+
+    if (pkgManager === 'pnpm') { install = 'pnpm install'; dev = 'pnpm dev'; build = 'pnpm build'; test = 'pnpm test'; lint = 'pnpm lint'; }
+    else if (pkgManager === 'yarn') { install = 'yarn'; dev = 'yarn dev'; build = 'yarn build'; test = 'yarn test'; lint = 'yarn lint'; }
+    else if (pkgManager === 'bun') { install = 'bun install'; dev = 'bun dev'; build = 'bun run build'; test = 'bun test'; lint = 'bun run lint'; }
+    else if (isPython) { install = 'pip install -r requirements.txt'; dev = 'python manage.py runserver'; build = '# no build step'; test = 'pytest'; lint = 'ruff check .'; }
+    else if (isGo) { install = 'go mod download'; dev = 'go run .'; build = 'go build ./...'; test = 'go test ./...'; lint = 'golangci-lint run'; }
+    else if (isRust) { install = 'cargo build'; dev = 'cargo run'; build = 'cargo build --release'; test = 'cargo test'; lint = 'cargo clippy'; }
+    else if (isPhp) {
+        install = 'composer install';
+        build = '# no build step';
+        test = testFramework === 'pest' ? './vendor/bin/pest' : './vendor/bin/phpunit';
+        const isCakePHP = frameworks.some(f => f.toLowerCase().includes('cakephp'));
+        const isSymfony = frameworks.some(f => f.toLowerCase().includes('symfony'));
+        const isCodeIgniter = frameworks.some(f => f.toLowerCase().includes('codeigniter'));
+        if (isCakePHP) {
+            dev = 'bin/cake server';
+            lint = './vendor/bin/phpcs';
+        } else if (isSymfony) {
+            dev = 'bin/console server:run';
+            lint = './vendor/bin/phpcs';
+        } else if (isCodeIgniter) {
+            dev = 'php spark serve';
+            lint = './vendor/bin/phpcs';
+        } else {
+            dev = 'php artisan serve';
+            lint = 'php artisan pint';
+        }
+    }
+
+    if (testFramework === 'vitest') test = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : pkgManager === 'bun' ? 'bun run' : 'npx'} vitest`;
+    else if (testFramework === 'jest') test = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : 'npx'} jest`;
+
+    return { install, dev, build, test, lint };
+}
+
+function generateProjectDoc(data) {
+    const commands = resolveCommands(data);
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- TODO: refine scan evidence by inspecting the project.';
+
+    return `# Project Rules
+
+Generated by thachvd-kit on ${new Date().toISOString().split('T')[0]}.
+
+## Summary
+
+- Name: ${data.project_name}
+- Description: ${data.description}
+- Type: ${data.project_type}
+- App root: ${data.app_root || '.'}
+
+## Stack
+
+- Language: ${data.primary_language}
+- Frameworks: ${(data.frameworks || []).join(', ') || 'none'}
+- Database: ${data.database || 'none'}
+- Infrastructure: ${(data.infrastructure || []).join(', ') || 'none'}
+- Package manager: ${data.package_manager || 'auto-detect'}
+- Test framework: ${data.test_framework || 'auto-detect'}
+
+## Commands
+
+- Install: \`${commands.install}\`
+- Dev: \`${commands.dev}\`
+- Build: \`${commands.build}\`
+- Test: \`${commands.test}\`
+- Lint: \`${commands.lint}\`
+
+## Available Integrations
+
+Use these integrations when available. Run thachvd-kit doctor to check the current machine.
+
+| MCP | When to Use |
+|-----|-------------|
+| \`codebase-memory-mcp\` | Explore symbols, trace call chains, architecture, and impact |
+| \`context7\` | Look up library/framework docs, API signatures, migration guides |
+| \`playwright\` | Verify UI behavior, take screenshots, test forms and navigation |
+| \`rtk\` | Recommended proxy for noisy git, tests, builds, and package commands |
+
+> Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
+
+## Scan Evidence
+
+${evidence}
+`;
+}
+
+function generateArchitectureDoc(data) {
+    const appRootLine = data.app_root && data.app_root !== '.'
+        ? `- App root is currently detected as \`${data.app_root}\`.`
+        : '- App root is the repository root unless refined below.';
+    const evidence = (data.scan_evidence || []).length > 0
+        ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
+        : '- TODO: refine architecture by scanning source directories.';
+
+    return `# Architecture Notes
+
+## Current Map
+
+${appRootLine}
+- TODO: refine major directories and responsibilities.
+- TODO: refine main entry points, routing, state boundaries, and integration boundaries.
+
+## Detected Evidence
+
+${evidence}
+
+## AI Maintenance Rule
+
+Before non-trivial implementation work, inspect this file. If it is stale or still contains TODO items relevant to the task, update it from the code before editing product code.
+`;
+}
+
+function generateConventionsDoc() {
+    return `# Coding Conventions
+
+${CONVENTIONS_STANDARDS_SECTION}
+
+${QUALITY_FLOOR_SECTION}
+
+## Verification
+
+- Run the focused test or lint command that matches the touched area.
+- If no automated check exists, document the manual verification performed.
+- For UI/web changes, prioritize using Playwright MCP to automatically verify client-side behavior and capture screenshots.
+- Do not claim completion without verification evidence.
+`;
+}
+
+function generateWorkflowDoc() {
+    return `# Agent Workflow
+
+This project uses Matt Pocock's promoted skills plus thachvd-kit's native workflow skills (installed under .agents/skills/ and .claude/skills/ by \`thachvd-kit setup\`) as the workflow layer. Native skills add opt-in workspace isolation, subagent-driven execution, and branch finishing; they do not replace Matt's planning, implementation, testing, or review skills.
+
+## Before Every Task
+
+1. Read AGENTS.md and the relevant files under .agent/docs/.
+2. Use the promoted skill that matches the request, or run /ask-matt if unsure which one fits.
+3. Use codebase-memory MCP for structural discovery when available.
+4. Make changes only after the required planning gate for that situation.
+5. Verify the change and request review before completion.
+
+## Route Matrix
+
+| Situation | Skill | Gate |
+|---|---|---|
+| Question or research only | direct answer or research | no product-code edits |
+| Clear, localized change | fast path (no skill) | inspect -> edit -> focused verify |
+| Ambiguous feature or design | /grill-with-docs, then optionally /to-spec | durable contract before implementation when useful |
+| Normal feature | /grill-with-docs -> /to-spec -> choose workspace -> /implement | spec agreed before implementation |
+| Large feature needing decomposition | /grill-with-docs -> /to-spec -> /to-tickets -> choose workspace -> executor | tickets agreed before implementation |
+| Huge, multi-session uncertainty | /wayfinder | shared decision map before implementation |
+| Bug or failing behavior | /diagnosing-bugs | reproduce -> root cause -> regression protection -> fix -> verify |
+| Test-driven implementation | /tdd | red -> green -> refactor per slice |
+| Architecture survey | /improve-codebase-architecture (+ /codebase-design vocabulary) | findings reviewed before large refactors |
+| Pre-merge | /code-review | blocking findings resolved |
+
+Not sure which row applies? Run /ask-matt instead of guessing.
+
+## Standard Feature Flow
+
+/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> choose workspace -> choose executor (/implement or /subagent-driven-development) -> /code-review -> /finishing-a-development-branch.
+
+Choose the current branch/workspace when the user explicitly wants to work there. Use /using-git-worktrees only when isolation is requested or appropriate workspace isolation already exists. SDD is for plans with multiple relatively independent tasks and falls back to /implement when subagent dispatch is unavailable; it never forces a worktree.
+
+${FAST_PATH_SECTION}
+
+## Documentation Maintenance
+
+- Update architecture.md when structure or boundaries change.
+- Update conventions.md when repeated project patterns become clear.
+- Update project.md when stack, scripts, or test tooling changes.
+- Keep AGENTS.md concise and put project-specific detail under .agent/docs/.
+`;
+}
+
+function generateGettingStartedDoc() {
+    return `# Getting Started
+
+thachvd-kit creates project context. Matt Pocock's promoted and thachvd-kit native skills own the development workflow.
+
+## Setup
+
+1. Run \`thachvd-kit init\` in the repository.
+2. Open or print \`.agent/docs/index-project-prompt.md\` with \`thachvd-kit prompt\`.
+3. Run \`thachvd-kit setup\` (installs promoted and native skill sets by default; add \`--no-install-skills\` to skip) and RTK.
+4. Inside the AI client, run \`/setup-matt-pocock-skills\` once to configure the issue tracker, triage labels, and doc layout.
+5. Run \`thachvd-kit doctor\` and restart the AI client.
+
+## Standard Flow
+
+1. \`/grill-with-docs\` for unclear requirements or design.
+2. \`/to-spec\` when a durable implementation contract is useful.
+3. \`/to-tickets\` for large work that benefits from decomposition.
+4. \`/implement\`, with \`/tdd\` where red-green-refactor helps.
+5. \`/code-review\` once before completion.
+
+Not sure which skill fits? Run \`/ask-matt\`.
+
+## Bug Flow
+
+Use \`/diagnosing-bugs\`: reproduce the symptom, inspect the path with codebase-memory MCP, test hypotheses, add regression protection, fix the root cause, and verify.
+
+${GETTING_STARTED_FAST_PATH_SECTION}
+`;
+}
+
+function resolveToolingSetup(data) {
+    const primaryLang = data.primary_language || 'javascript';
+    const packageManager = data.package_manager || 'npm';
+    const isPython = primaryLang === 'python';
+    const runner = packageManager === 'pnpm'
+        ? 'pnpm dlx'
+        : packageManager === 'yarn'
+            ? 'yarn dlx'
+            : packageManager === 'bun'
+                ? 'bunx'
+                : 'npx';
+    const playwrightCommand = isPython
+        ? 'pip install playwright && playwright install chromium'
+        : `${runner} playwright install`;
+
+    return { runner, playwrightCommand };
+}
+
+function generateToolingDoc(data) {
+    const { runner, playwrightCommand } = resolveToolingSetup(data);
+
+    return `# Optional Tooling
+
+Run \`thachvd-kit doctor\` to check the current machine.
+
+## Matt Pocock Skills + Native Workflow Skills
+
+Matt Pocock's promoted engineering and productivity skills are installed project-locally under \`.agents/skills/\` (never globally). thachvd-kit also bundles native workflow skills to both \`.agents/skills/\` and \`.claude/skills/\`:
+
+- Install the promoted set: \`thachvd-kit skills install\` (\`--dry-run\` to preview the command without running it)
+- Check what is installed: \`thachvd-kit skills check\` (read-only)
+- Update the promoted set: \`thachvd-kit skills update\` (re-adds each skill individually for safety, so it is slower than install — one network clone per skill)
+- The full manifest lives in \`bin/matt-skills.js\` (\`PROMOTED_SKILLS\`); it mirrors upstream's \`skills/engineering/\` + \`skills/productivity/\` catalog and never includes \`in-progress\`, \`misc\`, or \`deprecated\` skills.
+- After the first install, run \`/setup-matt-pocock-skills\` once inside the AI client to configure the issue tracker, triage labels, and generated docs location. thachvd-kit does not simulate that skill.
+- Unsure which skill fits a task? Run \`/ask-matt\`.
+- Native skills: \`/using-git-worktrees\` (opt-in isolation), \`/subagent-driven-development\` (alternative executor for multi-task plans), and \`/finishing-a-development-branch\`.
+- SDD's upstream shell scripts are retained for provenance; cross-platform Node entrypoints are used by the adapted workflow on Windows.
+
+${TOOL_ROUTING_SECTION}
+
+## Codebase Memory MCP
+
+Use \`codebase-memory-mcp\` for symbol search, call paths, architecture, and impact analysis.
+
+- Install: \`npm install -g codebase-memory-mcp\`
+- Index a repository: \`codebase-memory-mcp cli index_repository --repo-path .\`
+- Keep local index state out of git unless the team explicitly chooses a shared snapshot.
+
+## RTK
+
+RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands.
+
+- Install: \`cargo install --git https://github.com/rtk-ai/rtk --branch master rtk\`
+- Examples: \`rtk git status\`, \`rtk npm test\`, \`rtk git log\`.
+- If it is unavailable, run the underlying command directly.
+
+## Playwright
+
+- Check: \`${runner} playwright --version\`
+- Browser install: \`${playwrightCommand}\`
+- Use the project's existing Playwright scripts when available.
+`;
+}
+
+async function writeGeneratedFile(relativePath, content, assumeYes) {
+    const outputPath = path.join(targetDir, relativePath);
+    const exists = fs.existsSync(outputPath);
+    if (exists && !assumeYes) {
+        const response = await prompts({
+            type: 'confirm',
+            name: 'overwrite',
+            message: `File ${pc.bold(relativePath)} already exists. Do you want to overwrite it?`,
+            initial: false
+        });
+        if (response.overwrite === undefined) {
+            console.log(pc.yellow('\nCancelled.'));
+            process.exit(130);
+        }
+        if (!response.overwrite) return false;
+    }
+
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, content, 'utf8');
+    return true;
+}
+
+function homePath(...parts) {
+    const home = process.env.USERPROFILE || process.env.HOME;
+    return home ? path.join(home, ...parts) : null;
+}
+
+function printMattSkillsSetupReminder() {
+    console.log(`  Run ${pc.bold('/setup-matt-pocock-skills')} once inside your AI client to configure the issue tracker, triage labels, and generated docs location.`);
+}
+
+function runDoctor() {
+    console.log(pc.bold(pc.cyan('thachvd-kit doctor')));
+    const requiredFiles = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.cursorrules',
+        path.join('.agent', 'docs', 'project.md'), path.join('.agent', 'docs', 'workflow.md')];
+    for (const relativePath of requiredFiles) {
+        const ok = fs.existsSync(path.join(targetDir, relativePath));
+        console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${relativePath}`);
+    }
+
+    const tools = [
+        [CODEBASE_MEMORY_BINARY, `npm install -g ${CODEBASE_MEMORY_PACKAGE}`],
+        ['rtk', `recommended: ${RTK_INSTALL_COMMAND}`]
+    ];
+    console.log(`\n${pc.bold('Local integrations (RTK recommended)')}`);
+    for (const [binary, hint] of tools) {
+        const ok = commandExists(binary);
+        console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${binary}${ok ? '' : ` - ${hint}`}`);
+    }
+
+    console.log(`\n${pc.bold('Matt Pocock skills')}`);
+    const skillStatus = mattSkills.checkSkills(targetDir);
+    if (skillStatus.missing.length === 0) {
+        console.log(`  ${pc.green('OK')} promoted skill set installed (${skillStatus.total}/${skillStatus.total})`);
+    } else {
+        console.log(`  ${pc.yellow('WARN')} ${skillStatus.missing.length} promoted skill(s) missing`);
+        console.log(`       Run: ${pc.bold('thachvd-kit skills install')}`);
+    }
+    const setupSkillOk = mattSkills.isSkillInstalled(targetDir, mattSkills.SETUP_SKILL_NAME);
+    console.log(`  ${setupSkillOk ? pc.green('OK') : pc.yellow('WARN')} ${mattSkills.SETUP_SKILL_NAME} available`);
+    console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+    const nativeStatus = nativeSkills.checkNativeSkills(targetDir);
+    for (const name of nativeSkills.NATIVE_SKILLS) {
+        const status = nativeStatus.skills[name];
+        console.log(`  ${status.agents && status.claude ? pc.green('OK') : pc.yellow('WARN')} ${name} (.agents: ${status.agents ? 'installed' : 'missing'}, .claude: ${status.claude ? 'installed' : 'missing'})`);
+    }
+    for (const surface of nativeSkills.NATIVE_SKILL_SURFACES) {
+        const support = nativeStatus.surfaces[surface.id].support;
+        const status = support.missing.length === 0 ? pc.green('OK') : pc.yellow('WARN');
+        console.log(`  ${status} support files (${surface.relativeDir}: ${support.missing.length === 0 ? 'installed' : 'missing'})`);
+    }
+    const contextMdExists = fs.existsSync(path.join(targetDir, 'CONTEXT.md'));
+    const docsAdrExists = fs.existsSync(path.join(targetDir, 'docs', 'adr'));
+    console.log(`  ${pc.dim('-')} CONTEXT.md ${contextMdExists ? 'detected' : 'not created yet (informational only)'}`);
+    console.log(`  ${pc.dim('-')} docs/adr ${docsAdrExists ? 'detected' : 'not created yet (informational only)'}`);
+
+    console.log(`\n${pc.bold('Next step')}`);
+    console.log('  Run thachvd-kit prompt to print the saved project-indexing prompt.');
+}
+
+async function runSetup(args) {
+    const skipMcpSetup = args.includes('--no-setup-mcp');
+    const skipHookSetup = args.includes('--no-setup-hook');
+    const skipRtkInstall = args.includes('--no-install-rtk');
+    const skipIndex = args.includes('--no-index');
+    const skipSkillsInstall = args.includes('--no-install-skills');
+    console.log(pc.bold(pc.cyan('thachvd-kit setup')));
+    if (!skipSkillsInstall) {
+        console.log(pc.bold('Matt Pocock skills'));
+        const skillStatus = mattSkills.checkSkills(targetDir);
+        if (skillStatus.missing.length === 0) {
+            // Already fully installed: `setup` only ensures presence, it
+            // never re-installs or updates on its own. Explicit
+            // `thachvd-kit skills update` is required for that.
+            console.log(`  ${pc.green('OK')} promoted skill set already installed (${skillStatus.total}/${skillStatus.total})`);
+        } else {
+            const skillsResult = mattSkills.installSkills(targetDir);
+            const skillsMarker = skillsResult.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${skillsMarker} ${skillsResult.message}`);
+        }
+        printMattSkillsSetupReminder();
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        const nativeStatus = nativeSkills.checkNativeSkills(targetDir);
+        if (nativeStatus.allInstalled) {
+            console.log(`  ${pc.green('OK')} native skill set already installed (${nativeStatus.total}/${nativeStatus.total})`);
+        } else {
+            const nativeResult = nativeSkills.installNativeSkills(targetDir);
+            const nativeMarker = nativeResult.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${nativeMarker} ${nativeResult.message}`);
+        }
+    } else {
+        console.log(`${pc.bold('Matt Pocock skills')}\n  ${pc.dim('skipped (--no-install-skills)')}`);
+        console.log(`${pc.bold('thachvd-kit native skills')}\n  ${pc.dim('skipped (--no-install-skills)')}`);
+    }
+    if (!skipMcpSetup) {
+        console.log(pc.bold('MCP setup'));
+        for (const result of setupMcpServers({ install: true })) {
+            const marker = result.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${marker} ${result.message}`);
+        }
+        if (!skipIndex) {
+            const indexResult = indexRepository();
+            const marker = indexResult.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${marker} ${indexResult.message}`);
+        }
+    }
+    if (!skipHookSetup) {
+        console.log(`\n${pc.bold('Claude Code Definition-of-Done hook')}`);
+        const claudeProjectSettings = path.join(targetDir, '.claude', 'settings.json');
+        const result = mergeClaudeProjectHooks(claudeProjectSettings);
+        const marker = result.ok ? pc.green('OK') : pc.yellow('WARN');
+        console.log(`  ${marker} ${result.message}`);
+        console.log('  This hook only checks for plan/review/verification evidence; it never prescribes which skill produces it.');
+    }
+    console.log(`\n${pc.bold('RTK (recommended)')}`);
+    const rtkResult = ensureRtkInstalled(!skipRtkInstall);
+    const rtkMarker = rtkResult.ok ? pc.green('OK') : pc.yellow('WARN');
+    console.log(`  ${rtkMarker} ${rtkResult.message}`);
+    console.log('\nRestart your AI client after installing plugins or changing MCP configuration.');
+    console.log('Your onboarding prompt is saved at .agent/docs/index-project-prompt.md. Run thachvd-kit prompt to print it again.');
+}
+
+function commandExists(command) {
+    const checker = process.platform === 'win32' ? 'where' : 'command';
+    const args = process.platform === 'win32' ? [command] : ['-v', command];
+    const result = spawnSync(checker, args, { encoding: 'utf8', shell: process.platform !== 'win32' });
+    return result.status === 0;
+}
+
+function ensureGlobalNpmPackage(binaryName, packageName, install = false) {
+    if (commandExists(binaryName)) {
+        return { ok: true, message: `${binaryName} already installed` };
+    }
+    if (!install) {
+        return { ok: false, message: `${binaryName} is missing; run: npm install -g ${packageName}` };
+    }
+    if (!commandExists('npm')) {
+        return { ok: false, message: `npm not found; run: npm install -g ${packageName}` };
+    }
+    const result = spawnSync('npm', ['install', '-g', packageName], {
+        encoding: 'utf8',
+        stdio: 'pipe',
+        shell: process.platform === 'win32'
+    });
+    if (result.status !== 0) {
+        return { ok: false, message: `failed to install ${binaryName}; run: npm install -g ${packageName}` };
+    }
+    return { ok: true, message: `installed ${binaryName}` };
+}
+
+function ensureCodebaseMemoryCli(install = false) {
+    return ensureGlobalNpmPackage(CODEBASE_MEMORY_BINARY, CODEBASE_MEMORY_PACKAGE, install);
+}
+
+function ensureRtkInstalled(install = false) {
+    if (commandExists('rtk')) {
+        return { ok: true, message: 'rtk already installed' };
+    }
+    if (!install) {
+        return { ok: false, message: `rtk is missing; run: ${RTK_INSTALL_COMMAND}` };
+    }
+    if (!commandExists('cargo')) {
+        return { ok: false, message: `cargo not found; install Rust, then run: ${RTK_INSTALL_COMMAND}` };
+    }
+    console.log(pc.dim('  Installing rtk via cargo (compiles from source; this can take a few minutes)...'));
+    const result = spawnSync('cargo', ['install', '--git', 'https://github.com/rtk-ai/rtk', '--branch', 'master', 'rtk'], {
+        encoding: 'utf8',
+        stdio: 'inherit',
+        shell: process.platform === 'win32'
+    });
+    if (result.status !== 0) {
+        return { ok: false, message: `failed to install rtk; run: ${RTK_INSTALL_COMMAND}` };
+    }
+    return { ok: true, message: 'installed rtk' };
+}
+
+function indexRepository() {
+    if (!commandExists(CODEBASE_MEMORY_BINARY)) {
+        return { ok: false, message: `${CODEBASE_MEMORY_BINARY} is not installed; skipped indexing` };
+    }
+    console.log(pc.dim(`  Running ${CODEBASE_MEMORY_BINARY} cli index_repository --repo-path . (first index of a large repo can take a while)...`));
+    const result = spawnSync(CODEBASE_MEMORY_BINARY, ['cli', 'index_repository', '--repo-path', '.'], {
+        cwd: targetDir,
+        encoding: 'utf8',
+        stdio: 'inherit',
+        shell: process.platform === 'win32'
+    });
+    if (result.status !== 0) {
+        return { ok: false, message: `indexing failed; run manually: ${CODEBASE_MEMORY_BINARY} cli index_repository --repo-path .` };
+    }
+    return { ok: true, message: 'indexed repository with codebase-memory-mcp' };
+}
+
+function readJsonFile(filePath) {
+    if (!fs.existsSync(filePath)) return {};
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function writeJsonFile(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function mergeMcpJson(filePath, withType = false) {
+    const data = readJsonFile(filePath);
+    if (data === null) {
+        return { ok: false, message: `${filePath} is not valid JSON; skipped` };
+    }
+    data.mcpServers = data.mcpServers || {};
+    const baseServers = {
+        'codebase-memory-mcp': { command: CODEBASE_MEMORY_BINARY, args: [] },
+        playwright: { command: 'playwright-mcp' },
+        context7: { command: 'context7-mcp' }
+    };
+    if (data.permissions && Array.isArray(data.permissions.allow)) {
+        const requiredPermissions = [
+            "mcp__context7__resolve-library-id",
+            "mcp__context7__query-docs"
+        ];
+        for (const perm of requiredPermissions) {
+            if (!data.permissions.allow.includes(perm)) {
+                data.permissions.allow.push(perm);
+            }
+        }
+    }
+    for (const [name, server] of Object.entries(baseServers)) {
+        if (!data.mcpServers[name]) {
+            data.mcpServers[name] = withType ? { type: 'stdio', ...server } : server;
+        }
+    }
+    writeJsonFile(filePath, data);
+    const tools = Object.keys(baseServers).join(', ');
+    return { ok: true, message: `configured ${tools} MCP in ${filePath}` };
+}
+
+function appendMcpTomlIfMissing(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const blocks = [];
+    if (!/\[mcp_servers\.context7\]/.test(existing)) {
+        blocks.push(`[mcp_servers.context7]
+command = "context7-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+`);
+    }
+    if (!/\[mcp_servers\.codebase-memory-mcp\]/.test(existing)) {
+        blocks.push(`[mcp_servers.codebase-memory-mcp]
+command = "${CODEBASE_MEMORY_BINARY}"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+`);
+    }
+    if (!/\[mcp_servers\.playwright\]/.test(existing)) {
+        blocks.push(`[mcp_servers.playwright]
+command = "playwright-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+`);
+    }
+    if (blocks.length === 0) {        return { ok: true, message: `already configured ${filePath}` };
+    }
+    const separator = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
+    fs.writeFileSync(filePath, existing + separator + blocks.join('\n'), 'utf8');
+    return { ok: true, message: `configured codebase-memory-mcp, context7, playwright MCP in ${filePath}` };
+}
+
+const DOD_HOOK_MARKER = 'feature/refactor Definition-of-Done gate';
+
+function generateDodStopHookPrompt() {
+    return `Input JSON (Stop hook payload): $ARGUMENTS\n\nCheck this project's ${DOD_HOOK_MARKER}. This kit does not define its own workflow steps or require any specific workflow skill; it only verifies that evidence of the gate exists, however that evidence was produced (a documented planning/review skill, a manual process, or anything equivalent). Use the \`last_assistant_message\` field as the authoritative final response. Use \`transcript_path\` only for additional context because the transcript may not contain the final response yet.\n\nVerification is never optional: every change, fast path included, requires semantic evidence in the final response or visible transcript that focused tests or equivalent verification actually ran and passed (for example test/build output, or a described manual verification). Do not require a specific command; judge the evidence on its meaning.\n\nFor any change that is not a verified fast path (see below), completion additionally requires evidence of:\n- Plan: a plan was written and explicitly approved by the human before implementation started.\n- Review: the change was reviewed (correctness, simplicity, architecture, security, performance) and blocking issues were resolved.\n\nFast-path eligibility is based on risk and contract surface, not file count. A change is fast path only when it is localized, mechanically obvious, low-risk, and has no meaningful public API, schema, auth/security, data-integrity, payment, concurrency, dependency, CI/release, or architectural risk, with focused verification available. A source file plus its own focused test can still be fast path; a one-file auth, payment, schema, security, or concurrency change is not fast path no matter how small. A verified fast-path change is exempt from the Plan and Review evidence only when the final response states FAST_PATH: simple-fix, its reason, and its narrow scope — Verification evidence is still mandatory in that case, not optional.\n\nSteps:\n1. If the input JSON has \`stop_hook_active: true\`, allow stopping immediately (already checked once this cycle; never block twice in a row).\n2. Inspect the changed files and the \`last_assistant_message\` field.\n3. If no source files changed or the final response does not claim the task is done/complete, allow stopping.\n4. If the final response explicitly contains FAST_PATH: simple-fix, first check the claim against the risk criteria above, not file count. If it actually touches one of those risk areas regardless of file count, the FAST_PATH claim is invalid; treat it as a full feature/refactor change and continue to step 5. Otherwise, look for semantic evidence that focused verification actually ran and passed. If that evidence is present, allow stopping. If it is missing, block with {"ok": false, "reason": "Missing Verification evidence: ..."}.\n5. If the final response claims completion for a change that is not a verified fast path, check all three gates: (a) a plan was written and explicitly approved by the human before implementation started; (b) the change was reviewed and blocking issues were resolved; (c) tests or equivalent verification ran and passed. If any one of the three is missing, block naming exactly that gate; a generic statement that the task was simple, or that it touched only one file, is not enough on its own.\n6. Return exactly JSON: {"ok": true} to allow stopping, or {"ok": false, "reason": "..."} to block.\n\nWhen blocking, name exactly which gate is missing without prescribing which skill or workflow must produce it.`;
+}
+
+function isDefinitionOfDoneHook(hook) {
+    const prompt = hook && typeof hook.prompt === 'string' ? hook.prompt : '';
+    return prompt.includes(DOD_HOOK_MARKER);
+}
+
+function mergeClaudeProjectHooks(filePath) {
+    const data = readJsonFile(filePath);
+    if (data === null) {
+        return { ok: false, message: `${filePath} is not valid JSON; skipped hook setup` };
+    }
+    if (!data.hooks || typeof data.hooks !== 'object') data.hooks = {};
+    if (!Array.isArray(data.hooks.Stop)) data.hooks.Stop = [];
+
+    let primaryHook = null;
+    let definitionHookCount = 0;
+    for (const entry of data.hooks.Stop) {
+        for (const hook of Array.isArray(entry?.hooks) ? entry.hooks : []) {
+            if (isDefinitionOfDoneHook(hook)) {
+                definitionHookCount++;
+                if (!primaryHook) primaryHook = hook;
+            }
+        }
+    }
+
+    if (primaryHook) {
+        primaryHook.prompt = generateDodStopHookPrompt();
+        primaryHook.timeout = 60;
+        primaryHook.statusMessage = 'Checking feature/refactor Definition-of-Done gate...';
+
+        if (definitionHookCount > 1) {
+            data.hooks.Stop = data.hooks.Stop
+                .map(entry => ({
+                    ...entry,
+                    hooks: (Array.isArray(entry?.hooks) ? entry.hooks : [])
+                        .filter(hook => !isDefinitionOfDoneHook(hook) || hook === primaryHook)
+                }))
+                .filter(entry => entry.hooks.length > 0);
+        }
+
+        writeJsonFile(filePath, data);
+        return {
+            ok: true,
+            message: definitionHookCount > 1
+                ? `consolidated Definition-of-Done Stop hooks in ${filePath}`
+                : `updated Definition-of-Done Stop hook in ${filePath}`
+        };
+    }
+
+    data.hooks.Stop.push({
+        hooks: [
+            {
+                type: 'agent',
+                prompt: generateDodStopHookPrompt(),
+                timeout: 60,
+                statusMessage: 'Checking feature/refactor Definition-of-Done gate...'
+            }
+        ]
+    });
+    writeJsonFile(filePath, data);
+    return { ok: true, message: `configured Definition-of-Done Stop hook in ${filePath}` };
+}
+
+function setupMcpServers(options = {}) {
+    const install = options.install === true;
+    const results = [];
+    results.push(ensureCodebaseMemoryCli(install));
+    results.push(ensureGlobalNpmPackage('context7-mcp', '@upstash/context7-mcp', install));
+    results.push(ensureGlobalNpmPackage('playwright-mcp', '@playwright/mcp', install));
+
+    const codexConfig = homePath('.codex', 'config.toml');
+    if (codexConfig) results.push(appendMcpTomlIfMissing(codexConfig));
+
+    const geminiConfig = homePath('.gemini', 'config', 'mcp_config.json');
+    if (geminiConfig) results.push(mergeMcpJson(geminiConfig, false));
+
+    const antigravityIdeConfig = homePath('.gemini', 'antigravity-ide', 'mcp_config.json');
+    if (antigravityIdeConfig) results.push(mergeMcpJson(antigravityIdeConfig, false));
+
+    const antigravityConfig = homePath('.gemini', 'antigravity', 'mcp_config.json');
+    if (antigravityConfig && fs.existsSync(path.dirname(antigravityConfig))) {
+        results.push(mergeMcpJson(antigravityConfig, false));
+    }
+
+    const claudeConfig = homePath('.claude.json');
+    if (claudeConfig) results.push(mergeMcpJson(claudeConfig, true));
+
+    const claudeSettings = homePath('.claude', 'settings.json');
+    if (claudeSettings) results.push(mergeMcpJson(claudeSettings, true));
+
+    return results;
+}
+
+function runSkillsCommand(args) {
+    const subcommand = args[0];
+    const dryRun = args.includes('--dry-run');
+
+    if (subcommand === 'install') {
+        console.log(pc.bold(pc.cyan('thachvd-kit skills install')));
+        const mattResult = mattSkills.installSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('Matt Pocock skills')}`);
+        console.log(`  ${mattResult.ok ? pc.green('OK') : pc.yellow('WARN')} ${mattResult.message}`);
+        const nativeResult = nativeSkills.installNativeSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        if (dryRun) for (const item of nativeResult.operations) console.log(`  ${pc.dim('would copy')} ${item.relativePath} -> ${item.surface}`);
+        console.log(`  ${nativeResult.ok ? pc.green('OK') : pc.yellow('WARN')} ${nativeResult.message}`);
+        if (!dryRun && mattResult.ok) printMattSkillsSetupReminder();
+        if (!mattResult.ok || !nativeResult.ok) process.exitCode = 1;
+        return;
+    }
+
+    if (subcommand === 'check') {
+        console.log(pc.bold(pc.cyan('thachvd-kit skills check')));
+        const status = mattSkills.checkSkills(targetDir);
+        console.log(`\n${pc.bold('Matt Pocock skills')}`);
+        for (const name of mattSkills.PROMOTED_SKILLS) {
+            const installed = status.installed.includes(name);
+            console.log(`  ${installed ? pc.green('OK') : pc.yellow('WARN')} ${name}`);
+        }
+        console.log(`\n  ${status.installed.length}/${status.total} promoted skills installed in ${mattSkills.SKILLS_RELATIVE_DIR}`);
+        if (status.missing.length > 0) console.log(`  Run: ${pc.bold('thachvd-kit skills install')}`);
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        const nativeStatus = nativeSkills.checkNativeSkills(targetDir);
+        for (const name of nativeSkills.NATIVE_SKILLS) {
+            const item = nativeStatus.skills[name];
+            console.log(`  ${item.agents && item.claude ? pc.green('OK') : pc.yellow('WARN')} ${name}`);
+            console.log(`    .agents: ${item.agents ? 'installed' : 'missing'}`);
+            console.log(`    .claude: ${item.claude ? 'installed' : 'missing'}`);
+        }
+        for (const surface of nativeSkills.NATIVE_SKILL_SURFACES) {
+            const support = nativeStatus.surfaces[surface.id].support;
+            const status = support.missing.length === 0 ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${status} support files (${surface.relativeDir}: ${support.missing.length === 0 ? 'installed' : 'missing'})`);
+        }
+        if (!nativeStatus.allInstalled) console.log(`  Run: ${pc.bold('thachvd-kit skills install')}`);
+        return;
+    }
+
+    if (subcommand === 'update') {
+        console.log(pc.bold(pc.cyan('thachvd-kit skills update')));
+        const result = mattSkills.updateSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('Matt Pocock skills')}`);
+        if (dryRun) {
+            for (const item of result.results) console.log(`  ${pc.dim('would run')} ${item.command}`);
+        } else {
+            for (const item of result.results) console.log(`  ${item.ok ? pc.green('OK') : pc.yellow('WARN')} ${item.name}`);
+        }
+        console.log(`\n  ${result.ok ? pc.green('OK') : pc.yellow('WARN')} ${result.message}`);
+        const nativeResult = nativeSkills.updateNativeSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        if (dryRun) for (const item of nativeResult.operations) console.log(`  ${pc.dim('would copy')} ${item.relativePath} -> ${item.surface}`);
+        console.log(`  ${nativeResult.ok ? pc.green('OK') : pc.yellow('WARN')} ${nativeResult.message}`);
+        if (!result.ok || !nativeResult.ok) process.exitCode = 1;
+        return;
+    }
+
+    console.error(pc.red(`Unknown skills subcommand: ${subcommand || '(none)'}`));
+    console.error('Usage: thachvd-kit skills install|check|update [--dry-run]');
+    process.exit(1);
+}
+
+// --- Main CLI ---
+
+async function main() {
+    // Note: 'upgrade' and 'global' are handled directly by bin/entry.js
+    // (bin/upgrade.js / bin/global.js) before this module is even required,
+    // so they never reach here.
+    const rawArgs = process.argv.slice(2);
+    const command = rawArgs[0] && !rawArgs[0].startsWith('-') ? rawArgs[0] : 'init';
+    const args = command === 'init' ? rawArgs.slice(rawArgs[0] === 'init' ? 1 : 0) : rawArgs.slice(1);
+
+    if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
+        console.log(packageJson.version);
+        return;
+    }
+
+    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+        printHelp();
+        return;
+    }
+
+    if (command === 'doctor') {
+        runDoctor();
+        return;
+    }
+
+    if (command === 'prompt') {
+        printProjectPrompt();
+        return;
+    }
+
+    if (command === 'setup') {
+        await runSetup(rawArgs.slice(1));
+        return;
+    }
+
+    if (command === 'skills') {
+        runSkillsCommand(rawArgs.slice(1));
+        return;
+    }
+
+    if (command !== 'init') {
+        console.error(pc.red(`Unknown command: ${command}`));
+        printHelp();
+        process.exit(1);
+    }
+
+    const assumeYes = args.includes('--yes') || args.includes('-y');
+    const skipMcpSetup = args.includes('--no-setup-mcp') || process.env.THACHVD_KIT_SKIP_MCP_SETUP === '1';
+
+    console.log(pc.bold(pc.cyan('='.repeat(50))));
+    console.log('  ' + pc.bold('thachvd-kit') + ' - AI Project Bootstrap');
+    console.log('  Generates shared agent rules and configures MCP tooling');
+    console.log(pc.bold(pc.cyan('='.repeat(50))));
+
+    console.log(pc.dim('  Scanning current project files for a baseline...\n'));
+    const scanned = scanProject();
+
+    console.log(`  ${pc.bold('Detected context:')}`);
+    formatScanPreviewLines(scanned).forEach(([label, value]) => {
+        console.log(`    - ${label}: ${value}`);
+    });
+    console.log('');
+    if ((scanned.scan_evidence || []).length > 0) {
+        console.log(`  ${pc.bold('Evidence:')}`);
+        scanned.scan_evidence.forEach(line => console.log(`    - ${line}`));
+        console.log('');
+    }
+
+    // Combine data
+    const data = {
+        project_name: scanned?.project_name || path.basename(targetDir),
+        description: scanned?.description || 'A software project',
+        project_type: scanned?.project_type || 'web-app',
+        primary_language: scanned?.primary_language || 'typescript',
+        frameworks: scanned?.frameworks || [],
+        database: scanned?.database || 'none',
+        uses_docker: scanned?.uses_docker ?? true,
+        cloud: scanned?.cloud || 'none',
+        package_manager: scanned?.package_manager || 'auto-detect',
+        test_framework: scanned?.test_framework || 'auto-detect'
+    };
+
+    data.database = data.database || scanned?.database || 'none';
+    data.uses_docker = typeof data.uses_docker === 'boolean' ? data.uses_docker : (scanned?.uses_docker ?? true);
+    data.cloud = data.cloud || scanned?.cloud || 'none';
+    data.package_manager = data.package_manager || scanned?.package_manager || 'auto-detect';
+    data.test_framework = data.test_framework || scanned?.test_framework || 'auto-detect';
+    data.framework_details = scanned?.framework_details || [];
+    data.scan_evidence = scanned?.scan_evidence || [];
+    data.app_root = scanned?.app_root || '.';
+
+    data.infrastructure = [];
+    if (data.uses_docker) data.infrastructure.push('docker');
+    if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
+
+    const shouldSetupMcp = args.includes('--setup-mcp') && !skipMcpSetup;
+
+    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
+
+    // Shared entry files are written after the .agent folder is available.
+
+    console.log(`  ${pc.green('OK')} Project context generation enabled; run thachvd-kit setup to install the promoted Matt Pocock skill set`);
+
+
+    const generatedFiles = [
+        ['AGENTS.md', generateSharedAgentsMd(data)],
+        ['CLAUDE.md', generateSharedClaudeMd()],
+        ['GEMINI.md', generateSharedGeminiMd()],
+        ['.cursorrules', generateSharedCursorrules(data)],
+        [path.join('.agent', 'docs', 'project.md'), generateProjectDoc(data)],
+        [path.join('.agent', 'docs', 'architecture.md'), generateArchitectureDoc(data)],
+        [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc()],
+        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()],
+        [path.join('.agent', 'docs', 'tooling.md'), generateToolingDoc(data)],
+        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()],
+        [path.join('.agent', 'docs', 'index-project-prompt.md'), generateIndexProjectPrompt()]
+    ];
+
+    for (const [relativePath, content] of generatedFiles) {
+        const wrote = await writeGeneratedFile(relativePath, content, assumeYes);
+        if (wrote) console.log(`  ${pc.green('OK')} Generated ${pc.bold(relativePath)}`);
+        else console.log(`  ${pc.yellow('~')} Skipped ${pc.bold(relativePath)}`);
+    }
+
+    if (shouldSetupMcp) {
+        console.log(`\n${pc.bold(pc.cyan('Configuring MCP'))}`);
+        for (const result of setupMcpServers()) {
+            const marker = result.ok ? pc.green('OK') : pc.yellow('~');
+            console.log(`  ${marker} ${result.message}`);
+        }
+    }
+
+    console.log(`\n${pc.bold(pc.green('Done!'))}
+
+  ${pc.bold('Project:')} ${data.project_name}
+  ${pc.bold('Stack:')}   ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
+
+  ${pc.bold('Generated:')}
+    - ${pc.bold('AGENTS.md')} shared entry for Codex, Antigravity, Claude Code, and Cursor
+    - ${pc.bold('CLAUDE.md')} Claude Code entry that imports AGENTS.md
+    - ${pc.bold('GEMINI.md')} Antigravity entry
+    - ${pc.bold('.cursorrules')} Cursor entry
+    - ${pc.bold('.agent/docs/')} scan-based project rules and local operating notes
+    - ${pc.bold('.agent/docs/index-project-prompt.md')} durable onboarding prompt
+
+  ${pc.bold('MCP/tooling setup:')}
+    - Matt Pocock's promoted and thachvd-kit native skills are the workflow layer
+    - Run ${pc.bold('thachvd-kit setup')} to install both groups and configure codebase-memory MCP and recommended RTK
+
+  ${pc.bold('Next steps:')}
+    1. Run ${pc.bold('thachvd-kit prompt')} and paste the saved prompt into your AI editor
+    2. Run ${pc.bold('thachvd-kit setup')} to install promoted and native skill sets and RTK
+    3. Run ${pc.bold('thachvd-kit doctor')} to verify the machine
+    4. Re-run ${pc.bold('thachvd-kit prompt')} whenever you need the onboarding prompt again
+
+  ${pc.bold('Onboarding prompt saved to .agent/docs/index-project-prompt.md:')}
+${pc.dim('---')}
+${generateIndexProjectPrompt().trim()}
+${pc.dim('---')}
+`);
+}
+
+main().catch(err => {
+    console.error(pc.red('\nError during init:'), err);
+    process.exit(1);
+});