archdev.json reference

ArchDev reads repository configuration from archdev.json. This page lists every supported key, which file each key belongs in, how the files merge, and how the pipeline system executes.

Config files

Three files merge into the effective configuration. Checked-in files own repository policy; personal files own model and provider choice.

Validate the merged result without executing anything:

archdev check

archdev check parses every pipeline, resolves every binding, compiles every workflow, and verifies every model selector. It prints a table, or JSON in JSON mode. Fix what it reports before pushing config changes.

Minimal example

{
  "app": "current",
  "review": { "default_workflow": "team-review" },
  "factory": { "workers": 10, "model": "@factory-automation" },
  "modelAliases": {
    "factory-automation": [
      { "provider": "openai", "model": "gpt-5.6-sol" },
      { "provider": "platform", "model": "openai/gpt-5.6-sol" }
    ]
  },
  "publish": { "auto": true, "model": "@publication-metadata" },
  "pipelines": {
    "branch-validation": {
      "steps": [
        {
          "id": "lint",
          "run": ["aster", "affected", "lint", "--base", "origin/main"],
          "timeout_seconds": 900,
          "continue_on_error": true
        },
        { "id": "review", "uses": "review-and-fix" }
      ]
    }
  },
  "pipeline_bindings": { "branch_update": "branch-validation" }
}

Layering and precedence

Objects merge per field; scalar values are winner-takes-all. The general rule is project policy wins, personal model choice wins:

• For pipelines, review, factory, daemon, publish, and tasks, fields set in archdev.json beat the same fields in the user file and the local overlay.
• These model selections always come from the personal side (user file, then local overlay): the root modelAliases map, factory.model, factory.worker_model, publish.model, and the four evals model fields. Set a model in your user file once and no repository edit can override it.
• modelProviders account selection is always user-owned.
• tasks is repository policy, but the gitignored local overlay applies last, so it works as a per-checkout experiment override.
• pull_requests.automation.pause_label resolves last-set-wins across user, local, then project files.
• The user file can never set app, local, or worktree. Repository identity and worktree hooks only come from checked-in or daemon-managed files.
• Exact-commit daemon paths merge without the local overlay, so uncommitted local edits cannot change an already-queued job.

Top-level keys

All keys are optional. An absent key means its default, never null.

api_url and portal_url can also be set with ARCHDEV_API_URL and ARCHDEV_PORTAL_URL. The legacy singular pipeline key is rejected: define pipelines under pipelines and bind them under pipeline_bindings.

Identity and connection

modelAliases

Aliases give a short name to an ordered fallback list of models. Model fields elsewhere reference them as "@alias-name". Alias names must match ^[a-z][a-z0-9._-]{0,63}$. Each entry is one { provider, model } object or a non-empty array of them, tried in order.

"modelAliases": {
  "factory-automation": [
    { "provider": "openai", "model": "gpt-5.6-sol" },
    { "provider": "xai", "model": "grok-4.6" },
    { "provider": "platform", "model": "openai/gpt-5.6-sol" }
  ]
}

A provider of "platform" routes through your ArchDev model access with a provider/model id; other providers use that provider directly. An invalid alias entry fails archdev check with modelAliases.<name> must be a valid model reference or non-empty fallback list. The fallback default model is platform/xai/grok-latest-thinking-high.

review

Named workflows and review workflows are files, not inline config. The loader reads project <repo>/.archdev/workflows and user ~/.archdev/workflows; built-ins cover default. The example at the top of this page selects the team-review workflow.

factory

Controls the overseer/worker orchestration: how many workers, who claims work, and which models drive each role. CLI flags beat config: --dispatch beats factory.dispatch, --autonomy beats factory.autonomy, --model beats factory.model, and --workers beats factory.workers.

Details:

• dispatch: "auto" claims every ready task; "manual" claims only user-released tasks.
• autonomy: "confirm" asks before consequential worker actions; "auto" proceeds without asking.
• overseer_instructions and worker_instructions are free-text prompts prepended to each role.
• A model selector is a literal provider/model string, a @alias reference, or an array of selectors tried in order. factory.worker_model pins workers when set; otherwise workers follow the live overseer model, including factory.model.
• Unknown factory keys are ignored, so a typo there will not fail validation. Prefer archdev check plus a careful re-read when factory behavior surprises you.

publish

Constraints: automatic publication requires publish.remote to be "origin". The built-in branch-validation pipeline additionally requires publish.base "main"; point branch_update at a custom pipeline to use another base or remote.

pipelines

pipelines maps a name to { steps: [...] }. Names match step-id syntax. Run one locally with archdev pipeline run <name> in the current worktree.

Step fields

Each step is either a command step (run) or a pipeline call (uses), never both. A call step may only set id and uses.

Composition with uses

uses is a compile-time call, expanded before anything runs:

• The called pipeline's steps are inlined with dotted ids prefixed by the caller (review.fix, review.commit), so evidence and logs stay unambiguous.
• Cycles are rejected (Pipeline cycle: a -> b -> a).
• The fully expanded pipeline may contain at most 100 commands.

"pipelines": {
  "branch-validation": {
    "steps": [
      { "id": "lint", "run": ["aster", "affected", "lint", "--base", "origin/main"], "continue_on_error": true },
      { "id": "review", "uses": "review-and-fix" }
    ]
  }
}

Built-in pipelines

These exist without any configuration; defining the same name in pipelines overrides the built-in:

pipeline_bindings

Bindings connect daemon triggers to pipelines. A binding value must name a pipeline that parses; an unknown name fails validation.

Omit pipeline_bindings (or a single trigger) to keep the default. To disable automation for a trigger, point it at a pipeline whose steps exit cleanly without doing work.

worktree

Hooks and environment for daemon-managed worktrees. Unknown keys anywhere under worktree are rejected, unlike factory.

run is a non-empty array of non-empty strings. timeout_seconds is an integer from 1 to 86400. The create hook runs after a worktree is prepared (up to 1800 seconds in the example at the top of the repo config); the delete hook runs on cleanup. runtime_environment probes the worktree runtime before use.

daemon

tasks

Selects the task backend the factory claims work from. Repository policy, with the local overlay applied last. ARCHDEV_TASKS_BACKEND overrides the merged value.

pull_requests

evals

Agent evaluation harness settings. Every source is validated before merging.

local

local holds daemon-managed repository identity (project_id, repo_name, plus debug_projects scopes for non-production installs). It is stripped from the user file on merge. Do not edit it by hand; setup and the daemon maintain it.

How pipelines run

Whether triggered by the daemon or started by hand with archdev pipeline run <name>, execution follows one model:

1. Parse and expand. The named pipeline is parsed, uses calls are inlined with dotted step ids, and the result is capped at 100 commands. Anything invalid fails before any step runs.
2. Sequential steps. Steps run in order, each in cwd inside the pipeline worktree. The first failure stops the pipeline unless that step sets continue_on_error, which records failed_continued and continues. Cancellation and timeouts always stop the run.
3. Output chaining. Each step's stdout is saved and handed to the next step twice: piped on stdin and as a file path in ARCHDEV_PREVIOUS_OUTPUT. A step reads the previous result instead of re-deriving it.
4. Evidence file. ARCHDEV_PIPELINE_EVIDENCE points at a JSON record rewritten after every step with the ordered step history: ids, commands, states, exits, and output tails. Later steps (and the review-and-fix prompts) read lint failures and findings from evidence rather than re-running earlier steps.

Step environment

On top of env and the usual shell environment, every step receives:

Custom env keys must not start with ARCHDEV_; the runner rejects them so user config cannot spoof pipeline variables.