Archon 0.9.0 — workflow signatures, packaged workflows, and a dry-run mode (2 breaking changes)

[Wirasm]

Release: https://github.com/coleam00/Archon/releases/tag/v0.9.0

Workflows become properly composable in this release. A workflow can now declare the arguments it takes and the result it returns, ship as one self-contained folder you can copy between repos, and be simulated end to end without contacting a provider.

There are two breaking changes, both in workflow authoring. Read those first — the fix for each is one line of YAML.

---

Breaking changes

1. Claude workflow nodes no longer inherit ambient skills and MCP servers

A Claude node now sees exactly what its YAML declares, plus the native tools Archon injects for the run. User, project, and plugin MCP configuration on the machine no longer reaches workflow nodes.

If a node relied on an ambiently configured MCP server, declare it:

nodes:
  - id: review
    prompt: ...
    mcp: .archon/mcp/github.json

If it relied on an ambient skill, list it:

    skills: [code-review]

Declared skills are now also checked before spend: a skill that is installed but unreachable from the node's enabled settingSources fails up front instead of silently going missing. Built-in and plugin-qualified (plugin:skill) names warn and are left for the SDK to resolve.

Direct Claude chat, CLAUDE.md, and built-in/filesystem/inline agents are unchanged. (#2535)

2. An included command body must resolve, and may only reference its own workflow

command: and loop.command files inside an include: block are now resolved, validated, namespaced, and input-bound at load time. Two previously tolerated shapes now fail:

• A body that references a node id outside the included workflow. Previously it could bind whatever the caller happened to have.
• A body that cannot be resolved or read. Previously this warned and was skipped; it now fails a fresh execution.

The fix is to declare an input and pass it explicitly rather than reaching outward:

  - id: review
    include: reusable-review
    depends_on: [plan]
    with:
      plan: $plan.output
      base_branch: main

A paused loop still resumes from its persisted prompt snapshot even if its command file is later deleted. In exchange, included command bodies can now use $INPUTS.<name>, which was rejected outright before. (#2534, #2532)

---

What's new

Workflow signatures — inputs:, returns:, and with: on sub-runs. A workflow can declare the named arguments it accepts and which node's output is its result. A workflow: sub-run node binds those by name instead of passing one opaque input: string.

inputs:
  issue_number: { required: true }
  base_branch: { default: main }
returns: summarize

Values arrive as $INPUTS.<name> in prompts and command bodies, and as INPUTS_<UPPER_SNAKE> in bash:/script: environments. Missing required inputs and undeclared arguments are rejected before any worktree, clone, or provider cost. Workflows without inputs: keep their existing passthrough behavior byte for byte. (#2523)

--dry-run simulates a workflow without spending anything.

archon workflow run my-workflow --dry-run

An in-memory simulator walks the DAG — routing, when: conditions, strict $node.output references, gates, and loops — and prints a deterministic human or --json trace. No provider is contacted and nothing is persisted: no run row, events, sessions, or worktrees. Node outputs can be stubbed and code nodes actually executed with --exec-code. (#2530)

Packaged workflows — one folder holds a workflow and everything it uses.

.archon/workflows/my-pack/my-workflow/
├── my-workflow.yaml
├── commands/
└── scripts/

Bare command: and script: references in that YAML bind to the workflow's own directories instead of the shared trees, so copying a workflow to another repo is copying one folder rather than a scavenger hunt across three. Flat and one-level grouped layouts are unaffected. (#2528)

---

Worth knowing even if you skip the rest

A schema upgrade could crash-loop on an index that predates its column. An index or COMMENT ON COLUMN placed beside its table body names a column that does not exist yet on an upgrade. Because the schema applies in one transaction and re-throws, one such statement aborted the whole apply — on Postgres that broke startup and every CLI invocation for installs upgrading past #2414, and on SQLite it meant the adapter could not open a database created before parent_conversation_id existed.

Every index and column comment now sits below the additive block, and a new CI job proves the current schema applies cleanly on top of every schema vintage ever released, re-applies idempotently, and lands on exactly the fresh-install shape. If you were stuck on a boot loop after upgrading, this is your fix. (#2513, #2552)

Also fixed: workflow-level modelReasoningEffort:/webSearchMode: now actually reach Codex (they parsed cleanly and did nothing since March); WORKFLOW_ID is delivered to bash:/script: subprocess environments; Archon no longer guesses the default branch when origin/HEAD is unset; and the container write-back no longer mis-decodes filenames containing a leading dash, a trailing newline, or a tab.

---

Upgrading

# Homebrew
brew upgrade coleam00/archon/archon

# macOS / Linux
curl -fsSL https://archon.diy/install | bash

# Windows (PowerShell)
irm https://archon.diy/install.ps1 | iex

Full changelog: https://github.com/coleam00/Archon/blob/main/CHANGELOG.md

If one of the two breaking changes bites a workflow you can't easily fix, reply here — happy to look at the YAML.