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:
mkdir -p ~/.archon/workflows ~/.archon/commands ~/.archon/scriptsNote on location. These are direct children of
~/.archon/β same level asworkspaces/,archon.db, andconfig.yaml. Earlier Archon versions stored global workflows at~/.archon/.archon/workflows/; see Migrating from the old path below.
Supported layouts
Section titled β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 requiredYAML 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.
Load Priority
Section titled β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.
Installed workflow packs
Section titled βInstalled workflow packsβ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.mdThe 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:owneris the GitHub owner from the install id andpluginis the manifestname, so the pack above installed fromacme/review-kitruns asarchon workflow run acme/review-kit:review. The YAMLname: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 YAMLname:), and nothing else can run it: not the CLI, chat, the router, the API, another pack, or a project workflow. Inside a pack, aworkflow:child run may launch another entrypoint of the pack by its YAMLname:, 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 asacme/review-kit:reviewto select the intended target. Qualified identities take precedence over colliding authored names. Support identities use the YAMLname:, 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 updateorremoveaffects 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 ownname:, andupdateno longer touches it.
Practical Examples
Section titled βPractical ExamplesβPersonal Code Review
Section titled βPersonal Code ReviewβA workflow that runs your preferred review checklist on every project:
name: my-reviewdescription: Personal code review with my standardsmodel: 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
Section titled βCustom Linting or Formatting CheckβA workflow that runs project-agnostic checks:
name: lint-checkdescription: 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
Section titled βQuick ExplainβA simple workflow for understanding unfamiliar codebases:
name: explaindescription: Quick explanation of a codebase or modulemodel: 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: $ARGUMENTSPersonal Command Helpers
Section titled β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 clevernessBe terse. Report findings grouped by file.A workflow in any repo can then reference it:
nodes: - id: review command: review-checklistSyncing with Dotfiles
Section titled βSyncing with DotfilesβIf you manage your configuration with a dotfiles repository, you can include your global content:
# In your dotfiles repodotfiles/βββ archon/ βββ workflows/ β βββ my-review.yaml β βββ explain.yaml βββ commands/ βββ review-checklist.mdThen symlink during dotfiles setup:
ln -sf ~/dotfiles/archon/workflows ~/.archon/workflowsln -sf ~/dotfiles/archon/commands ~/.archon/commandsOr copy them as part of your dotfiles install script:
mkdir -p ~/.archon/workflows ~/.archon/commandscp ~/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
Section titled βCLI and Web SupportβThe CLI, server, and Web UI discover home-scoped content automatically β no flag, no config option.
# Lists bundled + global + repo-specific workflowsarchon workflow list
# Run a global workflow from any repoarchon workflow run my-reviewIn 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.
Migrating from the old path
Section titled βMigrating from the old pathβ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:
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.
Troubleshooting
Section titled βTroubleshootingβWorkflow Not Appearing in List
Section titled β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
.yamlor.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_HOMEto a custom path, global workflows must be at$ARCHON_HOME/workflows/, not~/.archon/workflows/.
