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, and it installs/checks Matt Pocock's promoted skills — the single workflow layer for planning, implementation, debugging, architecture, and review.

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

npm install -g thachvd-kit
thachvd-kit global
cd your-project
thachvd-kit init
thachvd-kit setup
thachvd-kit doctor

For an existing project:

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

• 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: 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, 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

Matt Pocock's promoted skills (skills/engineering/ + skills/productivity/) are the workflow layer, installed project-locally under .agents/skills/:

• 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.

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:

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:

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

Matt Pocock Skills

The promoted engineering + productivity catalog from mattpocock/skills, installed project-locally (never globally) under .agents/skills/:

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

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

Use it for structural discovery when symbol ownership, call paths, architecture, or impact are not already obvious:

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:

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

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] [--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

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 skills or RTK afterward cannot make it disappear. Run thachvd-kit prompt whenever you need to print it again.

Development

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.

Native Workflow Skills

The workflow layer combines Matt Pocock's planning and implementation skills with thachvd-kit's bundled native skills. thachvd-kit setup and thachvd-kit skills install install the native set to both .agents/skills/ and .claude/skills/.

• /using-git-worktrees is opt-in workspace isolation; an explicit choice to work on the current branch always wins.
• /subagent-driven-development is an alternative executor to /implement for plans with multiple relatively independent tasks. It uses bundled cross-platform Node entrypoints on Windows and falls back to /implement when subagent dispatch is unavailable.
• /finishing-a-development-branch verifies and hands off a branch, cleaning only manually managed project-local worktrees safely.

thachvd-kit skills update refreshes native skills from bundled repository copies and never fetches Superpowers at runtime. See THIRD_PARTY_NOTICES.md for recorded upstream provenance.