archon-cli

Archon CLI

Archon は archon CLI を通じて、複数ステップの AI ワークフローを実行します。Git プロジェクトはデフォルトで分離された worktree で実行され、登録済みフォルダのプロジェクトはその場で実行されます。実行を取りまとめるのはあなたです。概要を書き、起動し、1 つのストリームを監視し、届いた判断事項に回答して、各実行が残したものを確認します。

目的に応じて参照先を選びます。

ユーザーの目的	参照先
実際の作業でワークフローを実行する	operate/running.md
実行を調査、回答、キャンセル、または再開する	operate/managing-runs.md
SDLC パックのキューを操作する	operate/queues.md
実行が失敗または停止する理由を調べる	operate/troubleshooting.md
Archon をセットアップする、または設定を変更する	setup/setup-and-config.md
ワークフローを作成または変更する	authoring/authoring-workflows.md（続けて同じフォルダ内の node-reference.md と variables.md を参照）
ノードのプロンプトまたは実行メッセージを改善する	authoring/prompting-mistakes.md

• 目的が明確な場合（「X のワークフローを作って」「issue #42 で archon-ship を実行して」など）は、該当するリファレンスに直接進みます。質問は不要です。
• 目的が曖昧な場合は、ユーザーがどの項目を希望しているか尋ねます。
• archon doctor が失敗するマシンでは、setup/setup-and-config.md から始めます。

運用の流れ

1. 見つける。 archon workflow list --json で簡潔な説明を確認できます。候補になりそうなものごとに、archon workflow list <name> --full で説明全文を読みます。記憶している名前ではなく、説明全文に基づいて選びます。

2. 概要を確認する。 実行が読み取るメッセージ、issue 本文、またはドキュメントが、実行の評価基準となる契約です。問題、解決する価値がある理由、今取り組む理由、望ましい結果、不変条件、受け入れ条件を明記する必要があります。いずれかが欠けている場合は、欠けている項目を伝え、文案を提案し、起動する前にユーザーの同意を得ます。確認の全容は operate/running.md を参照してください。

3. デタッチモードで起動する。 作業内容をメッセージとして渡すか、ワークフローで宣言された入力を --input で渡すか、または両方を渡します。

   archon workflow run <workflow> --branch <branch-name> "<the work>" --detach
   archon workflow run <workflow> --input <name>=<value> --input <name>=<value> --detach
   

4. 一度だけ監視する。 起動した実行の数にかかわらず、ハーネスのバックグラウンドタスクとして 1 つのストリームを実行します。

   archon workflow attention --watch --json        # this project; add --all for the install
   

   各行は JSON です。attention は実行に判断が必要であることを示し、resolved は不要になったことを示し、terminal は実行が終了したことを示します。行の内容に対応したら、読み取りを続けます。

5. 慎重に回答する。 項目の質問、推奨事項、リンク先の根拠を読みます。理由を添えて、デタッチモードで回答します。 archon workflow respond <run-id> <decision> "<reason>" --detach。 あらゆる形式については operate/managing-runs.md を参照してください。

6. 結果を読む。 実行が完了しても、それだけで結論とはなりません。archon workflow get <run-id> --json で正規化された outcome と leave_behind.artifactFiles を確認できます。実行の結論をユーザーに伝える前に、レポートを読みます。

厳守事項

• 簡単な概要だけで開始しないでください。 入力が弱くても、結果が弱くなるわけではありません。代わりに、誤った問いに対する自信に満ちた整った回答が、正規の料金で生成されます。
• --detach を付けて開始し、回答してください。 デタッチ実行は独自のセッションを開始し、シェルを閉じても継続します。フォアグラウンドの respond または resume は、シェル内で実行を続けるため、シェルを閉じると停止します。
• 実行ごとではなく、監視は1つにしてください。 1つの workflow attention --watch ストリームで、トリガーや他のセッションが開始した実行も含め、対象範囲内のすべての実行をカバーできます。実行が1つか2つなら、実行ごとに workflow wait <run-id> を使っても問題ありませんが、数十件になるとデータベースの競合が発生します。
• 作業を止めるのは、終了させる意思があるときだけにしてください。 archon workflow cancel はノードの途中で実行を停止し、そのノードのプロバイダーセッションと未保存の作業は失われます。追加の実行開始だけを止めたい場合は、次の一時停止または終了まで実行を続けてください。ツールや、完了しないバックグラウンドコマンドでターンが停止している場合は、archon workflow end-turn <run-id> でそのターンを終了し、実行自体は継続します（operate/managing-runs.md、「停止したターン」）。
• レビューしたものだけをマージしてください。 プルリクエストを手動でマージする場合は、レビュー済みのヘッドにマージ対象を固定し（gh pr merge <n> --match-head-commit <sha>）、先に未解決のレビュースレッドを確認してから、チェックアウトを同期してください。
• エージェント優先で作成してください。 ワークフローを作成する場合は、型付き出力を持つエージェントノードで判断し、スクリプトは事実を読み取り境界で処理を行い、YAML はそれらを接続するだけにしてください。ルールと例については、authoring/authoring-workflows.md の「エージェント優先」を参照してください。

注意点

• 現在のディレクトリによって、プロジェクトの検出、実行開始、プロジェクト一覧の対象が決まります。workflow status、workflow runs、workflow attention は、そのプロジェクトをデフォルトで対象とします。インストール全体を対象にするには --all を追加してください。Git プロジェクトの場合は、リポジトリのルートから実行してください。Git 管理されていないフォルダーは workflow run --folder で登録します。完全な実行 ID は、どのディレクトリからでも使用できます。
• 要対応項目は一時停止中の実行です。停止したツール呼び出しで進行中の実行が止まっていても、要対応項目にはなりません。その場合は workflow wait <run-id> と workflow status で確認してください。
• 未登録のプロジェクトによってインストール全体を対象とした結果が返された場合、workflow status と workflow runs は JSON に scopeFallback: true を設定します。
• 出力を解析する場合は、--json を優先してください。
• archon --help の内容が正とします。このスキルで指定したフラグが拒否された場合は、CLI のヘルプに従い、ユーザーに差異を伝えてください。