WORKFLOW.md Configuration

Each project can have a WORKFLOW.md file in its repository root that configures AI agent behavior, quality gates, hooks, and more.

Format

WORKFLOW.md uses YAML front-matter for configuration:

---
orchestration:
  mode: polling
  interval_seconds: 30

agents:
  primary: claude
  fallback: codex
  type_mapping:
    design: claude
    coding: claude
    testing: claude
    review: claude
  fallback_chain:
    - claude
    - codex
    - opencode

gate_scores:
  auto_merge_threshold: 85
  human_review_threshold: 60
  block_threshold: 40

hooks:
  pre_task:
    - npm install
  test:
    - npm test
  lint:
    - npm run lint
  build:
    - npm run build

limits:
  max_parallel_tasks: 3

daemon:
  selection_strategy: least_loaded
  prefer_agent_match: true

sandbox:
  enabled: true
  base_image: node:22-alpine
  memory: 2g
  cpus: 2
  network: none
---

# Project Workflow

Additional markdown documentation about your project's workflow goes here.

Configuration Sections

orchestration

Field	Type	Default	Description
mode	string	polling	Orchestration mode: polling, event_driven, hybrid
interval_seconds	number	30	Polling interval (≥ 5)

agents

Field	Type	Default	Description
primary	string	claude	Primary agent for tasks
fallback	string	codex	Fallback agent
type_mapping	object	—	Map node types to specific agents
fallback_chain	list	—	Ordered fallback chain

Use canonical IDs such as claude, codex, copilot, gemini, opencode, kimi, mimo, qwen, codebuddy, qoder, trae, and zcode. MiMo Code, Qwen Code, CodeBuddy, Qoder CLI, TraeCode CLI, and ZCode are supported explicit selections — choose them through primary, type_mapping, or a node/execution override. Their authentication, endpoint, and model are managed by the local CLI profile on the machine that executes them; generic LLM Integrations do not configure these Coding Agents. Smart Router selection and the generated default fallback order intentionally exclude mimo, qwen, codebuddy, qoder, trae, and zcode; including one in a custom fallback_chain is an explicit opt-in that should be validated in your environment. CodeBuddy and Qoder are ready after their local AgentHost start/resume gates; TraeCode CLI and ZCode stay installed_but_not_ready until their live gates pass, and ZCode additionally requires an approved FORGEXA_ZCODE_ALLOWED_SHA256.

Harness is a separate explicit ID, deepseek, for a verified personal Runtime. For example:

agents:
  primary: deepseek
  fallback_chain: []

This never makes Harness an automatic RouterAgent/default fallback candidate. Its managed profile, model override and read-only auth reference are configured locally, not via generic LLM Integrations. A custom fallback entry is also explicit opt-in. See fixed-build acceptance and limits; native Windows and shared pools are blocked.

gate_scores

Field	Type	Default	Description
auto_merge_threshold	number	85	Score for auto-merge
human_review_threshold	number	60	Score requiring human review
block_threshold	number	40	Score that blocks progress

Thresholds must satisfy: auto_merge ≥ human_review ≥ block.

hooks

Hook commands are validated against a whitelist for security. Allowed prefixes include:

• npm install/ci/run/test, yarn install/run/test, pnpm install/run/test
• pip install, poetry install/run
• python -m pytest/ruff/mypy
• go mod/build/test/vet
• make, git, docker run
• mvn, gradle, cargo

Set hooks.allow_custom: true to bypass the whitelist (requires admin).

Hook	When	Example
pre_task	Before each task	npm install
post_task	After each task	npm run format
test	Test execution	npm test
lint	Lint execution	npm run lint
build	Build execution	npm run build

sandbox

Field	Type	Default	Description
enabled	boolean	false	Enable Docker sandbox for tests
base_image	string	auto-detect	Docker image to use
memory	string	2g	Container memory limit
cpus	number/string	2	Container CPU limit
network	string	none	Network mode (none for isolation)

daemon

Field	Type	Default	Description
selection_strategy	string	least_loaded	How to pick a daemon: least_loaded, round_robin, affinity, random
prefer_agent_match	boolean	true	Prefer daemons with matching agents
locality_aware	boolean	false	Prefer daemons near the git repo

Hot Reload

WORKFLOW.md is automatically reloaded when changes are detected. If the new configuration is invalid:

• The old configuration remains active
• The invalid snapshot is stored with status invalid
• A warning event is published