sead-method-core/sead-core/core-config.yaml

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

# SEAD-METHOD Core Configuration
# Specification Enforced Agentic Agile Development

project:
  name: "SEAD-METHOD"
  version: "1.0.0"
  methodology: "Specification Enforced Agentic Agile Development"
  description: "Catalog-based constraint enforcement preventing AI agent drift"

# Development Mode Configuration
# Controls constraint enforcement and catalog compliance requirements
modes:
  prototype:
    name: "Prototype"
    emoji: "🧪"
    description: "Rapid experimentation with minimal constraints"
    validation_level: "basic"
    catalog_enforcement: "optional"
    experimental_extensions: true
    constraints:
      - "prefer_simple_solutions"
      - "document_experiments"
      - "capture_patterns_for_catalog"
    validation:
      - "basic_linting"
      - "type_checking"
    blocking_violations: []

  development:
    name: "Development"
    emoji: "⚙️"
    description: "Production-ready features with catalog preference"
    validation_level: "comprehensive"
    catalog_enforcement: "preferred"
    experimental_extensions: "tracked"
    constraints:
      - "use_catalog_when_available"
      - "justify_new_patterns"
      - "plan_migration_path"
      - "document_deviations"
    validation:
      - "comprehensive_linting"
      - "type_checking"
      - "catalog_compliance_check"
      - "constraint_validation"
    blocking_violations:
      - "unjustified_catalog_deviation"

  build-to-deploy:
    name: "Build-to-Deploy"
    emoji: "🏭"
    description: "Factory assembly with strict catalog-only enforcement"
    validation_level: "strict"
    catalog_enforcement: "mandatory"
    experimental_extensions: false
    constraints:
      - "catalog_only"
      - "zero_deviations"
      - "full_compliance_required"
      - "no_custom_patterns"
    validation:
      - "strict_linting"
      - "type_checking"
      - "catalog_compliance_check"
      - "constraint_validation"
      - "security_scanning"
      - "performance_validation"
    blocking_violations:
      - "any_catalog_deviation"
      - "custom_pattern_usage"
      - "experimental_extension"

# Catalog Configuration
catalog:
  version: "1.0.0"
  enforce_constraints: true
  auto_validate: true
  pattern_capture: true
  path: "./sead-catalog"
  
  # Catalog structure validation
  required_components:
    - "api-contracts"
    - "shared-types" 
    - "design-system"
    - "state-management"
    - "error-handling"
    - "validation-schemas"
    - "test-patterns"
    - "auth-patterns"
    - "integration-patterns"
    - "data-strategy"
    - "deployment-strategy"

  # Pattern validation rules
  pattern_validation:
    require_documentation: true
    require_examples: true
    require_tests: true
    require_version: true

  # Greenfield catalog bootstrap configuration
  greenfield_bootstrap:
    enabled: true
    document_sources:
      project_context: "docs/sead-project-brief.md"
      functional_requirements: "docs/sead-prd.md"
      technical_architecture: "docs/sead-architecture.md" 
      ui_specifications: "docs/sead-front-end-spec.md"
      additional_context: "docs/brainstorming/*.md"
    
    # Pattern extraction mapping - which documents feed which catalog domains
    pattern_extraction:
      api_contracts_from: ["technical_architecture", "functional_requirements"]
      shared_types_from: ["technical_architecture", "functional_requirements", "ui_specifications"]
      design_system_from: ["functional_requirements", "ui_specifications"]
      state_management_from: ["technical_architecture", "ui_specifications"]
      error_handling_from: ["functional_requirements", "technical_architecture"]
      validation_schemas_from: ["functional_requirements"]
      test_patterns_from: ["technical_architecture"]
      auth_patterns_from: ["technical_architecture", "functional_requirements"]
      integration_patterns_from: ["technical_architecture"]
      data_strategy_from: ["technical_architecture", "functional_requirements"]
      deployment_strategy_from: ["technical_architecture"]
    
    # Mode-specific bootstrap behavior
    mode_behavior:
      prototype:
        extraction_depth: "basic"
        required_documents: ["project_context"]
        optional_documents: ["functional_requirements", "technical_architecture"]
        catalog_seeding_level: "minimal"
        required_domains: ["api-contracts", "shared-types", "design-system"]
      development:
        extraction_depth: "comprehensive"
        required_documents: ["project_context", "functional_requirements", "technical_architecture"]
        optional_documents: ["ui_specifications", "additional_context"] 
        catalog_seeding_level: "comprehensive"
        required_domains: "all"
      build_to_deploy:
        extraction_depth: "production_ready"
        required_documents: ["project_context", "functional_requirements", "technical_architecture", "ui_specifications"]
        optional_documents: ["additional_context"]
        catalog_seeding_level: "production_ready"
        required_domains: "all"
        validation_required: true

  # External asset integration configuration
  external_integration:
    enabled: true
    staging_directory: "external-assets-staging"
    supported_formats:
      design_systems: [".tsx", ".vue", ".json", ".css", ".scss"]
      api_specifications: [".yaml", ".json", ".openapi"]
      component_libraries: [".tsx", ".vue", ".js", ".ts"]
      documentation: [".md", ".mdx", ".html"]
    
    # Asset transformation mappings
    transformation_mappings:
      design_tokens: "sead-catalog/design-system/tokens/"
      ui_components: "sead-catalog/design-system/components/"
      api_contracts: "sead-catalog/api-contracts/"
      shared_types: "sead-catalog/shared-types/"
      auth_patterns: "sead-catalog/auth-patterns/"
      validation_schemas: "sead-catalog/validation-schemas/"
      test_patterns: "sead-catalog/test-patterns/"
      integration_patterns: "sead-catalog/integration-patterns/"
    
    # Quality requirements by mode
    quality_requirements:
      prototype:
        documentation_required: false
        examples_required: false
        tests_required: false
      development:
        documentation_required: true
        examples_required: true
        tests_required: false
      build_to_deploy:
        documentation_required: true
        examples_required: true
        tests_required: true
        security_validation: true

  # Technical Constraint Enforcement (Prevents AI Agent Drift)
  constraints:
    
    # Type System Constraints - Prevents type conflicts and naming mismatches
    shared-types:
      required_reads_before:
        - "shared-types/index.ts"
        - "shared-types/api-types.ts"  
        - "shared-types/domain-types.ts"
      mandatory_before_actions:
        - "type_definitions"
        - "interface_creation"
        - "data_modeling"
        - "api_response_typing"
      validation_rules:
        - "no_duplicate_type_names"
        - "consistent_naming_convention"
        - "required_export_validation"
        - "import_path_validation"
        - "type_extension_compliance"
      forbidden_by_mode:
        development:
          - "inline_type_definitions_without_catalog_check"
        build-to-deploy:
          - "custom_type_creation"
          - "type_name_conflicts"
          - "missing_shared_type_imports"
    
    # Code Style Constraints - Prevents naming convention drift
    code-style:
      required_reads_before:
        - "validation-schemas/code-style.json"
        - ".eslintrc.json"
        - "prettier.config.js"
      validation_rules:
        - "consistent_variable_naming" # camelCase, snake_case, PascalCase
        - "function_naming_convention"
        - "file_naming_convention"
        - "import_statement_formatting"
        - "code_formatting_compliance"
      forbidden_by_mode:
        development:
          - "mixed_naming_conventions_in_file"
        build-to-deploy:
          - "any_linting_errors"
          - "inconsistent_naming_patterns"
          - "unformatted_code"
    
    # Design System Constraints - Prevents inline styling and token drift
    design-system:
      required_reads_before:
        - "design-system/tokens.json"
        - "design-system/components/index.ts"
        - "design-system/theme.config.js"
      mandatory_before_actions:
        - "component_styling"
        - "theme_application"
        - "color_usage"
        - "spacing_application"
        - "typography_styling"
      validation_rules:
        - "token_only_styling"
        - "no_hardcoded_colors"
        - "no_hardcoded_spacing"
        - "approved_components_only"
        - "consistent_theme_usage"
      forbidden_by_mode:
        prototype:
          - "production_component_modification"
        development:
          - "inline_css_without_justification"
          - "custom_color_definitions"
        build-to-deploy:
          - "inline_styling"
          - "custom_css_classes"
          - "unapproved_design_tokens"
          - "hardcoded_design_values"
    
    # API Contract Constraints - Prevents endpoint and contract drift
    api-contracts:
      required_reads_before:
        - "api-contracts/current.json"
        - "api-contracts/endpoints.yaml"
        - "api-contracts/schemas.json"
      mandatory_before_actions:
        - "api_endpoint_calls"
        - "service_integration"
        - "data_fetching"
        - "request_response_handling"
      validation_rules:
        - "endpoint_existence_validation"
        - "request_schema_compliance"
        - "response_schema_validation"
        - "api_version_compatibility"
        - "authentication_requirement_check"
      forbidden_by_mode:
        development:
          - "undocumented_endpoint_usage"
        build-to-deploy:
          - "non_existent_endpoint_calls"
          - "deprecated_endpoint_usage"
          - "schema_mismatch_requests"
          - "missing_error_handling"
    
    # Validation Schema Constraints - Prevents validation inconsistencies
    validation-schemas:
      required_reads_before:
        - "validation-schemas/input-validation.json"
        - "validation-schemas/form-schemas.json"
        - "validation-schemas/api-validation.json"
      validation_rules:
        - "consistent_validation_patterns"
        - "required_field_validation"
        - "data_type_validation"
        - "format_validation_compliance"
      forbidden_by_mode:
        build-to-deploy:
          - "missing_input_validation"
          - "inconsistent_validation_rules"
          - "unvalidated_user_inputs"
    
    # Linting and Quality Constraints - Prevents build failures
    code-quality:
      required_reads_before:
        - ".eslintrc.json"
        - "tsconfig.json"
        - "jest.config.js"
      validation_rules:
        - "zero_linting_errors"
        - "zero_type_errors"
        - "required_test_coverage"
        - "no_console_logs_in_production"
        - "no_commented_out_code"
      forbidden_by_mode:
        development:
          - "typescript_errors_in_commit"
        build-to-deploy:
          - "any_linting_violations"
          - "typescript_compilation_errors"
          - "failing_tests"
          - "insufficient_test_coverage"

# Three-Tier Data Strategy
data_strategy:
  demo:
    storage: "sqlite"
    schema: "full_production_plus_experimental"
    purpose: "Rapid prototyping with complete data model access"
    validation_level: "basic"
    extensions_allowed: true
    
  mock:
    storage: "production_like"
    schema: "production_plus_extensions" 
    purpose: "Development testing with realistic data volumes"
    validation_level: "comprehensive"
    extensions_allowed: "tracked"
    
  production:
    storage: "production"
    schema: "catalog_only"
    purpose: "Deployment validation with real constraints"
    validation_level: "strict"
    extensions_allowed: false

# Three-Tier Deployment Strategy
deployment_strategy:
  local-dev:
    infrastructure: "docker_compose"
    complexity: "minimal"
    purpose: "Rapid iteration, team sharing, quick demos"
    validation_level: "basic"
    sharing: ["tunnels", "local_cloud"]
    
  cloud-staging:
    infrastructure: "lightweight_cloud"
    complexity: "moderate"
    purpose: "Integration testing, stakeholder reviews, CI validation"
    validation_level: "comprehensive"
    sharing: ["branch_environments", "public_urls"]
    
  production-deploy:
    infrastructure: "full_production"
    complexity: "comprehensive"
    purpose: "Production-ready deployment with full observability"
    validation_level: "strict"
    sharing: ["blue_green", "canary_releases"]

# Agent Configuration
agents:
  devLoadAlwaysFiles:
    - ".sead-core/core-config.yaml"
    - "sead-catalog/README.md"
    - "sead.config.yaml"
    
  context_preservation:
    enabled: true
    catalog_references: true
    constraint_tracking: true
    
  handoff_validation:
    enabled: true
    require_catalog_refs: true
    validate_constraints: true

# Workflow Configuration  
workflows:
  default_mode: "development"
  require_mode_explicit: false
  auto_validate_transitions: true
  
  # Command mappings (SEAD CLI to agent workflows)
  commands:
    specify: "sead-analyst"
    plan: "sead-architect"  
    stories: "sead-scrum-master"
    implement: "sead-developer"
    validate: "sead-qa"

# Tool Integration
tools:
  catalog_generator:
    enabled: true
    ai_assisted: true
    interactive_mode: true
    
  constraint_validator:
    enabled: true
    real_time: true
    blocking: true
    
  pattern_extractor:
    enabled: true
    auto_capture: true
    promotion_workflow: true

# Quality Gates
quality_gates:
  mode_transition:
    prototype_to_development:
      - "basic_validation_passes"
      - "patterns_documented"
      - "catalog_entries_created"
      
    development_to_deploy:
      - "catalog_compliance_100%"
      - "constraint_validation_passes"
      - "security_scan_passes"
      - "performance_validation_passes"

# Logging and Monitoring
logging:
  level: "info"
  constraint_violations: true
  catalog_usage: true
  mode_transitions: true
  
monitoring:
  agent_performance: true
  constraint_effectiveness: true
  catalog_coverage: true

# Document Sharding Configuration
sharding:
  enabled: true
  markdownExploder: true  # Use @kayvan/markdown-tree-parser for automatic sharding
  fallback_to_manual: true
  
  # Default sharding strategies by document type
  strategies:
    prd:
      method: "workstream"
      output_path: "docs/prd-shards/"
      index_template: "workstream-index"
      workstreams:
        - "authentication"
        - "competition" 
        - "talent"
        - "analytics"
        - "administration"
      
    architecture:
      method: "level2"
      output_path: "docs/arch-shards/"
      index_template: "technical-index"
      
    constitutional:
      method: "constitutional" 
      output_path: "docs/const-shards/"
      index_template: "principle-index"
      principles:
        - "user-autonomy"
        - "privacy-protection"
        - "educational-focus"
        - "accessibility-first"
        - "data-sovereignty"
        
    catalog:
      method: "catalog-pattern"
      output_path: "sead-catalog/shards/"
      index_template: "pattern-index"
      categories:
        - "api-contracts"
        - "auth-patterns"
        - "data-patterns"
        - "ui-patterns"
        - "integration-patterns"
        - "test-patterns"
        
    default:
      method: "level2"
      output_path: "docs/shards/"
      index_template: "basic-index"
  
  # Content preservation settings
  preservation:
    constitutional_markers: true
    catalog_references: true
    cross_references: true
    sead_templates: true
    
  # Validation settings
  validation:
    content_integrity: true
    constitutional_compliance: true
    catalog_integration: true
    reconstructible: true
    
  # Output formatting
  output:
    include_context_headers: true
    generate_navigation_index: true
    create_dependency_maps: true
    include_compliance_matrix: true