gh-comzine-claude-code-marketplace-meta-automation-architect/skills/meta-automation-architect/OVERVIEW.md

# Meta-Automation Architect - System Overview

A comprehensive skill that analyzes projects and generates tailored automation systems with parallel subagents, custom skills, commands, and hooks.

## Quick Links

- **[README.md](README.md)** - Main usage guide
- **[SKILL.md](SKILL.md)** - Full skill definition
- **[Communication Protocol](references/COMMUNICATION_PROTOCOL.md)** - Agent Communication Protocol (ACP) specification
- **[Examples](examples/)** - Complete examples for different project types
- **[Templates](templates/)** - Templates for generated artifacts

## Directory Structure

```
.claude/skills/meta-automation-architect/
├── SKILL.md                           # Main skill definition
├── README.md                          # Usage guide
├── OVERVIEW.md                        # This file
│
├── scripts/                           # Generation scripts
│   ├── detect_project.py              # Project analysis
│   ├── generate_agents.py             # Agent generation (11 templates)
│   └── generate_coordinator.py        # Coordinator generation
│
├── templates/                         # Output templates
│   ├── example-skill-template.md      # Skill template structure
│   ├── example-command-template.md    # Command template structure
│   └── example-hook-template.py       # Hook template structure
│
├── examples/                          # Complete examples
│   ├── EXAMPLE_WEB_APP.md            # Next.js web app automation
│   └── EXAMPLE_PYTHON_CLI.md         # Python CLI tool automation
│
└── references/                        # Technical docs
    └── COMMUNICATION_PROTOCOL.md      # ACP specification
```

## What This Meta-Skill Does

### 1. Interactive Discovery
- Analyzes project structure and tech stack
- Provides data-driven recommendations
- Asks targeted questions with smart defaults
- Never guesses - always validates with user

### 2. Generates Parallel Subagent System
- **Analysis Agents** - Run in parallel to analyze different domains
- **Implementation Agents** - Generate automation artifacts
- **Validation Agents** - Test and validate the system
- **Coordinator Agent** - Orchestrates the entire workflow

### 3. Creates Complete Automation
- **Custom Agents** - Specialized for project patterns
- **Skills** - Auto-invoked capabilities
- **Commands** - Slash commands for workflows
- **Hooks** - Event-driven automation
- **MCP Integrations** - External service connections

### 4. Enables Agent Communication
Uses **Agent Communication Protocol (ACP)** for coordination:
- File-based communication at `.claude/agents/context/{session-id}/`
- Coordination file for status tracking
- Message bus for event transparency
- Standardized reports for findings
- Data artifacts for detailed exchange

## Available Agent Templates

### Analysis Agents (Run in Parallel)
1. **security-analyzer** - Security vulnerabilities, auth flaws, secret exposure
2. **performance-analyzer** - Bottlenecks, inefficient algorithms, optimization opportunities
3. **code-quality-analyzer** - Code complexity, duplication, maintainability
4. **dependency-analyzer** - Outdated packages, vulnerabilities, conflicts
5. **documentation-analyzer** - Documentation completeness and quality

### Implementation Agents
6. **skill-generator** - Creates custom skills from findings
7. **command-generator** - Creates slash commands for workflows
8. **hook-generator** - Creates automation hooks
9. **mcp-configurator** - Configures external integrations

### Validation Agents
10. **integration-tester** - Validates all components work together
11. **documentation-validator** - Ensures comprehensive documentation

## Agent Communication Protocol (ACP)

### Core Concept
Parallel agents with isolated contexts communicate via structured files:

```
.claude/agents/context/{session-id}/
  ├── coordination.json       # Status tracking
  ├── messages.jsonl          # Event log (append-only)
  ├── reports/               # Agent outputs
  │   └── {agent-name}.json
  └── data/                  # Shared artifacts
```

### Key Features
- ✅ **Asynchronous** - Agents don't block each other
- ✅ **Discoverable** - Any agent can read any report
- ✅ **Persistent** - Survives crashes
- ✅ **Transparent** - Complete audit trail
- ✅ **Orchestratable** - Coordinator manages dependencies

See [COMMUNICATION_PROTOCOL.md](references/COMMUNICATION_PROTOCOL.md) for full specification.

## Usage Patterns

### Basic Invocation
```
"Set up automation for my project"
```

### Specific Project Type
```
"Create automation for my Next.js web app"
"Generate automation for my Python CLI tool"
"Set up automation for my data science workflow"
```

### With Priorities
```
"Focus automation on testing and security"
"Prioritize documentation and code quality"
```

### With Scope
```
"Create comprehensive automation with 8 agents"
"Generate basic automation (3-4 agents)"
```

## Example Output

For a typical web application, generates:

```
.claude/
├── agents/
│   ├── security-analyzer.md
│   ├── performance-analyzer.md
│   ├── code-quality-analyzer.md
│   ├── skill-generator.md
│   ├── command-generator.md
│   └── automation-coordinator.md
│
├── skills/
│   ├── tdd-workflow/
│   ├── api-doc-generator/
│   └── security-checker/
│
├── commands/
│   ├── test-fix.md
│   ├── security-scan.md
│   └── perf-check.md
│
├── hooks/
│   ├── security_validation.py
│   └── run_tests.py
│
├── settings.json (updated)
├── AUTOMATION_README.md
└── QUICK_REFERENCE.md
```

Plus complete session data:
```
.claude/agents/context/{session-id}/
├── coordination.json
├── messages.jsonl
├── reports/
│   ├── security-analyzer.json
│   ├── performance-analyzer.json
│   └── ...
└── data/
    └── ...
```

## Workflow Phases

### Phase 1: Discovery (Interactive)
- Project type detection with confidence scores
- Tech stack analysis
- Team size and workflow questions
- Pain point identification
- Priority setting
- Agent count recommendation

### Phase 2: Setup
- Generate unique session ID
- Create communication directory structure
- Initialize coordination file
- Export environment variables

### Phase 3: Analysis (Parallel)
- Launch analysis agents concurrently
- Each agent analyzes specific domain
- Agents log progress to message bus
- Generate standardized reports
- Update coordination status

### Phase 4: Synthesis
- Coordinator reads all reports
- Aggregates findings
- Identifies patterns
- Makes decisions on what to generate

### Phase 5: Implementation (Parallel)
- Launch implementation agents
- Generate skills, commands, hooks
- Configure MCP servers
- Create artifacts

### Phase 6: Validation (Sequential)
- Test all components
- Validate documentation
- Ensure everything works

### Phase 7: Delivery
- Generate documentation
- Create usage guides
- Report to user

## Key Scripts

### `detect_project.py`
```python
# Analyzes project to determine:
# - Project type (web app, CLI, data science, etc.)
# - Tech stack (frameworks, languages)
# - Pain points (testing, docs, dependencies)
# - Statistics (file counts, test coverage)

python scripts/detect_project.py
```

### `generate_agents.py`
```python
# Generates specialized agents with communication protocol
# Available types: security-analyzer, performance-analyzer, etc.

python scripts/generate_agents.py \
  --session-id "abc-123" \
  --agent-type "security-analyzer" \
  --output ".claude/agents/security-analyzer.md"
```

### `generate_coordinator.py`
```python
# Creates coordinator agent that orchestrates workflow

python scripts/generate_coordinator.py \
  --session-id "abc-123" \
  --agents "security,performance,quality" \
  --output ".claude/agents/coordinator.md"
```

## Benefits

### For Solo Developers
- Automates tedious documentation and testing
- Provides instant code quality feedback
- Reduces context switching
- Focuses on writing code, not boilerplate

### For Small Teams
- Standardizes workflows across team
- Ensures consistent code quality
- Automates code reviews
- Improves onboarding with documentation

### For Large Projects
- Comprehensive analysis across domains
- Identifies technical debt systematically
- Provides actionable recommendations
- Scales with multiple parallel agents

## Customization

All generated artifacts can be customized:

- **Agents** - Edit `.claude/agents/{agent-name}.md`
- **Skills** - Modify `.claude/skills/{skill-name}/SKILL.md`
- **Commands** - Update `.claude/commands/{command-name}.md`
- **Hooks** - Change `.claude/hooks/{hook-name}.py`
- **Settings** - Adjust `.claude/settings.json`

## Monitoring & Debugging

### Watch Agent Progress
```bash
watch -n 2 'cat .claude/agents/context/*/coordination.json | jq ".agents"'
```

### Follow Live Events
```bash
tail -f .claude/agents/context/*/messages.jsonl | jq
```

### Check Reports
```bash
ls .claude/agents/context/*/reports/
cat .claude/agents/context/*/reports/security-analyzer.json | jq
```

### Aggregate Findings
```bash
jq -s 'map(.findings[]) | map(select(.severity == "high"))' \
  .claude/agents/context/*/reports/*.json
```

## Best Practices

### When Invoking
1. Let the skill analyze your project first
2. Answer questions honestly
3. Use recommendations when unsure
4. Start with moderate agent count
5. Review generated automation

### After Generation
1. Read AUTOMATION_README.md
2. Try example invocations
3. Customize for your needs
4. Review session logs to understand decisions
5. Iterate based on usage

### For Maintenance
1. Review agent reports periodically
2. Update skills as patterns evolve
3. Add new commands for new workflows
4. Adjust hooks as needed
5. Keep documentation current

## Technical Details

### Requirements
- Python 3.8+
- Claude Code with Task tool support
- Write access to `.claude/` directory

### Dependencies
Scripts use only Python standard library:
- `json` - JSON parsing
- `subprocess` - Git analysis
- `pathlib` - File operations
- `argparse` - CLI parsing

### Performance
- Analysis phase: 3-5 minutes (parallel execution)
- Implementation phase: 2-3 minutes (parallel execution)
- Validation phase: 1-2 minutes (sequential)
- **Total: ~10-15 minutes** for complete automation system

### Scalability
- 2-3 agents: Basic projects, solo developers
- 4-6 agents: Medium projects, small teams
- 7-10 agents: Large projects, comprehensive coverage
- 10+ agents: Enterprise projects, all domains

## Examples

### Web Application (Next.js)
See [EXAMPLE_WEB_APP.md](examples/EXAMPLE_WEB_APP.md)
- 6 agents (4 analysis, 2 implementation)
- 3 skills (TDD workflow, API docs, security checker)
- 3 commands (test-fix, security-scan, perf-check)
- 2 hooks (security validation, run tests)
- GitHub MCP integration

### Python CLI Tool
See [EXAMPLE_PYTHON_CLI.md](examples/EXAMPLE_PYTHON_CLI.md)
- 4 agents (2 analysis, 2 implementation)
- 2 skills (docstring generator, CLI test helper)
- 2 commands (test-cov, release-prep)
- 1 hook (auto-lint Python)
- Focused on documentation and testing

## Related Claude Code Features

This meta-skill leverages:
- **Task Tool** - For parallel agent execution
- **Skills System** - Creates auto-invoked capabilities
- **Commands** - Creates user-invoked shortcuts
- **Hooks** - Enables event-driven automation
- **MCP** - Connects to external services

## Support & Troubleshooting

### Check Session Logs
```bash
# Review what happened
cat .claude/agents/context/{session-id}/messages.jsonl | jq

# Find errors
jq 'select(.type == "error")' .claude/agents/context/{session-id}/messages.jsonl
```

### Agent Failed
```bash
# Check status
jq '.agents | to_entries | map(select(.value.status == "failed"))' \
  .claude/agents/context/{session-id}/coordination.json

# Options:
# 1. Retry the agent
# 2. Continue without it
# 3. Manual intervention
```

### Missing Reports
```bash
# List what was generated
ls .claude/agents/context/{session-id}/reports/

# Check if agent completed
jq '.agents["agent-name"]' \
  .claude/agents/context/{session-id}/coordination.json
```

## Future Enhancements

Potential additions:
- Language-specific analyzers (Go, Rust, Java)
- CI/CD integration agents
- Database optimization agent
- API design analyzer
- Accessibility checker
- Performance profiling agent
- Machine learning workflow agent

## License & Attribution

Part of the Claude Code ecosystem.
Generated with Meta-Automation Architect skill.

---

**Ready to use?** Simply say: `"Set up automation for my project"`

The meta-skill will guide you through the entire process with smart recommendations and generate a complete, customized automation system!