sead-method-core/sead-core/templates/api-pattern-tmpl.yaml

Specification Enforced Agentic Agile Development - A hybrid methodology preventing AI agent drift through catalog-based constraints with comprehensive external asset integration

# SEAD API Pattern Documentation Template
template:
  id: api-pattern-template-v1
  name: SEAD API Pattern Documentation Template
  version: 1.0
  constitutional_framework: true
  catalog_integration: true
  pattern_domain: api_contracts
  output:
    format: markdown
    filename: "{{pattern_name}}-api-pattern.md"
    title: "{{pattern_name}} API Pattern Documentation"

constitutional_requirements:
  mode_detection: required
  catalog_read: mandatory
  context_preservation: enforced
  quality_validation: continuous
  anti_pattern_detection: enabled

workflow:
  mode: constitutional_interactive
  elicitation: guided_extraction
  catalog_validation: enabled
  constraint_enforcement: progressive

sections:
  - id: constitutional-initialization
    title: Constitutional Framework Initialization
    instruction: |
      Establish constitutional context for API pattern documentation:
      1. Identify development mode and API design quality requirements
      2. Load constitutional framework for API governance
      3. Configure catalog integration validation requirements
      4. Establish context preservation for API pattern handoffs
      5. Set quality gates appropriate for API pattern tier
    sections:
      - id: pattern-context
        title: API Pattern Context and Constitutional Framework
        template: |
          **Documentation Date:** {{documentation_date}}
          **Development Mode:** {{development_mode}}
          **Constitutional Framework:** {{constitutional_version}}
          **Pattern Agent:** sead-pattern-extraction
          **API Quality Tier:** {{pattern_quality_tier}}
          **Catalog Domain:** API Contracts > {{api_subdomain}}
          **Constitutional Compliance:** {{constitutional_compliance_level}}

  - id: api-pattern-overview
    title: API Pattern Overview
    instruction: |
      Provide comprehensive API pattern overview focusing on service interface design:
      1. Define API pattern purpose and communication problem it solves
      2. Establish API scope, boundaries, and service responsibilities
      3. Document when to use this API pattern and when NOT to use
      4. Identify target API consumers and integration prerequisites
      5. Provide value proposition and API design benefits
    elicit: true
    constitutional_validation: required
    sections:
      - id: api-pattern-summary
        title: API Pattern Summary
        template: |
          **API Pattern Name:** {{pattern_name}}
          **API Domain:** {{api_subdomain}}
          **Quality Tier:** {{quality_tier}}
          **API Complexity Level:** {{complexity_level}}
          **Service Scope:** {{service_scope}}
          
          **API Purpose:**
          {{api_purpose}}
          
          **Communication Problem Solved:**
          {{communication_problem_description}}
          
          **Key API Benefits:**
          {{#each api_benefits}}
          - {{benefit_description}}
          {{/each}}

      - id: api-usage-guidance
        title: API Usage Guidance
        template: |
          **When to Use This API Pattern:**
          {{#each api_use_cases}}
          - {{use_case_description}}
          {{/each}}
          
          **When NOT to Use This API Pattern:**
          {{#each api_anti_use_cases}}
          - {{anti_use_case_description}}
          {{/each}}
          
          **API Integration Prerequisites:**
          {{#each api_prerequisites}}
          - {{prerequisite_description}}
          {{/each}}
          
          **Target API Consumers:**
          - **Consumer Types:** {{target_consumer_types}}
          - **Integration Complexity:** {{integration_complexity}}
          - **Domain Knowledge Required:** {{api_domain_knowledge_required}}

  - id: api-specification
    title: API Specification and Contract Design
    instruction: |
      Document comprehensive API specification and contract design:
      1. Define API endpoints, methods, and resource structure
      2. Document request/response schemas and data contracts
      3. Specify authentication and authorization requirements
      4. Include error handling and status code specifications
      5. Address API versioning and evolution strategies
    elicit: true
    constitutional_validation: critical
    sections:
      - id: endpoint-design
        title: Endpoint Design and Resource Structure
        template: |
          **API Base URL:** {{api_base_url}}
          **API Version:** {{api_version}}
          **Resource Naming Convention:** {{resource_naming_convention}}
          
          **Core Endpoints:**
          {{#each core_endpoints}}
          - **{{http_method}} {{endpoint_path}}**
            - **Purpose:** {{endpoint_purpose}}
            - **Resource:** {{resource_type}}
            - **Authentication Required:** {{auth_required}}
            {{#if query_parameters}}
            - **Query Parameters:**
              {{#each query_parameters}}
              - `{{param_name}}` ({{param_type}}): {{param_description}}
              {{/each}}
            {{/if}}
          {{/each}}

      - id: request-response-contracts
        title: Request/Response Contracts
        template: |
          **Content Type:** {{content_type}}
          **Serialization Format:** {{serialization_format}}
          
          **Request Schema Example:**
          ```json
          {{request_schema_example}}
          ```
          
          **Response Schema Example:**
          ```json
          {{response_schema_example}}
          ```
          
          **Schema Validation Rules:**
          {{#each validation_rules}}
          - **{{field_name}}:** {{validation_description}}
          {{/each}}

      - id: authentication-authorization
        title: Authentication and Authorization
        template: |
          **Authentication Method:** {{auth_method}}
          **Authorization Scheme:** {{auth_scheme}}
          
          **Authentication Flow:**
          {{#each auth_flow_steps}}
          {{step_number}}. {{step_description}}
          {{/each}}
          
          **Authorization Examples:**
          ```http
          {{auth_header_example}}
          ```
          
          **Permission Requirements:**
          {{#each permission_requirements}}
          - **{{endpoint_pattern}}:** {{required_permissions}}
          {{/each}}

      - id: error-handling-specification
        title: Error Handling and Status Codes
        template: |
          **Standard Error Format:**
          ```json
          {{error_response_format}}
          ```
          
          **HTTP Status Codes:**
          {{#each status_codes}}
          - **{{status_code}} {{status_message}}:** {{status_description}}
            - **When:** {{status_condition}}
            - **Response:** {{status_response_example}}
          {{/each}}
          
          **Error Categories:**
          {{#each error_categories}}
          - **{{category_name}}:** {{category_description}}
          {{/each}}

  - id: api-implementation-guide
    title: API Implementation Guide
    instruction: |
      Provide step-by-step API implementation guidance with working examples:
      1. Document server-side implementation approach
      2. Provide client-side integration examples
      3. Include configuration and deployment considerations
      4. Address testing and validation approaches
      5. Include performance and scalability considerations
    elicit: true
    constitutional_validation: critical
    sections:
      - id: server-implementation
        title: Server-Side Implementation
        template: |
          **Implementation Framework:** {{server_framework}}
          **Language:** {{server_language}}
          
          **Basic API Handler Example:**
          ```{{server_language}}
          {{server_implementation_example}}
          ```
          
          **Middleware Configuration:**
          ```{{server_language}}
          {{middleware_configuration_example}}
          ```
          
          **Data Validation:**
          ```{{server_language}}
          {{validation_implementation_example}}
          ```

      - id: client-integration
        title: Client-Side Integration
        template: |
          **Recommended HTTP Client:** {{recommended_http_client}}
          
          **Basic Client Example:**
          ```{{client_language}}
          {{client_integration_example}}
          ```
          
          **Authentication Integration:**
          ```{{client_language}}
          {{client_auth_example}}
          ```
          
          **Error Handling:**
          ```{{client_language}}
          {{client_error_handling_example}}
          ```

      - id: api-configuration
        title: Configuration and Environment Setup
        template: |
          **Environment Configuration:**
          ```{{config_format}}
          {{environment_config_example}}
          ```
          
          **Required Environment Variables:**
          {{#each env_variables}}
          - **{{var_name}}:** {{var_description}}
            - **Type:** {{var_type}}
            - **Required:** {{var_required}}
            - **Example:** {{var_example}}
          {{/each}}

  - id: api-versioning-evolution
    title: API Versioning and Evolution
    instruction: |
      Document API versioning strategy and evolution planning:
      1. Define versioning scheme and backward compatibility approach
      2. Document breaking change management process
      3. Provide deprecation and migration strategies
      4. Address API documentation versioning
      5. Include consumer communication and transition planning
    elicit: true
    constitutional_validation: required
    sections:
      - id: versioning-strategy
        title: Versioning Strategy
        template: |
          **Versioning Scheme:** {{versioning_scheme}}
          **Backward Compatibility Policy:** {{compatibility_policy}}
          **Breaking Change Threshold:** {{breaking_change_threshold}}
          
          **Version Header Example:**
          ```http
          {{version_header_example}}
          ```
          
          **Supported Versions:**
          {{#each supported_versions}}
          - **{{version_number}}:** {{version_status}} ({{version_support_timeline}})
          {{/each}}

      - id: breaking-change-management
        title: Breaking Change Management
        template: |
          **Breaking Change Process:**
          {{#each breaking_change_steps}}
          {{step_number}}. {{step_description}}
          {{/each}}
          
          **Consumer Communication:**
          - **Advance Notice:** {{advance_notice_period}}
          - **Communication Channels:** {{communication_channels}}
          - **Migration Support:** {{migration_support_description}}
          
          **Deprecation Timeline:**
          {{#each deprecation_phases}}
          - **{{phase_name}}:** {{phase_description}} ({{phase_duration}})
          {{/each}}

  - id: api-testing-validation
    title: API Testing and Validation
    instruction: |
      Document comprehensive API testing and validation approaches:
      1. Define API testing strategies and test categories
      2. Provide contract testing and validation examples
      3. Include performance and load testing approaches
      4. Address security testing and vulnerability assessment
      5. Include API documentation testing and validation
    elicit: true
    constitutional_validation: required
    sections:
      - id: api-testing-strategy
        title: API Testing Strategy
        template: |
          **Testing Pyramid for APIs:**
          {{#each test_levels}}
          - **{{test_level}}:** {{test_description}}
            - **Coverage:** {{test_coverage}}
            - **Tools:** {{test_tools}}
            - **Frequency:** {{test_frequency}}
          {{/each}}
          
          **Test Environment Setup:**
          ```{{config_language}}
          {{test_environment_config}}
          ```

      - id: contract-testing
        title: Contract Testing
        template: |
          **Contract Testing Approach:** {{contract_testing_approach}}
          
          **Provider Contract Tests:**
          ```{{test_language}}
          {{provider_contract_test_example}}
          ```
          
          **Consumer Contract Tests:**
          ```{{test_language}}
          {{consumer_contract_test_example}}
          ```
          
          **Contract Validation:**
          - **Schema Validation:** {{schema_validation_approach}}
          - **Behavior Validation:** {{behavior_validation_approach}}

      - id: performance-testing
        title: Performance and Load Testing
        template: |
          **Performance Benchmarks:**
          - **Response Time Target:** {{response_time_target}}
          - **Throughput Target:** {{throughput_target}}
          - **Concurrent Users:** {{concurrent_users_target}}
          
          **Load Testing Script Example:**
          ```{{load_test_language}}
          {{load_test_script_example}}
          ```
          
          **Performance Monitoring:**
          {{#each performance_metrics}}
          - **{{metric_name}}:** {{metric_description}}
          {{/each}}

  - id: api-security-considerations
    title: API Security Considerations
    instruction: |
      Document comprehensive API security considerations and implementation:
      1. Address authentication and authorization security patterns
      2. Document input validation and sanitization approaches
      3. Include rate limiting and abuse prevention strategies
      4. Address secure communication and data protection
      5. Include security monitoring and incident response
    elicit: true
    constitutional_validation: required
    sections:
      - id: api-security-implementation
        title: Security Implementation
        template: |
          **Security Risk Assessment:** {{security_risk_level}}
          **Primary Security Concerns:**
          {{#each security_concerns}}
          - **{{concern_category}}:** {{concern_description}}
            - **Risk Level:** {{risk_level}}
            - **Mitigation:** {{mitigation_strategy}}
          {{/each}}

      - id: input-validation-security
        title: Input Validation and Sanitization
        template: |
          **Validation Strategy:**
          ```{{server_language}}
          {{input_validation_example}}
          ```
          
          **Sanitization Approaches:**
          {{#each sanitization_rules}}
          - **{{input_type}}:** {{sanitization_method}}
          {{/each}}
          
          **SQL Injection Prevention:**
          ```{{server_language}}
          {{sql_injection_prevention_example}}
          ```

      - id: rate-limiting-abuse-prevention
        title: Rate Limiting and Abuse Prevention
        template: |
          **Rate Limiting Configuration:**
          ```{{config_format}}
          {{rate_limiting_config}}
          ```
          
          **Abuse Detection Patterns:**
          {{#each abuse_patterns}}
          - **{{pattern_name}}:** {{pattern_description}}
          {{/each}}
          
          **Response to Rate Limit Exceeded:**
          ```http
          {{rate_limit_response_example}}
          ```

  - id: api-documentation-maintenance
    title: API Documentation and Maintenance
    instruction: |
      Document API documentation strategy and maintenance procedures:
      1. Define API documentation standards and formats
      2. Provide automated documentation generation approaches
      3. Include API change tracking and version documentation
      4. Address consumer onboarding and integration guides
      5. Include feedback collection and improvement processes
    elicit: true
    constitutional_validation: required
    sections:
      - id: documentation-strategy
        title: Documentation Strategy
        template: |
          **Documentation Format:** {{documentation_format}}
          **Documentation Tools:** {{documentation_tools}}
          **Update Frequency:** {{documentation_update_frequency}}
          
          **OpenAPI Specification Example:**
          ```yaml
          {{openapi_spec_example}}
          ```
          
          **Interactive Documentation:** {{interactive_docs_url}}

      - id: consumer-onboarding
        title: Consumer Onboarding
        template: |
          **Onboarding Process:**
          {{#each onboarding_steps}}
          {{step_number}}. {{step_description}}
          {{/each}}
          
          **Quick Start Guide:**
          ```{{example_language}}
          {{quick_start_example}}
          ```
          
          **SDK and Client Libraries:**
          {{#each client_libraries}}
          - **{{language}}:** {{library_name}} - {{library_description}}
          {{/each}}

  - id: constitutional-compliance
    title: Constitutional Framework Compliance
    instruction: |
      Document SEAD constitutional framework compliance for API patterns:
      1. Detail constitutional requirements for API design and governance
      2. Document mode-aware behavior for different development phases
      3. Provide context preservation capabilities for API pattern handoffs
      4. Address audit trail and governance requirements for API evolution
      5. Include compliance validation and monitoring for API patterns
    constitutional_validation: mandatory
    sections:
      - id: constitutional-integration
        title: Constitutional Framework Integration
        template: |
          **Framework Compliance:**
          - **Framework Version:** {{constitutional_framework_version}}
          - **API Compliance Level:** {{api_compliance_level}}
          - **Integration Date:** {{integration_date}}
          - **Validation Status:** {{validation_status}}
          
          **Mode-Aware API Behavior:**
          - **Prototype Mode:** {{prototype_mode_api_behavior}}
          - **Development Mode:** {{development_mode_api_behavior}}
          - **Build-to-Deploy Mode:** {{build_deploy_mode_api_behavior}}
          
          **API Constraint Enforcement:**
          {{#each api_constraints}}
          - **{{constraint_name}}:** {{constraint_description}}
            - **Enforcement Level:** {{enforcement_level}}
            - **Validation:** {{validation_approach}}
          {{/each}}

      - id: api-context-preservation
        title: Context Preservation and Agent Handoffs
        template: |
          **API Context Preservation:**
          - **State Serialization:** {{api_state_serialization_approach}}
          - **Context Metadata:** {{api_context_metadata_description}}
          - **Handoff Support:** {{api_handoff_support_level}}
          
          **API Agent Handoff Requirements:**
          {{#each api_handoff_requirements}}
          - {{requirement_description}}
          {{/each}}
          
          **API Context Validation:**
          ```{{validation_language}}
          {{api_context_validation_code}}
          ```

      - id: api-governance-integration
        title: Governance and Audit Integration
        template: |
          **API Governance Framework:**
          - **Governance Level:** {{api_governance_level}}
          - **Approval Process:** {{api_approval_process}}
          - **Review Requirements:** {{api_review_requirements}}
          
          **API Audit Trail:**
          - **Audit Events:** {{api_audit_events}}
          - **Log Format:** {{api_audit_log_format}}
          - **Retention Policy:** {{api_audit_retention_policy}}
          
          **API Compliance Monitoring:**
          {{#each api_monitoring_mechanisms}}
          - **{{mechanism_name}}:** {{mechanism_description}}
          {{/each}}