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-code
  fallback: codex
  type_mapping:
    design: claude-code
    coding: claude-code
    testing: claude-code
    review: claude-code
  fallback_chain:
    - claude-code
    - 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-code	Primary agent for tasks
fallback	string	codex	Fallback agent
type_mapping	object	—	Map node types to specific agents
fallback_chain	list	—	Ordered fallback chain

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