Skip to content

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. Repo-specific files take precedence over home-scoped files with the same name.

~/.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:

Terminal window
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.

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. Inside a pack, a folder with no direct YAML (tests, docs, assets) and any dot directory (.shared, .github) are not workflow folders and are skipped. A folder with two or more direct YAML files is reported as invalid rather than ignored silently.

Commands resolve by filename without extension. Project, global, and bundled workflows launch and compose by their exact, case-sensitive YAML name:, regardless of which subfolder the file lives in. Launch installed pack entrypoints by their qualified owner/plugin:entrypoint name; references within that pack can use the YAML name:. 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.

  1. Bundled defaults (lowest priority) β€” the archon-* workflows/commands embedded in the Archon binary.
  2. Global / home-scoped β€” ~/.archon/workflows/, ~/.archon/commands/, ~/.archon/scripts/ (override bundled by filename).
  3. 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.

A workflow pack published on GitHub installs for every project on this Archon with archon plugin add. Installed packs are a fourth source next to bundled, global and project, outside the precedence above.

A plugin root is a directory containing archon-plugin.json and one pack in the packaged layout. A repository can contain one or more plugin roots, at the repository root or in subdirectories. Each root installs independently using owner/repo[/path]. This example shows a single plugin root:

review-kit/ # plugin root: owner/repo or owner/repo/<path>
β”œβ”€β”€ archon-plugin.json
β”œβ”€β”€ .shared/ # modules and documents the pack's scripts use
β”‚ └── util.ts
β”œβ”€β”€ .github/workflows/ci.yml # a dot directory: never a workflow folder
β”œβ”€β”€ tests/ # no direct YAML: not a workflow folder
β”œβ”€β”€ review/ # an entrypoint
β”‚ β”œβ”€β”€ review.yaml
β”‚ β”œβ”€β”€ commands/scope.md
β”‚ └── scripts/check.ts
└── helper/ # a support workflow
β”œβ”€β”€ helper.yaml
└── commands/summarize.md

The whole plugin directory is installed, so a pack at the repository root can keep its CI configuration, tests and README next to its workflows. Only folders holding exactly one direct YAML file load as workflows.

{
"schemaVersion": 1,
"kind": "workflow-pack",
"name": "review-kit",
"description": "Review workflows",
"compatibility": { "archon": ">=0.11.0" },
"entrypoints": { "review": "review/review.yaml" }
}
  • Identity. An entrypoint is listed and run as owner/plugin:entrypoint: owner is the GitHub owner from the install id and plugin is the manifest name, so the pack above installed from acme/review-kit runs as archon workflow run acme/review-kit:review. The YAML name: is how workflows refer to each other inside the pack.
  • Support workflows. Every workflow that is not an entrypoint is support. An entrypoint uses it with include: (by its YAML name:), and nothing else can run it: not the CLI, chat, the router, the API, another pack, or a project workflow. Inside a pack, a workflow: child run may launch another entrypoint of the pack by its YAML name:, but not a support workflow, because a child run is dispatch.
  • Names. A qualified name matches exactly (case-sensitive) and never by suffix or substring, and a project or global workflow that declares an installed name is not loaded. Inside a pack, a reference to a YAML name: shared by multiple files fails discovery; when the files have distinct public identities, use a qualified identity such as acme/review-kit:review to select the intended target. Qualified identities take precedence over colliding authored names. Support identities use the YAML name:, so two support files with the same name also have the same public identity and fail discovery. Rename one support workflow and update its references; qualification cannot distinguish them.
  • Runs keep their revision. A run freezes the pack at the commit it started with, and a workflow: child takes the packs its parent froze. archon plugin update or remove affects only runs that start afterwards.
  • Installed or copied. An installed pack is read-only and changes only through archon plugin update. To change one for a single project, archon plugin copy <id> writes it to .archon/workflows/<name>/, where it is an ordinary project pack: its workflows run under their own name:, and update no longer touches it.

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

~/.archon/workflows/my-review.yaml
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.

A workflow that runs project-agnostic checks:

~/.archon/workflows/lint-check.yaml
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.

A simple workflow for understanding unfamiliar codebases:

~/.archon/workflows/explain.yaml
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

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

~/.archon/commands/review-checklist.md
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

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

Terminal window
# In your dotfiles repo
dotfiles/
└── archon/
β”œβ”€β”€ workflows/
β”‚ β”œβ”€β”€ my-review.yaml
β”‚ └── explain.yaml
└── commands/
└── review-checklist.md

Then symlink during dotfiles setup:

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

Or copy them as part of your dotfiles install script:

Terminal window
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.

The CLI, server, and Web UI discover home-scoped content automatically β€” no flag, no config option.

Terminal window
# 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, add a command node and enter the command name in the inspector. The builder does not currently provide source-grouped command browsing.

Earlier versions of Archon stored global workflows at ~/.archon/.archon/workflows/ (with an extra nested .archon/). Archon no longer reads that location or warns about it, and does not migrate workflows automatically. Set ARCHON_HOME in your shell to your Archon home (default ~/.archon). If $ARCHON_HOME/workflows does not exist, move the old directory:

Terminal window
mv "$ARCHON_HOME/.archon/workflows" "$ARCHON_HOME/workflows"

If the destination already exists, merge the files manually, checking for name conflicts. There was no prior home-scoped commands location, so ~/.archon/commands/ has nothing to migrate.

  1. 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/
  2. Check file extension β€” Workflow files must end in .yaml or .yml.

  3. 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
  4. 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.

  5. Check ARCHON_HOME β€” If you have set ARCHON_HOME to a custom path, global workflows must be at $ARCHON_HOME/workflows/, not ~/.archon/workflows/.