Initial commit

2025-11-29 18:26:08 +08:00
commit 8f22ddf339
295 changed files with 59710 additions and 0 deletions
--- a/agents/meta.create/README.md
+++ b/agents/meta.create/README.md
@@ -0,0 +1,374 @@
+# meta.create - Component Creation Orchestrator
+
+The intelligent orchestrator for creating Betty skills, commands, and agents from natural language descriptions.
+
+## Purpose
+
+`meta.create` is the primary entry point for creating Betty components. It automatically:
+
+- **Detects** what type of component you're describing (skill, command, agent, or combination)
+- **Checks** inventory to avoid duplicates
+- **Analyzes** complexity to determine the optimal creation pattern
+- **Creates** components in dependency order
+- **Validates** compatibility and identifies gaps
+- **Recommends** next steps for completion
+
+## Why Use meta.create?
+
+Instead of manually running multiple meta-agents (`meta.skill`, `meta.command`, `meta.agent`, `meta.compatibility`), `meta.create` orchestrates everything for you in the right order.
+
+### Before meta.create:
+```bash
+# Manual workflow - you had to know the order and check everything
+python3 agents/meta.command/meta_command.py description.md
+# Check if it recommends creating a skill...
+python3 agents/meta.skill/meta_skill.py skill_description.md
+python3 agents/meta.agent/meta_agent.py agent_description.md
+python3 agents/meta.compatibility/meta_compatibility.py analyze my.agent
+# Check for gaps, create missing skills...
+```
+
+### With meta.create:
+```bash
+# One command does it all
+python3 agents/meta.create/meta_create.py description.md
+```
+
+## How It Works
+
+### Step 1: Analysis
+Parses your description to determine:
+- Is this a skill? command? agent?
+- What artifacts are involved?
+- What's the complexity level?
+
+### Step 2: Duplicate Check
+Queries registries to find existing components:
+- Prevents recreating existing skills
+- Shows what you can reuse
+- Skips unnecessary work
+
+### Step 3: Creation Planning
+Uses `meta.command` complexity analysis to determine pattern:
+- **COMMAND_ONLY**: Simple inline logic (1-3 steps)
+- **SKILL_ONLY**: Reusable utility without command
+- **SKILL_AND_COMMAND**: Complex logic in skill + command wrapper
+- **AGENT**: Multi-skill orchestration
+
+### Step 4: Component Creation
+Creates components in dependency order:
+1. **Skills first** (using `meta.skill`)
+2. **Commands second** (using `meta.command`)
+3. **Agents last** (using `meta.agent` with skill composition)
+
+### Step 5: Compatibility Validation
+For agents, runs `meta.compatibility` to:
+- Find compatible agent pipelines
+- Identify artifact gaps
+- Suggest workflows
+
+### Step 6: Recommendations
+Provides actionable next steps:
+- Missing skills to create
+- Compatibility issues to fix
+- Integration opportunities
+
+## Usage
+
+### Basic Usage
+
+```bash
+python3 agents/meta.create/meta_create.py <description.md>
+```
+
+### Create Skill and Command
+
+```bash
+python3 agents/meta.create/meta_create.py examples/api_validate.md
+```
+
+If `api_validate.md` describes a complex command, meta.create will:
+1. Analyze complexity → detects SKILL_AND_COMMAND pattern
+2. Create the skill first
+3. Create the command that uses the skill
+4. Report what was created
+
+### Create Agent with Dependencies
+
+```bash
+python3 agents/meta.create/meta_create.py examples/api_agent.md
+```
+
+meta.create will:
+1. Detect it's an agent description
+2. Check for required skills (reuse existing)
+3. Create missing skills if needed
+4. Create the agent with proper skill composition
+5. Validate compatibility with other agents
+6. Report gaps and recommendations
+
+### Auto-Fill Gaps
+
+```bash
+python3 agents/meta.create/meta_create.py description.md --auto-fill-gaps
+```
+
+Automatically creates missing skills to fill compatibility gaps.
+
+### Skip Duplicate Check
+
+```bash
+python3 agents/meta.create/meta_create.py description.md --skip-duplicate-check
+```
+
+Force creation even if components exist (useful for updates).
+
+### Output Formats
+
+```bash
+# Human-readable text (default)
+python3 agents/meta.create/meta_create.py description.md
+
+# JSON output for automation
+python3 agents/meta.create/meta_create.py description.md --output-format json
+
+# YAML output
+python3 agents/meta.create/meta_create.py description.md --output-format yaml
+```
+
+### With Traceability
+
+```bash
+python3 agents/meta.create/meta_create.py description.md \
+  --requirement-id REQ-2025-042 \
+  --requirement-description "Create API validation agent" \
+  --issue-id JIRA-1234 \
+  --requested-by "Product Team"
+```
+
+## Description File Format
+
+Your description file can be Markdown or JSON. meta.create detects the type automatically.
+
+### Example: Skill Description
+
+```markdown
+# Name: data.validate
+
+# Type: skill
+
+# Purpose:
+Validate data against JSON schemas with detailed error reporting
+
+# Inputs:
+- data (JSON object to validate)
+- schema (JSON schema for validation)
+
+# Outputs:
+- validation_result (validation report with errors)
+
+# Produces Artifacts:
+- validation.report
+
+# Consumes Artifacts:
+- data.json
+- schema.json
+```
+
+### Example: Command Description
+
+```markdown
+# Name: /validate-api
+
+# Type: command
+
+# Description:
+Validate API responses against OpenAPI schemas
+
+# Execution Type: skill
+
+# Target: api.validate
+
+# Parameters:
+- endpoint: string (required) - API endpoint to validate
+- schema: string (required) - Path to OpenAPI schema
+```
+
+### Example: Agent Description
+
+```markdown
+# Name: api.validator
+
+# Type: agent
+
+# Purpose:
+Comprehensive API testing and validation agent
+
+# Inputs:
+- api.spec
+
+# Outputs:
+- validation.report
+- test.results
+
+# Examples:
+- Validate all API endpoints against OpenAPI spec
+- Generate test cases from schema
+```
+
+## What Gets Created
+
+### For Skills
+- `skills/{name}/skill.yaml` - Skill configuration
+- `skills/{name}/{name}.py` - Python implementation stub
+- `skills/{name}/test_{name}.py` - pytest test template
+- `skills/{name}/README.md` - Documentation
+
+### For Commands
+- `commands/{name}.yaml` - Command manifest
+- Recommendations for skill creation if needed
+
+### For Agents
+- `agents/{name}/agent.yaml` - Agent configuration
+- `agents/{name}/README.md` - Documentation with usage examples
+- Compatibility analysis report
+
+## Output Report
+
+meta.create provides a comprehensive report:
+
+```
+🎯 meta.create - Orchestrating component creation from description.md
+
+📋 Step 1: Analyzing description...
+   Detected types: Skill=True, Command=True, Agent=False
+
+🔍 Step 2: Checking for existing components...
+   ✅ No duplicates found
+
+🛠️  Step 3: Creating components...
+   📊 Analyzing command complexity...
+   Recommended pattern: SKILL_AND_COMMAND
+   Should create skill: True
+
+   🔧 Creating skill...
+   ✅ Skill 'api.validate' created
+
+   📜 Creating command...
+   ✅ Command '/validate-api' created
+
+================================================================================
+✨ CREATION SUMMARY
+================================================================================
+
+✅ Created 2 component(s):
+   • SKILL: api.validate
+   • COMMAND: /validate-api
+
+================================================================================
+```
+
+## Integration with Other Meta-Agents
+
+meta.create uses:
+- **meta.command** - Complexity analysis and command generation
+- **meta.skill** - Skill creation with full package
+- **meta.agent** - Agent creation with skill composition
+- **meta.compatibility** - Compatibility validation and gap detection
+- **registry.query** - Duplicate checking
+- **agent.compose** - Skill recommendation for agents
+
+## Decision Tree
+
+```
+Description Input
+       ↓
+   Parse Type
+       ↓
+    ┌──┴──────────────────┐
+    ↓                     ↓
+  Command?             Agent?
+    ↓                     ↓
+Analyze              Find Skills
+Complexity              ↓
+    ↓              Create Missing
+SKILL_ONLY            Skills
+COMMAND_ONLY            ↓
+SKILL_AND_COMMAND   Create Agent
+    ↓                     ↓
+Create Skill      Validate Compat
+    ↓                     ↓
+Create Command      Report Gaps
+    ↓                     ↓
+   Done              Recommend
+```
+
+## Examples
+
+### Example 1: Simple Command
+
+```bash
+# description.md specifies a simple 2-step command
+python3 agents/meta.create/meta_create.py description.md
+# Result: Creates COMMAND_ONLY (inline logic is sufficient)
+```
+
+### Example 2: Complex Command
+
+```bash
+# description.md specifies 10+ step validation logic
+python3 agents/meta.create/meta_create.py description.md
+# Result: Creates SKILL_AND_COMMAND (skill has logic, command delegates)
+```
+
+### Example 3: Multi-Agent System
+
+```bash
+# description.md describes an orchestration agent
+python3 agents/meta.create/meta_create.py description.md
+# Result:
+#   - Creates agent with existing skills
+#   - Validates compatibility
+#   - Reports: "Can receive from api.architect, can feed to report.generator"
+#   - Suggests pipeline workflows
+```
+
+## Benefits
+
+✅ **Intelligent** - Automatically determines optimal creation pattern
+✅ **Safe** - Checks for duplicates, prevents overwrites
+✅ **Complete** - Creates all necessary components in order
+✅ **Validated** - Runs compatibility checks automatically
+✅ **Traceable** - Supports requirement tracking
+✅ **Informative** - Provides detailed reports and recommendations
+
+## Next Steps
+
+After using meta.create:
+
+1. **Review** created files
+2. **Implement** TODO sections in generated code
+3. **Test** with pytest
+4. **Register** components (manual or use `skill.register`, etc.)
+5. **Use** in your Betty workflows
+
+## Troubleshooting
+
+**Q: meta.create says component already exists**
+A: Use `--skip-duplicate-check` to override, or rename your component
+
+**Q: Compatibility gaps reported**
+A: Use `--auto-fill-gaps` or manually create the missing skills
+
+**Q: Wrong pattern detected**
+A: Add explicit `# Type: skill` or `# Type: command` to your description
+
+## Related Documentation
+
+- [META_AGENTS.md](../../docs/META_AGENTS.md) - Overview of all meta-agents
+- [SKILL_COMMAND_DECISION_TREE.md](../../docs/SKILL_COMMAND_DECISION_TREE.md) - Pattern decision logic
+- [ARTIFACTS.md](../../docs/ARTIFACTS.md) - Artifact metadata system
+
+---
+
+*Created by the Betty Framework Meta-Agent System*