Initial commit

2025-11-29 18:26:08 +08:00
commit 8f22ddf339
295 changed files with 59710 additions and 0 deletions
--- a/agents/meta.compatibility/README.md
+++ b/agents/meta.compatibility/README.md
@@ -0,0 +1,469 @@
+# meta.compatibility - Agent Compatibility Analyzer
+
+Analyzes agent compatibility and discovers multi-agent workflows based on artifact flows.
+
+## Overview
+
+**meta.compatibility** helps Claude discover which agents can work together by analyzing what artifacts they produce and consume. It enables intelligent multi-agent orchestration by suggesting compatible combinations and detecting pipeline gaps.
+
+**What it does:**
+- Scans all agents and extracts artifact metadata
+- Builds compatibility maps (who produces/consumes what)
+- Finds compatible agents based on artifact flows
+- Suggests multi-agent pipelines for goals
+- Generates complete compatibility graphs
+- Detects gaps (consumed but not produced artifacts)
+
+## Quick Start
+
+### Find Compatible Agents
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py find-compatible meta.agent
+```
+
+Output:
+```
+Agent: meta.agent
+Produces: agent-definition, agent-documentation
+Consumes: agent-description
+
+✅ Can feed outputs to (1 agents):
+   • meta.compatibility (via agent-definition)
+
+⚠️  Gaps (1):
+   • agent-description: No agents produce 'agent-description' (required by meta.agent)
+```
+
+### Suggest Pipeline
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "Create and analyze an agent"
+```
+
+Output:
+```
+📋 Pipeline 1: meta.agent Pipeline
+   Pipeline starting with meta.agent
+   Steps:
+      1. meta.agent - Meta-agent that creates other agents...
+      2. meta.compatibility - Analyzes agent and skill compatibility...
+```
+
+### Analyze Agent
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py analyze meta.agent
+```
+
+### List All Compatibility
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py list-all
+```
+
+Output:
+```
+Total Agents: 7
+Total Artifact Types: 16
+Total Relationships: 3
+
+⚠️  Global Gaps (5):
+   • agent-description: Consumed by 1 agents but no producers
+   ...
+```
+
+## Commands
+
+### find-compatible
+
+Find agents compatible with a specific agent.
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py find-compatible AGENT_NAME [--format json|yaml|text]
+```
+
+**Shows:**
+- What the agent produces
+- What the agent consumes
+- Agents that can consume its outputs
+- Agents that can provide its inputs
+- Gaps (missing producers)
+
+### suggest-pipeline
+
+Suggest multi-agent pipeline for a goal.
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "GOAL" [--artifacts TYPE1 TYPE2...] [--format json|yaml|text]
+```
+
+**Examples:**
+```bash
+# Suggest pipeline for goal
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "Design and validate APIs"
+
+# With required artifacts
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "Process data" --artifacts openapi-spec validation-report
+```
+
+**Shows:**
+- Suggested pipelines (ranked)
+- Steps in each pipeline
+- Artifact flows between agents
+- Whether pipeline is complete (no gaps)
+
+### analyze
+
+Complete compatibility analysis for one agent.
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py analyze AGENT_NAME [--format json|yaml|text]
+```
+
+**Shows:**
+- Full compatibility report
+- Compatible agents (upstream/downstream)
+- Suggested workflows
+- Gaps and warnings
+
+### list-all
+
+Generate complete compatibility graph for all agents.
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py list-all [--format json|yaml|text]
+```
+
+**Shows:**
+- All agents in the system
+- All relationships
+- All artifact types
+- Global gaps
+- Statistics
+
+## Output Formats
+
+### Text (default)
+
+Human-readable output with emojis and formatting.
+
+### JSON
+
+Machine-readable JSON for programmatic use.
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py find-compatible meta.agent --format json > meta_agent_compatibility.json
+```
+
+### YAML
+
+YAML format for configuration or documentation.
+
+```bash
+python3 agents/meta.compatibility/meta_compatibility.py list-all --format yaml > compatibility_graph.yaml
+```
+
+## How It Works
+
+### 1. Agent Scanning
+
+Scans `agents/` directory for all `agent.yaml` files:
+
+```python
+for agent_dir in agents_dir.iterdir():
+    agent_yaml = agent_dir / "agent.yaml"
+    # Load and parse agent definition
+```
+
+### 2. Artifact Extraction
+
+Extracts artifact_metadata from each agent:
+
+```yaml
+artifact_metadata:
+  produces:
+    - type: openapi-spec
+  consumes:
+    - type: api-requirements
+```
+
+### 3. Compatibility Mapping
+
+Builds map of artifact types to producers/consumers:
+
+```
+openapi-spec:
+  producers: [api.define, api.architect]
+  consumers: [api.validate, api.code-generator]
+```
+
+### 4. Relationship Discovery
+
+For each agent:
+- Find agents that can consume its outputs
+- Find agents that can provide its inputs
+- Detect gaps (missing producers)
+
+### 5. Pipeline Suggestion
+
+Uses keyword matching and artifact analysis:
+- Match goal keywords to agent names/descriptions
+- Build pipeline from artifact flows
+- Rank by completeness and length
+- Return top suggestions
+
+## Integration
+
+### With meta.agent 
+After creating an agent, analyze its compatibility:
+
+```bash
+# Create agent
+python3 agents/meta.agent/meta_agent.py description.md
+
+# Analyze compatibility
+python3 agents/meta.compatibility/meta_compatibility.py analyze new-agent
+
+# Find who can work with it
+python3 agents/meta.compatibility/meta_compatibility.py find-compatible new-agent
+```
+
+### With meta.suggest
+
+meta.suggest uses meta.compatibility to make recommendations:
+
+```bash
+python3 agents/meta.suggest/meta_suggest.py --context meta.agent
+```
+
+Internally calls meta.compatibility to find next steps.
+
+## Common Workflows
+
+### Workflow 1: Understand Agent Ecosystem
+
+```bash
+# See all compatibility
+python3 agents/meta.compatibility/meta_compatibility.py list-all
+
+# Analyze each agent
+for agent in meta.agent meta.artifact meta.compatibility meta.suggest; do
+    echo "=== $agent ==="
+    python3 agents/meta.compatibility/meta_compatibility.py analyze $agent
+done
+```
+
+### Workflow 2: Build Multi-Agent Pipeline
+
+```bash
+# Suggest pipeline
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "Create and test an agent"
+
+# Get JSON for workflow automation
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "My goal" --format json > pipeline.json
+```
+
+### Workflow 3: Find Gaps
+
+```bash
+# Find global gaps
+python3 agents/meta.compatibility/meta_compatibility.py list-all | grep "Gaps:"
+
+# Analyze specific agent gaps
+python3 agents/meta.compatibility/meta_compatibility.py find-compatible api.architect
+```
+
+## Artifact Types
+
+### Consumes
+
+- **agent-definition** - Agent configurations
+  - Pattern: `agents/*/agent.yaml`
+
+- **registry-data** - Skills and agents registry
+  - Pattern: `registry/*.json`
+
+### Produces
+
+- **compatibility-graph** - Agent relationship maps
+  - Pattern: `*.compatibility.json`
+  - Schema: `schemas/compatibility-graph.json`
+
+- **pipeline-suggestion** - Multi-agent workflows
+  - Pattern: `*.pipeline.json`
+  - Schema: `schemas/pipeline-suggestion.json`
+
+## Understanding Output
+
+### Can Feed To
+
+Agents that can consume this agent's outputs.
+
+```
+✅ Can feed outputs to (2 agents):
+   • api.validator (via openapi-spec)
+   • api.code-generator (via openapi-spec)
+```
+
+Means:
+- api.architect produces openapi-spec
+- Both api.validator and api.code-generator consume openapi-spec
+- You can run: api.architect → api.validator
+- Or: api.architect → api.code-generator
+
+### Can Receive From
+
+Agents that can provide this agent's inputs.
+
+```
+⬅️  Can receive inputs from (1 agents):
+   • api.requirements-analyzer (via api-requirements)
+```
+
+Means:
+- api.architect needs api-requirements
+- api.requirements-analyzer produces api-requirements
+- You can run: api.requirements-analyzer → api.architect
+
+### Gaps
+
+Missing artifacts in the ecosystem.
+
+```
+⚠️  Gaps (1):
+   • agent-description: No agents produce 'agent-description'
+```
+
+Means:
+- meta.agent needs agent-description input
+- No agent produces it (it's user-provided)
+- This is expected for user inputs
+
+### Complete vs Incomplete Pipelines
+
+**Complete Pipeline:**
+```
+Complete: ✅ Yes
+```
+All consumed artifacts are produced by pipeline steps.
+
+**Incomplete Pipeline:**
+```
+Complete: ❌ No
+Gaps: agent-description, registry-data
+```
+Some consumed artifacts aren't produced. Requires user input or additional agents.
+
+## Tips & Best Practices
+
+### Finding Compatible Agents
+
+Use specific artifact types:
+```bash
+# Instead of generic goal
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "Process stuff"
+
+# Use specific artifacts
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "Validate API" --artifacts openapi-spec
+```
+
+### Understanding Gaps
+
+Not all gaps are problems:
+- **User inputs** (agent-description, api-requirements) - Expected
+- **Missing producers** for internal artifacts - Need new agents/skills
+
+### Building Pipelines
+
+Start with compatibility analysis:
+1. Understand what each agent needs/produces
+2. Find compatible combinations
+3. Build pipeline step-by-step
+4. Validate no gaps exist (or gaps are user inputs)
+
+## Troubleshooting
+
+### Agent not found
+
+```
+Error: Agent 'my-agent' not found
+```
+
+**Solutions:**
+- Check agent exists in `agents/` directory
+- Ensure `agent.yaml` exists
+- Verify agent name in agent.yaml matches
+
+### No compatible agents found
+
+```
+Can feed outputs to (0 agents)
+Can receive inputs from (0 agents)
+```
+
+**Causes:**
+- Agent is isolated (no shared artifact types)
+- Agent uses custom artifact types
+- No other agents exist yet
+
+**Solutions:**
+- Create agents with compatible artifact types
+- Use standard artifact types
+- Check artifact_metadata is properly defined
+
+### Empty pipeline suggestions
+
+```
+Error: Could not determine relevant agents for goal
+```
+
+**Solutions:**
+- Be more specific in goal description
+- Mention artifact types explicitly
+- Use `--artifacts` flag
+
+## Architecture
+
+```
+meta.compatibility
+    ├─ Scans: agents/ directory
+    ├─ Analyzes: artifact_metadata
+    ├─ Builds: compatibility maps
+    ├─ Produces: compatibility graphs
+    └─ Used by: meta.suggest, Claude
+```
+
+## Examples
+
+See test runs:
+```bash
+# Example 1: Find compatible agents
+python3 agents/meta.compatibility/meta_compatibility.py find-compatible meta.agent
+
+# Example 2: Suggest pipeline
+python3 agents/meta.compatibility/meta_compatibility.py suggest-pipeline "Create agent and check compatibility"
+
+# Example 3: Full analysis
+python3 agents/meta.compatibility/meta_compatibility.py analyze api.architect
+
+# Example 4: Export to JSON
+python3 agents/meta.compatibility/meta_compatibility.py list-all --format json > graph.json
+```
+
+## Related Documentation
+
+- [META_AGENTS.md](../../docs/META_AGENTS.md) - Meta-agent ecosystem
+- [ARTIFACT_STANDARDS.md](../../docs/ARTIFACT_STANDARDS.md) - Artifact system
+- [compatibility-graph schema](../../schemas/compatibility-graph.json)
+- [pipeline-suggestion schema](../../schemas/pipeline-suggestion.json)
+
+## How Claude Uses This
+
+Claude can:
+1. **Discover capabilities** - "What agents can work with openapi-spec?"
+2. **Build workflows** - "How do I design and validate an API?"
+3. **Make decisions** - "What should I run next?"
+4. **Detect gaps** - "What's missing from the ecosystem?"
+
+meta.compatibility enables autonomous multi-agent orchestration!