gh-epieczko-betty/agents/meta.command/README.md

meta.command - Command Creator Meta-Agent

Creates complete, production-ready command manifests from natural language descriptions.

Purpose

The meta.command meta-agent transforms command descriptions into properly structured YAML manifests that can be registered in the Betty Framework Command Registry. It handles all the details of command creation including parameter validation, execution configuration, and documentation.

What It Does

• ✅ Parses natural language command descriptions (Markdown or JSON)
• ✅ Generates complete command manifests in YAML format
• ✅ Validates command structure and execution types
• ✅ Supports all three execution types: agent, skill, workflow
• ✅ Creates proper parameter definitions with type validation
• ✅ Prepares commands for registration via command.define skill
• ✅ Supports traceability tracking

Usage

python3 agents/meta.command/meta_command.py <description_file>

With Traceability

python3 agents/meta.command/meta_command.py examples/api_validate_command.md \
  --requirement-id "REQ-2025-042" \
  --requirement-description "Create command for API validation" \
  --rationale "Simplify API validation workflow for developers"

Input Format

Markdown Format

Create a description file with the following structure:

# Name: /api-validate
# Version: 0.1.0
# Description: Validate API specifications against standards

# Execution Type: skill
# Target: api.validate

# Parameters:
- spec_file: string (required) - Path to API specification file
- format: enum (optional, default=openapi, values=[openapi,asyncapi,grpc]) - API specification format
- strict: boolean (optional, default=true) - Enable strict validation mode

# Execution Context:
- format: json
- timeout: 300

# Status: active

# Tags: api, validation, quality

JSON Format

Alternatively, use JSON:

{
  "name": "/api-validate",
  "version": "0.1.0",
  "description": "Validate API specifications against standards",
  "execution_type": "skill",
  "target": "api.validate",
  "parameters": [
    {
      "name": "spec_file",
      "type": "string",
      "required": true,
      "description": "Path to API specification file"
    },
    {
      "name": "format",
      "type": "enum",
      "values": ["openapi", "asyncapi", "grpc"],
      "default": "openapi",
      "description": "API specification format"
    }
  ],
  "execution_context": {
    "format": "json",
    "timeout": 300
  },
  "status": "active",
  "tags": ["api", "validation", "quality"]
}

Command Execution Types

1. Agent Execution

Use for complex, context-aware tasks requiring reasoning:

# Name: /api-design
# Execution Type: agent
# Target: api.architect
# Description: Design a complete API architecture

When to use:

• Tasks requiring multi-step reasoning
• Context-aware decision making
• Complex analysis or design work

2. Skill Execution

Use for atomic, deterministic operations:

# Name: /api-validate
# Execution Type: skill
# Target: api.validate
# Description: Validate API specifications

When to use:

• Direct, predictable operations
• Fast, single-purpose tasks
• Composable building blocks

3. Workflow Execution

Use for orchestrated multi-step processes:

# Name: /api-pipeline
# Execution Type: workflow
# Target: workflows/api-pipeline.yaml
# Description: Execute full API development pipeline

When to use:

• Multi-agent/skill coordination
• Sequential or parallel task execution
• Complex business processes

Parameter Types

Supported Types

Type	Description	Example
string	Text values	"api-spec.yaml"
integer	Whole numbers	42
boolean	true/false	true
enum	Fixed set of values	["openapi", "asyncapi"]
array	Lists of values	["tag1", "tag2"]
object	Structured data	{"key": "value"}

Parameter Options

• required: true/false - Whether parameter is mandatory
• default: value - Default value if not provided
• values: [...] - Allowed values (for enum type)
• description: "..." - What the parameter does

Examples

Example 1: Simple Validation Command

Input: examples/api-validate-cmd.md

# Name: /api-validate
# Description: Validate API specification files
# Execution Type: skill
# Target: api.validate

# Parameters:
- spec_file: string (required) - Path to specification file
- format: enum (optional, default=openapi, values=[openapi,asyncapi]) - Spec format

# Status: active
# Tags: api, validation

Output: commands/api-validate.yaml

name: /api-validate
version: 0.1.0
description: Validate API specification files
parameters:
  - name: spec_file
    type: string
    required: true
    description: Path to specification file
  - name: format
    type: enum
    values:
      - openapi
      - asyncapi
    default: openapi
    description: Spec format
execution:
  type: skill
  target: api.validate
status: active
tags:
  - api
  - validation

Example 2: Agent-Based Design Command

Input: examples/api-design-cmd.md

# Name: /api-design
# Description: Design a complete API architecture
# Execution Type: agent
# Target: api.architect

# Parameters:
- requirements: string (required) - Path to requirements document
- style: enum (optional, default=rest, values=[rest,graphql,grpc]) - API style

# Execution Context:
- reasoning_mode: iterative
- max_iterations: 10

# Status: active
# Tags: api, design, architecture

Output: commands/api-design.yaml

name: /api-design
version: 0.1.0
description: Design a complete API architecture
parameters:
  - name: requirements
    type: string
    required: true
    description: Path to requirements document
  - name: style
    type: enum
    values:
      - rest
      - graphql
      - grpc
    default: rest
    description: API style
execution:
  type: agent
  target: api.architect
  context:
    reasoning_mode: iterative
    max_iterations: 10
status: active
tags:
  - api
  - design
  - architecture

Example 3: Workflow Command

Input: examples/deploy-cmd.md

# Name: /deploy
# Description: Deploy application to specified environment
# Execution Type: workflow
# Target: workflows/deploy-pipeline.yaml

# Parameters:
- environment: enum (required, values=[dev,staging,production]) - Target environment
- version: string (required) - Version to deploy
- skip_tests: boolean (optional, default=false) - Skip test execution

# Status: draft
# Tags: deployment, devops

Output

The meta-agent creates:

1. Command Manifest - Complete YAML file in commands/ directory
2. Console Output - Summary of created command
3. Next Steps - Instructions for registration

Example console output:

🎯  meta.command - Creating command from examples/api-validate-cmd.md

✨ Command '/api-validate' created successfully!

📄 Created file:
   - commands/api-validate.yaml

✅ Command manifest is ready for registration
   Name: /api-validate
   Execution: skill → api.validate
   Status: active

📝 Next steps:
   1. Review the manifest: cat commands/api-validate.yaml
   2. Register command: python3 skills/command.define/command_define.py commands/api-validate.yaml
   3. Verify in registry: cat registry/commands.json

Integration with command.define

After creating a command manifest, register it using the command.define skill:

# Register the command
python3 skills/command.define/command_define.py commands/api-validate.yaml

# Verify registration
cat registry/commands.json

The command.define skill will:

• Validate the manifest structure
• Check that the execution target exists
• Add the command to the Command Registry
• Make the command available for use

Artifact Flow

┌──────────────────────────┐
│ Command Description      │
│ (Markdown or JSON)       │
└──────────┬───────────────┘
           │ consumes
           ▼
    ┌──────────────┐
    │ meta.command │
    └──────┬───────┘
           │ produces
           ▼
┌──────────────────────────┐
│ Command Manifest (YAML)  │
│ commands/*.yaml          │
└──────────┬───────────────┘
           │
           ▼
    ┌──────────────┐
    │command.define│
    │   (skill)    │
    └──────┬───────┘
           │
           ▼
┌──────────────────────────┐
│ Commands Registry        │
│ registry/commands.json   │
└──────────────────────────┘

Command Naming Conventions

• ✅ Must start with / (e.g., /api-validate)
• ✅ Use kebab-case for multi-word commands (e.g., /api-validate-all)
• ✅ Be concise but descriptive
• ✅ Avoid generic names like /run or /execute
• ✅ Use domain prefix for related commands (e.g., /api-*, /db-*)

Validation

The meta-agent validates:

• ✅ Required fields present (name, description, execution_type, target)
• ✅ Valid execution type (agent, skill, workflow)
• ✅ Command name starts with /
• ✅ Parameter types are valid
• ✅ Enum parameters have values defined
• ✅ Version follows semantic versioning
• ✅ Status is valid (draft, active, deprecated, archived)

Error Handling

Common errors and solutions:

Missing required fields:

❌ Error: Missing required fields: execution_type, target

→ Add all required fields to your description

Invalid execution type:

❌ Error: Invalid execution type: service. Must be one of: agent, skill, workflow

→ Use only valid execution types

Invalid parameter type:

❌ Error: Invalid parameter type: float

→ Use supported parameter types

Best Practices

1. Clear Descriptions - Write concise, actionable command descriptions
2. Proper Parameters - Define all parameters with types and validation
3. Appropriate Execution Type - Choose the right execution model (agent/skill/workflow)
4. Meaningful Tags - Add relevant tags for discoverability
5. Version Management - Start with 0.1.0, increment appropriately
6. Status Lifecycle - Use draft → active → deprecated → archived

Files Generated

commands/
└── {command-name}.yaml    # Command manifest

Integration with Meta-Agents

The meta.command agent works alongside:

• meta.skill - Create skills that commands can execute
• meta.agent - Create agents that commands can delegate to
• meta.artifact - Define artifact types for command I/O
• meta.compatibility - Find compatible agents for command workflows

Traceability

Track command creation with requirement metadata:

python3 agents/meta.command/meta_command.py examples/api-validate-cmd.md \
  --requirement-id "REQ-2025-042" \
  --requirement-description "API validation command" \
  --issue-id "BETTY-123" \
  --requested-by "dev-team" \
  --rationale "Streamline API validation process"

View trace:

python3 betty/trace_cli.py show command.api_validate

See Also

• command.define skill - Register command manifests
• meta.skill - Create skills for command execution
• meta.agent - Create agents for command delegation
• Command Registry - registry/commands.json
• Command Infrastructure - docs/COMMAND_HOOK_INFRASTRUCTURE.md