thachvd-kit 1.0.22 → 1.0.24

package/.agent/docs/architecture.md

@@ -1,23 +1,15 @@
-# 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, Claude Code, and Cursor.
-- `CLAUDE.md`: imports `AGENTS.md` for Claude Code.
-- `GEMINI.md`: points to `AGENTS.md` for Antigravity.
-- `.cursorrules`: points to `AGENTS.md` for Cursor.
-- `.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
+
+- App root is the repository root unless refined below.
+- TODO: refine major directories and responsibilities.
+- TODO: refine main entry points, routing, state boundaries, and integration boundaries.
+
+## Detected Evidence
+
+- language:javascript => found package.json; package.json -> JavaScript dependency graph
+
+## AI Maintenance Rule
+
+Before non-trivial implementation work, inspect this file. If it is stale or still contains TODO items relevant to the task, update it from the code before editing product code.

package/.agent/docs/conventions.md

@@ -1,21 +1,16 @@
-# 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`, `GEMINI.md`, and `.cursorrules` 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
+
+## Current Standards
+
+- Maximum file length: 300 lines unless the existing project standard is stricter.
+- Code comments and identifiers should be written in English.
+- Keep changes scoped to the user request.
+- Prefer existing local patterns over introducing new abstractions.
+- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.
+
+## Verification
+
+- Run the focused test or lint command that matches the touched area.
+- If no automated check exists, document the manual verification performed.
+- For UI/web changes, prioritize using Playwright MCP to automatically verify client-side behavior and capture screenshots.
+- Do not claim completion without verification evidence.

package/.agent/docs/project.md

@@ -1,40 +1,47 @@
-# 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 on 2026-06-16.
+
+## Summary
+
+- Name: thachvd-kit
+- Description: Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code
+- Type: cli
+- App root: .
+
+## Stack
+
+- Language: javascript
+- Frameworks: none
+- Database: none
+- Infrastructure: none
+- Package manager: npm
+- Test framework: auto-detect
+
+## Commands
+
+- Install: `npm install`
+- Dev: `npm run dev`
+- Build: `npm run build`
+- Test: `npm test`
+- Lint: `npm run lint`
+
+## Agent Routing
+
+| Task Type | Agent | Primary Skills |
+|-----------|-------|----------------|
+| Backend API | `backend-specialist` | nodejs-best-practices, api-design |
+| Debug | `debugger` | systematic-debugging |
+| Security | `security-auditor` | vulnerability-scanner |
+| Planning | `project-planner` | brainstorming, plan-writing |
+
+## Auto-Resolved Skills
+
+- api-design
+- clean-code
+- nodejs-best-practices
+- systematic-debugging
+
+## Scan Evidence
+
+- language:javascript => found package.json; package.json -> JavaScript dependency graph

package/.agent/docs/tooling.md

@@ -9,7 +9,7 @@ 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`
+- Auto setup: `thachvd-kit`
 - 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.
@@ -44,7 +44,7 @@ Use codegraph for codebase exploration when the environment exposes it. The inde
 - 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`
+- Auto setup: `thachvd-kit`
 - If your Codex environment provides the codegraph CLI, run its project indexing step from the repository root.
 - Keep `.codegraph/` ignored in git.
 
@@ -124,6 +124,8 @@ Common local path:
 
 - Claude Code: `~/.claude.json` or `~/.claude/settings.json`
 
+## Native Skill Folders
+
 The shared kit skills live in `.agent/skills/`. Antigravity reads that folder directly. Codex shows skills from `~/.codex/skills/` in the `$` menu. Claude Code reads project skills from `.claude/skills/`.
 
 - Codex global skills: `~/.codex/skills/` — installed by `thachvd-kit init`, visible in Codex `$` menu

package/.agent/docs/workflow.md

@@ -1,35 +1,36 @@
-# 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.
+# Agent Workflow
+
+## Before Every Task
+
+1. Read AGENTS.md.
+2. Read .agent/docs/project.md.
+3. Classify the request: question, survey, simple fix, feature, refactor, debug, UI, security, or deploy.
+4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
+5. Check if MCP servers (like `codegraph`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
 
 ## Skill Selection
 
 - 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`.
+- Codex global skills live in ~/.codex/skills/ and are visible via the $ menu; thachvd-kit copies selected skills there on init.
+- 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.
+- 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.
 
 ## 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.
+
+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 (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
+6. Summarize changed files and verification evidence.
+
+## When To Update Docs
+
+- Update .agent/docs/architecture.md when structure, boundaries, or entry points change.
+- Update .agent/docs/conventions.md when repeated project patterns become clear.
+- Update .agent/docs/project.md when stack, scripts, app root, test tooling, or routing changes.
+- Keep AGENTS.md concise. Put project-specific detail in .agent/docs.

package/bin/cli.js

@@ -931,6 +931,7 @@ If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the doc
 - State assumptions when the request is ambiguous.
 - Prefer the existing project style over new abstractions.
 - Keep changes surgical and remove only dead code introduced by your change.
+- **MCP First**: Prioritize using MCP server tools (e.g., \`codegraph\` for codebase search/symbol tracking, \`context7\` for API/docs queries, and \`playwright\` for browser/UI testing and verification) to explore, search, and verify rather than recursively listing directories, running expensive shell commands/grep, or reading large files. This minimizes token usage and maintains a cleaner context.
 - Tests or equivalent verification are mandatory before claiming done.
 - Keep files under ${data.max_file_lines || '300'} lines unless the project already has a different standard in \`.agent/docs/conventions.md\`.
 
@@ -948,9 +949,11 @@ If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the doc
 `;
 }
 
-function generateSharedClaudeMd() {
+function generateSharedClaudeMd(data) {
     return `@AGENTS.md
 
+${generateSharedAgentsMd(data)}
+
 ## Claude Code
 
 This repository uses AGENTS.md as the shared cross-agent entry file. Follow the imported instructions and keep Claude-specific notes here only when they cannot apply to Codex or Antigravity.
@@ -966,12 +969,16 @@ Read AGENTS.md first, then follow the shared docs under .agent/docs/.
 `;
 }
 
-function generateSharedCursorrules() {
+function generateSharedCursorrules(data) {
     return `# Cursor Rules
 
 This repository uses AGENTS.md as the shared cross-agent entry file. Follow the instructions in AGENTS.md and keep Cursor-specific notes here only when they cannot apply to Codex, Antigravity, or Claude Code.
 
 Read AGENTS.md first, then follow the shared docs under .agent/docs/.
+
+---
+
+${generateSharedAgentsMd(data)}
 `;
 }
 
@@ -1119,6 +1126,7 @@ function generateConventionsDoc(data) {
 
 - Run the focused test or lint command that matches the touched area.
 - If no automated check exists, document the manual verification performed.
+- For UI/web changes, prioritize using Playwright MCP to automatically verify client-side behavior and capture screenshots.
 - Do not claim completion without verification evidence.
 `;
 }
@@ -1132,6 +1140,7 @@ function generateWorkflowDoc() {
 2. Read .agent/docs/project.md.
 3. Classify the request: question, survey, simple fix, feature, refactor, debug, UI, security, or deploy.
 4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
+5. Check if MCP servers (like \`codegraph\`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
 
 ## Skill Selection
 
@@ -1150,7 +1159,7 @@ function generateWorkflowDoc() {
 2. Inspect dependent files before editing.
 3. Make the smallest coherent change.
 4. Add or update focused tests when behavior changes.
-5. Run verification.
+5. Run verification (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
 6. Summarize changed files and verification evidence.
 
 ## When To Update Docs
@@ -1476,18 +1485,10 @@ function mergeMcpJson(filePath, withType = false) {
     const baseServers = {
         codegraph: { command: 'codegraph', args: ['serve', '--mcp'] },
         playwright: { command: npxCmd, args: ['-y', '@playwright/mcp'] },
-        context7: { command: npxCmd, args: ['-y', '@upstash/context7-mcp'] },
-        filesystem: { command: npxCmd, args: ['-y', '@modelcontextprotocol/server-filesystem', targetDir.replace(/\\/g, '/')] }
+        context7: { command: npxCmd, args: ['-y', '@upstash/context7-mcp'] }
     };
     if (data.permissions && Array.isArray(data.permissions.allow)) {
         const requiredPermissions = [
-            "mcp__filesystem__read_file",
-            "mcp__filesystem__read_multiple_files",
-            "mcp__filesystem__list_directory",
-            "mcp__filesystem__directory_tree",
-            "mcp__filesystem__search_files",
-            "mcp__filesystem__get_file_info",
-            "mcp__filesystem__write_file",
             "mcp__context7__resolve-library-id",
             "mcp__context7__query-docs"
         ];
@@ -1500,24 +1501,6 @@ function mergeMcpJson(filePath, withType = false) {
     for (const [name, server] of Object.entries(baseServers)) {
         if (!data.mcpServers[name]) {
             data.mcpServers[name] = withType ? { type: 'stdio', ...server } : server;
-        } else if (name === 'filesystem') {
-            const fsServer = data.mcpServers[name];
-            if (fsServer && Array.isArray(fsServer.args)) {
-                // If it points to non-existent AppData roaming file, fix it to use npx
-                const isLegacyNode = fsServer.command === 'node' && fsServer.args[0] && fsServer.args[0].includes('server-filesystem');
-                if (isLegacyNode) {
-                    fsServer.command = npxCmd;
-                    fsServer.args[0] = '-y';
-                    fsServer.args.splice(1, 0, '@modelcontextprotocol/server-filesystem');
-                }
-                const normalizedTarget = targetDir.replace(/\\/g, '/');
-                const hasTarget = fsServer.args.some(arg => {
-                    return typeof arg === 'string' && (arg.replace(/\\/g, '/').toLowerCase() === normalizedTarget.toLowerCase());
-                });
-                if (!hasTarget) {
-                    fsServer.args.push(normalizedTarget);
-                }
-            }
         }
     }
     writeJsonFile(filePath, data);
@@ -1529,7 +1512,6 @@ function appendMcpTomlIfMissing(filePath) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
     const blocks = [];
-    const normalizedTarget = targetDir.replace(/\\/g, '/');
     const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
     if (!/\[mcp_servers\.context7\]/.test(existing)) {
         blocks.push(`[mcp_servers.context7]
@@ -1537,14 +1519,6 @@ command = "${npxCmd}"
 args = ["-y", "@upstash/context7-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 120
-`);
-    }
-    if (!/\[mcp_servers\.filesystem\]/.test(existing)) {
-        blocks.push(`[mcp_servers.filesystem]
-command = "${npxCmd}"
-args = ["-y", "@modelcontextprotocol/server-filesystem", "${normalizedTarget}"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
 `);
     }
     if (!/\[mcp_servers\.codegraph\]/.test(existing)) {
@@ -1568,7 +1542,7 @@ tool_timeout_sec = 120
     }
     const separator = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
     fs.writeFileSync(filePath, existing + separator + blocks.join('\n'), 'utf8');
-    return { ok: true, message: `configured context7, filesystem, codegraph, playwright MCP in ${filePath}` };
+    return { ok: true, message: `configured context7, codegraph, playwright MCP in ${filePath}` };
 }
 
 function setupMcpServers() {
@@ -1696,9 +1670,9 @@ async function main() {
 
     const generatedFiles = [
         ['AGENTS.md', generateSharedAgentsMd(data)],
-        ['CLAUDE.md', generateSharedClaudeMd()],
+        ['CLAUDE.md', generateSharedClaudeMd(data)],
         ['GEMINI.md', generateSharedGeminiMd()],
-        ['.cursorrules', generateSharedCursorrules()],
+        ['.cursorrules', generateSharedCursorrules(data)],
         [path.join('.agent', 'docs', 'project.md'), generateProjectDoc(data)],
         [path.join('.agent', 'docs', 'architecture.md'), generateArchitectureDoc(data)],
         [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc(data)],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.22",
+    "version": "1.0.24",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/cli.js"