thachvd-kit 1.0.33 → 1.0.35

package/README.md

@@ -1,20 +1,31 @@
 # 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.
+`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, and it installs/checks [Matt Pocock's promoted skills](https://github.com/mattpocock/skills) — the single workflow layer for planning, implementation, debugging, architecture, and review.
 
-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.
+Skill bodies are intentionally not vendored into this kit or copied globally. `thachvd-kit skills install` delegates to the upstream `skills` CLI and installs the promoted set project-locally under `.agents/skills/`.
 
 ## Quick Start
 
 ```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.
+For an existing project:
+
+```bash
+thachvd-kit upgrade
+thachvd-kit setup
+thachvd-kit doctor
+```
+
+`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 safe and project-focused: it does not install external tools, install 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` — it only adds/updates thachvd-kit's managed policy blocks and removes a small set of obsolete generated defaults, preserving project-specific knowledge (see Safe Project Upgrade below). `setup` installs the promoted Matt Pocock skill set by default (`--no-install-skills` to skip) alongside MCP/RTK tooling.
+
+After the first skill install, run `/setup-matt-pocock-skills` once inside your AI client to configure the issue tracker, triage labels, and generated docs location — thachvd-kit does not simulate that skill.
 
 ## Generated Files
 
@@ -26,24 +37,25 @@ thachvd-kit doctor
 - `.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/tooling.md`: Matt Pocock skills, 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.
+`init` does not generate `.agent/skills`, `.agent/workflows`, `.agent/agents`, or client-specific skill copies — skills are installed by `thachvd-kit setup`/`skills install` into `.agents/skills/` instead. `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:
+[Matt Pocock's promoted skills](https://github.com/mattpocock/skills) (`skills/engineering/` + `skills/productivity/`) are the workflow layer, installed project-locally under `.agents/skills/`:
 
-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.
+- Ambiguous feature or design: `/grill-with-docs`, then optionally `/to-spec` for a durable contract.
+- Normal feature: `/grill-with-docs` -> `/to-spec` -> `/implement`.
+- Large feature needing decomposition: add `/to-tickets` before `/implement`.
+- Huge, multi-session uncertainty: `/wayfinder`.
+- Bug or failing behavior: `/diagnosing-bugs`.
+- Test-driven implementation: `/tdd`.
+- Architecture survey: `/improve-codebase-architecture` (`/codebase-design` for the design vocabulary).
+- Pre-completion review: `/code-review`.
+- Unsure which skill fits? Run `/ask-matt`.
 
 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.
 
@@ -57,11 +69,50 @@ The generated context optimizes for the **smallest sufficient change**, not the
 - 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
 
-### Superpowers
+### Matt Pocock Skills
+
+The promoted engineering + productivity catalog from [mattpocock/skills](https://github.com/mattpocock/skills), installed project-locally (never globally) under `.agents/skills/`:
+
+```bash
+thachvd-kit skills install        # install the promoted set (--dry-run to preview)
+thachvd-kit skills check          # read-only: report what's installed
+thachvd-kit skills update         # re-add each promoted skill individually to update it (slower: one clone per skill)
+```
+
+The manifest (`bin/matt-skills.js`) mirrors upstream's `skills/engineering/` + `skills/productivity/` catalog and deliberately excludes `skills/in-progress`, `skills/misc`, and `skills/deprecated`. Installation targets the Codex and Antigravity agent identifiers of the upstream `skills` CLI, both of which resolve to `.agents/skills/`.
 
-Install it separately for each AI client. The official guide contains the current commands for Claude Code, Antigravity, Codex App, Codex CLI, and Cursor.
+After the first install, run `/setup-matt-pocock-skills` once inside your AI client — it configures the issue tracker, triage labels, and generated docs location. thachvd-kit does not simulate that skill.
 
 ### codebase-memory-mcp
 
@@ -88,15 +139,20 @@ Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installe
 
 ```text
 thachvd-kit init [--yes]
-thachvd-kit setup [--no-setup-mcp] [--no-setup-hook] [--no-install-rtk] [--no-index]
+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] [--no-install-skills]
 thachvd-kit doctor
 thachvd-kit prompt
+thachvd-kit skills install [--dry-run]
+thachvd-kit skills check
+thachvd-kit skills update [--dry-run]
 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.
+`init` generates project context for a new project; `upgrade` and `global` are the safe, additive-only paths for an existing project or machine (see Safe Project Upgrade and Global Tool Routing above). `setup` installs the promoted Matt Pocock skill set by default (skip with `--no-install-skills`), configures MCP entries for detected clients, 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 a Matt Pocock skill or a manual process. `setup` 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`). `doctor` is read-only and reports missing integrations, including the promoted skill set, 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.
+The project-indexing prompt is saved by `init`, so installing skills or RTK afterward cannot make it disappear. Run `thachvd-kit prompt` whenever you need to print it again.
 
 ## Development