Global Workflows, Commands, and Scripts

Workflows placed in ~/.archon/workflows/, commands in ~/.archon/commands/, and scripts in ~/.archon/scripts/ are loaded globally — they appear in every project and can be invoked from any repository. Workflows and commands carry the source: 'global' label in the Web UI node palette; scripts resolve under the same repo-wins-over-home precedence.

Paths

~/.archon/workflows/
~/.archon/commands/
~/.archon/scripts/

Or, if you have set ARCHON_HOME:

$ARCHON_HOME/workflows/
$ARCHON_HOME/commands/
$ARCHON_HOME/scripts/

Create the directories if they do not exist:

mkdir -p ~/.archon/workflows ~/.archon/commands ~/.archon/scripts

Note on location. These are direct children of ~/.archon/ — same level as workspaces/, archon.db, and config.yaml. Earlier Archon versions stored global workflows at ~/.archon/.archon/workflows/; see Migrating from the old path below.

Supported layouts

Shared commands/scripts and legacy grouped workflows support one grouping folder. Packaged workflows instead use exactly <pack>/<workflow>/, with one YAML file directly inside the workflow folder.

~/.archon/workflows/
├── my-review.yaml              # ✅ top-level file
├── triage/                     # ✅ 1-level subfolder (grouping)
│   └── weekly-cleanup.yaml     # ✅ resolvable as `weekly-cleanup`
└── team/                       # ✅ packaged workflow
    └── personal/
        └── personal.yaml       # exactly one direct YAML is required

YAML nested below the workflow folder is not loaded. A package folder without exactly one direct YAML is reported as invalid rather than ignored silently.

Resolution is by filename without extension (for commands) or exact filename (for workflows), regardless of which subfolder the file lives in. Duplicate basenames within the same scope are a user error — keep each name unique within ~/.archon/commands/ (or <repoRoot>/.archon/commands/), across whatever subfolders you use.

Load Priority

Bundled defaults (lowest priority) — the archon-* workflows/commands embedded in the Archon binary.
Global / home-scoped — ~/.archon/workflows/, ~/.archon/commands/, ~/.archon/scripts/ (override bundled by filename).
Repo-specific — <repoRoot>/.archon/workflows/, <repoRoot>/.archon/commands/, <repoRoot>/.archon/scripts/ (override global by filename).

Same-named legacy/shared files at a higher scope win. Packaged commands and scripts resolve only within their owning package and never fall through to another scope.

Practical Examples

Personal Code Review

A workflow that runs your preferred review checklist on every project:

name: my-review
description: Personal code review with my standards
model: sonnet

nodes:
  - id: review
    prompt: |
      Review the changes on this branch against main.
      Check for: error handling, test coverage, naming conventions,
      and unnecessary complexity. Be direct and specific.

Custom Linting or Formatting Check

A workflow that runs project-agnostic checks:

name: lint-check
description: Check for common code quality issues across any project

nodes:
  - id: check
    prompt: |
      Scan this codebase for:
      1. Functions longer than 50 lines
      2. Deeply nested conditionals (>3 levels)
      3. TODO/FIXME comments without issue references
      Report findings as a prioritized list.

Quick Explain

A simple workflow for understanding unfamiliar codebases:

name: explain
description: Quick explanation of a codebase or module
model: haiku

nodes:
  - id: explain
    prompt: |
      Give a concise explanation of this codebase.
      Focus on: what it does, key entry points, and how the main
      pieces connect. Keep it under 500 words.
      Topic: $ARGUMENTS

Personal Command Helpers

Commands placed in ~/.archon/commands/ are available to every workflow on the machine. Useful for prompts you reuse across projects.

Review the uncommitted changes in the current worktree.
Check for:
- Error handling gaps
- Missing tests
- Surprising API shapes
- Unnecessary cleverness
Be terse. Report findings grouped by file.

A workflow in any repo can then reference it:

nodes:
  - id: review
    command: review-checklist

Syncing with Dotfiles

If you manage your configuration with a dotfiles repository, you can include your global content:

# In your dotfiles repo
dotfiles/
└── archon/
    ├── workflows/
    │   ├── my-review.yaml
    │   └── explain.yaml
    └── commands/
        └── review-checklist.md

Then symlink during dotfiles setup:

ln -sf ~/dotfiles/archon/workflows ~/.archon/workflows
ln -sf ~/dotfiles/archon/commands  ~/.archon/commands

Or copy them as part of your dotfiles install script:

mkdir -p ~/.archon/workflows ~/.archon/commands
cp ~/dotfiles/archon/workflows/*.yaml ~/.archon/workflows/
cp ~/dotfiles/archon/commands/*.md    ~/.archon/commands/

This way your personal workflows and commands travel with you across machines.

CLI and Web Support

Both the CLI, the server, and the Web UI discover home-scoped content automatically — no flag, no config option.

# Lists bundled + global + repo-specific workflows
archon workflow list

# Run a global workflow from any repo
archon workflow run my-review

In the Web UI workflow builder, commands from ~/.archon/commands/ appear under a Global (~/.archon/commands/) section in the node palette, distinct from project and bundled entries.

Migrating from the old path

Pre-refactor versions of Archon stored global workflows at ~/.archon/.archon/workflows/ (with an extra nested .archon/). That location is no longer read. If you have workflows there, Archon emits a one-time deprecation warning on first use telling you the exact migration command:

mv ~/.archon/.archon/workflows ~/.archon/workflows && rmdir ~/.archon/.archon

Run it once; the warning stops firing on subsequent invocations. There was no prior home-scoped commands location, so ~/.archon/commands/ is new capability — nothing to migrate.

Troubleshooting

Workflow Not Appearing in List

Check the path — The directory must be exactly ~/.archon/workflows/ (a direct child of ~/.archon/, not the old double-nested ~/.archon/.archon/workflows/).
Terminal window
```
ls ~/.archon/workflows/
```
Check file extension — Workflow files must end in .yaml or .yml.
Check YAML validity — A syntax error in the YAML will cause the workflow to appear in the errors list rather than the workflow list. Run:
Terminal window
```
archon validate workflows my-workflow
```
Check for name conflicts — If a repo-specific workflow has the same filename, it overrides the global one. The global version will not appear when you are in that repo.
Check ARCHON_HOME — If you have set ARCHON_HOME to a custom path, global workflows must be at $ARCHON_HOME/workflows/, not ~/.archon/workflows/.