thachvd-kit 1.0.17 → 1.0.18

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

package/.agent/docs/architecture.md

@@ -1,22 +1,22 @@
-# Architecture Notes
-
-## Current Map
-
-- `bin/cli.js`: Main Node.js CLI. Handles scan detection, prompts, file generation, and `.agent/` copy.
-- `.agent/`: Installed kit content copied into target projects.
-- `agents/`, `skills/`, `workflows/`, `rules/`: Source mirrors for kit content.
-- `kit/`: Human-facing kit docs and prompt recipes.
-- `scripts/`: Helper scripts used by generated workflows.
-
-## Output Model
-
-`thachvd-kit init` creates thin root entry files and puts project-specific knowledge in `.agent/docs/`:
-
-- `AGENTS.md`: shared instructions for Codex, Antigravity, and Claude Code.
-- `CLAUDE.md`: imports `AGENTS.md` for Claude Code.
-- `GEMINI.md`: Antigravity entry that points to `AGENTS.md`.
-- `.agent/docs/*.md`: stack, architecture, conventions, and workflow.
-
-## Maintenance Rule
-
-Keep root entry files short. Add project-specific details to `.agent/docs/*` and reusable behavior to `.agent/skills/*` or `.agent/workflows/*`.
+# Architecture Notes
+
+## Current Map
+
+- `bin/cli.js`: Main Node.js CLI. Handles scan detection, prompts, file generation, and `.agent/` copy.
+- `.agent/`: Installed kit content copied into target projects.
+- `agents/`, `skills/`, `workflows/`, `rules/`: Source mirrors for kit content.
+- `kit/`: Human-facing kit docs and prompt recipes.
+- `scripts/`: Helper scripts used by generated workflows.
+
+## Output Model
+
+`thachvd-kit init` creates thin root entry files and puts project-specific knowledge in `.agent/docs/`:
+
+- `AGENTS.md`: shared instructions for Codex, Antigravity, and Claude Code.
+- `CLAUDE.md`: imports `AGENTS.md` for Claude Code.
+- `GEMINI.md`: Antigravity entry that points to `AGENTS.md`.
+- `.agent/docs/*.md`: stack, architecture, conventions, and workflow.
+
+## Maintenance Rule
+
+Keep root entry files short. Add project-specific details to `.agent/docs/*` and reusable behavior to `.agent/skills/*` or `.agent/workflows/*`.

package/.agent/docs/conventions.md

@@ -1,21 +1,21 @@
-# Coding Conventions
-
-## JavaScript CLI
-
-- Keep CLI behavior in `bin/cli.js` unless a helper becomes clearly reusable.
-- Prefer simple filesystem APIs from Node.js standard library.
-- Keep generated Markdown ASCII-only unless the target file already requires non-ASCII.
-- Avoid adding dependencies for small formatting or path operations.
-
-## Docs And Rules
-
-- Root `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` should stay concise.
-- Put scan-specific or project-specific detail in `.agent/docs/`.
-- Keep `.agent/rules/GEMINI.md` and `rules/GEMINI.md` aligned.
-- Keep mirrored source folders and `.agent/` content aligned when changing kit assets.
-
-## Verification
-
-- Syntax-check `bin/cli.js` after edits.
-- Run `npm test`.
-- Run `npm pack --dry-run` for package output changes.
+# Coding Conventions
+
+## JavaScript CLI
+
+- Keep CLI behavior in `bin/cli.js` unless a helper becomes clearly reusable.
+- Prefer simple filesystem APIs from Node.js standard library.
+- Keep generated Markdown ASCII-only unless the target file already requires non-ASCII.
+- Avoid adding dependencies for small formatting or path operations.
+
+## Docs And Rules
+
+- Root `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` should stay concise.
+- Put scan-specific or project-specific detail in `.agent/docs/`.
+- Keep `.agent/rules/GEMINI.md` and `rules/GEMINI.md` aligned.
+- Keep mirrored source folders and `.agent/` content aligned when changing kit assets.
+
+## Verification
+
+- Syntax-check `bin/cli.js` after edits.
+- Run `npm test`.
+- Run `npm pack --dry-run` for package output changes.

package/.agent/docs/project.md

@@ -1,40 +1,40 @@
-# Project Rules
-
-Generated by thachvd-kit.
-
-## Summary
-
-- Name: thachvd-kit
-- Description: Project rules bootstrap kit for Codex, Antigravity, and Claude Code.
-- Type: CLI package
-- App root: `.`
-
-## Stack
-
-- Language: JavaScript
-- Runtime: Node.js
-- Package manager: npm
-- CLI entry: `bin/cli.js`
-- Published package files: `.agent`, `agents`, `bin`, `kit`, `rules`, `scripts`, `skills`, `workflows`, `README.md`, `LICENSE`
-
-## Commands
-
-- Install: `npm install`
-- Test: `npm test`
-- Package dry run: `npm pack --dry-run`
-- Publish: `npm publish`
-
-## Agent Routing
-
-| Task Type | Agent | Primary Skills |
-|-----------|-------|----------------|
-| CLI behavior | `backend-specialist` | `nodejs-best-practices`, `clean-code` |
-| Docs/rules | `documentation-writer` | `documentation-templates` |
-| Workflow design | `project-planner` | `plan-writing`, `executing-plans` |
-| Security/release | `security-auditor` / `devops-engineer` | `vulnerability-scanner`, `deployment-procedures` |
-
-## Verification
-
-- Run `node --check bin/cli.js` after CLI edits.
-- Run `npm test` before claiming code changes are complete.
-- Run `npm pack --dry-run` before release-oriented changes.
+# Project Rules
+
+Generated by thachvd-kit.
+
+## Summary
+
+- Name: thachvd-kit
+- Description: Project rules bootstrap kit for Codex, Antigravity, and Claude Code.
+- Type: CLI package
+- App root: `.`
+
+## Stack
+
+- Language: JavaScript
+- Runtime: Node.js
+- Package manager: npm
+- CLI entry: `bin/cli.js`
+- Published package files: `.agent`, `agents`, `bin`, `kit`, `rules`, `scripts`, `skills`, `workflows`, `README.md`, `LICENSE`
+
+## Commands
+
+- Install: `npm install`
+- Test: `npm test`
+- Package dry run: `npm pack --dry-run`
+- Publish: `npm publish`
+
+## Agent Routing
+
+| Task Type | Agent | Primary Skills |
+|-----------|-------|----------------|
+| CLI behavior | `backend-specialist` | `nodejs-best-practices`, `clean-code` |
+| Docs/rules | `documentation-writer` | `documentation-templates` |
+| Workflow design | `project-planner` | `plan-writing`, `executing-plans` |
+| Security/release | `security-auditor` / `devops-engineer` | `vulnerability-scanner`, `deployment-procedures` |
+
+## Verification
+
+- Run `node --check bin/cli.js` after CLI edits.
+- Run `npm test` before claiming code changes are complete.
+- Run `npm pack --dry-run` before release-oriented changes.

package/.agent/docs/tooling.md

@@ -0,0 +1,123 @@
+# Optional Tooling
+
+This kit keeps tool setup explicit. Do not assume these tools are available until you verify them in the current environment.
+
+## Playwright
+
+Use Playwright for browser and UI verification when a task touches web behavior.
+
+- Check availability: `npx playwright --version`
+- Install browsers: `npx playwright install`
+- Codex MCP CLI setup: `codex mcp add playwright -- npx -y @playwright/mcp`
+- Auto setup: `thachvd-kit init`
+- Kit helper: `python .agent/skills/webapp-testing/scripts/playwright_runner.py <url> --screenshot`
+
+If the project already has Playwright configured, prefer the project's existing scripts.
+
+Codex `config.toml` example:
+
+```toml
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+## Codegraph
+
+Use codegraph for codebase exploration when the environment exposes it. The index is local state and should not be committed.
+
+- Check for an index: look for `.codegraph/`
+- Check CLI availability: `codegraph --help`
+- Install CLI if needed: `npm install -g @colbymchenry/codegraph`
+- Codex MCP CLI setup: `codex mcp add codegraph -- codegraph serve --mcp`
+- Auto setup: `thachvd-kit init`
+- If your Codex environment provides the codegraph CLI, run its project indexing step from the repository root.
+- Keep `.codegraph/` ignored in git.
+
+Codex `config.toml` example:
+
+```toml
+[mcp_servers.codegraph]
+command = "codegraph"
+args = ["serve", "--mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+Codex reads MCP servers from `~/.codex/config.toml` by default. For repo-local setup, use `.codex/config.toml`; Codex loads project config only for trusted projects.
+
+Gemini CLI / Antigravity `mcp_config.json` example:
+
+```json
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp"]
+    }
+  }
+}
+```
+
+Common local paths:
+
+- Gemini CLI: `~/.gemini/config/mcp_config.json`
+- Antigravity IDE: `~/.gemini/antigravity-ide/mcp_config.json`
+- Older Antigravity setups may use `~/.gemini/antigravity/mcp_config.json`
+
+Claude Code user config example:
+
+```json
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp"]
+    }
+  }
+}
+```
+
+Common local path:
+
+- Claude Code: `~/.claude.json`
+
+## Native Skill Folders
+
+The shared kit skills live in `.agent/skills/`. Antigravity can use that folder directly, but Codex expects repo skills under `.agents/skills/` or user skills under `~/.agents/skills/`. Claude Code may require its own native skill location depending on the installed client.
+
+- Codex repo skills: `.agents/skills/`
+- Codex user skills: `~/.agents/skills/`
+- Codex may also keep installed/system skills under `$CODEX_HOME/skills` such as `~/.codex/skills`; treat that as local Codex state, not a repo folder to generate or commit.
+- Claude Code project skills commonly live under `.claude/skills/`.
+- `thachvd-kit` copies selected native skills to `.agents/skills/` and `.claude/skills/` based on the detected stack.
+- Keep `.agent/skills/` as the full shared source of truth committed with the repo.
+
+Recommended candidates to copy first:
+
+- `clean-code`
+- `systematic-debugging`
+- `verification-before-completion`
+- Stack-specific skills listed in `.agent/docs/project.md`

package/.agent/docs/workflow.md

@@ -1,24 +1,35 @@
-# Agent Workflow
-
-## Before Every Task
-
+# Agent Workflow
+
+## Before Every Task
+
 1. Read `AGENTS.md`.
 2. Read `.agent/docs/project.md`.
 3. Classify the request.
 4. Load only the relevant agent, skill, or workflow docs.
 
-## Implementation Flow
+## Skill Selection
 
-1. State assumptions and success criteria when the task is not trivial.
-2. Inspect dependent files before editing.
-3. Make the smallest coherent change.
-4. Add or update focused tests when behavior changes.
-5. Run verification.
-6. Summarize changed files and verification evidence.
+- Prefer native skill discovery when the client exposes it.
+- Codex repo skills live in `.agents/skills`.
+- Claude Code project skills live in `.claude/skills`.
+- Shared fallback skills live in `.agent/skills`.
+- Do not load skill bodies by default.
+- Load a skill when the user mentions it, the task clearly matches its `SKILL.md` description, or `.agent/docs/project.md` routes the task to it.
+- Use explicit skill names in prompts for predictable behavior, for example `$webapp-testing` or `$clean-code`.
+- Run `thachvd-kit --help` to see common workflow and skill recommendations.
 
-## Release Flow
-
-1. Update package metadata when changing publish behavior.
-2. Run `npm test`.
-3. Run `npm pack --dry-run`.
-4. Review tarball contents before publish.
+## Implementation Flow
+
+1. State assumptions and success criteria when the task is not trivial.
+2. Inspect dependent files before editing.
+3. Make the smallest coherent change.
+4. Add or update focused tests when behavior changes.
+5. Run verification.
+6. Summarize changed files and verification evidence.
+
+## Release Flow
+
+1. Update package metadata when changing publish behavior.
+2. Run `npm test`.
+3. Run `npm pack --dry-run`.
+4. Review tarball contents before publish.

package/.agent/rules/GEMINI.md

@@ -1,45 +1,45 @@
----
-trigger: always_on
----
-
-# GEMINI.md
-
-Antigravity-compatible entry rules for thachvd-kit projects.
-
-## Startup
-
-1. Read `AGENTS.md` at the project root.
-2. Read `.agent/docs/project.md` for stack, commands, and routing.
-3. Read `.agent/docs/workflow.md` before editing.
-4. Read `.agent/docs/architecture.md` and `.agent/docs/conventions.md` before planning non-trivial code changes.
-5. If any `.agent/docs/*.md` file contains `TODO: refine`, update that doc from the real code before product code changes.
-
-## Routing
-
-- Frontend/UI: `.agent/agents/frontend-specialist.md`
-- Backend/API: `.agent/agents/backend-specialist.md`
-- Database/schema: `.agent/agents/database-architect.md`
-- Mobile/desktop: `.agent/agents/mobile-developer.md`
-- DevOps/CI/deploy: `.agent/agents/devops-engineer.md`
-- Debug/RCA: `.agent/agents/debugger.md`
-- Security: `.agent/agents/security-auditor.md`
-- Multi-domain: `.agent/agents/orchestrator.md`
-
-Load only the agent, skill, or workflow files relevant to the current task.
-
-## Execution
-
-- Questions and analysis: answer directly; do not edit code.
-- Simple fix: inspect dependencies, make the smallest change, verify.
-- Feature or refactor: state assumptions, define success criteria, plan, implement, verify.
-- UI work: use relevant frontend design skills before editing.
-- Security or deploy work: run the matching checklist before claiming done.
-
-## Standards
-
-- Respond in the user's language.
-- Keep code, identifiers, and code comments in English.
-- Prefer existing project patterns over new abstractions.
-- Keep changes surgical.
-- Tests or equivalent verification are mandatory.
-- Update `.agent/docs/*` when stack, architecture, workflow, or conventions change.
+---
+trigger: always_on
+---
+
+# GEMINI.md
+
+Antigravity-compatible entry rules for thachvd-kit projects.
+
+## Startup
+
+1. Read `AGENTS.md` at the project root.
+2. Read `.agent/docs/project.md` for stack, commands, and routing.
+3. Read `.agent/docs/workflow.md` before editing.
+4. Read `.agent/docs/architecture.md` and `.agent/docs/conventions.md` before planning non-trivial code changes.
+5. If any `.agent/docs/*.md` file contains `TODO: refine`, update that doc from the real code before product code changes.
+
+## Routing
+
+- Frontend/UI: `.agent/agents/frontend-specialist.md`
+- Backend/API: `.agent/agents/backend-specialist.md`
+- Database/schema: `.agent/agents/database-architect.md`
+- Mobile/desktop: `.agent/agents/mobile-developer.md`
+- DevOps/CI/deploy: `.agent/agents/devops-engineer.md`
+- Debug/RCA: `.agent/agents/debugger.md`
+- Security: `.agent/agents/security-auditor.md`
+- Multi-domain: `.agent/agents/orchestrator.md`
+
+Load only the agent, skill, or workflow files relevant to the current task.
+
+## Execution
+
+- Questions and analysis: answer directly; do not edit code.
+- Simple fix: inspect dependencies, make the smallest change, verify.
+- Feature or refactor: state assumptions, define success criteria, plan, implement, verify.
+- UI work: use relevant frontend design skills before editing.
+- Security or deploy work: run the matching checklist before claiming done.
+
+## Standards
+
+- Respond in the user's language.
+- Keep code, identifiers, and code comments in English.
+- Prefer existing project patterns over new abstractions.
+- Keep changes surgical.
+- Tests or equivalent verification are mandatory.
+- Update `.agent/docs/*` when stack, architecture, workflow, or conventions change.

package/.agent/skills/desktop-design/SKILL.md

@@ -1,25 +1,25 @@
----
-name: desktop-design
-description: Desktop and cross-platform app design guidance for Tauri and similar desktop shells. Use when building desktop-first interfaces, windowed workflows, keyboard-heavy UX, or cross-platform desktop UI behavior.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
----
-
-# Desktop Design
-
-This skill covers desktop-first product thinking where `mobile-design` is the wrong default.
-
-Use it for Tauri and other desktop-oriented apps with window management, keyboard shortcuts, dense layouts, or multi-panel workflows.
-
-## Guidance
-
-- Design for pointer + keyboard, not touch-first.
-- Use information density deliberately; desktop screens can support richer sidebars and multi-column layouts.
-- Respect platform conventions for menus, shortcuts, dialogs, file pickers, and drag/drop.
-- Assume resizing, multiple windows, and long-running sessions are normal.
-- Pair with `rust-pro` for Tauri backend/native concerns and `frontend-design` for UI execution.
-
-## Related Skills
-
-- `mobile-design` for touch-first mobile products
-- `frontend-design` for visual and interaction design
-- `rust-pro` for Rust and Tauri implementation details
+---
+name: desktop-design
+description: Desktop and cross-platform app design guidance for Tauri and similar desktop shells. Use when building desktop-first interfaces, windowed workflows, keyboard-heavy UX, or cross-platform desktop UI behavior.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Desktop Design
+
+This skill covers desktop-first product thinking where `mobile-design` is the wrong default.
+
+Use it for Tauri and other desktop-oriented apps with window management, keyboard shortcuts, dense layouts, or multi-panel workflows.
+
+## Guidance
+
+- Design for pointer + keyboard, not touch-first.
+- Use information density deliberately; desktop screens can support richer sidebars and multi-column layouts.
+- Respect platform conventions for menus, shortcuts, dialogs, file pickers, and drag/drop.
+- Assume resizing, multiple windows, and long-running sessions are normal.
+- Pair with `rust-pro` for Tauri backend/native concerns and `frontend-design` for UI execution.
+
+## Related Skills
+
+- `mobile-design` for touch-first mobile products
+- `frontend-design` for visual and interaction design
+- `rust-pro` for Rust and Tauri implementation details

package/.agent/skills/project-onboarding/SKILL.md

@@ -1,42 +1,42 @@
----
-name: project-onboarding
-description: Scan the repository and refine `.agent/docs/*` so all supported AI tools share accurate project rules.
----
-
-# Project Onboarding
-
-Use this skill when a project has just run `thachvd-kit init`, when `.agent/docs/*` contains `TODO: refine`, or when the stack/architecture has changed.
-
-## Goal
-
-Create or update the shared project docs used by Codex, Antigravity, and Claude Code:
-
-- `.agent/docs/project.md`
-- `.agent/docs/architecture.md`
-- `.agent/docs/conventions.md`
-- `.agent/docs/workflow.md`
-
-Do not create a legacy root context file.
-
-## Process
-
-1. Read `AGENTS.md`.
-2. Inspect repository structure, package/build config, test config, entry points, and representative source files.
-3. Update `.agent/docs/project.md` with stack, app root, commands, test/lint tooling, and routing.
-4. Update `.agent/docs/architecture.md` with major directories, entry points, boundaries, and important decisions.
-5. Update `.agent/docs/conventions.md` with real naming, formatting, API, state, styling, and testing patterns.
-6. Update `.agent/docs/workflow.md` only when the repository needs project-specific workflow steps.
-
-## Rules
-
-- Keep docs concise and factual.
-- Mark unknowns as `TODO: refine` only when the codebase does not provide evidence.
-- Do not implement product code during onboarding.
-- Do not overwrite unrelated user-maintained notes.
-
-## Completion Checklist
-
-- [ ] `.agent/docs/project.md` reflects actual stack and commands.
-- [ ] `.agent/docs/architecture.md` maps the current codebase.
-- [ ] `.agent/docs/conventions.md` captures observed patterns.
-- [ ] `.agent/docs/workflow.md` has the task flow agents should follow.
+---
+name: project-onboarding
+description: Scan the repository and refine `.agent/docs/*` so all supported AI tools share accurate project rules.
+---
+
+# Project Onboarding
+
+Use this skill when a project has just run `thachvd-kit init`, when `.agent/docs/*` contains `TODO: refine`, or when the stack/architecture has changed.
+
+## Goal
+
+Create or update the shared project docs used by Codex, Antigravity, and Claude Code:
+
+- `.agent/docs/project.md`
+- `.agent/docs/architecture.md`
+- `.agent/docs/conventions.md`
+- `.agent/docs/workflow.md`
+
+Do not create a legacy root context file.
+
+## Process
+
+1. Read `AGENTS.md`.
+2. Inspect repository structure, package/build config, test config, entry points, and representative source files.
+3. Update `.agent/docs/project.md` with stack, app root, commands, test/lint tooling, and routing.
+4. Update `.agent/docs/architecture.md` with major directories, entry points, boundaries, and important decisions.
+5. Update `.agent/docs/conventions.md` with real naming, formatting, API, state, styling, and testing patterns.
+6. Update `.agent/docs/workflow.md` only when the repository needs project-specific workflow steps.
+
+## Rules
+
+- Keep docs concise and factual.
+- Mark unknowns as `TODO: refine` only when the codebase does not provide evidence.
+- Do not implement product code during onboarding.
+- Do not overwrite unrelated user-maintained notes.
+
+## Completion Checklist
+
+- [ ] `.agent/docs/project.md` reflects actual stack and commands.
+- [ ] `.agent/docs/architecture.md` maps the current codebase.
+- [ ] `.agent/docs/conventions.md` captures observed patterns.
+- [ ] `.agent/docs/workflow.md` has the task flow agents should follow.