@neyugn/agent-kits 0.3.4 → 0.3.6

package/dist/cli.js

@@ -99,7 +99,7 @@ var AI_TOOLS = [
     path: ".opencode",
     globalPathPattern: "~/.config/opencode",
     rulesFile: "AGENTS.md",
-    kitRulesFile: "AGENTS.md",
+    kitRulesFile: "OPENCODE.md",
     rulesInsideKit: false,
     // OpenCode reads AGENTS.md from project root
     workflowsAs: "commands",

package/kits/coder/rules/OPENCODE.md

@@ -0,0 +1,346 @@
+# AGENTS.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
+- **40 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 ARCHITECTURE.md for assigned skills → Use `skill` tool to load each → Apply.
+
+- **Priority:** P0 (AGENTS.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 ARCHITECTURE?  | → Check ARCHITECTURE.md agent-skills table  |
+
+❌ 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
+
+```
+Agent activated → Check ARCHITECTURE.md for assigned skills → Use `skill` tool → Apply SKILL.md content
+```
+
+### How Skills Work in OpenCode
+
+OpenCode has a **native `skill` tool** that automatically discovers all available skills.
+
+1. **Discovery**: OpenCode scans `.agent/skills/*/SKILL.md` and lists them in the `skill` tool description
+2. **Selection**: Check ARCHITECTURE.md → find your agent → note the "Skills Used" column
+3. **Loading**: Call `skill({ name: "skill-name" })` to load each assigned skill
+4. **Apply**: Follow the loaded SKILL.md instructions
+
+```
+# Example: frontend-specialist activated
+1. Read ARCHITECTURE.md → Skills: clean-code, react-patterns, typescript-patterns, ...
+2. Call skill({ name: "clean-code" }) → Read content
+3. Call skill({ name: "react-patterns" }) → Read content
+4. Apply all loaded skill rules to the task
+```
+
+### Profile-Aware Loading
+
+> **CRITICAL:** Before loading any skill or selecting any agent, check `.agent/profile.json`
+
+```
+1. Check if `.agent/profile.json` exists
+2. If EXISTS:
+   - Read skills.enabled[] → Only load these skills
+   - Read skills.disabled[] → Skip these skills
+   - Read agents.disabled[] → Skip these agents
+   - Respect userOverrides.force-enabled/force-disabled
+3. If NOT EXISTS:
+   - All skills/agents are ENABLED by default
+   - Behave as if no filtering is applied
+```
+
+### Skill Permissions (OpenCode)
+
+Control skill access in `opencode.json`:
+
+```json
+{
+  "permission": {
+    "skill": {
+      "*": "allow",
+      "internal-*": "deny"
+    }
+  }
+}
+```
+
+Or per-agent in agent frontmatter:
+
+```yaml
+---
+permission:
+  skill:
+    "documents-*": "allow"
+---
+```
+
+### Core Skills (Always Available)
+
+These skills are NEVER disabled regardless of profile:
+
+- `clean-code` - Pragmatic coding standards (used by ALL agents)
+- `testing-patterns` - Testing pyramid, AAA pattern
+- `security-fundamentals` - OWASP 2025
+- `brainstorming` - Socratic questioning protocol
+- `plan-writing` - Task breakdown and WBS
+- `systematic-debugging` - 4-phase debugging
+
+### Domain Skills (40 total - see .agent/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`, `github-actions`, `gitlab-ci-patterns`
+
+> 🔴 Full skill list: See `.agent/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 `.agent/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 `.agent/ARCHITECTURE.md` → Scripts section
+
+---
+
+## 📊 Kit Statistics
+
+| Metric    | Count |
+| --------- | ----- |
+| Agents    | 22    |
+| Skills    | 40    |
+| Workflows | 7     |
+| Scripts   | 19    |
+
+---
+
+> **Philosophy:** Modular agents + reusable skills + clear workflows + automated scripts = scalable AI assistance.

package/kits/coder/scripts/kit_status.py

@@ -90,6 +90,46 @@ def parse_frontmatter(file_path: Path) -> Dict[str, Any]:
     return {}
 
 
+def parse_skills_from_architecture(agent_dir: Path) -> Dict[str, List[str]]:
+    """Parse agent-skill mappings from ARCHITECTURE.md tables.
+    
+    Falls back to this when agents don't have skills in frontmatter
+    (e.g., OpenCode strips the skills field during transformation).
+    """
+    arch_file = agent_dir / "ARCHITECTURE.md"
+    if not arch_file.exists():
+        return {}
+    
+    mapping = {}
+    try:
+        content = arch_file.read_text()
+        # Match table rows: | `agent-name` | description | skills-list |
+        # Pattern: | `name` | ... | skill1, skill2, ... |
+        for line in content.split('\n'):
+            if not line.startswith('|'):
+                continue
+            cells = [c.strip() for c in line.split('|')]
+            # Filter out empty cells from leading/trailing pipes
+            cells = [c for c in cells if c]
+            if len(cells) >= 3:
+                # First cell might be agent name wrapped in backticks
+                agent_name = cells[0].strip('`').strip()
+                # Last cell contains skills
+                skills_str = cells[-1]
+                # Skip header/separator rows
+                if agent_name.startswith('-') or agent_name == 'Agent':
+                    continue
+                # Parse comma-separated skills
+                skills = [s.strip().strip('`') for s in skills_str.split(',') if s.strip()]
+                # Only add if skills look valid (not header text)
+                if skills and not any(s in ['Skills Used', '---', 'Skills'] for s in skills):
+                    mapping[agent_name] = skills
+    except Exception:
+        pass
+    
+    return mapping
+
+
 def get_agents(agent_dir: Path) -> List[Dict[str, Any]]:
     """Get list of agents with their metadata."""
     agents = []
@@ -98,10 +138,12 @@ def get_agents(agent_dir: Path) -> List[Dict[str, Any]]:
     if not agents_path.exists():
         return agents
     
+    # Parse agent-skill mappings from ARCHITECTURE.md (single source of truth)
+    arch_skills = parse_skills_from_architecture(agent_dir)
+    
     for agent_file in agents_path.glob("*.md"):
         frontmatter = parse_frontmatter(agent_file)
-        skills = frontmatter.get("skills", "").replace("[", "").replace("]", "").split(",")
-        skills = [s.strip() for s in skills if s.strip()]
+        skills = arch_skills.get(agent_file.stem, [])
         
         agents.append({
             "name": agent_file.stem,
@@ -146,22 +188,33 @@ def get_skills(agent_dir: Path) -> List[Dict[str, Any]]:
 
 
 def get_workflows(agent_dir: Path) -> List[Dict[str, Any]]:
-    """Get list of workflows."""
-    workflows = []
-    workflows_path = agent_dir / "workflows"
+    """Get list of workflows/commands.
     
-    if not workflows_path.exists():
-        return workflows
+    Checks both 'workflows/' (Cursor, Gemini) and 'commands/' (OpenCode)
+    directories since different AI tools use different naming.
+    """
+    workflows = []
     
-    for workflow_file in workflows_path.glob("*.md"):
-        frontmatter = parse_frontmatter(workflow_file)
+    # Check both possible directories
+    for dir_name in ["workflows", "commands"]:
+        workflows_path = agent_dir / dir_name
         
-        workflows.append({
-            "name": workflow_file.stem,
-            "command": f"/{workflow_file.stem}",
-            "file": str(workflow_file.relative_to(agent_dir)),
-            "description": frontmatter.get("description", ""),
-        })
+        if not workflows_path.exists():
+            continue
+        
+        for workflow_file in workflows_path.glob("*.md"):
+            frontmatter = parse_frontmatter(workflow_file)
+            
+            workflows.append({
+                "name": workflow_file.stem,
+                "command": f"/{workflow_file.stem}",
+                "file": str(workflow_file.relative_to(agent_dir)),
+                "description": frontmatter.get("description", ""),
+            })
+        
+        # Only use the first directory found (don't double-count)
+        if workflows:
+            break
     
     return sorted(workflows, key=lambda x: x["name"])
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neyugn/agent-kits",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Universal AI Agent Toolkit - Skills, Agents, and Workflows for any AI coding assistant",
   "type": "module",
   "bin": {