# 개요

> 워크스페이스 오케스트레이터가 노출하는 공개 진입점, 두 저장소의 역할, 가장 짧은 성공 경로, 주요 문서 라우트를 정리합니다.

- Repository: local/master-ops-with-local-mogui-ADE-orchestrator

- Human docs: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3
- Complete Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms-full.txt

## Source Files

- `local-mogui-ade-orchestrator:README.md`
- `local-mogui-ade-orchestrator:docs/public/overview.md`
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-master-ops:ONBOARDING.md`
- `local-master-ops:docs/MASTER-OPERATIONS.md`

---

---
title: "개요"
description: "워크스페이스 오케스트레이터가 노출하는 공개 진입점, 두 저장소의 역할, 가장 짧은 성공 경로, 주요 문서 라우트를 정리합니다."
---

`mogui-ADE-orchestrator`는 Orca terminal, git worktree, 로컬 `scripts/` CLI, `master-ops/` 템플릿을 조합해 장기 실행 master 세션과 worker 세션을 운영하는 워크스페이스 오케스트레이터다. 런타임은 모델 API를 직접 호출하지 않으며, 실제 실행 단위는 Orca 안의 agent CLI 터미널과 저장소 checkout이다.

## 공개 진입점

| 표면 | 위치 | 역할 |
| --- | --- | --- |
| 설치 시작 | `local-mogui-ade-orchestrator:README.md` | clone, Orca 등록, agent CLI 시작, wake-up 문장까지의 최소 경로 |
| 사람용 시작 문서 | `local-mogui-ade-orchestrator:docs/public/getting-started.md` | 도구 측정, Orca CLI 등록, 첫 founding 흐름 |
| 에이전트 온보딩 라우터 | `local-master-ops:ONBOARDING.md` | Founding, Reverify, Upgrade, Template improve 모드 분기 |
| 운영 헌장 | `local-master-ops:docs/MASTER-OPERATIONS.md` | role, 실행 원칙, dispatch, succession, record, observability 문서 라우터 |
| 런타임 CLI | `local-mogui-ade-orchestrator:scripts/` | `master-succeed`, `dispatch-gate`, `master-bootstrap-live`, `acceptance-loop`, `redaction-scan.sh` 등 |
| 설치 템플릿 | `local-master-ops:MANIFEST.json` | ops 저장소에 복사될 템플릿 파일 목록과 `template_version` |

<Info>
Orca는 live master 운영의 필수 substrate다. 순수 함수와 일부 CLI 검사는 Orca 없이 실행할 수 있지만, supervised dispatch, terminal placement, master spawn, worker completion mailbox는 Orca 런타임에 의존한다.
</Info>

## 두 저장소의 역할

| 저장소 | 소유 범위 | 설치 후 위치 |
| --- | --- | --- |
| `local-mogui-ade-orchestrator` | Python stdlib 기반 runtime, 공개 문서, config example, redaction gate, succession/dispatch/acceptance CLI | installer와 runtime source |
| `local-master-ops` | workspace 운영 템플릿, onboarding step, charter, lineage/runbook/card skeleton, model tier policy template | 새 workspace의 ops repository로 복사 및 치환 |

`master-ops/`는 제품 저장소가 아니다. 설치가 끝나면 workspace root 아래에 별도 ops repository가 생기고, 제품 repository들은 sibling checkout으로 남는다. Workspace root 자체는 보통 git repository가 아닌 plain folder이며, master seat는 그 folder workspace에 놓인다. 단일 저장소 workspace만 예외적으로 primary worktree를 master seat로 쓸 수 있다.

```text
workspace-root/
  CLAUDE.md              # 배포된 workspace session card
  AGENTS.md              # 배포된 workspace session card
  product-repo-a/        # worker 대상 제품 저장소
  product-repo-b/        # worker 대상 제품 저장소
  workspace-ops/         # master-ops 템플릿에서 생성된 운영 저장소
```

## 가장 짧은 성공 경로

<Steps>
<Step title="오케스트레이터를 clone한다">

```console
$ git clone https://github.com/baksohyeon/mogui-ADE-orchestrator
$ cd mogui-ADE-orchestrator
```

</Step>

<Step title="Orca에 folder project를 등록한다">

Orca UI에서 workspace root 또는 이 clone을 project로 추가한다. CLI가 등록되어 있으면 다음 형태도 쓸 수 있다.

```console
$ orca repo add --path <path-to-folder>
$ orca status
```

성공 조건은 Orca CLI가 `PATH`에 있고 runtime이 ready 상태인 것이다.

</Step>

<Step title="Orca terminal에서 agent CLI를 시작한다">

```console
$ claude
```

`claude`는 가장 많이 검증된 master host다. 다른 agent CLI는 worker로 쓸 수 있으며, master host runtime은 onboarding에서 측정하거나 기록한다.

</Step>

<Step title="wake-up 문장만 보낸다">

```text
Wake the master.
```

또는

```text
일어나라 마스터여
```

구체 작업이 없으면 agent는 installer 역할로 `master-ops/ONBOARDING.md`를 읽고 mode classification부터 시작한다.

</Step>

<Step title="Founding이면 Step 0 preflight부터 통과한다">

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

preflight는 Orca, orchestration Run, agent CLI, worker runtime, `git`, `gh`, `python3`, `bd`, skills, redaction rules를 측정한다. `FAIL`은 founding을 막고, `WARN`은 단독으로 exit 1을 만들지 않는다.

</Step>
</Steps>

## 온보딩 모드

`ONBOARDING.md`는 설치 절차 전체를 한 번에 읽는 문서가 아니라 mode router다. 각 step은 별도 파일로 분리되어 있고, 이전 step의 Verify가 통과해야 다음 파일을 연다.

| 모드 | 진입 조건 | spawn 여부 |
| --- | --- | --- |
| Founding | 새 workspace에 ops repository와 Generation 1 master를 만든다 | 허용 |
| Reverify | 이미 founded된 workspace의 상태를 점검한다 | 차단 |
| Upgrade | 기존 ops repository의 template drift를 확인하고 template-layer 파일만 갱신한다 | 차단 |
| Template improve | 오케스트레이터 저장소 자체의 문서나 코드를 수정한다 | 설치 흐름 중단 |

기존 ops repository나 lineage 파일이 있으면 Founding으로 재진입하지 않는다. 죽은 master, 중단된 Gen-1 boot, 살아 있는 master의 succession은 설치 재실행이 아니라 ops repository의 recovery/succession 경로가 처리한다.

## 런타임 경계

`src/master_runtime/core/`는 orchestration 판단을 담당하고, 실제 terminal 생성과 host 조작은 Orca CLI와 adapter layer를 통해 일어난다.

| 런타임 유닛 | 대표 표면 | 동작 |
| --- | --- | --- |
| Bootstrap | `scripts/master-bootstrap`, `scripts/master-bootstrap-live` | charter, handoff, Role State, active-track context를 bounded block으로 만든다 |
| Dispatch gate | `scripts/dispatch-gate check/register/watch/report` | contract, model tier, fan-out, completion channel, job probe를 gate ledger에 기록한다 |
| Succession | `scripts/master-succeed detect/handoff/spawn/verify-successor/check-duplicates/retire` | master handoff, successor spawn, duplicate detection, predecessor retirement를 분리한다 |
| Workspace descriptor | `config/workspace-descriptor.json` | sibling repository inventory, role, capability, prohibition을 instance config로 기록한다 |
| Redaction gate | `scripts/redaction-scan.sh`, `scripts/redaction-inventory` | tracked content, commit message, organization rule loading 범위를 명시하고 fail-closed한다 |

<Note>
Provider-neutral 경계는 “모델을 추상 API로 감싼다”가 아니라 “로컬 agent CLI 터미널을 Orca가 관리한다”에 있다. Skill pack, repository file, catalog source는 portable source로 취급할 수 있지만, 이 runtime은 특정 hosted model provider나 proprietary connector를 요구하지 않는다.
</Note>

## Dispatch의 최소 형태

Worker에게 일을 넘기기 전에는 contract 파일이 먼저 있어야 한다. Gate는 contract를 읽고 hash를 기록하며, 허용된 dispatch만 ticket과 JSONL ledger에 남긴다.

```console
$ scripts/dispatch-gate --ledger ~/.mogui/dispatch-ledger.jsonl check \
  --runtime codex \
  --model <model-id> \
  --contract <contract-file> \
  --agents 1 \
  --est-chars <estimated-input-chars> \
  --completion-channel orchestration
```

Founding spawn 절차도 같은 원칙을 따른다. Run과 Task를 만들고, `master-succeed spawn`으로 placement-verified terminal을 만든 뒤, Orca orchestration dispatch와 `dispatch-gate register`로 job identity를 다시 확인한다. Worker의 `done` 문장은 completion evidence가 아니라 claim이며, master가 별도로 acceptance를 수행한다.

## 주요 설정 파일

| 파일 | 필드 예시 | 비고 |
| --- | --- | --- |
| `config/instance-runtime.json` | `master_host_runtime`, `transcript_globs`, `product_repo` | master host와 transcript probe 위치를 instance가 소유한다 |
| `config/workspace-descriptor.json` | `workspace_root`, `master_seat`, `repositories[]` | repository role은 `product` 또는 `ops`; prohibition은 fail-closed 판단에 쓰인다 |
| `config/model-tier-policy.json` | `version`, `tiers`, `fanout_caps`, `window_seconds` | instance policy가 있으면 template fallback보다 우선한다 |
| `master-ops/MANIFEST.json` | `template_version`, `files[]` | ops repository 생성과 template drift 판단의 기준이다 |

## 문서 라우트

<CardGroup>
<Card title="설치" href="/installation">
설치 전 도구, redaction rules, Orca CLI, Beads, 선택 skill stack의 측정 경로를 확인한다.
</Card>
<Card title="Quickstart" href="/quickstart">
clone부터 Orca 등록, wake-up 문장, 첫 작은 작업까지의 최소 실행 경로를 따른다.
</Card>
<Card title="온보딩 모드" href="/onboarding-modes">
Founding, Reverify, Upgrade, Template improve의 진입 조건과 spawn 금지 조건을 구분한다.
</Card>
<Card title="워크스페이스와 제품 저장소 관계" href="/workspace-product-relationship">
orchestrator, ops repository, product repository, sibling checkout 모델을 분리해서 본다.
</Card>
<Card title="작업자 위임" href="/dispatch-workers">
contract, dispatch gate, Orca task, register probe, completion channel, acceptance 재검증 흐름을 확인한다.
</Card>
<Card title="CLI 참조" href="/cli-reference">
공개 `scripts/` 명령, option, exit code, drift test 기준을 확인한다.
</Card>
</CardGroup>