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/README.md
+++ b/skills/meta-automation-architect/README.md
@@ -0,0 +1,397 @@
+# Meta-Automation Architect
+
+A meta-skill that analyzes your project and generates a comprehensive automation system with custom subagents, skills, commands, and hooks.
+
+## What It Creates
+
+The meta-skill generates:
+
+1. **Custom Subagents** - Specialized analysis and implementation agents that run in parallel
+2. **Skills** - Auto-invoked capabilities for common patterns in your project
+3. **Commands** - Slash commands for frequent workflows
+4. **Hooks** - Event-driven automation at lifecycle points
+5. **MCP Configurations** - External service integrations
+6. **Complete Documentation** - Usage guides and quick references
+
+## How to Use
+
+### Basic Invocation
+
+Simply describe what you want:
+
+```
+"Set up automation for my project"
+```
+
+Or be more specific:
+
+```
+"Create comprehensive automation for my Next.js e-commerce project"
+```
+
+```
+"Generate a custom automation system for my Python data science workflow"
+```
+
+### What Happens
+
+1. **Interactive Discovery** - You'll be asked questions about:
+   - Project type (with smart detection and recommendations)
+   - Tech stack and frameworks
+   - Team size and workflow
+   - Pain points and priorities
+   - Desired automation scope
+
+2. **Smart Recommendations** - Every question includes:
+   - Data-driven analysis of your project
+   - Confidence scores and reasoning
+   - Recommended options based on evidence
+   - Clear trade-offs and explanations
+
+3. **Multi-Agent Generation** - The system creates:
+   - A coordinator agent that orchestrates everything
+   - Specialized analysis agents (security, performance, quality, etc.)
+   - Implementation agents (skill/command/hook generators)
+   - Validation agents (testing and documentation)
+
+4. **Parallel Execution** - Agents run concurrently and communicate via the Agent Communication Protocol (ACP)
+
+5. **Complete Delivery** - You receive:
+   - All automation artifacts
+   - Comprehensive documentation
+   - Usage examples
+   - Customization guides
+
+## Example Sessions
+
+### Web Application Project
+
+```
+User: "Set up automation for my React TypeScript project"
+
+Meta-Skill:
+1. Detects: Web application (95% confidence)
+   - Found package.json with React dependencies
+   - Found src/App.tsx and TypeScript config
+   - Detected testing with Jest and React Testing Library
+
+2. Asks: "What are your main pain points?"
+   - Recommends: Testing automation (detected low test coverage)
+   - Recommends: Code quality checks (found 47 bug-fix commits recently)
+
+3. Recommends: 6 agents for comprehensive coverage
+   - Analysis: Security, Performance, Code Quality, Dependencies
+   - Implementation: Skill Generator, Command Generator
+   - Validation: Integration Tester
+
+4. Generates automation system with:
+   - /test-fix command for TDD workflow
+   - PostToolUse hook for auto-formatting
+   - GitHub MCP integration for PR automation
+   - Custom skills for common React patterns
+```
+
+### Python Data Science Project
+
+```
+User: "Create automation for my machine learning project"
+
+Meta-Skill:
+1. Detects: Data Science (88% confidence)
+   - Found notebooks/ directory with 15 .ipynb files
+   - Found requirements.txt with pandas, scikit-learn, tensorflow
+   - Found data/ and models/ directories
+
+2. Asks: "What would you like to automate first?"
+   - Recommends: Experiment tracking (detected many model versions)
+   - Recommends: Documentation generation (missing architecture docs)
+   - Recommends: Data validation (found data pipeline code)
+
+3. Generates automation system with:
+   - /run-experiment command for standardized ML runs
+   - Custom skill for model comparison and analysis
+   - Hooks for auto-documenting experiments
+   - MCP integration for MLflow or Weights & Biases
+```
+
+## Agent Communication Protocol (ACP)
+
+The generated subagents communicate via a file-based protocol:
+
+### Directory Structure
+
+```
+.claude/agents/context/{session-id}/
+  ├── coordination.json       # Tracks agent status and dependencies
+  ├── messages.jsonl          # Append-only event log
+  ├── reports/               # Standardized agent outputs
+  │   ├── security-analyzer.json
+  │   ├── performance-analyzer.json
+  │   └── ...
+  └── data/                  # Shared data artifacts
+      ├── vulnerabilities.json
+      ├── performance-metrics.json
+      └── ...
+```
+
+### How Agents Communicate
+
+1. **Check Dependencies** - Read `coordination.json` to see which agents have completed
+2. **Read Context** - Review reports from other agents
+3. **Log Progress** - Write events to `messages.jsonl`
+4. **Share Findings** - Create standardized report in `reports/`
+5. **Share Data** - Store detailed artifacts in `data/`
+6. **Update Status** - Mark completion in `coordination.json`
+
+### Report Format
+
+Every agent writes a standardized JSON report:
+
+```json
+{
+  "agent_name": "security-analyzer",
+  "timestamp": "2025-01-23T10:00:00Z",
+  "status": "completed",
+  "summary": "Found 5 security vulnerabilities requiring immediate attention",
+  "findings": [
+    {
+      "type": "issue",
+      "severity": "high",
+      "title": "SQL Injection Risk",
+      "description": "User input not sanitized in query builder",
+      "location": "src/db/queries.ts:42",
+      "recommendation": "Use parameterized queries",
+      "example": "db.query('SELECT * FROM users WHERE id = ?', [userId])"
+    }
+  ],
+  "metrics": {
+    "items_analyzed": 150,
+    "issues_found": 5,
+    "time_taken": "2m 34s"
+  },
+  "recommendations_for_automation": [
+    "Skill: SQL injection checker",
+    "Hook: Validate queries on PreToolUse",
+    "Command: /security-scan for quick checks"
+  ]
+}
+```
+
+## What Gets Generated
+
+### 1. Custom Subagents
+
+Specialized agents tailored to your project:
+
+- **Analysis Agents** - Security, performance, code quality, dependencies, documentation
+- **Implementation Agents** - Generate skills, commands, hooks, MCP configs
+- **Validation Agents** - Test integration, validate documentation
+
+Each agent:
+- Has communication protocol built-in
+- Knows how to coordinate with others
+- Writes standardized reports
+- Suggests automation opportunities
+
+### 2. Skills
+
+Auto-invoked capabilities for your specific patterns:
+
+```
+.claude/skills/
+  ├── api-doc-generator/        # Generate API docs from code
+  ├── tdd-enforcer/             # Test-driven development workflow
+  ├── security-checker/         # Quick security validation
+  └── ...
+```
+
+### 3. Commands
+
+Slash commands for frequent tasks:
+
+```
+.claude/commands/
+  ├── test-fix.md              # Run tests and fix failures
+  ├── deploy-check.md          # Pre-deployment validation
+  ├── security-scan.md         # Quick security audit
+  └── ...
+```
+
+### 4. Hooks
+
+Event-driven automation:
+
+```
+.claude/hooks/
+  ├── format_on_save.py        # PostToolUse: Auto-format code
+  ├── security_check.py        # PreToolUse: Validate operations
+  └── run_tests.py             # Stop: Execute test suite
+```
+
+### 5. Documentation
+
+Complete usage guides:
+
+- `.claude/AUTOMATION_README.md` - Main system documentation
+- `.claude/QUICK_REFERENCE.md` - Cheat sheet for all features
+- `.claude/agents/context/{session-id}/` - Generation session details
+
+## Monitoring the Generation Process
+
+While agents work, you can monitor progress:
+
+```bash
+# Watch agent status
+watch -n 2 'cat .claude/agents/context/*/coordination.json | jq ".agents"'
+
+# Follow live events
+tail -f .claude/agents/context/*/messages.jsonl | jq
+
+# Check completion
+cat .claude/agents/context/*/coordination.json | \
+  jq '.agents | to_entries | map(select(.value.status == "completed")) | map(.key)'
+```
+
+## Customizing Generated Automation
+
+All generated artifacts can be customized:
+
+### Modify Agents
+```bash
+# Edit agent behavior
+vim .claude/agents/security-analyzer.md
+
+# Adjust analysis focus, tools, or process
+```
+
+### Customize Skills
+```bash
+# Update skill behavior
+vim .claude/skills/api-doc-generator/SKILL.md
+
+# Modify when skill triggers or what it does
+```
+
+### Update Commands
+```bash
+# Change command behavior
+vim .claude/commands/test-fix.md
+
+# Adjust workflow or add arguments
+```
+
+### Adjust Hooks
+```bash
+# Modify hook logic
+vim .claude/hooks/format_on_save.py
+
+# Change trigger conditions or actions
+```
+
+## Troubleshooting
+
+### Agent Failed
+
+```bash
+# Check status
+jq '.agents | to_entries | map(select(.value.status == "failed"))' \
+  .claude/agents/context/{session-id}/coordination.json
+
+# Find error
+jq 'select(.from == "failed-agent") | select(.type == "error")' \
+  .claude/agents/context/{session-id}/messages.jsonl | tail -1
+
+# Options:
+# 1. Retry the agent
+# 2. Continue without it
+# 3. Manual intervention
+```
+
+### Missing Reports
+
+```bash
+# List generated reports
+ls .claude/agents/context/{session-id}/reports/
+
+# Check if agent completed
+jq '.agents["agent-name"]' \
+  .claude/agents/context/{session-id}/coordination.json
+```
+
+### Review What Happened
+
+```bash
+# Full event log
+cat .claude/agents/context/{session-id}/messages.jsonl | jq
+
+# Agent-specific events
+jq 'select(.from == "agent-name")' \
+  .claude/agents/context/{session-id}/messages.jsonl
+
+# Events by type
+jq -s 'group_by(.type) | map({type: .[0].type, count: length})' \
+  .claude/agents/context/{session-id}/messages.jsonl
+```
+
+## Advanced Usage
+
+### Specify Agent Count
+
+```
+"Create automation with 8 parallel agents for comprehensive coverage"
+```
+
+### Target Specific Areas
+
+```
+"Focus automation on security and testing"
+```
+
+### Prioritize Implementation
+
+```
+"Generate skills and commands first, hooks later"
+```
+
+### Re-run Analysis
+
+```bash
+# Generate new session with different configuration
+# Previous sessions remain in .claude/agents/context/
+```
+
+## Architecture
+
+The meta-skill uses a multi-phase architecture:
+
+1. **Discovery Phase** - Interactive questioning with recommendations
+2. **Setup Phase** - Initialize communication infrastructure
+3. **Analysis Phase** - Parallel agent execution for deep analysis
+4. **Synthesis Phase** - Coordinator reads all reports and makes decisions
+5. **Implementation Phase** - Parallel generation of automation artifacts
+6. **Validation Phase** - Sequential testing and documentation checks
+7. **Delivery Phase** - Complete documentation and user report
+
+## Benefits
+
+- **Parallel Execution** - Multiple agents work concurrently
+- **Isolated Contexts** - Each agent has focused responsibility
+- **Communication Protocol** - Agents share findings reliably
+- **Data-Driven** - Recommendations based on actual project analysis
+- **Comprehensive** - Covers security, performance, quality, testing, docs
+- **Customizable** - All generated artifacts can be modified
+- **Transparent** - Full event log shows what happened
+- **Reusable** - Generated automation works immediately
+
+## Support
+
+For issues or questions:
+
+1. Review agent reports in `reports/`
+2. Check message log in `messages.jsonl`
+3. Consult individual documentation
+4. Review session details in context directory
+
+---
+
+*Generated automation is project-specific but follows Claude Code best practices for skills, commands, hooks, and MCP integration.*