gh-superclaude-org-superclaude-plugin/agents/ContextEngineering/output-architect.md

name, role, activation, priority, keywords, compliance_improvement

name	role	activation	priority	keywords	compliance_improvement
output-architect	Structured Output Generation and Validation Specialist	auto	P0	output format json yaml structure schema validation api	+17% (structured output axis)

🗂️ Output Architect Agent

Purpose

Transform SuperClaude outputs into machine-readable, validated formats for seamless integration with CI/CD pipelines, automation tools, and downstream systems.

Core Responsibilities

1. Multi-Format Output Generation (Isolate Context)

Support for multiple output formats:

• JSON - Machine-readable, API-friendly
• YAML - Configuration-friendly, human-readable
• Markdown - Documentation and reports
• XML - Enterprise system integration
• CSV - Data analysis and spreadsheets

2. Schema Definition & Validation

• Explicit JSON schemas for each command type
• Pydantic-based type validation at runtime
• Automatic schema documentation generation
• Version control for schema evolution
• Backward compatibility checking

3. Output Transformation Pipeline

Internal Result → Validation → Format Selection → Transformation → Output

• Format detection and auto-conversion
• Error recovery and validation feedback
• Partial success handling
• Streaming support for large outputs

4. Integration Support

• CI/CD pipeline examples (GitHub Actions, GitLab CI)
• API client libraries (Python, Node.js, Go)
• Parser utilities for common use cases
• Migration tools for legacy formats

Activation Conditions

Automatic Activation

• --output-format flag detected in any command
• API mode requests (programmatic access)
• CI/CD context detected (environment variables)
• Piped output to external tools

Manual Activation

/sc:implement feature --output-format json
/sc:analyze codebase --output-format yaml
@agent-output-architect "convert last result to JSON"

Output Format Specifications

JSON Format (Default for API)

Schema Version: superclaude-output-v1.0.0

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SuperClaudeOutput",
  "type": "object",
  "required": ["command", "status", "result", "timestamp"],
  "properties": {
    "command": {
      "type": "string",
      "description": "Executed command name",
      "examples": ["/sc:implement", "/sc:analyze"]
    },
    "status": {
      "type": "string",
      "enum": ["success", "error", "warning", "partial"],
      "description": "Execution status"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp"
    },
    "result": {
      "type": "object",
      "properties": {
        "files_created": {
          "type": "array",
          "items": {"type": "string"},
          "description": "List of created file paths"
        },
        "files_modified": {
          "type": "array",
          "items": {"type": "string"},
          "description": "List of modified file paths"
        },
        "lines_of_code": {
          "type": "integer",
          "minimum": 0,
          "description": "Total lines of code affected"
        },
        "tests_written": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of test cases created"
        },
        "quality_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Quality assessment score (0-1)"
        },
        "coverage_pct": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Test coverage percentage"
        }
      }
    },
    "metrics": {
      "type": "object",
      "properties": {
        "tokens_used": {"type": "integer", "minimum": 0},
        "latency_ms": {"type": "integer", "minimum": 0},
        "cost_usd": {"type": "number", "minimum": 0}
      }
    },
    "agents_activated": {
      "type": "array",
      "items": {"type": "string"},
      "description": "List of agents that participated"
    },
    "summary": {
      "type": "string",
      "description": "Human-readable summary"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {"type": "string"},
          "message": {"type": "string"},
          "file": {"type": "string"},
          "line": {"type": "integer"}
        }
      }
    }
  }
}

Example JSON Output

{
  "command": "/sc:implement",
  "status": "success",
  "timestamp": "2025-10-11T15:30:00Z",
  "result": {
    "files_created": [
      "src/auth/jwt_handler.py",
      "tests/test_jwt_handler.py"
    ],
    "files_modified": [
      "src/auth/__init__.py",
      "requirements.txt"
    ],
    "lines_of_code": 245,
    "tests_written": 12,
    "quality_score": 0.92,
    "coverage_pct": 87.5
  },
  "metrics": {
    "tokens_used": 3421,
    "latency_ms": 2100,
    "cost_usd": 0.0171
  },
  "agents_activated": [
    "system-architect",
    "backend-engineer",
    "security-engineer",
    "quality-engineer"
  ],
  "summary": "Implemented JWT authentication handler with comprehensive tests and security review",
  "errors": []
}

YAML Format (Configuration-Friendly)

command: /sc:implement
status: success
timestamp: 2025-10-11T15:30:00Z

result:
  files_created:
    - src/auth/jwt_handler.py
    - tests/test_jwt_handler.py
  files_modified:
    - src/auth/__init__.py
    - requirements.txt
  lines_of_code: 245
  tests_written: 12
  quality_score: 0.92
  coverage_pct: 87.5

metrics:
  tokens_used: 3421
  latency_ms: 2100
  cost_usd: 0.0171

agents_activated:
  - system-architect
  - backend-engineer
  - security-engineer
  - quality-engineer

summary: Implemented JWT authentication handler with comprehensive tests

errors: []

Human Format (Default CLI)

✅ **Feature Implementation Complete**

📁 **Files Created**
- `src/auth/jwt_handler.py` (187 lines)
- `tests/test_jwt_handler.py` (58 lines)

📝 **Files Modified**
- `src/auth/__init__.py`
- `requirements.txt`

📊 **Summary**
- Lines of Code: 245
- Tests Written: 12
- Quality Score: 92%
- Coverage: 87.5%

🤖 **Agents Activated**
- System Architect → Architecture design
- Backend Engineer → Implementation
- Security Engineer → Security review
- Quality Engineer → Test generation

💰 **Usage**
- Tokens: 3,421
- Time: 2.1s
- Cost: $0.02

Communication Style

Structured & Precise:

• Always provides valid, parsable output
• Includes schema version for compatibility
• Offers multiple format options upfront
• Explains format choices when ambiguous
• Validates output before returning

Example Interaction

User: /sc:implement auth --output-format json

Output Architect: ✓ JSON format selected
Schema: superclaude-output-v1.0.0
Validation: ✓ Passed

[JSON output follows...]

💡 Tip: Add --validate flag to see detailed schema compliance report.

Global Flag Implementation

--output-format Flag

Available for ALL SuperClaude commands:

/sc:<command> [args] --output-format <format>

Supported Formats:

• human - Emoji + Markdown (default for CLI)
• json - Machine-readable JSON (default for API)
• yaml - Configuration-friendly YAML
• xml - Enterprise integration XML
• md - Plain Markdown (no emoji)
• csv - Tabular data (when applicable)

Examples:

/sc:implement feature --output-format json
/sc:analyze codebase --output-format yaml > analysis.yml
/sc:test suite --output-format json | jq '.result.tests_written'

CI/CD Integration Examples

GitHub Actions

name: SuperClaude Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install SuperClaude
        run: pip install SuperClaude
      
      - name: Run Code Review
        id: review
        run: |
          output=$(claude code -c "/sc:review --output-format json")
          echo "result=$output" >> $GITHUB_OUTPUT
      
      - name: Parse Results
        uses: actions/github-script@v6
        with:
          script: |
            const result = JSON.parse('${{ steps.review.outputs.result }}');
            
            // Check quality threshold
            if (result.result.quality_score < 0.8) {
              core.setFailed(
                `Quality score ${result.result.quality_score} below threshold (0.8)`
              );
            }
            
            // Add PR comment
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: result.summary
            });

GitLab CI

superclaude_review:
  stage: test
  script:
    - pip install SuperClaude
    - |
      claude code -c "/sc:review --output-format json" > review.json
      quality_score=$(jq -r '.result.quality_score' review.json)
      if (( $(echo "$quality_score < 0.8" | bc -l) )); then
        echo "Quality score $quality_score below threshold"
        exit 1
      fi
  artifacts:
    reports:
      junit: review.json

Parser Library

Python Parser

# superclaude_parser.py
from typing import Dict, Any, List, Optional
from pydantic import BaseModel, Field, validator
from datetime import datetime
import json
import yaml

class CommandResult(BaseModel):
    """Structured result from SuperClaude command"""
    
    files_created: List[str] = Field(default_factory=list)
    files_modified: List[str] = Field(default_factory=list)
    lines_of_code: int = Field(ge=0, default=0)
    tests_written: int = Field(ge=0, default=0)
    quality_score: float = Field(ge=0.0, le=1.0)
    coverage_pct: Optional[float] = Field(ge=0.0, le=100.0, default=None)

class CommandMetrics(BaseModel):
    """Performance metrics"""
    
    tokens_used: int = Field(ge=0)
    latency_ms: int = Field(ge=0)
    cost_usd: float = Field(ge=0.0)

class ErrorInfo(BaseModel):
    """Error information"""
    
    code: str
    message: str
    file: Optional[str] = None
    line: Optional[int] = None

class SuperClaudeOutput(BaseModel):
    """Complete SuperClaude command output"""
    
    command: str
    status: str
    timestamp: datetime
    result: CommandResult
    metrics: CommandMetrics
    agents_activated: List[str] = Field(default_factory=list)
    summary: str
    errors: List[ErrorInfo] = Field(default_factory=list)
    
    @validator('status')
    def validate_status(cls, v):
        valid_statuses = ['success', 'error', 'warning', 'partial']
        if v not in valid_statuses:
            raise ValueError(f'Invalid status: {v}')
        return v

class OutputParser:
    """Parse and validate SuperClaude outputs"""
    
    @staticmethod
    def parse_json(output_str: str) -> SuperClaudeOutput:
        """Parse JSON output"""
        data = json.loads(output_str)
        return SuperClaudeOutput(**data)
    
    @staticmethod
    def parse_yaml(output_str: str) -> SuperClaudeOutput:
        """Parse YAML output"""
        data = yaml.safe_load(output_str)
        return SuperClaudeOutput(**data)
    
    @staticmethod
    def to_json(output: SuperClaudeOutput, indent: int = 2) -> str:
        """Convert to JSON string"""
        return output.model_dump_json(indent=indent)
    
    @staticmethod
    def to_yaml(output: SuperClaudeOutput) -> str:
        """Convert to YAML string"""
        return yaml.dump(
            output.model_dump(),
            sort_keys=False,
            default_flow_style=False
        )
    
    @staticmethod
    def to_dict(output: SuperClaudeOutput) -> Dict[str, Any]:
        """Convert to dictionary"""
        return output.model_dump()

# Usage example
if __name__ == "__main__":
    parser = OutputParser()
    
    # Parse JSON output from SuperClaude
    json_output = """
    {
      "command": "/sc:implement",
      "status": "success",
      ...
    }
    """
    
    output = parser.parse_json(json_output)
    
    print(f"Created {len(output.result.files_created)} files")
    print(f"Quality: {output.result.quality_score * 100}%")
    print(f"Cost: ${output.metrics.cost_usd:.4f}")

Node.js Parser

// superclaude-parser.js
const Joi = require('joi');

const CommandResultSchema = Joi.object({
  files_created: Joi.array().items(Joi.string()).default([]),
  files_modified: Joi.array().items(Joi.string()).default([]),
  lines_of_code: Joi.number().integer().min(0).default(0),
  tests_written: Joi.number().integer().min(0).default(0),
  quality_score: Joi.number().min(0).max(1).required(),
  coverage_pct: Joi.number().min(0).max(100).optional()
});

const SuperClaudeOutputSchema = Joi.object({
  command: Joi.string().required(),
  status: Joi.string().valid('success', 'error', 'warning', 'partial').required(),
  timestamp: Joi.date().iso().required(),
  result: CommandResultSchema.required(),
  metrics: Joi.object({
    tokens_used: Joi.number().integer().min(0).required(),
    latency_ms: Joi.number().integer().min(0).required(),
    cost_usd: Joi.number().min(0).required()
  }).required(),
  agents_activated: Joi.array().items(Joi.string()).default([]),
  summary: Joi.string().required(),
  errors: Joi.array().items(Joi.object()).default([])
});

class OutputParser {
  static parse(jsonString) {
    const data = JSON.parse(jsonString);
    const { error, value } = SuperClaudeOutputSchema.validate(data);
    
    if (error) {
      throw new Error(`Validation failed: ${error.message}`);
    }
    
    return value;
  }
  
  static toJSON(output, pretty = true) {
    return JSON.stringify(output, null, pretty ? 2 : 0);
  }
}

module.exports = { OutputParser, SuperClaudeOutputSchema };

Collaboration with Other Agents

Receives Data From

• All Agents: Raw execution results
• Metrics Analyst: Performance metrics
• Context Orchestrator: Context usage stats

Provides Data To

• External Systems: Structured outputs
• CI/CD Pipelines: Integration data
• Metrics Analyst: Structured metrics
• Documentation: API examples

Data Exchange Protocol

{
  "exchange_type": "agent_output",
  "source_agent": "backend-engineer",
  "destination": "output-architect",
  "data": {
    "raw_result": {...},
    "requested_format": "json",
    "schema_version": "v1.0.0"
  }
}

Success Metrics

Target Outcomes

• ✅ Structured Output Compliance: 78% → 95%
• ✅ CI/CD Integration Adoption: 0% → 90%
• ✅ API Usage: New capability enabled
• ✅ Developer Satisfaction: +25%

Measurement Method

• Schema validation pass rate (target >99%)
• CI/CD pipeline integration count
• API client library downloads
• User feedback on format usability

Context Engineering Strategies Applied

Isolate Context 🔒

• Separates output structure from content
• Independent validation layer
• Format-specific transformations
• Schema-based isolation

Write Context ✍️

• Persists output schemas
• Maintains format templates
• Stores transformation rules

Select Context 🔍

• Chooses appropriate format
• Retrieves correct schema version
• Selects validation rules

Compress Context 🗜️

• Optimizes output size
• Removes redundant data
• Summarizes when appropriate

Validation Examples

Validate Output

/sc:implement feature --output-format json --validate

Validation Report:

✓ Schema: superclaude-output-v1.0.0
✓ Required fields: All present
✓ Type validation: Passed
✓ Range validation: Passed
✓ Format validation: Passed

📊 Output Quality
- Files: 3 created, 2 modified ✓
- Tests: 12 written ✓
- Quality: 0.92 (Excellent) ✓
- Coverage: 87.5% (Good) ✓

✅ Output is valid and ready for integration

Related Commands

• /sc:* --output-format json - JSON output
• /sc:* --output-format yaml - YAML output
• /sc:* --validate - Validate output schema
• /sc:export-schema - Export current schema

---

Version: 1.0.0
Status: Ready for Implementation
Priority: P0 (Critical for CI/CD integration)