# Archon Workflows Variable Substitution Syntax: Complete Reference Guide

> Master Archon workflows variable substitution syntax for flexible prompts. Learn `$1` through `$9`, `$ARGUMENTS`, `$WORKFLOW_ID`, and more for dynamic runtime context.

- Repository: [Cole Medin/Archon](https://github.com/coleam00/Archon)
- Tags: api-reference
- Published: 2026-04-10

---

**Archon employs a dollar-sign prefix convention where command-level substitutions like `$1` through `$9` and `$ARGUMENTS` are processed first, followed by workflow-level placeholders including `$WORKFLOW_ID`, `$USER_MESSAGE`, and `$ARTIFACTS_DIR` to inject runtime context into prompts.**

The coleam00/Archon repository implements a two-layer variable substitution system that processes placeholders beginning with `$` in both command texts and workflow prompts. This architecture separates lightweight command argument replacement from runtime-specific context injection, enabling dynamic workflow execution. Mastering the variable substitution syntax in Archon workflows allows developers to build responsive automation that adapts to user inputs, Git context, and execution environment variables.

## Command-Level Substitution Syntax

Archon processes command-level variables through the `substituteVariables` function defined in [`packages/workflows/src/utils/variable-substitution.ts`](https://github.com/coleam00/Archon/blob/main/packages/workflows/src/utils/variable-substitution.ts). This layer handles positional arguments supplied directly to command nodes before workflow-level context is applied.

### Supported Placeholders

The command substitution engine recognizes three distinct placeholder types:

- **`$1` through `$9`** – Positional arguments mapped to indices in the arguments array, where `$1` corresponds to the first element.
- **`$ARGUMENTS`** – A special variable that expands to all arguments joined as a single space-delimited string.
- **`\$`** – An escaped dollar sign that produces a literal `$` character in the output.

### Implementation Details

The `substituteVariables(text, args)` function iterates through the provided arguments array, replacing each indexed placeholder with its corresponding value. After processing positional arguments, it substitutes the `$ARGUMENTS` token and finally un-escapes any `\$` sequences to preserve literal dollar signs.

```typescript
import { substituteVariables } from '@/workflows/utils/variable-substitution';

const cmd = 'git checkout $1 && echo "Branch is $1" && echo "All args: $ARGUMENTS" && echo "Literal dollar: \\$"';
const args = ['feature/login', '--force', '--no-verify'];

const result = substituteVariables(cmd, args);
// Output: git checkout feature/login && echo "Branch is feature/login" && echo "All args: feature/login --force --no-verify" && echo "Literal dollar: $"

```

## Workflow-Level Substitution Syntax

After command processing, Archon applies workflow-level substitutions through the `substituteWorkflowVariables` function in [`packages/workflows/src/executor-shared.ts`](https://github.com/coleam00/Archon/blob/main/packages/workflows/src/executor-shared.ts) (lines 55-64). This routine injects runtime context that only exists during workflow execution.

### Runtime Context Variables

The workflow substitution layer supports placeholders for execution metadata and environment configuration:

- **`$WORKFLOW_ID`** – The UUID of the current workflow run.
- **`$USER_MESSAGE`** – The original trigger message from the user that initiated the workflow.
- **`$ARTIFACTS_DIR`** – Absolute path to the per-run artifacts directory.
- **`$DOCS_DIR`** – Path to the documentation folder (defaults to `docs/` or uses the [`.archon/config.yaml`](https://github.com/coleam00/Archon/blob/main/.archon/config.yaml) override).
- **`$BASE_BRANCH`** – The base Git branch, auto-detected or explicitly configured.
- **`$CONTEXT`**, **`$EXTERNAL_CONTEXT`**, **`$ISSUE_CONTEXT`** – GitHub issue and pull request data when available.
- **`$ARGUMENTS`** – All command arguments joined as a string, accessible within prompt contexts.

### Error Handling for Missing Values

If the `$BASE_BRANCH` placeholder appears in a prompt but the system cannot resolve a branch name, `substituteWorkflowVariables` throws an explicit error to prevent un-expanded tokens from reaching the AI model. This validation ensures workflow integrity before prompt submission.

```typescript
import { substituteWorkflowVariables } from '@/workflows/executor-shared';

const prompt = `
  Run ID: $WORKFLOW_ID
  User said: $USER_MESSAGE
  Artifacts can be found at: $ARTIFACTS_DIR
  Docs live in: $DOCS_DIR
`;

const { prompt: expanded } = substituteWorkflowVariables(
  prompt,
  'c3f9e2a1-7b4d-4a5e-9f3c-2c7f9e1b6a5d', // workflowId
  '/review add auth',                         // userMessage
  '/tmp/archon/artifacts/123',               // artifactsDir
  'main',                                    // baseBranch
  'documentation/'                           // docsDir
);

```

## Interactive Loop and Approval Variables

Archon provides specialized placeholders for interactive workflow nodes that handle user feedback and rejection states.

### Loop User Input and Rejection Reasons

- **`$LOOP_USER_INPUT`** – Contains feedback supplied to an interactive loop node, populated only during the first iteration of a resumed loop.
- **`$REJECTION_REASON`** – Stores reviewer comments when an approval node is rejected, enabling conditional logic based on rejection context.

```typescript
const loopPrompt = `
  You are reviewing the changes. User feedback: $LOOP_USER_INPUT
  If the reviewer rejected, show reason: $REJECTION_REASON
`;

const { prompt } = substituteWorkflowVariables(
  loopPrompt,
  'run-42', '', '', '', '', '',
  undefined,
  'I think the variable naming is unclear.',  // loopUserInput
  'Too many nested loops.'                    // rejectionReason
);

```

## Key Source Files

The variable substitution mechanism spans several critical files in the Archon codebase:

- **[`packages/workflows/src/utils/variable-substitution.ts`](https://github.com/coleam00/Archon/blob/main/packages/workflows/src/utils/variable-substitution.ts)** – Implements `substituteVariables()` for command-level `$1…$9` and `$ARGUMENTS` processing.
- **[`packages/workflows/src/executor-shared.ts`](https://github.com/coleam00/Archon/blob/main/packages/workflows/src/executor-shared.ts)** – Contains `substituteWorkflowVariables()` that expands runtime placeholders like `$WORKFLOW_ID` and `$ARTIFACTS_DIR` using sequential `String.replace` operations.
- **[`packages/workflows/src/executor.ts`](https://github.com/coleam00/Archon/blob/main/packages/workflows/src/executor.ts)** – Orchestrates the end-to-end substitution flow during node execution.
- **[`packages/workflows/src/schemas/workflow.ts`](https://github.com/coleam00/Archon/blob/main/packages/workflows/src/schemas/workflow.ts)** – Defines the YAML schema where users declare variable references within workflow nodes.

## Summary

- Archon uses a **two-layer substitution system**: command-level for arguments (`$1`–`$9`, `$ARGUMENTS`) and workflow-level for runtime context (`$WORKFLOW_ID`, `$USER_MESSAGE`, etc.).
- All placeholders follow the **dollar-sign prefix convention** (`$VARIABLE`), with `\$` used to escape literal dollar signs in command texts.
- The `substituteVariables()` function in [`variable-substitution.ts`](https://github.com/coleam00/Archon/blob/main/variable-substitution.ts) handles positional argument replacement, while `substituteWorkflowVariables()` in [`executor-shared.ts`](https://github.com/coleam00/Archon/blob/main/executor-shared.ts) manages execution-specific data.
- **Error handling** prevents unresolved variables like `$BASE_BRANCH` from reaching AI prompts by throwing exceptions when required context is missing.
- Interactive workflows access special variables including **`$LOOP_USER_INPUT`** and **`$REJECTION_REASON`** to process user feedback and approval states.

## Frequently Asked Questions

### What is the difference between $ARGUMENTS at the command level versus the workflow level?

While both use the same syntax, command-level `$ARGUMENTS` is processed by `substituteVariables()` in [`variable-substitution.ts`](https://github.com/coleam00/Archon/blob/main/variable-substitution.ts) for bash commands and executable nodes, whereas workflow-level `$ARGUMENTS` is expanded by `substituteWorkflowVariables()` in [`executor-shared.ts`](https://github.com/coleam00/Archon/blob/main/executor-shared.ts) for inclusion in AI prompts. Both produce the same space-joined string of all input arguments, but they operate at different stages of the execution pipeline.

### How do I include a literal dollar sign in my workflow commands?

Use the backslash escape sequence `\$` in your command text. The `substituteVariables()` function converts `\$` to a literal `$` after processing all other placeholders, ensuring special characters are preserved without triggering substitution.

### What happens if I reference an undefined variable like $BASE_BRANCH in my workflow?

If `$BASE_BRANCH` cannot be resolved because the Git context is missing or not configured in [`.archon/config.yaml`](https://github.com/coleam00/Archon/blob/main/.archon/config.yaml), the `substituteWorkflowVariables()` function throws an error before sending the prompt to the AI model. This strict validation prevents malformed prompts containing unexpanded tokens.

### When is $LOOP_USER_INPUT available during workflow execution?

`$LOOP_USER_INPUT` is only populated during the **first iteration of a resumed loop** in interactive workflow nodes. When a workflow pauses for user feedback and resumes, this variable captures the initial input provided by the user, allowing subsequent iterations to reference the original feedback context.