thachvd-kit 1.0.26 → 1.0.27

package/.agent/docs/getting-started.md

@@ -0,0 +1,81 @@
+# 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.
+
+## Start Every Task With /task
+
+Use `/task <request>` before editing whenever the route is not already obvious. 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 | `/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 |
+
+## Standard Feature Flow
+
+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.
+
+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 `/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 `/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 `/task`.
+
+## Command And Skill Map
+
+- `/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.
+
+## 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/`.

package/.agent/docs/project.md

@@ -1,6 +1,6 @@
 # Project Rules
 
-Generated by thachvd-kit on 2026-06-16.
+Generated by thachvd-kit on 2026-08-13.
 
 ## Summary
 
@@ -26,6 +26,18 @@ Generated by thachvd-kit on 2026-06-16.
 - Test: `npm test`
 - Lint: `npm run 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 |

package/.agent/docs/tooling.md

@@ -8,7 +8,7 @@ Use Playwright for browser and UI verification when a task touches web behavior.
 
 - Check availability: `npx playwright --version`
 - Install browsers: `npx playwright install`
-- Codex MCP CLI setup: `codex mcp add playwright -- npx -y @playwright/mcp`
+- 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`
 
@@ -18,8 +18,7 @@ Codex `config.toml` example:
 
 ```toml
 [mcp_servers.context7]
-command = "npx"
-args = ["-y", "@upstash/context7-mcp"]
+command = "context7-mcp"
 startup_timeout_sec = 20
 tool_timeout_sec = 120
 
@@ -30,8 +29,7 @@ startup_timeout_sec = 20
 tool_timeout_sec = 120
 
 [mcp_servers.playwright]
-command = "npx"
-args = ["-y", "@playwright/mcp"]
+command = "playwright-mcp"
 startup_timeout_sec = 20
 tool_timeout_sec = 120
 ```
@@ -70,16 +68,14 @@ Gemini CLI / Antigravity `mcp_config.json` example:
       "args": ["serve", "--mcp"]
     },
     "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
+      "command": "context7-mcp"
     },
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
     },
     "playwright": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp"]
+      "command": "playwright-mcp"
     }
   }
 }
@@ -103,8 +99,7 @@ Claude Code user config example:
     },
     "context7": {
       "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
+      "command": "context7-mcp"
     },
     "filesystem": {
       "type": "stdio",
@@ -113,8 +108,7 @@ Claude Code user config example:
     },
     "playwright": {
       "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp"]
+      "command": "playwright-mcp"
     }
   }
 }

package/.agent/docs/workflow.md

@@ -4,10 +4,24 @@
 
 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.
+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.
 
+## Route Matrix
+
+| 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 |
+
+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.
@@ -21,6 +35,16 @@
 
 ## Implementation Flow
 
+For `/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.
@@ -28,6 +52,24 @@
 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.
+
+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 `/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.

package/.agent/rules/GEMINI.md

@@ -27,13 +27,28 @@ Antigravity-compatible entry rules for thachvd-kit projects.
 
 Load only the agent, skill, or workflow files relevant to the current task.
 
-## Execution
-
-- Questions and analysis: answer directly; do not edit code.
-- Simple fix: inspect dependencies, make the smallest change, verify.
-- Feature or refactor: state assumptions, define success criteria, plan, implement, verify.
-- UI work: use relevant frontend design skills before editing.
-- Security or deploy work: run the matching checklist before claiming done.
+## Execution
+
+- Route every task before editing. Use `/task <request>` when the correct path is not obvious.
+- Questions and analysis: answer directly; do not edit code.
+- 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`.
+- Release or npm publish: use `/release`; never use the simple fast path.
+- UI work: use relevant frontend design skills before editing.
+- Security or deploy work: run the matching checklist before claiming done.
+
+### Fast Path (`/simple`)
+
+The fast path bypasses only Spec, Plan, and the feature/refactor Review gate for a trivial change. It never bypasses inspection or verification. State `FAST_PATH: simple-fix`, the reason, and the narrow scope before editing. Re-route with `/task` if the scope expands.
+
+### Gated Flow (feature or refactor)
+
+1. **Spec** — `.agent/workflows/spec.md` when scope is ambiguous, multi-file, or >~30 min. Skip only for single-line/self-contained fixes. Wait for human confirmation at its exit criteria.
+2. **Plan** — `.agent/workflows/plan.md`. Wait for explicit user approval before implementing.
+3. **Implement** — smallest coherent change per the approved plan, with focused tests.
+4. **Review** — `.agent/workflows/review.md` (five-axis). All 🔴 BLOCKING items resolved or explicitly accepted before calling the task done.
 
 ## Standards
 

package/.agent/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.

package/.agent/workflows/simple.md

@@ -0,0 +1,40 @@
+---
+description: Fast path for one-file, unambiguous fixes with no behavior or shared-contract change.
+---
+
+# /simple - Fast Path
+
+$ARGUMENTS
+
+## Use Only When
+
+- The change is limited to one obvious file or one tiny local edit.
+- The expected result is unambiguous.
+- No behavior, API, schema, security, CI, dependency, workflow, or release contract changes.
+
+## Explicit Bypass
+
+Start the response with:
+
+```text
+FAST_PATH: simple-fix
+REASON: [why Spec/Plan/Review are not needed]
+SCOPE: [file or narrow area]
+```
+
+## Steps
+
+1. Inspect the target and its immediate context.
+2. Make the smallest change.
+3. Run focused verification.
+4. Report the changed file and evidence.
+
+Do not create a spec or plan for this route. Do not skip verification. If the scope expands, stop and re-route through `/task` as a feature, bug, or multi-domain task.
+
+## Examples
+
+```text
+/simple fix a typo in README.md
+/simple update one stale command in a workflow doc
+/simple change one test assertion message
+```

package/.agent/workflows/task.md

@@ -0,0 +1,57 @@
+---
+description: Route every task to the smallest safe workflow, fast path, bug flow, feature flow, or release flow.
+---
+
+# /task - Task Router
+
+$ARGUMENTS
+
+## Purpose
+
+Use `/task` at the start of a task when you are unsure which workflow, skill, or specialist agent applies. This command routes the request before implementation.
+
+## Required Output
+
+```text
+ROUTE: question | simple | feature | bug | review | release | multi-domain
+WORKFLOW: [exact .agent/workflows/<name>.md file]
+SKILLS: [skills to load, or none]
+AGENTS: [specialist agents to load, or none]
+GATE: fast-path | standard
+NEXT: [the next command or action]
+```
+
+Do not write code while routing. Ask one concise clarification question if the route cannot be determined safely.
+
+## Routing Rules
+
+| Signal | Route | Next action |
+|---|---|---|
+| Asking for information or architecture explanation | question | Answer directly; no edits |
+| One obvious file, no behavior or contract change | simple | Use `/simple <request>` |
+| New behavior, multiple files, unclear scope, or >30 minutes | feature | `/brainstorm` -> `/spec` when needed -> `/plan`, then approval |
+| Failing test, regression, error, or unknown root cause | bug | Use `/debug <symptom>` |
+| Review request or pre-merge check | review | Use `/review` |
+| npm version/tag/publish request | release | Use `/release` |
+| Several specialist domains | multi-domain | Use `/orchestrate` |
+
+## Workflow And Skill Map
+
+- `/simple`: `$clean-code` + `$verification-before-completion`.
+- `/brainstorm`: `brainstorming`; no code.
+- `/spec`: `.agent/workflows/spec.md`; define scope and acceptance criteria, no code.
+- `/plan`: `project-planner` + `plan-writing`; no code before approval.
+- `/enhance` or `/create`: relevant domain agent and implementation skills after approval.
+- `/debug`: `debugger` + `$systematic-debugging` + `testing-patterns`.
+- `/test`: `test-engineer` + `testing-patterns`.
+- `/review`: `$code-review-checklist` + `$verification-before-completion`.
+- `/release`: `release.md` and the npm release scripts; never use the fast path.
+
+## Examples
+
+```text
+/task add an export button
+/task login returns 500
+/task fix typo in README
+/task publish a new npm version
+```

package/README.md

@@ -1,17 +1,17 @@
-# thachvd-kit
-
-`thachvd-kit` bootstraps shared project rules for AI coding agents.
-
-It creates a compact cross-agent entry setup for Codex, Antigravity, and Claude Code, then stores scan-based project knowledge under `.agent/docs/` so the root instruction files stay small.
-
-## Quick Start
-
-Install globally:
-
-```bash
-npm install -g thachvd-kit
-```
-
+# thachvd-kit
+
+`thachvd-kit` bootstraps shared project rules for AI coding agents.
+
+It creates a compact cross-agent entry setup for Codex, Antigravity, and Claude Code, then stores scan-based project knowledge under `.agent/docs/` so the root instruction files stay small.
+
+## Quick Start
+
+Install globally:
+
+```bash
+npm install -g thachvd-kit
+```
+
 Run inside a project:
 
 ```bash
@@ -60,10 +60,48 @@ Skills work best through progressive disclosure: the agent should first see skil
 - Keep `.agent/skills` as the complete shared source from the kit.
 - Let `thachvd-kit` copy selected skills to `~/.codex/skills/` for Codex and `.claude/skills` for Claude Code.
 - Make every `SKILL.md` frontmatter `description` specific: include when to use it, trigger phrases, and boundaries.
-- Run `thachvd-kit --help` to see a compact workflow guide without adding that guidance to every agent context. It recommends when to use `/brainstorm`, `/plan`, `/create`, `/enhance`, `/debug`, `/test`, `/preview`, `/deploy`, `/status`, and `/orchestrate`.
+- Run `thachvd-kit --help` to see a compact workflow guide without adding that guidance to every agent context. It recommends when to use `/task`, `/simple`, `/brainstorm`, `/plan`, `/create`, `/enhance`, `/debug`, `/test`, `/preview`, `/deploy`, `/review`, `/release`, `/status`, and `/orchestrate`.
 - Use explicit prompts when implicit matching misses, for example `Use $webapp-testing to verify this UI` or `Use $clean-code before refactoring`.
 - Restart Codex or Claude Code if a newly copied or edited skill does not appear.
 
+## Development Workflow
+
+After install, every AI client starts at `/task <request>` when the route is not already obvious. `/task` selects the smallest safe workflow and the relevant skills/agents; it does not force the full feature gate onto every request.
+
+| Situation | Command | Required flow |
+|---|---|---|
+| Question or analysis | direct answer | no edits |
+| One obvious local fix | `/simple <request>` | inspect → edit → focused verify |
+| Bug or failing behavior | `/debug <symptom>` | reproduce → root cause → regression test → fix → verify |
+| New behavior or refactor | `/task` → `/brainstorm` → `/spec` when needed → `/plan` | approval → implement → test → `/review` |
+| Pre-merge review | `/review` | five-axis review; resolve blocking findings |
+| npm version/tag/publish | `/release` | release verification; never fast path |
+| Several specialist domains | `/orchestrate` | plan → approval → parallel work → integration verify |
+
+### Standard Feature Flow
+
+`/task` → `/brainstorm` when needed → `/spec` for ambiguous or multi-file scope → `/plan` → explicit user approval → implementation → `/test` → `/review` → final verification → commit/push.
+
+Workflow files define process and gates. Skills define methods/checklists. Agents provide specialist ownership. Members should invoke the command, not only describe the work in chat.
+
+### Bug Fix Flow
+
+Use `/debug` for regressions, failing tests, exceptions, incorrect output, or any symptom with an unknown root cause. Load `$systematic-debugging`, the `debugger` agent, and `testing-patterns`; reproduce the issue, inspect the code path, test hypotheses, add regression protection, make the smallest root-cause fix, and verify. Use `/review` when the change is cross-file or affects a shared contract.
+
+### Simple Fast Path
+
+Use `/simple` only for one obvious file, an unambiguous result, and no behavior, API, schema, security, CI, dependency, workflow, or release contract change. 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 or verification. If the scope expands, stop and run `/task` again.
+
+Claude Code has a Stop hook that checks the standard feature/refactor gate. Codex, Antigravity, and Cursor use the same written routing rules through `AGENTS.md`, `.cursorrules`, and `.agent/rules/GEMINI.md`.
+
 ## Optional Tooling
 
 `init` performs setup and prints what it configured:
@@ -107,4 +145,38 @@ npm test
 npm pack --dry-run
 ```
 
+## Npm Release Flow
+
+An npm release is never a simple fix. Release only from a clean `main` branch after the change has passed the feature/refactor gates and has been pushed to GitHub.
+
+```bash
+# 1. Verify the clean, pushed source
+git status --short --branch
+npm run release:verify
+
+# 2. Bump patch version, create the version commit and git tag
+npm run release:patch
+
+# 3. Push the version commit and tag
+git push origin main --follow-tags
+
+# 4. Confirm npm authentication, then publish
+npm whoami
+npm run release:publish
+
+# 5. Verify the registry and the installed CLI
+npm view thachvd-kit version
+npx thachvd-kit@<published-version> --help
+```
+
+`npm run release:patch` runs the verification command first through `preversion`; `npm version patch` then updates `package.json`/`package-lock.json`, creates a commit, and creates a git tag. A published `name@version` cannot be reused, so do not publish until the version and tarball are correct. Use `npm publish --tag beta` for a prerelease channel instead of changing `latest`.
+
+### Which Flow To Use
+
+- **Question/analysis:** answer or inspect only; no files changed, so no spec/plan/review.
+- **Simple fix:** one unambiguous file, no behavior/API/schema/security/CI/release contract change; inspect, edit, run focused verification, summarize.
+- **Feature/refactor:** any new behavior, multiple files, dependency/API/schema/security/CI changes, or work likely over 30 minutes; run Spec → user-approved Plan → Implement → Review → verification.
+- **Multi-domain task:** route through `.agent/workflows/orchestrate.md`.
+- **Release/publish:** only after the relevant implementation flow is complete; run the npm release flow above. Never bypass release verification.
+
 The npm package page updates only after `npm publish`.

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
+${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
-  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      /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 /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.
@@ -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. 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: 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.
+
+### Fast Path (\`/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 \`/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 \`/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 \`/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.
+
+## Route Matrix
+
+| 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 |
+
+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 \`/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 \`/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 \`/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,91 @@ 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.
+
+## Start Every Task With /task
+
+Use \`/task <request>\` before editing whenever the route is not already obvious. 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 | \`/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 |
+
+## Standard Feature Flow
+
+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.
+
+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 \`/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 \`/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 \`/task\`.
+
+## Command And Skill Map
+
+- \`/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.
+
+## 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';
@@ -1560,6 +1724,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());
@@ -1694,7 +1930,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 +1940,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 +1962,11 @@ 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('.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 +1976,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.27",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/cli.js"
@@ -23,6 +23,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/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.

package/workflows/simple.md

@@ -0,0 +1,40 @@
+---
+description: Fast path for one-file, unambiguous fixes with no behavior or shared-contract change.
+---
+
+# /simple - Fast Path
+
+$ARGUMENTS
+
+## Use Only When
+
+- The change is limited to one obvious file or one tiny local edit.
+- The expected result is unambiguous.
+- No behavior, API, schema, security, CI, dependency, workflow, or release contract changes.
+
+## Explicit Bypass
+
+Start the response with:
+
+```text
+FAST_PATH: simple-fix
+REASON: [why Spec/Plan/Review are not needed]
+SCOPE: [file or narrow area]
+```
+
+## Steps
+
+1. Inspect the target and its immediate context.
+2. Make the smallest change.
+3. Run focused verification.
+4. Report the changed file and evidence.
+
+Do not create a spec or plan for this route. Do not skip verification. If the scope expands, stop and re-route through `/task` as a feature, bug, or multi-domain task.
+
+## Examples
+
+```text
+/simple fix a typo in README.md
+/simple update one stale command in a workflow doc
+/simple change one test assertion message
+```

package/workflows/task.md

@@ -0,0 +1,57 @@
+---
+description: Route every task to the smallest safe workflow, fast path, bug flow, feature flow, or release flow.
+---
+
+# /task - Task Router
+
+$ARGUMENTS
+
+## Purpose
+
+Use `/task` at the start of a task when you are unsure which workflow, skill, or specialist agent applies. This command routes the request before implementation.
+
+## Required Output
+
+```text
+ROUTE: question | simple | feature | bug | review | release | multi-domain
+WORKFLOW: [exact .agent/workflows/<name>.md file]
+SKILLS: [skills to load, or none]
+AGENTS: [specialist agents to load, or none]
+GATE: fast-path | standard
+NEXT: [the next command or action]
+```
+
+Do not write code while routing. Ask one concise clarification question if the route cannot be determined safely.
+
+## Routing Rules
+
+| Signal | Route | Next action |
+|---|---|---|
+| Asking for information or architecture explanation | question | Answer directly; no edits |
+| One obvious file, no behavior or contract change | simple | Use `/simple <request>` |
+| New behavior, multiple files, unclear scope, or >30 minutes | feature | `/brainstorm` -> `/spec` when needed -> `/plan`, then approval |
+| Failing test, regression, error, or unknown root cause | bug | Use `/debug <symptom>` |
+| Review request or pre-merge check | review | Use `/review` |
+| npm version/tag/publish request | release | Use `/release` |
+| Several specialist domains | multi-domain | Use `/orchestrate` |
+
+## Workflow And Skill Map
+
+- `/simple`: `$clean-code` + `$verification-before-completion`.
+- `/brainstorm`: `brainstorming`; no code.
+- `/spec`: `.agent/workflows/spec.md`; define scope and acceptance criteria, no code.
+- `/plan`: `project-planner` + `plan-writing`; no code before approval.
+- `/enhance` or `/create`: relevant domain agent and implementation skills after approval.
+- `/debug`: `debugger` + `$systematic-debugging` + `testing-patterns`.
+- `/test`: `test-engineer` + `testing-patterns`.
+- `/review`: `$code-review-checklist` + `$verification-before-completion`.
+- `/release`: `release.md` and the npm release scripts; never use the fast path.
+
+## Examples
+
+```text
+/task add an export button
+/task login returns 500
+/task fix typo in README
+/task publish a new npm version
+```