# Quickstart

> 클론 → Orca 준비 → wake-up 온보딩 → Generation 1 부트 → 첫 supervised worker까지 최단 성공 경로와 검증 신호.

- Repository: local/mogui-ADE-orchestrator

- Human docs: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac
- Complete Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/llms-full.txt

## Source Files

- `docs/public/getting-started.md`
- `README.md`
- `master-ops/ONBOARDING.md`
- `master-ops/onboarding/09-spawn.md`
- `scripts/master-succeed`
- `scripts/dispatch-gate`
- `scripts/adapter`

---

---
title: "Quickstart"
description: "클론 → Orca 준비 → wake-up 온보딩 → Generation 1 부트 → 첫 supervised worker까지 최단 성공 경로와 검증 신호."
---

첫 실행 경로는 `docs/public/getting-started.md`의 인간 경로와 `master-ops/ONBOARDING.md` 라우터(단계 파일 1회 1로드)가 합쳐진 설치 인터뷰다. Orca 런타임이 준비된 뒤 이 저장소 클론 안에서 에이전트를 깨우면 Founding 모드가 ops 저장소를 만들고, `scripts/master-succeed spawn`으로 Generation 1 마스터를 좌석 검증 후 띄우며, 첫 작업은 `scripts/dispatch-gate check` → Orca orchestration dispatch → `register` → `worker_done` 수락 순으로 끝난다.

<Warning>
Orca 없이 마스터를 돌리면 완료 감지가 화면 폴링으로 떨어지고 감독이 사라진다. Step 0 preflight는 준비된 런타임 없이 founding을 진행하지 않는다.
</Warning>

## 성공 경로 한눈에

| 단계 | 행위자 | 핵심 명령 / 표면 | 통과 신호 |
| --- | --- | --- | --- |
| 1. Orca 설치·CLI 등록 | 사람 | `brew install --cask stablyai/orca/orca` 또는 [download](https://www.onorca.dev/download); Settings → Orca CLI → Shell command | `orca status` → `appRunning: true`, `runtimeState: ready` (또는 `--json` `"ok": true`) |
| 2. 클론·프로젝트 등록 | 사람 | `git clone` …; `orca repo add --path <path>` | Orca 프로젝트 안 터미널에서 `pwd`가 클론/워크스페이스 경로 |
| 3. Wake-up 온보딩 | 설치 에이전트 | 에이전트 CLI 기동 후 구체 작업 없는 짧은 문구 | `master-ops/ONBOARDING.md` 라우터 로드, 세션 모드 질문 |
| 4. Preflight (Step 0) | 설치 에이전트 | `ORCA_AGENT_CLI=<cli> bash scripts/onboarding-preflight.sh` | exit 0, 요약 `READY` 또는 `READY WITH WAIVERS` |
| 5. Founding → Gen-1 | 설치 에이전트 + 신생 마스터 | `master-succeed spawn` + orchestration Run/Task/Dispatch | placement `MATCH` 또는 `MATCH_REISSUED`; seat에 마스터 1개; boot smoke `worker_done` |
| 6. 첫 supervised worker | 마스터 | `dispatch-gate check` → dispatch → `register` → mailbox wait | 게이트 `allow: true`; 마스터가 증거를 재검증 후 수락 |

```text
[사람] Orca ready + clone in project terminal
    │
    ▼
[설치 에이전트] wake-up → ONBOARDING router → Founding
    │  00…08 prepare ops seat rules
    ▼
[Gen-1 마스터] spawn (empty-seat + placement) → boot smoke → installer retire
    │
    ▼
[사람] 작은 계약 승인 → [마스터] gate/dispatch/register → [워커] worker_done
    │
    ▼
[마스터] 독립 증거 수락  (self-report ≠ proof)
```

## 전제조건 (측정)

분류는 `scripts/onboarding-preflight.sh` 기준이다. `FAIL`은 exit 1 `BLOCKED`에 합산되어 founding을 막는다. `WARN`만으로는 exit 1이 되지 않지만, essential로 표시된 항목은 요약에서 반복된다. 만족할 수 없는 필수 검사만 `PREFLIGHT_WAIVE=<check-label>`로 명시 면제한다(미일치 라벨은 그대로 강제).

| 필요 | 확인 | 부재 시 |
| --- | --- | --- |
| Orca 앱 + 준비된 런타임 | `orca status` / `orca status --json` | `orca` FAIL |
| `orca` on `PATH` | `command -v orca` (지원 basename: `orca`, `orca-dev`, `orca-ide`) | 동일 FAIL |
| 마스터 에이전트 CLI | `command -v claude` 등; 온보딩이 `ORCA_AGENT_CLI` 설정 | `agent-cli` FAIL |
| 워커 런타임 ≥1 | `command -v codex` 및/또는 `cursor-agent` | 둘 다 없으면 `worker-runtime` FAIL |
| `git`, `gh`, `python3`, `bd` | 각 `--version` / `command -v` | 각 FAIL (`gh` 미인증은 WARN) |
| skills `orca-cli`, `orchestration` | 에이전트 skills root 또는 전역 목록 | `skills` FAIL |
| 조직 redaction 규칙 파일 | 기본 `~/.config/redaction-extra.txt` 또는 `REDACTION_EXTRA_PATTERNS` (id\|desc\|regex ≥1) | `redaction-extra` FAIL |

WARN 예: `gitleaks`, `ctx`, skill-stack(`superpowers`/`ponytail`), `gh-auth` / `workflow` scope.

클론 루트에서 세션 상태 포함 전체 측정:

```console
$ bash scripts/onboarding-preflight.sh
```

`--fix`는 승인 후에만: 전역 Orca skills 보강 가능, 앱 설치는 수동.

## 최단 절차

<Steps>
<Step title="Orca 설치 및 셸 명령 등록">
macOS(검증된 경로):

```console
$ brew install --cask stablyai/orca/orca
```

Linux/Windows: [Orca download](https://www.onorca.dev/download). Linux에서는 GNOME 스크린 리더와 충돌을 피하려고 바이너리명이 `orca-ide`일 수 있다.

Orca 앱을 연 뒤 **Settings → Orca CLI → Shell command**를 켠다. 성공 조건:

```console
$ command -v orca
$ orca status
```

앱이 꺼져 있으면 `orca open`이 런타임이 닿을 때까지 기다린다.
</Step>

<Step title="저장소 클론 및 폴더 등록">
두 계층을 혼동하지 않는다.

1. **폴더 워크스페이스 루트** — 여러 저장소를 묶는 디렉터리(자체 git이 아닐 수 있음). 마스터 좌석.
2. **이 오케스트레이터 클론** — 설치기·런타임 소스. 마스터는 여기에 영구 거주하지 않는다.

```console
$ git clone https://github.com/baksohyeon/mogui-ADE-orchestrator
$ cd mogui-ADE-orchestrator
$ orca repo add --path <path-to-folder>
```

Orca에서 **해당 프로젝트 안** 터미널을 연다. `pwd`가 설치 세션 체크아웃이어야 한다. 프로젝트 밖 임의 cwd는 이후 placement/spawn이 잘못된 좌석을 측정한다.

워크스페이스 루트는 나중에 **절대 경로**로 붙여넣는다. 상대 경로와 bare `~`는 불충분하다.
</Step>

<Step title="에이전트 기동 및 wake-up">
프로젝트 터미널에서 마스터로 쓸 에이전트 CLI를 켠다(`claude`가 하드 런 검증된 조합; 다른 CLI는 워커로 검증됨, Codex 마스터는 미테스트).

구체 작업 없이 짧게 깨운다. 문구 예:

```text
Wake the master.
```

라우터 키는 의식 문구가 아니라 **구체 태스크 부재**다. 에이전트는 `master-ops/ONBOARDING.md`만 먼저 읽고 세션 모드를 묻는다.

| 모드 | 의미 | 스폰 |
| --- | --- | --- |
| **Founding** | 새 워크스페이스: ops 저장소 구축 + Gen-1 | 허용 (`00`→`10`) |
| **Reverify** | 이미 ops+마스터 있음: 건강 점검만 | 차단 |
| **Upgrade** | 템플릿 드리프트 적용 | 차단 |
| **Template improve** | 이 오케스트레이터 자체 수정 | 온보딩 중단 |

기존 ops 저장소·lineage 파일이 있으면 Founding이 아니다. 반쯤 끝난 설치에 Founding을 다시 돌리면 lineage/거버넌스가 깨진다. 죽은 마스터·반쯤 끝난 Gen-1은 ops의 `docs/runbooks/succession-boot-card.md` 경로다.
</Step>

<Step title="Founding 인터뷰 (사람 결정)">
설치 에이전트(Herald)는 한 번에 한 단계 파일을 읽고, 해당 Verify가 통과하기 전에는 다음 파일을 열지 않는다. Founding에서 사람이 답해야 하는 결정:

| 결정 | 이유 |
| --- | --- |
| 워크스페이스 루트(절대 경로 붙여넣기) | 이후 측정·마스터 좌석 기준. 홈 스캔/후보 목록 없음 |
| 목적·소속 저장소 인벤토리 | 마스터가 조정할 허용 표면 |
| ops 저장소 이름·위치 | 거버넌스용 **별도** git (제품 코드 아님) |
| 마스터 callsign | 문서의 “master”는 임시 역할 라벨; 살아 있는 세션 호칭 |
| 이슈 트래커·선택 스킬 스택 | 실행 상태; 선택 스킬 거부는 정상 |
| Gen-1 스폰 확인 | 기록된 좌석에 터미널 1개 생성·킥오프·boot smoke. smoke 중 해당 패인에 타이핑하지 말 것 |

설치 인터뷰 세션 ≠ 마스터. Founding 스폰 후 설치기는 은퇴하고, 마스터는 워크스페이스 좌석의 **새** 세션이다.
</Step>

<Step title="Preflight 및 인스턴스 설정 (Step 0)">
에이전트가 `{{RUNTIME_ROOT}}`에서 실행한다(서술은 `$` 프롬프트):

```console
$ cd "{{RUNTIME_ROOT}}"
$ ORCA_AGENT_CLI="<user-named agent CLI>" bash scripts/onboarding-preflight.sh
```

통과 후 인스턴스 전용(커밋하지 않음) 파일:

```console
$ test -f config/instance-runtime.json || cp config/instance-runtime.example.json config/instance-runtime.json
# master_host_runtime = 확인된 에이전트 CLI
$ test -f config/model-tier-policy.json || cp config/model-tier-policy.example.json config/model-tier-policy.json
# version: 2, agents/tiers/fanout_caps/window_seconds, consent
```

- `instance-runtime.json`: `master_host_runtime`, `transcript_globs`, optional `product_repo`. 해석: env 오버라이드 → 파일 → unconfigured(추측 금지).
- `model-tier-policy.json`: 게이트 소비 필드 `version`/`tiers`/`fanout_caps`/`window_seconds`. 해석: `DISPATCH_TIER_POLICY` → `config/model-tier-policy.json` → 템플릿 `master-ops/model-tier-policy.json`.

오케스트레이션이 unbound/`run_required`이거나 legacy coordinator가 write를 떨어뜨리면 `orca orchestration run-create`로 새 Run을 묶고 재측정한다. 앱 재시작만으로는 legacy가 안 지워질 수 있다.
</Step>

<Step title="Generation 1 스폰과 boot smoke">
Step 8 전에 좌석 empty-gate: `ORCA terminal list --worktree <selector> --json`이 **해당 좌석 터미널 0개**. 잔여 seat-check/이전 스폰이 있으면 하드 스톱(두 번째 마스터 금지).

에이전트 전용 감독 경로(소유자에게 붙여넣지 않음; `ORCA`는 해석된 실행 파일):

```bash
G={{RUNTIME_ROOT}}/scripts/dispatch-gate
L=~/.mogui/dispatch-ledger.jsonl
"$G" --ledger "$L" check \
    --runtime <runtime> \
    --model "{{MODEL_ID}}" \
    --contract <contract file> \
    --agents 1 \
    --est-chars <estimated input chars> \
    --completion-channel orchestration
ORCA orchestration run-create --objective "Found and verify the Generation 1 master" --json
ORCA orchestration task-create --spec "Run the byte-identical founding kickoff file and complete Step 9 boot smoke" --json
"{{RUNTIME_ROOT}}/scripts/master-succeed" spawn \
    --workspace-selector <durable placement selector, id: prefixed> \
    --kickoff-file <kickoff file> \
    --root "{{WORKSPACE_ROOT}}" \
    --model "{{MODEL_ID}}" \
    --title "Gen-1 founding boot" \
    --json
ORCA terminal wait --terminal <verified live handle> --for tui-idle --timeout-ms 60000 --json
ORCA orchestration dispatch --task <task id> --to <verified live handle> --inject --json
"$G" --ledger "$L" register \
    --job-id <job id> \
    --probe-cmd "<command proving the job-id appears in an artifact>" \
    --orchestration-task <task id>
ORCA orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
```

`master-succeed spawn` 주요 플래그:

| 플래그 | 역할 |
| --- | --- |
| `--workspace-selector` | 내구 좌석 선택자 (`id:…` 등) |
| `--kickoff-file` / `--kickoff-text` | 부트 킥오프 (파일 바이트 동일 전달 검증) |
| `--root` | 워크스페이스 루트 |
| `--model` / `--agent` | 모델·런타임 CLI (`claude`/`grok`/`codex`/커스텀) |
| `--title` | 터미널 제목 |
| `--expected-placement` | 독립 기대 worktree; 불일치 시 fail-closed **exit 26** `SPAWN_PLACEMENT_MISMATCH` |
| `--dry-run` / `--json` | 시뮬레이션·JSON 출력 |

게이트 `check`가 `allow: true`여야 스폰/부착. placement 결과는 `MATCH` 또는 유효 `MATCH_REISSUED`(`handle_reissued: true` + 채택 핸들). Codex 워커 전 `scripts/codex-worker-pretrust <worktree-path>`.

Step 9(신생 마스터 안): Role State·callsign 선언, 설정/실측 모델 분리 보고, placement 증거, `docs/lineage/MASTER-LINEAGE.md` Gen-1 append, founding Task에 `worker_done` 1회.
</Step>

<Step title="운영 카드와 설치기 은퇴">
boot smoke 통과 후 Step 10이 운영 카드를 출력하고(Role State / Propose / Approved execute / Dispatch / succession 문구), 신생 마스터가 설치기 핸들·pty/session 신원 재확인 후 `ORCA terminal close --terminal <installer handle> --json`으로 설치기를 닫는다. 신원 모호·불일치 시 아무 터미널도 닫지 않고 보고한다. 마스터 터미널은 유지한다.
</Step>

<Step title="첫 supervised worker">
설치만으로는 긴 채팅과 같다. 시스템이 보이는 지점은 좁은 계약 → 승인 → 워커 → 증거 수락이다.

계약 예시 형태:

```text
In the repository <repo-name>, open README.md and list the top-level section headings.
Do not edit any file. Return the heading list as the artifact.
```

관찰 순서:

1. **Proposal** — 대상 저장소/체크아웃, 허용 표면, 수락 기준, 증거, 커밋 규칙.
2. **Approval** — 비사소 작업은 제안 → 승인 → 실행.
3. **Dispatch** — 보통 저장소 worktree 브랜치 워커; 완료는 orchestration 메일박스(`worker_done` 등), 화면 스크레이프 아님.
4. **Acceptance** — 워커 “done”은 주장; 마스터가 아티팩트·diff·게이트를 재검증.

정상 디스패치 상태 객체 순서(README 측정 경로):

1. 계약 파일 해시가 게이트 결정·태스크와 함께 기록  
2. `scripts/dispatch-gate check` → 티어×fan-out 정책, JSONL ledger (`--ledger`, dry-run은 `--no-record`)  
3. `orca orchestration task-create`  
4. worktree + terminal 격리  
5. `orca orchestration dispatch --task … --to … --inject`  
6. `scripts/dispatch-gate register` (모델 probe: 선언 대비 실측; 더 비싼 모델이면 deny)  
7. `orca orchestration check --wait` (mailbox)  
8. 마스터 독립 수락  

`dispatch-gate` 하위 명령: `check`, `register`, `watch`, `report`. `check`의 `--completion-channel`은 `orchestration` 또는 `sentinel-log`(라이브 마스터 경로는 orchestration).
</Step>
</Steps>

## 검증 신호 체크리스트

Founding이 “done” 한 줄에 의존하지 않는다.

| # | 검사 | 기대 |
| --- | --- | --- |
| 1 | Orca UI / `orca terminal list` | Gen-1 세션이 **워크스페이스 루트 폴더 워크스페이스**(또는 단일 저장소면 primary worktree)에 있음. 멀티 레포에서 제품 레포 worktree에만 걸리면 misplacement |
| 2 | 마스터 트랜스크립트 boot smoke | Role State(+ callsign); configured vs measured 모델 분리; placement 증거가 의도 좌석과 일치 |
| 3 | 좌석 유일성 | 해당 워크스페이스 마스터 정확히 1. `master-succeed check-duplicates` |
| 4 | 폴더 좌석 라벨 | worktree 경로 비어 있음 / “Unavailable worktree” 칩 → **정상**(git worktree가 아님) |
| 5 | 설치기 | 카드 출력 후 설치 터미널 종료; 마스터 터미널 생존 |
| 6 | 첫 워커 | 게이트 allow → mailbox `worker_done` → 마스터 수락(self-report만으로 종료 금지) |

```console
$ orca terminal list
$ scripts/master-succeed check-duplicates --help   # 실제 호출은 ops 마커/셀프 핸들로
```

## 빠른 순수 함수 스모크 (선택)

Orca 없이 코어 진입점만 확인(마스터 세션은 생기지 않음):

```console
$ scripts/master-succeed detect "routine status update" --context-ratio 0.7 --json
$ scripts/dispatch-gate --ledger /tmp/gate.jsonl check \
  --runtime codex --model grok-4.5 --contract README.md --agents 1 --est-chars 1000 \
  --completion-channel orchestration
$ scripts/adapter doctor
```

`adapter doctor`는 런타임 presence JSON 리포트만 반환한다.

## 실패 형태

| 증상 | 확인 | 조치 |
| --- | --- | --- |
| 스폰이 호스트를 못 부름 | `command -v orca`; `orca status` | Shell command 등록 |
| Preflight `BLOCKED` | `FAIL` 줄 | 필수 갭 수정; 의도된 경우만 `PREFLIGHT_WAIVE` |
| 마스터가 제품 레포 아래에만 있음 | 사이드바 vs 워크스페이스 루트 | misplacement. 두 번째 Founding 금지 → succession/recovery |
| Orca 없이 에이전트가 오류에 계속 진행 | 세션 전 `orca status` | 중단. 감독 경로 불가 |
| “Unavailable worktree” | 폴더 워크스페이스 여부 | 예상 동작 |
| 두 번째 세션이 master 주장 | `orca terminal list`; lineage / check-duplicates | 사고. Reverify는 스폰 안 함 |
| `SPAWN_PLACEMENT_MISMATCH` (exit 26) | `--expected-placement` vs 실제 좌석 | 경로 selector로 재시도 금지; 설정 후 **새** 세션 |
| 빈 mailbox / binding 상실 | orchestration Run 바인딩 | `run-create` 후 재측정; empty mailbox ≠ 완료 |
| inject “dispatched”인데 워커가 시작 화면 | Dispatch 상태 vs 셸 프롬프트 도착 | task ready 리셋 후 `orca terminal send`로 브리프 재전달, 프롬프트 착지 확인 |

## 제약 (이 경로에 해당하는 것)

- 로컬 전용: `src/`·`scripts/` 네트워킹 import 없음, API 키 없음. 에이전트 CLI가 각자 제공자에 연결하는 것은 기존 동작.
- 라이브 세션은 Orca 필수. 순수 함수 CLI는 Orca 없이 동작.
- 마스터 기본 스폰 경로는 Claude Code 검증 조합; 워커는 터미널 바이너리 무엇이든 계약 하에 가능.

## Next

<CardGroup>
<Card title="Installation" href="/installation">
Orca·CLI·preflight FAIL/WARN·셸 명령 등록 상세.
</Card>
<Card title="프로그레시브 온보딩" href="/onboarding">
라우터, 1회 1단계·Verify, Founding/Reverify/Upgrade.
</Card>
<Card title="Orca 객체 모델" href="/orca-object-model">
project·folder workspace·worktree·terminal·selector·UI 라벨.
</Card>
<Card title="Supervised dispatch" href="/supervised-dispatch">
check → dispatch → register, ledger, model probe, mailbox.
</Card>
<Card title="마스터 라이프사이클" href="/master-lifecycle">
founding → steady state → succession → lineage.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
BLOCKED, placement, MODEL_PROBE_FAILED, seat 중복, revival.
</Card>
</CardGroup>