thachvd-kit 1.0.26 → 1.0.28

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

@@ -0,0 +1,92 @@
+# 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/`.

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 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
 
 - Prefer native skill discovery when the client exposes it.
@@ -21,6 +35,16 @@
 
 ## 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.
@@ -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 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.

package/.agent/rules/GEMINI.md

@@ -27,13 +27,29 @@ 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.
+- Workspace workflows are available as `/task`, `/simple`, `/debug`, `/spec`, and `/release` from `.agent/workflows/`.
+- 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,42 @@
+---
+description: Fast path for one-file, unambiguous fixes with no behavior or shared-contract change.
+---
+
+# /simple - Fast Path
+
+$ARGUMENTS
+
+Codex UI command: `/prompts:simple`. The `/simple` name below describes the workflow; it is not a built-in Codex slash command.
+
+## 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,59 @@
+---
+description: Route every task to the smallest safe workflow, fast path, bug flow, feature flow, or release flow.
+---
+
+# /task - Task Router
+
+$ARGUMENTS
+
+Codex UI command: `/prompts:task`. The `/task` name below describes the workflow; it is not a built-in Codex slash command.
+
+## 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,59 @@ 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. In Codex, custom prompts appear as `/prompts:task`, `/prompts:simple`, `/prompts:debug`, `/prompts:spec`, and `/prompts:release` after `init` and a Codex restart. Built-in commands such as `/plan` and `/review` remain unchanged.
 - 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 the task router when the route is not already obvious. In Codex, use `/prompts:task <request>`; other clients can read `.agent/workflows/task.md` directly. The router selects the smallest safe workflow and relevant skills/agents; it does not force the full feature gate onto every request.
+
+### Client Commands
+
+| Client | Router | Fast path | Bug flow | 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` |
+
+`init` installs these from the same source: Codex prompts in `~/.codex/prompts`, Antigravity workflows in `.agent/workflows`, Claude Code skills in `.claude/skills`, and Cursor commands in `.cursor/commands`. Restart or reload the client after the first installation if commands do not appear.
+
+| Situation | Command | Required flow |
+|---|---|---|
+| Question or analysis | direct answer | no edits |
+| One obvious local fix | `/prompts:simple <request>` in Codex | inspect → edit → focused verify |
+| Bug or failing behavior | `/prompts:debug <symptom>` in Codex | reproduce → root cause → regression test → fix → verify |
+| New behavior or refactor | `/prompts:task` → `/brainstorm` → `/prompts: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
+
+`/prompts:task` → `/brainstorm` when needed → `/prompts: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 `/prompts:debug` in Codex 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 `/prompts:simple` in Codex 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 `/prompts: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 +156,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`.