okstra 0.79.0 → 0.81.0

package/README.kr.md

@@ -74,12 +74,14 @@ okstra/                          npm 패키지 = repo 루트
 ├── archive/                     완료된 run
 └── .locks/                      central/task mutex 파일
 
-~/.claude/skills/                Claude Code 가 자동 인식
-└── okstra-*/SKILL.md            스킬 11종 (§3.3 참조)
+~/.claude/skills/                Claude Code 가 자동 인식 (`~/.claude` 가 있을 때)
+~/.codex/skills/                 Codex 호환 host 가 인식 (`~/.codex` 가 있을 때)
+~/.omp/agent/skills/             둘 다 없을 때 OMP-native fallback skill target
+└── okstra-*/SKILL.md            사용자 노출 스킬 + hidden 내부 지원 스킬
 
-~/.claude/agents/                Claude Code 가 자동 인식 (subagent 디스커버리 경로)
+~/.claude/agents/                Claude Code 가 자동 인식 (`~/.claude` 가 있을 때)
 └── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
-                                 (multi-agent dispatch 필수)
+                                 (Claude Code multi-agent dispatch 필수)
 
 <프로젝트 루트>/.okstra/
 ├── project.json                 {projectId, projectRoot, ...} (`/okstra-setup` 이 작성)
@@ -95,8 +97,8 @@ okstra/                          npm 패키지 = repo 루트
 |---|---|---|
 | 런타임 코드 (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
 | agents/prompts/schemas/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
-| 스킬 마크다운 | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (`installed-skills.json` 에 트래킹) |
-| 워커 에이전트 마크다운 | `~/.claude/agents/<worker>.md` | `okstra install` (`installed-agents.json` 에 트래킹) |
+| 스킬 마크다운 | `~/.claude/skills`, `~/.codex/skills`, 또는 `~/.omp/agent/skills` | `okstra install` (`installed-skills.json` 에 target별 트래킹) |
+| 워커 에이전트 마크다운 | `~/.claude/agents/<worker>.md` | `~/.claude` 가 있을 때 `okstra install` (`installed-agents.json` 에 트래킹) |
 | 프로젝트 메타데이터 | `<project>/.okstra/` | `/okstra-setup` + 프로젝트 자체 |
 | Run 인덱스 | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 
@@ -108,7 +110,7 @@ okstra/                          npm 패키지 = repo 루트
 npx -y okstra@latest install
 ```
 
-`~/.okstra/{lib/python, bin, templates, version}`, `~/.claude/skills/` 아래 스킬 마크다운 11개, `~/.claude/agents/` 아래 worker agent 4개, `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
+`~/.okstra/{lib/python, bin, templates, version}` 과 `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 스킬 설치는 host home 기준입니다. `~/.claude` 가 있으면 `~/.claude/skills/` 와 `~/.claude/agents/` 에 설치하고, `~/.codex` 가 있으면 `~/.codex/skills/` 에도 설치합니다. 둘 다 없고 `~/.omp/agent` 가 있으면 `~/.omp/agent/skills/` 에 설치합니다. 사용자 진입점 스킬만 목록에 보이고, lead/support 내부 스킬은 hidden 으로 설치되어 런타임이 해석할 수만 있게 둡니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
 
 검증:
 
@@ -125,10 +127,10 @@ npx -y okstra@latest doctor
 ```bash
 npm i -g okstra
 okstra --version       # CLI 가 PATH 에 잡혔는지 확인
-okstra install         # 'npx -y okstra@latest install' 와 동일
+okstra install          # 'npx -y okstra@latest install' 과 동일
 ```
 
-글로벌 설치는 Node CLI 를 PATH 에 등록할 뿐입니다. 런타임(`~/.okstra/`) 과 Claude 스킬(`~/.claude/skills/`) 은 여전히 `okstra install` 이 생성합니다 — `npm i -g` 에 포함되지 않습니다. 실험적 Codex lead adapter 용 공유 runtime 만 설치하려면 `okstra install --runtime codex` 를 사용하세요 (`~/.claude` 자산은 건너뜀). 이후 업그레이드: `npm i -g okstra@latest && okstra install`. 글로벌 바이너리 제거: `npm uninstall -g okstra` (`~/.okstra/` 는 그대로; 그것까지 지우려면 `okstra uninstall`).
+글로벌 설치는 Node CLI 를 PATH 에 등록할 뿐입니다. 런타임(`~/.okstra/`) 과 host skill directory(`~/.claude/skills/`, `~/.codex/skills/`, 또는 `~/.omp/agent/skills/`) 는 여전히 `okstra install` 이 생성합니다 — `npm i -g` 에 포함되지 않습니다. 이후 업그레이드: `npm i -g okstra@latest && okstra install`. 글로벌 바이너리 제거: `npm uninstall -g okstra` (`~/.okstra/` 는 그대로; 그것까지 지우려면 `okstra uninstall`).
 
 **글로벌 설치 시 스킬 동작.** 모든 okstra 스킬은 PATH 에 잡힌 `okstra` 를 자동 감지하여 `npx -y okstra@latest` 대신 우선 사용합니다. 즉 글로벌 설치를 해두면 매 스킬 호출(`okstra-run`, `okstra-inspect`, `okstra-schedule`, `okstra-setup` Step 2 의 Step 0) 마다 npx 가 패키지 fetch / 버전 체크하던 비용이 사라집니다. 스킬이 본인이 설치한 버전을 그대로 쓰므로 **업그레이드 타이밍은 사용자가 통제** 합니다 — 더 이상 호출마다 `@latest` 가 강제되지 않습니다. 새 릴리스를 받으려면 원하는 시점에 `npm i -g okstra@latest && okstra install` 을 실행하세요. `okstra` 가 PATH 에 없으면 스킬은 자동으로 npx fallback 으로 동작하므로 글로벌 설치가 없는 환경에서도 변경 없이 그대로 동작합니다.
 

package/README.md

@@ -73,12 +73,14 @@ okstra/                          npm package = repo root
 ├── archive/                     completed runs
 └── .locks/                      central/task mutex files
 
-~/.claude/skills/                discovered automatically by Claude Code
-└── okstra-*/SKILL.md            11 skills total (see §3.3)
+~/.claude/skills/                discovered automatically by Claude Code (if ~/.claude exists)
+~/.codex/skills/                 discovered by Codex-compatible hosts (if ~/.codex exists)
+~/.omp/agent/skills/             fallback OMP-native skill target when neither exists
+└── okstra-*/SKILL.md            visible user skills + hidden internal support skills
 
-~/.claude/agents/                discovered automatically by Claude Code
+~/.claude/agents/                discovered automatically by Claude Code (if ~/.claude exists)
 └── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
-                                 (required for multi-agent dispatch)
+                                 (required for Claude Code multi-agent dispatch)
 
 <project-root>/.okstra/
 ├── project.json                 {projectId, projectRoot, ...} (written by /okstra-setup)
@@ -94,8 +96,8 @@ okstra/                          npm package = repo root
 |---|---|---|
 | Runtime code (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
 | agents/prompts/schemas/templates/validators | npm package's `runtime/` | the `okstra` package (resolved via `okstra paths`) |
-| Skill markdown | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (tracked in `installed-skills.json`) |
-| Worker agent markdown | `~/.claude/agents/<worker>.md` | `okstra install` (tracked in `installed-agents.json`) |
+| Skill markdown | `~/.claude/skills`, `~/.codex/skills`, or `~/.omp/agent/skills` | `okstra install` (tracked per target in `installed-skills.json`) |
+| Worker agent markdown | `~/.claude/agents/<worker>.md` | `okstra install` when `~/.claude` exists (tracked in `installed-agents.json`) |
 | Project metadata | `<project>/.okstra/` | `/okstra-setup` + the project itself |
 | Run index | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 
@@ -107,7 +109,7 @@ okstra/                          npm package = repo root
 npx -y okstra@latest install
 ```
 
-Provisions `~/.okstra/{lib/python, bin, templates, version}`, the 11 skill markdown files under `~/.claude/skills/`, the 4 worker agents under `~/.claude/agents/`, and the installed-asset manifests in `~/.okstra/`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
+Provisions `~/.okstra/{lib/python, bin, templates, version}` and the installed-asset manifests in `~/.okstra/`. Skill installation is host-home driven: if `~/.claude` exists, okstra copies skills to `~/.claude/skills/` and worker agents to `~/.claude/agents/`; if `~/.codex` exists, it also copies skills to `~/.codex/skills/`; if neither exists and `~/.omp/agent` exists, it copies skills to `~/.omp/agent/skills/`. User-facing skills are visible; internal lead/support skills are installed hidden so the runtime can resolve them without cluttering the list. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
 
 Verify:
 
@@ -124,10 +126,10 @@ Every example in this README uses `npx -y okstra@latest <cmd>` so you don't need
 ```bash
 npm i -g okstra
 okstra --version       # confirm the CLI is on PATH
-okstra install         # same as 'npx -y okstra@latest install'
+okstra install          # same as 'npx -y okstra@latest install'
 ```
 
-The global install only registers the Node CLI on your PATH. The runtime (`~/.okstra/`) and the Claude skills (`~/.claude/skills/`) are still provisioned by `okstra install` — they are not part of `npm i -g`. To install only the shared runtime for the experimental Codex lead adapter, use `okstra install --runtime codex` (skips `~/.claude` assets). To upgrade later: `npm i -g okstra@latest && okstra install`. To remove the global binary: `npm uninstall -g okstra` (leaves `~/.okstra/` untouched; remove that with `okstra uninstall`).
+The global install only registers the Node CLI on your PATH. The runtime (`~/.okstra/`) and host skill directories (`~/.claude/skills/`, `~/.codex/skills/`, or `~/.omp/agent/skills/`) are still provisioned by `okstra install` — they are not part of `npm i -g`. To upgrade later: `npm i -g okstra@latest && okstra install`. To remove the global binary: `npm uninstall -g okstra` (leaves `~/.okstra/` untouched; remove that with `okstra uninstall`).
 
 **Skill behaviour with a global install.** All okstra skills auto-detect a PATH-resolved `okstra` and prefer it over `npx -y okstra@latest`. That means a global install removes the per-call npx fetch / version-check from every skill invocation (Step 0 of `okstra-run`, `okstra-inspect`, `okstra-schedule`, `okstra-setup` Step 2). Since the skill uses your globally installed version directly, *you* control upgrade timing — `@latest` is no longer forced on each call. Run `npm i -g okstra@latest && okstra install` whenever you want to pull a new release. If `okstra` is not on PATH the skill silently falls back to npx, so machines without a global install keep working unchanged.
 

package/docs/kr/architecture.md

@@ -18,7 +18,7 @@
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](../../scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
 - **Required team contract**: 각 phase profile의 `Required workers:` 블록이 roster의 권위입니다. 일반 분석 phase는 Claude/Codex analyser + report-writer를 기본으로 하고, Gemini는 profile과 `--workers`가 허용할 때만 포함됩니다. `release-handoff`처럼 lead-only에 가까운 phase는 별도 roster를 가집니다.
-- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 11종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. `--runtime codex` 는 실험적 Codex lead adapter 용 공유 runtime 만 설치하고 `~/.claude` 자산을 건너뜁니다. 전역 대화 메모리는 프로젝트와 분리된 `~/.okstra/memory-book/` 에 저장됩니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`)을 설치하고, 존재하는 agent home 에 skill 을 복사합니다. `~/.claude` 가 있으면 Claude skills + worker agent 4종(`~/.claude/agents/*-worker.md`), `~/.codex` 가 있으면 Codex skills, 둘 다 없고 `~/.omp/agent` 가 있으면 OMP-native skills 를 설치합니다. 사용자 진입점 스킬만 목록에 노출되고 lead/support 내부 스킬은 `hide: true` 로 설치됩니다. 전역 대화 메모리는 프로젝트와 분리된 `~/.okstra/memory-book/` 에 저장됩니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 실행 권한을 제공합니다.
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Derived views and telemetry**: final-report data.json → Markdown → slim MD / self-contained HTML view, worker error sidecar, wrapper log sidecar, token usage / cost accounting을 제공합니다.
 
@@ -152,9 +152,9 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`agents/SKILL.md`](../../agents/SKILL.md) — main okstra lead contract.
 - [`skills/okstra-setup/SKILL.md`](../../skills/okstra-setup/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) — **현재 claude 세션 안에서 okstra task 를 시작**하는 in-session 진입점. `prepare_task_bundle` 직접 호출.
-- `skills/okstra-{brief,run,memory,inspect,schedule,context-loader,team-contract,convergence,report-writer,coding-preflight}/SKILL.md` — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/log/cost read-side, schedule 보조 skill, 구현/검증 워커의 언어별 coding preflight. `okstra-inspect logs` 는 codex/gemini wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내 (read-only, find-delete cleanup 명령 제안만 함). `okstra-inspect cost` 는 `okstra context-cost` CLI 결과를 요약해 task bundle 의 lead/worker/report-writer 읽기 비용을 보여준다.
-- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다.
-- 설치 위치: `~/.claude/skills/<name>/SKILL.md` (`okstra-install.sh` dev 설치, 또는 위 npx 채널).
+- `skills/okstra-{brief,run,memory,inspect,schedule,context-loader,team-contract,convergence,report-writer,coding-preflight}/SKILL.md` — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/log/cost read-side, schedule 보조 skill, 구현/검증 워커의 언어별 coding preflight. `context-loader` / `team-contract` / `convergence` / `report-writer` / `coding-preflight` 와 `agents/SKILL.md` lead skill 은 내부 지원 스킬이며 frontmatter `hide: true` 로 설치되어 목록에는 노출되지 않습니다. `okstra-inspect logs` 는 codex/gemini wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내 (read-only, find-delete cleanup 명령 제안만 함). `okstra-inspect cost` 는 `okstra context-cost` CLI 결과를 요약해 task bundle 의 lead/worker/report-writer 읽기 비용을 보여준다.
+- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 6개(`okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-memory`, `okstra-inspect`, `okstra-schedule`)만 노출한다.
+- 설치 위치: `~/.claude/skills/<name>/SKILL.md`, `~/.codex/skills/<name>/SKILL.md`, 또는 fallback `~/.omp/agent/skills/<name>/SKILL.md`.
 - 릴리스 절차: [`../../RELEASING.md`](../../RELEASING.md) — npm publish 흐름과 release-please / manual fallback.
 
 ## Architecture: python authority + thin callers
@@ -533,7 +533,7 @@ scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래
 - `.okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
 - `.okstra/discovery/task-catalog.json`: 현재 프로젝트에 준비된 okstra task bundle 목록을 `taskKey`, `taskGroup`, `taskId` 기준으로 유지하는 canonical project-level catalog
 - `instruction-set/reference-expectations.md`: 현재 task가 참조해야 할 config files, deployment manifests, expected values를 task-level canonical artifact로 정리한 파일
-- `~/.claude/skills/okstra-*/...`, `~/.claude/agents/...`: `okstra install` 이 사용자 홈에 seed하는 Claude asset (project-local 시딩은 더 이상 발생하지 않음 — `okstra install --refresh` 로 갱신)
+- `~/.claude/skills/okstra-*/...`, `~/.codex/skills/okstra-*/...`, `~/.omp/agent/skills/okstra-*/...`, `~/.claude/agents/...`: `okstra install` 이 사용자 홈에 seed하는 skill/agent asset (project-local 시딩은 더 이상 발생하지 않음 — `okstra install --refresh` 로 갱신)
 
 이전의 아래 파일들은 더 이상 okstra 생성 대상이 아닙니다.
 
@@ -1001,8 +1001,8 @@ phase 산출물의 출고 가능 여부를 강제하는 진입점:
 - Executor 별 worktree cwd 주입: codex / gemini executor 는 wrapper(`okstra-codex-exec.sh -C` / `okstra-gemini-exec.sh --include-directories`) 가 CLI layer 에서 cwd 를 worktree 로 고정합니다. Claude executor 는 Bash tool 에 per-call cwd 인자가 없어 cwd 민감 toolchain (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) 호출을 같은 Bash invocation 안에서 `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` 로 prefix 합니다 — `bash -lc`/`bash -c` 래핑은 금지되며 (`cd` leading token 이 가려져 permission auto-allow 우회 실패), 작업 디렉터리 플래그 (`git -C`, `cargo --manifest-path` 등) 가 있으면 그것을 우선합니다. 자세한 규약은 `prompts/profiles/implementation.md` 의 *Executor Worktree* 블록과 `agents/workers/claude-worker.md` 의 Executor exception 항목 참고.
 - project-level current-task convenience pointer는 `.okstra/discovery/latest-task.json`입니다.
 - project-level canonical task inventory는 `.okstra/discovery/task-catalog.json`입니다.
-- okstra Claude asset은 `~/.claude/skills/`와 `~/.claude/agents/` 아래에 `okstra install` 시점에 seed되며, `okstra install --refresh` 로 갱신할 수 있습니다 (per-project seeding은 더 이상 수행되지 않음).
-- seeded okstra Claude assets는 Agent Teams 우선, sequential/background fallback 차선 규칙을 Claude에게 제공합니다.
+- okstra skill asset은 `okstra install` 시점에 존재하는 agent home 기준으로 seed됩니다: `~/.claude/skills/` + `~/.claude/agents/`, `~/.codex/skills/`, 또는 fallback `~/.omp/agent/skills/` (per-project seeding은 더 이상 수행되지 않음).
+- seeded okstra Claude assets는 Agent Teams 우선, sequential/background fallback 차선 규칙을 Claude에게 제공합니다. Codex/OMP targets 는 skill markdown 만 받습니다.
 - 최종 판단은 스크립트가 아니라 Claude가 수행합니다.
 - stable task key를 유지해야 이후 bug 추적, 재수정, 재검증이 가능합니다.
 - 워커 에러는 옵션 sidecar `runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl`로 수집되며 lead가 단독 writer입니다. 진입점 helper는 `scripts/okstra-error-log.py`입니다.

package/docs/kr/cli.md

@@ -318,7 +318,19 @@ Lead runtime independence boundary:
 - `codex`: Codex lead adapter 용 runtime marker 입니다. `okstra codex-run` 이 `--render-only --lead-runtime codex` 를 소유해 task bundle 을 준비하고, 준비된 run manifest 는 `okstra codex-dispatch` 로 CLI-backed worker 실행에 넘길 수 있습니다.
 - `external`: Claude Code Teams 없이 `--render-only --lead-runtime external` 로 task bundle 과 external lead prompt 를 준비하고, lead 는 `okstra team dispatch` / `okstra team await` / `okstra team teardown` 으로 tmux-pane worker lifecycle 을 관리합니다. 이 path 는 `TeamCreate` / `Agent(...)` 를 쓰지 않고 artifact-only accounting 을 사용합니다.
 
-현재 Claude Code 독립 범위는 external lead prompt + `okstra team *` worker dispatch 입니다. non-render `okstra_ctl.run --lead-runtime external` remains blocked; 완전한 external lead driver 는 아직 별도 구현 대상입니다. `--runtime external` does not install `~/.claude` assets, but selecting a `claude` worker still requires a local Claude CLI wrapper.
+현재 Claude Code 독립 범위는 external lead prompt + `okstra team *` worker dispatch 입니다. non-render `okstra_ctl.run --lead-runtime external` remains blocked; 완전한 external lead driver 는 아직 별도 구현 대상입니다. `--runtime external` 은 runtime adapter 선택만 의미하며, 스킬 설치 여부는 `~/.claude` / `~/.codex` / `~/.omp/agent` home 존재 여부가 결정합니다. `claude` worker 선택은 여전히 local Claude CLI wrapper 를 필요로 합니다.
+
+### Runtime auto-detection (`auto`)
+
+`okstra run` 의 기본 runtime은 `auto` 입니다. `auto` 는 host 기반으로 `claude-code`, `codex`, `external` 중 하나로 resolve 됩니다 (`src/runtime-resolver.mjs`). 우선순위: 명시 runtime > `OKSTRA_RUNTIME_HOST` env > Claude Code skill handoff > tmux 가용 시 external > 그 외 fail-fast (safe fallback: 의도와 다른 runtime 으로 조용히 넘어가지 않음).
+
+- Claude Code 안에서는 `/okstra-run` 이 front door 입니다. bare `okstra run` 은 Claude Code `TeamCreate` / `Agent(...)` 를 호출할 수 없습니다.
+- Codex host: `okstra run` 이 `codex-run` -> `codex-dispatch` 를 orchestration 합니다.
+- generic terminal + tmux: `okstra run` 이 `render-bundle --lead-runtime external` -> `okstra team dispatch` -> `okstra team await` 를 orchestration 합니다.
+
+`okstra install` / `ensure-installed` / `doctor` / `render-bundle` 도 `auto` 를 기본값으로 받지만, host signal 이 없는 plain terminal 에서는 host 지정이 필요합니다. 그래서 Claude Code skill 들은 `--runtime claude-code` / `--lead-runtime claude-code` 를 명시합니다. 단, `okstra install` 의 스킬 복사 대상은 runtime resolution 이 아니라 agent home 존재 여부입니다. `~/.claude` 와 `~/.codex` 가 있으면 둘 다 설치하고, 둘 다 없을 때만 `~/.omp/agent` 를 fallback 으로 사용합니다.
+
+`installed-runtimes.json` 은 schemaVersion 2 로 `installRequest`, `runtimeResolution`, `installedRuntimes`, `installedAssets` 를 분리합니다. `installed-skills.json` 은 schemaVersion 2 target 목록(`provider`, `root`, `skills`)으로 Claude/Codex/OMP skill target 을 기록하며, uninstall 은 이 target 목록을 기준으로 제거합니다. 이전 `codexAdapter` / `externalAdapter` 는 v1 manifest read 호환 경로에서만 해석됩니다.
 
 Codex lead dry-run 은 `okstra codex-run <args...>` 를 쓰면 됩니다. 이 명령은 `--render-only --lead-runtime codex` 를 직접 붙이고, worker dispatch 없이 준비된 task bundle 과 lead prompt 를 출력합니다.
 생성된 team-state / run-manifest / task-manifest 는 `leadEventsPath` 로 `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl` 를 가리키며, render 단계는 `bundle-prepared` event 를 기록합니다.
@@ -611,9 +623,9 @@ chmod +x ~/.local/bin/okstra-ctl
 | 명령 | 용도 |
 |---|---|
 | `okstra paths [--field <name>\|--shell]` | package/runtime/home/bin/pythonpath/version 경로 출력 |
-| `okstra install [--runtime claude-code\|codex\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | runtime, templates, skills, agents 설치/갱신. 기본값 `claude-code` 는 기존처럼 Claude skills/agents 까지 설치한다. `codex` / `external` 은 공유 runtime 만 설치하고 `~/.claude` 자산을 건드리지 않는다 |
-| `okstra ensure-installed [--runtime claude-code\|codex\|external\|all] [-q]` | 설치 상태 확인, stale이면 같은 runtime 으로 재설치. `codex` / `external` runtime 은 Claude skills/agents drift 검사를 건너뛴다 |
-| `okstra uninstall [--purge -y]` | 설치 자산 제거. 기본값은 사용자 데이터 보존 |
+| `okstra install [--runtime claude-code\|codex\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | runtime, templates, skills, agents 설치/갱신. 기본 runtime 은 `auto`; 스킬 대상은 runtime 이 아니라 기존 home 기준이다. `~/.claude` 가 있으면 Claude skills + agents, `~/.codex` 가 있으면 Codex skills, 둘 다 없고 `~/.omp/agent` 가 있으면 OMP skills 를 설치한다 |
+| `okstra ensure-installed [--runtime claude-code\|codex\|external\|all] [-q]` | 설치 상태 확인, stale이면 같은 runtime 으로 재설치. 존재하는 skill target 의 drift 만 검사한다 |
+| `okstra uninstall [--purge -y]` | 설치 자산 제거. 기본값은 `installed-skills.json` target 목록과 `installed-agents.json` 기준으로 제거하고 사용자 데이터는 보존 |
 | `okstra doctor [--runtime claude-code\|codex\|external\|all] [--phase <phase>] [--json]` | runtime + Python import + skill/agent 설치 진단. `codex` / `external` runtime 은 Claude skill checks 를 제외한다. `--phase` 는 `implementation`, `final-verification`, `release-handoff`, `improvement-discovery` 실행 전 readiness 체크를 추가한다 |
 | `okstra setup --project-id <id>` | 현재 프로젝트의 `.okstra/project.json` 생성/갱신 |
 | `okstra check-project [--json]` | 현재 프로젝트가 등록되었는지 검증 |

package/docs/project-structure-overview.md

@@ -124,13 +124,15 @@ Runtime/install asset changes follow this checklist:
 - `runtime/python/*` → `~/.okstra/lib/python/`
 - `runtime/bin/*` → `~/.okstra/bin/`
 - `runtime/templates/*` → `~/.okstra/templates/`
-- `runtime/skills/<name>` → `~/.claude/skills/<name>`
-- `runtime/agents/workers/*.md` → `~/.claude/agents/*-worker.md`
-- install manifests → `~/.okstra/installed-skills.json`, `~/.okstra/installed-agents.json`
+- `runtime/skills/<name>` + `runtime/agents/SKILL.md` → existing skill homes: `~/.claude/skills`, `~/.codex/skills`, or fallback `~/.omp/agent/skills`
+- `runtime/agents/workers/*.md` → `~/.claude/agents/*-worker.md` when `~/.claude` exists
+- install manifests → `~/.okstra/installed-skills.json` (target-aware), `~/.okstra/installed-agents.json`
 - version stamp → `~/.okstra/version`
 
 `--link <repo>` mode is for development and symlinks installed files back to repo sources.
 
+`src/runtime-resolver.mjs` is the single reference point for runtime auto-detection. `okstra install` defaults to `--runtime auto`, records the request and resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree. Skill targets are discovered from existing agent homes: `~/.claude` and `~/.codex` are both populated when present; `~/.omp/agent` is the fallback only when neither exists. Dynamic capabilities such as `tmux` and `codex` CLI availability are checked by `doctor` and `run`, not frozen into the install manifest. Claude Code skills pass explicit `--runtime claude-code` / `--lead-runtime claude-code` so they never depend on host auto-detection.
+
 ---
 
 ## 4. 폴더별 역할
@@ -391,7 +393,7 @@ Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a s
 ### 7.1 First setup
 
 1. `okstra install`
-2. `okstra doctor`
+2. `okstra doctor --runtime claude-code`
 3. inside target repo: `okstra setup --project-id <id>` or `/okstra-setup`
 
 ### 7.2 Brief creation