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 - Main usage guide
• SKILL.md - Full skill definition
• Communication Protocol - Agent Communication Protocol (ACP) specification
• Examples - Complete examples for different project types
• 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 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

# 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

# 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

# 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

watch -n 2 'cat .claude/agents/context/*/coordination.json | jq ".agents"'

Follow Live Events

tail -f .claude/agents/context/*/messages.jsonl | jq

Check Reports

ls .claude/agents/context/*/reports/
cat .claude/agents/context/*/reports/security-analyzer.json | jq

Aggregate Findings

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

• 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

• 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

# 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

# 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

# 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!