thachvd-kit 1.0.32 → 1.0.34

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

@@ -8,13 +8,16 @@ Workflow skills are intentionally not copied into projects. Install [Superpowers
 
 ```bash
 npm install -g thachvd-kit
+thachvd-kit global
 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.
+`global` installs a managed tool-routing block into the current user's Antigravity and Codex global instruction files while preserving unrelated user content. `init` is project-focused. It does not install external workflow skills or create a second workflow engine.
+
+For an existing project that already has refined `.agent/docs/*`, use `thachvd-kit upgrade` instead of re-running `init --yes`. `upgrade` only adds/updates thachvd-kit managed policy blocks and removes a small set of obsolete generated defaults; it preserves project-specific knowledge.
 
 ## Generated Files
 
@@ -45,7 +48,46 @@ Superpowers is the primary workflow backend:
 
 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.
+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.
+
+## Global Tool Routing
+
+`thachvd-kit global` patches a managed block into:
+
+- Antigravity: `~/.gemini/GEMINI.md`
+- Codex: `~/.codex/AGENTS.override.md` when a non-empty override exists, otherwise `~/.codex/AGENTS.md`
+
+The managed block encourages one structural index for structural questions, direct `rg`/`grep` for exact-text or narrow searches, RTK for verbose shell output, and duplicate-retrieval avoidance. It does not ban `rg` or raw commands when those are the cheaper or diagnostically necessary operation.
+
+Useful variants:
+
+```bash
+thachvd-kit global --dry-run
+thachvd-kit global --antigravity-only
+thachvd-kit global --codex-only
+```
+
+## Safe Project Upgrade
+
+For projects initialized by an older version:
+
+```bash
+cd existing-project
+thachvd-kit upgrade --dry-run
+thachvd-kit upgrade
+```
+
+`upgrade` does not rescan the repository or regenerate architecture/project knowledge. It preserves custom content and manages only marked policy blocks plus a small list of known obsolete defaults such as the old 300-line rule and `MCP First` wording.
 
 ## Integrations
 
@@ -55,14 +97,14 @@ Install it separately for each AI client. The official guide contains the curren
 
 ### codebase-memory-mcp
 
-Use it for symbol search, call paths, architecture, and impact analysis:
+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.
+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
 
@@ -78,13 +120,15 @@ Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installe
 
 ```text
 thachvd-kit init [--yes]
+thachvd-kit upgrade [--dry-run]
+thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
 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.
+`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, 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.