thachvd-kit 1.0.26 → 1.0.28

package/bin/cli.js

@@ -144,23 +144,34 @@ ${pc.bold('What gets generated:')}
   ~/.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:')}
-  Idea is fuzzy            /brainstorm  Explore options, tradeoffs, and recommended direction
-  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
+${pc.bold('Workflow guide:')}
+  Every task               /prompts:task   Classify request and select workflow, skill, and agent
+  Small obvious fix        /prompts:simple Fast path; skips spec/plan/review but still verifies
+  Idea is fuzzy            /brainstorm  Explore options, tradeoffs, and recommended direction
+  Scope needs a contract    /prompts: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  /prompts:debug Investigate symptoms, 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
-  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 /brainstorm for this feature idea before planning.
-  Use /plan for this feature; do not write code yet.
-  Use /enhance to implement this planned feature.
+  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      /prompts: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:')}
+  In Codex, use /prompts:task to route this request before editing.
+  In Codex, use /prompts:simple for a one-file fix with no behavior or contract change.
+  Use /brainstorm for this feature idea before planning.
+  In Codex, use /prompts: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.
+  In Codex, use /prompts:debug for this failing behavior and find the root cause before editing.
+  Use /review before claiming this feature/refactor complete.
+  In Codex, use /prompts: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.
@@ -906,14 +917,40 @@ Shared operating instructions for Codex, Antigravity, Claude Code, and Cursor.
 
 If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
 
-## Task Flow
-
-- 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.
-- 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.
-
+## Task Flow
+
+Route every task before editing. In Codex, use \`/prompts:task <request>\`; other clients can read the matching file under \`.agent/workflows/\`.
+
+- Questions and analysis: answer directly, cite relevant files when useful, and do not edit code.
+- Simple fix: use Codex \`/prompts:simple <request>\` only for one-file, unambiguous changes with no behavior or contract change.
+- Bug or failing behavior: use Codex \`/prompts:debug <symptom>\` and follow the evidence-first root-cause flow.
+- Feature or refactor: use \`/brainstorm\` for discovery, Codex \`/prompts: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 Codex \`/prompts: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.
+
+### Fast Path (Codex \`/prompts:simple\`)
+
+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:
+
+\`\`\`text
+FAST_PATH: simple-fix
+REASON: [why the change is one-file and unambiguous]
+SCOPE: [file or narrow area]
+\`\`\`
+
+If the scope expands, stop and re-route with Codex \`/prompts: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)
+
+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.
+
+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 Codex \`/prompts:simple\` fast path above. See \`.agent/docs/getting-started.md\` for the complete route guide.
+
 ## Skill Loading
 
 - Treat \`.agent/skills/\` as the shared source of truth for all kit skills.
@@ -968,7 +1005,7 @@ Read AGENTS.md first, then follow the shared docs under .agent/docs/.
 }
 
 function generateSharedCursorrules(data) {
-    return `# Cursor Rules
+    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.
 
@@ -976,8 +1013,8 @@ Read AGENTS.md first, then follow the shared docs under .agent/docs/.
 
 ---
 
-${generateSharedAgentsMd(data)}
-`;
+${generateSharedAgentsMd(data).trimEnd()}
+`;
 }
 
 function resolveCommands(data) {
@@ -1148,9 +1185,23 @@ function generateWorkflowDoc() {
 
 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.
-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.
+3. Route the request with Codex \`/prompts:task <request>\` when the path is not obvious; otherwise read \`.agent/workflows/task.md\` directly.
+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.
+
+## Route Matrix
+
+| Situation | Command | Workflow / gate |
+|---|---|---|
+| Question or analysis only | direct answer | no edits |
+| One obvious local fix | Codex \`/prompts:simple\` | \`.agent/workflows/simple.md\`, fast-path |
+| Bug, regression, failing test, or unknown error | Codex \`/prompts:debug\` | \`.agent/workflows/debug.md\`, evidence-first |
+| New behavior, multi-file change, or unclear scope | \`/brainstorm\` -> Codex \`/prompts: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 | Codex \`/prompts:release\` | \`.agent/workflows/release.md\`, release gate |
+| Several specialist domains | \`/orchestrate\` | plan -> approval -> parallel work -> integration verify |
+
+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
 
@@ -1165,6 +1216,16 @@ function generateWorkflowDoc() {
 
 ## Implementation Flow
 
+For Codex \`/prompts:simple\` fixes, state the fast-path decision before editing:
+
+\`\`\`text
+FAST_PATH: simple-fix
+REASON: [why Spec/Plan/Review are not needed]
+SCOPE: [file or narrow area]
+\`\`\`
+
+Then:
+
 1. State assumptions and success criteria when the task is not trivial.
 2. Inspect dependent files before editing.
 3. Make the smallest coherent change.
@@ -1172,6 +1233,24 @@ function generateWorkflowDoc() {
 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 Codex \`/prompts:debug\` with \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
+
+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.
+
+## Definition of Done (feature or refactor)
+
+A feature/refactor task is only complete when all of the following hold — not when code compiles or tests pass:
+
+The Spec checkbox may be skipped only when the documented Codex \`/prompts:simple\` fast-path protocol is stated and its criteria are met.
+
+- [ ] \`.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
+
+Do not report a feature/refactor task as done if any box above is unchecked — say explicitly which gate is still open.
+
 ## When To Update Docs
 
 - Update .agent/docs/architecture.md when structure, boundaries, or entry points change.
@@ -1181,6 +1260,102 @@ function generateWorkflowDoc() {
 `;
 }
 
+function generateGettingStartedDoc() {
+    return `# Getting Started With This Kit
+
+Read this after \`thachvd-kit init\`. The kit gives every member one entry point, then selects only the process and expertise the task needs.
+
+## Client Command Map
+
+| Client | Task router | Simple fix | Bug fix | Feature spec | Release |
+|---|---|---|---|---|---|
+| Codex | \`/prompts:task\` | \`/prompts:simple\` | \`/prompts:debug\` | \`/prompts:spec\` | \`/prompts:release\` |
+| Antigravity | \`/task\` | \`/simple\` | \`/debug\` | \`/spec\` | \`/release\` |
+| Claude Code | \`/task\` | \`/simple\` | \`/debug\` | \`/spec\` | \`/release\` |
+| Cursor | \`/task\` | \`/simple\` | \`/debug\` | \`/spec\` | \`/release\` |
+
+Codex reads custom prompts from \`~/.codex/prompts\`. Antigravity reads workspace workflows from \`.agent/workflows\`. Claude Code reads project skills from \`.claude/skills/<name>/SKILL.md\`. Cursor reads commands from \`.cursor/commands\`.
+
+## Start Every Task With The Router
+
+In Codex, use \`/prompts:task <request>\` before editing whenever the route is not already obvious. Other clients can read \`.agent/workflows/task.md\` directly. It must produce:
+
+\`\`\`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]
+\`\`\`
+
+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.
+
+## Route Matrix
+
+| 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 | \`/prompts:simple <request>\` in Codex | fast-path | inspect -> edit -> focused verify |
+| New behavior, multi-file change, unclear scope, or >~30 min | \`/prompts:task\` -> \`/brainstorm\` -> \`/prompts:spec\` when needed -> \`/plan\` | standard | wait for approval before implementation |
+| Bug, regression, failing test, or unknown error | \`/prompts:debug <symptom>\` in Codex | 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 | \`/prompts:release\` in Codex | release | release checklist; never fast-path |
+| Frontend + backend + data/security together | \`/orchestrate\` | standard | plan -> approval -> specialist work -> integration verify |
+
+## Standard Feature Flow
+
+The gated sequence is Spec -> Plan -> Implement -> Review: \`/prompts:task\` -> \`/brainstorm\` -> \`/prompts:spec\` when scope is ambiguous or multi-file -> \`/plan\` -> user approves the plan -> implementation -> \`/test\` -> \`/review\` -> final verification -> commit/push.
+
+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\`.
+
+## Bug Fix Flow
+
+Use Codex \`/prompts:debug <symptom>\`, not the feature flow, when something is failing or the root cause is unknown:
+
+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.
+
+Load \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\` for this route.
+
+## Simple Fast Path
+
+Use Codex \`/prompts: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:
+
+\`\`\`text
+FAST_PATH: simple-fix
+REASON: [why Spec/Plan/Review are not needed]
+SCOPE: [file or narrow area]
+\`\`\`
+
+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 Codex \`/prompts:task\`.
+
+## Command And Skill Map
+
+- \`/brainstorm\`: clarify intent and tradeoffs; no code.
+- Codex \`/prompts: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.
+- Codex \`/prompts:debug\`: systematic root-cause investigation and regression protection.
+- \`/test\`: add or run tests and assess coverage.
+- \`/review\`: five-axis review before completion or merge.
+- Codex \`/prompts: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.
+
+## Enforcement
+
+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\`.
+
+Full details live in \`AGENTS.md\`, \`.agent/docs/workflow.md\`, and the matching file under \`.agent/workflows/\`.
+`;
+}
+
 function resolveToolingSetup(data) {
     const primaryLang = data.primary_language || 'javascript';
     const packageManager = data.package_manager || 'npm';
@@ -1372,7 +1547,7 @@ function copyAgentFolder() {
     return { copied, skipped: 0 };
 }
 
-function copySelectedSkillFolders(data, assumeYes) {
+function copySelectedSkillFolders(data, assumeYes) {
     const srcSkills = path.join(sourceDir, '.agent', 'skills');
     if (!fs.existsSync(srcSkills)) return { copied: 0, skipped: 0, missing: 0, skills: [] };
 
@@ -1415,8 +1590,55 @@ function copySelectedSkillFolders(data, assumeYes) {
         }
     }
 
-    return { copied, skipped: 0, missing, skills: selectedSkills };
-}
+    return { copied, skipped: 0, missing, skills: selectedSkills };
+}
+
+function copyCodexPrompts() {
+    const srcPrompts = path.join(sourceDir, 'prompts');
+    const codexPromptsDir = homePath('.codex', 'prompts');
+    if (!fs.existsSync(srcPrompts) || !codexPromptsDir) {
+        return { copied: 0, prompts: [] };
+    }
+
+    let copied = 0;
+    const prompts = [];
+    fs.mkdirSync(codexPromptsDir, { recursive: true });
+    for (const entry of fs.readdirSync(srcPrompts, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+        fs.copyFileSync(path.join(srcPrompts, entry.name), path.join(codexPromptsDir, entry.name));
+        copied++;
+        prompts.push(path.basename(entry.name, '.md'));
+    }
+    return { copied, prompts };
+}
+
+function copyClientWorkflowCommands() {
+    const srcPrompts = path.join(sourceDir, 'prompts');
+    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
+    const cursorCommandsDir = path.join(targetDir, '.cursor', 'commands');
+    if (!fs.existsSync(srcPrompts)) {
+        return { claude: 0, cursor: 0, prompts: [] };
+    }
+
+    let claude = 0;
+    let cursor = 0;
+    const prompts = [];
+    for (const entry of fs.readdirSync(srcPrompts, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+        const name = path.basename(entry.name, '.md');
+        const sourcePath = path.join(srcPrompts, entry.name);
+        const sourceContent = fs.readFileSync(sourcePath, 'utf8');
+        const cursorContent = sourceContent.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+        fs.mkdirSync(path.join(claudeSkillsDir, name), { recursive: true });
+        fs.copyFileSync(sourcePath, path.join(claudeSkillsDir, name, 'SKILL.md'));
+        fs.mkdirSync(cursorCommandsDir, { recursive: true });
+        fs.writeFileSync(path.join(cursorCommandsDir, entry.name), cursorContent, 'utf8');
+        claude++;
+        cursor++;
+        prompts.push(name);
+    }
+    return { claude, cursor, prompts };
+}
 
 async function writeGeneratedFile(relativePath, content, assumeYes) {
     const outputPath = path.join(targetDir, relativePath);
@@ -1560,6 +1782,78 @@ tool_timeout_sec = 120
     return { ok: true, message: `configured context7, codegraph, 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} (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 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 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() {
     const results = [];
     results.push(ensureCodegraphCli());
@@ -1677,12 +1971,22 @@ async function main() {
         console.log(`  ${pc.yellow('~')} ${pc.bold('.agent/')} already exists - ${skipped} file${skipped !== 1 ? 's' : ''} skipped (no overwrite)`);
     }
 
-    const nativeSkills = copySelectedSkillFolders(data, assumeYes);
+    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 codexPrompts = copyCodexPrompts();
+    if (codexPrompts.copied > 0) {
+        console.log(`  ${pc.green('OK')} Installed Codex custom prompts in ${pc.bold('~/.codex/prompts/')} (${codexPrompts.prompts.map(name => `/prompts:${name}`).join(', ')})`);
+    }
+
+    const clientCommands = copyClientWorkflowCommands();
+    if (clientCommands.claude > 0 || clientCommands.cursor > 0) {
+        console.log(`  ${pc.green('OK')} Installed workflow commands for Claude Code (${clientCommands.claude}) and Cursor (${clientCommands.cursor})`);
+    }
 
 
     const generatedFiles = [
@@ -1694,7 +1998,8 @@ async function main() {
         [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', 'tooling.md'), generateToolingDoc(data)],
+        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()]
     ];
 
     for (const [relativePath, content] of generatedFiles) {
@@ -1703,6 +2008,10 @@ async function main() {
         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()) {
@@ -1721,10 +2030,14 @@ async function main() {
     - ${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/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('~/.codex/skills/')} selected Codex skills installed globally (visible in $ menu)
+    - ${pc.bold('~/.codex/prompts/')} Codex custom prompts (visible as /prompts:<name> after restart)
+    - ${pc.bold('.claude/skills/')} selected Claude Code native skills
+    - ${pc.bold('.claude/skills/{task,simple,debug,spec,release}/')} workflow skills (visible as /task, /simple, /debug, /spec, /release)
+    - ${pc.bold('.cursor/commands/')} Cursor workflow commands (visible as /task, /simple, /debug, /spec, /release)
+    - ${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
@@ -1734,9 +2047,10 @@ async function main() {
     - 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
+    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('---')}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.26",
+    "version": "1.0.28",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/cli.js"
@@ -13,6 +13,7 @@
         "rules",
         "scripts",
         "skills",
+        "prompts",
         "workflows",
         "README.md",
         "LICENSE"
@@ -23,6 +24,8 @@
     },
     "scripts": {
         "test": "node test/cli.test.js",
+        "release:verify": "npm test && node --check bin/cli.js && npm pack --dry-run",
+        "preversion": "npm run release:verify",
         "release:patch": "npm version patch",
         "release:dry-run": "npm pack --dry-run",
         "release:publish": "npm publish"

package/prompts/debug.md

@@ -0,0 +1,11 @@
+---
+description: Investigate a bug with evidence, root-cause analysis, regression protection, and verification.
+argument-hint: [SYMPTOM]
+---
+
+Read and follow `.agent/workflows/debug.md` in the current repository.
+
+Bug or symptom:
+$ARGUMENTS
+
+Use `$systematic-debugging`, the `debugger` agent, and `testing-patterns` when available. Reproduce and isolate the root cause before editing.

package/prompts/release.md

@@ -0,0 +1,11 @@
+---
+description: Run the npm release workflow with verification, versioning, tagging, publishing, and registry checks.
+argument-hint: [RELEASE_REQUEST]
+---
+
+Read and follow `.agent/workflows/release.md` in the current repository.
+
+Release request:
+$ARGUMENTS
+
+Do not publish until the release gate and `npm run release:verify` pass.

package/prompts/simple.md

@@ -0,0 +1,11 @@
+---
+description: Run the fast path for one-file, unambiguous fixes with verification.
+argument-hint: [TASK]
+---
+
+Read and follow `.agent/workflows/simple.md` in the current repository.
+
+Request:
+$ARGUMENTS
+
+Use the fast path only when its criteria are met. State `FAST_PATH: simple-fix`, `REASON`, and `SCOPE` before editing. Never skip verification.

package/prompts/spec.md

@@ -0,0 +1,11 @@
+---
+description: Define requirements and acceptance criteria before planning or implementation.
+argument-hint: [REQUEST]
+---
+
+Read and follow `.agent/workflows/spec.md` in the current repository.
+
+Request:
+$ARGUMENTS
+
+Do not write product code. Stop at the spec gate and wait for human confirmation.

package/prompts/task.md

@@ -0,0 +1,12 @@
+---
+description: Route the current request to the smallest safe workflow before editing.
+argument-hint: [TASK]
+---
+
+Read and follow `.agent/workflows/task.md` in the current repository.
+
+Route this request before editing:
+
+$ARGUMENTS
+
+Return the required ROUTE, WORKFLOW, SKILLS, AGENTS, GATE, and NEXT fields. Do not edit code while routing.

package/workflows/release.md

@@ -0,0 +1,42 @@
+---
+description: Release the thachvd-kit npm package with verification, versioning, tagging, publishing, and registry checks.
+---
+
+# /release - Npm Release
+
+Use this workflow only after the implementation workflow is complete and the release commit is the only intended change.
+
+## Release Gate
+
+- [ ] Working tree is clean before starting.
+- [ ] Change is already reviewed and pushed to `main`.
+- [ ] `npm run release:verify` passes.
+- [ ] The next version is correct and has not been published.
+- [ ] npm authentication is available with `npm whoami`.
+- [ ] Rollback/response plan is known: npm versions cannot be overwritten or reused.
+
+## Commands
+
+```bash
+git status --short --branch
+npm run release:verify
+npm run release:patch
+git push origin main --follow-tags
+npm whoami
+npm run release:publish
+npm view thachvd-kit version
+npx thachvd-kit@<published-version> --help
+```
+
+`npm run release:patch` runs `preversion`, which executes the release verification, then `npm version patch` updates the package metadata and creates the version commit/tag. Do not run `npm publish` until the version and dry-run contents are correct.
+
+## Version Rules
+
+- Patch: backward-compatible fixes, docs, tests, and internal workflow improvements.
+- Minor: backward-compatible new CLI behavior or user-facing capability.
+- Major: breaking CLI, configuration, package, or generated-artifact contract.
+- Beta/prerelease: publish with a non-`latest` dist-tag, for example `npm publish --tag beta`.
+
+## Bypass Rules
+
+Questions and simple fixes bypass Spec/Plan/Review only when they do not change behavior or a shared contract. Publishing never bypasses `release:verify`, versioning, tagging, authentication, or registry verification.