Use this file to discover all available pages before exploring further.
Commands are the building blocks of Archon workflows. Each command is a markdown file that serves as a detailed instruction set for an AI agent. When a workflow executes command: investigate-issue, Archon loads the file, substitutes variables, and sends the content as a prompt to the AI. This page explains how to write effective commands.
A command file is a .md file placed in .archon/commands/ relative to your working directory. Archon discovers them at runtime and makes them available to workflow command: nodes and slash commands.
.archon/commands/investigate-issue.md
---description: Investigate a GitHub issue and produce an implementation planargument-hint: <issue-number or description>---# Investigate Issue**Input**: $ARGUMENTS---## Your missionAnalyze the reported issue and produce a detailed implementation plan artifact.**Output artifact**: `$ARTIFACTS_DIR/issues/issue-$1.md`## Phase 1: Load context1. Read the issue description: `gh issue view $1`2. Find relevant source files using search tools3. Read the files and trace the code path## Phase 2: PlanCreate a step-by-step implementation plan with:- Specific file paths and line numbers to change- Before/after code snippets- Validation commands to verify the fix## Phase 3: Save artifactWrite the complete plan to `$ARTIFACTS_DIR/issues/issue-$1.md`.
Global — ~/.archon/commands/ (applies to every project)
Project — .archon/commands/ in your repo (overrides globals and defaults by filename)
Subdirectories are not supported for commands. Same-named files in your repo override bundled defaults.
CLI vs. server: The CLI reads commands from wherever you run it (sees uncommitted changes). The server reads from ~/.archon/workspaces/owner/repo/ and only sees changes that have been pushed.
In multi-step workflows, agents don’t share memory between nodes (especially with fresh_context: true). The only way to pass information between steps is through artifact files written to $ARTIFACTS_DIR.
Step 1: investigate Step 2: implement┌─────────────────┐ ┌─────────────────┐│ AI reads issue │ │ AI reads plan ││ Produces plan ──┼──────►│ Executes plan │└─────────────────┘ └─────────────────┘ │ ▼ $ARTIFACTS_DIR/ issues/issue-42.md
A good artifact contains everything the next agent needs — specific file paths, line numbers, code snippets, validation commands, and edge cases. A vague artifact causes the next step to fail or produce low-quality output.
Break commands into named phases so the AI knows where it is in the process and can self-verify before proceeding:
.archon/commands/implement-feature.md
---description: Implement a feature from an existing plan artifactargument-hint: <feature-name>---# Implement Feature**Input**: $ARGUMENTS---## Phase 1: LOAD — Get context1. Load the plan: `cat $ARTIFACTS_DIR/plans/$1.md`2. Read the files listed in the plan3. Confirm you understand all required changes**PHASE_1_CHECKPOINT:**- [ ] Plan loaded and understood- [ ] All relevant files read---## Phase 2: IMPLEMENT — Make changesFollow the plan step by step. After each file change, run:```bashbun run type-check
<Tip>Use checkpoints (`PHASE_N_CHECKPOINT`) so the AI self-verifies before moving to the next phase. This significantly reduces errors in long-running commands.</Tip>## Anti-patterns to avoid<AccordionGroup> <Accordion title="Vague instructions"> **Bad:** `Analyze the code and find the problem.` **Good:** Be specific — name the file, the function, the error type. Tell the agent exactly what to search for and what to document. Vague instructions produce vague artifacts, and the next workflow node will have nothing concrete to act on. </Accordion> <Accordion title="Missing artifact instructions"> **Bad:** `Output your findings.` **Good:** Specify the exact artifact path and format. Treat the artifact as the handoff document to the next agent — it must be complete and self-contained with file paths, line numbers, and validation steps. </Accordion> <Accordion title="Assuming context across nodes"> **Bad:** `Fix the bug in the file we discussed.` **Good:** Load the artifact explicitly at the start of the command. Reference `$ARTIFACTS_DIR/issues/issue-$1.md` so the agent knows exactly where to find the context — never assume it persists from a previous node. </Accordion> <Accordion title="No error handling"> **Bad:** `Create the PR.` **Good:** Check if a PR already exists first. If it does, update it. If not, create a new draft PR. Always handle the case where the previous step produced no changes — the command should gracefully exit rather than failing the whole workflow. </Accordion></AccordionGroup>## Testing your command```bash# Run the workflow that uses this command with test inputarchon workflow run my-workflow "test input"# Validate the command file is syntactically correctarchon validate commands my-command
After the run, check the artifacts directory:
ls ~/.archon/workspaces/owner/repo/artifacts/runs/
Verify the artifact contains everything needed for the next workflow step.
