thachvd-kit 1.0.15 → 1.0.17

package/README.md

@@ -1,8 +1,8 @@
 # thachvd-kit
 
-`thachvd-kit` bootstraps project context for AI coding agents such as Antigravity, Claude Code, and Codex.
+`thachvd-kit` bootstraps shared project rules for AI coding agents.
 
-It installs a local `.agent/` kit, generates `PROJECT_CONTEXT.md`, and can scan an existing codebase to infer stack, framework, database, and infra signals before your agent starts working.
+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
 
@@ -12,101 +12,67 @@ Install globally:
 npm install -g thachvd-kit
 ```
 
-Then run inside any project folder:
+Run inside a project:
 
 ```bash
 thachvd-kit init
 ```
 
-You can also skip directly to scan mode:
+For existing projects, scan first:
 
 ```bash
 thachvd-kit init --scan
 ```
 
-## What `init` Does
+## What `init` Generates
 
-`thachvd-kit init` now supports both new and existing projects:
+- `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/agents`, `.agent/skills`, `.agent/workflows`, `.agent/rules`.
 
-- New project: enter context manually.
-- Existing project: choose scan mode or manual mode.
-- Scan mode: detect stack from the codebase, show evidence, then either accept detected values or review/edit them.
+## Why Docs Live Under `.agent/docs`
 
-Generated files:
+Root instruction files are loaded often, so they should stay short and stable. Project-specific details belong in `.agent/docs/`:
 
-- `.agent/agents`
-- `.agent/rules`
-- `.agent/skills`
-- `.agent/workflows`
-- `PROJECT_CONTEXT.md`
-- `CLAUDE.md`
-- `AGENTS.md`
-- `AI_CONTEXT_REFINEMENT.md` when first-session AI refinement is enabled
+- 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.
 
-## Scan Behavior
+`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.
 
-The scanner is hybrid and practical:
+## Platform Notes
 
-- App stack detection uses an inferred `app_root` so nested apps like `src/` can still resolve Laravel, CakePHP, Next.js, and similar stacks correctly.
-- Infra detection stays repo-wide, so folders like `dev/`, `stg/`, `prod/` can still contribute Docker and CI evidence.
-- Noise folders such as `vendor`, `node_modules`, `.git`, `dist`, and `build` are ignored during recursive scan.
-
-The scan preview surfaces:
-
-- app root
-- project type
-- primary language
-- frameworks
-- database
-- package manager
-- test framework
-- cloud
-- infrastructure
-- CI/CD
-- evidence for each inferred framework
-
-## AI Refinement Flow
-
-`init` creates a baseline `PROJECT_CONTEXT.md`.
-
-If you enable first-session AI refinement, the generated context is marked with:
-
-- `context.status: baseline`
-- `context.needs_ai_refinement: true`
-
-Then, when your agent opens the project, `GEMINI.md` / `CLAUDE.md` / `AGENTS.md` instruct it to:
-
-1. Read `PROJECT_CONTEXT.md`
-2. Refine the context once if `needs_ai_refinement` is `true`
-3. Update the file to `context.status: refined`
-4. Set `context.needs_ai_refinement: false`
-
-This keeps `init` simple while still allowing a deeper AI pass without requiring API-key integration inside the CLI.
-
-## Skill Resolution
-
-The kit auto-loads generic and framework-specific skills based on detected context.
-
-Examples:
-
-- React -> `react-frontend`, `frontend-design`
-- Next.js -> `nextjs-react-expert`, `frontend-design`
-- Laravel -> `laravel-patterns`, `laravel-security`, `laravel-tdd`
-- Tauri -> `rust-pro`, `desktop-design`
-
-Generic quality skills such as `clean-code` and `systematic-debugging` are always included.
+- 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/
+│   ├── architecture.md
+│   ├── conventions.md
+│   ├── project.md
+│   └── workflow.md
 ├── rules/
 ├── skills/
 └── workflows/
 ```
 
-## Notes
+## Development
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+```
 
-- `thachvd-kit` generates both `CLAUDE.md` for Claude Code and `AGENTS.md` for Codex/AGENTS-compatible editors.
-- The npm package page updates only after a new `npm publish`, not just after pushing to GitHub.
+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