thachvd-kit 1.0.17 → 1.0.19

package/.agent/skills/react-frontend/SKILL.md

@@ -1,25 +1,25 @@
----
-name: react-frontend
-description: React-focused frontend guidance for component architecture, state flow, rendering boundaries, and maintainable UI systems. Use for plain React apps that are not specifically Next.js-first.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
----
-
-# React Frontend
-
-This skill is the React-first counterpart to `nextjs-react-expert`.
-
-Use it when the project uses React without needing Next.js-specific assumptions such as SSR, App Router, or server components.
-
-## Guidance
-
-- Prefer the existing project architecture over introducing a new pattern.
-- Keep state ownership shallow and explicit.
-- Separate presentational UI from data-fetching and side effects when it improves maintainability.
-- Optimize rendering only after confirming an actual bottleneck.
-- Pair with `frontend-design` for UI/UX decisions.
-
-## Related Skills
-
-- `nextjs-react-expert` for Next.js-specific performance and routing concerns
-- `frontend-design` for layout, visual hierarchy, and responsive design
-- `clean-code` for naming, file boundaries, and readability
+---
+name: react-frontend
+description: React-focused frontend guidance for component architecture, state flow, rendering boundaries, and maintainable UI systems. Use for plain React apps that are not specifically Next.js-first.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# React Frontend
+
+This skill is the React-first counterpart to `nextjs-react-expert`.
+
+Use it when the project uses React without needing Next.js-specific assumptions such as SSR, App Router, or server components.
+
+## Guidance
+
+- Prefer the existing project architecture over introducing a new pattern.
+- Keep state ownership shallow and explicit.
+- Separate presentational UI from data-fetching and side effects when it improves maintainability.
+- Optimize rendering only after confirming an actual bottleneck.
+- Pair with `frontend-design` for UI/UX decisions.
+
+## Related Skills
+
+- `nextjs-react-expert` for Next.js-specific performance and routing concerns
+- `frontend-design` for layout, visual hierarchy, and responsive design
+- `clean-code` for naming, file boundaries, and readability

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,78 +1,109 @@
-# 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:
-
-```bash
-npm install -g thachvd-kit
-```
-
+# 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:
+
+```bash
+npm install -g thachvd-kit
+```
+
 Run inside a project:
 
 ```bash
-thachvd-kit init
-```
-
-For existing projects, scan first:
-
-```bash
-thachvd-kit init --scan
+thachvd-kit
 ```
 
-## What `init` Generates
-
-- `AGENTS.md`: shared entry instructions for Codex, Antigravity, and Claude Code.
-- `CLAUDE.md`: Claude Code entry file that imports `AGENTS.md`.
-- `GEMINI.md`: Antigravity entry file that points to `AGENTS.md`.
-- `.agent/docs/project.md`: stack, commands, routing, and scan evidence.
+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, and Claude Code.
+- `CLAUDE.md`: Claude Code entry file that imports `AGENTS.md`.
+- `GEMINI.md`: Antigravity 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`.
-
-## 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.
-
+- `.agents/skills`: selected repo-native Codex skills copied from the kit.
+- `.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`.
-
-## Directory Layout
-
-```text
-.agent/
-├── agents/
-├── docs/
+- `.agent/skills` is committed shared knowledge. `thachvd-kit` also copies selected native skills into `.agents/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 `.agents/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 repo skills live in `.agents/skills/`, Claude Code project skills live in `.claude/skills/`, and the full shared source remains in `.agent/skills/`. Codex may also keep installed/system skills in `$CODEX_HOME/skills` such as `~/.codex/skills`; do not treat repo `.codex/skills` as the generated project skill folder.
+
+## Directory Layout
+
+```text
+.agent/
+├── agents/
+├── docs/
 │   ├── architecture.md
 │   ├── conventions.md
 │   ├── project.md
+│   ├── tooling.md
 │   └── workflow.md
-├── rules/
-├── skills/
+├── rules/
+├── skills/
 └── workflows/
 ```
 
-## Development
+The generated project also gets selected native skill folders:
 
-```bash
-npm install
-npm test
-npm pack --dry-run
+```text
+.agents/skills/
+.claude/skills/
 ```
-
-The npm package page updates only after `npm publish`.
+
+## Development
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+```
+
+The npm package page updates only after `npm publish`.

package/agents/frontend-specialist.md

@@ -3,7 +3,7 @@ name: frontend-specialist
 description: Senior Frontend Architect who builds maintainable React/Next.js systems with performance-first mindset. Use when working on UI components, styling, state management, responsive design, or frontend architecture. Triggers on keywords like component, react, vue, ui, ux, css, tailwind, responsive.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
-skills: clean-code, react-frontend, nextjs-react-expert, web-design-guidelines, tailwind-patterns, frontend-design, lint-and-validate
+skills: clean-code, react-frontend, nextjs-react-expert, web-design-guidelines, tailwind-patterns, frontend-design, lint-and-validate
 ---
 
 # Senior Frontend Architect
@@ -575,7 +575,7 @@ After editing any file:
 
 ---
 
-> **Note:** This agent loads relevant skills (`react-frontend`, `nextjs-react-expert`, etc.) for detailed guidance. Apply behavioral principles from those skills rather than copying patterns.
+> **Note:** This agent loads relevant skills (`react-frontend`, `nextjs-react-expert`, etc.) for detailed guidance. Apply behavioral principles from those skills rather than copying patterns.
 
 ---
 

package/agents/mobile-developer.md

@@ -1,14 +1,14 @@
 ---
-name: mobile-developer
-description: Expert in React Native, Flutter, and Tauri-style app development. Use for cross-platform mobile or desktop apps, native features, and platform-specific UI patterns. Triggers on mobile, desktop, tauri, react native, flutter, ios, android, app store, expo.
+name: mobile-developer
+description: Expert in React Native, Flutter, and Tauri-style app development. Use for cross-platform mobile or desktop apps, native features, and platform-specific UI patterns. Triggers on mobile, desktop, tauri, react native, flutter, ios, android, app store, expo.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
-skills: clean-code, mobile-design, desktop-design
+skills: clean-code, mobile-design, desktop-design
 ---
 
 # Mobile Developer
 
-Expert app developer specializing in React Native, Flutter, and Tauri-style cross-platform development.
+Expert app developer specializing in React Native, Flutter, and Tauri-style cross-platform development.
 
 ## Your Philosophy