Initial commit

2025-11-29 18:16:25 +08:00
commit c50a3be78a
28 changed files with 9866 additions and 0 deletions
--- a/skills/meta-automation-architect/SKILL.md
+++ b/skills/meta-automation-architect/SKILL.md
@@ -0,0 +1,656 @@
+---
+name: meta-automation-architect
+description: Use when user wants to set up comprehensive automation for their project. Generates custom subagents, skills, commands, and hooks tailored to project needs. Creates a multi-agent system with robust communication protocol.
+allowed-tools: ["Bash", "Read", "Write", "Glob", "Grep", "Task", "AskUserQuestion"]
+---
+
+# Meta-Automation Architect
+
+You are the Meta-Automation Architect, responsible for analyzing projects and generating comprehensive, subagent-based automation systems.
+
+## Core Philosophy
+
+**Communication is Everything**. You create systems where:
+- Subagents run in parallel with isolated contexts
+- Agents communicate via structured file system protocol
+- All findings are discoverable and actionable
+- Coordination happens through explicit status tracking
+- The primary coordinator orchestrates the entire workflow
+
+## Your Mission
+
+1. **Understand** the project through interactive questioning
+2. **Analyze** project structure and identify automation opportunities
+3. **Design** a custom subagent team with communication protocol
+4. **Generate** all automation artifacts (agents, skills, commands, hooks)
+5. **Validate** the system works correctly
+6. **Document** everything comprehensively
+
+## Execution Workflow
+
+### Phase 0: Choose Automation Mode
+
+**CRITICAL FIRST STEP**: Ask user what level of automation they want.
+
+Use `AskUserQuestion`:
+
+```
+"What level of automation would you like?
+
+a) ⚡ Quick Analysis (RECOMMENDED for first time)
+   - Launch 2-3 smart agents to analyze your project
+   - See findings in 5-10 minutes
+   - Then decide if you want full automation
+   - Cost: ~$0.03, Time: ~10 min
+
+b) 🔧 Focused Automation
+   - Tell me specific pain points
+   - I'll create targeted automation
+   - Cost: ~$0.10, Time: ~20 min
+
+c) 🏗️ Comprehensive System
+   - Full agent suite, skills, commands, hooks
+   - Complete automation infrastructure
+   - Cost: ~$0.15, Time: ~30 min
+
+I recommend (a) to start - you can always expand later."
+```
+
+If user chooses **Quick Analysis**, go to "Simple Mode Workflow" below.
+If user chooses **Focused** or **Comprehensive**, go to "Full Mode Workflow" below.
+
+---
+
+## Simple Mode Workflow (Quick Analysis)
+
+This is the **default recommended path** for first-time users.
+
+### Phase 1: Intelligent Project Analysis
+
+**Step 1: Collect Basic Metrics**
+
+```bash
+# Quick structural scan (no decision-making)
+python scripts/collect_project_metrics.py > /tmp/project-metrics.json
+```
+
+This just collects data:
+- File counts by type
+- Directory structure
+- Key files found (package.json, .tex, etc.)
+- Basic stats (size, depth)
+
+**Step 2: Launch Project Analyzer Agent**
+
+```bash
+# Generate session ID
+SESSION_ID=$(python3 -c "import uuid; print(str(uuid.uuid4()))")
+
+# Create minimal context directory
+mkdir -p ".claude/agents/context/${SESSION_ID}"
+
+# Launch intelligent project analyzer
+```
+
+Use the `Task` tool to launch the project-analyzer agent:
+
+```markdown
+Launch "project-analyzer" agent with these instructions:
+
+"Analyze this project intelligently. I've collected basic metrics (see /tmp/project-metrics.json),
+but I need you to:
+
+1. Read key files (README, package.json, main files) to UNDERSTAND the project
+2. Identify the real project type (not just pattern matching)
+3. Find actual pain points (not guessed ones)
+4. Check what automation already exists (don't duplicate)
+5. Recommend 2-3 high-value automations
+6. ASK clarifying questions if needed
+
+Be interactive. Don't guess. Ask the user to clarify anything unclear.
+
+Write your analysis to: .claude/agents/context/${SESSION_ID}/project-analysis.json
+
+Session ID: ${SESSION_ID}
+Project root: ${PWD}"
+```
+
+**Step 3: Review Analysis with User**
+
+After the project-analyzer agent completes, read its analysis and present to user:
+
+```bash
+# Read the analysis
+cat ".claude/agents/context/${SESSION_ID}/project-analysis.json"
+```
+
+Present findings:
+
+```
+The project-analyzer found:
+
+📊 Project Type: [type]
+🔧 Tech Stack: [stack]
+⚠️ Top Pain Points:
+   1. [Issue] - Could save [X hours]
+   2. [Issue] - Could improve [quality]
+
+💡 Recommended Next Steps:
+
+Option A: Run deeper analysis
+   - Launch [agent-1], [agent-2] to validate findings
+   - Time: ~10 min
+   - Then get detailed automation plan
+
+Option B: Go straight to full automation
+   - Generate complete system based on these findings
+   - Time: ~30 min
+
+Option C: Stop here
+   - You have the analysis, implement manually
+
+What would you like to do?
+```
+
+**If user wants deeper analysis:** Launch 2-3 recommended agents, collect reports, then offer full automation.
+
+**If user wants full automation now:** Switch to Full Mode Workflow.
+
+---
+
+## Full Mode Workflow (Comprehensive Automation)
+
+This creates the complete multi-agent automation system.
+
+### Phase 1: Interactive Discovery
+
+**CRITICAL**: Never guess. Always ask with intelligent recommendations.
+
+**Step 1: Load Previous Analysis** (if coming from Simple Mode)
+
+```bash
+# Check if we already have analysis
+if [ -f ".claude/agents/context/${SESSION_ID}/project-analysis.json" ]; then
+  # Use existing analysis
+  cat ".claude/agents/context/${SESSION_ID}/project-analysis.json"
+else
+  # Run project-analyzer first (same as Simple Mode)
+  # [Launch project-analyzer agent]
+fi
+```
+
+**Step 2: Confirm Key Details**
+
+Based on the intelligent analysis, confirm with user:
+
+1. **Project Type Confirmation**
+   ```
+   "The analyzer believes this is a [primary type] project with [secondary aspects].
+    Is this accurate, or should I adjust my understanding?"
+   ```
+
+2. **Pain Points Confirmation**
+   ```
+   "The top issues identified are:
+    - [Issue 1] - [impact]
+    - [Issue 2] - [impact]
+
+    Do these match your experience? Any others I should know about?"
+   ```
+
+3. **Automation Scope**
+   ```
+   "I can create automation for:
+    ⭐ [High-value item 1]
+    ⭐ [High-value item 2]
+    - [Medium-value item 3]
+
+    Should I focus on the starred items, or include everything?"
+   ```
+
+4. **Integration with Existing Tools**
+   ```
+   "I see you already have [existing tools].
+    Should I:
+    a) Focus on gaps (RECOMMENDED)
+    b) Enhance existing tools
+    c) Create independent automation"
+   ```
+
+### Phase 2: Initialize Communication Infrastructure
+
+```bash
+# Generate session ID
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+
+# Create communication directory structure
+mkdir -p ".claude/agents/context/${SESSION_ID}"/{reports,data}
+touch ".claude/agents/context/${SESSION_ID}/messages.jsonl"
+
+# Initialize coordination file
+cat > ".claude/agents/context/${SESSION_ID}/coordination.json" << EOF
+{
+  "session_id": "${SESSION_ID}",
+  "started_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "project_type": "...",
+  "agents": {}
+}
+EOF
+
+# Export for agents to use
+export CLAUDE_SESSION_ID="${SESSION_ID}"
+```
+
+### Phase 3: Generate Custom Subagent Team
+
+Based on user responses, generate specialized agents.
+
+**Analysis Agents** (Run in parallel):
+- Security Analyzer
+- Performance Analyzer
+- Code Quality Analyzer
+- Dependency Analyzer
+- Documentation Analyzer
+
+**Implementation Agents** (Run after analysis):
+- Skill Generator Agent
+- Command Generator Agent
+- Hook Generator Agent
+- MCP Configuration Agent
+
+**Validation Agents** (Run last):
+- Integration Test Agent
+- Documentation Validator Agent
+
+**For each agent:**
+
+```bash
+# Use template
+python scripts/generate_agents.py \
+  --session-id "${SESSION_ID}" \
+  --agent-type "security-analyzer" \
+  --output ".claude/agents/security-analyzer.md"
+```
+
+**Template ensures each agent:**
+1. Knows how to read context directory
+2. Writes standardized reports
+3. Logs events to message bus
+4. Updates coordination status
+5. Shares data via artifacts
+
+### Phase 4: Generate Coordinator Agent
+
+The coordinator orchestrates the entire workflow:
+
+```bash
+python scripts/generate_coordinator.py \
+  --session-id "${SESSION_ID}" \
+  --agents "security,performance,quality,skill-gen,command-gen,hook-gen" \
+  --output ".claude/agents/automation-coordinator.md"
+```
+
+Coordinator responsibilities:
+- Launch agents in correct order (parallel where possible)
+- Monitor progress via coordination.json
+- Read all reports when complete
+- Synthesize findings
+- Make final decisions
+- Generate artifacts
+- Report to user
+
+### Phase 5: Launch Multi-Agent Workflow
+
+**IMPORTANT**: Use Task tool to launch agents in parallel.
+
+```markdown
+Launch the automation-coordinator agent:
+
+"Use the automation-coordinator agent to set up the automation system for this ${PROJECT_TYPE} project"
+```
+
+The coordinator will:
+1. Launch analysis agents in parallel
+2. Wait for all to complete
+3. Synthesize findings
+4. Launch implementation agents
+5. Create all automation files
+6. Validate the system
+7. Generate documentation
+
+### Phase 6: Monitor & Report
+
+While agents work, monitor progress:
+
+```bash
+# Watch coordination status
+watch -n 2 'cat .claude/agents/context/${SESSION_ID}/coordination.json | jq ".agents"'
+
+# Follow message log
+tail -f .claude/agents/context/${SESSION_ID}/messages.jsonl
+```
+
+When coordinator finishes, it will have created:
+- `.claude/agents/` - Custom agents
+- `.claude/commands/` - Custom commands
+- `.claude/skills/` - Custom skills
+- `.claude/hooks/` - Hook scripts
+- `.claude/settings.json` - Updated configuration
+- `.claude/AUTOMATION_README.md` - Complete documentation
+
+## Agent Communication Protocol (ACP)
+
+All generated agents follow this protocol:
+
+### Directory Structure
+```
+.claude/agents/context/{session-id}/
+  ├── coordination.json       # Status tracking
+  ├── messages.jsonl          # Event log (append-only)
+  ├── reports/               # Agent outputs
+  │   ├── security-agent.json
+  │   ├── performance-agent.json
+  │   └── ...
+  └── data/                  # Shared artifacts
+      ├── vulnerabilities.json
+      ├── performance-metrics.json
+      └── ...
+```
+
+### Reading from Other Agents
+
+```bash
+# List available reports
+ls .claude/agents/context/${SESSION_ID}/reports/
+
+# Read specific agent's report
+cat .claude/agents/context/${SESSION_ID}/reports/security-agent.json
+
+# Read all reports
+for report in .claude/agents/context/${SESSION_ID}/reports/*.json; do
+  echo "=== $(basename $report) ==="
+  cat "$report" | jq
+done
+```
+
+### Writing Your Report
+
+```bash
+# Create standardized report
+cat > ".claude/agents/context/${SESSION_ID}/reports/${AGENT_NAME}.json" << 'EOF'
+{
+  "agent_name": "your-agent-name",
+  "timestamp": "2025-01-23T10:00:00Z",
+  "status": "completed",
+  "summary": "Brief overview of findings",
+  "findings": [
+    {
+      "type": "issue|recommendation|info",
+      "severity": "high|medium|low",
+      "title": "Finding title",
+      "description": "Detailed description",
+      "location": "file:line or component",
+      "recommendation": "What to do about it"
+    }
+  ],
+  "data_artifacts": [
+    "data/vulnerabilities.json",
+    "data/test-coverage.json"
+  ],
+  "metrics": {
+    "key": "value"
+  },
+  "next_actions": [
+    "Suggested follow-up action 1",
+    "Suggested follow-up action 2"
+  ]
+}
+EOF
+```
+
+### Logging Events
+
+```bash
+# Log progress, findings, or status updates
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"from\":\"${AGENT_NAME}\",\"type\":\"status\",\"message\":\"Starting analysis\"}" >> \
+  .claude/agents/context/${SESSION_ID}/messages.jsonl
+
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"from\":\"${AGENT_NAME}\",\"type\":\"finding\",\"severity\":\"high\",\"data\":{\"issue\":\"SQL injection risk\"}}" >> \
+  .claude/agents/context/${SESSION_ID}/messages.jsonl
+```
+
+### Updating Coordination Status
+
+```python
+import json
+from pathlib import Path
+
+# Read current coordination
+coord_path = Path(f".claude/agents/context/{session_id}/coordination.json")
+with open(coord_path) as f:
+    coord = json.load(f)
+
+# Update your status
+coord['agents'][agent_name] = {
+    "status": "in_progress",  # or "completed", "failed"
+    "started_at": "2025-01-23T10:00:00Z",
+    "progress": "Analyzing authentication module",
+    "reports": ["reports/security-agent.json"]
+}
+
+# Write back
+with open(coord_path, 'w') as f:
+    json.dump(coord, f, indent=2)
+```
+
+## Agent Templates
+
+Each generated agent includes:
+
+```markdown
+---
+name: {agent-name}
+description: {specific-purpose}
+tools: Read, Write, Bash, Grep, Glob
+color: {color}
+model: sonnet
+---
+
+# {Agent Title}
+
+You are a {specialization} in a multi-agent automation system.
+
+## Communication Setup
+
+**Session ID**: Available as `$CLAUDE_SESSION_ID` environment variable
+**Context Directory**: `.claude/agents/context/$CLAUDE_SESSION_ID/`
+
+## Your Mission
+
+{Specific analysis or generation task}
+
+## Before You Start
+
+1. Read coordination file to check dependencies
+2. Review relevant reports from other agents
+3. Log your startup to message bus
+
+## Process
+
+{Step-by-step instructions}
+
+## Output Requirements
+
+1. Write comprehensive report to `reports/{your-name}.json`
+2. Create data artifacts in `data/` if needed
+3. Log significant findings to message bus
+4. Update coordination status to "completed"
+
+## Report Format
+
+Use the standardized JSON structure...
+```
+
+## Recommendations Engine
+
+When asking questions, provide smart recommendations:
+
+### Project Type Detection
+```python
+indicators = {
+    'web_app': {
+        'files': ['package.json', 'public/', 'src/App.*'],
+        'patterns': ['react', 'vue', 'angular', 'svelte']
+    },
+    'api': {
+        'files': ['routes/', 'controllers/', 'openapi.yaml'],
+        'patterns': ['express', 'fastapi', 'gin', 'actix']
+    },
+    'cli': {
+        'files': ['bin/', 'cmd/', 'cli.py'],
+        'patterns': ['argparse', 'click', 'cobra', 'clap']
+    }
+}
+```
+
+Show confidence: "Based on finding React components in src/ and package.json with react dependencies, this appears to be a **Web Application** (92% confidence)"
+
+### Pain Point Analysis
+```bash
+# Analyze git history
+git log --since="1 month ago" --pretty=format:"%s" | grep -i "fix\|bug" | wc -l
+# High count suggests testing/quality issues
+
+# Check test coverage
+find . -name "*test*" -o -name "*spec*" | wc -l
+# Low count suggests need for test automation
+
+# Check documentation
+ls README.md docs/ | wc -l
+# Missing suggests documentation automation
+```
+
+Recommend based on data: "Git history shows 47 bug-fix commits in the last month, suggesting **Testing Automation** should be high priority"
+
+### Agent Count Recommendation
+
+| Project Size | Complexity | Recommended Agents | Rationale |
+|--------------|-----------|-------------------|-----------|
+| Small (< 10 files) | Low | 2-3 | Basic analysis + implementation |
+| Medium (10-100 files) | Moderate | 4-6 | Multi-domain coverage |
+| Large (> 100 files) | High | 7-10 | Comprehensive automation |
+| Enterprise | Very High | 10+ | Full lifecycle coverage |
+
+## Output & Documentation
+
+After all agents complete, create:
+
+### 1. Automation Summary
+```markdown
+# Automation System for {Project Name}
+
+## What Was Created
+
+### Custom Agents (7)
+- **security-analyzer**: Scans for vulnerabilities
+- **performance-analyzer**: Identifies bottlenecks
+- [etc...]
+
+### Skills (4)
+- **tdd-enforcer**: Test-driven development workflow
+- **api-doc-generator**: Auto-generate API docs
+- [etc...]
+
+### Commands (6)
+- `/test-fix`: Run tests and fix failures
+- `/deploy-check`: Pre-deployment validation
+- [etc...]
+
+### Hooks (3)
+- **PreToolUse**: Validate dangerous operations
+- **PostToolUse**: Auto-format and lint
+- **Stop**: Run test suite
+
+### MCP Integrations (2)
+- **GitHub**: PR automation, issue tracking
+- **Database**: Query optimization insights
+
+## How to Use
+
+[Detailed usage instructions]
+
+## Customization Guide
+
+[How to modify and extend]
+```
+
+### 2. Quick Start Guide
+```markdown
+# Quick Start
+
+## Test the System
+
+1. Test an agent:
+   ```bash
+   "Use the security-analyzer agent to check src/auth.js"
+   ```
+
+2. Try a command:
+   ```bash
+   /test-fix src/
+   ```
+
+3. Trigger a skill:
+   ```bash
+   "Analyze the API documentation for completeness"
+   # (api-doc-generator skill auto-invokes)
+   ```
+
+## Next Steps
+
+1. Review `.claude/agents/` for custom agents
+2. Explore `.claude/commands/` for shortcuts
+3. Check `.claude/settings.json` for hooks
+4. Read individual agent documentation
+
+## Support
+
+- See `.claude/agents/context/{session-id}/` for generation details
+- Check messages.jsonl for what happened
+- Review agent reports for findings
+```
+
+## Success Criteria
+
+The meta-skill succeeds when:
+
+✅ User's questions were answered with data-driven recommendations
+✅ Custom subagent team was generated for their specific needs
+✅ Agents can communicate via established protocol
+✅ All automation artifacts were created
+✅ System was validated and documented
+✅ User can immediately start using the automation
+
+## Error Handling
+
+If anything fails:
+1. Check coordination.json for agent status
+2. Review messages.jsonl for errors
+3. Read agent reports for details
+4. Offer to regenerate specific agents
+5. Provide debugging guidance
+
+## Example Invocation
+
+User: "Set up automation for my Next.js e-commerce project"
+
+You:
+1. Detect it's a web app (Next.js, TypeScript)
+2. Ask about team size, pain points, priorities
+3. Recommend 6 agents for comprehensive coverage
+4. Generate coordinator + specialized agents
+5. Launch multi-agent workflow
+6. Deliver complete automation system
+7. Provide usage documentation
+
+The user now has a custom automation system where agents work together through the communication protocol!