thachvd-kit 1.0.31 → 1.0.33

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 thachvd
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 thachvd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,99 +1,109 @@
-# thachvd-kit
-
-`thachvd-kit` bootstraps project context for AI coding agents. It creates shared entry files and scan-based documentation so an agent can understand the repository quickly.
-
-Workflow skills are intentionally not copied into projects. Install [Superpowers](https://github.com/obra/superpowers#installation) through the official plugin surface for the AI client each member uses.
-
-## Quick Start
-
-```bash
-npm install -g thachvd-kit
-cd your-project
-thachvd-kit init
-thachvd-kit setup
-thachvd-kit doctor
-```
-
-`init` is safe and project-focused. It does not install external tools, modify global AI skill folders, or create a second workflow engine.
-
-## Generated Files
-
-- `AGENTS.md`: shared project instructions.
-- `CLAUDE.md`: Claude Code entry file importing `AGENTS.md`.
-- `GEMINI.md`: Antigravity entry file.
-- `.cursorrules`: Cursor entry file.
-- `.agent/docs/project.md`: detected stack, commands, and project evidence.
-- `.agent/docs/architecture.md`: architecture notes to refine over time.
-- `.agent/docs/conventions.md`: coding and verification conventions.
-- `.agent/docs/workflow.md`: the project workflow contract.
-- `.agent/docs/tooling.md`: Superpowers, MCP, RTK, and Playwright setup.
-- `.agent/docs/getting-started.md`: member onboarding guide.
-- `.agent/docs/index-project-prompt.md`: durable prompt for the first project scan.
-
-The kit does not generate `.agent/skills`, `.agent/workflows`, `.agent/agents`, Forge commands, Claude hooks, or client-specific skill copies.
-
-## Workflow
-
-Superpowers is the primary workflow backend:
-
-1. `brainstorming` for unclear requirements.
-2. `using-git-worktrees` for isolated work.
-3. `writing-plans`, then explicit approval.
-4. `test-driven-development` and `executing-plans` or `subagent-driven-development`.
-5. `requesting-code-review` and `verification-before-completion`.
-6. `finishing-a-development-branch`.
-
-For bugs, use `systematic-debugging`: reproduce, inspect, test hypotheses, add regression protection, fix the root cause, and verify.
-
-For a trivial one-file change with no behavior or contract change, use the client's fast path. State the narrow scope and verification before editing. If the scope grows, return to brainstorming and planning.
-
-## Integrations
-
-### Superpowers
-
-Install it separately for each AI client. The official guide contains the current commands for Claude Code, Antigravity, Codex App, Codex CLI, and Cursor.
-
-### codebase-memory-mcp
-
-Use it for symbol search, call paths, architecture, and impact analysis:
-
-```bash
-npm install -g codebase-memory-mcp
-codebase-memory-mcp cli index_repository --repo-path .
-```
-
-The index is local state. Keep it out of git unless the team explicitly chooses to share a snapshot.
-
-### RTK
-
-RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands:
-
-```bash
-cargo install --git https://github.com/rtk-ai/rtk --branch master rtk
-```
-
-Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installed, run the underlying command directly.
-
-## CLI
-
-```text
-thachvd-kit init [--yes]
-thachvd-kit setup [--no-setup-mcp]
-thachvd-kit doctor
-thachvd-kit prompt
-thachvd-kit --help
-```
-
-`setup` configures MCP entries for detected clients and prints official Superpowers installation guidance. It may install npm-based MCP packages when they are missing. `doctor` is read-only and reports missing integrations without changing the machine.
-
-The project-indexing prompt is saved by `init`, so installing Superpowers or RTK afterward cannot make it disappear. Run `thachvd-kit prompt` whenever you need to print it again.
-
-## Development
-
-```bash
-npm install
-npm test
-npm run release:verify
-```
-
-Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.
+# thachvd-kit
+
+`thachvd-kit` bootstraps project context for AI coding agents. It creates shared entry files and scan-based documentation so an agent can understand the repository quickly.
+
+Workflow skills are intentionally not copied into projects. Install [Superpowers](https://github.com/obra/superpowers#installation) through the official plugin surface for the AI client each member uses.
+
+## Quick Start
+
+```bash
+npm install -g thachvd-kit
+cd your-project
+thachvd-kit init
+thachvd-kit setup
+thachvd-kit doctor
+```
+
+`init` is safe and project-focused. It does not install external tools, modify global AI skill folders, or create a second workflow engine.
+
+## Generated Files
+
+- `AGENTS.md`: shared project instructions.
+- `CLAUDE.md`: Claude Code entry file importing `AGENTS.md`.
+- `GEMINI.md`: Antigravity entry file.
+- `.cursorrules`: Cursor entry file.
+- `.agent/docs/project.md`: detected stack, commands, and project evidence.
+- `.agent/docs/architecture.md`: architecture notes to refine over time.
+- `.agent/docs/conventions.md`: coding and verification conventions.
+- `.agent/docs/workflow.md`: the project workflow contract.
+- `.agent/docs/tooling.md`: Superpowers, MCP, RTK, and Playwright setup.
+- `.agent/docs/getting-started.md`: member onboarding guide.
+- `.agent/docs/index-project-prompt.md`: durable prompt for the first project scan.
+
+`init` does not generate `.agent/skills`, `.agent/workflows`, `.agent/agents`, Forge commands, or client-specific skill copies. `setup` can optionally add a Claude Code Stop hook (see below); it never adds workflow content of its own.
+
+## Workflow
+
+Superpowers is the primary workflow backend:
+
+1. `brainstorming` for unclear requirements.
+2. `using-git-worktrees` for isolated work.
+3. `writing-plans`, then explicit approval.
+4. `test-driven-development` and `executing-plans` or `subagent-driven-development`.
+5. `requesting-code-review` and `verification-before-completion`.
+6. `finishing-a-development-branch`.
+
+For bugs, use `systematic-debugging`: reproduce, inspect, test hypotheses, add regression protection, fix the root cause, and verify.
+
+Fast-path eligibility is based on risk and contract surface, not file count. A localized, mechanically obvious, low-risk change with focused verification can use the client fast path; a one-file security, schema, payment, concurrency, or public-contract change should not.
+
+## Engineering Policy
+
+The generated context optimizes for the **smallest sufficient change**, not the fewest lines of code.
+
+- Preserve required behavior, product and architectural contracts, UX/accessibility, security/data integrity, compatibility/performance, and maintainability before optimizing for simplicity.
+- Reuse an existing project abstraction when it satisfies the contract. Do not bypass it merely because a lower-level primitive is shorter.
+- Avoid speculative abstractions and unrelated refactors.
+- Do not split code solely to satisfy a hard line-count target; prefer cohesive modules and split only for a concrete design or maintenance benefit.
+- Use the cheapest reliable context source. Read known local code directly; use structural tooling for unknown ownership, call paths, architecture, or impact; avoid duplicate retrieval when one source already provides enough evidence.
+
+## Integrations
+
+### Superpowers
+
+Install it separately for each AI client. The official guide contains the current commands for Claude Code, Antigravity, Codex App, Codex CLI, and Cursor.
+
+### codebase-memory-mcp
+
+Use it for structural discovery when symbol ownership, call paths, architecture, or impact are not already obvious:
+
+```bash
+npm install -g codebase-memory-mcp
+codebase-memory-mcp cli index_repository --repo-path .
+```
+
+The index is local state. Keep it out of git unless the team explicitly chooses to share a snapshot. If another structural index such as CodeGraph already provides sufficient evidence, avoid querying both for the same question.
+
+### RTK
+
+RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands:
+
+```bash
+cargo install --git https://github.com/rtk-ai/rtk --branch master rtk
+```
+
+Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installed, run the underlying command directly.
+
+## CLI
+
+```text
+thachvd-kit init [--yes]
+thachvd-kit setup [--no-setup-mcp] [--no-setup-hook] [--no-install-rtk] [--no-index]
+thachvd-kit doctor
+thachvd-kit prompt
+thachvd-kit --help
+```
+
+`setup` configures MCP entries for detected clients, prints official Superpowers installation guidance, and adds a Claude Code Stop hook that checks for Plan/Review/Verification evidence before a feature or refactor can be reported as done (skip with `--no-setup-hook`). The hook only checks for evidence; it never prescribes which skill must produce it, so it works whether that evidence came from Superpowers or from a manual process. It also auto-installs missing npm-based MCP packages (`codebase-memory-mcp`, `context7-mcp`, `playwright-mcp`), indexes the current repository with `codebase-memory-mcp` (skip with `--no-index`), and installs `rtk` via `cargo` when `cargo` is available (skip with `--no-install-rtk`). Superpowers itself cannot be auto-installed by this CLI — it is installed through each AI client's own plugin command (e.g. `/plugin install ...` typed in the client's chat), not a shell command this tool can run. `doctor` is read-only and reports missing integrations without changing the machine.
+
+The project-indexing prompt is saved by `init`, so installing Superpowers or RTK afterward cannot make it disappear. Run `thachvd-kit prompt` whenever you need to print it again.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run release:verify
+```
+
+Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.