@musashishao/agent-kit 1.1.4 → 1.1.6

package/.agent/rules/CODEX.md

@@ -0,0 +1,250 @@
+---
+trigger: always_on
+platform: codex-cli
+priority: P0
+---
+
+# CODEX.md - Codex CLI Optimization Rules
+
+> **Agent Kit** - Codex CLI specific rules for maximum output quality.
+> This file extends the universal rules with Codex-specific optimizations.
+
+---
+
+## 🎯 CODEX CLI OPTIMIZATION PROTOCOL
+
+### 1. Context Window Management
+
+Codex CLI has specific context handling. Optimize by:
+
+| Strategy | Implementation |
+|----------|----------------|
+| **Selective Loading** | Only read skills referenced in user request |
+| **Skill Caching** | Once a skill is read, don't re-read in same session |
+| **Minimal Agents** | Load max 3 agents per task |
+| **Token Budget** | Reserve 40% for reasoning, 30% for code output |
+
+### 2. Skill Loading Order
+
+```
+STEP 1: Check AGENTS.md → Understand kit structure
+STEP 2: Identify task type → Map to skills/agents
+STEP 3: Read skill SKILL.md → Get instructions
+STEP 4: Read only sections needed → Not entire folder
+STEP 5: Execute → Apply skill principles
+```
+
+### 3. Output Quality Standards
+
+| Aspect | Requirement |
+|--------|-------------|
+| **Code** | Production-ready, no TODOs, no placeholders |
+| **Comments** | Minimal, only for non-obvious logic |
+| **Types** | Full TypeScript strict types |
+| **Error Handling** | Comprehensive try-catch, proper error messages |
+| **Security** | No hardcoded secrets, proper input validation |
+| **Performance** | Optimized queries, no N+1, lazy loading |
+
+---
+
+## 🧠 TASK CLASSIFICATION
+
+Before action, classify the request:
+
+| Type | Keywords | Action |
+|------|----------|--------|
+| **QUESTION** | "what is", "how does", "explain" | Text response only |
+| **SIMPLE FIX** | "fix", "update", "change" (single file) | Direct edit |
+| **FEATURE** | "add", "implement", "create" | Use `/create` or `/enhance` workflow |
+| **DEBUG** | "why", "not working", "error" | Use `/debug` workflow |
+| **REVIEW** | "review", "audit", "check" | Use appropriate agent |
+| **DESIGN** | "design", "UI", "page" | Use `/ui-ux-pro-max` workflow |
+
+---
+
+## 🔴 CRITICAL RULES
+
+### Rule 1: Read Before Write
+```
+❌ WRONG: Immediately start coding
+✅ CORRECT: Read → Understand → Plan → Code
+```
+
+### Rule 2: Skill-Based Coding
+```
+For each domain, apply corresponding skill:
+- Frontend → Read react-patterns, nextjs-best-practices
+- Backend → Read api-patterns, nodejs-best-practices  
+- Database → Read database-design, prisma-expert
+- Security → Read vulnerability-scanner
+- UI/UX → Read ui-ux-pro-max, frontend-design
+```
+
+### Rule 3: Quality Over Speed
+```
+- No placeholder code (e.g., "// TODO: implement")
+- No generic variable names (e.g., "data", "temp")
+- No console.log in production code
+- Always handle edge cases
+```
+
+### Rule 4: Socratic Gate
+For complex/unclear requests, ASK before implementing:
+```
+Before I implement, let me clarify:
+1. [Specific question about scope]
+2. [Specific question about requirements]
+3. [Specific question about constraints]
+```
+
+---
+
+## 📂 SKILL QUICK REFERENCE
+
+### Frontend Development
+```
+/read .agent/skills/react-patterns/SKILL.md
+/read .agent/skills/nextjs-best-practices/SKILL.md
+/read .agent/skills/tailwind-patterns/SKILL.md
+/read .agent/skills/frontend-design/SKILL.md
+```
+
+### Backend Development
+```
+/read .agent/skills/api-patterns/SKILL.md
+/read .agent/skills/nodejs-best-practices/SKILL.md
+/read .agent/skills/database-design/SKILL.md
+/read .agent/skills/prisma-expert/SKILL.md
+```
+
+### Security
+```
+/read .agent/skills/vulnerability-scanner/SKILL.md
+/read .agent/skills/red-team-tactics/SKILL.md
+```
+
+### UI/UX Design
+```
+/read .agent/skills/ui-ux-pro-max/SKILL.md
+/read .agent/skills/mobile-design/SKILL.md
+```
+
+### Debugging
+```
+/read .agent/skills/systematic-debugging/SKILL.md
+/read .agent/skills/problem-solving/SKILL.md
+```
+
+---
+
+## 🛠️ WORKFLOW TRIGGERS
+
+| User Says | Trigger Workflow |
+|-----------|-----------------|
+| "create", "build", "make new" | `/create` |
+| "fix", "debug", "not working" | `/debug` |
+| "plan", "break down", "roadmap" | `/plan` |
+| "design", "UI", "beautiful" | `/ui-ux-pro-max` |
+| "test", "coverage", "unit test" | `/test` |
+| "deploy", "production", "ship" | `/deploy` |
+| "review", "audit", "check" | Use agent directly |
+
+---
+
+## 🎨 OUTPUT FORMATTING
+
+### For Code
+```typescript
+// Use proper structure
+interface Example {
+  id: string;
+  name: string;
+  createdAt: Date;
+}
+
+function exampleFunction(param: Example): Result {
+  // Implementation with proper error handling
+  try {
+    // Logic here
+  } catch (error) {
+    throw new CustomError('Descriptive message', { cause: error });
+  }
+}
+```
+
+### For Explanations
+1. **Be concise** - No unnecessary verbosity
+2. **Use tables** - For comparisons and options
+3. **Use code blocks** - For any code reference
+4. **Use headers** - For organization
+
+### For Plans
+```markdown
+## Task: [Name]
+
+### Phase 1: [Name]
+- [ ] Task 1.1: Description
+- [ ] Task 1.2: Description
+
+### Phase 2: [Name]
+...
+```
+
+---
+
+## 📊 QUALITY CHECKLIST
+
+Before completing any task:
+
+| Check | Criteria |
+|-------|----------|
+| ✅ Code compiles | No TypeScript errors |
+| ✅ Clean code | Following skill guidelines |
+| ✅ Security | No vulnerabilities |
+| ✅ Performance | No obvious bottlenecks |
+| ✅ Documentation | Inline comments where needed |
+| ✅ Tests | Unit tests for logic (if applicable) |
+| ✅ Edge cases | Handled null, undefined, errors |
+
+---
+
+## 🔗 INTEGRATION WITH AGENTS
+
+When user mentions an agent (e.g., `@security-auditor`):
+
+1. **Read** `.agent/agents/{agent-name}.md`
+2. **Apply** the agent's personality and rules
+3. **Use** the agent's skills (listed in frontmatter)
+4. **Output** in the agent's expected format
+
+---
+
+## 📝 EXAMPLE USAGE
+
+### User Request
+```
+Create a login page with email/password authentication
+```
+
+### Codex Response (Following CODEX.md)
+```
+I'll create a production-ready login page.
+
+**Skills Applied:**
+- react-patterns → Component structure
+- nextjs-best-practices → App Router patterns
+- tailwind-patterns → Styling
+- vulnerability-scanner → Auth security
+
+**Implementation:**
+[Full code with proper types, error handling, security]
+
+**Next Steps:**
+- [ ] Add forgot password flow
+- [ ] Configure email provider
+- [ ] Add rate limiting
+```
+
+---
+
+*Agent Kit - CODEX.md rules for highest quality AI output*

package/.agent/skills/app-builder/project-detection.md

@@ -29,6 +29,6 @@
 1. Tokenize user request
 2. Extract keywords
 3. Determine project type
-4. Detect missing information → forward to conversation-manager
+4. Detect missing information → forward to brainstorming skill
 5. Suggest tech stack
 ```

package/.agent/skills/context-engineering/scripts/quality_validator.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""
+Agent Kit Quality Validator
+Validates AGENTS.md and .agent folder structure for Codex CLI compatibility.
+
+Usage:
+    python quality_validator.py [path]
+    
+Example:
+    python quality_validator.py .
+    python quality_validator.py /path/to/project
+"""
+
+import os
+import sys
+import re
+import json
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+# ANSI colors
+class Colors:
+    RED = '\033[91m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    BLUE = '\033[94m'
+    MAGENTA = '\033[95m'
+    CYAN = '\033[96m'
+    RESET = '\033[0m'
+    BOLD = '\033[1m'
+
+def print_header(msg: str):
+    print(f"\n{Colors.BOLD}{Colors.MAGENTA}{msg}{Colors.RESET}\n")
+
+def print_check(name: str, passed: bool, message: str = ""):
+    status = f"{Colors.GREEN}✓{Colors.RESET}" if passed else f"{Colors.RED}✗{Colors.RESET}"
+    msg_color = Colors.GREEN if passed else Colors.RED
+    print(f"  {status} {Colors.CYAN}{name}{Colors.RESET}: {msg_color}{message}{Colors.RESET}")
+
+
+class AgentKitValidator:
+    def __init__(self, project_path: str):
+        self.project_path = Path(project_path).resolve()
+        self.agent_dir = self.project_path / ".agent"
+        self.agents_md = self.project_path / "AGENTS.md"
+        self.results: List[Tuple[str, bool, str]] = []
+        
+    def validate_all(self) -> Dict:
+        """Run all validations and return summary"""
+        print_header("🔍 Agent Kit Quality Validator")
+        print(f"Project: {self.project_path}\n")
+        
+        checks = [
+            self.check_agents_md_exists,
+            self.check_agent_folder_structure,
+            self.check_agents_format,
+            self.check_skills_format,
+            self.check_workflows_format,
+            self.check_codex_compatibility,
+            self.check_skill_loading_protocol,
+        ]
+        
+        for check in checks:
+            check()
+        
+        return self.summarize()
+    
+    def check_agents_md_exists(self):
+        """Check if AGENTS.md exists at project root"""
+        print_header("📄 AGENTS.md Validation")
+        
+        if self.agents_md.exists():
+            content = self.agents_md.read_text()
+            
+            # Check required sections
+            required_sections = [
+                ("Project Overview", r"##.*Overview"),
+                ("Setup Commands", r"##.*Setup"),
+                ("Code Style", r"##.*Code Style|##.*Standards"),
+            ]
+            
+            for name, pattern in required_sections:
+                found = bool(re.search(pattern, content, re.IGNORECASE))
+                self.results.append((f"AGENTS.md: {name}", found, "Found" if found else "Missing"))
+                print_check(f"Section: {name}", found, "Found" if found else "Missing")
+                
+            # Check for loading protocol
+            has_protocol = "workflow" in content.lower() and "skill" in content.lower()
+            self.results.append(("Loading Protocol", has_protocol, "Found" if has_protocol else "Missing"))
+            print_check("Loading Protocol", has_protocol, "Found" if has_protocol else "Should document how to use skills/workflows")
+            
+        else:
+            self.results.append(("AGENTS.md exists", False, "Not found"))
+            print_check("AGENTS.md", False, f"Not found at {self.agents_md}")
+    
+    def check_agent_folder_structure(self):
+        """Check .agent folder structure"""
+        print_header("📁 Folder Structure Validation")
+        
+        required_dirs = ["agents", "skills", "workflows"]
+        optional_dirs = ["rules", "templates", "plans"]
+        
+        for dir_name in required_dirs:
+            dir_path = self.agent_dir / dir_name
+            exists = dir_path.exists()
+            count = len(list(dir_path.iterdir())) if exists else 0
+            self.results.append((f".agent/{dir_name}", exists, f"{count} items" if exists else "Missing"))
+            print_check(f".agent/{dir_name}/", exists, f"{count} items" if exists else "Missing (required)")
+        
+        for dir_name in optional_dirs:
+            dir_path = self.agent_dir / dir_name
+            exists = dir_path.exists()
+            count = len(list(dir_path.iterdir())) if exists else 0
+            if exists:
+                print_check(f".agent/{dir_name}/", True, f"{count} items (optional)")
+    
+    def check_agents_format(self):
+        """Check agent file format"""
+        print_header("🤖 Agent Files Validation")
+        
+        agents_dir = self.agent_dir / "agents"
+        if not agents_dir.exists():
+            return
+        
+        for agent_file in agents_dir.glob("*.md"):
+            content = agent_file.read_text()
+            
+            # Check frontmatter
+            has_frontmatter = content.startswith("---")
+            has_name = bool(re.search(r"^name:\s*.+", content, re.MULTILINE))
+            has_description = bool(re.search(r"^description:\s*.+", content, re.MULTILINE))
+            
+            is_valid = has_frontmatter and has_name and has_description
+            issues = []
+            if not has_frontmatter:
+                issues.append("missing frontmatter")
+            if not has_name:
+                issues.append("missing name")
+            if not has_description:
+                issues.append("missing description")
+            
+            message = "Valid" if is_valid else f"Issues: {', '.join(issues)}"
+            self.results.append((f"Agent: {agent_file.name}", is_valid, message))
+            print_check(agent_file.name, is_valid, message)
+    
+    def check_skills_format(self):
+        """Check skill file format"""
+        print_header("🧠 Skills Validation")
+        
+        skills_dir = self.agent_dir / "skills"
+        if not skills_dir.exists():
+            return
+        
+        valid_count = 0
+        total_count = 0
+        
+        for skill_dir in skills_dir.iterdir():
+            if not skill_dir.is_dir():
+                continue
+            
+            total_count += 1
+            skill_md = skill_dir / "SKILL.md"
+            
+            if skill_md.exists():
+                content = skill_md.read_text()
+                has_frontmatter = content.startswith("---")
+                has_description = bool(re.search(r"^description:\s*.+", content, re.MULTILINE))
+                
+                if has_frontmatter and has_description:
+                    valid_count += 1
+        
+        is_valid = valid_count == total_count
+        message = f"{valid_count}/{total_count} skills have valid SKILL.md"
+        self.results.append(("Skills Format", is_valid, message))
+        print_check("Skills Format", is_valid, message)
+    
+    def check_workflows_format(self):
+        """Check workflow file format"""
+        print_header("⚡ Workflows Validation")
+        
+        workflows_dir = self.agent_dir / "workflows"
+        if not workflows_dir.exists():
+            return
+        
+        valid_count = 0
+        total_count = 0
+        
+        for wf_file in workflows_dir.glob("*.md"):
+            total_count += 1
+            content = wf_file.read_text()
+            
+            has_frontmatter = content.startswith("---")
+            has_description = bool(re.search(r"^description:\s*.+", content, re.MULTILINE))
+            
+            if has_frontmatter and has_description:
+                valid_count += 1
+            else:
+                print_check(wf_file.name, False, "Missing frontmatter or description")
+        
+        is_valid = valid_count == total_count
+        message = f"{valid_count}/{total_count} workflows are valid"
+        self.results.append(("Workflows Format", is_valid, message))
+        print_check("Overall", is_valid, message)
+    
+    def check_codex_compatibility(self):
+        """Check Codex CLI specific requirements"""
+        print_header("🔗 Codex CLI Compatibility")
+        
+        checks = []
+        
+        # Check 1: AGENTS.md in root
+        checks.append(("AGENTS.md in root", self.agents_md.exists()))
+        
+        # Check 2: .codex folder (optional)
+        codex_dir = self.project_path / ".codex"
+        checks.append((".codex config (optional)", codex_dir.exists()))
+        
+        # Check 3: CODEX.md rules
+        codex_rules = self.agent_dir / "rules" / "CODEX.md"
+        checks.append(("CODEX.md rules", codex_rules.exists()))
+        
+        for name, passed in checks:
+            message = "Found" if passed else "Missing"
+            self.results.append((name, passed, message))
+            print_check(name, passed, message)
+    
+    def check_skill_loading_protocol(self):
+        """Check if AGENTS.md has proper skill loading protocol"""
+        print_header("📖 Skill Loading Protocol")
+        
+        if not self.agents_md.exists():
+            print_check("Protocol Check", False, "AGENTS.md not found")
+            return
+        
+        content = self.agents_md.read_text().lower()
+        
+        protocols = [
+            ("Skill reference", ".agent/skills" in content),
+            ("Workflow reference", ".agent/workflows" in content),
+            ("Agent reference", ".agent/agents" in content),
+            ("Loading order", "loading" in content or "protocol" in content),
+        ]
+        
+        for name, passed in protocols:
+            message = "Documented" if passed else "Should be documented"
+            self.results.append((name, passed, message))
+            print_check(name, passed, message)
+    
+    def summarize(self) -> Dict:
+        """Print summary and return results"""
+        print_header("📊 Summary")
+        
+        passed = sum(1 for _, p, _ in self.results if p)
+        total = len(self.results)
+        percentage = (passed / total * 100) if total > 0 else 0
+        
+        color = Colors.GREEN if percentage >= 80 else Colors.YELLOW if percentage >= 60 else Colors.RED
+        
+        print(f"  {color}Passed: {passed}/{total} ({percentage:.0f}%){Colors.RESET}")
+        
+        if percentage >= 90:
+            print(f"\n  {Colors.GREEN}✓ Excellent! Agent Kit is fully configured for Codex CLI.{Colors.RESET}")
+        elif percentage >= 70:
+            print(f"\n  {Colors.YELLOW}⚠ Good, but some improvements recommended.{Colors.RESET}")
+        else:
+            print(f"\n  {Colors.RED}✗ Several issues found. Please review the checks above.{Colors.RESET}")
+        
+        # Show failed checks
+        failed = [(n, m) for n, p, m in self.results if not p]
+        if failed:
+            print(f"\n  {Colors.BOLD}Issues to fix:{Colors.RESET}")
+            for name, message in failed[:5]:  # Show top 5
+                print(f"    - {name}: {message}")
+        
+        return {
+            "passed": passed,
+            "total": total,
+            "percentage": percentage,
+            "results": self.results
+        }
+
+
+def main():
+    project_path = sys.argv[1] if len(sys.argv) > 1 else "."
+    
+    validator = AgentKitValidator(project_path)
+    results = validator.validate_all()
+    
+    # Exit with error code if less than 70% passed
+    sys.exit(0 if results["percentage"] >= 70 else 1)
+
+
+if __name__ == "__main__":
+    main()