Skip to content

Optimal Command Structure

Why XML is Superior for Commands

XML is the recommended format by Anthropic for creating structured, reliable command sequences. Unlike markdown or plain text instructions, XML provides several critical advantages:

Technical Superiority of XML

  • Hierarchical Structure: XML's nested elements perfectly mirror the logical flow of complex operations
  • Validation: XML parsers can validate structure before execution, catching errors early
  • Parsing Reliability: LLMs process XML more consistently than free-form text
  • Conditional Logic: XML naturally supports conditional statements and loops
  • Metadata Integration: XML allows embedding of execution metadata alongside instructions
  • Error Handling: XML structure enables sophisticated error handling patterns

Anthropic's Recommendation

Anthropic specifically recommends XML for command structures because: - It reduces ambiguity in instruction interpretation - It provides clear boundaries between different command phases - It enables more reliable execution by AI systems - It supports complex conditional logic and iteration patterns

Three-Stage Command Architecture

This command structure is based on the popularized Pocket Flow methodology, which embraces a node-based system with three distinct stages: prep, execute, and post. The architecture adapts this proven pattern to ensure reliable execution:

Stage 1: Preparation Stage

Purpose: Validate context and resources before any execution begins

Key Components: - Requirements Validation: Check all prerequisites (dependencies, permissions, resources) - Context Verification: Ensure sufficient information is available - Critical Validation: Mandatory stop-gate if any requirement fails - Error Response: Standardized failure message format

Why This Matters: Prevents partial failures and wasted effort by catching issues upfront.

<preparation_stage>
  <requirements>
    <requirement_list>
      <requirement>Python 3.7+ is installed and accessible</requirement>
      <requirement>Write permissions available for current working directory</requirement>
    </requirement_list>
  </requirements>
  <critical_validation>
    <condition>If ANY requirement fails, immediately stop</condition>
    <error_response>ERROR: Insufficient context - missing [specific requirement]</error_response>
  </critical_validation>
</preparation_stage>

Stage 2: Execution Stage

Purpose: Perform the actual work with built-in error handling and recovery

Key Components: - Success Criteria: Clear definition of what constitutes successful completion - Error Handling Policy: Standardized retry logic and failure management - Sub-Agent Architecture: Specialized agents for complex tasks requiring parallel processing or domain expertise - Sequential Steps: Ordered execution with explicit dependencies - Loop Support: Iteration patterns for repetitive tasks - Conditional Logic: IF/THEN branching for complex scenarios

Why This Matters: Provides predictable execution with automatic error recovery and clear progress tracking.

Sub-Agent Architecture Pattern

For complex tasks requiring specialized processing or parallel analysis, the execution stage can leverage a sub-agent architecture. This pattern breaks down complex operations into specialized components, each with a specific domain of responsibility.

When to Use Sub-Agents: - Complex analysis requiring multiple specialized perspectives - Tasks that benefit from parallel processing - Operations where different components have distinct expertise areas - Large-scale processing that can be divided into logical segments

Sub-Agent Structure: Each sub-agent should have: 1. Clear Identity: Descriptive name indicating its role 2. Specific Responsibility: Precise scope of what it analyzes or processes 3. Defined Output: Clear deliverable or contribution to the final result

<execution_stage>
  <success_criteria>All tests pass and artifacts are generated</success_criteria>
  <error_handling>
    <policy>IF any step fails:</policy>
    <steps>
      <step>Log error with specific agent responsible</step>
      <step>Attempt retry once with fallback analysis</step>
      <step>If still failing, mark that analysis section as INCOMPLETE and continue</step>
    </steps>
  </error_handling>
  <sub-agents>
    <agent>Data Collector Agent: Gather all required input files and validate structure</agent>
    <agent>Analysis Agent: Perform core computational analysis on collected data</agent>
    <agent>Validation Agent: Verify results meet quality and accuracy standards</agent>
    <agent>Report Generator Agent: Synthesize findings into final deliverable format</agent>
  </sub-agents>
  <execution_steps>
    <step_list>
      <step>Initialize specialized sub-agents for parallel analysis</step>
      <step>Execute sub-agent processing in coordinated sequence</step>
      <step>Synthesize sub-agent outputs into unified result</step>
      <loop name="validation" iterations="3">
        <loop_step iteration="1">Test basic cases</loop_step>
        <loop_step iteration="2">Test edge cases</loop_step>
        <loop_step iteration="3">Test error conditions</loop_step>
      </loop>
    </step_list>
  </execution_steps>
</execution_stage>

Stage 3: Resolution Stage

Purpose: Validate completion and provide comprehensive status reporting

Key Components: - Validation Areas: Systematic review of all deliverables - Completion Indicator: Standardized success/failure reporting - Status Summary: Clear outcome documentation - Timestamp: Execution timing for audit trails

Why This Matters: Ensures nothing is missed and provides clear accountability for results.

<resolution_stage>
  <validation_areas>
    <area>Review that all functions work correctly</area>
    <area>Verify error handling manages edge cases</area>
    <area>Confirm documentation is complete</area>
  </validation_areas>
  <completion_indicator>
    <template>
      FLOW COMPLETE: ✓ execution finished - Status: [SUCCESS/PARTIAL/FAILED] - Timestamp: [completion time]
      [Summary of execution and outcomes]
    </template>
  </completion_indicator>
</resolution_stage>

How the Structure Works

1. Mandatory Sequential Execution

The XML structure enforces that all three stages must be completed in order. This prevents: - Starting work without proper preparation - Skipping validation steps - Incomplete status reporting

2. Built-in Error Resilience

  • Preparation Stage: Catches issues before work begins
  • Execution Stage: Handles failures with retry logic
  • Resolution Stage: Validates final outcomes

3. Clear Success Criteria

Each command defines exactly what success looks like, eliminating ambiguity about whether the task was completed properly.

4. Standardized Reporting

The completion indicator provides consistent status reporting across all commands, making it easy to track execution outcomes.

5. Metadata Integration

The XML structure allows embedding execution instructions, loop conditions, and error handling policies directly within the command structure.

6. Sub-Agent Specialization

For complex tasks, the architecture supports specialized sub-agents that: - Divide Complex Tasks: Break large operations into manageable, specialized components - Enable Parallel Processing: Allow multiple analyses to run simultaneously - Provide Domain Expertise: Each agent focuses on its area of specialization - Improve Error Isolation: Failures in one agent don't necessarily affect others - Enhance Maintainability: Clear separation of concerns makes debugging easier

Template Structure

<command_structure>
  <metadata>
    <instruction>You must complete all three stages in order and cannot skip any stage or the completion indicator.</instruction>
  </metadata>

  <preparation_stage>
    <description>Before you begin any work, you must validate that you have sufficient context and resources</description>
    <requirements>
      <requirement_list>
        <!-- List all context that is required -->
      </requirement_list>
    </requirements>
    <critical_validation>
      <condition>If ANY requirement fails, immediately stop and respond with:</condition>
      <error_response>ERROR: Insufficient context - missing [specific requirement]</error_response>
      <instruction>Do not proceed to execution. Only continue if you can confirm you have everything needed.</instruction>
    </critical_validation>
  </preparation_stage>

  <execution_stage>
    <success_criteria>[Define what success looks like]</success_criteria>
    <error_handling>
      <policy>IF any step fails:</policy>
      <steps>
        <step>Log error with specific agent responsible</step>
        <step>Attempt retry once with fallback analysis</step>
        <step>If still failing, mark that analysis section as INCOMPLETE and continue to next step</step>
      </steps>
    </error_handling>
    <!-- Optional: Use sub-agents for complex tasks requiring specialized processing -->
    <sub-agents>
      <!-- <agent>Agent Name: Specific responsibility and scope</agent> -->
    </sub-agents>
    <execution_steps>
      <instruction>Execute these steps in exact order:</instruction>
      <step_list>
        <!-- List all steps that must be completed -->
      </step_list>
    </execution_steps>
  </execution_stage>

  <resolution_stage>
    <description>Analyze the complete execution:</description>
    <validation_areas>
      <!-- List all areas that must be validated before completing -->
    </validation_areas>
    <completion_indicator>
      <format>Always end with:</format>
      <template>
        FLOW COMPLETE: ✓ execution finished - Status: [SUCCESS/PARTIAL/FAILED] - Timestamp: [completion time]
        [Summary of execution and outcomes]
      </template>
    </completion_indicator>
  </resolution_stage>
</command_structure>

This structure ensures reliable, predictable execution while providing comprehensive error handling and status reporting. The XML format makes it easy for AI systems to parse and execute consistently, leading to better outcomes and fewer failed operations.