example.config.yaml

root_dir: "~/agent-os"

# Keep this config inside the repo by default:
#   ~/agent-os/config.yaml
# Keep repo-specific business objectives in the repo too, for example:
#   ~/agent-os/objectives/<repo>.yaml
# Keep raw analytics snapshots and other external evidence outside repo control, for example:
#   ~/.local/share/agent-os/evidence/<repo>/*.json

mailbox_dir: "~/agent-os/runtime/mailbox"
logs_dir: "~/agent-os/runtime/logs"
worktrees_dir: "/path/to/worktrees"
objectives_dir: "~/agent-os/objectives"
evidence_dir: "~/.local/share/agent-os/evidence"

automation_mode: full # choose dispatcher_only to skip the sprint loop

# Optional explicit overrides when the default objectives_dir lookup is not enough.
# repo_objectives:
#   yourname/repo1: "~/agent-os/objectives/repo1.yaml"
#
# Objective files define the real business target outside the managed repo, for example:
# - traffic
# - conversion
# - retention
# - ARPU

allowed_repos:
  - /path/to/repo1

default_agent: auto
default_task_type: implementation
max_runtime_minutes: 40
default_base_branch: main
default_allow_push: true
default_max_attempts: 4
max_processing_minutes: 30         # Treat processing tasks older than this as stalled when no live worker PID holds the task lock
stall_watchdog_interval_minutes: 5 # Supervisor/queue watchdog cadence for stale processing recovery; set 0 to disable
automation_mode: full                # full=planner/review/self-healing enabled, dispatcher_only=manual Ready -> dispatch -> PR only
max_parallel_workers: 1
test_timeout_minutes: 5             # Timeout for test commands (default: 5)

dashboard_bind_address: "127.0.0.1" # Set to a non-local address only with dashboard_auth_backend configured
# dashboard_auth_backend: "tailscale" # "tailscale" or "shared_secret"
# dashboard_allowed_users:
#   - "operator@example.com"
# dashboard_shared_secret: "change-me"
# dashboard_readonly_fallback: true # Optional fail-closed fallback: force localhost read-only mode when auth config is invalid

incident_router:
  business_timezone: "UTC"          # IANA timezone for next-business-hour and digest routing
  business_hours:
    start_hour: 9
    end_hour: 17
  digest_hour: 9                    # sev3 digest send hour in business_timezone
  tiers:
    sev1:
      delivery: immediate
      dedup_window_minutes: 0
      bypass_kill_switch: true
      snooze_minutes: 0
      handlers:
        - type: telegram_chat
          snooze_minutes: 0
    sev2:
      delivery: next_business_hour
      dedup_window_minutes: 60
      bypass_kill_switch: false
      snooze_minutes: 60
      handlers:
        - type: telegram_chat
          snooze_minutes: 60
    sev3:
      delivery: regular_digest
      dedup_window_minutes: 240
      bypass_kill_switch: false
      snooze_minutes: 240
      handlers:
        - type: telegram_chat
          snooze_minutes: 240
  sources:
    queue:
      default_severity: sev3
      rules:
        - type: task_failed
          blocker_code: missing_credentials
          severity: sev2
    pr_monitor:
      default_severity: sev3
      rules:
        - type: high_risk_pr
          risk_level: high
          severity: sev2
        - type: quality_harness_block
          severity: sev2
    agent_scorer:
      default_severity: sev3
    deploy_watchdog:
      default_severity: sev2

plan_size: 5                         # Number of tasks per sprint plan (default: 5)
sprint_cadence_days: 7               # Planner cadence + retrospective window in days; supports fractions, 0=dormant; actual run frequency is still capped by cron frequency
planner_allow_early_refresh: true    # If true, planner may refresh early when the current sprint empties before the next cadence tick
groomer_cadence_days: 7              # Backlog grooming cadence in days; supports fractions, 0=dormant; if unset, defaults to sprint_cadence_days * 0.5 so the groomer runs ahead of the planner
backlog_depth_multiplier: 2          # Target open backlog = plan_size * multiplier (default: 2). The groomer refills toward this target each run instead of always emitting 3-5 issues.
# target_backlog_depth: 12           # Optional absolute override for the target backlog depth; takes precedence over backlog_depth_multiplier

priority_weights:                   # Score added per priority label (default: prio:normal=10)
  prio:high: 30
  prio:normal: 10
  prio:low: 0

# Per-repo test commands (keyed by resolved repo path or repo directory name)
repo_configs:
  /path/to/repo1:
    test_command: "pytest"          # e.g. "npm test", "make test", "pytest -q"

agent_fallbacks:
  implementation: [omp, codex, claude, gemini]
  debugging: [omp, claude, codex, gemini]
  architecture: [omp, claude, codex]
  research: [omp, claude, codex]
  docs: [omp, claude, codex]
  design: [omp, claude, codex]
  content: [omp, claude, codex]
  browser_automation: [omp, claude, codex, gemini]

# Strategic planning is a control-plane task. Keep its LLM fallback narrow.
planner_agents: [omp, claude, codex]
# planner_claude_model: opus

cost_tracking:
  default_price_multiplier: 1.0      # Global adjustment when your real billed price differs from the built-in baseline
  provider_multipliers:              # Optional per-provider adjustment layer applied after baseline pricing
    anthropic: 1.0
    google: 1.0
    openrouter: 1.0
    openai: 1.0
  agent_models:                      # Default model family recorded in agent_stats.jsonl attempt metadata
    claude: "claude-sonnet-4"
    opus: "claude-opus-4"
    gemini: "gemini-2.5-flash"
    omp: "z-ai/glm-5.2"
    codex: "codex"
  model_overrides: {}                # Example:
                                     # codex:
                                     #   input_per_million_tokens: 12.0
                                     #   output_per_million_tokens: 48.0

budgets:

  # Per-agent monthly USD budget caps. Agents omitted from per_agent use
  # budgets.default when present; without a matching default they are unlimited.

  # Per-agent monthly USD budget caps. Missing agents use `default` when set;
  # otherwise they are treated as unlimited.

  # soft_warn_usd  — fires a one-time Telegram warning for the month.
  # hard_stop_usd  — removes the agent from healthy-agent selection for the
  #                  remainder of the calendar month (UTC).
  # The helper in orchestrator/budgets.py aggregates spend from
  # runtime/metrics/cost_events.jsonl so the reset boundary matches the
  # UTC calendar month every operator sees.
  default:
    soft_warn_usd: 40.0
    hard_stop_usd: 50.0
  per_agent:
    claude:
      soft_warn_usd: 80.0
      hard_stop_usd: 100.0
    codex:
      soft_warn_usd: 40.0
      hard_stop_usd: 50.0
    gemini:
      soft_warn_usd: 10.0
      hard_stop_usd: 20.0
    deepseek:
      soft_warn_usd: 10.0
      hard_stop_usd: 20.0

planning_research:
  enabled: false
  max_age_hours: 72                # Refresh stale research every 72h before planning
  max_sources: 4                   # Hard cap; first version stays intentionally small
  max_source_chars: 4000           # Per-source fetch/read cap before summarization
  allowed_domains:                 # Only used for type=web sources; host must match
    - docs.example.com
    - competitor.example.com
  dynamic_search:
    enabled: false                 # When true, generates 2-3 DuckDuckGo searches about
                                   # competitors and ecosystem before each planning cycle
    max_queries: 3                 # Hard cap on search queries per cycle
  artifact_file: "PLANNING_RESEARCH.md"
  sources:
    - name: "Official docs"
      type: "web"
      kind: "official_docs"
      url: "https://docs.example.com/product/changelog"
    - name: "Competitor pricing"
      type: "web"
      kind: "competitor"
      url: "https://competitor.example.com/pricing"
    - name: "Shared launch notes"
      type: "file"
      kind: "repo_reference"
      path: "../shared/launch-notes.md"

product_inspection:
  enabled: false                   # Opt-in: set true to inspect live product surfaces before planning
  max_age_hours: 24                # Re-inspect after this many hours
  max_targets: 4                   # Hard cap on URLs inspected per cycle
  max_target_chars: 6000           # Per-target fetch cap (text-only, after HTML stripping)
  allowed_domains:                 # Only HTTPS URLs on these domains are fetched
    - app.example.com
    - www.example.com
  artifact_file: "PRODUCT_INSPECTION.md"
  targets:
    - name: "Landing page"
      url: "https://www.example.com"
      description: "Public landing page — check messaging, CTA, broken links"
    - name: "Signup flow"
      url: "https://app.example.com/signup"
      description: "Public signup page — check form presence, error states, UX clarity"

production_feedback:
  enabled: false
  max_age_hours: 24                # Refresh stale feedback every 24h before planning
  stale_after_hours: 72            # Guardrail: older evidence is marked guarded, not planning-driving
  minimum_trust_level: "medium"    # Guardrail: low-trust inputs stay inspectable but do not drive planning
  allowed_privacy_levels:          # Guardrail: restricted inputs stay visible but are excluded from planning use
    - public
    - internal
  max_inputs: 6                    # Hard cap; keep the first version bounded
  max_source_chars: 4000           # Per-input fetch/read cap before normalization
  allowed_domains:                 # Only used for type=web inputs; host must match
    - analytics.example.com
    - community.example.com
    - status.example.com
    - app.example.com
  artifact_file: "PRODUCTION_FEEDBACK.md"
  inputs:
    # Objective-defined metrics can be injected automatically from ~/agent-os/objectives/*.yaml.
    # Keep only additional bounded signals here that are not already part of the objective spec.
    - name: "Weekly activation funnel"
      type: "web"
      signal_class: "analytics"
      url: "https://analytics.example.com/public/weekly-funnel"
      observed_at: "2026-03-19T08:00:00Z"
      provenance: "Public dashboard snapshot"
      trust_level: "high"
      trust_note: "Aggregated product analytics exported for planning"
      privacy: "public"
      privacy_note: "Aggregated public-safe metrics only"
    - name: "Community export requests"
      type: "file"
      signal_class: "user_feedback"
      path: "../shared/community-feedback.md"
      observed_at: "2026-03-18T17:00:00Z"
      provenance: "Maintainer-curated summary of public issue comments"
      trust_level: "medium"
      trust_note: "Qualitative sample; treat volume as directional"
      privacy: "public"
      privacy_note: "Summary only; no raw user identifiers"
    - name: "Signup flow inspection"
      type: "web"
      signal_class: "product_inspection"
      url: "https://app.example.com/signup"
      observed_at: "2026-03-19T09:30:00Z"
      provenance: "Maintainer walkthrough of public product surface"
      trust_level: "medium"
      trust_note: "Manual inspection; verify before large workflow changes"
      privacy: "public"
      privacy_note: "Public product surface only"
    - name: "Weekly availability summary"
      type: "file"
      signal_class: "incident_slo"
      path: "../shared/status-summary.md"
      observed_at: "2026-03-19T06:00:00Z"
      provenance: "Bounded incident summary exported from status tooling"
      trust_level: "high"
      trust_note: "Operational summary reviewed by maintainer"
      privacy: "public"
      privacy_note: "Service-level summary only; no customer-identifying logs"

external_signals:
  enabled: false
  fetch_interval_minutes: 30       # Per-source minimum fetch cadence to avoid API quota burn
  sources:
    - name: "Sentry incidents"
      enabled: false
      type: "sentry_json"
      repo: "owner/repo"
      url: "https://ops.example.com/public/sentry-feed.json"
      credential_env: "SENTRY_API_TOKEN"   # Optional; when unset the source is skipped with logging
      auth_header: "Bearer {token}"
      max_signals: 20
    - name: "Untrusted GitHub mentions"
      enabled: false
      type: "github_mentions"
      repo: "owner/repo"
      query: "\"owner/repo\" type:issue type:pr"
      max_signals: 20
    - name: "Public support feed"
      enabled: false
      type: "rss"
      repo: "owner/repo"
      url: "https://status.example.com/support.xml"
      kind: "support"
      credential_env: "SUPPORT_FEED_TOKEN" # Optional; when unset the source is skipped with logging
      auth_header: "Bearer {token}"
      max_signals: 20

outcome_attribution:
  enabled: true                        # Set true to enable post-merge outcome measurement
  max_source_chars: 4000
  allowed_domains:
    - analytics.example.com
  checks:
    # Outcome checks are also injected automatically from objectives/*.yaml.
    # The objective file's outcome_check blocks (github_stars, github_forks,
    # task_success_rate, completion_time, escalation_rate) are merged in at
    # runtime. Keep explicit entries here for non-objective checks only.
    # Baseline metrics (stars, forks, operational stats) are automatically
    # captured at merge time and passed to the evaluation prompt.
    - id: "activation_rate"
      name: "Activation rate"
      type: "web"
      url: "https://analytics.example.com/public/activation-after-release"
      measurement_window_days: 7
      comparison_window: "Compare 7 days after merge vs 7 days before merge"
    - id: "community_feedback"
      name: "Community feedback pulse"
      type: "file"
      path: "../shared/community-feedback-after-release.md"
      measurement_window_days: 3
      comparison_window: "Compare the post-release comment volume against the prior 3 days"

quality_harness:
  enabled: false                       # Opt-in per repo; repos without explicit suites keep pytest-only gating
  operator_approved: false             # Architect can propose plans immediately; implementation issues wait for approval
  score_threshold: 0.9                 # PRs must meet this eval score before auto-merge
  suites: []                           # Fixed taxonomy only: unit, api_contract, browser_e2e, visual_regression,
                                       # multimodal_eval, llm_judge_eval, bot_conversation_eval
  suite_commands: {}                   # Optional per-suite command; may print JSON {"score": 0.95, "failing_fixtures": [...]}

tool_registry:
  verified_packages_file: "verified_packages.yaml"  # Operator-curated package allowlist with pinned versions + sha256
  library_catalog_file: "library_catalog.yaml"      # Operator-curated suggestion catalog; scout never invents packages
  mcp_servers:
    linear_mcp:
      title: "Linear MCP"
      package: "@acme/mcp-linear"
      version: "1.2.3"                               # Required pin; @latest is banned
      sha256: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      command: ["npx", "-y", "@acme/mcp-linear@1.2.3"]
      env:
        LINEAR_API_KEY: "${LINEAR_API_KEY}"          # Env-var reference only; raw secrets are forbidden
      task_permissions:
        groomer: ["issues:read", "issues:write"]
        research: ["issues:read"]
    browser_mcp:
      title: "Browser MCP"
      package: "@acme/mcp-browser"
      version: "0.4.1"
      sha256: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      command: ["npx", "-y", "@acme/mcp-browser@0.4.1"]
      env:
        BROWSER_API_KEY: "${BROWSER_API_KEY}"
      task_permissions:
        quality_harness: ["browser:run", "browser:screenshot"]
  http_apis:
    receipt_ocr_api:
      title: "Receipt OCR API"
      base_url: "https://ocr.example.com/v1"
      credential_env: "OCR_API_KEY"                 # Env-var reference only
      task_permissions:
        quality_harness: ["ocr:extract"]
        implementation: ["ocr:extract"]

library_scout:
  enabled: true
  cadence_days: 30                    # Monthly scout cadence
  max_suggestions_per_repo: 3

semantic_dedup:
  enabled: true                         # Groomer suppresses near-duplicate issues before filing them
  threshold: 0.82                       # Per-repo override: semantic_dedup_threshold or semantic_dedup.threshold
  recently_closed_days: 90              # Compare proposed issues against recently closed work too
  model: "sentence-transformers/all-MiniLM-L6-v2"
  fallback: "simhash"                   # Local deterministic fallback when sentence-transformers/model load fails

system_architect:
  enabled: true                        # Compares current agent-os topology against target_operating_model.yaml
  cadence_days: 30                     # Monthly default; capability/sensor topology shifts slower than sprint work
  target_model: "target_operating_model.yaml"

dependency_watcher:
  enabled: true                        # Weekly dependency/CVE watcher; set false to disable globally
  cadence_days: 7                      # Per-repo scan cadence; 0 makes the watcher dormant
  max_actions_per_week: 3              # Cap total PRs + issues per repo per ISO week to prevent flood

deploy_watchdog:
  enabled: false                       # Opt-in per repo; when enabled, checks recent merges every cron run
  window_minutes: 60                   # Watch merges and signals in this post-merge window
  error_rate_spike_ratio: 2.0          # Regression when post-merge error rate exceeds 2x baseline
  latency_p95_spike_ratio: 1.5         # Regression when post-merge p95 exceeds 150% of baseline

agent_timeout_minutes:
  codex: 40
  claude: 45
  gemini: 35
  omp: 30

github_owner: "yourname"
github_project_number: 1
github_project_status_field: "Status"
github_project_ready_value: "Ready"
github_project_in_progress_value: "In Progress"
github_project_blocked_value: "Blocked"
github_project_done_value: "Done"

github_repos:
  repo1: "yourname/repo1"
  repo2: "yourname/repo2"

github_projects:
  example-project:
    planner_allow_early_refresh: false  # Optional project default: follow cadence strictly unless a repo overrides this
    repos:
      - github_repo: "yourname/repo1"
        path: "/path/to/repo1"
        automation_mode: full             # Full automation: planner/groomer/analyzer/pr_monitor stay enabled
        enabled_tools: [linear_mcp, receipt_ocr_api] # Explicit opt-in; repos without this keep adapter defaults
        plan_size: 3
        sprint_cadence_days: 1      # Daily planning for this repo
        planner_allow_early_refresh: true  # Optional per-repo override
        groomer_cadence_days: 0.5   # Groom every 12 hours for this repo; requires cron to run at least every 12 hours
        # Pair this repo with ~/agent-os/objectives/repo1.yaml
        # so planning and scoring are anchored to external business outcomes.
        planning_research:
          enabled: true
          allowed_domains:
            - docs.example.com
          sources:
            - name: "Repo1 docs"
              type: "web"
              kind: "official_docs"
              url: "https://docs.example.com/repo1"
        product_inspection:
          enabled: true
          allowed_domains:
            - app.example.com
          targets:
            - name: "Repo1 app"
              url: "https://app.example.com/repo1"
              description: "Main product surface for repo1"
        quality_harness:
          enabled: true
          operator_approved: false
          score_threshold: 0.9
          suites: [unit, multimodal_eval]
          suite_commands:
            unit: "pytest -q"
            multimodal_eval: "python3 -m repo1.eval --json"
        library_scout:
          cadence_days: 30
        production_feedback:
          enabled: true
          stale_after_hours: 48
          allowed_privacy_levels:
            - public
            - internal
          allowed_domains:
            - analytics.example.com
          inputs:
            - name: "Repo1 activation"
              type: "web"
              signal_class: "analytics"
              url: "https://analytics.example.com/repo1"
              observed_at: "2026-03-19T08:00:00Z"
              provenance: "Public repo metrics snapshot"
              trust_note: "Aggregated public metrics"
              privacy_note: "No user-level data"
        outcome_attribution:
          enabled: true
          checks:
            - id: "repo1_activation"
              name: "Repo1 activation"
              type: "web"
              url: "https://analytics.example.com/repo1-post-merge"
              measurement_window_days: 7
              comparison_window: "Compare 7 days after merge vs 7 days before merge"
        deploy_watchdog:
          enabled: true
          window_minutes: 60
          error_rate_spike_ratio: 2.0
          latency_p95_spike_ratio: 1.5
      - github_repo: "yourname/repo2"
        path: "/path/to/repo2"
        automation_mode: dispatcher_only  # Dispatch only: manual Ready -> dispatch -> PR, no planner/groomer/analyzer/pr_monitor
        plan_size: 5
        sprint_cadence_days: 0            # Dormant because this repo is dispatch-only
        groomer_cadence_days: 0           # Dormant because this repo is dispatch-only
        # Pair this repo with ~/agent-os/objectives/repo2.yaml if you still want
        # external objective scoring for manually dispatched work.
        planning_research:
          enabled: false
        product_inspection:
          enabled: false
        production_feedback:
          enabled: false
        outcome_attribution:
          enabled: false
        deploy_watchdog:
          enabled: false

telegram_bot_token: "YOUR_TELEGRAM_BOT_TOKEN"
telegram_chat_id: "YOUR_CHAT_ID"

# Blocker regression alert thresholds (rolling 24h window, forward-looking).
# Telegram alert fires when a blocker code exceeds its threshold.
# RCA runbook: identify affected task IDs → check prompt snapshots →
# determine which dispatch context was missing → verify write_prompt() injection.
blocker_regression_alerts:
  missing_context: 5