description: Investigate and fix a GitHub issue end-to-end
nodes:
- id: investigate
command: investigate-issue
- id: implement
command: implement-issue
depends_on: [investigate]
context: fresh
default를 template으로 사용하기: Archon은 .archon/workflows/defaults/에 default workflows를 제공합니다(binary에 포함된 12개와 source build에서 disk에 있는 추가 workflow). 실제 예시를 살펴본 뒤 복사해서 수정하세요.
workflow는 working directory 기준 .archon/workflows/에 둡니다.
.archon/
├── workflows/
│ ├── my-workflow.yaml
│ └── review/
│ └── full-review.yaml # Subdirectories work
└── commands/
└── [commands used by workflows]
Archon은 workflow를 recursive하게 발견하므로 subdirectory를 사용할 수 있습니다. workflow file load에 실패하면(syntax error, validation failure) 해당 file은 skip되고 error가 /workflow list에 보고됩니다.
Global workflows: 모든 project에 적용되는 workflow는 ~/.archon/.archon/workflows/에 두세요. global workflow는 같은 이름의 repo workflow에 의해 덮어써집니다. 전역 워크플로를 참고하세요.
CLI vs Server: CLI는 실행한 위치에서 workflow file을 읽습니다(uncommitted changes도 보임). server는 ~/.archon/workspaces/owner/repo/의 workspace clone에서 읽으며, 이 clone은 worktree creation 전에 remote에서만 sync됩니다. workflow를 local에서 수정하고 push하지 않으면 server는 변경을 보지 못합니다.
workflow는 nodes:를 사용하는 DAG-based execution을 사용합니다. 각 node는 command 또는 inline prompt를 실행하고, dependency를 선언하며, conditional branching을 지원합니다.
name: classify-and-fix
description: Classify issue type, then run the appropriate fix path
nodes:
- id: classify
command: classify-issue
output_format:
type: object
properties:
type:
type: string
enum: [BUG, FEATURE]
required: [type]
- id: investigate
command: investigate-bug
depends_on: [classify]
when: "$classify.output.type == 'BUG'"
- id: plan
command: plan-feature
depends_on: [classify]
when: "$classify.output.type == 'FEATURE'"
- id: implement
command: implement-changes
depends_on: [investigate, plan]
trigger_rule: none_failed_min_one_success
depends_on이 없는 node는 즉시 실행됩니다. 같은 topological layer의 node는 Promise.allSettled를 통해 동시에 실행됩니다. skipped node(when: condition 또는 trigger_rule 실패)는 skipped state를 dependant로 전파합니다.
참고:steps:(sequential) format은 제거되었습니다. 모든 workflow는 nodes:(DAG) format만 사용합니다.
이 필드들은 Claude Agent SDK options에 직접 매핑됩니다. 모두 Claude 전용입니다. Codex node는 warning을 출력하고 무시합니다. per-node 또는 default로 workflow level에 설정할 수 있으며, per-node가 우선합니다. maxBudgetUsd와 systemPrompt는 per-node only입니다.
effort — reasoning depth:
- id: thorough-review
command: review
effort: high# 'low' | 'medium' | 'high' | 'max'
thinking — extended thinking mode(string shorthand 또는 object form):
AI node에서 JSON output을 강제하려면 output_format을 사용하세요. Claude에서는 schema가 SDK의 outputFormat option으로 전달되고 structured_output이 직접 사용됩니다. Codex(v0.116.0+)에서는 schema가 TurnOptions.outputSchema로 전달되고 agent의 inline JSON response가 사용됩니다. 두 방식 모두 when: condition과 $nodeId.output substitution에 사용할 수 있는 깔끔한 JSON을 보장합니다.
nodes:
- id: classify
command: classify-issue
output_format:
type: object
properties:
type:
type: string
enum: [BUG, FEATURE]
severity:
type: string
enum: [low, medium, high]
required: [type]
output은 JSON string으로 capture되며 $classify.output(전체 JSON) 또는 $classify.output.type(field access)으로 사용할 수 있습니다
downstream node가 when:을 통해 특정 값으로 branch해야 할 때 output_format을 사용하세요
.claude/agents/*.md file을 작성하지 않고 workflow YAML 안에서 Claude sub-agent를 직접 정의할 수 있습니다. main agent는 Task tool을 통해 이들을 parallel로 spawn할 수 있습니다. 저렴한 model(예: Haiku)이 item을 brief하고 더 강한 model이 reduce하는 map-reduce pattern에 유용합니다.
nodes:
- id: triage
prompt: |
Fetch open issues via `gh issue list ...`. For each issue, spawn the
brief-gen sub-agent in parallel (one message, multiple Task tool calls)
to produce a 2-3 sentence brief. Then cluster briefs for duplicates.
model: sonnet
allowed_tools: [Bash, Read, Write, Task]
agents:
brief-gen:
description: Summarises a single GitHub issue in 2-3 sentences
prompt: |
You are concise. Read the issue provided in the caller's prompt.
map은 SDK-level agents 및 skills:가 만드는 internal dag-node-skills wrapper와 merge됩니다. ID collision이 있으면 user-defined agent가 우선합니다(이 경우 warning log가 남음)
Claude 전용입니다. inline agent를 지원하지 않는 Codex와 community provider는 warning을 출력하고 field를 무시합니다
agents:와 .claude/agents/*.md file 중 무엇을 쓸지:
agents: (inline) — sub-agent가 특정 workflow 하나의 요구에만 맞을 때 사용합니다. workflow를 single YAML file 안에 self-contained로 유지하므로 PR과 fork에서 깔끔하게 이동합니다.
.claude/agents/*.md (on-disk) — sub-agent가 여러 workflow 또는 project 전체에서 공유될 때 사용합니다(예: 여러 maintenance workflow가 쓰는 triage-agent). on-disk agent는 workflow YAML 밖에 있으며 Claude Agent SDK가 자동으로 감지합니다.
두 source는 함께 사용할 수 있습니다. runtime에는 inline agent와 on-disk agent 모두 Task(subagent_type=...)에서 사용할 수 있습니다.
모든 node는 default configuration으로 transient error(SDK subprocess crash, rate limit, network timeout)를 자동 retry합니다. 기본값은 2 retries(총 3 attempts), exponential backoff가 적용된 3 s base delay입니다. 각 retry attempt 전에 platform notification을 받습니다.
customize하려면 retry: block을 추가하세요.
nodes:
- id: flaky-node
command: flaky-command
retry:
max_attempts: 3# 3 retries = 4 total attempts
delay_ms: 5000
on_error: transient
- id: aggressive-retry
prompt: "Summarise the output"
retry:
max_attempts: 4# 4 retries = 5 total attempts
on_error: all# Retry even non-transient errors (use with caution)
첫 retry 전 base delay(ms). attempt마다 두 배가 됩니다(exponential backoff)
on_error
'transient' | 'all'
'transient'
—
어떤 error가 retry를 trigger하는지 정합니다. 'transient' = SDK crash, rate limit, network timeout만. 'all' = unknown error를 포함한 모든 error(auth failure 같은 FATAL error는 어떤 경우에도 retry하지 않음)
SDK subprocess retry (claude.ts) — 3 total attempts, 2 s base backoff
↓ only if all SDK retries exhausted
Node retry (dag-executor) — default 2 retries, 3 s base backoff
↓ only if all node retries exhausted
Workflow fails → next invocation auto-resumes completed nodes
즉, single transient crash가 node retry attempt 하나를 소비하기 전에 최대 3 SDK retries를 trigger할 수 있습니다.
DAG resume: nodes:(DAG) workflow에서는 resume이 자동입니다. 다음 invocation이 이전 failed run을 감지하고 이미 completed된 node를 skip합니다. --resume flag는 필요 없습니다. 아래 DAG Resume on Failure를 참고하세요.
Crashed servers / orphaned runs: Archon은 server startup 시 running row를 자동으로 fail 처리하지 않습니다. 그렇게 하면 다른 process(CLI, adapter)에서 실제로 실행 중인 workflow를 죽일 수 있기 때문입니다. server crash로 row가 running에 stuck되면 dashboard에 계속 표시됩니다(Dashboard nav tab에 running workflow count가 표시됨). 명시적으로 terminal status로 전환하세요.
Web UI: workflow card에서 Abandon 또는 Cancel button을 클릭하세요. Abandon은 run을 cancelled로 mark하고 completed-node history를 보존합니다. Cancel은 in-flight subprocess도 종료합니다.
CLI: archon workflow abandon <run-id>를 실행하세요(dashboard의 Abandon button과 동일). Run ID는 archon workflow status에서 확인할 수 있습니다.
row가 terminal status에 도달하면 같은 path에서 같은 workflow를 다음에 invocation할 때 위 mechanism으로 completed node부터 auto-resume합니다.
archon workflow cleanup [days]와 혼동하지 마세요. 이 command는 disk hygiene을 위해 오래된 terminal run(completed/failed/cancelled)을 database에서 삭제합니다. running row를 전환하지는 않습니다.
Known limitation: 이전 node의 AI session context는 restore되지 않습니다. downstream node가 artifact가 아니라 prior run session의 in-context knowledge에 의존한다면 해당 artifact를 명시적으로 다시 읽어야 할 수 있습니다.
Fresh start: 이전 run에서 completed node가 하나도 없으면 Archon은 fresh start합니다(skip할 node 없음).
기본적으로 Web UI에서 시작한 workflow는 background에서 실행됩니다. execution은 internal worker conversation으로 dispatch되고, result는 chat window가 아니라 workflow run log에만 표시됩니다.
workflow를 foreground에서 실행하려면 interactive: true를 설정하세요(CLI, Slack, Telegram, GitHub와 동일). 모든 AI output과 approval gate message가 user의 chat window로 직접 stream됩니다.
name: my-interactive-workflow
interactive: true# Web UI: foreground execution (output visible in chat)
nodes:
- id: plan
prompt: "Create a plan for $USER_MESSAGE"
- id: review-gate
approval:
message: "Does this plan look good?"
depends_on: [plan]
- id: implement
command: implement
depends_on: [review-gate]
interactive: true를 사용할 때:
approval node가 있는 workflow — user가 AI output을 보고 inline으로 응답해야 합니다
interactive loop node(loop.interactive: true)가 있는 workflow — loop gate pause가 gate message와 run ID를 user에게 전달하려면 foreground execution이 필요합니다
user가 각 step에서 feedback을 제공해야 하는 multi-turn workflow
response가 user의 active chat thread에 표시되어야 하는 모든 workflow
Platforms:interactive는 web platform에만 영향을 줍니다. CLI, Slack, Telegram, GitHub는 이 설정과 관계없이 항상 foreground mode로 workflow를 실행합니다.
Web UI: dashboard card의 Approve/Reject button을 클릭하세요
API: POST /api/workflows/runs/<run-id>/approve 또는 /reject
natural language 또는 CLI로 approve하면 workflow는 다음 node부터 auto-resume합니다. user의 approval comment는 approval node에 capture_response: true가 설정된 경우에만 downstream node에서 $review-gate.output으로 사용할 수 있습니다.
on_reject가 없으면 reject 시 workflow가 cancel됩니다.
on_reject가 있으면 reject가 AI rework prompt를 trigger하고 re-review를 위해 다시 pause합니다.
자세한 내용은 Approval Nodes를 참고하세요.
Gate-then-fix — approve하면 진행하고, reject하면 특정 corrective action을 trigger
Approval signal
AI가 output에서 user intent를 감지합니다(<promise>DONE</promise>)
user가 button/command로 명시적으로 approve 또는 reject합니다
Example
PIV loop: explore → user feedback → explore again
Report generation: generate → user rejects → AI revises specific section
Interactive loop (loop.interactive: true):
- id: refine-plan
loop:
prompt: |
User's feedback: $LOOP_USER_INPUT
Read the plan, apply feedback, present changes.
until: PLAN_APPROVED
max_iterations: 10
interactive: true
gate_message: "Review the plan. Provide feedback or say 'approved'."
AI는 각 iteration을 실행한 뒤 user input을 위해 pause하고, user text는 $LOOP_USER_INPUT을 통해 다음 iteration에 전달됩니다. AI는 user response를 바탕으로 completion signal을 언제 emit할지 결정합니다.
Approval with on_reject (approval.on_reject):
- id: review
approval:
message: "Review the report. Approve or request changes."
capture_response: true
on_reject: { prompt: "Revise based on: $REJECTION_REASON", max_attempts: 5 }
depends_on: [generate]
workflow는 approval gate에서 pause합니다. user가 approve하면 workflow가 계속됩니다. user가 feedback과 함께 reject하면 on_reject prompt가 $REJECTION_REASON과 함께 실행되고, 같은 gate에서 다시 pause합니다.
경험칙: human과 AI가 conversation을 하는 경우(exploring, refining, iterating)는 interactive loop를 사용하세요. human이 objection하지 않는 한 workflow가 진행되어야 한다면 on_reject가 있는 approval gate를 사용하세요.
