goal-flight

goal-flight는 Claude Code 세션을 장기 실행되는 소프트웨어 프로젝트의 **오케스트레이터 (orchestrator)**로 변환합니다. 사용자는 목표를 제시합니다. 오케스트레이터는 주의를 기울일 가치가 있는 요구사항을 수집하고, 코드가 작성되기 전에 사용자와 함께 아키텍처 (architecture)를 결정한 다음, 로컬에서 실행되거나 SSH를 통해 원격 노드에서 실행되는 codex, grok, cursor, claude와 같은 다양한 코딩 에이전트 (coding agents)에게 작업을 할당합니다. 각 워커 (worker)는 자체적인 계획/실행/테스트/검토 (plan/act/test/review) 루프를 반복하며, 모든 커밋 (commit)은 독립적인 검토 과정을 거칩니다. 실행 상태는 압축, 재시작, 그리고 관리되지 않는 야간 시간 동안에도 유지되는 영구적인 프로젝트 파일 (계획, 대기열, 워커 상태, 검토 증거, 재개 노트)에 저장됩니다. 몇 시간 동안 지속된 실행 결과는 사용자의 브랜치에 검토를 마친, 청크(chunk)당 하나의 커밋 형태로 반영됩니다. 사용자의 허가 없이는 아무것도 푸시 (push)되지 않습니다.

호스트 (Hosts) 및 워커 (workers). Claude Code가 지원되는 오케스트레이터입니다. Codex는 표준 워커입니다. cursor, grok, claude-cli 및 기타 워커 어댑터 (worker adapters)도 역할을 수행합니다. Codex, Cursor 및 OpenCode를 위한 지원되지 않는 오케스트레이터 포트 (orchestrator ports)가 리포지토리 내에 포함되어 있습니다.

오케스트레이터 세션의 용도: 요구사항 수집, 아키텍처 결정, 질문 에스컬레이션 (question escalation), 그리고 모니터링을 위한 것이며, 실행을 위한 것이 아닙니다. 오케스트레이터는 프로젝트의 목표, 환경 (제약 조건, 아키텍처, 이전 결정, 실패 모드), 그리고 의도에 대해 충분한 컨텍스트 (context)를 보유하여 재량권을 행사하고 다음 단계를 권장하며, 그 후 반복적인 코드 검토 루프를 실행하는 워커들에게 작업을 할당합니다. 사용자의 작업은 코딩을 감독하는 것에서 설계를 조종하는 것으로 전환됩니다. 사용자는 체크인하여 승인하거나 방향을 재설정하고, 실행 과정에서 에스컬레이션된 질문에 답변합니다.

Quickstart • 제공 기능 • 아키텍처 • 명령

한 번 설치:

# Claude Code (지원되는 오케스트레이터):
git clone https://github.com/simonrowland/goal-flight.git ~/.claude/skills/goal-flight

(Codex / Cursor / OpenCode를 위한 오케스트레이터 포트가 존재하지만 지원되지 않습니다 — 설치 명령은 호스트 설치 노트에 있습니다.)

주요 플랫폼은 macOS입니다. Linux 호스트도 작동하지만 (docs/hosts/linux.md 참조), macOS 전용 OS-sandbox 백스톱(backstop)이 없으므로 워커(worker)들은 자체 샌드박스 및 승인 정책에 의존합니다. Windows의 완전한 지원을 위해서는 WSL이 필요합니다 — Windows 섹션을 참조하세요.

호스트를 재시작한 다음, 오케스트레이터 세션에서 프로젝트 리포지토리(repo)를 엽니다. 여기서부터의 흐름은 네 단계로 진행됩니다:

1. 프로젝트를 초기화하고 워커(workers)를 확인합니다.

/goal-flight init <topic>

리포지토리를 감사(audit)하고, 실행의 지속 가능한 상태(durable state)를 스캐폴딩(scaffold)하며 (docs-private/, 목표 진술서(goal statement), 오퍼레이터 로컬 AGENTS.md), 어떤 워커 CLI가 설치되어 있고 정상 작동하는지 조사합니다. 또한 codex 신뢰를 등록하고, 머신 용량을 측정하며, 워커들이 필요로 할 환경적 주의 사항을 기록하고, 선택적으로 RAG 코퍼스(corpus)를 구축하여 워커들이 동일한 프로젝트 환경을 반복해서 읽지 않도록 합니다. 초기화(init)를 마치면 어떤 에이전트(agent)를 사용할 수 있고 상태가 정상인지 알 수 있습니다. (/goal-flight doctor 명령으로 언제든 이 모든 것을 재점검할 수 있습니다.)

2. 요구 사항 문서(requirements document)를 작성합니다.

/goal-flight ask-questions

예측적 서브 에이전트(anticipatory subagents)가 리포지토리와 목표 진술서를 읽은 다음, 코드가 답할 수 없는 제품 선택 및 트레이드오프(trade-offs)에 대해 사용자에게 인터뷰를 진행합니다 — 코드가 답할 수 있는 사소한 정보(trivia)가 아닙니다. 사용자의 답변은 프로젝트의 요구 사항 문서로 성장하는 목표 파일(goal file)에 기록됩니다. 이 파일은 북극성(north star) (프로젝트가 반드시 수행해야 하는 것에 대한 지속 가능한 진술), 검증된 전제 조건, 그리고 미결 질문들로 구성됩니다. 이후의 모든 아키텍처 결정과 검토는 이 파일에 따라 테스트되며, 압축(compaction) 과정에서도 유지됩니다.

3. 아키텍처 문서(architecture document)를 작성합니다.

/goal-flight decompose-plan [<plan>]

작성된 계획, 아키텍처 문서(architecture doc), 또는 지금까지의 대화 내용 등 당신이 가진 어떤 신호(signal)든 가져와서 실행 가능한 아키텍처로 변환하세요. 여기에는 병렬성(parallelism)이 표시된 폐쇄형 청크(closed chunks: SCOPE / CHECKLIST / ACCEPTANCE / FORBIDDEN)와 분해(decomposition) 자체에 대한 리뷰어 검토(reviewer pass)가 포함되며, 이를 통해 코드가 작성되기 전에 설계에 대한 적대적 검토(adversarial scrutiny)를 받게 됩니다. 특정 청크에 동의하지 않나요? 채팅에서 그렇게 말씀하세요. 세션 중간의 조종(steering)은 요구사항 입력(requirements input)이 되며, 계획은 수정됩니다. (gstack이 설치되어 있다면, /office-hours 및 /plan-eng-review를 통해 이 단계에서 구조화된 심문(structured interrogation)을 추가할 수 있습니다.)

4. 작업을 배정(Dispatch)합니다.

/goal-flight execute [--parallel <N>]

오케스트레이터(orchestrator)는 각 청크를 가장 적합한 워커(worker)에게 배정하고, 터미널을 계속 지켜보는 대신 상태 파일(status files)을 모니터링하며, 속도 제한(rate-limited)이 걸린 제공자를 우회하고, 모든 청크가 완료되어 도달하기 전에 실행자의 자체 검토(executor self-review)와 독립적인 리뷰어(independent reviewer)의 검토를 거치도록 게이트(gate)를 설정합니다. 실행은 중단되어 허가 게이트(permission gates), 파괴적인 선택(destructive choices), 인증(auth) 또는 용량 제한(capacity hard stops), 검토 또는 테스트 실패 게이트, 그리고 계획이 추론할 수 없는 제품 선택 사항에 대해 권한을 요청합니다. 즉, 당신의 허가 없이 작업을 밀어붙이지 않습니다. 몇 시간 뒤에 돌아오면, 리뷰 증거와 재개 노트(resume notes)가 디스크에 저장된 상태로, 당신의 브랜치에 청크당 하나의 커밋(one-commit-per-chunk)으로 검토된 작업이 완료되어 있을 것입니다.

세션 관리(Session management). 압축(Compaction)은 컨트롤러(controller)가 계속 업데이트하는 핸드오프 파일(handoff file)에 의해 관리됩니다. 여기에는 레포지토리 상태(repo state), 진행 중인 배정(in-flight dispatches), 다음 의도된 작업(next intended action)이 포함됩니다. 세션이 압축되기 전에 컨트롤러에게 핸드오프를 업데이트하도록 요청하고, /compact를 실행한 다음, /goal-flight resume를 실행하세요. 동일한 재개(resume) 명령은 재시작 후나 며칠이 지난 후에도 프로젝트를 다시 불러옵니다. 채팅 메모리(chat memory)에 의존하는 것은 아무것도 없습니다.

경직된 게이트가 아닌 작동하는 신호: 이 기술은 압축 생존(compaction-survival)을 위해 초기화 시 goal-<topic>-<date>.md 파일을 고정(pins)하지만, 이는 닻(anchor)일 뿐 계약(contract)은 아닙. decompose-plan

존재하는 어떤 신호(목표 진술(goal-statement)이 있는 경우 그것, 또는 계획 소스(plan source), 아키텍처 문서(architecture doc), 세션 내 대화)를 바탕으로 진행하며, 추론된 모든 가정들을 사용자가 실행 중에 검증할 수 있도록 인라인 오피스 아워(inline-office-hours) 백로그 항목으로 노출합니다. "여기 제 아키텍처 문서와 10분 분량의 컨텍스트 설정 대화 내용입니다"라고 제시하면 decompose-plan이 거기서부터 진행합니다. 전제 조건(premises) 파일은 실행이 진행됨에 따라 검증된 답변들을 축적합니다. 초안(DRAFT) 상태의 목표 진술(goal-statement)이라도 괜찮습니다. decompose-plan은 어쨌든 진행하며, docs-private/goal-<topic>-<date>.md를 직접 편집하여 언제든 내용을 다듬을 수 있습니다.

/goal-flight

인자를 전달하지 않고 실행하면 전체 패턴 참조인 SKILL.md를 출력합니다.

보게 될 용어들: *청크(chunk)*는 하나의 완결된 작업 단위(범위, 체크리스트, 수락 기준(acceptance criteria), 금지된 경로)를 의미합니다. *목표 모드(goal-mode)*는 해당 청크가 수렴할 때까지 계획/실행/테스트/검토(plan/act/test/review)를 반복하는 워커 루프(worker loop)입니다. *ACP (Agent Client Protocol)*는 오케스트레이터(orchestrator)에게 구조화된 워커 이벤트를 제공하며, bash-tail(감시 중인 로그 파일)이 폴백(fallback) 역할을 합니다. *RAG 코퍼스(RAG corpus)*는 워커들이 코드베이스를 새로 탐색하는 대신 읽을 수 있도록 큐레이션된 프로젝트 노트의 선택적 집합입니다. *워크백(walkback)*은 제한된 제공자(provider)로부터 작업을 우회시키는 속도 압박(rate-pressure) 대응 방식입니다.

로컬 또는 원격의 다양한 에이전트들. 워커에는 ACP 또는 bash-tail을 통해 codex, grok, cursor, claude-cli가 포함됩니다. 플릿 레이어(fleet layer)는 원격 SSH 노드에서 동일한 디스패치(dispatch)를 실행합니다. 오케스트레이터는 청크별로 실행기(executor)와 반복 패턴(원샷(one-shot), 수렴까지의 목표 모드 루프, 또는 사소한 편집을 위한 컨트롤러 직접 제어(controller-direct))을 선택하며, 사용량과 속도 제한(rate limits)을 여러 벤더(vendor)에 분산시켜, 실행을 중단하는 대신 압박을 받는 제공자를 우회하여 라우팅합니다.

커밋 전 독립적 검토. 모든 /goal 청크는 워커 루프 내부에서 수렴할 때까지 7가지 카테고리의 적대적 자가 검토(adversarial self-review)를 수행합니다. 커밋할 가치가 있는 청크는 이후 독립적인 검토자 통과(gstack의 /review를 통해) 과정을 거칩니다.

설치 시(when installed), 그리고 설정된 주기(cadence)에 따라 다양한 관점(concern-diverse lenses)을 가진 마일스톤 리뷰(milestone reviews)가 수행됩니다. 포착된 각각의 새로운 버그 형태는 내구성이 있는 버그 클래스 술어(bug-class predicate)로 발행됩니다. 이미 검토된 코드와 저장된 리뷰 아카이브를 스캔하여 추가 사례를 찾아내며, 해당 술어는 이후의 모든 리뷰를 위한 기존 렌즈(standing lenses)에 합류합니다 (protocols/review-mining.md 참조).

큐레이션된 프로젝트 코퍼스 (RAG). 초기화 시 선택적으로 — 또는 나중에 build-corpus를 통해 — goal-flight는 저장소(repo)와 문서(docs)를 추출하여 docs-private/rag/ 아래의 큐레이션된 코퍼스 슬라이스(corpus slices)로 정제합니다. 브리프(briefs)는 프로젝트 컨텍스트를 모든 워커 프롬프트(worker prompt)에 다시 붙여넣는 대신 해당 파일들을 참조(anchor)합니다. 따라서 읽기 비용(read cost)은 워커에게 부과되며, 코퍼스는 단 한 번만 작성됩니다.

검증 우선 디스패치 (Verification-first dispatch). 래퍼(Wrappers)는 에이전트가 조사할 파일들을 가리키며, 몇 분 단위의 시간 척도에서 금방 낡아버리는(stale) 미리 붙여넣은 "사실(facts)"을 제공하지 않습니다. 프런티어 모델(Frontier models)은 오케스트레이터 텍스트(orchestrator-text)를 비판 없이 신뢰하는 경향이 있으나, 포인터(pointers)를 사용하면 모델이 실제 디스크와 대조하여 재검증하도록 강제하고 드리프트(drift)를 드러내게 합니다.

가벼운 감독을 동반한 수 시간 단위의 무인 실행. 주기적으로 확인하거나 결정 알림(decision notifications)에 응답하십시오. 오케스트레이터의 컨텍스트(context)에는 주로 아키텍처, 계획, 메타데이터(큐 상태, 최근 커밋, 진행 중인 디스패치 헤더)가 포함됩니다. 실제 작업은 서브 에이전트(subagent)의 컨텍스트 윈도우(context windows)에서 수행되며, 오케스트레이터는 결정이 진정으로 사용자의 판단을 필요로 할 때만 에스컬레이션(escalate)합니다.

결정론적 운영 스크립트 (Deterministic ops scripts). 용량 임대(Capacity leases), 디스패치 원장(dispatch ledgers), 컴팩트 상태(compact status), 구조화된 ACP 모니터링, 속도 압박 탐지(rate-pressure detection), 파일 기반 리뷰 작업은 scripts/goalflight_*.py에 존재합니다. 모델은 숫자가 무엇을 의미하는지에 판단력을 집중합니다. Doctor는 런타임 준비 상태와 워커-CLI(worker-CLI)의 최신성(currency)을 점검하므로, 사용자는 언제 /goal-flight update를 실행해야 하는지 알 수 있습니다.

• vs.
  단일 코딩 세션을 컨텍스트 고갈(context exhaustion)까지 실행하는 방식— 오케스트레이터(orchestrator)는 직접 코드를 작성하지 않습니다. 오케스트레이터는 요구 사항과 아키텍처를 유지하면서, 워커(worker)들이 각자의 컨텍스트 윈도우(context window)를 소모하는 동안 작업을 할당하고 검증합니다. 즉, 실행(run)은 단일 세션보다 더 오래 지속됩니다. - vs.
  내장된 장기 지평 메모리(long-horizon memory)를 갖춘 에이전트 프레임워크— 지속 가능한 세션 간 메모리(파일 기반 프로젝트 상태, RAG 코퍼스, 재개 루틴 등)는 별도로 채택해야 하는 독립된 런타임이 아니라, 사용 중인 기존 Claude Code 세션 내부로 제공됩니다. - vs.
  클라우드 에이전트 스웜(swarms) 또는 에디터 에이전트— 워커들은 사용자의 CLI 및 프로바이더 구독을 사용하여 사용자의 머신(또는 사용자의 SSH 노드)에서 실행됩니다. 오케스트레이터는 사용자의 호스트 세션에서 이들을 조정합니다. - vs.
  프롬프트를 수동으로 작성하는 방식— 코드가 아닌 계획을 만드세요. 이 기술은 프론티어 모델(frontier model)이 사용자의 계획을 청크(chunks)로 분해하고, 무엇을 병렬로 실행할 수 있는지와 무엇을 /goal 패턴으로 처리할 수 있는지 플래그를 지정하도록 요청합니다. 모든 /goal은 기본적으로 수렴(convergence)할 때까지 리뷰를 수행합니다. 7개 카테고리의 적대적 자기 리뷰(adversarial self-review)가 리뷰를 통과할 때까지 루프 내부에서 실행되므로, 오케스트레이터는 수렴되지 않은 결과를 결코 보지 못합니다.

명령 (Command)	기능 (What it does)
/goal-flight init <topic>	도구 점검 (Tool check), 저장소 감사 (repo audit), 스캐폴딩 (scaffold), codex-trust 등록
/goal-flight decompose-plan [<plan>]	병렬 리뷰어 패스 (parallel reviewer pass)와 함께 계획을 /goal 청크로 분해
/goal-flight ask-questions [<scope>]	선제적 서브에이전트 (Anticipatory subagents); 명확화 질문 (clarifying questions) 표출
/goal-flight execute [--parallel <N>]	청크별 루프; 기본값은 순차적 (sequential), 병렬 안전 옵션 (parallel-safe opt-in) 선택 가능
/goal-flight doctor	플러그인/패키지/런타임 준비 상태, 모델 최신성 (model currency), 속도 제한 압박 (rate-pressure)에 대한 읽기 전용 상태 점검 (health check)
/goal-flight update	origin에서 최신 goal-flight를 가져오고(pull) 각 워커 CLI의 자체 업데이트(self-update) 실행
/goal-flight build-corpus [<flags>]	선택적 RAG 코퍼스 (corpus) 확장 또는 재구축
/goal-flight resume	현재 git 상태로부터 RESUME-NOTES 재구축
/goal-flight goal <SLUG>	대기열(queue)에 하나의 목표(goal) 추가
/goal-flight register-codex [<path>]	프로젝트를 codex-trusted로 등록
/goal-flight validate-dispatch [<slug>]	실제 실행(dispatch) 없이 청크의 디스패치 래퍼(dispatch wrapper) 렌더링
/goal-flight validate-queue [<path>]	goal-queue의 스키마 점검 (Schema-check)

또한 /fork를 통한 선택적 자기 위임 (self-delegation) 패턴이 있습니다.

— 오케스트레이터(orchestrator)가 마커 계약(marker contract)을 작성하면;
포크된 세션(forked session)이 환경 변수(env var)를 통해 이를 감지하고 계약을 따릅니다; 오케스트레이터는 압축된 상태(compact status)를 모니터링합니다. protocols/self-delegation.md를 참조하세요.

; 포크(fork) 명령은 항상 로드되는 것이 아닙니다.

상세 운영 절차는 protocols/ 아래의 온디맨드 로드(load-on-demand) 파일로 분리되어 있습니다.
항상 로드되는 SKILL.md는 의도적으로 작게 유지됩니다.

워커 선택(worker selection)을 튜닝하는 경우가 아니라면 일반적으로 이 섹션은 필요하지 않습니다.

반복 패턴 (Iteration pattern) — 청크에 필요한 턴(turn) 수:

패턴 (Pattern)	시점 (When)	비용 (Cost)
controller-direct	사소한 수준 (단일 파일, ~30 LoC 미만), 또는 오케스트레이터 (orchestrator)가 새로운 하위 에이전트 (subagent)가 다시 발견해야 할 세션 로드된 컨텍스트 (session-loaded context)를 이미 보유한 경우	인라인 (Inline); 하위 에이전트 없음
one-shot subagent	대부분의 청크 (chunk)에 대한 기본값. 프론티어 모델 (Frontier model)이 청크 형태에 따라 실행 대상 (executor target)을 선택	청크당 하위 에이전트 1회 파견
goal-mode loop	다단계 리팩터링 (refactor), 코드 마이그레이션 (migration), 프로토타입 구현 (prototype implementation), 코드를 그라운드 트루스 (ground-truth)로 수렴시키기 — 계획/실행/테스트/검토를 통한 수렴 (plan/act/test/review-to-convergence)의 이점을 얻는 모든 작업	수 시간 동안의 자율 세션 (codex /goal 네이티브 지원, 또는 오케스트레이터 주도 반복 루프 (orchestrator-driven iteration loop))

통신 형태 (Comms shape) (직교 축) — 오케스트레이터가 작업자 (worker)를 관찰하는 방식. Goal-flight는 작업자가 어댑터 (adapter)를 가진 모든 곳에서 에이전트 클라이언트 프로토콜 (Agent Client Protocol)을 사용합니다 (codex / cursor / claude / grok은 현재 모두 지원함); tail -f를 사용한 bash-tail