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:

npm install -g thachvd-kit

Run inside a project:

thachvd-kit

By default, thachvd-kit scans the current project, generates shared AI-agent files, installs/configures Codegraph when needed, and configures Context7, Codegraph, and Playwright MCP for local AI clients. Use --no-setup-mcp to skip machine-level MCP setup.

What init Generates

• AGENTS.md: shared entry instructions for Codex, Antigravity, Claude Code, and Cursor.
• CLAUDE.md: Claude Code entry file that imports AGENTS.md.
• GEMINI.md: Antigravity entry file that points to AGENTS.md.
• .cursorrules: Cursor entry file that points to AGENTS.md.
• .agent/docs/project.md: stack, commands, routing, and scan evidence.
• .agent/docs/architecture.md: architecture map and maintenance rule.
• .agent/docs/conventions.md: coding and verification conventions.
• .agent/docs/workflow.md: repeatable task flow for future AI work.
• .agent/docs/tooling.md: setup hints for Playwright, codegraph, and native Codex/Claude skill folders.
• .agent/agents, .agent/skills, .agent/workflows, .agent/rules.
• ~/.codex/skills/: selected Codex skills copied to the global user dir.
• .claude/skills: selected Claude Code project skills copied from the kit.

Why Docs Live Under .agent/docs

Root instruction files are loaded often, so they should stay short and stable. Project-specific details belong in .agent/docs/:

• update project.md when stack, scripts, or tooling changes;
• update architecture.md when structure or boundaries change;
• update conventions.md when repeated patterns become clear;
• update workflow.md when the repo needs special task steps.

AGENTS.md tells every AI agent to read these docs before coding. If a doc contains TODO: refine, the agent should scan the repository and update the doc before product code changes.

Platform Notes

• Codex reads AGENTS.md.
• Claude Code reads CLAUDE.md; this kit uses @AGENTS.md inside CLAUDE.md so Claude shares the same rules.
• Antigravity can use GEMINI.md; this kit points it back to the shared AGENTS.md.
• .agent/skills is committed shared knowledge. thachvd-kit also copies selected native skills into ~/.codex/skills/ for Codex and .claude/skills for Claude Code.

Skill Usage Best Practice

Skills work best through progressive disclosure: the agent should first see skill names and descriptions, then read only the matching SKILL.md body.

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

Optional Tooling

init performs setup and prints what it configured:

• Playwright: install browsers with npx playwright install for Node projects, or pip install playwright && playwright install chromium when using the Python helper.
• Auto setup: thachvd-kit installs the Codegraph CLI when missing and merges MCP config for Codex, Gemini/Antigravity, and Claude Code.
• Codex MCP: uses ~/.codex/config.toml with [mcp_servers.context7], [mcp_servers.codegraph], and [mcp_servers.playwright].
• Gemini/Antigravity MCP: uses mcp_config.json with a top-level mcpServers object. The generated config includes codegraph, context7, and playwright.
• Claude Code MCP: uses ~/.claude.json with a top-level mcpServers object.
• Codegraph indexes: .codegraph/ is local state and should not be committed.
• Native skills: Codex global skills live in ~/.codex/skills/, Claude Code project skills live in .claude/skills/, and the full shared source remains in .agent/skills/.

Directory Layout

.agent/
├── agents/
├── docs/
│   ├── architecture.md
│   ├── conventions.md
│   ├── project.md
│   ├── tooling.md
│   └── workflow.md
├── rules/
├── skills/
└── workflows/

The generated project copies selected native skills to global user folder and project folder:

~/.codex/skills/
.claude/skills/

Development

npm install
npm test
npm pack --dry-run

The npm package page updates only after npm publish.