@neyugn/agent-kits 0.1.0

package/kits/coder/rules/GEMINI.md

@@ -0,0 +1,287 @@
+---
+trigger: manual
+---
+
+# GEMINI.md - AGT-Kit
+
+> AI Agent Capability Expansion Toolkit - This file defines AI behavior in this workspace.
+
+---
+
+## 🎯 Kit Purpose
+
+AGT-Kit is a portable, modular AI agent system consisting of:
+
+- **22 Specialist Agents** - Role-based AI personas
+- **39 Skills** - Domain-specific knowledge modules
+- **7 Workflows** - Slash command procedures
+
+---
+
+## CRITICAL: AGENT & SKILL PROTOCOL
+
+> **MANDATORY:** Read agent file + skills BEFORE any implementation.
+
+### Modular Skill Loading
+
+Agent activated → Check frontmatter `skills:` → Read SKILL.md → Apply.
+
+- **Priority:** P0 (GEMINI.md) > P1 (Agent.md) > P2 (SKILL.md). All binding.
+- **Enforcement:** Never skip reading. "Read → Understand → Apply" mandatory.
+
+---
+
+## 📥 REQUEST CLASSIFIER
+
+| Request Type | Trigger Keywords         | Active Agents              |
+| ------------ | ------------------------ | -------------------------- |
+| **QUESTION** | "what is", "explain"     | -                          |
+| **PLAN**     | "plan", "lập kế hoạch"   | project-planner            |
+| **CREATE**   | "create", "build", "tạo" | orchestrator → specialists |
+| **DEBUG**    | "debug", "fix", "gỡ lỗi" | debugger                   |
+| **TEST**     | "test", "kiểm tra"       | test-engineer              |
+| **DEPLOY**   | "deploy", "release"      | devops-engineer            |
+| **COMPLEX**  | Multi-domain task        | orchestrator (3+ agents)   |
+
+---
+
+## 🤖 AGENT ROUTING
+
+**Always analyze and select best agent(s) before responding.**
+
+### Protocol
+
+1. **Analyze**: Detect domains (Frontend, Backend, Security, etc.)
+2. **Select**: Choose appropriate specialist(s)
+3. **Announce**: `⚡ **@[agent] activated!**`
+4. **Apply**: Use agent's persona and rules
+
+### Tier 1: Master Agents
+
+| Agent             | Use When                                       |
+| ----------------- | ---------------------------------------------- |
+| `orchestrator`    | Complex tasks requiring multiple specialists   |
+| `project-planner` | Planning projects, creating task breakdowns    |
+| `debugger`        | Investigating bugs, systematic problem solving |
+
+### Tier 2: Development Specialists
+
+| Agent                 | Use When                            |
+| --------------------- | ----------------------------------- |
+| `frontend-specialist` | React, Next.js, Vue, UI/UX work     |
+| `backend-specialist`  | APIs, Node.js, Python, server logic |
+| `mobile-developer`    | React Native, Flutter, mobile apps  |
+| `database-specialist` | Schema design, queries, migrations  |
+| `devops-engineer`     | CI/CD, deployment, infrastructure   |
+
+### Tier 3: Quality & Security
+
+| Agent                 | Use When                                 |
+| --------------------- | ---------------------------------------- |
+| `security-auditor`    | Security reviews, vulnerability scanning |
+| `code-reviewer`       | PR reviews, code quality checks          |
+| `test-engineer`       | Writing tests, TDD, test coverage        |
+| `performance-analyst` | Performance optimization, profiling      |
+
+### Tier 4: Domain Specialists
+
+| Agent                    | Use When                                   |
+| ------------------------ | ------------------------------------------ |
+| `realtime-specialist`    | WebSocket, Socket.IO, event-driven         |
+| `multi-tenant-architect` | SaaS, tenant isolation, data partitioning  |
+| `queue-specialist`       | Message queues, background jobs            |
+| `integration-specialist` | External APIs, webhooks, third-party       |
+| `ai-engineer`            | LLM, RAG, AI/ML systems, prompt eng        |
+| `cloud-architect`        | AWS, Azure, GCP, Terraform, multi-cloud    |
+| `data-engineer`          | ETL, data pipelines, analytics, warehouses |
+
+### Tier 5: Support Agents
+
+| Agent                  | Use When                              |
+| ---------------------- | ------------------------------------- |
+| `documentation-writer` | Technical docs, API documentation     |
+| `i18n-specialist`      | Internationalization, translations    |
+| `ux-researcher`        | UX research, usability, accessibility |
+
+### Routing Checklist
+
+| Step | Check                           | If Unchecked                      |
+| ---- | ------------------------------- | --------------------------------- |
+| 1    | Correct agent identified?       | → Analyze domain                  |
+| 2    | Read agent's .md file?          | → Open `.agent/agents/{agent}.md` |
+| 3    | Announced @agent?               | → Add announcement                |
+| 4    | Loaded skills from frontmatter? | → Check `skills:` field           |
+
+❌ Code without agent = PROTOCOL VIOLATION
+❌ Skip announcement = USER CANNOT VERIFY
+
+---
+
+## 📜 WORKFLOWS (Slash Commands)
+
+| Command        | Description                          | Agent           |
+| -------------- | ------------------------------------ | --------------- |
+| `/plan`        | Create project plan, NO CODE         | project-planner |
+| `/create`      | Build new application                | orchestrator    |
+| `/debug`       | Systematic debugging                 | debugger        |
+| `/test`        | Generate and run tests               | test-engineer   |
+| `/deploy`      | Production deployment                | devops-engineer |
+| `/orchestrate` | Multi-agent coordination (3+ agents) | orchestrator    |
+
+---
+
+## 🛠️ SKILL LOADING PROTOCOL
+
+```
+User Request → Skill Description Match → Load SKILL.md → Apply
+```
+
+### Core Skills (Always Available)
+
+- `clean-code` - Pragmatic coding standards (used by ALL agents)
+- `testing-patterns` - Testing pyramid, AAA pattern
+- `security-fundamentals` - OWASP 2025
+
+### Domain Skills (39 total - see ARCHITECTURE.md)
+
+Key skills: `api-patterns`, `database-design`, `react-patterns`, `typescript-patterns`, `docker-patterns`, `kubernetes-patterns`, `terraform-patterns`, `auth-patterns`, `graphql-patterns`, `redis-patterns`, `realtime-patterns`, `queue-patterns`, `multi-tenancy`, `ai-rag-patterns`, `prompt-engineering`, `monitoring-observability`, `frontend-design`, `mobile-design`, `tailwind-patterns`, `e2e-testing`, `performance-profiling`, `plan-writing`, `systematic-debugging`, `brainstorming`, `github-actions`, `gitlab-ci-patterns`
+
+> 🔴 Full skill list: See `ARCHITECTURE.md` → Skills section
+
+---
+
+## TIER 0: UNIVERSAL RULES
+
+### 🌐 Language
+
+- Non-English prompt → Respond in user's language
+- Code comments/variables → Always English
+- File names → Always English (kebab-case)
+
+### 🧹 Clean Code
+
+- Concise, no over-engineering, self-documenting
+- Testing: Pyramid (Unit > Int > E2E) + AAA
+- Performance: Measure first, Core Web Vitals
+
+### 🗺️ System Map
+
+> 🔴 Read `ARCHITECTURE.md` at session start.
+
+**Paths:** Agents `.agent/agents/`, Skills `.agent/skills/`, Workflows `.agent/workflows/`
+
+### 🧠 Read → Understand → Apply
+
+Before coding: 1) What is the GOAL? 2) What PRINCIPLES? 3) How does this DIFFER from generic?
+
+---
+
+## TIER 1: CODE RULES
+
+### 📱 Project Routing
+
+| Type                               | Agent               | Skills                        |
+| ---------------------------------- | ------------------- | ----------------------------- |
+| MOBILE (iOS, Android, RN, Flutter) | mobile-developer    | mobile-design                 |
+| WEB (Next.js, React)               | frontend-specialist | frontend-design               |
+| BACKEND (API, DB)                  | backend-specialist  | api-patterns, database-design |
+
+> 🔴 Mobile + frontend-specialist = WRONG.
+
+### 🛑 Socratic Gate
+
+For complex requests, STOP and ASK first:
+
+| Request Type        | Action                                |
+| ------------------- | ------------------------------------- |
+| New Feature / Build | Ask 3+ strategic questions            |
+| Code Edit / Bug Fix | Confirm understanding first           |
+| Vague Request       | Ask Purpose, Users, Scope             |
+| Full Orchestration  | User must confirm plan before Phase 2 |
+
+**Never Assume.** If 1% unclear → ASK.
+
+### 🎭 Mode Mapping
+
+| Mode | Agent           | Behavior                        |
+| ---- | --------------- | ------------------------------- |
+| plan | project-planner | 4-phase, NO CODE before Phase 4 |
+| ask  | -               | Questions only                  |
+| edit | orchestrator    | Check {task-slug}.md first      |
+
+---
+
+## TIER 2: DESIGN RULES
+
+> Rules in specialist agents: Web → `frontend-specialist.md`, Mobile → `mobile-developer.md`
+
+---
+
+## 📜 SCRIPTS (Automation)
+
+### When to Run Scripts
+
+| Trigger          | Script                     | Purpose                                  |
+| ---------------- | -------------------------- | ---------------------------------------- |
+| Before PR/commit | `checklist.py`             | Quick validation (Security, Lint, Tests) |
+| Before deploy    | `verify_all.py`            | Full pre-deployment suite                |
+| Kit maintenance  | `kit_status.py --validate` | Check kit integrity                      |
+| Managing skills  | `skills_manager.py`        | Enable/disable/search skills             |
+
+### Master Scripts
+
+```bash
+# Quick check during development
+python3 .agent/scripts/checklist.py .
+
+# Full check with performance audits
+python3 .agent/scripts/checklist.py . --url http://localhost:3000
+
+# Pre-deployment verification
+python3 .agent/scripts/verify_all.py . --url http://localhost:3000
+
+# Kit status
+python3 .agent/scripts/kit_status.py --validate
+
+# Skill management
+python3 .agent/scripts/skills_manager.py list
+python3 .agent/scripts/skills_manager.py search <query>
+```
+
+### Skill-Specific Scripts
+
+| Skill                    | Script                | When to Use                      |
+| ------------------------ | --------------------- | -------------------------------- |
+| `clean-code`             | `lint_runner.py`      | After code changes               |
+| `testing-patterns`       | `test_runner.py`      | After logic changes              |
+| `security-fundamentals`  | `security_scan.py`    | Before deploy, after deps change |
+| `database-design`        | `schema_validator.py` | After schema changes             |
+| `api-patterns`           | `api_validator.py`    | After API changes                |
+| `i18n-localization`      | `i18n_checker.py`     | After UI text changes            |
+| `seo-patterns`           | `seo_checker.py`      | After page changes               |
+| `accessibility-patterns` | `a11y_checker.py`     | After UI changes                 |
+
+### AI Script Protocol
+
+1. **Security changes** → Run `security_scan.py`
+2. **Database changes** → Run `schema_validator.py`
+3. **API changes** → Run `api_validator.py`
+4. **UI changes** → Run `a11y_checker.py`
+5. **Before suggesting deploy** → Run `verify_all.py`
+
+> 🔴 Full script documentation: See `ARCHITECTURE.md` → Scripts section
+
+---
+
+## 📊 Kit Statistics
+
+| Metric    | Count |
+| --------- | ----- |
+| Agents    | 22    |
+| Skills    | 39    |
+| Workflows | 7     |
+| Scripts   | 19    |
+
+---
+
+> **Philosophy:** Modular agents + reusable skills + clear workflows + automated scripts = scalable AI assistance.

package/kits/coder/scripts/checklist.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""
+AGT-Kit Master Checklist Runner
+=================================
+
+Orchestrates validation scripts in priority order for any project type.
+Designed to work with AGT-Kit's 37 skills.
+
+Usage:
+    python .agent/scripts/checklist.py <project_path>
+    python .agent/scripts/checklist.py . --url http://localhost:3000
+    python .agent/scripts/checklist.py . --quick
+
+Priority Order (P0-P6):
+    P0: Security Scan (vulnerabilities, secrets)
+    P1: Lint & Type Check (code quality)
+    P2: Schema Validation (if database exists)
+    P3: Test Runner (unit/integration tests)
+    P4: UX Audit (accessibility, design)
+    P5: SEO Check (meta tags, Core Web Vitals)
+    P6: Performance (Lighthouse - requires URL)
+"""
+
+import sys
+import subprocess
+import argparse
+import json
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+
+# ANSI colors for terminal output
+class Colors:
+    HEADER = '\033[95m'
+    BLUE = '\033[94m'
+    CYAN = '\033[96m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    RED = '\033[91m'
+    ENDC = '\033[0m'
+    BOLD = '\033[1m'
+
+
+def print_header(text: str):
+    print(f"\n{Colors.BOLD}{Colors.CYAN}{'='*60}{Colors.ENDC}")
+    print(f"{Colors.BOLD}{Colors.CYAN}{text.center(60)}{Colors.ENDC}")
+    print(f"{Colors.BOLD}{Colors.CYAN}{'='*60}{Colors.ENDC}\n")
+
+
+def print_step(text: str):
+    print(f"{Colors.BOLD}{Colors.BLUE}🔄 {text}{Colors.ENDC}")
+
+
+def print_success(text: str):
+    print(f"{Colors.GREEN}✅ {text}{Colors.ENDC}")
+
+
+def print_warning(text: str):
+    print(f"{Colors.YELLOW}⚠️  {text}{Colors.ENDC}")
+
+
+def print_error(text: str):
+    print(f"{Colors.RED}❌ {text}{Colors.ENDC}")
+
+
+# Define skill-based checks - maps to AGT-Kit skills
+CORE_CHECKS = [
+    {
+        "name": "Security Scan",
+        "skill": "security-fundamentals",
+        "script": ".agent/skills/security-fundamentals/scripts/security_scan.py",
+        "priority": 0,
+        "required": True,
+    },
+    {
+        "name": "Lint Check",
+        "skill": "clean-code",
+        "script": ".agent/skills/clean-code/scripts/lint_runner.py",
+        "priority": 1,
+        "required": True,
+    },
+    {
+        "name": "Schema Validation",
+        "skill": "database-design",
+        "script": ".agent/skills/database-design/scripts/schema_validator.py",
+        "priority": 2,
+        "required": False,
+    },
+    {
+        "name": "Test Runner",
+        "skill": "testing-patterns",
+        "script": ".agent/skills/testing-patterns/scripts/test_runner.py",
+        "priority": 3,
+        "required": False,
+    },
+    {
+        "name": "UX Audit",
+        "skill": "frontend-design",
+        "script": ".agent/skills/frontend-design/scripts/ux_audit.py",
+        "priority": 4,
+        "required": False,
+    },
+    {
+        "name": "SEO Check",
+        "skill": "seo-patterns",
+        "script": ".agent/skills/seo-patterns/scripts/seo_checker.py",
+        "priority": 5,
+        "required": False,
+    },
+]
+
+PERFORMANCE_CHECKS = [
+    {
+        "name": "Lighthouse Audit",
+        "skill": "performance-profiling",
+        "script": ".agent/skills/performance-profiling/scripts/lighthouse_audit.py",
+        "priority": 6,
+        "required": False,
+        "needs_url": True,
+    },
+    {
+        "name": "E2E Tests",
+        "skill": "e2e-testing",
+        "script": ".agent/skills/e2e-testing/scripts/playwright_runner.py",
+        "priority": 7,
+        "required": False,
+        "needs_url": True,
+    },
+]
+
+QUICK_CHECKS = ["Security Scan", "Lint Check", "Test Runner"]
+
+
+def detect_project_type(project_path: Path) -> str:
+    """Detect project type to filter relevant checks."""
+    if (project_path / "package.json").exists():
+        pkg = json.loads((project_path / "package.json").read_text())
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        
+        if "next" in deps:
+            return "nextjs"
+        if "react" in deps:
+            return "react"
+        if "express" in deps or "fastify" in deps:
+            return "node-backend"
+        return "node"
+    
+    if (project_path / "pyproject.toml").exists() or (project_path / "requirements.txt").exists():
+        return "python"
+    
+    if (project_path / "pubspec.yaml").exists():
+        return "flutter"
+    
+    if (project_path / "go.mod").exists():
+        return "go"
+    
+    return "unknown"
+
+
+def run_script(check: Dict[str, Any], project_path: Path, url: Optional[str] = None) -> Dict[str, Any]:
+    """Run a validation script and capture results."""
+    script_path = project_path / check["script"]
+    
+    if not script_path.exists():
+        print_warning(f"{check['name']}: Script not found ({check['skill']} skill)")
+        return {
+            "name": check["name"],
+            "skill": check["skill"],
+            "passed": True,
+            "skipped": True,
+            "reason": "Script not found"
+        }
+    
+    print_step(f"Running: {check['name']} ({check['skill']})")
+    
+    # Build command
+    cmd = ["python", str(script_path), str(project_path)]
+    if url and check.get("needs_url"):
+        cmd.append(url)
+    
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=300  # 5 minute timeout
+        )
+        
+        passed = result.returncode == 0
+        
+        if passed:
+            print_success(f"{check['name']}: PASSED")
+        else:
+            print_error(f"{check['name']}: FAILED")
+            if result.stderr:
+                print(f"  Error: {result.stderr[:200]}")
+        
+        return {
+            "name": check["name"],
+            "skill": check["skill"],
+            "passed": passed,
+            "output": result.stdout[:2000] if result.stdout else "",
+            "error": result.stderr[:500] if result.stderr else "",
+            "skipped": False
+        }
+    
+    except subprocess.TimeoutExpired:
+        print_error(f"{check['name']}: TIMEOUT (>5 minutes)")
+        return {"name": check["name"], "skill": check["skill"], "passed": False, "skipped": False, "error": "Timeout"}
+    
+    except Exception as e:
+        print_error(f"{check['name']}: ERROR - {str(e)}")
+        return {"name": check["name"], "skill": check["skill"], "passed": False, "skipped": False, "error": str(e)}
+
+
+def print_summary(results: List[Dict], project_type: str) -> bool:
+    """Print final summary report."""
+    print_header("📊 AGT-KIT CHECKLIST SUMMARY")
+    
+    passed = sum(1 for r in results if r["passed"] and not r.get("skipped"))
+    failed = sum(1 for r in results if not r["passed"] and not r.get("skipped"))
+    skipped = sum(1 for r in results if r.get("skipped"))
+    
+    print(f"Project Type: {project_type}")
+    print(f"Total Checks: {len(results)}")
+    print(f"{Colors.GREEN}✅ Passed: {passed}{Colors.ENDC}")
+    print(f"{Colors.RED}❌ Failed: {failed}{Colors.ENDC}")
+    print(f"{Colors.YELLOW}⏭️  Skipped: {skipped}{Colors.ENDC}")
+    print()
+    
+    # Results by skill
+    print(f"{Colors.BOLD}Results by Skill:{Colors.ENDC}")
+    for r in results:
+        if r.get("skipped"):
+            status = f"{Colors.YELLOW}⏭️ {Colors.ENDC}"
+        elif r["passed"]:
+            status = f"{Colors.GREEN}✅{Colors.ENDC}"
+        else:
+            status = f"{Colors.RED}❌{Colors.ENDC}"
+        
+        print(f"  {status} {r['name']} ({r['skill']})")
+    
+    print()
+    
+    if failed > 0:
+        print_error(f"{failed} check(s) FAILED - Please fix before proceeding")
+        return False
+    else:
+        print_success("All checks PASSED ✨")
+        return True
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="AGT-Kit Master Checklist - Validate project with AGT-Kit skills",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python .agent/scripts/checklist.py .                      # Core checks
+  python .agent/scripts/checklist.py . --url http://localhost:3000  # + Performance
+  python .agent/scripts/checklist.py . --quick              # Quick checks only
+        """
+    )
+    parser.add_argument("project", help="Project path to validate")
+    parser.add_argument("--url", help="URL for performance checks (Lighthouse, Playwright)")
+    parser.add_argument("--quick", action="store_true", help="Run only quick checks (Security, Lint, Tests)")
+    parser.add_argument("--stop-on-fail", action="store_true", help="Stop on first critical failure")
+    
+    args = parser.parse_args()
+    
+    project_path = Path(args.project).resolve()
+    
+    if not project_path.exists():
+        print_error(f"Project path does not exist: {project_path}")
+        sys.exit(1)
+    
+    project_type = detect_project_type(project_path)
+    
+    print_header("🚀 AGT-KIT MASTER CHECKLIST")
+    print(f"Project: {project_path}")
+    print(f"Type: {project_type}")
+    print(f"URL: {args.url if args.url else 'Not provided'}")
+    print(f"Mode: {'Quick' if args.quick else 'Full'}")
+    
+    results = []
+    
+    # Filter checks based on --quick flag
+    checks_to_run = CORE_CHECKS.copy()
+    if args.quick:
+        checks_to_run = [c for c in checks_to_run if c["name"] in QUICK_CHECKS]
+    
+    # Run core checks
+    print_header("📋 CORE CHECKS")
+    for check in sorted(checks_to_run, key=lambda x: x["priority"]):
+        result = run_script(check, project_path)
+        results.append(result)
+        
+        # Stop on critical failure if flag set
+        if args.stop_on_fail and check["required"] and not result["passed"] and not result.get("skipped"):
+            print_error(f"CRITICAL: {check['name']} failed. Stopping.")
+            print_summary(results, project_type)
+            sys.exit(1)
+    
+    # Run performance checks if URL provided
+    if args.url and not args.quick:
+        print_header("⚡ PERFORMANCE CHECKS")
+        for check in PERFORMANCE_CHECKS:
+            result = run_script(check, project_path, args.url)
+            results.append(result)
+    
+    # Print summary
+    all_passed = print_summary(results, project_type)
+    
+    sys.exit(0 if all_passed else 1)
+
+
+if __name__ == "__main__":
+    main()