archon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Archon CLI Skill

Archon CLI 技能

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.

Archon是一个远程智能编码平台，可在隔离的Git工作树中运行AI工作流。本技能将教你如何运行工作流、创建新的工作流和命令，以及管理Archon配置。

Available Workflows (live)

可用工作流（实时）

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

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:

Intent	Action
Setup / install / "how to use"	Read `guides/setup.md` — interactive setup wizard
Config / settings	Read `guides/config.md` — interactive config editor
Initialize .archon/ in a repo	Read `references/repo-init.md`
Create a workflow	Read `references/workflow-dag.md` — the complete workflow authoring guide
Quick parameter lookup — which field works on which node type	Read `references/parameter-matrix.md` — master matrix, intent-based lookup, silent-failure catalog
Advanced features (hooks/MCP/skills)	Read `references/dag-advanced.md`
Create a command file	Read `references/authoring-commands.md`
Variable substitution reference	Read `references/variables.md`
CLI command reference	Read `references/cli-commands.md`
Run an interactive workflow	Read `references/interactive-workflows.md` — transparent relay protocol
Workflow good practices / anti-patterns	Read `references/good-practices.md` — read before designing a non-trivial workflow
Troubleshoot a failing / stuck workflow	Read `references/troubleshooting.md` — log locations, common failure modes
Run a workflow (default)	Continue with "Running Workflows" below

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

判断用户意图并分配至对应指南：

意图	操作
搭建/安装/"使用方法"	阅读 `guides/setup.md` —— 交互式搭建向导
配置/设置	阅读 `guides/config.md` —— 交互式配置编辑器
在仓库中初始化.archon/	阅读 `references/repo-init.md`
创建工作流	阅读 `references/workflow-dag.md` —— 完整的工作流创作指南
快速参数查询——哪些字段适用于哪种节点类型	阅读 `references/parameter-matrix.md` —— 主参数矩阵、基于意图的查询、静默故障目录
高级功能（钩子/MCP/技能）	阅读 `references/dag-advanced.md`
创建命令文件	阅读 `references/authoring-commands.md`
变量替换参考	阅读 `references/variables.md`
CLI命令参考	阅读 `references/cli-commands.md`
运行交互式工作流	阅读 `references/interactive-workflows.md` —— 透明中继协议
工作流最佳实践/反模式	阅读 `references/good-practices.md` —— 在设计非 trivial 工作流前必读
故障排查（失败/卡住的工作流）	阅读 `references/troubleshooting.md` —— 日志位置、常见故障模式
运行工作流（默认）	继续阅读下方的"运行工作流"章节

若意图不明确，请询问用户以澄清。

Richer Context: archon.diy

更多上下文：archon.diy

The references in this skill are a distilled subset. The full, canonical docs live at archon.diy (Starlight site from

packages/docs-web/

). If the skill's reference pages don't cover what you need — an edge case, a worked example, a diagram, a deeper section on a feature — fetch the matching page from archon.diy.

本技能中的参考内容是提炼后的子集。完整的官方文档托管在 archon.diy（基于

packages/docs-web/

的Starlight站点）。如果本技能的参考页面未覆盖你的需求——比如边缘案例、完整示例、图表、功能深度解析——请从archon.diy获取对应页面。

When to reach for the live docs

何时使用在线文档

You need an end-to-end example that's longer than what the skill shows (e.g. full patterns for hooks, MCP config, sandbox schema, approval flows)
You're explaining a concept to the user and want the most readable framing (the
```
book/
```
series is written as a tutorial, not a reference)
You hit a feature the skill only mentions in passing (e.g.
```
agents:
```
inline sub-agents, advanced Codex options, the full SyncHookJSONOutput schema)
The user asks "where is this documented?" — point them at the archon.diy URL, not a skill file path

你需要比本技能展示更长的端到端示例（例如钩子、MCP配置、沙箱 schema、审批流程的完整模式）
你需要向用户解释概念并希望使用最易读的表述（
```
book/
```
系列为教程式编写，而非参考文档）
你遇到本技能仅提及的功能（例如
```
agents:
```
内联子代理、高级Codex选项、完整的SyncHookJSONOutput schema）
用户询问"此功能在哪里有文档？"——指向archon.diy的URL，而非技能文件路径

URL map

URL映射

Topic	URL
Landing + install	archon.diy
Getting started (installation, quick start, concepts)	archon.diy/getting-started/
The book (tutorial-style walkthrough)	archon.diy/book/
Workflow authoring guide	archon.diy/guides/authoring-workflows/
Command authoring guide	archon.diy/guides/authoring-commands/
Node type guides	archon.diy/guides/loop-nodes/, /approval-nodes/, /script-nodes/
Per-node features (Claude only)	/hooks/, /mcp-servers/, /skills/
Global workflows/commands/scripts	archon.diy/guides/global-workflows/
Variables reference	archon.diy/reference/variables/
CLI reference	archon.diy/reference/cli/
Security model (env, sandbox, target-repo `.env` stripping)	archon.diy/reference/security/
Architecture	archon.diy/reference/architecture/
Configuration ( `.archon/config.yaml` full schema)	archon.diy/reference/configuration/
Troubleshooting	archon.diy/reference/troubleshooting/
Adapter setup (Slack/Telegram/GitHub/Web/Discord/Gitea/GitLab)	archon.diy/adapters/
Deployment (Docker, cloud, Windows)	archon.diy/deployment/

URL shape is

archon.diy/<section>/<page>/

— the paths mirror the filenames under

packages/docs-web/src/content/docs/

主题	URL
首页 + 安装	archon.diy
入门指南（安装、快速开始、概念）	archon.diy/getting-started/
教程书籍（分步讲解）	archon.diy/book/
工作流创作指南	archon.diy/guides/authoring-workflows/
命令创作指南	archon.diy/guides/authoring-commands/
节点类型指南	archon.diy/guides/loop-nodes/、/approval-nodes/、/script-nodes/
节点专属功能（仅Claude）	/hooks/、/mcp-servers/、/skills/
全局工作流/命令/脚本	archon.diy/guides/global-workflows/
变量参考	archon.diy/reference/variables/
CLI参考	archon.diy/reference/cli/
安全模型（环境变量、沙箱、目标仓库 `.env` 清理）	archon.diy/reference/security/
架构	archon.diy/reference/architecture/
配置（ `.archon/config.yaml` 完整schema）	archon.diy/reference/configuration/
故障排查	archon.diy/reference/troubleshooting/
适配器搭建（Slack/Telegram/GitHub/Web/Discord/Gitea/GitLab）	archon.diy/adapters/
部署（Docker、云服务、Windows）	archon.diy/deployment/

URL格式为

archon.diy/<section>/<page>/

—— 路径与

packages/docs-web/src/content/docs/

下的文件名一致。

Precedence

优先级

This skill's reference pages are the primary source for routine workflow authoring, CLI use, and setup. Reach for archon.diy when the skill is incomplete for your case — don't go to the live docs first by default (skill refs load into context faster and are tuned for agents).

本技能的参考页面是日常工作流创作、CLI使用和搭建的主要来源。仅当本技能内容不足以满足需求时，再使用archon.diy——不要默认优先使用在线文档（技能参考加载到上下文的速度更快，且针对Agent进行了优化）。

Running Workflows

运行工作流

Core Command

核心命令

bash

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

CRITICAL RULES:

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.
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.
One workflow per shell — Each workflow blocks its shell. Run multiple workflows as separate background tasks.

bash

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

关键规则:

始终在后台运行 —— Archon工作流运行时间较长。调用Bash工具时务必使用
```
run_in_background: true
```
。使用
```
/tasks
```
或TaskOutput工具检查进度。
始终使用工作树隔离 —— 除非用户明确要求，否则使用
```
--branch
```
标志。这会创建一个隔离环境，确保Archon工作时不会影响主分支。
每个Shell运行一个工作流 —— 每个工作流会阻塞其所在Shell。将多个工作流作为独立的后台任务运行。

Isolation Modes

隔离模式

Mode	Flag	When to Use
Worktree (Default)	`--branch <name>`	Always use this unless told otherwise
Custom start-point	`--branch <name> --from <base>`	Start from a specific branch
Direct checkout	`--no-worktree`	Only if user explicitly requests no isolation
Resume failed run	`--resume`	Resume from the last failure point

模式	标志	使用场景
工作树（默认）	`--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:

User Intent	Typical Workflow	Branch Pattern
"Fix issue #X" / "Resolve bug"	`archon-fix-github-issue`	`fix/issue-{N}`
"Review PR #X" / "Full review"	`archon-comprehensive-pr-review`	`review/pr-{N}`
"Quick review PR #X"	`archon-smart-pr-review`	`review/pr-{N}`
"Validate PR #X" / "Check PR"	`archon-validate-pr`	`review/pr-{N}`
"Implement from plan"	`archon-feature-development`	`feat/{name}`
"Plan and implement feature"	`archon-idea-to-pr`	`feat/{name}`
"Execute plan file"	`archon-plan-to-pr`	`feat/{name}`
"Run ralph" / "Implement PRD"	`archon-ralph-dag`	`feat/{name}`
"Resolve conflicts"	`archon-resolve-conflicts`	`resolve/pr-{N}`
"Create issue" / "File a bug"	`archon-create-issue`	`issue/{name}`
"Review issue #X fully"	`archon-issue-review-full`	`review/issue-{N}`
"Refactor safely"	`archon-refactor-safely`	`refactor/{name}`
"Architecture review"	`archon-architect`	`review/{name}`
"PIV loop" / "guided dev"	`archon-piv-loop` ⚡	`piv/{name}`
"Create a PRD" / "interactive PRD"	`archon-interactive-prd` ⚡	`prd/{name}`
General / debugging	`archon-assist`	`assist/{description}`

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

references/interactive-workflows.md

before running.

If no specific workflow matches, use

archon-assist

as the fallback. The live workflow list above is always authoritative — it may include workflows not in this table.

将用户意图与上方的实时工作流列表匹配。常见模式：

用户意图	典型工作流	分支模式
"修复问题#X" / "解决bug"	`archon-fix-github-issue`	`fix/issue-{N}`
"审核PR #X" / "全面审核"	`archon-comprehensive-pr-review`	`review/pr-{N}`
"快速审核PR #X"	`archon-smart-pr-review`	`review/pr-{N}`
"验证PR #X" / "检查PR"	`archon-validate-pr`	`review/pr-{N}`
"根据方案实现功能"	`archon-feature-development`	`feat/{name}`
"规划并实现功能"	`archon-idea-to-pr`	`feat/{name}`
"执行方案文件"	`archon-plan-to-pr`	`feat/{name}`
"运行ralph" / "实现PRD"	`archon-ralph-dag`	`feat/{name}`
"解决冲突"	`archon-resolve-conflicts`	`resolve/pr-{N}`
"创建问题" / "提交bug"	`archon-create-issue`	`issue/{name}`
"全面审核问题#X"	`archon-issue-review-full`	`review/issue-{N}`
"安全重构"	`archon-refactor-safely`	`refactor/{name}`
"架构审核"	`archon-architect`	`review/{name}`
"PIV循环" / "引导式开发"	`archon-piv-loop` ⚡	`piv/{name}`
"创建PRD" / "交互式PRD"	`archon-interactive-prd` ⚡	`prd/{name}`
通用/调试	`archon-assist`	`assist/{description}`

⚡ = 交互式工作流 —— 需要透明中继协议。运行前请阅读

references/interactive-workflows.md

。

若没有匹配的特定工作流，使用

archon-assist

作为备选。上方的实时工作流列表始终是权威的——可能包含本表未列出的工作流。

Multi-Issue Invocation

多任务调用

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

bash

undefined

当用户提及多个问题、PR或任务时——将每个任务作为独立的后台任务运行：

bash

undefined

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

其他CLI命令

bash

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

bash

archon workflow list              # 列出所有可用工作流
archon workflow list --json       # 机器可读的JSON格式
archon isolation list             # 显示活跃的工作树环境
archon isolation cleanup          # 移除过期工作树（默认：7天）
archon isolation cleanup --merged # 移除已合并到主分支的分支
archon complete <branch>          # 完成分支生命周期（移除工作树+分支）
archon version                    # 显示版本信息

如需包含所有标志的完整CLI参考：阅读

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.

Archon使用单一工作流格式：节点（DAG）。工作流是

.archon/workflows/

目录下的YAML文件。

重要提示：以下示例为起始模板。请始终根据用户实际需求设计工作流——节点数量、类型、依赖关系和配置应匹配用户需求，而非这些模板。

Workflow Structure

工作流结构

yaml

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]

yaml

name: my-workflow
description: What this workflow does
provider: claude          # 可选：'claude'或'codex'
model: sonnet             # 可选：模型覆盖
nodes:
  - id: first-node
    command: my-command    # 加载.archon/commands/my-command.md
  - id: second-node
    prompt: "Use the output: $first-node.output"
    depends_on: [first-node]

Node Types

节点类型

Each node has exactly ONE of:

command

prompt

bash

script

loop

approval

, or

cancel

Command node — runs a

.archon/commands/*.md

file:

yaml

- id: investigate
  command: investigate-issue

Prompt node — inline AI prompt:

yaml

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

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

yaml

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

Script node — TypeScript/JavaScript (via

bun

) or Python (via

uv

), no AI, stdout captured as output:

yaml

- id: transform
  script: |
    const raw = process.argv.slice(2).join(' ') || '{}';
    console.log(JSON.stringify({ parsed: JSON.parse(raw) }));
  runtime: bun           # 'bun' (.ts/.js) or 'uv' (.py) — REQUIRED
  timeout: 30000         # Optional, ms, default 120000

每个节点必须包含以下类型之一：

command

、

prompt

、

bash

、

script

、

loop

、

approval

或

cancel

。

命令节点 —— 运行

.archon/commands/*.md

文件：

yaml

- id: investigate
  command: investigate-issue

提示节点 —— 内联AI提示：

yaml

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

Bash节点 —— Shell脚本，无AI，标准输出会被捕获为输出：

yaml

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

脚本节点 —— TypeScript/JavaScript（通过

bun

）或Python（通过

uv

），无AI，标准输出会被捕获为输出：

yaml

- id: transform
  script: |
    const raw = process.argv.slice(2).join(' ') || '{}';
    console.log(JSON.stringify({ parsed: JSON.parse(raw) }));
  runtime: bun           # 'bun'（.ts/.js）或'uv'（.py）—— 必填
  timeout: 30000         # 可选，毫秒，默认120000

Or reference a named script from .archon/scripts/ or ~/.archon/scripts/

或引用.archon/scripts/或~/.archon/scripts/下的命名脚本

id: analyze script: analyze-metrics # loads .archon/scripts/analyze-metrics.py runtime: uv deps: ["pandas>=2.0"] # Optional, uv only — 'uv run --with <dep>'


**Loop node** — iterates AI prompt until completion:
```yaml
- 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

Approval node — pauses the workflow for human review. Requires

interactive: true

at the workflow level for Web UI delivery:

yaml

interactive: true   # workflow level — required for web UI

nodes:
  - id: review-gate
    approval:
      message: "Review the plan above before proceeding."
      capture_response: true      # Optional: user's comment → $review-gate.output
      on_reject:                  # Optional: AI rework on rejection instead of cancel
        prompt: "Revise based on feedback: $REJECTION_REASON"
        max_attempts: 3           # Range 1-10, default 3
    depends_on: [plan]

Cancel node — terminates the workflow with a reason. Typically gated with

when:

yaml

- id: stop-if-unsafe
  cancel: "Refusing to proceed: input flagged UNSAFE."
  depends_on: [classify]
  when: "$classify.output != 'SAFE'"

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

references/workflow-dag.md

id: analyze script: analyze-metrics # 加载.archon/scripts/analyze-metrics.py runtime: uv deps: ["pandas>=2.0"] # 可选，仅uv支持——'uv run --with <dep>'


**循环节点** —— 重复执行AI提示直到完成：
```yaml
- 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"    # 可选：exit 0表示完成

审批节点 —— 暂停工作流等待人工审核。如需通过Web UI交付，需在工作流级别设置

interactive: true

：

yaml

interactive: true   # 工作流级别——Web UI必填

nodes:
  - id: review-gate
    approval:
      message: "Review the plan above before proceeding."
      capture_response: true      # 可选：用户评论→$review-gate.output
      on_reject:                  # 可选：拒绝后AI重新处理，而非取消
        prompt: "Revise based on feedback: $REJECTION_REASON"
        max_attempts: 3           # 范围1-10，默认3
    depends_on: [plan]

取消节点 —— 终止工作流并给出原因。通常与

when:

配合使用：

yaml

- id: stop-if-unsafe
  cancel: "Refusing to proceed: input flagged UNSAFE."
  depends_on: [classify]
  when: "$classify.output != 'SAFE'"

如需包含所有字段、条件、触发规则和模式的完整创作指南：阅读

references/workflow-dag.md

Creating a Command File

创建命令文件

Commands are

.md

files in

.archon/commands/

containing AI prompt templates:

markdown

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

命令是

.archon/commands/

目录下的

.md

文件，包含AI提示模板：

markdown

---
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`

User request: $ARGUMENTS Workflow artifacts: $ARTIFACTS_DIR

[Instructions for the AI agent]


如需完整的命令创作指南：阅读`references/authoring-commands.md`

Key Variables

关键变量

Variable	Description
`$ARGUMENTS`	User's input message
`$ARTIFACTS_DIR`	Pre-created directory for workflow artifacts
`$BASE_BRANCH`	Base branch (auto-detected from git)
`$WORKFLOW_ID`	Unique workflow run ID
`$nodeId.output`	Output from upstream node

Full variable reference: Read

references/variables.md

变量	描述
`$ARGUMENTS`	用户输入消息
`$ARTIFACTS_DIR`	预创建的工作流产物目录
`$BASE_BRANCH`	基础分支（从Git自动检测）
`$WORKFLOW_ID`	唯一的工作流运行ID
`$nodeId.output`	上游节点的输出

完整变量参考：阅读

references/variables.md

Advanced Features (Command/Prompt Nodes, Claude Only)

高级功能（命令/提示节点，仅Claude）

hooks

(tool interception),

mcp

(external tool servers),

skills

(domain knowledge injection),

output_format

(structured JSON output),

allowed_tools

denied_tools

(tool restrictions).

For details: Read

references/dag-advanced.md

hooks

（工具拦截）、

mcp

（外部工具服务器）、

skills

（领域知识注入）、

output_format

（结构化JSON输出）、

allowed_tools

denied_tools

（工具限制）。

详情：阅读

references/dag-advanced.md

Example Files

示例文件

```
examples/dag-workflow.yaml
```
— workflow with conditions, bash + script + loop nodes, structured output
```
examples/command-template.md
```
— Command file skeleton with all variables

```
examples/dag-workflow.yaml
```
—— 包含条件、bash+脚本+循环节点、结构化输出的工作流
```
examples/command-template.md
```
—— 包含所有变量的命令文件模板

Example Interactions

交互示例

User: "Use Archon to fix issue #42"

bash

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

User: "Have Archon review PR #15"

bash

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

and create a workflow with parallel review nodes.

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

references/workflow-dag.md

and create nodes with

when:

conditions and

output_format

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

references/authoring-commands.md

and create an

.md

file in

.archon/commands/

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

references/repo-init.md

to create the

.archon/

directory structure.

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

references/repo-init.md

, then the appropriate workflow reference.

用户："Use Archon to fix issue #42"

bash

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

用户："Have Archon review PR #15"

bash

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

用户："Create a workflow that reviews code and runs tests" → 阅读

references/workflow-dag.md

并创建包含并行审核节点的工作流。

用户："Make a workflow with conditional routing" → 阅读

references/workflow-dag.md

并创建带有

when:

条件和

output_format

的节点。

用户："Write a command file for investigating bugs" → 阅读

references/authoring-commands.md

并在

.archon/commands/

目录下创建一个

.md

文件。

用户："Set up Archon in this repo" → 阅读

references/repo-init.md

创建

.archon/

目录结构。

用户："Initialize .archon and create a custom workflow" → 先阅读

references/repo-init.md

，再阅读对应的工作流参考文档。