Initial commit
This commit is contained in:
Zhongwei Li
510
agents/meta.suggest/README.md
Normal file
510
agents/meta.suggest/README.md
Normal file
@@ -0,0 +1,510 @@
|
||||
# meta.suggest - Context-Aware Next-Step Recommender
|
||||
|
||||
Helps Claude decide what to do next after an agent completes by analyzing context and suggesting compatible next steps.
|
||||
|
||||
## Overview
|
||||
|
||||
**meta.suggest** provides intelligent "what's next" recommendations by analyzing what just happened, what artifacts were produced, and what agents are compatible. It works with meta.compatibility to enable smart multi-agent orchestration.
|
||||
|
||||
**What it does:**
|
||||
- Analyzes context (what agent ran, what artifacts produced)
|
||||
- Uses meta.compatibility to find compatible next steps
|
||||
- Provides ranked suggestions with clear rationale
|
||||
- Considers project state and user goals
|
||||
- Detects warnings (gaps, isolated agents)
|
||||
- Suggests project-wide improvements
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Suggest Next Steps
|
||||
|
||||
```bash
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.agent \
|
||||
--artifacts agents/api.architect/agent.yaml
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Context: meta.agent
|
||||
Produced: agent-definition
|
||||
|
||||
🌟 Primary Suggestion:
|
||||
Process with meta.compatibility
|
||||
Rationale: meta.agent produces 'agent-definition' which meta.compatibility consumes
|
||||
Priority: high
|
||||
|
||||
🔄 Alternatives:
|
||||
1. Test the created artifact
|
||||
Verify the artifact works as expected
|
||||
|
||||
2. Analyze compatibility
|
||||
Understand what agents can work with meta.agent's outputs
|
||||
```
|
||||
|
||||
### Analyze Project
|
||||
|
||||
```bash
|
||||
python3 agents/meta.suggest/meta_suggest.py --analyze-project
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
📊 Project Analysis:
|
||||
Total Agents: 7
|
||||
Total Artifacts: 16
|
||||
Relationships: 3
|
||||
Gaps: 5
|
||||
|
||||
💡 Suggestions (6):
|
||||
1. Create agent/skill to produce 'agent-description'
|
||||
Consumed by 1 agents but no producers
|
||||
Priority: medium
|
||||
...
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### Suggest After Agent Runs
|
||||
|
||||
```bash
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context AGENT_NAME \
|
||||
[--artifacts FILE1 FILE2...] \
|
||||
[--goal "USER_GOAL"] \
|
||||
[--format json|text]
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `--context` - Agent that just ran
|
||||
- `--artifacts` - Artifact files that were produced (optional)
|
||||
- `--goal` - User's goal for better suggestions (optional)
|
||||
- `--format` - Output format (text or json)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# After meta.agent creates agent
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.agent \
|
||||
--artifacts agents/my-agent/agent.yaml
|
||||
|
||||
# After meta.artifact creates artifact type
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.artifact \
|
||||
--artifacts schemas/my-artifact.json
|
||||
|
||||
# With user goal
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.agent \
|
||||
--goal "Create and validate API design agent"
|
||||
```
|
||||
|
||||
### Analyze Project
|
||||
|
||||
```bash
|
||||
python3 agents/meta.suggest/meta_suggest.py --analyze-project [--format json|text]
|
||||
```
|
||||
|
||||
Analyzes the entire agent ecosystem and suggests improvements:
|
||||
- Agents to create
|
||||
- Gaps to fill
|
||||
- Documentation needs
|
||||
- Ecosystem health
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Context Analysis
|
||||
|
||||
Determines what just happened:
|
||||
- Which agent ran
|
||||
- What artifacts were produced
|
||||
- What artifact types are involved
|
||||
|
||||
### 2. Compatibility Check
|
||||
|
||||
Uses meta.compatibility to find:
|
||||
- Agents that can consume the produced artifacts
|
||||
- Agents that are compatible downstream
|
||||
- Potential pipeline steps
|
||||
|
||||
### 3. Suggestion Generation
|
||||
|
||||
Creates suggestions based on:
|
||||
- Compatible agents (high priority)
|
||||
- Validation/testing options (medium priority)
|
||||
- Gap-filling needs (low priority if applicable)
|
||||
|
||||
### 4. Ranking
|
||||
|
||||
Ranks suggestions by:
|
||||
- Priority level (high > medium > low)
|
||||
- Automation (automated > manual)
|
||||
- Relevance to user goal
|
||||
|
||||
### 5. Warning Generation
|
||||
|
||||
Detects potential issues:
|
||||
- Gaps in required artifacts
|
||||
- Isolated agents (no compatible partners)
|
||||
- Failed validations
|
||||
|
||||
## Suggestion Types
|
||||
|
||||
### 1. Process with Compatible Agent
|
||||
|
||||
```
|
||||
🌟 Primary Suggestion:
|
||||
Process with api.validator
|
||||
Rationale: api.architect produces 'openapi-spec' which api.validator consumes
|
||||
```
|
||||
|
||||
Automatically suggests running compatible agents.
|
||||
|
||||
### 2. Validate/Test Artifact
|
||||
|
||||
```
|
||||
Test the created artifact
|
||||
Rationale: Verify the artifact works as expected
|
||||
```
|
||||
|
||||
Suggests testing when creation-type agents run.
|
||||
|
||||
### 3. Analyze Compatibility
|
||||
|
||||
```
|
||||
Analyze compatibility
|
||||
Rationale: Understand what agents can work with meta.agent's outputs
|
||||
Command: python3 agents/meta.compatibility/meta_compatibility.py analyze meta.agent
|
||||
```
|
||||
|
||||
Suggests understanding the ecosystem.
|
||||
|
||||
### 4. Fill Gaps
|
||||
|
||||
```
|
||||
Create producer for 'agent-description'
|
||||
Rationale: No agents produce 'agent-description' (required by meta.agent)
|
||||
```
|
||||
|
||||
Suggests creating missing components.
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Text Format
|
||||
|
||||
```
|
||||
Context: AGENT_NAME
|
||||
Produced: artifact-type-1, artifact-type-2
|
||||
|
||||
🌟 Primary Suggestion:
|
||||
ACTION
|
||||
Rationale: WHY
|
||||
[Command: HOW (if automated)]
|
||||
Priority: LEVEL
|
||||
|
||||
🔄 Alternatives:
|
||||
1. ACTION
|
||||
Rationale: WHY
|
||||
|
||||
⚠️ Warnings:
|
||||
• WARNING_MESSAGE
|
||||
```
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"context": {
|
||||
"agent": "meta.agent",
|
||||
"artifacts_produced": ["agents/my-agent/agent.yaml"],
|
||||
"artifact_types": ["agent-definition"],
|
||||
"timestamp": "2025-10-24T..."
|
||||
},
|
||||
"suggestions": [
|
||||
{
|
||||
"action": "Process with meta.compatibility",
|
||||
"agent": "meta.compatibility",
|
||||
"rationale": "...",
|
||||
"priority": "high",
|
||||
"command": "..."
|
||||
}
|
||||
],
|
||||
"primary_suggestion": {...},
|
||||
"alternatives": [...],
|
||||
"warnings": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
### With meta.compatibility
|
||||
|
||||
meta.suggest uses meta.compatibility for discovery:
|
||||
|
||||
```python
|
||||
# Internal call
|
||||
compatibility = meta.compatibility.find_compatible(agent_name)
|
||||
|
||||
# Use compatible agents for suggestions
|
||||
for compatible in compatibility.get("can_feed_to", []):
|
||||
suggest(f"Process with {compatible['agent']}")
|
||||
```
|
||||
|
||||
### With Claude
|
||||
|
||||
Claude can call meta.suggest after any agent:
|
||||
|
||||
```
|
||||
User: Create an API design agent
|
||||
Claude: *runs meta.agent*
|
||||
Claude: *calls meta.suggest --context meta.agent*
|
||||
Claude: I've created the agent. Would you like me to:
|
||||
1. Analyze its compatibility
|
||||
2. Test it
|
||||
3. Add documentation
|
||||
```
|
||||
|
||||
### In Workflows
|
||||
|
||||
Use in shell scripts:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Create and analyze agent
|
||||
|
||||
# Step 1: Create agent
|
||||
python3 agents/meta.agent/meta_agent.py description.md
|
||||
|
||||
# Step 2: Get suggestions
|
||||
SUGGESTIONS=$(python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.agent \
|
||||
--format json)
|
||||
|
||||
# Step 3: Extract primary suggestion
|
||||
PRIMARY=$(echo "$SUGGESTIONS" | jq -r '.primary_suggestion.command')
|
||||
|
||||
# Step 4: Run it
|
||||
eval "$PRIMARY"
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: Agent Creation Pipeline
|
||||
|
||||
```bash
|
||||
# Create agent
|
||||
python3 agents/meta.agent/meta_agent.py my_agent.md
|
||||
|
||||
# Get suggestions
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.agent \
|
||||
--artifacts agents/my-agent/agent.yaml
|
||||
|
||||
# Follow primary suggestion
|
||||
python3 agents/meta.compatibility/meta_compatibility.py analyze my-agent
|
||||
```
|
||||
|
||||
### Workflow 2: Continuous Improvement
|
||||
|
||||
```bash
|
||||
# Analyze project
|
||||
python3 agents/meta.suggest/meta_suggest.py --analyze-project > improvements.txt
|
||||
|
||||
# Review suggestions
|
||||
cat improvements.txt
|
||||
|
||||
# Implement top suggestions
|
||||
# (create missing agents, fill gaps, etc.)
|
||||
```
|
||||
|
||||
### Workflow 3: Goal-Oriented Orchestration
|
||||
|
||||
```bash
|
||||
# Define goal
|
||||
GOAL="Design, validate, and implement an API"
|
||||
|
||||
# Get suggestions for goal
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--goal "$GOAL" \
|
||||
--format json > pipeline.json
|
||||
|
||||
# Execute suggested pipeline
|
||||
# (extract steps from pipeline.json and run)
|
||||
```
|
||||
|
||||
## Artifact Types
|
||||
|
||||
### Consumes
|
||||
|
||||
- **compatibility-graph** - Agent compatibility information
|
||||
- From: meta.compatibility
|
||||
|
||||
- **agent-definition** - Agent that just ran
|
||||
- Pattern: `agents/*/agent.yaml`
|
||||
|
||||
### Produces
|
||||
|
||||
- **suggestion-report** - Next-step recommendations
|
||||
- Pattern: `*.suggestions.json`
|
||||
- Schema: `schemas/suggestion-report.json`
|
||||
|
||||
## Understanding Suggestions
|
||||
|
||||
### Priority Levels
|
||||
|
||||
**High** - Should probably do this
|
||||
- Compatible agent waiting
|
||||
- Validation needed
|
||||
- Next logical step
|
||||
|
||||
**Medium** - Good to do
|
||||
- Analyze compatibility
|
||||
- Understand ecosystem
|
||||
- Non-critical validation
|
||||
|
||||
**Low** - Nice to have
|
||||
- Fill gaps
|
||||
- Documentation
|
||||
- Future improvements
|
||||
|
||||
### Automated vs Manual
|
||||
|
||||
**Automated** - Has command to run
|
||||
```
|
||||
Command: python3 agents/meta.compatibility/...
|
||||
```
|
||||
|
||||
**Manual** - Requires user action
|
||||
```
|
||||
(No command - manual action required)
|
||||
```
|
||||
|
||||
### Rationale
|
||||
|
||||
Always includes "why" for each suggestion:
|
||||
```
|
||||
Rationale: meta.agent produces 'agent-definition' which meta.compatibility consumes
|
||||
```
|
||||
|
||||
Helps Claude and users understand the reasoning.
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
### Providing Context
|
||||
|
||||
More context = better suggestions:
|
||||
|
||||
✅ **Good:**
|
||||
```bash
|
||||
--context meta.agent \
|
||||
--artifacts agents/my-agent/agent.yaml \
|
||||
--goal "Create and validate agent"
|
||||
```
|
||||
|
||||
❌ **Minimal:**
|
||||
```bash
|
||||
--context meta.agent
|
||||
```
|
||||
|
||||
### Interpreting Warnings
|
||||
|
||||
**Gaps warning:**
|
||||
```
|
||||
⚠️ meta.agent requires artifacts that aren't produced by any agent
|
||||
```
|
||||
This is often expected for user inputs. Not always a problem.
|
||||
|
||||
**Isolated warning:**
|
||||
```
|
||||
⚠️ my-agent has no compatible agents
|
||||
```
|
||||
This suggests the agent uses non-standard artifact types or no other agents exist yet.
|
||||
|
||||
### Using Suggestions
|
||||
|
||||
1. **Review primary suggestion first** - Usually the best option
|
||||
2. **Consider alternatives** - May be better for your specific case
|
||||
3. **Check warnings** - Understand potential issues
|
||||
4. **Verify commands** - Review before running automated suggestions
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No suggestions returned
|
||||
|
||||
```
|
||||
Error: Could not determine relevant agents for goal
|
||||
```
|
||||
|
||||
**Causes:**
|
||||
- Agent has no compatible downstream agents
|
||||
- Artifact types are all user-provided inputs
|
||||
- No other agents in ecosystem
|
||||
|
||||
**Solutions:**
|
||||
- Create more agents
|
||||
- Use standard artifact types
|
||||
- Check agent artifact_metadata
|
||||
|
||||
### Incorrect suggestions
|
||||
|
||||
If suggestions don't make sense:
|
||||
- Verify agent artifact_metadata is correct
|
||||
- Check meta.compatibility output directly
|
||||
- Ensure artifact types are registered
|
||||
|
||||
### Empty project analysis
|
||||
|
||||
```
|
||||
Total Agents: 0
|
||||
```
|
||||
|
||||
**Cause:** No agents found in `agents/` directory
|
||||
|
||||
**Solution:** Create agents using meta.agent or manually
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
meta.suggest
|
||||
├─ Uses: meta.compatibility (discovery)
|
||||
├─ Analyzes: context and artifacts
|
||||
├─ Produces: ranked suggestions
|
||||
└─ Helps: Claude make decisions
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Example 1: After creating agent
|
||||
python3 agents/meta.agent/meta_agent.py examples/api_architect_description.md
|
||||
python3 agents/meta.suggest/meta_suggest.py --context meta.agent
|
||||
|
||||
# Example 2: After creating artifact type
|
||||
python3 agents/meta.artifact/meta_artifact.py create artifact.md
|
||||
python3 agents/meta.suggest/meta_suggest.py --context meta.artifact
|
||||
|
||||
# Example 3: Project health check
|
||||
python3 agents/meta.suggest/meta_suggest.py --analyze-project
|
||||
|
||||
# Example 4: Export to JSON
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.agent \
|
||||
--format json > suggestions.json
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [META_AGENTS.md](../../docs/META_AGENTS.md) - Meta-agent ecosystem
|
||||
- [meta.compatibility README](../meta.compatibility/README.md) - Compatibility analyzer
|
||||
- [ARTIFACT_STANDARDS.md](../../docs/ARTIFACT_STANDARDS.md) - Artifact system
|
||||
- [suggestion-report schema](../../schemas/suggestion-report.json)
|
||||
|
||||
## How Claude Uses This
|
||||
|
||||
After any agent completes:
|
||||
1. Claude calls meta.suggest with context
|
||||
2. Reviews suggestions and rationale
|
||||
3. Presents options to user or auto-executes
|
||||
4. Makes intelligent orchestration decisions
|
||||
|
||||
meta.suggest is Claude's assistant for "what's next" decisions!
|
||||
Reference in New Issue
Block a user