project.yaml.example

orchestrator_version: "1.0"
name: "Sample Project"
description: "A demonstration project for the Orchestrator."
language: "python"
repo_path: "."
devplan_dir: "devplan"

llm:
  provider: "openrouter"
  model: "anthropic/claude-3.5-sonnet"
  api_key_env_var: "OPENROUTER_API_KEY"
  temperature: 0.1

task_processors:
  - type: "markdown_planner"
    settings:
      status_key: "status"
      target_files_key: "files_to_modify"
      test_command_key: "test_command"
      max_retries_per_task: 3

tools:
  - name: "Git"
    type: "git"
  - name: "Python Formatter"
    type: "formatter"
    command: "black {path}"
  - name: "Python Test Runner"
    type: "test_runner"
    command: "pytest"

environment:
  type: "venv"
  root_dir: ".venv"
  setup_commands:
    - "python -m venv {root_dir}"
    - "pip install pytest black"

# Container environment (opt-in). type: docker|container runs gate commands
# (build/lint/test/golden) inside a throwaway OCI container against the
# bind-mounted repo, so the toolchain is pinned and reproducible. Detection
# prefers rootless engines (podman) then docker/nerdctl/colima; if no engine is
# reachable, gates run locally exactly as today (never hard-fails). Git stays
# host-side. Image is auto-detected from `language` if `image` is omitted.
# environment:
#   type: "docker"
#   image: "python:3.12-slim"   # optional; else auto from language
#   engine: "podman"            # optional; else rootless-first auto-detect
#   memory: "512m"              # optional; cap container memory (docker --memory)
#   cpus: "1.5"                 # optional; cap container CPUs (docker --cpus)
#   pids_limit: 2048            # optional; cap process count (fork-bomb guard)
#   cap_drop: ["ALL"]           # optional; drop Linux capabilities (--cap-drop)
#   security_opt: ["no-new-privileges"]  # optional; --security-opt (seccomp etc.)

# Runtime smoke gate (opt-in, off by default). Set orchestrator.runtime_smoke
# true and describe how to launch/probe the built artifact. Runs in a daemon
# thread with a hard timeout so it can never block the build; missing config or
# a timeout is a SKIP (not a failure). RED (non-zero exit or missing `expect`)
# blocks the build.
# orchestrator:
#   runtime_smoke: true
# runtime:
#   smoke:
#     launch: "./target/debug/myapp --serve"
#     ready: "listening on"      # optional readiness substring in output
#     probe: "ping"              # optional text piped to stdin once ready
#     expect: "pong"             # substring asserted in output -> GREEN
#     timeout: 30

# Web verification gate (opt-in, off by default). Requires the [web] extra
# (`pip install -e '.[web]'` + `playwright install chromium`). Drives a headless
# browser against the running web artifact and runs declarative checks. Daemon
# thread + hard timeout so it can never block; no config or no Playwright/browser
# is a SKIP. RED only on a failed check (missing selector/text, a console error,
# an axe violation, or a screenshot diff beyond threshold).
# orchestrator:
#   web_verify: true
# runtime:
#   web:
#     serve: "npm run dev"          # optional; started before loading url
#     url: "http://localhost:5173"
#     ready: "Local:"               # optional readiness substring in serve output
#     checks:                       # any of dom:/text:/no-console-errors/axe/screenshot
#       - "dom:#app"
#       - "text:Welcome"
#       - "no-console-errors"
#       - "axe"
#       - "screenshot"
#     baseline_dir: ".orchestrator" # where baseline/evidence images live
#     threshold: 0.02               # screenshot diff fraction that fails
#     timeout: 60

# Vision verification gate (opt-in, off by default). Asks the project's vision
# model whether a captured screenshot satisfies a stated requirement. Daemon
# thread + hard timeout; no config / no model / no network is a SKIP. RED only
# when the model denies the assertion.
# orchestrator:
#   vision_verify: true
# runtime:
#   vision:
#     capture: ".orchestrator/web_verify_evidence.png"  # screenshot to judge
#     assert: "the dashboard shows a bar chart and no error banner"
#     model: "anthropic/claude-sonnet-4.6"  # optional vision-capable model id
#     timeout: 60

# MCP (Model Context Protocol) tool-host substrate (opt-in, off by default).
# Requires the [mcp] extra (`pip install -e '.[mcp]'`). Connects to the stdio
# servers below, discovers their tools (project.mcp.tools), and can call one
# (project.mcp.call_tool). Daemon thread + hard timeout throughout; a missing
# SDK, a server that won't start, or one that hangs is simply absent — never an
# error or a hang. mcp_enabled gates only the awareness injection: when on, the
# discovered tools are described to the model in the task context (additive; the
# single-shot build loop is unchanged).
#
# mcp_tool_use (off by default) layers a BOUNDED agentic pre-edit loop on top:
# when on (and tools were discovered), the model may request MCP tool calls to
# gather information BEFORE editing. Each round it sees the tools and may reply
# with one line `CALL <server>.<tool> {json-args}` (or NO_TOOL to stop); the call
# runs via the timeout-guarded call_tool and the result is prepended to the task
# context. mcp_max_tool_rounds (default 3) hard-caps the loop. Additive: off =>
# the edit path is byte-identical to today; any failure degrades to gathering
# nothing.
# orchestrator:
#   mcp_enabled: true
#   mcp_tool_use: true        # enable the bounded agentic gathering loop
#   mcp_max_tool_rounds: 3    # hard cap on gathering rounds
# mcp:
#   servers:
#     - name: "docs"                  # routing key for call_tool
#       command: "my-mcp-server"      # executable launched as a stdio subprocess
#       args: ["--root", "."]         # optional
#       transport: "stdio"            # only stdio is supported today

# Goal-completion check (opt-in, off by default). An LLM judge reads the goal,
# the tasks' acceptance criteria, and the build's cumulative diff and reports
# whether the goal is actually met — "gates green != goal met". ADVISORY by
# default: gaps are recorded in the report and logged but do NOT fail the build.
# Set block_on_goal_gap true to make an unmet goal fail the build. Daemon thread
# + hard timeout; no goal/criteria/client, an unparseable verdict, or a timeout
# is a SKIP (never blocks, never hangs).
# orchestrator:
#   goal_check: true
#   block_on_goal_gap: false   # true => a GAP verdict fails the build
#   goal_check_timeout: 60

# Adversarial critic (opt-in, off by default). An INDEPENDENT second component
# reviews each candidate edit BEFORE it is applied; a rejection feeds concrete
# objections back to the generator for the next attempt. Set critic.model to a
# DIFFERENT model than the generator so the reviewer doesn't share its blind
# spots (a same-model critic still runs but is weaker, and that is logged). It is
# advisory — the build/test gates remain authoritative; critic_max_rejections
# caps how many regenerations it may force before deferring to those gates.
# Daemon thread + hard timeout; no client / unparseable verdict / timeout = SKIP.
# orchestrator:
#   adversarial_critic: true
#   critic_max_rejections: 2   # regenerations the critic may force before deferring
#   critic_timeout: 60
# critic:
#   model: "anthropic/claude-opus-4-8"   # independent reviewer model (optional)
#   panel: 3                             # reviewers run concurrently; majority rejects

# Independent JUDGE model for the post-build goal-completion check and the LLM
# acceptance judge (distinct from critic.model, which is edit-time). Optional;
# set to a model different from the generator so those judgments don't share its
# blind spots. Unset => each judge runs on the generator's own model.
# judge:
#   model: "anthropic/claude-opus-4-8"

# Mutation-score gate (opt-in, off by default). Runs the project's configured
# mutation-testing command and asserts the parsed score meets a floor — proving
# the suite kills injected faults, not just passes. Tool-agnostic: supply any
# command (mutmut, cosmic-ray, cargo-mutants, Stryker, ...). Daemon thread + hard
# timeout; no config, an unparseable score, or a timeout is a SKIP (not a RED).
# Only a parsed score below min_score is a RED that blocks the build (G3.6).
# orchestrator:
#   mutation_gate: true
# mutation:
#   command: "mutmut run && mutmut results"   # any command that prints a score
#   min_score: 0.8        # floor; a fraction (0.8) or a percentage (80)
#   timeout: 1800         # seconds (mutation runs are slow)

# Spec-as-tests (opt-in, off by default). Generates a failing test from a task's
# acceptance criteria before it is implemented, then requires it to pass once the
# task is built (red->green TDD per task). The generated test is written under
# .orchestrator/spec_tests/ (OUTSIDE the project suite, so it never flips the
# integration-gate baseline) and run scoped to its file after the task's gates
# pass. ADVISORY by default (a still-red spec test is logged, not fatal — the
# generated test may be imperfect); set spec_as_tests_block for strict TDD.
# Scoped runs support pytest/jest-style suites; other languages SKIP.
# orchestrator:
#   spec_as_tests: true
#   spec_as_tests_block: false   # true => a still-failing spec test fails the task

# Governance layer (opt-in, off by default). A precise risk classifier gates
# executor commands that are destructive/irreversible/paid (rm -rf, git push
# --force, DROP TABLE, kubectl delete, terraform destroy, aws/gcloud/az delete,
# docker rmi / system prune, deploy/publish, curl|sh) while ordinary build/test/
# lint commands run untouched. When ON in autonomous mode a risky command is
# BLOCKED and an escalation is recorded unless auto_approve is set; OFF (default)
# leaves the command path byte-identical to today. Interactive prompting is a
# deferred seam (autonomous runs block rather than hang on stdin). An append-only
# audit trail is written to .orchestrator/audit.jsonl regardless (on by default,
# gitignored; never breaks a build).
# orchestrator:
#   governance: true
# governance:
#   auto_approve: false           # true => risky commands run unattended
#   approval_required:            # extra risky regex patterns (matched case-insensitively)
#     - "\\bhelm\\s+delete\\b"
#   network: "none"               # container egress: "none" runs gate commands with
#                                 # --network none. CONTAINER-ONLY (environment.type:
#                                 # docker); host execution and git keep their network.

# Empirical probe discovery (SMART/CREATE Phase 1.5) grounds the spec with an
# LLM call + ephemeral script runs before planning. On by default; set false for
# a cheaper/faster run that skips that pre-work.
# orchestrator:
#   enable_probes: false

# Multi-target (polyglot) gate routing. For a monorepo with sub-projects in
# different languages, declare each with its own toolchain; a task's gate is
# routed to the target that owns its files. A matched target is self-contained —
# only the commands it lists run (others are skipped, NOT inherited, so a web
# task is never gated by cargo). The top-level build/test/lint apply only to files
# outside every target. Omit entirely for a single-language project.
# Zero-config alternative: set `orchestrator.auto_targets: true` to auto-detect
# sub-projects (best-effort commands); an explicit `targets` list always wins.
# targets:
#   - name: core
#     path: emathy-core
#     build_command: "cargo build -p emathy-core"
#     test_command: "cargo test -p emathy-core --lib"
#   - name: web
#     path: clients/web
#     build_command: "npm run typecheck"   # tsc --noEmit; no unit tests yet
#     # Opt-in behavioral verification for a frontend target: render + check it
#     # actually works (not just type-checks). Best-effort; only a failed check
#     # fails the target. `vision` judges the web gate's screenshot via a VLM.
#     web: { serve: "npm run serve", url: "http://localhost:8000", checks: ["#app"] }
#     vision: { assert: "the editor toolbar is visible" }   # judges the web gate's screenshot

# Build workflow settings (6-phase autonomous builder)
build:
  max_tasks: 30   # also overridable per-run with the CLI flag --max-tasks N
  max_attempts_per_task: 3
  max_consecutive_failures: 3
  build_timeout: 120
  test_timeout: 180
  lint_timeout: 120
  parallel_analysis: true

# Commands for health checks and validation
build_command: "python -m py_compile *.py"
test_command: "pytest"
lint_command: "black --check ."

prompt_templates:
  system: |
    You are an expert AI developer.
    Always output code in markdown code blocks with file path comments.
    {inherited_system_prompt}
  task_completion_instruction: |
    Implement: {task.description}
    Files: {task.target_files}
    Context:
    {code_context}
  error_correction_instruction: |
    Fix this error:
    {error_logs}