@musashishao/agent-kit 1.2.2 → 1.3.0

package/.agent/skills/app-builder/scripts/generate_ai_infra.py

@@ -0,0 +1,510 @@
+#!/usr/bin/env python3
+"""
+AI Infrastructure Generator
+
+Automatically generates AGENTS.md, dependency graph, and RAG structure
+for new projects created via /create workflow.
+
+Usage:
+    python generate_ai_infra.py --project-root ./my-project
+"""
+
+import os
+import json
+import subprocess
+import argparse
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, List, Optional
+
+
+def detect_tech_stack(project_root: Path) -> Dict:
+    """Detect tech stack from project files."""
+    stack = {
+        'frontend': None,
+        'backend': None,
+        'database': None,
+        'styling': None,
+        'testing': None,
+        'language': None,
+    }
+    
+    # Check package.json
+    package_json = project_root / 'package.json'
+    if package_json.exists():
+        try:
+            pkg = json.loads(package_json.read_text())
+            deps = {**pkg.get('dependencies', {}), **pkg.get('devDependencies', {})}
+            
+            # Frontend
+            if 'next' in deps:
+                stack['frontend'] = 'Next.js'
+            elif 'react' in deps:
+                stack['frontend'] = 'React'
+            elif 'vue' in deps:
+                stack['frontend'] = 'Vue'
+            elif 'svelte' in deps:
+                stack['frontend'] = 'Svelte'
+            
+            # Backend
+            if 'express' in deps:
+                stack['backend'] = 'Express'
+            elif 'fastify' in deps:
+                stack['backend'] = 'Fastify'
+            elif 'nestjs' in deps or '@nestjs/core' in deps:
+                stack['backend'] = 'NestJS'
+            
+            # Database
+            if 'prisma' in deps or '@prisma/client' in deps:
+                stack['database'] = 'Prisma'
+            elif 'mongoose' in deps:
+                stack['database'] = 'MongoDB + Mongoose'
+            elif 'drizzle-orm' in deps:
+                stack['database'] = 'Drizzle ORM'
+            
+            # Styling
+            if 'tailwindcss' in deps:
+                stack['styling'] = 'Tailwind CSS'
+            elif 'styled-components' in deps:
+                stack['styling'] = 'Styled Components'
+            elif 'sass' in deps:
+                stack['styling'] = 'Sass'
+            
+            # Testing
+            if 'vitest' in deps:
+                stack['testing'] = 'Vitest'
+            elif 'jest' in deps:
+                stack['testing'] = 'Jest'
+            elif 'playwright' in deps or '@playwright/test' in deps:
+                stack['testing'] = 'Playwright'
+            
+            # Language
+            if 'typescript' in deps:
+                stack['language'] = 'TypeScript'
+            else:
+                stack['language'] = 'JavaScript'
+                
+        except json.JSONDecodeError:
+            pass
+    
+    # Check Python files
+    requirements = project_root / 'requirements.txt'
+    pyproject = project_root / 'pyproject.toml'
+    
+    if requirements.exists() or pyproject.exists():
+        stack['language'] = 'Python'
+        
+        if requirements.exists():
+            content = requirements.read_text().lower()
+            if 'fastapi' in content:
+                stack['backend'] = 'FastAPI'
+            elif 'django' in content:
+                stack['backend'] = 'Django'
+            elif 'flask' in content:
+                stack['backend'] = 'Flask'
+            
+            if 'sqlalchemy' in content:
+                stack['database'] = 'SQLAlchemy'
+            elif 'prisma' in content:
+                stack['database'] = 'Prisma'
+            
+            if 'pytest' in content:
+                stack['testing'] = 'Pytest'
+    
+    return stack
+
+
+def detect_directory_structure(project_root: Path) -> Dict[str, str]:
+    """Detect and describe directory structure."""
+    structure = {}
+    
+    common_dirs = {
+        'src': 'Source code',
+        'app': 'Next.js App Router pages',
+        'pages': 'Next.js Pages Router / Vue pages',
+        'components': 'React/Vue components',
+        'lib': 'Utility functions and helpers',
+        'utils': 'Utility functions',
+        'hooks': 'Custom React hooks',
+        'types': 'TypeScript type definitions',
+        'api': 'API routes',
+        'services': 'Business logic services',
+        'models': 'Database models',
+        'prisma': 'Prisma schema and migrations',
+        'public': 'Static assets',
+        'static': 'Static files',
+        'tests': 'Test files',
+        '__tests__': 'Jest test files',
+        'e2e': 'End-to-end tests',
+        'docs': 'Documentation',
+        'scripts': 'Build/utility scripts',
+        'config': 'Configuration files',
+    }
+    
+    for dir_name, description in common_dirs.items():
+        dir_path = project_root / dir_name
+        if dir_path.exists() and dir_path.is_dir():
+            structure[dir_name] = description
+    
+    return structure
+
+
+def detect_commands(project_root: Path) -> Dict[str, str]:
+    """Detect available npm/python commands."""
+    commands = {}
+    
+    package_json = project_root / 'package.json'
+    if package_json.exists():
+        try:
+            pkg = json.loads(package_json.read_text())
+            scripts = pkg.get('scripts', {})
+            
+            # Map common scripts
+            script_descriptions = {
+                'dev': 'Start development server',
+                'start': 'Start production server',
+                'build': 'Build for production',
+                'test': 'Run tests',
+                'lint': 'Run linter',
+                'format': 'Format code',
+                'db:push': 'Push database schema',
+                'db:migrate': 'Run database migrations',
+                'db:studio': 'Open database studio',
+            }
+            
+            for script, cmd in scripts.items():
+                desc = script_descriptions.get(script, cmd[:50])
+                commands[f'npm run {script}'] = desc
+                
+        except json.JSONDecodeError:
+            pass
+    
+    # Python commands
+    if (project_root / 'manage.py').exists():
+        commands['python manage.py runserver'] = 'Start Django server'
+        commands['python manage.py migrate'] = 'Run migrations'
+    
+    if (project_root / 'pyproject.toml').exists():
+        commands['pytest'] = 'Run tests'
+        commands['uvicorn main:app --reload'] = 'Start FastAPI server'
+    
+    return commands
+
+
+def generate_agents_md(
+    project_root: Path,
+    project_name: str,
+    stack: Dict,
+    structure: Dict[str, str],
+    commands: Dict[str, str]
+) -> str:
+    """Generate AGENTS.md content."""
+    
+    # Build tech stack table
+    stack_rows = []
+    layer_map = {
+        'frontend': 'Frontend',
+        'backend': 'Backend',
+        'database': 'Database',
+        'styling': 'Styling',
+        'testing': 'Testing',
+        'language': 'Language',
+    }
+    for key, layer in layer_map.items():
+        if stack.get(key):
+            stack_rows.append(f"| **{layer}** | {stack[key]} | - |")
+    
+    stack_table = '\n'.join(stack_rows) if stack_rows else "| - | - | - |"
+    
+    # Build directory map
+    dir_lines = []
+    for dir_name, desc in sorted(structure.items()):
+        dir_lines.append(f"│   ├── {dir_name}/{'':>15} # {desc}")
+    dir_map = '\n'.join(dir_lines) if dir_lines else "│   └── (empty project)"
+    
+    # Build commands table
+    cmd_rows = []
+    for cmd, desc in list(commands.items())[:10]:  # Limit to 10
+        cmd_rows.append(f"| `{cmd}` | {desc} |")
+    cmd_table = '\n'.join(cmd_rows) if cmd_rows else "| - | - |"
+    
+    return f"""# AGENTS.md
+
+> AI Navigation Map for **{project_name}**
+
+---
+
+## 📊 Project Pulse
+
+| Metric | Value |
+|--------|-------|
+| **Status** | 🟢 Active |
+| **Version** | 0.1.0 |
+| **Last Updated** | {datetime.now().strftime('%Y-%m-%d')} |
+| **Primary Language** | {stack.get('language', 'Unknown')} |
+
+---
+
+## 🛠️ Tech Stack
+
+| Layer | Technology | Notes |
+|-------|------------|-------|
+{stack_table}
+
+---
+
+## 📁 Directory Map
+
+```
+{project_name}/
+{dir_map}
+├── .agent/            # AI agent configuration
+└── AGENTS.md          # This file
+```
+
+### Critical Paths
+
+| Path | Purpose | ⚠️ Caution |
+|------|---------|------------|
+| `.env.local` | Environment secrets | Never commit |
+| `prisma/schema.prisma` | Database schema | Requires migration |
+
+### Off-Limits (Do Not Modify)
+
+- `node_modules/` - Dependencies
+- `.next/` / `dist/` / `build/` - Build artifacts
+- `__pycache__/` - Python cache
+
+---
+
+## 📜 Rules & Conventions
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase | `UserProfile.tsx` |
+| Hooks | camelCase with `use` prefix | `useAuth.ts` |
+| Utils | camelCase | `formatDate.ts` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
+
+### Code Style
+
+- **TypeScript Strict Mode** - No `any` types allowed
+- **Functional Components** - No class components
+- **Server-First** - Prefer Server Components when using Next.js
+
+---
+
+## 🔧 Commands Reference
+
+| Task | Command |
+|------|---------|
+{cmd_table}
+
+---
+
+## 🤖 AI Agent Instructions
+
+### When Modifying Code
+
+1. **Check Dependencies First** - Read `.agent/graph.json` for file relationships
+2. **Run Tests After Changes** - Verify with test command
+3. **Update Types** - If changing data structures, update type definitions
+
+### When Creating New Features
+
+1. Follow existing folder structure patterns
+2. Create component in appropriate directory
+3. Add types to designated types folder
+4. Write tests mirroring source path
+
+### MCP Servers Available
+
+| Server | Purpose | When to Use |
+|--------|---------|-------------|
+| `filesystem` | Read/write project files | File operations |
+
+---
+
+## 📈 Current Focus
+
+> Update this section to guide AI on current priorities
+
+- [ ] Initial project setup
+- [ ] Core feature implementation
+- [ ] Testing and documentation
+
+---
+
+*Generated by Agent Kit on {datetime.now().strftime('%Y-%m-%d %H:%M')}*
+"""
+
+
+def setup_agent_directory(project_root: Path):
+    """Create .agent directory structure."""
+    agent_dir = project_root / '.agent'
+    rag_dir = agent_dir / 'rag'
+    
+    # Create directories
+    agent_dir.mkdir(exist_ok=True)
+    rag_dir.mkdir(exist_ok=True)
+    
+    # Create .gitkeep for rag directory
+    (rag_dir / '.gitkeep').touch()
+    
+    # Create RAG readme
+    rag_readme = """# RAG Data Directory
+
+This directory stores RAG (Retrieval-Augmented Generation) data for AI assistance.
+
+## Files
+
+- `chunks.json` - Code chunks with metadata (generated by `chunk_code.py`)
+- `embeddings.npy` - Vector embeddings (optional, for local vector DB)
+
+## Generate Chunks
+
+```bash
+python .agent/skills/rag-engineering/scripts/chunk_code.py \\
+  --src ./src \\
+  --output .agent/rag/chunks.json
+```
+
+## Note
+
+These files are typically gitignored as they can be regenerated.
+Add to `.gitignore`:
+```
+.agent/rag/chunks.json
+.agent/rag/embeddings.npy
+```
+"""
+    (rag_dir / 'README.md').write_text(rag_readme)
+    
+    return agent_dir
+
+
+def run_graph_mapper(project_root: Path, agent_dir: Path) -> bool:
+    """Run graph-mapper script if source exists."""
+    src_dir = project_root / 'src'
+    app_dir = project_root / 'app'
+    
+    # Determine source directory
+    if src_dir.exists():
+        source = src_dir
+    elif app_dir.exists():
+        source = app_dir
+    else:
+        print("No src/ or app/ directory found, skipping graph generation")
+        return False
+    
+    # Check if graph-mapper script exists
+    script_path = Path(__file__).parent.parent / 'graph-mapper' / 'scripts' / 'generate_graph.py'
+    
+    if not script_path.exists():
+        print(f"Graph mapper script not found at {script_path}")
+        return False
+    
+    try:
+        result = subprocess.run(
+            [
+                'python', str(script_path),
+                '--src', str(source),
+                '--output', str(agent_dir / 'graph.json'),
+                '--format', 'both'
+            ],
+            capture_output=True,
+            text=True,
+            cwd=str(project_root)
+        )
+        
+        if result.returncode == 0:
+            print("✅ Dependency graph generated")
+            return True
+        else:
+            print(f"⚠️ Graph generation warning: {result.stderr}")
+            return False
+            
+    except Exception as e:
+        print(f"⚠️ Could not run graph mapper: {e}")
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate AI infrastructure for project')
+    parser.add_argument('--project-root', default='.', help='Project root directory')
+    parser.add_argument('--name', help='Project name (auto-detected if not provided)')
+    parser.add_argument('--skip-graph', action='store_true', help='Skip graph generation')
+    
+    args = parser.parse_args()
+    
+    project_root = Path(args.project_root).resolve()
+    
+    if not project_root.exists():
+        print(f"Error: Project root '{project_root}' does not exist")
+        return 1
+    
+    # Detect project name
+    project_name = args.name
+    if not project_name:
+        package_json = project_root / 'package.json'
+        if package_json.exists():
+            try:
+                pkg = json.loads(package_json.read_text())
+                project_name = pkg.get('name', project_root.name)
+            except:
+                project_name = project_root.name
+        else:
+            project_name = project_root.name
+    
+    print(f"🚀 Generating AI infrastructure for: {project_name}")
+    print(f"   Project root: {project_root}")
+    
+    # Step 1: Detect tech stack
+    print("\n📦 Detecting tech stack...")
+    stack = detect_tech_stack(project_root)
+    for key, value in stack.items():
+        if value:
+            print(f"   {key}: {value}")
+    
+    # Step 2: Detect directory structure
+    print("\n📁 Analyzing directory structure...")
+    structure = detect_directory_structure(project_root)
+    print(f"   Found {len(structure)} directories")
+    
+    # Step 3: Detect commands
+    print("\n🔧 Detecting available commands...")
+    commands = detect_commands(project_root)
+    print(f"   Found {len(commands)} commands")
+    
+    # Step 4: Setup .agent directory
+    print("\n📂 Setting up .agent directory...")
+    agent_dir = setup_agent_directory(project_root)
+    print(f"   Created: {agent_dir}")
+    
+    # Step 5: Generate AGENTS.md
+    print("\n📝 Generating AGENTS.md...")
+    agents_md = generate_agents_md(project_root, project_name, stack, structure, commands)
+    agents_path = project_root / 'AGENTS.md'
+    agents_path.write_text(agents_md)
+    print(f"   Created: {agents_path}")
+    
+    # Step 6: Generate dependency graph
+    if not args.skip_graph:
+        print("\n🔗 Generating dependency graph...")
+        run_graph_mapper(project_root, agent_dir)
+    
+    print("\n✅ AI Infrastructure setup complete!")
+    print("\nGenerated files:")
+    print(f"   - {project_root}/AGENTS.md")
+    print(f"   - {agent_dir}/")
+    if (agent_dir / 'graph.json').exists():
+        print(f"   - {agent_dir}/graph.json")
+        print(f"   - {agent_dir}/graph.md")
+    
+    return 0
+
+
+if __name__ == '__main__':
+    exit(main())

package/.agent/skills/documentation-templates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation-templates
-description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
+description: Documentation templates and structure guidelines. README, API docs, code comments, AGENTS.md for AI navigation, and AI-friendly documentation.
 allowed-tools: Read, Glob, Grep
 ---
 
@@ -10,6 +10,14 @@ allowed-tools: Read, Glob, Grep
 
 ---
 
+## 🔧 Quick Reference
+
+| File | Purpose |
+|------|---------|
+| [agents-template.md](agents-template.md) | AGENTS.md - AI Navigation Map (Layer 1) |
+
+---
+
 ## 1. README Structure
 
 ### Essential Sections (Priority Order)