archon

Archon CLI スキル

Archon は、分離された git worktree で AI ワークフローを実行するリモートのエージェント型コーディングプラットフォームです。このスキルでは、ワークフローの実行、新しいワークフローとコマンドの作成、Archon の設定管理について説明します。

利用可能なワークフロー（リアルタイム）

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

ルーティング

ユーザーの意図を判断し、適切なガイドを参照してください。

意図	アクション
セットアップ／インストール／「使い方」	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 を参照 — 複雑なワークフローを設計する前にお読みください
失敗または停止したワークフローのトラブルシューティング	references/troubleshooting.md を参照 — ログの場所、一般的な失敗原因
ワークフローを実行（デフォルト）	以下の「ワークフローの実行」に進みます

意図が曖昧な場合は、ユーザーに確認してください。

---

より詳しい情報：archon.diy

このスキル内のリファレンスは、内容を抜粋したものです。完全かつ正式なドキュメントは archon.diy（packages/docs-web/ にある Starlight サイト）にあります。このスキルのリファレンスページで必要な情報（特殊なケース、実例、図、機能の詳しい説明など）が見つからない場合は、archon.diy から該当ページを取得してください。

ライブドキュメントを参照するタイミング

• スキルの説明より詳しい、一連の流れがわかる例が必要な場合（例：フック、MCP 設定、サンドボックススキーマ、承認フローの完全なパターン）
• ユーザーに概念を説明する際、最も読みやすい説明が必要な場合（book/ シリーズはリファレンスではなくチュートリアルとして書かれています）
• スキルで簡単に触れられているだけの機能に行き当たった場合（例：agents: インラインサブエージェント、高度な Codex オプション、完全な SyncHookJSONOutput スキーマ）
• ユーザーが「どこに説明がありますか？」と尋ねた場合 — スキルファイルのパスではなく、archon.diy の URL を案内してください

URL マップ

トピック	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 の完全なスキーマ）	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/ 配下のファイル名と対応しています。

優先順位

このスキルのリファレンスページは、通常のワークフロー作成、CLI の使用、セットアップに関する主要な情報源です。スキルの情報が個別のケースに不十分な場合は archon.diy を参照してください。デフォルトでは、最初にライブドキュメントを参照しないでください（スキルのリファレンスはコンテキストにすばやく読み込まれ、エージェント向けに調整されています）。

---

ワークフローの実行

基本コマンド

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

重要なルール：

1. 必ずバックグラウンドで実行する — Archon のワークフローは長時間実行されます。必ず run_in_background: true を指定して Bash ツールを呼び出してください。進行状況の確認には /tasks または TaskOutput ツールを使用してください。

2. 必ずワークツリーで分離する — ユーザーから明示的な指示がない限り、--branch フラグを使用してください。これにより、Archon がメインブランチに影響を与えずに動作できる分離環境が作成されます。

3. シェルごとにワークフローは1つ — 各ワークフローはシェルを占有します。複数のワークフローは、それぞれ別のバックグラウンドタスクとして実行してください。

分離モード

モード	フラグ	使用する場面
ワークツリー（デフォルト）	--branch <name>	指示がない限り、常にこれを使用します
カスタム開始地点	--branch <name> --from <base>	特定のブランチを起点にする場合
直接チェックアウト	--no-worktree	ユーザーが分離しないよう明示的に要求した場合のみ
失敗した実行の再開	--resume	最後に失敗した地点から再開する場合

ワークフローの選択

ユーザーの意図に、上記の最新リストからワークフローを対応付けます。よくあるパターン：

ユーザーの意図	代表的なワークフロー	ブランチのパターン
「issue #X を修正」／「バグを解決」	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}
「issue を作成」／「バグを報告」	archon-create-issue	issue/{name}
「issue #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 を使用します。上記の最新ワークリストは常に優先されます。この表にないワークフローが含まれる場合があります。

複数の issue の実行

ユーザーが複数の issue、PR、またはタスクに言及した場合は、それぞれを別個のバックグラウンドタスクとして実行します：

# 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"

複数の issue を単一のコマンドにまとめてはいけません。

---

その他の CLI コマンド

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

すべてのフラグを含む CLI の完全なリファレンスについては、references/cli-commands.md を読んでください。

---

作成のクイックスタート

Archon は単一のワークフロー形式であるノード（DAG）を使用します。ワークフローは .archon/workflows/ 内の YAML ファイルです。

重要：以下の例は出発点です。ワークフローは常に、ユーザーが実際に必要としていることに合わせて設計してください。ノードの数、種類、依存関係、設定は、これらのテンプレートではなく、ユーザーの要件に合わせる必要があります。

ワークフローの構造

name: my-workflow
description: What this workflow does
provider: claude          # Optional: 'claude', 'codex', 'pi', ... (default: from config)
model: medium             # Optional: tier keyword (small|medium|large), @alias, or literal model
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]

ノードの種類

各ノードには、command、prompt、bash、script、loop、loop_group、approval、cancel のいずれか1つだけを指定します。

Command ノード — .archon/commands/*.md ファイルを実行します：

- id: investigate
  command: investigate-issue

Prompt ノード — インライン AI プロンプトです：

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

Bash ノード — AI を使用せずにシェルスクリプトを実行し、標準出力を出力として取得します：

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

Script ノード — AI を使用せずに TypeScript／JavaScript（bun 経由）または Python（uv 経由）を実行し、標準出力を出力として取得します：

- 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

# Or reference a named script from .archon/scripts/ or ~/.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 ノード — 完了するまで AI プロンプトを繰り返します。until／until_bash の少なくとも一方を宣言します。条件が決定的な場合は until を省略し、文章との照合を一切行わないようにします：

- id: implement
  loop:
    prompt: "Implement next story. When done: <promise>COMPLETE</promise>"
    until: COMPLETE               # Prose signal
    max_iterations: 10
    fresh_context: true
    until_bash: "bun run test"    # Exit 0 = done
    # until_field: done           # Or: a declared boolean in this node's output_format
    # At least ONE of until / until_bash / until_field

Loop group ノード — 反復ごとに複数ノードのサブ DAG 本体を繰り返します（実装 → テスト → レビューを1つの反復サイクルとして実行します）：

- id: fix-cycle
  loop_group:
    nodes:
      - id: implement
        prompt: "Implement the next fix. Last review: $LOOP_PREV.review.output"
      - id: test
        bash: "bun run test 2>&1 || true"
        depends_on: [implement]
      - id: review
        prompt: "Review diff + tests: $test.output. All good? <promise>SHIP</promise>"
        depends_on: [test]
    until: SHIP
    max_iterations: 6

Approval ノード — 人によるレビューのためにワークフローを一時停止します。Web UI で配信するには、ワークフローレベルで interactive: true が必要です：

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 ノード — 理由を示してワークフローを終了します。通常は when: で条件を設定します：

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

すべてのフィールド、条件、トリガールール、パターンを含む作成ガイド全文については、references/workflow-dag.md を読んでください。

コマンドファイルの作成

コマンドは .archon/commands/ 内の .md ファイルで、AI プロンプトのテンプレートを含みます：

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

# My Command

User request: $ARGUMENTS
Workflow artifacts: $ARTIFACTS_DIR

[Instructions for the AI agent]

コマンド作成ガイド全文については、references/authoring-commands.md を読んでください。

主要な変数

変数	説明
$ARGUMENTS	ユーザーの入力メッセージ
$ARTIFACTS_DIR	ワークフローの成果物用に事前作成されたディレクトリ
$BASE_BRANCH	ベースブランチ (git から自動検出)
$WORKFLOW_ID	ワークフロー実行の一意な ID
$nodeId.output	上流ノードからの出力 (.field アクセスは厳格です — 変数リファレンスを参照)
$LOOP_PREV_OUTPUT / $LOOP_PREV.<id>.output	前回の loop / loop_group イテレーションの出力
$LOOP_USER_INPUT / $REJECTION_REASON	ループゲート / 承認拒否時の人によるフィードバック

完全な変数リファレンス: references/variables.md を参照してください

高度な機能 (コマンド/プロンプトノード)

output_format (構造化 JSON 出力 — すべてのプロバイダー、スキーマ検証済み、不一致時はノードが失敗)、hooks (ツールインターセプト — Claude のみ)、mcp (外部ツールサーバー — Pi を除くすべてのプロバイダー)、skills (Claude/Pi/OpenCode/Copilot でのノード単位の注入; Codex はファイルシステム経由)、allowed_tools/denied_tools (ツール制限 — Codex を除くすべて)、agents (サブエージェント — Claude ではインライン定義; OpenCode/Copilot は名前で CONFIGURED エージェントを選択し、インライン定義は使用しません)、persist_session (実行をまたぐ AI メモリ)、output_type (型付き成果物サイドカー)。

詳細: references/dag-advanced.md を参照してください

サンプルファイル

• examples/dag-workflow.yaml — 条件、bash + script + loop ノード、構造化出力を含むワークフロー
• examples/command-template.md — すべての変数を含むコマンドファイルのスケルトン

---

対話例

ユーザー: 「Archon を使って issue #42 を修正して」

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

ユーザー: 「Archon に PR #15 をレビューさせて」

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

ユーザー: 「コードをレビューしてテストを実行するワークフローを作成して」 → references/workflow-dag.md を読み、並列レビューノードを含むワークフローを作成します。

ユーザー: 「条件付きルーティングを含むワークフローを作成して」 → references/workflow-dag.md を読み、when: 条件と output_format を含むノードを作成します。

ユーザー: 「バグを調査するためのコマンドファイルを書いて」 → references/authoring-commands.md を読み、.archon/commands/ に .md ファイルを作成します。

ユーザー: 「このリポジトリで Archon をセットアップして」 → references/repo-init.md を読み、.archon/ ディレクトリ構造を作成します。

ユーザー: 「.archon を初期化してカスタムワークフローを作成して」 → まず references/repo-init.md を読み、次に適切なワークフローリファレンスを読みます。