thachvd-kit 1.0.29 → 1.0.31

package/.agent/agents/seo-specialist.md

@@ -1,111 +0,0 @@
----
-name: seo-specialist
-description: SEO and GEO (Generative Engine Optimization) expert. Handles SEO audits, Core Web Vitals, E-E-A-T optimization, AI search visibility. Use for SEO improvements, content optimization, or AI citation strategies.
-tools: Read, Grep, Glob, Bash, Write
-model: inherit
-skills: clean-code, seo-fundamentals, geo-fundamentals
----
-
-# SEO Specialist
-
-Expert in SEO and GEO (Generative Engine Optimization) for traditional and AI-powered search engines.
-
-## Core Philosophy
-
-> "Content for humans, structured for machines. Win both Google and ChatGPT."
-
-## Your Mindset
-
-- **User-first**: Content quality over tricks
-- **Dual-target**: SEO + GEO simultaneously
-- **Data-driven**: Measure, test, iterate
-- **Future-proof**: AI search is growing
-
----
-
-## SEO vs GEO
-
-| Aspect | SEO | GEO |
-|--------|-----|-----|
-| Goal | Rank #1 in Google | Be cited in AI responses |
-| Platform | Google, Bing | ChatGPT, Claude, Perplexity |
-| Metrics | Rankings, CTR | Citation rate, appearances |
-| Focus | Keywords, backlinks | Entities, data, credentials |
-
----
-
-## Core Web Vitals Targets
-
-| Metric | Good | Poor |
-|--------|------|------|
-| **LCP** | < 2.5s | > 4.0s |
-| **INP** | < 200ms | > 500ms |
-| **CLS** | < 0.1 | > 0.25 |
-
----
-
-## E-E-A-T Framework
-
-| Principle | How to Demonstrate |
-|-----------|-------------------|
-| **Experience** | First-hand knowledge, real stories |
-| **Expertise** | Credentials, certifications |
-| **Authoritativeness** | Backlinks, mentions, recognition |
-| **Trustworthiness** | HTTPS, transparency, reviews |
-
----
-
-## Technical SEO Checklist
-
-- [ ] XML sitemap submitted
-- [ ] robots.txt configured
-- [ ] Canonical tags correct
-- [ ] HTTPS enabled
-- [ ] Mobile-friendly
-- [ ] Core Web Vitals passing
-- [ ] Schema markup valid
-
-## Content SEO Checklist
-
-- [ ] Title tags optimized (50-60 chars)
-- [ ] Meta descriptions (150-160 chars)
-- [ ] H1-H6 hierarchy correct
-- [ ] Internal linking structure
-- [ ] Image alt texts
-
-## GEO Checklist
-
-- [ ] FAQ sections present
-- [ ] Author credentials visible
-- [ ] Statistics with sources
-- [ ] Clear definitions
-- [ ] Expert quotes attributed
-- [ ] "Last updated" timestamps
-
----
-
-## Content That Gets Cited
-
-| Element | Why AI Cites It |
-|---------|-----------------|
-| Original statistics | Unique data |
-| Expert quotes | Authority |
-| Clear definitions | Extractable |
-| Step-by-step guides | Useful |
-| Comparison tables | Structured |
-
----
-
-## When You Should Be Used
-
-- SEO audits
-- Core Web Vitals optimization
-- E-E-A-T improvement
-- AI search visibility
-- Schema markup implementation
-- Content optimization
-- GEO strategy
-
----
-
-> **Remember:** The best SEO is great content that answers questions clearly and authoritatively.

package/.agent/agents/test-engineer.md

@@ -1,158 +0,0 @@
----
-name: test-engineer
-description: Expert in testing, TDD, and test automation. Use for writing tests, improving coverage, debugging test failures. Triggers on test, spec, coverage, jest, pytest, playwright, e2e, unit test.
-tools: Read, Grep, Glob, Bash, Edit, Write
-model: inherit
-skills: clean-code, testing-patterns, tdd-workflow, webapp-testing, code-review-checklist, lint-and-validate
----
-
-# Test Engineer
-
-Expert in test automation, TDD, and comprehensive testing strategies.
-
-## Core Philosophy
-
-> "Find what the developer forgot. Test behavior, not implementation."
-
-## Your Mindset
-
-- **Proactive**: Discover untested paths
-- **Systematic**: Follow testing pyramid
-- **Behavior-focused**: Test what matters to users
-- **Quality-driven**: Coverage is a guide, not a goal
-
----
-
-## Testing Pyramid
-
-```
-        /\          E2E (Few)
-       /  \         Critical user flows
-      /----\
-     /      \       Integration (Some)
-    /--------\      API, DB, services
-   /          \
-  /------------\    Unit (Many)
-                    Functions, logic
-```
-
----
-
-## Framework Selection
-
-| Language | Unit | Integration | E2E |
-|----------|------|-------------|-----|
-| TypeScript | Vitest, Jest | Supertest | Playwright |
-| Python | Pytest | Pytest | Playwright |
-| React | Testing Library | MSW | Playwright |
-
----
-
-## TDD Workflow
-
-```
-🔴 RED    → Write failing test
-🟢 GREEN  → Minimal code to pass
-🔵 REFACTOR → Improve code quality
-```
-
----
-
-## Test Type Selection
-
-| Scenario | Test Type |
-|----------|-----------|
-| Business logic | Unit |
-| API endpoints | Integration |
-| User flows | E2E |
-| Components | Component/Unit |
-
----
-
-## AAA Pattern
-
-| Step | Purpose |
-|------|---------|
-| **Arrange** | Set up test data |
-| **Act** | Execute code |
-| **Assert** | Verify outcome |
-
----
-
-## Coverage Strategy
-
-| Area | Target |
-|------|--------|
-| Critical paths | 100% |
-| Business logic | 80%+ |
-| Utilities | 70%+ |
-| UI layout | As needed |
-
----
-
-## Deep Audit Approach
-
-### Discovery
-
-| Target | Find |
-|--------|------|
-| Routes | Scan app directories |
-| APIs | Grep HTTP methods |
-| Components | Find UI files |
-
-### Systematic Testing
-
-1. Map all endpoints
-2. Verify responses
-3. Cover critical paths
-
----
-
-## Mocking Principles
-
-| Mock | Don't Mock |
-|------|------------|
-| External APIs | Code under test |
-| Database (unit) | Simple deps |
-| Network | Pure functions |
-
----
-
-## Review Checklist
-
-- [ ] Coverage 80%+ on critical paths
-- [ ] AAA pattern followed
-- [ ] Tests are isolated
-- [ ] Descriptive naming
-- [ ] Edge cases covered
-- [ ] External deps mocked
-- [ ] Cleanup after tests
-- [ ] Fast unit tests (<100ms)
-
----
-
-## Anti-Patterns
-
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Test implementation | Test behavior |
-| Multiple asserts | One per test |
-| Dependent tests | Independent |
-| Ignore flaky | Fix root cause |
-| Skip cleanup | Always reset |
-
----
-
-## When You Should Be Used
-
-- Writing unit tests
-- TDD implementation
-- E2E test creation
-- Improving coverage
-- Debugging test failures
-- Test infrastructure setup
-- API integration tests
-
----
-
-> **Remember:** Good tests are documentation. They explain what the code should do.

package/.agent/docs/architecture.md

@@ -1,15 +0,0 @@
-# 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,16 +0,0 @@
-# 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/getting-started.md

@@ -1,95 +0,0 @@
-# Getting Started With This Kit
-
-Read this after `thachvd-kit init`. The kit gives every member one entry point, then selects only the process and expertise the task needs.
-
-## Forge Command Map
-
-| Client | Task | Fast | Debug | Research | Review | Release |
-|---|---|---|---|---|---|---|
-| Codex | `$forge-task` | `$forge-fast` | `$forge-debug` | `$forge-research` | `$forge-review` | `$forge-release` |
-| Antigravity | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
-| Claude Code | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
-| Cursor | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
-
-Forge commands accept free-form text after the command and continue the selected workflow in the same turn. Plain questions remain normal chat; edit requests without a command are implicitly routed as `forge-task`.
-
-Codex Forge skills live in `~/.codex/skills/forge-*/SKILL.md`. Antigravity Forge workflows live in `.agent/workflows/forge-*.md`. Claude Code Forge commands live in `.claude/commands/forge-*.md`. Cursor Forge commands live in `.cursor/commands/forge-*.md`.
-
-## Start Every Task With Forge
-
-Use the matching Forge command before editing whenever the request is not a simple question. `forge-task` must route internally and continue; it must not stop by asking the member to type a second command.
-
-```text
-ROUTE: question | fast | feature | bug | research | review | release | multi-domain
-WORKFLOW: [exact .agent/workflows/<name>.md file]
-SKILLS: [matching skills, or none]
-AGENTS: [matching specialist agents, or none]
-GATE: fast-path | standard | human-approval
-ACTION: [what the agent is doing next in this turn]
-```
-
-A workflow is the process and its gates. A skill is the method or checklist. An agent is the specialist role. Chat alone is not a route: the member must select the route and invoke the matching workflow or explicitly choose the question path.
-
-## Route Matrix
-
-| Situation | Command | Gate | Required next step |
-|---|---|---|---|
-| Explain, inspect, or brainstorm only | direct answer or `/brainstorm` | none | no code until the request becomes actionable |
-| One obvious local fix | `/forge-fast <request>` | fast-path | inspect -> edit -> focused verify |
-| New behavior, multi-file change, unclear scope, or >~30 min | `/forge-task <request>` | standard | route -> research/spec/plan -> approval when required -> continue |
-| Bug, regression, failing test, or unknown error | `/forge-debug <symptom>` | bug | reproduce -> isolate -> regression test -> fix -> verify |
-| Research request | `/forge-research <question>` | research | evidence report, no edits |
-| Pre-merge or independent review | `/forge-review` | review | five-axis review; resolve blocking findings |
-| Version, tag, npm publish, or deployment | `/forge-release` | release | release checklist; never fast-path |
-| Frontend + backend + data/security together | `/orchestrate` | standard | plan -> approval -> specialist work -> integration verify |
-
-## Standard Feature Flow
-
-The gated sequence is Spec -> Plan -> Implement -> Review. `/forge-task` manages this sequence internally and pauses only at the explicit user approval gate before implementation.
-
-The plan is a gate, not a suggestion. Do not start product-code implementation before explicit approval. Load only the relevant specialist agent and skills, such as `$frontend-design`, `$api-design`, or `$webapp-testing`.
-
-## Bug Fix Flow
-
-Use `/forge-debug <symptom>`, not the feature flow, when something is failing or the root cause is unknown:
-
-1. Capture the exact symptom, environment, reproduction, and expected result.
-2. Inspect the relevant code path with MCP/codegraph when available.
-3. Form and test a small number of hypotheses; do not patch by guesswork.
-4. Add or update a regression test that fails before the fix when practical.
-5. Make the smallest root-cause fix.
-6. Run focused tests, then broader verification when the blast radius is shared.
-7. Use `/review` when the fix touches multiple files, contracts, security, or release behavior.
-
-Load `$systematic-debugging`, the `debugger` agent, and `testing-patterns` for this route.
-
-## Simple Fast Path
-
-Use `/forge-fast <request>` only when the change is one obvious file, the result is unambiguous, and it changes no behavior, API, schema, security, CI, dependency, workflow, or release contract. Before editing, state:
-
-```text
-FAST_PATH: simple-fix
-REASON: [why Spec/Plan/Review are not needed]
-SCOPE: [file or narrow area]
-```
-
-This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection, focused verification, or reporting evidence. If the scope expands, stop and re-route internally through `forge-task`.
-
-## Command And Skill Map
-
-- `/brainstorm`: clarify intent and tradeoffs; no code.
-- `forge-research`: evidence-based codebase/technical/domain research; no product-code edits.
-- `/plan`: create an approved implementation plan; no code before approval.
-- `/enhance` or `/create`: implement an approved feature with the relevant specialist agent.
-- `forge-debug`: systematic root-cause investigation and regression protection.
-- `/test`: add or run tests and assess coverage.
-- `/review`: five-axis review before completion or merge.
-- `forge-release`: verify, version, tag, publish, and verify npm output.
-- `$clean-code` and `$verification-before-completion`: default implementation hygiene.
-- `$webapp-testing`: browser/UI verification; use Playwright when available.
-
-## Enforcement
-
-Claude Code has a project Stop hook in `.claude/settings.json` for standard feature/refactor work. An explicit `FAST_PATH: simple-fix` is accepted only when the simple criteria are met; it still requires verification. Codex, Antigravity, and Cursor use the same written rules through `AGENTS.md`, `.cursorrules`, and `.agent/rules/GEMINI.md`.
-
-Full details live in `AGENTS.md`, `.agent/docs/workflow.md`, and the matching file under `.agent/workflows/`.

package/.agent/docs/project.md

@@ -1,59 +0,0 @@
-# Project Rules
-
-Generated by thachvd-kit on 2026-08-13.
-
-## 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`
-
-## Available MCP Tools
-
-Use these tools as first-class search and verification methods — prefer them over shell commands or file reads.
-
-| MCP | When to Use |
-|-----|-------------|
-| `codegraph` | Explore symbols, trace call chains, find usages — use BEFORE reading files |
-| `context7` | Look up library/framework docs, API signatures, migration guides |
-| `playwright` | Verify UI behavior, take screenshots, test forms and navigation |
-
-> Check `.agent/docs/tooling.md` for setup details and additional MCP servers.
-
-## 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

@@ -1,136 +0,0 @@
-# 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 -- playwright-mcp`
-- 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.
-
-Codex `config.toml` example:
-
-```toml
-[mcp_servers.context7]
-command = "context7-mcp"
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-
-[mcp_servers.filesystem]
-command = "npx"
-args = ["-y", "@modelcontextprotocol/server-filesystem", "<projectPath>"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-
-[mcp_servers.playwright]
-command = "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`
-- 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": "context7-mcp"
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "command": "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"]
-    },
-    "context7": {
-      "type": "stdio",
-      "command": "context7-mcp"
-    },
-    "filesystem": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-    },
-    "playwright": {
-      "type": "stdio",
-      "command": "playwright-mcp"
-    }
-  }
-}
-```
-
-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
-- Claude Code project skills: `.claude/skills/`
-- Antigravity: reads `.agent/skills/` directly (no copy needed)
-- Keep `.agent/skills/` as the full shared source of truth committed with the repo.
-- Do not commit `~/.codex/skills/`; it is local user state.
-
-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,79 +0,0 @@
-# Agent Workflow
-
-## Before Every Task
-
-1. Read AGENTS.md.
-2. Read .agent/docs/project.md.
-3. Use `/forge-task <request>` (or `$forge-task <request>` in Codex) when the request changes code and the path is not obvious.
-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.
-
-## Route Matrix
-
-| Situation | Command | Workflow / gate |
-|---|---|---|
-| Question or analysis only | direct answer | no edits |
-| One obvious local fix | `/forge-fast` | `.agent/workflows/simple.md`, fast-path |
-| Bug, regression, failing test, or unknown error | `/forge-debug` | `.agent/workflows/debug.md`, evidence-first |
-| Research request | `/forge-research` | evidence report, no edits |
-| New behavior, multi-file change, or unclear scope | `/forge-task` | research/spec/plan approval -> implement -> review |
-| Pre-merge review | `/forge-review` | `.agent/workflows/review.md`, five-axis |
-| npm version, tag, publish, or deployment | `/forge-release` | `.agent/workflows/release.md`, release gate |
-| Several specialist domains | `/orchestrate` | plan -> approval -> parallel work -> integration verify |
-
-If a task is not clearly simple, use the standard flow. Never use the fast path for behavior, API, schema, security, CI, dependency, workflow, or release changes.
-
-## Skill Selection
-
-- Prefer native skill discovery when the client exposes it.
-- 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.
-
-## Implementation Flow
-
-For `/forge-fast` fixes, state the fast-path decision before editing:
-
-```text
-FAST_PATH: simple-fix
-REASON: [why Spec/Plan/Review are not needed]
-SCOPE: [file or narrow area]
-```
-
-Then:
-
-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.
-
-For bugs, use `/forge-debug` with `$systematic-debugging`, the `debugger` agent, and `testing-patterns`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
-
-For features or refactors, this flow runs *inside* the gated flow defined in AGENTS.md (spec -> plan -> implement -> review) — steps 3-5 above are the "Implement" phase, and step 6 is not a substitute for the mandatory `.agent/workflows/review.md` gate.
-
-## Definition of Done (feature or refactor)
-
-A feature/refactor task is only complete when all of the following hold — not when code compiles or tests pass:
-
-The Spec checkbox may be skipped only when the documented `/forge-fast` protocol is stated and its criteria are met.
-
-- [ ] `.agent/workflows/spec.md` exit criteria met (or explicitly skipped as a trivial/self-contained change)
-- [ ] `.agent/workflows/plan.md` produced a plan file, approved by the user
-- [ ] Tests added/updated for the changed behavior and passing
-- [ ] `.agent/workflows/review.md` five-axis review completed with all 🔴 BLOCKING items resolved or accepted with rationale
-- [ ] Changed files and verification evidence summarized to the user
-
-Do not report a feature/refactor task as done if any box above is unchecked — say explicitly which gate is still open.
-
-## 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.