thachvd-kit 1.0.25 → 1.0.27

package/bin/cli.js

@@ -1,11 +1,11 @@
 #!/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 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 sourceDir = path.resolve(__dirname, '..');
 const targetDir = process.cwd();
@@ -63,7 +63,7 @@ const INFRA_SKILLS = {
     vercel: ["deployment-procedures"],
 };
 
-function resolveSkills(data) {
+function resolveSkills(data) {
     const skills = new Set();
     const lang = (data.primary_language || "").toLowerCase();
 
@@ -88,16 +88,16 @@ function resolveSkills(data) {
     skills.add("clean-code");
     skills.add("systematic-debugging");
 
-    return Array.from(skills).sort();
-}
-
-function resolveNativeSkills(data) {
-    return Array.from(new Set([
-        ...resolveSkills(data),
-        'verification-before-completion',
-        'webapp-testing'
-    ])).sort();
-}
+    return Array.from(skills).sort();
+}
+
+function resolveNativeSkills(data) {
+    return Array.from(new Set([
+        ...resolveSkills(data),
+        'verification-before-completion',
+        'webapp-testing'
+    ])).sort();
+}
 
 const FRAMEWORK_CHOICES = [
     'vue', 'react', 'next', 'nuxt', 'svelte', 'angular',
@@ -120,59 +120,70 @@ const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'bu
 
 function printHelp() {
     console.log(`
-${pc.bold('Usage:')}
-  thachvd-kit [--yes]
-  thachvd-kit init [--yes]
-  thachvd-kit --version
-  thachvd-kit --help
-
-${pc.bold('Commands:')}
-  init      Bootstrap shared AI-agent rules and tooling
-
-${pc.bold('Options:')}
-  --yes     Overwrite generated files when they already exist
-  --no-setup-mcp Skip local Codegraph and Playwright MCP setup
-  --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/     Shared docs, skills, workflows, agents, and rules
-  ~/.codex/skills/  Selected Codex skills copied to global user dir (shows in $ menu)
-  .claude/skills/   Selected Claude Code project skills copied from .agent/skills
-
+${pc.bold('Usage:')}
+  thachvd-kit [--yes]
+  thachvd-kit init [--yes]
+  thachvd-kit --version
+  thachvd-kit --help
+
+${pc.bold('Commands:')}
+  init      Bootstrap shared AI-agent rules and tooling
+
+${pc.bold('Options:')}
+  --yes     Overwrite generated files when they already exist
+  --no-setup-mcp Skip local Codegraph and Playwright MCP setup
+  --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/     Shared docs, skills, workflows, agents, and rules
+  ~/.codex/skills/  Selected Codex skills copied to global user dir (shows in $ menu)
+  .claude/skills/   Selected Claude Code project skills copied from .agent/skills
+
 ${pc.bold('Workflow guide:')}
+  Every task               /task        Classify the request and select the workflow, skill, and agent
+  Small obvious fix        /simple      Fast path; skips spec/plan/review but still verifies
   Idea is fuzzy            /brainstorm  Explore options, tradeoffs, and recommended direction
+  Scope needs a contract    /spec        Define requirements and acceptance criteria; no code yet
   New app from scratch     /create      Turn an app idea into plan + implementation flow
   Feature is clear         /plan        Create docs/PLAN-*.md first, no code yet
   Existing app update      /enhance     Add or change a feature in an existing codebase
-  Bug or failing behavior  /debug       Investigate symptoms, hypotheses, root cause, fix
-  UI / UX work             ui-ux-pro-max, frontend-specialist, $frontend-design, $webapp-testing
-  Run or add tests         /test        Generate tests, run tests, check coverage
-  Preview locally          /preview     Start, stop, restart, or health-check dev server
+  Bug or failing behavior  /debug       Investigate symptoms, hypotheses, root cause, fix
+  UI / UX work             ui-ux-pro-max, frontend-specialist, $frontend-design, $webapp-testing
+  Run or add tests         /test        Generate tests, run tests, check coverage
+  Preview locally          /preview     Start, stop, restart, or health-check dev server
   Deploy / infra           /deploy      Release, hosting, Docker, cloud, environment setup
+  Pre-merge review         /review      Run the five-axis review before calling work complete
+  Npm package release      /release     Verify, version, tag, publish, and verify the package
   Project state            /status      Summarize stack, progress, preview, pending work
   Multi-domain work        /orchestrate Coordinate frontend, backend, data, security, QA
 
 ${pc.bold('Common explicit skill prompts:')}
+  Use /task to route this request before editing.
+  Use /simple for a one-file fix with no behavior or contract change.
   Use /brainstorm for this feature idea before planning.
+  Use /spec when requirements or scope need an explicit contract.
   Use /plan for this feature; do not write code yet.
   Use /enhance to implement this planned feature.
-  Use $clean-code before editing this module.
-  Use $systematic-debugging to investigate this bug.
-  Use $webapp-testing to verify the UI with Playwright.
-  Use $verification-before-completion before claiming done.
-  Use $writing-skills to improve a SKILL.md description.
-
-${pc.bold('Tip:')}
-  Skills are copied for Codex/Claude, but you can call them explicitly with $skill-name
-  when implicit matching does not fire.
-`);
-
-}
+  Use /debug for this failing behavior and find the root cause before editing.
+  Use /review before claiming this feature/refactor complete.
+  Use /release for npm versioning and publishing.
+  Use $clean-code before editing this module.
+  Use $systematic-debugging to investigate this bug.
+  Use $webapp-testing to verify the UI with Playwright.
+  Use $verification-before-completion before claiming done.
+  Use $writing-skills to improve a SKILL.md description.
+
+${pc.bold('Tip:')}
+  Skills are copied for Codex/Claude, but you can call them explicitly with $skill-name
+  when implicit matching does not fire.
+`);
+
+}
 
 function formatScanPreviewLines(scanned) {
     return [
@@ -886,859 +897,1104 @@ function resolveAgentTable(data) {
     rows.push(["Debug", "debugger", "systematic-debugging"]);
     rows.push(["Security", "security-auditor", "vulnerability-scanner"]);
     rows.push(["Planning", "project-planner", "brainstorming, plan-writing"]);
-
    return rows;
-}
-// --- 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 Playwright, codegraph, MCP, or native Codex/Claude skill setup.
-6. Select and load only the agent, skill, or workflow files that match the current task.
-
-If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
-
+
    return rows;
+}
+// --- 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 Playwright, codegraph, MCP, or native Codex/Claude skill setup.
+6. Select and load only the agent, skill, or workflow files that match the current task.
+
+If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
+
 ## Task Flow
 
+Route every task before editing. Use \`/task <request>\` when the correct path is not obvious.
+
 - Questions and analysis: answer directly, cite relevant files when useful, and do not edit code.
-- Simple fix: inspect dependencies, make the smallest change, run focused verification.
-- Feature or refactor: define success criteria, make a short plan, implement, then verify.
+- Simple fix: use \`/simple <request>\` only for one-file, unambiguous changes with no behavior or contract change.
+- Bug or failing behavior: use \`/debug <symptom>\` and follow the evidence-first root-cause flow.
+- Feature or refactor: use \`/brainstorm\` for discovery, \`/spec\` for ambiguous or multi-file scope, then \`/plan\`, wait for approval, implement, test, and \`/review\`.
+- Pre-merge review: use \`/review\` even when the implementation itself was done by another client or member.
+- Release or npm publish: use \`/release\`; release work never uses the simple fast path.
 - Multi-domain work: use \`.agent/workflows/orchestrate.md\` and route to the relevant specialist docs.
 - UI work: read \`.agent/agents/frontend-specialist.md\` and applicable design skills before editing.
 
-## Skill Loading
-
-- Treat \`.agent/skills/\` as the shared source of truth for all kit skills.
-- Codex exposes skills from \`~/.codex/skills/\` in the \`$\` menu; \`thachvd-kit\` copies selected skills there on init.
-- Claude Code project skills live in \`.claude/skills/\`.
-- If a skill is missing from the global dir, fall back to the matching \`.agent/skills/<skill>/SKILL.md\` file.
-- Do not load skill bodies by default; load a skill only when the user mentions it, the task clearly matches its description, or \`.agent/docs/project.md\` routes the task to it.
-- Prefer explicit skill mentions for predictable behavior: \`$clean-code\`, \`$systematic-debugging\`, \`$webapp-testing\`, or any skill listed in \`.agent/docs/project.md\`.
-- Run \`thachvd-kit --help\` to see common workflow and skill recommendations.
-- When creating or improving skills, use \`writing-skills\` first and make the \`description\` field specific enough for implicit invocation.
-
-## Rules
-
-- Respond in the user's language; keep code, identifiers, and code comments in English.
-- State assumptions when the request is ambiguous.
-- Prefer the existing project style over new abstractions.
-- Keep changes surgical and remove only dead code introduced by your change.
-- **MCP First**: Prioritize using MCP server tools (e.g., \`codegraph\` for codebase search/symbol tracking, \`context7\` for API/docs queries, and \`playwright\` for browser/UI testing and verification) to explore, search, and verify rather than recursively listing directories, running expensive shell commands/grep, or reading large files. This minimizes token usage and maintains a cleaner context.
-- Tests or equivalent verification are mandatory before claiming done.
-- Keep files under ${data.max_file_lines || '300'} lines unless the project already has a different standard in \`.agent/docs/conventions.md\`.
-
-## Shared Knowledge
-
-- Project docs: \`.agent/docs/\`
-- Specialist agents: \`.agent/agents/\`
-- Skills: \`.agent/skills/\`
-- Codex global skills: \`~/.codex/skills/\` (installed by thachvd-kit init)
-- Claude Code project skills: \`.claude/skills/\`
-- Workflows: \`.agent/workflows/\`
-- Tooling setup: \`.agent/docs/tooling.md\`
-- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
-- Cursor entry rules: \`.cursorrules\`
-`;
-}
-
-function generateSharedClaudeMd(data) {
-    return `@AGENTS.md
+### Fast Path (\`/simple\`)
 
-${generateSharedAgentsMd(data)}
+The fast path intentionally bypasses only Spec, Plan, and the feature/refactor Review gate for a trivial change. It never bypasses inspection, focused verification, or reporting evidence. The agent must state this protocol before editing:
 
-## 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.
-`;
-}
+\`\`\`text
+FAST_PATH: simple-fix
+REASON: [why the change is one-file and unambiguous]
+SCOPE: [file or narrow area]
+\`\`\`
 
-function generateSharedGeminiMd() {
-    return `# GEMINI.md
+If the scope expands, stop and re-route with \`/task\`. Do not silently skip gates for work that changes behavior, APIs, schemas, security, CI, dependencies, workflows, or release state.
+
+### Gated Flow (feature or refactor)
 
-Antigravity entry file for this project.
+1. **Spec** — run \`.agent/workflows/spec.md\` when scope is ambiguous, touches multiple files, or would take more than ~30 minutes. Skip only for single-line/self-contained fixes. Stop at its exit criteria and wait for human confirmation before moving on.
+2. **Plan** — run \`.agent/workflows/plan.md\` (project-planner agent, no code writing). Wait for explicit user approval of the plan file before implementing.
+3. **Implement** — smallest coherent change per the approved plan, with focused tests for changed behavior.
+4. **Review** — run \`.agent/workflows/review.md\` (five-axis review) before the change is considered done. All 🔴 BLOCKING items must be resolved or explicitly accepted with rationale.
 
-Read AGENTS.md first, then follow the shared docs under .agent/docs/.
-`;
-}
+A feature/refactor task is not "done" until step 4's exit criteria are met — passing tests alone does not satisfy the gate. Simple fixes use the explicit \`/simple\` fast path above. See \`.agent/docs/getting-started.md\` for the complete route guide.
 
-function generateSharedCursorrules(data) {
+## Skill Loading
+
+- Treat \`.agent/skills/\` as the shared source of truth for all kit skills.
+- Codex exposes skills from \`~/.codex/skills/\` in the \`$\` menu; \`thachvd-kit\` copies selected skills there on init.
+- Claude Code project skills live in \`.claude/skills/\`.
+- If a skill is missing from the global dir, fall back to the matching \`.agent/skills/<skill>/SKILL.md\` file.
+- Do not load skill bodies by default; load a skill only when the user mentions it, the task clearly matches its description, or \`.agent/docs/project.md\` routes the task to it.
+- Prefer explicit skill mentions for predictable behavior: \`$clean-code\`, \`$systematic-debugging\`, \`$webapp-testing\`, or any skill listed in \`.agent/docs/project.md\`.
+- Run \`thachvd-kit --help\` to see common workflow and skill recommendations.
+- When creating or improving skills, use \`writing-skills\` first and make the \`description\` field specific enough for implicit invocation.
+
+## Rules
+
+- Respond in the user's language; keep code, identifiers, and code comments in English.
+- State assumptions when the request is ambiguous.
+- Prefer the existing project style over new abstractions.
+- Keep changes surgical and remove only dead code introduced by your change.
+- **MCP First**: Prioritize using MCP server tools (e.g., \`codegraph\` for codebase search/symbol tracking, \`context7\` for API/docs queries, and \`playwright\` for browser/UI testing and verification) to explore, search, and verify rather than recursively listing directories, running expensive shell commands/grep, or reading large files. This minimizes token usage and maintains a cleaner context.
+- Tests or equivalent verification are mandatory before claiming done.
+- Keep files under ${data.max_file_lines || '300'} lines unless the project already has a different standard in \`.agent/docs/conventions.md\`.
+
+## Shared Knowledge
+
+- Project docs: \`.agent/docs/\`
+- Specialist agents: \`.agent/agents/\`
+- Skills: \`.agent/skills/\`
+- Codex global skills: \`~/.codex/skills/\` (installed by thachvd-kit init)
+- Claude Code project skills: \`.claude/skills/\`
+- Workflows: \`.agent/workflows/\`
+- Tooling setup: \`.agent/docs/tooling.md\`
+- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
+- Cursor entry rules: \`.cursorrules\`
+`;
+}
+
+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)}
-`;
-}
-
-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 agentRows = resolveAgentTable(data).map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
-    const skillsList = resolveSkills(data).map(s => `- ${s}`).join('\n');
-    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}\`
-
-## Agent Routing
-
-| Task Type | Agent | Primary Skills |
-|-----------|-------|----------------|
-${agentRows}
-
-## Auto-Resolved Skills
-
-${skillsList}
-
-## 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(data) {
-    return `# Coding Conventions
-
-## Current Standards
-
-- Maximum file length: ${data.max_file_lines || '300'} lines unless the existing project standard is stricter.
-- Code comments and identifiers should be written in English.
-- Keep changes scoped to the user request.
-- Prefer existing local patterns over introducing new abstractions.
-- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.
-
-## 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.
+
+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 generateWorkflowDoc() {
-    return `# Agent Workflow
-
-## Before Every Task
-
-1. Read AGENTS.md.
-2. Read .agent/docs/project.md.
-3. Classify the request: question, survey, simple fix, feature, refactor, debug, UI, security, or deploy.
+}
+
+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 agentRows = resolveAgentTable(data).map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
+    const skillsList = resolveSkills(data).map(s => `- ${s}`).join('\n');
+    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 MCP Tools
+
+Use these tools as first-class search and verification methods — prefer them over shell commands or file reads.
+
+| MCP | When to Use |
+|-----|-------------|
+| \`codegraph\` | Explore symbols, trace call chains, find usages — use BEFORE reading files |
+| \`context7\` | Look up library/framework docs, API signatures, migration guides |
+| \`playwright\` | Verify UI behavior, take screenshots, test forms and navigation |
+
+> Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
+
+## Agent Routing
+
+| Task Type | Agent | Primary Skills |
+|-----------|-------|----------------|
+${agentRows}
+
+## Auto-Resolved Skills
+
+${skillsList}
+
+## 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(data) {
+    return `# Coding Conventions
+
+## Current Standards
+
+- Maximum file length: ${data.max_file_lines || '300'} lines unless the existing project standard is stricter.
+- Code comments and identifiers should be written in English.
+- Keep changes scoped to the user request.
+- Prefer existing local patterns over introducing new abstractions.
+- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.
+
+## 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
+
+## Before Every Task
+
+1. Read AGENTS.md.
+2. Read .agent/docs/project.md.
+3. Route the request with \`/task <request>\` when the path is not obvious.
 4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
 5. Check if MCP servers (like \`codegraph\`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
 
-## Skill Selection
-
-- Prefer native skill discovery when the client exposes it.
-- Codex global skills live in ~/.codex/skills/ and are visible via the $ menu; thachvd-kit copies selected skills there on init.
-- Claude Code project skills live in .claude/skills.
-- Shared fallback skills live in .agent/skills.
-- Do not load skill bodies by default.
-- Load a skill when the user mentions it, the task clearly matches its SKILL.md description, or .agent/docs/project.md routes the task to it.
-- Use explicit skill names in prompts for predictable behavior, for example $webapp-testing or $clean-code.
-- Run thachvd-kit --help to see common workflow and skill recommendations.
+## Route Matrix
 
-## Implementation Flow
+| Situation | Command | Workflow / gate |
+|---|---|---|
+| Question or analysis only | direct answer | no edits |
+| One obvious local fix | \`/simple\` | \`.agent/workflows/simple.md\`, fast-path |
+| Bug, regression, failing test, or unknown error | \`/debug\` | \`.agent/workflows/debug.md\`, evidence-first |
+| New behavior, multi-file change, or unclear scope | \`/brainstorm\` -> \`/spec\` when needed -> \`/plan\` | spec/plan approval -> implement -> review |
+| Pre-merge review | \`/review\` | \`.agent/workflows/review.md\`, five-axis |
+| npm version, tag, publish, or deployment | \`/release\` | \`.agent/workflows/release.md\`, release gate |
+| Several specialist domains | \`/orchestrate\` | plan -> approval -> parallel work -> integration verify |
 
-1. State assumptions and success criteria when the task is not trivial.
-2. Inspect dependent files before editing.
-3. Make the smallest coherent change.
-4. Add or update focused tests when behavior changes.
-5. Run verification (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
-6. Summarize changed files and verification evidence.
-
-## When To Update Docs
+If a task is not clearly simple, use the standard flow. Never use the fast path for behavior, API, schema, security, CI, dependency, workflow, or release changes.
+
+## Skill Selection
+
+- Prefer native skill discovery when the client exposes it.
+- Codex global skills live in ~/.codex/skills/ and are visible via the $ menu; thachvd-kit copies selected skills there on init.
+- Claude Code project skills live in .claude/skills.
+- Shared fallback skills live in .agent/skills.
+- Do not load skill bodies by default.
+- Load a skill when the user mentions it, the task clearly matches its SKILL.md description, or .agent/docs/project.md routes the task to it.
+- Use explicit skill names in prompts for predictable behavior, for example $webapp-testing or $clean-code.
+- Run thachvd-kit --help to see common workflow and skill recommendations.
+
+## Implementation Flow
+
+For \`/simple\` fixes, state the fast-path decision before editing:
 
-- Update .agent/docs/architecture.md when structure, boundaries, or entry points change.
-- Update .agent/docs/conventions.md when repeated project patterns become clear.
-- Update .agent/docs/project.md when stack, scripts, app root, test tooling, or routing changes.
-- Keep AGENTS.md concise. Put project-specific detail in .agent/docs.
-`;
-}
+\`\`\`text
+FAST_PATH: simple-fix
+REASON: [why Spec/Plan/Review are not needed]
+SCOPE: [file or narrow area]
+\`\`\`
 
-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`;
+Then:
 
-    return { runner, playwrightCommand };
-}
+1. State assumptions and success criteria when the task is not trivial.
+2. Inspect dependent files before editing.
+3. Make the smallest coherent change.
+4. Add or update focused tests when behavior changes.
+5. Run verification (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
+6. Summarize changed files and verification evidence.
+
+For bugs, use \`/debug\` with \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
 
-function generateToolingDoc(data) {
-    const { runner, playwrightCommand } = resolveToolingSetup(data);
+For features or refactors, this flow runs *inside* the gated flow defined in AGENTS.md (spec -> plan -> implement -> review) — steps 3-5 above are the "Implement" phase, and step 6 is not a substitute for the mandatory \`.agent/workflows/review.md\` gate.
 
-    return `# Optional Tooling
+## Definition of Done (feature or refactor)
 
-This kit keeps tool setup explicit. Do not assume these tools are available until you verify them in the current environment.
+A feature/refactor task is only complete when all of the following hold — not when code compiles or tests pass:
 
-## Playwright
+The Spec checkbox may be skipped only when the documented \`/simple\` fast-path protocol is stated and its criteria are met.
 
-Use Playwright for browser and UI verification when a task touches web behavior.
+- [ ] \`.agent/workflows/spec.md\` exit criteria met (or explicitly skipped as a trivial/self-contained change)
+- [ ] \`.agent/workflows/plan.md\` produced a plan file, approved by the user
+- [ ] Tests added/updated for the changed behavior and passing
+- [ ] \`.agent/workflows/review.md\` five-axis review completed with all 🔴 BLOCKING items resolved or accepted with rationale
+- [ ] Changed files and verification evidence summarized to the user
 
-- Check availability: \`${runner} playwright --version\`
-- Install browsers: \`${playwrightCommand}\`
-- Codex MCP CLI setup: \`codex mcp add playwright -- npx -y @playwright/mcp\`
-- Auto setup: \`thachvd-kit\`
-- Kit helper: \`python .agent/skills/webapp-testing/scripts/playwright_runner.py <url> --screenshot\`
+Do not report a feature/refactor task as done if any box above is unchecked — say explicitly which gate is still open.
 
-If the project already has Playwright configured, prefer the project's existing scripts.
+## When To Update Docs
+
+- Update .agent/docs/architecture.md when structure, boundaries, or entry points change.
+- Update .agent/docs/conventions.md when repeated project patterns become clear.
+- Update .agent/docs/project.md when stack, scripts, app root, test tooling, or routing changes.
+- Keep AGENTS.md concise. Put project-specific detail in .agent/docs.
+`;
+}
+
+function generateGettingStartedDoc() {
+    return `# Getting Started With This Kit
 
-Codex \`config.toml\` example:
+Read this after \`thachvd-kit init\`. The kit gives every member one entry point, then selects only the process and expertise the task needs.
 
-\`\`\`toml
-[mcp_servers.context7]
-command = "npx"
-args = ["-y", "@upstash/context7-mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
+## Start Every Task With /task
 
-[mcp_servers.filesystem]
-command = "npx"
-args = ["-y", "@modelcontextprotocol/server-filesystem", "<projectPath>"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
+Use \`/task <request>\` before editing whenever the route is not already obvious. It must produce:
 
-[mcp_servers.playwright]
-command = "npx"
-args = ["-y", "@playwright/mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
+\`\`\`text
+ROUTE: question | simple | feature | bug | review | release | multi-domain
+WORKFLOW: [exact .agent/workflows/<name>.md file]
+SKILLS: [matching skills, or none]
+AGENTS: [matching specialist agents, or none]
+GATE: fast-path | standard
+NEXT: [the next command or action]
 \`\`\`
 
-## Codegraph
+A workflow is the process and its gates. A skill is the method or checklist. An agent is the specialist role. Chat alone is not a route: the member must select the route and invoke the matching workflow or explicitly choose the question path.
 
-Use codegraph for codebase exploration when the environment exposes it. The index is local state and should not be committed.
+## Route Matrix
 
-- Check for an index: look for \`.codegraph/\`
-- Check CLI availability: \`codegraph --help\`
-- Install CLI if needed: \`npm install -g @colbymchenry/codegraph\`
-- Codex MCP CLI setup: \`codex mcp add codegraph -- codegraph serve --mcp\`
-- Auto setup: \`thachvd-kit\`
-- If your Codex environment provides the codegraph CLI, run its project indexing step from the repository root.
-- Keep \`.codegraph/\` ignored in git.
+| Situation | Command | Gate | Required next step |
+|---|---|---|---|
+| Explain, inspect, or brainstorm only | direct answer or \`/brainstorm\` | none | no code until the request becomes actionable |
+| One obvious local fix | \`/simple <request>\` | fast-path | inspect -> edit -> focused verify |
+| New behavior, multi-file change, unclear scope, or >~30 min | \`/task\` -> \`/brainstorm\` -> \`/spec\` when needed -> \`/plan\` | standard | wait for approval before implementation |
+| Bug, regression, failing test, or unknown error | \`/debug <symptom>\` | bug | reproduce -> isolate -> regression test -> fix -> verify |
+| Pre-merge or independent review | \`/review\` | review | five-axis review; resolve blocking findings |
+| Version, tag, npm publish, or deployment | \`/release\` | release | release checklist; never fast-path |
+| Frontend + backend + data/security together | \`/orchestrate\` | standard | plan -> approval -> specialist work -> integration verify |
 
-Codex \`config.toml\` example:
+## Standard Feature Flow
 
-\`\`\`toml
-[mcp_servers.codegraph]
-command = "codegraph"
-args = ["serve", "--mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-\`\`\`
+The gated sequence is Spec -> Plan -> Implement -> Review: \`/task\` -> \`/brainstorm\` -> \`/spec\` when scope is ambiguous or multi-file -> \`/plan\` -> user approves the plan -> implementation -> \`/test\` -> \`/review\` -> final verification -> commit/push.
 
-Codex reads MCP servers from \`~/.codex/config.toml\` by default. For repo-local setup, use \`.codex/config.toml\`; Codex loads project config only for trusted projects.
+The plan is a gate, not a suggestion. Do not start product-code implementation before explicit approval. Load only the relevant specialist agent and skills, such as \`$frontend-design\`, \`$api-design\`, or \`$webapp-testing\`.
 
-Gemini CLI / Antigravity \`mcp_config.json\` example:
+## Bug Fix Flow
 
-\`\`\`json
-{
-  "mcpServers": {
-    "codegraph": {
-      "command": "codegraph",
-      "args": ["serve", "--mcp"]
-    },
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp"]
-    }
-  }
-}
-\`\`\`
+Use \`/debug <symptom>\`, not the feature flow, when something is failing or the root cause is unknown:
 
-Common local paths:
+1. Capture the exact symptom, environment, reproduction, and expected result.
+2. Inspect the relevant code path with MCP/codegraph when available.
+3. Form and test a small number of hypotheses; do not patch by guesswork.
+4. Add or update a regression test that fails before the fix when practical.
+5. Make the smallest root-cause fix.
+6. Run focused tests, then broader verification when the blast radius is shared.
+7. Use \`/review\` when the fix touches multiple files, contracts, security, or release behavior.
 
-- Gemini CLI: \`~/.gemini/config/mcp_config.json\`
-- Antigravity IDE: \`~/.gemini/antigravity-ide/mcp_config.json\`
-- Older Antigravity setups may use \`~/.gemini/antigravity/mcp_config.json\`
+Load \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\` for this route.
 
-Claude Code user config example:
+## Simple Fast Path
 
-\`\`\`json
-{
-  "mcpServers": {
-    "codegraph": {
-      "type": "stdio",
-      "command": "codegraph",
-      "args": ["serve", "--mcp"]
-    },
-    "context7": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    },
-    "filesystem": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp"]
-    }
-  }
-}
-\`\`\`
+Use \`/simple <request>\` only when the change is one obvious file, the result is unambiguous, and it changes no behavior, API, schema, security, CI, dependency, workflow, or release contract. Before editing, state:
 
-Common local path:
+\`\`\`text
+FAST_PATH: simple-fix
+REASON: [why Spec/Plan/Review are not needed]
+SCOPE: [file or narrow area]
+\`\`\`
 
-- Claude Code: \`~/.claude.json\` or \`~/.claude/settings.json\`
+This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection, focused verification, or reporting evidence. If the scope expands, stop and re-route with \`/task\`.
 
-## Native Skill Folders
+## Command And Skill Map
 
-The shared kit skills live in \`.agent/skills/\`. Antigravity reads that folder directly. Codex shows skills from \`~/.codex/skills/\` in the \`$\` menu. Claude Code reads project skills from \`.claude/skills/\`.
+- \`/brainstorm\`: clarify intent and tradeoffs; no code.
+- \`/spec\`: define requirements and acceptance criteria; no code.
+- \`/plan\`: create an approved implementation plan; no code before approval.
+- \`/enhance\` or \`/create\`: implement an approved feature with the relevant specialist agent.
+- \`/debug\`: systematic root-cause investigation and regression protection.
+- \`/test\`: add or run tests and assess coverage.
+- \`/review\`: five-axis review before completion or merge.
+- \`/release\`: verify, version, tag, publish, and verify npm output.
+- \`$clean-code\` and \`$verification-before-completion\`: default implementation hygiene.
+- \`$webapp-testing\`: browser/UI verification; use Playwright when available.
 
-- Codex global skills: \`~/.codex/skills/\` — installed by \`thachvd-kit init\`, visible in Codex \`$\` menu
-- Claude Code project skills: \`.claude/skills/\`
-- Antigravity: reads \`.agent/skills/\` directly (no copy needed)
-- Keep \`.agent/skills/\` as the full shared source of truth committed with the repo.
-- Do not commit \`~/.codex/skills/\`; it is local user state.
+## Enforcement
 
-Recommended candidates to copy first:
+Claude Code has a project Stop hook in \`.claude/settings.json\` for standard feature/refactor work. An explicit \`FAST_PATH: simple-fix\` is accepted only when the simple criteria are met; it still requires verification. Codex, Antigravity, and Cursor use the same written rules through \`AGENTS.md\`, \`.cursorrules\`, and \`.agent/rules/GEMINI.md\`.
 
-- \`clean-code\`
-- \`systematic-debugging\`
-- \`verification-before-completion\`
-- Stack-specific skills listed in \`.agent/docs/project.md\`
+Full details live in \`AGENTS.md\`, \`.agent/docs/workflow.md\`, and the matching file under \`.agent/workflows/\`.
 `;
 }
 
-// --- Agent Folder Copy ---
-
-function copyAgentFolder() {
-    const srcAgent = path.join(sourceDir, '.agent');
-    if (!fs.existsSync(srcAgent)) return { copied: 0, skipped: 0 };
-
-    const destAgent = path.join(targetDir, '.agent');
-    let copied = 0;
-
-    function copyDir(src, dest) {
-        fs.mkdirSync(dest, { recursive: true });
-        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-            const srcPath = path.join(src, entry.name);
-            const destPath = path.join(dest, entry.name);
-            const relativeSrc = path.relative(srcAgent, srcPath).split(path.sep).join('/');
-            if (relativeSrc === 'docs' || relativeSrc.startsWith('docs/')) {
-                continue;
-            }
-            if (entry.isDirectory()) {
-                copyDir(srcPath, destPath);
-            } else {
-                fs.copyFileSync(srcPath, destPath);
-                copied++;
-            }
-        }
-    }
-
-    copyDir(srcAgent, destAgent);
-    return { copied, skipped: 0 };
-}
-
-function copySelectedSkillFolders(data, assumeYes) {
-    const srcSkills = path.join(sourceDir, '.agent', 'skills');
-    if (!fs.existsSync(srcSkills)) return { copied: 0, skipped: 0, missing: 0, skills: [] };
-
-    const selectedSkills = resolveNativeSkills(data);
-
-    // ~/.codex/skills/ — global Codex user skills dir, always visible in the $ menu
-    const codexSkillsDir = homePath('.codex', 'skills');
-    // .claude/skills/ — project-level Claude Code skills
-    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
-
-    const destinations = [claudeSkillsDir];
-    if (codexSkillsDir) destinations.push(codexSkillsDir);
-
-    let copied = 0;
-    let missing = 0;
-
-    function copyDir(src, dest) {
-        fs.mkdirSync(dest, { recursive: true });
-        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-            const srcPath = path.join(src, entry.name);
-            const destPath = path.join(dest, entry.name);
-            if (entry.isDirectory()) {
-                copyDir(srcPath, destPath);
-            } else {
-                fs.mkdirSync(path.dirname(destPath), { recursive: true });
-                fs.copyFileSync(srcPath, destPath);
-                copied++;
-            }
-        }
-    }
-
-    for (const skill of selectedSkills) {
-        const srcSkill = path.join(srcSkills, skill);
-        if (!fs.existsSync(srcSkill)) {
-            missing++;
-            continue;
-        }
-        for (const destSkills of destinations) {
-            copyDir(srcSkill, path.join(destSkills, skill));
-        }
-    }
-
-    return { copied, skipped: 0, missing, skills: selectedSkills };
-}
-
-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 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 ensureCodegraphCli() {
-    if (commandExists('codegraph')) {
-        return { ok: true, message: 'codegraph CLI already installed' };
-    }
-    if (!commandExists('npm')) {
-        return { ok: false, message: 'npm not found; run: npm install -g @colbymchenry/codegraph' };
-    }
-    const result = spawnSync('npm', ['install', '-g', '@colbymchenry/codegraph'], {
-        encoding: 'utf8',
-        stdio: 'pipe'
-    });
-    if (result.status !== 0) {
-        return { ok: false, message: 'failed to install codegraph; run: npm install -g @colbymchenry/codegraph' };
-    }
-    return { ok: true, message: 'installed codegraph CLI' };
-}
+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
+
+This kit keeps tool setup explicit. Do not assume these tools are available until you verify them in the current environment.
+
+## Playwright
+
+Use Playwright for browser and UI verification when a task touches web behavior.
+
+- Check availability: \`${runner} playwright --version\`
+- Install browsers: \`${playwrightCommand}\`
+- Codex MCP CLI setup: \`codex mcp add playwright -- playwright-mcp\`
+- Auto setup: \`thachvd-kit\`
+- Kit helper: \`python .agent/skills/webapp-testing/scripts/playwright_runner.py <url> --screenshot\`
+
+If the project already has Playwright configured, prefer the project's existing scripts.
+
+Codex \`config.toml\` example:
+
+\`\`\`toml
+[mcp_servers.context7]
+command = "context7-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "<projectPath>"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+
+[mcp_servers.playwright]
+command = "playwright-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+\`\`\`
+
+## Codegraph
+
+Use codegraph for codebase exploration when the environment exposes it. The index is local state and should not be committed.
+
+- Check for an index: look for \`.codegraph/\`
+- Check CLI availability: \`codegraph --help\`
+- Install CLI if needed: \`npm install -g @colbymchenry/codegraph\`
+- Codex MCP CLI setup: \`codex mcp add codegraph -- codegraph serve --mcp\`
+- Auto setup: \`thachvd-kit\`
+- If your Codex environment provides the codegraph CLI, run its project indexing step from the repository root.
+- Keep \`.codegraph/\` ignored in git.
+
+Codex \`config.toml\` example:
+
+\`\`\`toml
+[mcp_servers.codegraph]
+command = "codegraph"
+args = ["serve", "--mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+\`\`\`
+
+Codex reads MCP servers from \`~/.codex/config.toml\` by default. For repo-local setup, use \`.codex/config.toml\`; Codex loads project config only for trusted projects.
+
+Gemini CLI / Antigravity \`mcp_config.json\` example:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    },
+    "context7": {
+      "command": "context7-mcp"
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+    },
+    "playwright": {
+      "command": "playwright-mcp"
+    }
+  }
+}
+\`\`\`
+
+Common local paths:
+
+- Gemini CLI: \`~/.gemini/config/mcp_config.json\`
+- Antigravity IDE: \`~/.gemini/antigravity-ide/mcp_config.json\`
+- Older Antigravity setups may use \`~/.gemini/antigravity/mcp_config.json\`
+
+Claude Code user config example:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    },
+    "context7": {
+      "type": "stdio",
+      "command": "context7-mcp"
+    },
+    "filesystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "playwright-mcp"
+    }
+  }
+}
+\`\`\`
+
+Common local path:
+
+- Claude Code: \`~/.claude.json\` or \`~/.claude/settings.json\`
+
+## Native Skill Folders
+
+The shared kit skills live in \`.agent/skills/\`. Antigravity reads that folder directly. Codex shows skills from \`~/.codex/skills/\` in the \`$\` menu. Claude Code reads project skills from \`.claude/skills/\`.
+
+- Codex global skills: \`~/.codex/skills/\` — installed by \`thachvd-kit init\`, visible in Codex \`$\` menu
+- Claude Code project skills: \`.claude/skills/\`
+- Antigravity: reads \`.agent/skills/\` directly (no copy needed)
+- Keep \`.agent/skills/\` as the full shared source of truth committed with the repo.
+- Do not commit \`~/.codex/skills/\`; it is local user state.
+
+Recommended candidates to copy first:
+
+- \`clean-code\`
+- \`systematic-debugging\`
+- \`verification-before-completion\`
+- Stack-specific skills listed in \`.agent/docs/project.md\`
+`;
+}
+
+// --- Agent Folder Copy ---
+
+function copyAgentFolder() {
+    const srcAgent = path.join(sourceDir, '.agent');
+    if (!fs.existsSync(srcAgent)) return { copied: 0, skipped: 0 };
+
+    const destAgent = path.join(targetDir, '.agent');
+    let copied = 0;
+
+    function copyDir(src, dest) {
+        fs.mkdirSync(dest, { recursive: true });
+        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            const relativeSrc = path.relative(srcAgent, srcPath).split(path.sep).join('/');
+            if (relativeSrc === 'docs' || relativeSrc.startsWith('docs/')) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                copyDir(srcPath, destPath);
+            } else {
+                fs.copyFileSync(srcPath, destPath);
+                copied++;
+            }
+        }
+    }
+
+    copyDir(srcAgent, destAgent);
+    return { copied, skipped: 0 };
+}
+
+function copySelectedSkillFolders(data, assumeYes) {
+    const srcSkills = path.join(sourceDir, '.agent', 'skills');
+    if (!fs.existsSync(srcSkills)) return { copied: 0, skipped: 0, missing: 0, skills: [] };
+
+    const selectedSkills = resolveNativeSkills(data);
+
+    // ~/.codex/skills/ — global Codex user skills dir, always visible in the $ menu
+    const codexSkillsDir = homePath('.codex', 'skills');
+    // .claude/skills/ — project-level Claude Code skills
+    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
+
+    const destinations = [claudeSkillsDir];
+    if (codexSkillsDir) destinations.push(codexSkillsDir);
+
+    let copied = 0;
+    let missing = 0;
+
+    function copyDir(src, dest) {
+        fs.mkdirSync(dest, { recursive: true });
+        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            if (entry.isDirectory()) {
+                copyDir(srcPath, destPath);
+            } else {
+                fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                fs.copyFileSync(srcPath, destPath);
+                copied++;
+            }
+        }
+    }
+
+    for (const skill of selectedSkills) {
+        const srcSkill = path.join(srcSkills, skill);
+        if (!fs.existsSync(srcSkill)) {
+            missing++;
+            continue;
+        }
+        for (const destSkills of destinations) {
+            copyDir(srcSkill, path.join(destSkills, skill));
+        }
+    }
+
+    return { copied, skipped: 0, missing, skills: selectedSkills };
+}
+
+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 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) {
+    if (commandExists(binaryName)) {
+        return { ok: true, message: `${binaryName} already installed` };
+    }
+    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'
+    });
+    if (result.status !== 0) {
+        return { ok: false, message: `failed to install ${binaryName}; run: npm install -g ${packageName}` };
+    }
+    return { ok: true, message: `installed ${binaryName}` };
+}
+
+function ensureCodegraphCli() {
+    return ensureGlobalNpmPackage('codegraph', '@colbymchenry/codegraph');
+}
+
+function ensureContext7Cli() {
+    return ensureGlobalNpmPackage('context7-mcp', '@upstash/context7-mcp');
+}
+
+function ensurePlaywrightMcpCli() {
+    return ensureGlobalNpmPackage('playwright-mcp', '@playwright/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 = {
+        codegraph: { command: 'codegraph', args: ['serve', '--mcp'] },
+        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\.codegraph\]/.test(existing)) {
+        blocks.push(`[mcp_servers.codegraph]
+command = "codegraph"
+args = ["serve", "--mcp"]
+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 context7, codegraph, playwright MCP in ${filePath}` };
+}
+
+const DOD_HOOK_MARKER = 'feature/refactor Definition-of-Done gate';
 
-function readJsonFile(filePath) {
-    if (!fs.existsSync(filePath)) return {};
-    try {
-        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    } catch {
-        return null;
-    }
+function generateDodStopHookPrompt() {
+    return `Input JSON (Stop hook payload): $ARGUMENTS\n\nCheck this project's ${DOD_HOOK_MARKER} (defined in AGENTS.md "Gated Flow" and .agent/docs/workflow.md "Definition of Done"). 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\nFor a feature or refactor (multi-file change, new behavior, or non-trivial refactor), the work must go through spec -> plan -> implement -> review before being reported as complete:\n- spec: \`.agent/workflows/spec.md\` (skip allowed for trivial/self-contained changes)\n- plan: \`.agent/workflows/plan.md\`, with a plan artifact such as \`docs/PLAN-*.md\` and explicit user approval\n- review: \`.agent/workflows/review.md\` five-axis review, with blocking issues resolved\n\nSimple/self-contained fixes (single-line, typo, or unambiguous one-file change) may use /simple and are explicitly exempt from spec+plan+review only when the final response states FAST_PATH: simple-fix, its reason, and its narrow scope. They should never be blocked when those criteria are met. Verification is still mandatory.\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, the final response does not claim the task is done/complete, or the final response explicitly contains FAST_PATH: simple-fix and the changed scope is clearly a simple/self-contained fix, allow stopping.\n4. If it is a feature/refactor-scale change and the final response claims completion, verify that a plan artifact exists with evidence of user approval and that a review pass was completed. If either gate is missing, block; a generic statement that the task was simple is not enough.\n5. Return exactly JSON: {"ok": true} to allow stopping, or {"ok": false, "reason": "..."} to block.\n\nWhen blocking, name exactly which gate is missing and instruct the assistant to run the relevant workflow or explicitly state why the task qualifies as a simple fix.`;
 }
 
-function writeJsonFile(filePath, data) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+function isDefinitionOfDoneHook(hook) {
+    const prompt = hook && typeof hook.prompt === 'string' ? hook.prompt : '';
+    return prompt.includes(DOD_HOOK_MARKER) || (
+        prompt.includes('Input JSON (Stop hook payload)') &&
+        prompt.includes('.agent/workflows/spec.md') &&
+        prompt.includes('.agent/workflows/review.md')
+    );
 }
 
-function mergeMcpJson(filePath, withType = false) {
+function mergeClaudeProjectHooks(filePath) {
     const data = readJsonFile(filePath);
     if (data === null) {
-        return { ok: false, message: `${filePath} is not valid JSON; skipped` };
+        return { ok: false, message: `${filePath} is not valid JSON; skipped hook setup` };
     }
-    data.mcpServers = data.mcpServers || {};
-    const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-    const baseServers = {
-        codegraph: { command: 'codegraph', args: ['serve', '--mcp'] },
-        playwright: { command: npxCmd, args: ['-y', '@playwright/mcp'] },
-        context7: { command: npxCmd, args: ['-y', '@upstash/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);
+    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;
             }
         }
     }
-    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 = [];
-    const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-    if (!/\[mcp_servers\.context7\]/.test(existing)) {
-        blocks.push(`[mcp_servers.context7]
-command = "${npxCmd}"
-args = ["-y", "@upstash/context7-mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (!/\[mcp_servers\.codegraph\]/.test(existing)) {
-        blocks.push(`[mcp_servers.codegraph]
-command = "codegraph"
-args = ["serve", "--mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
-    }
-    if (!/\[mcp_servers\.playwright\]/.test(existing)) {
-        blocks.push(`[mcp_servers.playwright]
-command = "${npxCmd}"
-args = ["-y", "@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 context7, codegraph, playwright MCP in ${filePath}` };
-}
-
-function setupMcpServers() {
-    const results = [];
-    results.push(ensureCodegraphCli());
-
-    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;
-}
-
-// --- Main CLI ---
-
-async function main() {
-    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 (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);
+        }
 
-    if (command !== 'init') {
-        console.error(pc.red(`Unknown command: ${command}`));
-        printHelp();
-        process.exit(1);
+        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}`
+        };
     }
 
-    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}`);
+    data.hooks.Stop.push({
+        hooks: [
+            {
+                type: 'agent',
+                prompt: generateDodStopHookPrompt(),
+                timeout: 60,
+                statusMessage: 'Checking feature/refactor Definition-of-Done gate...'
+            }
+        ]
     });
-    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',
-        max_file_lines: scanned?.max_file_lines || '300'
-    };
-
-    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.max_file_lines = data.max_file_lines || scanned?.max_file_lines || '300';
-    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 = !skipMcpSetup;
-
-    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
-
-    // Shared entry files are written after the .agent folder is available.
-
-    // Copy .agent folder
-    const { copied, skipped } = copyAgentFolder();
-    if (copied > 0) {
-        console.log(`  ${pc.green('OK')} Copied ${pc.bold('.agent/')} (${copied} file${copied !== 1 ? 's' : ''} added${skipped > 0 ? `, ${skipped} skipped` : ''})`);
-    } else if (skipped > 0) {
-        console.log(`  ${pc.yellow('~')} ${pc.bold('.agent/')} already exists - ${skipped} file${skipped !== 1 ? 's' : ''} skipped (no overwrite)`);
-    }
-
-    const nativeSkills = copySelectedSkillFolders(data, assumeYes);
-    if (nativeSkills.copied > 0) {
-        console.log(`  ${pc.green('OK')} Copied native skills to ${pc.bold('~/.codex/skills/')} and ${pc.bold('.claude/skills/')} (${nativeSkills.skills.join(', ')})`);
-    } else if (nativeSkills.skipped > 0) {
-        console.log(`  ${pc.yellow('~')} Native skills already exist - ${nativeSkills.skipped} file${nativeSkills.skipped !== 1 ? 's' : ''} skipped`);
-    }
-
-
-    const generatedFiles = [
-        ['AGENTS.md', generateSharedAgentsMd(data)],
-        ['CLAUDE.md', generateSharedClaudeMd(data)],
-        ['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(data)],
-        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()],
-        [path.join('.agent', 'docs', 'tooling.md'), generateToolingDoc(data)]
-    ];
-
-    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
-    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
-    - ${pc.bold('~/.codex/skills/')} selected Codex skills installed globally (visible in $ menu)
-    - ${pc.bold('.claude/skills/')} selected Claude Code native skills
-
-  ${pc.bold('MCP/tooling setup:')}
-    - Codegraph CLI checked or installed; MCP configured for Codex, Gemini/Antigravity, and Claude Code
-    - Context7 MCP configured for Codex and Gemini/Antigravity
-    - Playwright MCP configured for Codex, Gemini/Antigravity, and Claude Code
-    - Browser install hint: ${pc.bold(resolveToolingSetup(data).playwrightCommand)}
-    - Codegraph index hint: run ${pc.bold('codegraph init -i')} when a project index is missing, then keep ${pc.bold('.codegraph/')} uncommitted
-
-  ${pc.bold('Next steps:')}
-    1. Copy the prompt below into your AI editor and describe what the project does
-    2. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, ${pc.bold('.cursorrules')}, and ${pc.bold('.agent/')}
-    3. Open the project in Codex, Antigravity, Claude Code, or Cursor
-
-  ${pc.bold('Copy this prompt into your AI editor:')}
-${pc.dim('---')}
-Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
-Ask me what this project does and any important conventions I want preserved.
-Then scan this repository.
-Update CLAUDE.md, AGENTS.md, .cursorrules and .agent/docs/project.md, .agent/docs/architecture.md, .agent/docs/conventions.md, .agent/docs/workflow.md, and .agent/docs/tooling.md with factual project-specific rules.
-Do not implement product code.
-Remove TODO: refine only when backed by evidence from the codebase.
-${pc.dim('---')}
-`);
+    writeJsonFile(filePath, data);
+    return { ok: true, message: `configured Definition-of-Done Stop hook in ${filePath}` };
 }
 
-main().catch(err => {
-    console.error(pc.red('\nError during init:'), err);
-    process.exit(1);
-});
+function setupMcpServers() {
+    const results = [];
+    results.push(ensureCodegraphCli());
+    results.push(ensureContext7Cli());
+    results.push(ensurePlaywrightMcpCli());
+
+    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;
+}
+
+// --- Main CLI ---
+
+async function main() {
+    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 !== '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',
+        max_file_lines: scanned?.max_file_lines || '300'
+    };
+
+    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.max_file_lines = data.max_file_lines || scanned?.max_file_lines || '300';
+    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 = !skipMcpSetup;
+
+    console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
+
+    // Shared entry files are written after the .agent folder is available.
+
+    // Copy .agent folder
+    const { copied, skipped } = copyAgentFolder();
+    if (copied > 0) {
+        console.log(`  ${pc.green('OK')} Copied ${pc.bold('.agent/')} (${copied} file${copied !== 1 ? 's' : ''} added${skipped > 0 ? `, ${skipped} skipped` : ''})`);
+    } else if (skipped > 0) {
+        console.log(`  ${pc.yellow('~')} ${pc.bold('.agent/')} already exists - ${skipped} file${skipped !== 1 ? 's' : ''} skipped (no overwrite)`);
+    }
+
+    const nativeSkills = copySelectedSkillFolders(data, assumeYes);
+    if (nativeSkills.copied > 0) {
+        console.log(`  ${pc.green('OK')} Copied native skills to ${pc.bold('~/.codex/skills/')} and ${pc.bold('.claude/skills/')} (${nativeSkills.skills.join(', ')})`);
+    } else if (nativeSkills.skipped > 0) {
+        console.log(`  ${pc.yellow('~')} Native skills already exist - ${nativeSkills.skipped} file${nativeSkills.skipped !== 1 ? 's' : ''} skipped`);
+    }
+
+
+    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(data)],
+        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()],
+        [path.join('.agent', 'docs', 'tooling.md'), generateToolingDoc(data)],
+        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()]
+    ];
+
+    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)}`);
+    }
+
+    console.log(`\n${pc.bold(pc.cyan('Configuring Claude Code hooks'))}`);
+    const hookResult = mergeClaudeProjectHooks(path.join(targetDir, '.claude', 'settings.json'));
+    console.log(`  ${hookResult.ok ? pc.green('OK') : pc.yellow('~')} ${hookResult.message}`);
+
+    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, including ${pc.bold('getting-started.md')} (standard flow vs fast path)
+    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
+    - ${pc.bold('~/.codex/skills/')} selected Codex skills installed globally (visible in $ menu)
+    - ${pc.bold('.claude/skills/')} selected Claude Code native skills
+    - ${pc.bold('.claude/settings.json')} Definition-of-Done Stop hook (Claude Code only — blocks reporting a feature/refactor "done" without a plan + review pass)
+
+  ${pc.bold('MCP/tooling setup:')}
+    - Codegraph CLI checked or installed; MCP configured for Codex, Gemini/Antigravity, and Claude Code
+    - Context7 MCP configured for Codex and Gemini/Antigravity
+    - Playwright MCP configured for Codex, Gemini/Antigravity, and Claude Code
+    - Browser install hint: ${pc.bold(resolveToolingSetup(data).playwrightCommand)}
+    - Codegraph index hint: run ${pc.bold('codegraph init -i')} when a project index is missing, then keep ${pc.bold('.codegraph/')} uncommitted
+
+  ${pc.bold('Next steps:')}
+    1. Read ${pc.bold('.agent/docs/getting-started.md')} for the standard flow vs fast path
+    2. Copy the prompt below into your AI editor and describe what the project does
+    3. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, ${pc.bold('.cursorrules')}, ${pc.bold('.agent/')}, and ${pc.bold('.claude/settings.json')}
+    4. Open the project in Codex, Antigravity, Claude Code, or Cursor
+
+  ${pc.bold('Copy this prompt into your AI editor:')}
+${pc.dim('---')}
+Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
+Ask me what this project does and any important conventions I want preserved.
+Then scan this repository.
+Update CLAUDE.md, AGENTS.md, .cursorrules and .agent/docs/project.md, .agent/docs/architecture.md, .agent/docs/conventions.md, .agent/docs/workflow.md, and .agent/docs/tooling.md with factual project-specific rules.
+Do not implement product code.
+Remove TODO: refine only when backed by evidence from the codebase.
+${pc.dim('---')}
+`);
+}
+
+main().catch(err => {
+    console.error(pc.red('\nError during init:'), err);
+    process.exit(1);
+});