thachvd-kit 1.0.13 → 1.0.15

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

@@ -0,0 +1,111 @@
+---
+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

@@ -0,0 +1,158 @@
+---
+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/rules/GEMINI.md

@@ -0,0 +1,207 @@
+---
+trigger: always_on
+---
+
+# GEMINI.md — Universal Agent Kit
+
+> Cross-platform agent protocol. Works with: Antigravity · Claude Code · Codex · OpenCode
+
+---
+
+## MANDATORY FIRST ACTION
+
+**At session start — before anything else:**
+
+```
+1. Read AGENTS.md (at project root) → load stack, agents, constraints
+2. If missing → ask user to run: thachvd-kit init --scan
+3. Confirm: "Context loaded: [Project Name] | Stack: [Stack] | Ready."
+```
+
+> All routing decisions below depend on AGENTS.md.
+> Without it, ask user to run: `thachvd-kit init --scan`
+
+---
+
+## STEP 1 — CLASSIFY REQUEST
+
+| Type | Triggers | Action |
+|------|----------|--------|
+| **QUESTION** | "what", "how", "explain", "why" | Direct answer |
+| **SURVEY** | "analyze", "list", "overview", "check" | Analysis only, no code |
+| **SIMPLE FIX** | "fix", "add", "change" (single file) | Inline edit |
+| **BUILD** | "build", "create", "implement", "refactor" | Agent + `{task-slug}.md` |
+| **DESIGN/UI** | "design", "UI", "page", "dashboard" | Agent + `{task-slug}.md` |
+
+---
+
+## STEP 2 — AUTO-SELECT AGENT
+
+**Protocol:**
+1. Read `## Project Overview` from AGENTS.md → detect language and frameworks
+2. Match to agent table below
+3. Announce before responding:
+
+```
+🤖 Applying knowledge of `@[agent-name]`...
+```
+
+### Agent Routing Table
+
+| Domain | Agent | Skills to Load |
+|--------|-------|---------------|
+| Web frontend (any framework) | `frontend-specialist` | `frontend-design` + framework skill from AGENTS.md |
+| Backend API (any language) | `backend-specialist` | language skill + `api-design` |
+| Database / Schema | `database-architect` | `database-design` |
+| Mobile / Desktop (Tauri, RN, Flutter) | `mobile-developer` | platform skill from AGENTS.md |
+| DevOps / Cloud / CI | `devops-engineer` | `docker-patterns`, `deployment-procedures` |
+| Security audit | `security-auditor` | `vulnerability-scanner` |
+| Debug / RCA | `debugger` | `systematic-debugging` |
+| Planning / Discovery | `project-planner` | `brainstorming`, `plan-writing` |
+| Multi-domain | `orchestrator` | `dispatching-parallel-agents` |
+
+**Framework-specific skill mapping** (reference AGENTS.md stack):
+
+| Framework/Language | Load Skill |
+|-------------------|-----------|
+| Vue | `frontend-design` (+ Vue-specific if available) |
+| React | `react-frontend` |
+| Next.js | `nextjs-react-expert` |
+| Laravel | `laravel-patterns` + `laravel-security` |
+| Node.js | `nodejs-best-practices` |
+| Python | `python-patterns` |
+| Go | `golang-patterns` |
+| Rust | `rust-pro` |
+| Tauri | `desktop-design` + `rust-pro` |
+| Docker | `docker-patterns` |
+
+> If stack not in mapping → use agent's general skill set + `clean-code`.
+
+**MANDATORY checklist before any code:**
+- [ ] Agent identified from AGENTS.md stack?
+- [ ] Agent `.md` file read/recalled?
+- [ ] Announcement `🤖 Applying knowledge of @[agent]...` written?
+
+> 🔴 Code without announcement = **PROTOCOL VIOLATION**
+
+---
+
+## STEP 3 — SOCRATIC GATE
+
+**Trigger: BUILD or DESIGN/UI requests only**
+
+| Scenario | Action |
+|----------|--------|
+| New feature / greenfield | Ask **3 questions**: Purpose · Users · Must-have vs Nice-to-have |
+| Code edit / bug fix | Confirm scope + 1 impact question |
+| Vague request | Ask Purpose + Constraints |
+| User gave full spec | **Proceed immediately** |
+| User says "proceed" / "just do it" | **DO IT — no more questions** |
+
+**Rules:**
+- Max 3 questions at once
+- Never ask edge case questions after user already answered
+- Reference `@[skills/brainstorming]` for question format
+
+---
+
+## UNIVERSAL RULES (Always Active)
+
+### Language
+- Respond in user's language (auto-detect from prompt)
+- Code comments/variables always in English
+
+### Code Quality
+- `@[skills/clean-code]` applies to ALL code, ALL languages
+- Tests mandatory: Unit > Integration > E2E
+- `@[skills/verification-before-completion]` before claiming "done"
+
+### File Changes
+- Identify dependent files before modifying
+- Update ALL affected files together
+
+---
+
+## EXECUTION WORKFLOW
+
+**BUILD tasks — 7-step flow:**
+
+```
+1. brainstorming           → Clarify (Socratic Gate)
+2. plan-writing            → Create {task-slug}.md
+3. using-git-worktrees     → Isolated workspace
+4. subagent-driven-development → Implement + 2-stage review
+5. requesting-code-review  → After each major task
+6. verification-before-completion → Before claiming done
+7. finishing-a-development-branch → Merge / PR / keep
+```
+
+**SIMPLE FIX:** Skip to step 4, no worktree needed.
+
+---
+
+## MODE BEHAVIOR
+
+| Mode | Behavior |
+|------|----------|
+| **plan** | Analysis → Planning → Architecture → NO CODE until confirmed |
+| **ask** | Questions and analysis only |
+| **edit** | Execute. Multi-file → create `{task-slug}.md`. Single-file → proceed. |
+
+---
+
+## FINAL CHECK
+
+**Trigger:** "final check", "deploy check", "kiểm tra cuối", "done?"
+
+```bash
+python scripts/checklist.py .
+```
+
+Priority: Security → Lint → Tests → UX → SEO
+
+---
+
+## PATHS
+
+```
+agents/     → agents/{agent}.md
+skills/     → skills/{skill}/SKILL.md
+workflows/  → workflows/{command}.md
+scripts/    → scripts/init.py, checklist.py, verify_all.py
+```
+
+---
+
+## QUICK SKILL REFERENCE
+
+| Need | Skill |
+|------|-------|
+| Clean code (any lang) | `clean-code` |
+| Plan a task | `plan-writing` → `executing-plans` |
+| Parallel agents | `dispatching-parallel-agents` |
+| Code review | `requesting-code-review` / `receiving-code-review` |
+| Git isolation | `using-git-worktrees` |
+| Agent-based dev | `subagent-driven-development` |
+| Verify done | `verification-before-completion` |
+| Finish branch | `finishing-a-development-branch` |
+| Write new skill | `writing-skills` |
+| API design | `api-design` |
+| Docker | `docker-patterns` |
+| Laravel | `laravel-patterns`, `laravel-security`, `laravel-tdd` |
+| Go | `golang-patterns`, `golang-testing` |
+| Debugging | `systematic-debugging` |
+| Security | `vulnerability-scanner` |
+
+---
+
+## CROSS-PLATFORM NOTES
+
+| Platform | Rules File | Skills Dir | Workflows |
+|----------|-----------|-----------|-----------| 
+| **Antigravity** | `rules/GEMINI.md` (this file) | `skills/` | `workflows/` |
+| **Claude Code** | `CLAUDE.md` at project root | `.agent/skills/` | `.agent/workflows/` |
+| **Codex / OpenCode** | `AGENTS.md` at project root | `.agent/skills/` | `.agent/workflows/` |
+| **Cursor** | `.cursorrules` or `.agent/rules/GEMINI.md` | `.agent/skills/` | `.agent/workflows/` |
+
+> Run `thachvd-kit init --scan` to generate AGENTS.md and copy the `.agent/` folder automatically.

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

@@ -0,0 +1,156 @@
+---
+name: api-design
+description: REST API design patterns. Use when designing new API endpoints, reviewing API contracts, choosing pagination strategies, error response formats, versioning, or HTTP status codes.
+allowed-tools: Read, Edit, Write
+---
+
+# API Design Patterns
+
+## URL Structure
+
+```
+# Resources: plural nouns, lowercase, kebab-case, no verbs
+GET    /api/v1/users
+POST   /api/v1/users
+GET    /api/v1/users/:id
+PUT    /api/v1/users/:id
+PATCH  /api/v1/users/:id
+DELETE /api/v1/users/:id
+
+# Sub-resources for relationships
+GET    /api/v1/users/:id/orders
+POST   /api/v1/users/:id/orders
+
+# Actions that don't map to CRUD
+POST   /api/v1/orders/:id/cancel
+POST   /api/v1/auth/refresh
+```
+
+**Naming rules:**
+```
+✅ /api/v1/team-members          kebab-case
+✅ /api/v1/orders?status=active  query params for filtering
+✅ /api/v1/users/123/orders      nested for ownership
+
+❌ /api/v1/getUsers              verb in URL
+❌ /api/v1/user                  singular
+❌ /api/v1/team_members          snake_case in URLs
+```
+
+## HTTP Methods and Status Codes
+
+| Method | Idempotent | Use For |
+|--------|-----------|---------|
+| GET | Yes | Retrieve |
+| POST | No | Create / trigger actions |
+| PUT | Yes | Full replacement |
+| PATCH | No | Partial update |
+| DELETE | Yes | Remove |
+
+```
+# Success
+200 OK                    GET, PUT, PATCH (with body)
+201 Created               POST (add Location header)
+204 No Content            DELETE, PUT (no body)
+
+# Client Errors
+400 Bad Request           Validation failure, malformed JSON
+401 Unauthorized          Missing or invalid auth
+403 Forbidden             Authenticated, not authorized
+404 Not Found             Resource doesn't exist
+409 Conflict              Duplicate entry, state conflict
+422 Unprocessable Entity  Valid JSON, semantically invalid
+429 Too Many Requests     Rate limit exceeded
+
+# Server Errors
+500 Internal Server Error Never expose internal details
+503 Service Unavailable   Include Retry-After header
+```
+
+## Response Format
+
+```json
+// Success
+{ "data": { "id": "abc-123", "email": "alice@example.com", "created_at": "2025-01-15T10:30:00Z" } }
+
+// Collection with pagination
+{
+  "data": [{ "id": "abc-123", "name": "Alice" }],
+  "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 },
+  "links": { "next": "/api/v1/users?page=2&per_page=20" }
+}
+
+// Error
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Must be a valid email", "code": "invalid_format" }
+    ]
+  }
+}
+```
+
+## Pagination
+
+| Use Case | Type |
+|----------|------|
+| Admin dashboards, small datasets (<10K) | Offset |
+| Infinite scroll, feeds, large datasets | **Cursor** |
+| Public APIs | Cursor (default) |
+| Search results | Offset (users expect page numbers) |
+
+```
+# Offset
+GET /api/v1/users?page=2&per_page=20
+
+# Cursor
+GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
+→ { "data": [...], "meta": { "has_next": true, "next_cursor": "eyJpZCI6MTQzfQ" } }
+```
+
+## Versioning
+
+```
+/api/v1/users     ← recommended
+/api/v2/users     ← when breaking changes needed
+```
+
+**Breaking changes** (require new version): removing fields, changing types, changing URL structure.
+**Non-breaking** (no new version): adding optional fields/params, adding endpoints.
+
+Deprecation: 6-month notice, add `Sunset` header, return `410 Gone` after.
+
+## Filtering, Sorting, Search
+
+```
+GET /api/v1/orders?status=active&created_after=2025-01-01
+GET /api/v1/users?sort=created_at&order=desc
+GET /api/v1/products?q=widget
+GET /api/v1/users?fields=id,email,name      # Sparse fieldsets
+```
+
+## Rate Limiting Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 45
+X-RateLimit-Reset: 1640995200
+Retry-After: 30    # on 429
+```
+
+## API Design Checklist
+
+Before shipping a new endpoint:
+
+- [ ] URL: plural noun, kebab-case, no verbs
+- [ ] Correct HTTP method and status code
+- [ ] Input validated with schema (Zod, Pydantic, Go validator)
+- [ ] Error response follows standard format with field-level details
+- [ ] Pagination implemented for list endpoints
+- [ ] Authentication required (or explicitly marked public)
+- [ ] Authorization checked (user can only access their own resources)
+- [ ] Rate limiting configured
+- [ ] Response does not leak internal details (stack traces, SQL errors)
+- [ ] OpenAPI spec updated

package/.agent/skills/api-patterns/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: api-patterns
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# API Patterns
+
+> API design principles and decision-making for 2025.
+> **Learn to THINK, not copy fixed patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
+| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
+| `response.md` | Envelope pattern, error format, pagination | Response structure |
+| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
+| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
+| `versioning.md` | URI/Header/Query versioning | API evolution planning |
+| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
+| `rate-limiting.md` | Token bucket, sliding window | API protection |
+| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
+| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+|------|-------|
+| API implementation | `@[skills/backend-development]` |
+| Data structure | `@[skills/database-design]` |
+| Security details | `@[skills/security-hardening]` |
+
+---
+
+## ✅ Decision Checklist
+
+Before designing an API:
+
+- [ ] **Asked user about API consumers?**
+- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
+- [ ] **Defined consistent response format?**
+- [ ] **Planned versioning strategy?**
+- [ ] **Considered authentication needs?**
+- [ ] **Planned rate limiting?**
+- [ ] **Documentation approach defined?**
+
+---
+
+## ❌ Anti-Patterns
+
+**DON'T:**
+- Default to REST for everything
+- Use verbs in REST endpoints (/getUsers)
+- Return inconsistent response formats
+- Expose internal errors to clients
+- Skip rate limiting
+
+**DO:**
+- Choose API style based on context
+- Ask about client requirements
+- Document thoroughly
+- Use appropriate status codes
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+