foundation-config.yaml

# Foundation Configuration Template
# Configure all foundation processes for your repository

# Repository information
repository:
  name: "neotoma"
  type: "application"
  languages:
    - "typescript"
    - "sql"
    - "yaml"
    - "shell"

# Development workflow configuration
development:
  # Branch strategy
  branch_strategy:
    main_branches:
      - "main"
      - "dev"
    feature_prefix: "feature"
    bugfix_prefix: "bugfix"
    hotfix_prefix: "hotfix"
    release_prefix: "release"
    naming_pattern: "{prefix}/{description}"
    require_id: true  # whether ID is required in branch names
  
  # Workflow preferences
  workflow:
    use_worktrees: true
    worktree_base_path: "../{repo}-{branch}"
    env_copy_script: "scripts/copy-env-to-worktree.js"  # optional
  
  # Commit format
  commit_format:
    require_id: true  # whether ID is required in commit messages
    require_references: false  # whether "References:" line is required
    pattern: "{description}"
  
  # Commit workflow configuration
  commit:
    migrate_plans: true  # Enable automatic plan migration during commit
    migrate_plans_config:
      proposals_dir: "docs/proposals"
      archive_completed: true
      auto_remove_obsolete: false  # Require manual confirmation for removal
  
  # Pull requests
  pull_requests:
    require_id_in_title: true
    title_pattern: "{description}"
    min_approvals: 1
    high_risk_approvals: 2
    require_review_from_code_owners: false
    merge_strategy: "squash"  # or "merge", "rebase"
    delete_branch_on_merge: true
    require_linear_history: false
  
  # Publish command configuration
  publish:
    enabled: true
    integration_branch: "dev"  # Branch to merge from
    main_branch: "main"  # Branch to merge to
    create_release_doc: true  # Create release documents
    release_type: "not_marketed"  # Default release type for incremental releases
    deployment:
      enabled: true
      provider: "fly"  # Deployment provider (fly, custom, etc.)
      run_migrations: true  # Run database migrations on deploy
      smoke_tests: true  # Run smoke tests after deploy
      health_check_url: "https://app.neotoma.app/health"  # Health check endpoint
    versioning:
      planned_release_pattern: "v*.*.0"  # Pattern for planned releases (vX.Y.0)
      incremental_release_patch_only: true  # Incremental releases only increment patch
      initial_version: "v0.1.0"  # Initial version if no planned release exists
      detection:
        check_status_changes: true  # Detect planned releases via status.md changes
        check_new_directories: true  # Detect planned releases via new release directories
        check_commit_messages: true  # Detect planned releases via commit messages
    submodules:
      # Per-submodule configuration (optional)
      foundation:
        deployment:
          enabled: false  # Submodules may not need deployment
        version_file: "package.json"  # Version file to update (null for git tags only)

# Code conventions
conventions:
  typescript:
    files: "snake_case"  # Neotoma uses snake_case
    components: "PascalCase"  # React components
    functions: "camelCase"
    types: "PascalCase"
    interfaces: "PascalCase"
    variables: "camelCase"
    constants: "UPPER_SNAKE_CASE"
    classes: "PascalCase"
    string_quotes: "double"  # or "single"
    prefer_named_exports: true
    import_order:
      - "external"  # node_modules
      - "internal"  # from src/
      - "relative"  # ./ or ../
  
  sql:
    tables: "snake_case"  # Always plural
    columns: "snake_case"
    indexes: "idx_{table}_{columns}"
    constraints: "{table}_{constraint_type}"
    policies: "{action} - {table}"  # if using RLS
    use_rls: false  # Postgres Row Level Security
    timestamp_columns:
      created: "created_at"
      updated: "updated_at"
      deleted: "deleted_at"
  
  yaml:
    keys: "snake_case"
    indentation: 2
    use_quotes: "when_needed"  # or "always", "never"
    boolean_style: "lowercase"  # true/false
  
  shell:
    constants: "UPPER_SNAKE_CASE"
    local_variables: "lowercase"
    functions: "snake_case"  # or "camelCase"
    scripts: "kebab-case.sh"

# Testing configuration
testing:
  framework: "vitest"  # or "jest", "mocha", "pytest", "go test"
  coverage:
    domain_logic: 85
    application_layer: 80
    ui_components: 75
    infrastructure: 70
  test_types:
    - "unit"
    - "integration"
    - "e2e"
  test_file_suffix: ".test.ts"  # or ".spec.ts", "_test.py"

# Documentation standards
documentation:
  required_sections:
    - "Purpose"
    - "Scope"
    - "Agent Instructions"  # Neotoma requires Agent Instructions
  structure:
    manifest_path: "docs/NEOTOMA_MANIFEST.md"
    architecture_path: "docs/architecture/"
    foundation_path: "docs/foundation/"
  validation:
    check_dependencies: true  # Neotoma validates doc dependencies
    check_links: true
    enforce_agent_instructions: true  # Neotoma enforces Agent Instructions
  writing_style:
    avoid_ai_patterns: true
    require_rfc_2119: true  # MUST/MUST NOT language
    max_sentence_length: null  # or number for enforcement

# Validation systems
validation:
  spec_compliance:
    enabled: true  # Neotoma validates spec compliance
    spec_paths:
      - "docs/specs/**/*.md"
      - "docs/features/**/*.md"
    requirement_patterns:
      - "MUST"
      - "MUST NOT"
      - "SHALL"
      - "REQUIRED"
    check_types:
      - "code_existence"
      - "database_schema"
      - "validation_logic"
      - "testing"
  
  doc_dependencies:
    enabled: true  # Neotoma tracks doc dependencies
    dependency_map_path: "docs/doc_dependencies.yaml"
    check_on_commit: false
    auto_suggest_updates: false

# Security configuration
security:
  enabled: true
  pre_commit_audit:
    enabled: true
    protected_paths:
      - "docs/private/"  # Neotoma private docs
      - "data/"          # Neotoma data directory
    protected_patterns:
      - "\\.env"
      - "secrets"
      - "credentials"
    check_env_files: true
    check_data_directory: true  # Neotoma has data/ directory
  credential_management:
    enabled: true
    require_env_separation: false  # whether to require DEV_*/PROD_* prefixes
    secrets_manager:
      enabled: false
      storage_path: ".secrets/secrets.enc"
      key_path: ".secrets/.key"
      algorithm: "aes-256-gcm"
      master_key_env: "SECRETS_MASTER_KEY"

# Tooling configuration
tooling:
  secrets:
    enabled: false
    storage_path: ".secrets/secrets.enc"
    key_path: ".secrets/.key"
    algorithm: "aes-256-gcm"
    master_key_env: "SECRETS_MASTER_KEY"
  
  env_management:
    enabled: true
    env_file_priority:
      - ".env.dev"
      - ".env"
      - ".env.development"
    worktree_detection:
      cursor_worktrees: true
      custom_patterns: []
    environment_separation:
      enabled: false
      dev_prefix: "DEV_"
      prod_prefix: "PROD_"
      require_explicit_env: false  # whether to prevent generic variables
    onepassword_sync:
      enabled: true
      # Inclusion list (whitelist) - if specified, ONLY these variables will be synced
      # If not specified, all variables with mappings in parquet will be synced
      # Supports two formats:
      #   1. Flat list: inclusions: [VAR1, VAR2, ...]
      #   2. Nested from expected_variables (automatically flattened)
      expected_variables:
        # Required for Neotoma to function (environment-based, set by 1Password sync)
        required:
          - DATABASE_URL  # Environment-based (dev/prod selected automatically)
          # Run: npm run generate:connector-key
        # Recommended for full functionality
        recommended:
          - OPENAI_API_KEY  # Environment-based (dev/prod selected automatically)
          - ACTIONS_BEARER_TOKEN  # Environment-based (dev/prod selected automatically) - HTTP Actions API auth
          - CURSOR_CLOUD_API_KEY  # For multi-agent orchestration
          - NGROK_AUTHTOKEN  # For HTTPS tunneling (development environment)
        # Optional, feature-specific
        optional: []
        # Backward compatibility: DEV_*/PROD_* prefixed variables still supported
        # but deprecated in favor of environment-based single variable names
      # Alternative: Use flat list format instead of expected_variables
      # inclusions:
      #   - DATABASE_URL
      #   - OPENAI_API_KEY
      # Variables to exclude from 1Password sync (preserved from existing .env)
      # These are local development values that shouldn't be synced
      default_exclusions:
        # Local development variables (not secrets, should remain local)
        - PORT
        - NEOTOMA_PORT
        - HTTP_PORT
        - NEOTOMA_HTTP_PORT
        - WS_PORT
        - NEOTOMA_WS_PORT
        - NEOTOMA_HOST_URL
        - FRONTEND_URL
        - NEOTOMA_FRONTEND_URL
        - MCP_PROXY_URL
        - NEOTOMA_MCP_PROXY_URL
        - OAUTH_REDIRECT_BASE_URL
        - NEOTOMA_OAUTH_REDIRECT_BASE_URL
        - MCP_TOKEN_ENCRYPTION_KEY
        - NEOTOMA_MCP_TOKEN_ENCRYPTION_KEY
        - MCP_CMD
        - NEOTOMA_MCP_CMD
        - MCP_ARGS
        - NEOTOMA_MCP_ARGS
        # Note: ACTIONS_BEARER_TOKEN is now managed by 1Password sync (removed from exclusions)
        - VITE_WS_PORT
        - VITE_LOCAL_MCP_URL
        - VITE_MCP_URL
        - VITE_API_BASE_URL
        - VITE_AUTO_SEED_RECORDS
        - NEOTOMA_ENV
        - NODE_ENV
        - NEOTOMA_ACTIONS_DISABLE_AUTOSTART
        - BRANCH_PORTS_FILE
        # Icon generation (local dev)
        - ICON_GENERATION_ENABLED
        - NEOTOMA_ICON_GENERATION_ENABLED
        - ICON_MATCH_CONFIDENCE_THRESHOLD
        - NEOTOMA_ICON_MATCH_CONFIDENCE_THRESHOLD
        - ICON_GENERATION_MODEL
        - NEOTOMA_ICON_GENERATION_MODEL
        - ICON_CACHE_TTL
        - NEOTOMA_ICON_CACHE_TTL
      # Instance-specific exclusions go in foundation-config.local.yaml (gitignored)
  
  agent_setup:
    enabled: false
    database:
      type: null  # "postgres", "mysql", etc.
      migration_command: null  # "npm run migrate" or custom
      fallback_script: null  # "scripts/apply_migrations.js"
    tools: []
      # - name: "playwright"
      #   install_command: "npx playwright install --with-deps chromium"
      # - name: "database_cli"
      #   verify_command: "psql --version"
  
  # Error reporting configuration
  error_reporting:
    enabled: true
    auto_detect: true
    auto_classify_bugs: true
    severity_threshold: "medium"
    max_stack_trace_length: 5000
    retention_days: 30
    output_directory: ".cursor/error_reports"
    
    # Wait mode configuration
    wait_mode:
      enabled: true
      default_timeout: 300  # seconds (5 minutes)
      default_poll_interval: 5  # seconds
      max_timeout: 3600  # 1 hour maximum
      min_poll_interval: 1  # minimum poll interval
  
  # Error debugging automation (repo-specific scripts)
  error_debugging:
    enabled: true
    automation:
      type: "cursor_cli"  # "cursor_cli" | "cloud_agents" | "disabled"
      trigger_on_error: true  # Auto-trigger debugging when error reported
      watch_mode: false  # Continuous monitoring (optional)
      cursor_cli:
        command: "cursor"  # Cursor CLI command (cursor agent)
        working_dir: "."  # Workspace directory for agent
        force: true  # Force allow commands (--force flag)
        approve_mcps: true  # Auto-approve MCP servers (--approve-mcps flag)
        # Legacy keyboard automation settings (not used in headless mode)
        platform: "darwin"  # Deprecated: kept for backwards compatibility
        clipboard_command: "pbcopy"  # Deprecated: not used in headless mode
        keyboard_shortcut: "cmd+l"  # Deprecated: not used in headless mode
        delay_before_shortcut_ms: 2000  # Deprecated: not used in headless mode
  
  readme_generation:
    enabled: false
    source_documents: []
      # - "docs/foundation/core_identity.md"
      # - "docs/specs/overview.md"
    structure_template: null  # "templates/readme-structure.md"
    regenerate_triggers: []
      # - "docs/foundation/**/*.md"
      # - "docs/specs/**/*.md"

# Agent instructions configuration
agent_instructions:
  enabled: true
  location: "docs/foundation/agent_instructions.md"
  cursor_rules:
    enabled: true
    location: ".cursor/rules/"
    generic_rules:
      - security
      - worktree_env
      - readme_maintenance
      - downstream_doc_updates
      - instruction_documentation
    custom_rules: []  # Repo-specific rules (most workflow rules now in foundation)
  cursor_commands:
    enabled: true
    location: ".cursor/commands/"
    generic_commands:
      - commit
      - publish
    custom_commands:
      - create_plan
      - release
      - fix_feature_bug
      - run_feature_workflow
      - ui_workflow
      - modify-subsystem
      - ingestion-flow
      - gather_ux_input
      - create_prototype
      - final_review
  constraints: []
    # Project-specific constraints
    # - "Never commit secrets"
    # - "Always update documentation when code changes"
  validation_checklist:
    enabled: true
    custom_checks: []  # Repo-specific checks

# Strategy evaluation (optional)
strategy:
  discovery:
    enabled: false
    framework: "cagan"  # or "lean", "jobs-to-be-done"
    risks:
      value:
        enabled: false
        method: "interviews"  # or "surveys", "prototypes"
        success_threshold: 70  # % validating problem
        min_participants: 5
      usability:
        enabled: false
        method: "prototype_testing"
        success_threshold: 80  # % completing workflows
        min_participants: 5
      feasibility:
        enabled: false
        method: "poc"  # or "architectural_review"
        success_criteria: "meets_requirements"
      business_viability:
        enabled: false
        method: "pricing_interviews"
        success_threshold: 50  # % willing to pay
        min_participants: 5
    mom_test:
      enabled: false
      require_live_interviews: false
      commitment_signals:
        - "time_spent"
        - "money_spent"
        - "reputation_risk"
        - "emotional_intensity"
    continuous_discovery:
      enabled: false
      frequency: "weekly"  # or "bi-weekly", "monthly"
      min_participants_per_cycle: 2

# Plan workflow — plans are stored as Neotoma entities, not repo files.
# See foundation/development/plan_workflow.md for the complete workflow.
plans:
  enabled: true
  mirror_profile: "neotoma-plans"   # Default profile id in canonical_mirror.ts
  mirror_output_path: "docs/plans"  # Repo-relative path where plans are mirrored

# Release orchestration (optional)
orchestration:
  release:
    enabled: true
    execution_strategy: "sequential"  # or "multi_agent", "parallel"
    max_parallel_items: 3
    agent_spawning:
      enabled: false  # Requires Cursor Cloud API
      api_url: "${CURSOR_CLOUD_API_URL}"
      api_key: "${CURSOR_CLOUD_API_KEY}"

# Neotoma-specific extensions
custom:
  determinism:
    enabled: true
    no_random_ids: true
    no_current_timestamps: true
    hash_based_ids: true
  truth_layer:
    enabled: true
    no_strategy_logic: true
    no_execution_logic: true
  spec_compliance:
    enabled: true
  doc_dependencies:
    enabled: true