# 워크스페이스 Founding

> workspace root 선택, ops 저장소 생성, seat 기록, placeholder 치환, tracker 연결, Gen-1 spawn, boot smoke 검증 절차를 다룹니다.

- 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-master-ops:ONBOARDING.md`
- `local-master-ops:onboarding/02-workspace-facts.md`
- `local-master-ops:onboarding/03-ops-repo.md`
- `local-master-ops:onboarding/04-seat.md`
- `local-master-ops:onboarding/05-placeholders.md`
- `local-master-ops:onboarding/09-spawn.md`
- `local-master-ops:onboarding/10-card-and-retire.md`

---

---
title: "워크스페이스 Founding"
description: "workspace root 선택, ops 저장소 생성, seat 기록, placeholder 치환, tracker 연결, Gen-1 spawn, boot smoke 검증 절차를 다룹니다."
---

Founding은 새 workspace에 `master-ops` 템플릿을 설치하고, Orca folder workspace seat에 Generation 1 master를 정확히 하나 생성한 뒤, boot smoke와 운영 카드 전달까지 완료하는 온보딩 경로다. 이미 ops 저장소나 lineage가 있는 workspace는 Founding 대상이 아니며, 재검증은 Reverify, 템플릿 갱신은 Upgrade, 죽은 master 복구는 ops 저장소의 succession boot card로 라우팅한다.

## 진입 조건

| 조건 | Founding 처리 |
| --- | --- |
| 새 workspace | `onboarding/00`부터 `10`까지 순서대로 진행 |
| ops 저장소 존재 | Founding 중단, Upgrade 또는 succession 경로로 전환 |
| master가 이미 존재 | Founding 중단, Reverify 또는 succession 경로로 전환 |
| 템플릿 자체 수정 | 온보딩이 아니라 일반 개발 작업으로 처리 |

<Warning>
Founding은 중복 master를 만들면 안 된다. 기존 ops tree, lineage, half-finished Gen-1 boot 흔적이 있으면 새 세션을 만들지 말고 현재 상태를 먼저 분류한다.
</Warning>

## 생성되는 주요 표면

| 표면 | 위치 | 성격 |
| --- | --- | --- |
| ops 저장소 | `{{OPS_REPO}}` | governance, runbook, tracker, dispatch contract 보관소 |
| workspace descriptor | `{{RUNTIME_ROOT}}/config/workspace-descriptor.json` | workspace inventory와 guard 입력 |
| instance runtime config | `{{RUNTIME_ROOT}}/config/instance-runtime.json` | master host runtime, transcript glob, product repo |
| workspace session card | `{{OPS_REPO}}/workspace-card/{CLAUDE.md,AGENTS.md}` | workspace root에 배포되는 canonical card |
| root session card | `{{WORKSPACE_ROOT}}/{CLAUDE.md,AGENTS.md}` | agent host가 읽는 배포본 |
| lineage | `{{OPS_REPO}}/docs/lineage/MASTER-LINEAGE.md` | Gen-1 boot smoke 후 master가 append |
| role state | `{{OPS_REPO}}/docs/runbooks/role-state.md` | Gen-1 active role과 Role Lock 기록 |
| tracker | `{{OPS_REPO}}/.beads` | 실행 상태 저장소, workspace root에서 resolve되어야 함 |

## Founding 절차

<Steps>
<Step title="workspace root를 확정한다">
workspace root는 사용자가 고른 절대 경로여야 한다. 에이전트는 후보를 스캔해 추천하지 않고, 전달받은 경로가 absolute path이며 directory인지 검증한다.

```console
$ test "${WORKSPACE_ROOT#/}" != "$WORKSPACE_ROOT" && test -d "$WORKSPACE_ROOT"
$ ls -la "$WORKSPACE_ROOT"
```

확정 후 immediate child Git repository를 측정해 `{{REPO_LIST}}` 기본값으로 삼는다. workspace 밖의 저장소는 먼저 root 아래로 이동하거나 clone하도록 안내하고, 거부된 경우에만 external lane으로 기록한다.
</Step>

<Step title="descriptor와 runtime config를 채운다">
`config/workspace-descriptor.json`은 template example에서 복사한 instance-owned 파일이다. `workspace_root_is_plain_folder`는 항상 `true`이며, `repositories`에는 측정된 member repository가 들어간다.

```json
{
  "workspace_root_is_plain_folder": true,
  "workspace_root": "/absolute/path/to/workspace-root",
  "master_seat": "id:folder:<uuid>",
  "repositories": [
    {
      "name": "product-app",
      "path": "product-app",
      "remote": "https://example.invalid/product-app.git",
      "role": "product",
      "capabilities": ["pr", "dispatch-target"],
      "prohibited": ["direct-main-commit", "force-push"]
    }
  ]
}
```

`config/instance-runtime.json`은 `master_host_runtime`, 측정 가능한 경우 `transcript_globs`, 단일 primary product가 owner-confirmed인 경우 `product_repo`를 갖는다. 값이 없으면 기본 추정값을 만들지 않고 unconfigured 상태로 남긴다.
</Step>

<Step title="ops 저장소를 생성한다">
ops repository 이름은 product repository와 혼동되지 않아야 하며, 보통 `<workspace>-ops`가 기본 후보가 된다. 새 저장소이거나 비어 있으면 `{{RUNTIME_ROOT}}/master-ops/MANIFEST.json`에 등재된 Stage 1 skeleton만 복사한다.

설치된 ops 저장소에는 `MANIFEST.json`, `CLAUDE.md`, `AGENTS.md`, `docs/MASTER-OPERATIONS.md`, `workspace-card/`, runbook, script가 포함된다. `TEMPLATE-VERSION`, `CHANGELOG.md`, `ONBOARDING.md`, `onboarding/`은 template side에 남는다.
</Step>

<Step title="Orca seat를 기록한다">
ops repository를 Orca에 등록하고, 사용자가 workspace root의 folder workspace에서 임시 terminal을 열게 한 뒤 `terminal show`로 seat metadata를 측정한다.

```console
$ ORCA repo add --path "{{OPS_REPO}}" --json
$ ORCA terminal show --terminal <temporary terminal handle> --json
```

durable seat는 terminal handle이 아니라 `id:folder:<uuid>` 형식 selector다. folder workspace는 `worktreeId`가 `folder:<uuid>`이고 `worktreePath`가 비어 있는 형태로 보일 수 있다. 기록할 때는 모든 consumer가 받는 `id:` prefixed form을 사용한다. 임시 seat-check terminal은 spawn 전에 닫혀 있어야 한다.
</Step>

<Step title="placeholder를 전부 치환하고 card를 배포한다">
허용 placeholder는 다음 8개뿐이다: `{{WORKSPACE_NAME}}`, `{{WORKSPACE_ROOT}}`, `{{OPS_REPO}}`, `{{MONITOR_NS}}`, `{{MODEL_ID}}`, `{{REPO_LIST}}`, `{{RUNTIME_ROOT}}`, `{{TEMPLATE_VERSION}}`.

모든 `{{...}}` token은 이 단계에서 confirmed 또는 measured 값으로 치환한다. deferral list는 없다.

```console
$ cp "{{OPS_REPO}}/workspace-card/CLAUDE.md" "{{WORKSPACE_ROOT}}/CLAUDE.md" \
  && cp "{{OPS_REPO}}/workspace-card/AGENTS.md" "{{WORKSPACE_ROOT}}/AGENTS.md" \
  && echo deployed
deployed
```

검증은 세 가지다: ops 저장소 전체에 placeholder가 없어야 하고, ops root의 `CLAUDE.md`와 `AGENTS.md`가 byte-identical이어야 하며, `workspace-card` canonical pair와 workspace root 배포본이 각각 일치해야 한다.
</Step>

<Step title="tracker를 연결한다">
지원 tracker는 Beads다. owner 승인 후 ops repository에서 초기화하고, workspace root의 `.beads`가 ops repository의 `.beads`를 가리키게 한다.

```console
$ cd "{{OPS_REPO}}" && bd init --prefix <approved prefix>
$ { [ -e "{{WORKSPACE_ROOT}}/.beads" ] || [ -L "{{WORKSPACE_ROOT}}/.beads" ]; } \
    && echo "already exists, inspect before linking" \
    || ln -s "$(cd "{{OPS_REPO}}" && pwd)/.beads" "{{WORKSPACE_ROOT}}/.beads"
$ cd "{{WORKSPACE_ROOT}}" && bd where
```

`bd where`는 workspace root에서 ops repository로 resolve되어야 한다. 상위 directory나 product repository의 tracker DB가 선택되면 pass가 아니다.
</Step>

<Step title="Gen-1 master를 spawn한다">
spawn 전 durable selector로 `ORCA terminal list --worktree <selector> --json`를 실행해 seat가 비어 있는지 확인한다. 하나라도 terminal이 있으면 hard stop이다.

spawn은 Orca orchestration을 통해서만 진행한다. raw terminal polling이나 vendor-direct CLI dispatch는 compliant path가 아니다.

```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 <id:folder selector> \
  --kickoff-file <kickoff file> \
  --root "{{WORKSPACE_ROOT}}" \
  --model "{{MODEL_ID}}" \
  --title "Gen-1 founding boot" \
  --json
```

`dispatch-gate check`가 `allow: true`를 반환해야 spawn 또는 worker attach를 진행한다. `master-succeed spawn`은 created terminal의 `worktreeId`와 expected placement를 비교하고, mismatch 시 fail-closed한다.
</Step>

<Step title="boot smoke를 확인하고 installer를 retire한다">
boot smoke는 새 master session 안에서 실행된다. master는 Role State를 선언하고, model identity를 measured/unavailable/unsupported 중 하나로 보고하며, placement evidence를 남기고, Generation 1을 lineage에 append한 뒤 `worker_done`을 한 번만 보낸다.

마지막 단계에서 installer는 owner에게 operating card를 출력한다. 이후 newborn master가 Step 8에서 받은 kill switch로 installer terminal을 닫고, pane/process/tty disappearance를 가능한 범위에서 재확인한다. master terminal은 계속 실행 상태로 남는다.
</Step>
</Steps>

## 검증 신호

| 단계 | pass 신호 |
| --- | --- |
| workspace root | owner-provided absolute directory, measured repository inventory |
| descriptor | `workspace_root_is_plain_folder: true`, repository별 `role`, `capabilities`, `prohibited` 존재 |
| ops skeleton | `MANIFEST.json` 존재, template version 일치, required files 존재 |
| seat | durable selector가 `id:folder:<uuid>` form, 임시 terminal 닫힘 |
| placeholder | `rg '\{\{[^}]+\}\}' "{{OPS_REPO}}"` 결과 없음 |
| card | ops pair, workspace-card pair, root 배포본이 각각 byte-identical |
| tracker | workspace root에서 `bd where`가 ops repository로 resolve |
| spawn | seat empty, exactly one new master, placement `MATCH` 또는 valid `MATCH_REISSUED` |
| boot smoke | Role Lock enabled, lineage append, placement evidence, `worker_done` |

## 실패 처리

Founding 실패는 “대체 경로로 계속 진행”하지 않는다. 특히 seat selector가 실패할 때 filesystem path나 `path:` selector로 바꾸지 않는다. spawn 중 실패하면 같은 installer에서 master를 대신 boot하지 않고, 두 번째 session을 만들지 않는다.

이미 founded된 workspace에서 문제가 발견되면 Founding을 반복하지 않는다. template drift는 Upgrade로, 살아 있는 master 건강 확인은 Reverify로, master 부재 또는 half-finished boot는 `docs/runbooks/succession-boot-card.md`로 보낸다.

## Provider-neutral boundary

Founding의 source of truth는 repository files, local CLI, Orca object metadata, Beads tracker, JSON config다. skill pack이나 agent runtime은 실행 표면을 제공할 수 있지만, workspace inventory, placeholder allowlist, seat selector, tracker resolution, spawn verification은 특정 model provider나 hosted connector에 묶이지 않는다.

## Related pages

<CardGroup>
<Card title="온보딩 모드" href="/onboarding-modes">Founding, Reverify, Upgrade, Template improve의 진입 조건과 금지 경로를 구분한다.</Card>
<Card title="워크스페이스와 제품 저장소 관계" href="/workspace-product-relationship">ops 저장소, 제품 저장소, sibling checkout 모델의 경계를 확인한다.</Card>
<Card title="Orca 객체 모델" href="/orca-object-model">Project, workspace, worktree, terminal, selector 형식을 확인한다.</Card>
<Card title="작업자 위임" href="/dispatch-workers">Founding 이후 worker dispatch와 acceptance 전 재검증 흐름을 연결한다.</Card>
</CardGroup>