thachvd-kit 1.0.0

package/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/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/bin/cli.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const prompts = require('prompts');
+const pc = require('picocolors');
+
+const sourceDir = path.resolve(__dirname, '..');
+const targetDir = process.cwd();
+
+// --- Skill Resolver ---
+
+const LANG_SKILLS = {
+    javascript: ["nodejs-best-practices", "api-design"],
+    typescript: ["nodejs-best-practices", "api-design"],
+    python: ["python-patterns"],
+    go: ["golang-patterns", "golang-testing"],
+    php: ["laravel-patterns", "laravel-security", "laravel-tdd"],
+    rust: ["rust-pro"],
+    java: ["api-design"],
+    swift: ["mobile-design"],
+    kotlin: ["mobile-design"],
+    csharp: ["api-design"],
+};
+
+const FRAMEWORK_SKILLS = {
+    vue: ["frontend-design", "tailwind-patterns"],
+    react: ["nextjs-react-expert", "frontend-design"],
+    next: ["nextjs-react-expert", "frontend-design"],
+    nuxt: ["frontend-design"],
+    svelte: ["frontend-design"],
+    laravel: ["laravel-patterns", "laravel-security", "laravel-tdd"],
+    express: ["nodejs-best-practices", "api-design"],
+    fastapi: ["python-patterns", "api-design"],
+    django: ["python-patterns", "api-design"],
+    gin: ["golang-patterns", "golang-testing"],
+    fiber: ["golang-patterns", "golang-testing"],
+    nestjs: ["nodejs-best-practices", "api-design"],
+    tauri: ["rust-pro", "mobile-design"],
+    flutter: ["mobile-design"],
+    "react-native": ["mobile-design"],
+};
+
+const INFRA_SKILLS = {
+    docker: ["docker-patterns"],
+    aws: ["deployment-procedures", "docker-patterns"],
+    gcp: ["deployment-procedures", "docker-patterns"],
+    azure: ["deployment-procedures", "docker-patterns"],
+    vercel: ["deployment-procedures"],
+};
+
+function resolveSkills(data) {
+    const skills = new Set();
+    const lang = (data.primary_language || "").toLowerCase();
+
+    if (LANG_SKILLS[lang]) {
+        LANG_SKILLS[lang].forEach(s => skills.add(s));
+    }
+
+    (data.frameworks || []).forEach(fw => {
+        const fwLower = fw.toLowerCase();
+        for (const [key, vals] of Object.entries(FRAMEWORK_SKILLS)) {
+            if (fwLower.includes(key)) vals.forEach(s => skills.add(s));
+        }
+    });
+
+    (data.infrastructure || []).forEach(infra => {
+        const infraLower = infra.toLowerCase();
+        for (const [key, vals] of Object.entries(INFRA_SKILLS)) {
+            if (infraLower.includes(key)) vals.forEach(s => skills.add(s));
+        }
+    });
+
+    skills.add("clean-code");
+    skills.add("systematic-debugging");
+
+    return Array.from(skills).sort();
+}
+
+function resolveAgentTable(data) {
+    const rows = [];
+    const frameworks = (data.frameworks || []).map(f => f.toLowerCase());
+    const lang = (data.primary_language || "").toLowerCase();
+
+    // Frontend
+    const frontendFws = frameworks.filter(f => ["vue", "react", "next", "nuxt", "svelte", "angular"].includes(f));
+    if (frontendFws.length > 0) {
+        let feSkills = [];
+        frontendFws.forEach(fw => {
+            feSkills.push(...(FRAMEWORK_SKILLS[fw] || []));
+        });
+        rows.push(["Frontend UI", "frontend-specialist", Array.from(new Set(feSkills)).slice(0, 3).join(", ")]);
+    }
+
+    // Backend
+    let beSkills = [...(LANG_SKILLS[lang] || ["api-design"])];
+    const backendFws = frameworks.filter(f => ["laravel", "express", "fastapi", "django", "gin", "fiber", "nestjs"].includes(f));
+    backendFws.forEach(fw => {
+        beSkills.push(...(FRAMEWORK_SKILLS[fw] || []));
+    });
+    rows.push(["Backend API", "backend-specialist", Array.from(new Set(beSkills)).slice(0, 3).join(", ")]);
+
+    // Mobile/Desktop
+    const mobileFws = frameworks.filter(f => ["tauri", "flutter", "react-native"].includes(f));
+    if (mobileFws.length > 0) {
+        let mobileSkills = [];
+        mobileFws.forEach(fw => {
+            mobileSkills.push(...(FRAMEWORK_SKILLS[fw] || []));
+        });
+        rows.push(["Mobile/Desktop", "mobile-developer", Array.from(new Set(mobileSkills)).slice(0, 3).join(", ")]);
+    }
+
+    // DevOps
+    if (data.uses_docker || data.cloud !== "none") {
+        rows.push(["DevOps/Infra", "devops-engineer", "docker-patterns, deployment-procedures"]);
+    }
+
+    rows.push(["Debug", "debugger", "systematic-debugging"]);
+    rows.push(["Security", "security-auditor", "vulnerability-scanner"]);
+    rows.push(["Planning", "project-planner", "brainstorming, plan-writing"]);
+
+    return rows;
+}
+
+// --- File Generators ---
+
+function generateProjectContext(data) {
+    const agentTable = resolveAgentTable(data);
+    const autoSkills = resolveSkills(data);
+
+    const agentRows = agentTable.map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
+    const autoSkillsList = autoSkills.map(s => `- ${s}`).join('\n');
+
+    return `# PROJECT_CONTEXT.md
+# Generated by thachvd-kit init wizard on ${new Date().toISOString().split('T')[0]}
+# Edit freely — this is your project's brain.
+
+## Project
+
+- **Name:** ${data.project_name}
+- **Description:** ${data.description}
+- **Type:** ${data.project_type}
+
+---
+
+## Stack
+
+\`\`\`yaml
+stack:
+  primary_language: ${data.primary_language}
+  frameworks: [${(data.frameworks || []).join(', ')}]
+  database: ${data.database || 'none'}
+  infrastructure: [${(data.infrastructure || []).join(', ')}]
+  package_manager: ${data.package_manager || 'auto-detect'}
+  test_framework: ${data.test_framework || 'auto-detect'}
+\`\`\`
+
+---
+
+## Agent Routing
+
+| Task Type | Agent | Primary Skills |
+|-----------|-------|----------------|
+${agentRows}
+
+---
+
+## Auto-Resolved Skills
+
+Based on your stack, these skills will be loaded automatically:
+
+\`\`\`text
+${autoSkillsList}
+\`\`\`
+
+---
+
+## Project Conventions
+
+- **Max file size:** ${data.max_file_lines || '300'} lines (then modularize)
+- **Code style:** ${data.code_style || 'project-standard'}
+
+---
+
+## Architecture Notes
+
+<!-- Add architecture notes, key decisions, patterns used -->
+
+---
+
+## Current Phase
+
+- **Done:** —
+- **In Progress:** Initial setup
+- **Next:** —
+
+---
+
+## Known Issues / Tasks
+
+<!-- Add known issues or pending tasks -->
+`;
+}
+
+function generateClaudeMd(data) {
+    return `# CLAUDE.md — ${data.project_name}
+# Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
+# Cross-platform: Claude Code · Codex · OpenCode
+
+## Project
+${data.description}
+Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ')}
+
+## Rules
+- Read PROJECT_CONTEXT.md first for stack details and agent routing.
+- Follow skills in .agent/skills/ (or .claude/skills/).
+- Tests are mandatory. Verify before claiming done.
+- Max ${data.max_file_lines || '300'} lines per file.
+
+## Key Skills
+- Plan: \`plan-writing\` → \`executing-plans\`
+- Review: \`requesting-code-review\` / \`receiving-code-review\`
+- Quality: \`clean-code\`, \`verification-before-completion\`
+- Workflow: \`subagent-driven-development\`, \`finishing-a-development-branch\`
+
+## Commands
+- \`/plan\` — Create implementation plan
+- \`/debug\` — Systematic debugging
+- \`/test\` — Run test suite
+- \`/deploy\` — Deploy checklist
+
+See PROJECT_CONTEXT.md for full agent routing table.
+`;
+}
+
+// --- Main CLI ---
+
+async function main() {
+    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+    console.log('  ' + pc.bold('thachvd-kit') + ' — Project Init Wizard');
+    console.log('  Generates .agent/ folder & smart PROJECT_CONTEXT.md');
+    console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')) + '\n');
+
+    if (fs.existsSync(path.join(targetDir, 'PROJECT_CONTEXT.md'))) {
+        const res = await prompts({
+            type: 'confirm',
+            name: 'overwrite',
+            message: 'PROJECT_CONTEXT.md already exists in this folder. Overwrite?',
+            initial: false
+        });
+        if (!res.overwrite) {
+            console.log(pc.yellow('\nAborted. Existing project context unchanged.'));
+            process.exit(0);
+        }
+    }
+
+    const { project_name, description, project_type } = await prompts([
+        { type: 'text', name: 'project_name', message: 'Project name:', initial: path.basename(targetDir) },
+        { type: 'text', name: 'description', message: 'Short description:', initial: 'A software project' },
+        {
+            type: 'select', name: 'project_type', message: 'Project type:',
+            choices: [
+                { title: 'Web App', value: 'web-app' },
+                { title: 'API', value: 'api' },
+                { title: 'Mobile', value: 'mobile' },
+                { title: 'Desktop', value: 'desktop' },
+                { title: 'CLI', value: 'cli' },
+                { title: 'Fullstack', value: 'fullstack' },
+            ]
+        }
+    ]);
+
+    const { primary_language } = await prompts({
+        type: 'select',
+        name: 'primary_language',
+        message: 'Primary language:',
+        choices: ['typescript', 'javascript', 'python', 'go', 'php', 'rust', 'java', 'swift', 'kotlin', 'csharp', 'cpp'].map(l => ({ title: l, value: l }))
+    });
+
+    const { frameworks } = await prompts({
+        type: 'multiselect',
+        name: 'frameworks',
+        message: 'Frameworks (Space to select, Enter to confirm):',
+        choices: [
+            'vue', 'react', 'next', 'nuxt', 'svelte', 'angular',
+            'laravel', 'express', 'fastapi', 'django', 'gin', 'fiber', 'nestjs',
+            'tauri', 'flutter', 'react-native'
+        ].map(f => ({ title: f, value: f })),
+        min: 0
+    });
+
+    const dbAndInfra = await prompts([
+        {
+            type: 'select', name: 'database', message: 'Database / ORM:',
+            choices: ['postgres', 'mysql', 'sqlite', 'mongodb', 'redis', 'dynamodb', 'none'].map(d => ({ title: d, value: d }))
+        },
+        { type: 'confirm', name: 'uses_docker', message: 'Uses Docker / Docker Compose?', initial: true },
+        {
+            type: 'select', name: 'cloud', message: 'Cloud Provider:',
+            choices: ['aws', 'gcp', 'azure', 'vercel', 'fly', 'railway', 'none'].map(c => ({ title: c, value: c }))
+        }
+    ]);
+
+    const { package_manager, test_framework, max_file_lines } = await prompts([
+        {
+            type: 'select', name: 'package_manager', message: 'Package Manager:',
+            choices: ['npm', 'pnpm', 'yarn', 'bun', 'pip', 'uv', 'go mod', 'cargo', 'composer', 'auto-detect'].map(p => ({ title: p, value: p }))
+        },
+        { type: 'text', name: 'test_framework', message: 'Test Framework (jest, phpunit, etc):', initial: 'auto-detect' },
+        { type: 'text', name: 'max_file_lines', message: 'Max lines per file:', initial: '300' }
+    ]);
+
+    // Combine data
+    const data = {
+        project_name, description, project_type, primary_language, frameworks,
+        ...dbAndInfra, package_manager, test_framework, max_file_lines
+    };
+
+    data.infrastructure = [];
+    if (data.uses_docker) data.infrastructure.push('docker');
+    if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
+
+    // --- Copy .agent folder ---
+    const agentDir = path.join(targetDir, '.agent');
+    console.log(`\n${pc.bold(pc.cyan('━━ Generating Files ━━'))}`);
+
+    if (!fs.existsSync(agentDir)) {
+        fs.mkdirSync(agentDir, { recursive: true });
+    }
+
+    // Copy folders: agents, rules, skills, workflows
+    const foldersToCopy = ['agents', 'rules', 'skills', 'workflows'];
+    for (const folder of foldersToCopy) {
+        const srcPath = path.join(sourceDir, folder);
+        const destPath = path.join(agentDir, folder);
+        if (fs.existsSync(srcPath)) {
+            // Use basic recursive copy since Node 16.7 fs.cpSync handles this
+            fs.cpSync(srcPath, destPath, { recursive: true, force: true });
+            console.log(`  ${pc.green('✓')} Copied ${pc.bold(`.agent/${folder}`)}`);
+        } else {
+            console.log(`  ${pc.yellow('-')} Source ${folder} not found.`);
+        }
+    }
+
+    // Write contexts
+    fs.writeFileSync(path.join(targetDir, 'PROJECT_CONTEXT.md'), generateProjectContext(data), 'utf8');
+    console.log(`  ${pc.green('✓')} Generated ${pc.bold('PROJECT_CONTEXT.md')}`);
+
+    fs.writeFileSync(path.join(targetDir, 'CLAUDE.md'), generateClaudeMd(data), 'utf8');
+    console.log(`  ${pc.green('✓')} Generated ${pc.bold('CLAUDE.md')}`);
+
+    // Summary
+    const autoSkills = resolveSkills(data);
+    console.log(`\n${pc.bold(pc.green('━━ Done! ━━'))}
+  
+  ${pc.bold('Project:')} ${data.project_name}
+  ${pc.bold('Stack:')}   ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
+  ${pc.bold('Infra:')}   ${(data.infrastructure || []).join(', ') || 'none'}
+  
+  ${pc.bold('Auto-resolved skills:')}
+${autoSkills.map(s => '    · ' + s).join('\n')}
+
+  ${pc.bold('Next steps:')}
+    1. Your kit is installed in ${pc.bold('./.agent')}
+    2. Review ${pc.bold('PROJECT_CONTEXT.md')} and add architecture notes
+    3. Open project in Antigravity or Claude Code — the agent will read context on start!
+`);
+}
+
+main().catch(err => {
+    console.error(pc.red('\nError during init:'), err);
+    process.exit(1);
+});

package/kit/PROJECT_CONTEXT.template.md

@@ -0,0 +1,35 @@
+# 🗺️ PROJECT CONTEXT - [Project Name]
+
+> Initialize this file at the start of a project to provide the Agent with a Ground Truth.
+
+---
+
+## 🎯 Project Objectives
+- Brief description of what the app does and the problem it solves.
+
+## 🛠️ Technology Stack
+- **Frontend/UI:** [e.g., React, Vue, Flutter]
+- **Backend/Core:** [e.g., Rust, Node.js, Python]
+- **State Management:** [e.g., Zustand, Redux, Signals]
+- **Styling:** [e.g., Tailwind CSS, Vanilla CSS]
+
+## 📂 Project Structure
+- `src/[store|state]/`: State management modules.
+- `src/[services|logic]/`: Heavy business logic and I/O.
+- `src/lib/`: Reusable utility functions.
+- [Additional critical directories...]
+
+## 📜 Rules & Constraints
+- **Granularity:** [e.g., Max 250 lines/file] (Mandatory file splitting).
+- **Architecture:** Decouple UI from business logic.
+- **Safety:** [e.g., Use specific patterns for terminal commands or secrets].
+- [Project-specific golden rules...]
+
+## 🚧 Current Status
+- **Current Objective:** [e.g., Implementing Auth flow].
+- **Known Issues:** [e.g., API latency on high load].
+- **Next Milestones:** [e.g., Deployment to staging].
+
+---
+
+**Note:** This file is the "Ground Truth". The Agent IS ALLOWED and MANDATED to update this file after every significant task.