Archon CLI Skill

Archon is a remote agentic coding platform that runs AI workflows in isolated git worktrees. This skill teaches you how to run workflows, create new workflows and commands, and manage Archon configuration.

Available Workflows (live)

!

archon workflow list 2>&1 || echo "Archon CLI not installed. Read guides/setup.md to set it up."

Routing

Determine the user's intent and dispatch to the appropriate guide:

guides/setup.md

guides/config.md

references/repo-init.md

references/workflow-dag.md

references/dag-advanced.md

references/authoring-commands.md

references/variables.md

references/cli-commands.md

references/interactive-workflows.md

If the intent is ambiguous, ask the user to clarify.

Running Workflows

Core Command

archon workflow run <workflow-name> --branch <branch-name> "<message>"

CRITICAL RULES:

1. Always run in background — Archon workflows are long-running. Always invoke the Bash tool with

   run_in_background: true

   . Use

   /tasks

   or the TaskOutput tool to check on progress.

2. Always use worktree isolation — Use the

   --branch

   flag unless the user explicitly requests otherwise. This creates an isolated environment so Archon works without affecting the main branch.

3. One workflow per shell — Each workflow blocks its shell. Run multiple workflows as separate background tasks.

Isolation Modes

--branch <name>

--branch <name> --from <base>

--no-worktree

--resume

Workflow Selection

Match the user's intent to a workflow from the live list above. Common patterns:

archon-fix-github-issue

fix/issue-{N}

archon-comprehensive-pr-review

review/pr-{N}

archon-smart-pr-review

review/pr-{N}

archon-validate-pr

review/pr-{N}

archon-feature-development

feat/{name}

archon-idea-to-pr

feat/{name}

archon-plan-to-pr

feat/{name}

archon-ralph-dag

feat/{name}

archon-resolve-conflicts

resolve/pr-{N}

archon-create-issue

issue/{name}

archon-issue-review-full

review/issue-{N}

archon-refactor-safely

refactor/{name}

archon-architect

review/{name}

archon-piv-loop

piv/{name}

archon-interactive-prd

prd/{name}

archon-assist

assist/{description}

⚡ = Interactive workflow — requires the transparent relay protocol. Read

references/interactive-workflows.md

If no specific workflow matches, use

archon-assist

Multi-Issue Invocation

When the user mentions multiple issues, PRs, or tasks — run each as a separate background task:

# Each gets its own worktree — they won't conflict
archon workflow run archon-fix-github-issue --branch fix/issue-10 "Fix issue #10"
archon workflow run archon-fix-github-issue --branch fix/issue-11 "Fix issue #11"
archon workflow run archon-fix-github-issue --branch fix/issue-12 "Fix issue #12"

Never combine multiple issues into a single command.

Other CLI Commands

archon workflow list              # List all available workflows
archon workflow list --json       # Machine-readable JSON
archon isolation list             # Show active worktree environments
archon isolation cleanup          # Remove stale worktrees (default: 7 days)
archon isolation cleanup --merged # Remove branches merged into main
archon complete <branch>          # Complete branch lifecycle (remove worktree + branches)
archon version                    # Show version info

For the full CLI reference with all flags: Read

references/cli-commands.md

Authoring Quick Start

Archon uses a single workflow format: nodes (DAG). Workflows are YAML files in

.archon/workflows/

IMPORTANT: The examples below are starting points. Always design the workflow around what the user actually needs — the number of nodes, their types, dependencies, and configuration should match the user's requirements, not these templates.

Workflow Structure

name: my-workflow
description: What this workflow does
provider: claude          # Optional: 'claude' or 'codex'
model: sonnet             # Optional: model override
nodes:
  - id: first-node
    command: my-command    # Loads .archon/commands/my-command.md
  - id: second-node
    prompt: "Use the output: $first-node.output"
    depends_on: [first-node]

Four Node Types

Each node has exactly ONE of:

command

prompt

bash

loop

Command node — runs a

.archon/commands/*.md

- id: investigate
  command: investigate-issue

Prompt node — inline AI prompt:

- id: classify
  prompt: "Classify this issue: $ARGUMENTS"
  model: haiku
  allowed_tools: []

Bash node — shell script, no AI, stdout captured as output:

- id: fetch-data
  bash: "gh issue view 42 --json title,body"
  timeout: 15000

Loop node — iterates AI prompt until completion:

- id: implement
  loop:
    prompt: "Implement next story. When done: <promise>COMPLETE</promise>"
    until: COMPLETE
    max_iterations: 10
    fresh_context: true
    until_bash: "bun run test"    # Optional: exit 0 = done

For the full authoring guide with all fields, conditions, trigger rules, and patterns: Read

references/workflow-dag.md

Creating a Command File

Commands are

.md

.archon/commands/

---
description: What this command does
argument-hint: <expected arguments>
---

# My Command

User request: $ARGUMENTS
Workflow artifacts: $ARTIFACTS_DIR

[Instructions for the AI agent]

For the full command authoring guide: Read

references/authoring-commands.md

Key Variables

$ARGUMENTS

$ARTIFACTS_DIR

$BASE_BRANCH

$WORKFLOW_ID

$nodeId.output

Full variable reference: Read

references/variables.md

Advanced Features (Command/Prompt Nodes, Claude Only)

hooks

mcp

skills

output_format

allowed_tools

denied_tools

For details: Read

references/dag-advanced.md

Example Files

• examples/dag-workflow.yaml

  — workflow with conditions, bash nodes, structured output

• examples/command-template.md

  — Command file skeleton with all variables

Example Interactions

User: "Use Archon to fix issue #42"

archon workflow run archon-fix-github-issue --branch fix/issue-42 "Fix issue #42"

User: "Have Archon review PR #15"

archon workflow run archon-comprehensive-pr-review --branch review/pr-15 "Review PR #15"

User: "Create a workflow that reviews code and runs tests" → Read

references/workflow-dag.md

User: "Make a workflow with conditional routing" → Read

references/workflow-dag.md

when:

output_format

User: "Write a command file for investigating bugs" → Read

references/authoring-commands.md

.md

.archon/commands/

User: "Set up Archon in this repo" → Read

references/repo-init.md

.archon/

User: "Initialize .archon and create a custom workflow" → First read

references/repo-init.md