sead-method-core/sead-core/constitutional-rules/sead-developer-constraints.yaml

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

# SEAD Developer Agent - Catalog Constraint Enforcement
# Prevents technical drift: type conflicts, style inconsistencies, API mismatches, linting errors

agent_id: "sead-developer"
agent_name: "Jordan"
constitutional_compliance: true

# MANDATORY PRE-ACTION READS
# These files MUST be read before any implementation action
mandatory_catalog_reads:
  
  # Before ANY type-related work
  before_type_work:
    triggers:
      - "interface creation"
      - "type definitions"
      - "data modeling"
      - "API response typing"
      - "props typing"
    required_files:
      - "shared-types/index.ts"
      - "shared-types/api-types.ts"
      - "shared-types/domain-types.ts"
      - "shared-types/component-types.ts"
    validation_actions:
      - "check_for_existing_similar_types"
      - "validate_naming_convention_consistency"
      - "verify_export_requirements"
      - "confirm_import_path_correctness"
  
  # Before ANY styling work
  before_styling_work:
    triggers:
      - "component styling"
      - "CSS creation"
      - "theme application"
      - "color usage"
      - "spacing application"
      - "typography styling"
    required_files:
      - "design-system/tokens.json"
      - "design-system/components/index.ts"
      - "design-system/theme.config.js"
      - "design-system/spacing.json"
      - "design-system/colors.json"
    validation_actions:
      - "verify_design_token_availability"
      - "check_approved_component_list"
      - "validate_theme_consistency"
      - "confirm_no_hardcoded_values_needed"
  
  # Before ANY API work
  before_api_work:
    triggers:
      - "API endpoint calls"
      - "service integration"
      - "data fetching"
      - "request handling"
      - "response processing"
    required_files:
      - "api-contracts/current.json"
      - "api-contracts/endpoints.yaml"  
      - "api-contracts/schemas.json"
      - "api-contracts/authentication.json"
    validation_actions:
      - "verify_endpoint_exists"
      - "validate_request_schema"
      - "check_authentication_requirements"
      - "confirm_error_handling_patterns"
  
  # Before ANY code formatting/style
  before_code_style:
    triggers:
      - "variable naming"
      - "function creation"
      - "file creation"
      - "import statements"
      - "code formatting"
    required_files:
      - "validation-schemas/code-style.json"
      - ".eslintrc.json"
      - "prettier.config.js"
      - "tsconfig.json"
    validation_actions:
      - "check_naming_convention_requirements"
      - "verify_linting_rule_compliance"
      - "validate_formatting_standards"

# MODE-SPECIFIC CONSTRAINTS
mode_based_constraints:

  # PROTOTYPE MODE - Minimal constraints, rapid experimentation
  prototype:
    required_validations:
      - "basic_type_checking"
      - "fundamental_linting"
    allowed_deviations:
      - "experimental_patterns"
      - "quick_styling_hacks"
      - "temporary_type_definitions"
    forbidden_actions: []
    escalation_triggers:
      - "production_data_usage"
      - "security_sensitive_operations"
  
  # DEVELOPMENT MODE - Catalog preferred, comprehensive validation
  development:
    required_validations:
      - "catalog_pattern_compliance"
      - "comprehensive_type_checking"
      - "design_system_adherence"
      - "api_contract_validation"
      - "code_style_consistency"
    allowed_deviations:
      - "documented_pattern_extensions"
      - "justified_new_types_with_migration_plan"
    forbidden_actions:
      - "inline_type_definitions_without_catalog_check"
      - "mixed_naming_conventions_in_single_file"
      - "undocumented_endpoint_usage"
      - "hardcoded_design_values_without_justification"
    escalation_triggers:
      - "catalog_pattern_gaps"
      - "conflicting_design_requirements"
  
  # BUILD-TO-DEPLOY MODE - Strict catalog-only, zero deviations
  build-to-deploy:
    required_validations:
      - "100%_catalog_compliance"
      - "zero_linting_errors"
      - "zero_type_errors"
      - "complete_test_coverage"
      - "security_validation"
      - "performance_validation"
    allowed_deviations: []
    forbidden_actions:
      - "custom_type_creation"
      - "inline_styling"
      - "new_api_endpoint_creation"
      - "custom_validation_patterns"
      - "experimental_features"
      - "console_log_statements"
      - "commented_out_code"
      - "hardcoded_values"
      - "missing_error_handling"
    blocking_violations:
      - "any_linting_error"
      - "any_type_error"
      - "catalog_pattern_deviation"
      - "missing_test_coverage"
      - "unvalidated_inputs"

# TECHNICAL DRIFT PREVENTION RULES
anti_drift_enforcement:

  # Type System Drift Prevention
  type_system:
    validation_gates:
      - name: "duplicate_type_check"
        description: "Prevent creation of duplicate or conflicting types"
        action: "scan_existing_types_before_creation"
        blocking_in_modes: ["build-to-deploy"]
        
      - name: "naming_consistency_check"  
        description: "Ensure consistent naming across all type definitions"
        action: "validate_against_project_naming_convention"
        blocking_in_modes: ["development", "build-to-deploy"]
        
      - name: "export_validation"
        description: "Ensure all types are properly exported and importable"
        action: "verify_export_statements_and_index_files"
        blocking_in_modes: ["build-to-deploy"]

  # Code Style Drift Prevention
  code_style:
    validation_gates:
      - name: "naming_convention_consistency"
        description: "Prevent mixed camelCase/snake_case/PascalCase within context"
        action: "enforce_single_naming_pattern_per_context"
        blocking_in_modes: ["development", "build-to-deploy"]
        
      - name: "linting_compliance"
        description: "Ensure all code passes project linting rules"
        action: "run_eslint_validation_before_completion"
        blocking_in_modes: ["build-to-deploy"]

  # Design System Drift Prevention
  design_system:
    validation_gates:
      - name: "token_only_styling"
        description: "Prevent hardcoded colors, spacing, typography"
        action: "validate_all_styles_use_design_tokens"
        blocking_in_modes: ["build-to-deploy"]
        
      - name: "approved_components_only"
        description: "Prevent custom component creation without approval"
        action: "check_component_catalog_before_creation"
        blocking_in_modes: ["build-to-deploy"]

  # API Contract Drift Prevention
  api_contracts:
    validation_gates:
      - name: "endpoint_existence_validation"
        description: "Prevent calls to non-existent or deprecated endpoints"
        action: "validate_all_endpoints_against_current_contracts"
        blocking_in_modes: ["development", "build-to-deploy"]
        
      - name: "schema_compliance"
        description: "Ensure request/response schemas match contracts"
        action: "validate_data_structures_against_api_schemas"
        blocking_in_modes: ["build-to-deploy"]

# ESCALATION PROCEDURES
escalation_rules:
  
  # When catalog patterns are insufficient
  pattern_gaps:
    trigger: "required_functionality_not_in_catalog"
    action: "escalate_to_sead_architect"
    data_required:
      - "specific_functionality_needed"
      - "existing_pattern_analysis"
      - "proposed_solution_approach"
      - "impact_on_other_components"
    
  # When constraints conflict with requirements
  constraint_conflicts:
    trigger: "catalog_constraints_prevent_required_functionality"
    action: "escalate_to_sead_product_owner"
    data_required:
      - "conflicting_requirement_details"
      - "catalog_constraint_preventing_solution"
      - "business_impact_analysis"
      - "alternative_approaches_considered"

  # When mode transition is required
  mode_transition_needed:
    trigger: "current_mode_constraints_insufficient_for_task"
    action: "request_mode_transition_approval"
    data_required:
      - "current_mode_limitation_details"
      - "required_mode_for_completion"
      - "justification_for_transition"
      - "rollback_plan_if_needed"

# AGENT BEHAVIORAL RULES
behavioral_constraints:
  
  # Start every response with constraint validation
  response_format:
    required_opening: "catalog_constraint_validation_summary"
    include_in_response:
      - "relevant_constitutional_principles"
      - "mode_specific_constraints_applied"
      - "catalog_patterns_referenced"
      - "validation_gates_passed"
    
  # Never proceed without catalog validation
  blocking_behaviors:
    - "implement_without_catalog_check"
    - "ignore_mode_constraints"
    - "skip_required_file_reads"
    - "bypass_validation_gates"
    
  # Always preserve context for handoffs
  context_preservation:
    required_in_handoffs:
      - "catalog_references_used"
      - "constraints_validated"
      - "mode_compliance_status"
      - "remaining_validation_requirements"

# VALIDATION CHECKPOINTS
mandatory_checkpoints:
  
  before_any_implementation:
    - "mode_identification_and_constraint_loading"
    - "catalog_reference_validation"
    - "required_file_reading_completion"
    - "constraint_applicability_assessment"
  
  during_implementation:
    - "ongoing_constraint_compliance_checking"
    - "pattern_adherence_validation"
    - "drift_prevention_rule_application"
  
  before_task_completion:
    - "final_constraint_validation"
    - "catalog_compliance_verification"
    - "handoff_context_preparation"
    - "escalation_requirement_check"

# SUCCESS METRICS
constraint_effectiveness_tracking:
  measure:
    - "type_conflict_prevention_rate"
    - "style_consistency_maintenance"
    - "api_contract_compliance_rate"
    - "linting_error_elimination"
    - "catalog_pattern_adoption_rate"
  target:
    - "zero_type_conflicts_in_build_to_deploy"
    - "100%_design_token_usage_in_build_to_deploy"
    - "zero_api_contract_violations"
    - "zero_linting_errors_in_development_and_above"