Configuration

Dark Factory is configured through godark.yaml in your project root, with CLI flags available as overrides.

godark.yaml

Here's a complete example showing all available fields:

# ── Required ──
repo: owner/my-project

# ── Build Commands ──
format_command: "gofmt -w ."
build_command: "go build ./..."
test_command: "go test ./..."
lint_command: "golangci-lint run"
generate_command: "go generate ./..."

# ── Agent Behavior ──
max_retries: 3                    # Review/fix retry cycles per issue
max_resume_retries: 2             # At attempt N >= this, start fresh session
max_rebase_attempts: 1            # Auto-rebase cycles before needs-human-review
agent_timeout: "30m"              # Timeout per agent execution
quality_strictness_decay: true    # Relax quality gates on successive retries

# ── Safety ──
no_sandbox: false                 # true = run on host, false = Docker (default)
protected_paths:                  # Files agents cannot modify
  - godark.yaml
  - CLAUDE.md
denied_commands:                  # Patterns forbidden in agent execution
  - "rm -rf"
  - "git push --force"
  - "git reset --hard"

# ── Paths ──
roadmap_path: "docs/ROADMAP.md"
planning_dir: "docs/planning/"
scenario_dir: "tests/scenarios/"
review_dir: "tests/review/"
architecture_doc: "docs/architecture.md"
architecture_json: "docs/architecture.json"
conventions_doc: "docs/conventions.md"
base_branch: "main"

# ── Auth ──
auth_preference: "oauth"          # "oauth" or "api_key"
required_env:                     # Must be set before run starts
  - CUSTOM_API_KEY

Runtime & Docker

Configure the project runtime and Docker sandbox settings:

runtime:
  name: "go"                       # go, flutter, node, rust, python, elixir
  version: "1.26.0"                # Optional — auto-detected if empty

docker:
  image: "ubuntu:22.04"            # Base Docker image
  dockerfile: "Dockerfile.devloop" # Custom Dockerfile (optional)
  mount: "/workspace"              # Container mount point
  user: "devloop"                  # Container user
  node_version: "20"               # Node.js version if needed
  extra_packages:                  # Additional APT packages
    - chromium
    - ffmpeg
  install_commands:                # Custom install commands
    - "pip install -r requirements.txt"

sandbox_env:                       # Environment vars passed to Docker
  GOOS: linux
  GOARCH: arm64

When no_sandbox: true, agents run directly on the host. The Docker configuration is ignored and environment variables are inherited.

Auto Merge

Feature branches and rollup branches have independent merge strategies:

auto_merge:
  feature: "none"     # none | low_risk | all
  rollup: "none"      # none | manual | auto

Risk Thresholds

Used by the low_risk feature merge strategy to classify PRs:

risk_thresholds:
  max_lines: 200      # Max changed lines for low_risk classification
  max_files: 10        # Max changed files for low_risk classification

Prompts

Override the default prompt templates for each agent role:

prompts:
  implementer: "prompts/implementer.md"
  implementer_retry: "prompts/implementer-retry.md"
  reviewer: "prompts/reviewer.md"
  quality_reviewer: "prompts/quality-reviewer.md"
  spec_generator: "prompts/spec-generator.md"
  punchlist: "prompts/punchlist.md"
  verify_fix: "prompts/verify-fix.md"
  recon: "prompts/recon.md"

Prompt templates support template variables that are populated at runtime with issue data, file paths, and configuration values.

Modules

For monorepos or multi-module projects, override build commands per module:

modules:
  backend:
    build_command: "go build ./..."
    test_command: "go test ./..."
    lint_command: "golangci-lint run"
    depends_on: ["core"]
  frontend:
    build_command: "npm run build"
    test_command: "npm test"
    lint_command: "eslint ."
  core:
    build_command: "go build ./..."
    test_command: "go test ./..."

Module names must match ^[a-zA-Z0-9._-]+$. Dependencies are validated for cycles.

Quality & Verification

quality:
  min_review_cost_usd: 0.0          # Quality gate: minimum review cost (0 = disabled)
  min_review_duration_seconds: 0    # Quality gate: minimum review duration (0 = disabled)

verify:
  max_fix_attempts: 2               # Fix cycles per verify failure
  blocking: true                    # Verify failures block merge

truncation:
  verify_output: 4096               # Max bytes from verify command output
  pr_diff: 30000                    # Max bytes from PR diff in prompts

CI Checks

Wait for CI checks to pass before merging:

wait_for_checks:
  timeout: "10m"                    # Max wait time (Go duration string)
  required:                         # CI check names to wait for
    - "test"
    - "lint"
    - "build"

Notifications

Get notified about run events. Environment variable references (${VAR}) are expanded from the host environment:

notify:
  - provider: "telegram"
    events:
      - "run_complete"
      - "implementation_complete"
      - "abort"
    settings:
      bot_token: "${TELEGRAM_BOT_TOKEN}"
      chat_id: "${TELEGRAM_CHAT_ID}"

Watch Mode

watch:
  poll_interval: "60s"              # How often to check for review feedback

Environment Variables

Additional variables listed in required_env must be set or the run will fail. These are forwarded into the Docker sandbox automatically.