Workflow arguments

Updated Sep 16, 2026

Set project-specific behaviour in args.json. The workflow also has matching top-of-file defaults, but the sidecar args.json is the normal retuning point for ODW launches.

Common arguments:

  • base: integration branch. Defaults to main.
  • roadmap: roadmap path. Defaults to docs/roadmap.md.
  • designDocs: design document and ADR locations cited in planner prompts.
  • researchNote: optional external-library research pointer, such as a vendored source path.
  • projectRoot: target-project checkout to chdir into before the workflow creates worktrees. Use this when launching a copied workflow from a sidecar.
  • searchBackend: canonical code-search backend for prompt guidance. Supported values are grepai and memtrace. Defaults to grepai, or to memtrace when memtraceRepoId is set.
  • grepaiWorkspace: GrepAI workspace name. Defaults to Projects.
  • grepaiProject: canonical main-branch GrepAI project name. Set this when the ODW source path or worker worktree path would make $(get-project) resolve to the wrong project.
  • memtraceRepoId: canonical Memtrace repository id. Set this, or set searchBackend to memtrace, when GrepAI is unavailable on the host.
  • coderabbitReviewCommand: CodeRabbit command used in implementation prompts. Defaults to coderabbit review --agent.
  • reviewTool: host reviewer for committed work: dakar (the default; requires OPENAI_API_KEY) or coderabbit (the retained NDJSON CLI path). Other values fail at launch.

Migration: The default is now dakar. Existing operators must put dakar-review and pi on PATH and provide OPENAI_API_KEY. Set reviewTool to coderabbit to retain the previous NDJSON CLI path. See Migrate to Dakar host review for the operator checklist. - dakarCommand: Dakar CLI invoked in dakar mode. Defaults to dakar-review. - reviewTimeoutSeconds: host-side timeout for each Dakar or CodeRabbit review process and, in Dakar mode, the value passed as Dakar's --timeout. Defaults to 3600 and is clamped to 60–7200 seconds. The former dakarTimeoutSeconds name remains an accepted input alias. - dakarBudgetGbp: optional Dakar admission budget, clamped to 0–10. Values above 0 are forwarded as --budget-gbp; 0 defers to Dakar's own hard budget. - maxParallel: task worker-pool width. Defaults to 8 unless taskId is set. - maxPlanningParallel: concurrent planning-stage agents. Defaults to 4. - maxBuildParallel: concurrent build-stage agents. Defaults to 4. - maxTasks: maximum roadmap tasks for one run. - maxDesignRounds: planning and design-review exchange cap. Defaults to 4. - maxReviewRounds: implementation review/fix exchange cap. Defaults to 3. - commitGates: ordered list of deterministic gate commands every task, addendum, fix, and remediation agent must run before declaring work green. Defaults to ["make all"]. The run result echoes the effective list so operators can audit reported gate greenness against it; agents are told never to assume make all aggregates the gates a project names in AGENTS.md. - hostCommitGates: when true (the default), the workflow host re-runs the commitGates commands itself against each branch's committed HEAD before review and integration, so a gatesGreen claim is verified rather than trusted. Set false to restore the trust-the-agent flow. - commitGateTimeoutSeconds: per-command timeout for host-run gates. Defaults to 3600; a gate that exceeds it is killed and reported as a failure with the timeout named in the evidence. - stageAttempts: total attempts per stage agent when the previous attempt died on an infrastructure fault (an ODW adapter timeout or crash, or schema-retry exhaustion). Defaults to 2. Product failures are never retried, and the host never re-dispatches a faulted integration stage: a crash between the squash push and the agent's return can leave a hidden success already landed on origin/<base>, which the host cannot detect, so repeating the stage risks a double merge. (The integration agent still redoes its own squash idempotently on a non-fast-forward push rejection within a single turn — see the recovery model.) - perWorkItemBuild: when true (the default), the workflow host reads the approved ExecPlan's ## Progress checklist and dispatches one builder turn per unticked work item, verifying committed progress after every turn. Plans without a Progress checklist fall back to the single-turn build automatically; set false to force the single-turn build for every task. - maxWorkItemRounds: builder turns per task before the work-item loop fails closed. Defaults to 16. - coderabbitHostReview: in CodeRabbit mode, when true (the default), the workflow host runs coderabbit review --agent against committed work. Set false to restore the legacy agent-run flow. Dakar always runs host-side, so this flag has no effect in the default mode. - hostGatesBetweenWorkItems: when true (the default), and when both hostCommitGates and perWorkItemBuild are on, the host re-runs the commit gates after each committed work item — before the between-item selected host reviewer — so a committed work item whose gates are actually red is caught at the item boundary instead of only at the dual-review stage. A red gate drives a bounded fix loop; if it cannot be made green the work item fails. Set false to verify gates only at the dual-review boundary (cheaper: one gate run per review round rather than one per work item). - csCheck: when true (the default), the host runs a CodeScene code-health check on the committed changed files as a deterministic gate AFTER the commit gates and BEFORE the selected host reviewer (both free checks precede the selected host reviewer and the token-spending reviewer agents). A regression drives a bounded fix round; the build agent clears it by refactoring or, only where refactoring would be deleterious, suppresses the specific smell with a justified @codescene(disable:"...") comment. The check skips gracefully only when its binary is absent from PATH, like make verify-modules without Dafny; an availability-probe fault is reported as a failed check instead of being treated as an absent binary. Set false to disable it. - csCheckCommand: the command the CodeScene check runs in the worktree. Defaults to cs-check-changed (an operator-provided wrapper); override it with the exact invocation, e.g. cs check --changed --base main. - hostReviewBetweenWorkItems: when true (the default) and perWorkItemBuild is on, the host runs a review after each committed work item — using Dakar by default or CodeRabbit when selected — rather than only once after the whole implementation stage. CodeRabbit additionally requires coderabbitHostReview; Dakar always runs host-side and ignores that legacy flag. Blocking findings drive a bounded fix loop; terminal deferral or errors halt the task for assessment instead of continuing unreviewed. Set false to review only once at the end of the implementation stage. - hostReviewAttempts: total host-review attempts when Dakar defers or CodeRabbit rate limits the review. Defaults to 3 and is clamped to 1–10. - hostReviewBackoffMinutes: [low, high] range for the deterministic backoff wait after a Dakar deferral or CodeRabbit rate limit. Defaults to [45, 90]; each endpoint is clamped to 1–1440 minutes, with high never below low. - hostReviewFindingsFile: optional absolute path to an append-only JSONL file recording every host-review finding (timestamp, task, severity, file, comment). The historical coderabbitBetweenWorkItems, coderabbitAttempts, coderabbitBackoffMinutes, and coderabbitFindingsFile names remain accepted as deprecated aliases for the corresponding canonical fields. - writeProbeEffort: reasoning effort for the once-per-run write-preflight probe (write an exact token to an exact path — no reasoning). Defaults to minimal. The probe keeps the plan/build ADAPTER but never inherits planModel/buildModel. - writeProbeModelByAdapter: optional { "<adapter>": "<model>" } map to run the probe on a cheaper model per adapter (adapter name lowercased). Defaults to Claude Haiku (claude-haiku-4-5) and GPT-5.6 Luna (gpt-5.6-luna) for the default planning and build adapters respectively. - assessmentModel: model for the report-only partial-branch assessment. Defaults to a medium model (claude-sonnet-5) rather than inheriting the Opus-class review model, because a deterministic fast-classifier already handles the clear cases (empty branch, evidence-collection failure) with zero tokens and only genuinely ambiguous branches reach the model. - assessmentEscalationModel: the stronger model used for a strong adopt-complete candidate (a branch that committed an ExecPlan). Defaults to the review model. - triageModel: model for remediation triage. Defaults to a medium model (gpt-5.6-sol); a deterministic pre-pass collapses exact-duplicate proposals before the agent runs. - triageEffort: reasoning effort for remediation triage. Defaults to medium. - triageEscalationModel: the stronger model used when the deduped proposals span more than one audit/review source (potential cross-phase or conflicting routing). Defaults to the same gpt-5.6-sol model. - taskId: run exactly one roadmap task. - dryRun: when true, a fresh task stops before worktree creation — and so before planning, review, implementation, integration, or document writes — making it a read-only validation path that mutates no git state. (Recovery and continue-mode resume keep their own dry-run handling over pre-existing worktrees.) - autoMerge: when false, leave reviewed task branches for manual integration. - documentAudit: when false, return audit findings without writing audit files. - assessPartialBranches: when false, skip the report-only assessment of failed or halted task branches. Defaults to enabled. - resumePartialBranches: when true, discover surviving roadmap-* branches on launch and assess them before normal roadmap selection. Defaults to false; the default workflow behaviour is unchanged unless an operator opts in. - resumeMode: the maximum recovery action for discovered branches. assess (the default) reports only. review may additionally route clean, committed, task-scoped adopt-complete branches with validation evidence into the ordinary review and integration path. continue dispatches each surviving branch deterministically from its committed ExecPlan status, with no judgement agent. Any other value fails fast at launch. - resumeTaskId: limit recovery discovery to one roadmap id. This is separate from taskId, which selects normal roadmap work. - resumeMaxCandidates: bound on recovery candidates per run. Defaults to 4; excess candidates are reported as skipped with reason candidate-cap. - worktreeWritePreflight: when false, skip the once-per-run probe that proves the planning and build adapters can write into sibling task worktrees. Defaults to enabled; a failed probe fails the task at stage worktree-write as an environment fault. - buildAdapter and buildModel: adapter and model for worktree creation, implementation, integration, and remediation agents. - planAdapter and planModel: adapter and model for planning agents. - reviewAdapter and reviewModel: adapter and model for design review, code review, expert review, and addendum fallback review agents. - auditAdapter, auditModel, and auditEffort: adapter, model, and effort for post-merge audits. Defaults to Claude Code, claude-sonnet-5, and medium. - triageAdapter and triageModel: adapter and model for remediation triage (routing review and audit proposals onto roadmap lanes). Defaults are codex and gpt-5.6-sol. - assessmentAdapter and assessmentModel: adapter and model for partial branch assessment. assessmentAdapter defaults to the review adapter, while assessmentModel independently defaults to claude-sonnet-5.

Current defaults deliberately split execution and judgement. Build, implementation, and integration use GPT-5.6 Terra through the medium-effort Codex adapter; triage uses GPT-5.6 Sol at medium effort. Planning and review judgement default to Claude Code with claude-opus-4-8. That means the plan stage, design review, code review, expert review, and addendum fallback review use the reviewAdapter or planAdapter Claude routing unless args.json overrides them. Post-merge audit uses Claude Sonnet 5 at medium effort. Set assessmentAdapter explicitly when partial-branch assessment should stay on Codex instead of inheriting the review adapter.

Example args.json:

{
  "base": "main",
  "roadmap": "docs/roadmap.md",
  "projectRoot": "/home/example/Projects/example-project",
  "designDocs": "docs/architecture.md, docs/adr-001-adopt-odw-sidecar-launches.md, docs/users-guide.md, docs/developers-guide.md",
  "searchBackend": "grepai",
  "grepaiWorkspace": "Projects",
  "grepaiProject": "example-project",
  "maxParallel": 8,
  "maxPlanningParallel": 4,
  "maxBuildParallel": 4,
  "maxTasks": 12,
  "hostReviewFindingsFile": "/home/example/Projects/example-project.workshop/df12-build-run/host-review-findings.jsonl",
  "buildAdapter": "codex-medium",
  "buildModel": "gpt-5.6-terra",
  "planAdapter": "claude",
  "planModel": "claude-opus-4-8",
  "assessmentAdapter": "codex-high",
  "assessmentModel": "gpt-5.5",
  "triageAdapter": "codex",
  "triageModel": "gpt-5.6-sol",
  "triageEffort": "medium",
  "reviewAdapter": "claude",
  "reviewModel": "claude-opus-4-8",
  "auditAdapter": "claude",
  "auditModel": "claude-sonnet-5",
  "auditEffort": "medium"
}