okstra 0.3.0 → 0.4.0

package/README.md

@@ -1,4 +1,175 @@
-# OKSTRA Usage Manual
+# okstra
+
+> npm: [`okstra`](https://www.npmjs.com/package/okstra) · 설치: `npx -y okstra@latest install`
+
+## 1. 용도
+
+`okstra` 는 **Claude Code 안에서 task 한 건을 lead + 워커(Codex, Gemini, Claude) 조합으로 cross-verify 하기 위한 정형화된 진행 도구**입니다. 사용자는 자연어로 task brief 만 적어두면, okstra 가 task 정체성 · profile · prompt · run history · 프로젝트 레벨 metadata 를 한 묶음(task bundle)으로 만들어 Claude lead 가 안정적으로 phase 진행과 워커 dispatch 를 수행하도록 돕습니다.
+
+핵심 가치는 다음 세 가지입니다.
+
+- **단일 진입점(`prepare_task_bundle`)**: 어떤 호출자(스킬, bash CLI)가 들어와도 task 디렉터리 구조 · 매니페스트 · 검증 경로가 동일하게 산출됩니다.
+- **task 정체성의 영구화**: `<project-id>/<task-group>/<task-id>` stable task key 가 phase 간 / 세션 간 / 모델 간 컨텍스트를 잇습니다.
+- **lead/worker 계약 강제**: 모든 task 는 Claude lead + 4종 worker(claude, codex, gemini, report-writer) 의 표준 구성을 갖고 진행되며, 산출 형식과 검증 절차가 templates/ + validators/ 로 묶여 있습니다.
+
+cross-verify 가 필요 없는 단발 코드 리뷰는 okstra 의 범위가 아닙니다. okstra 는 **여러 단계로 나뉘는, 여러 에이전트가 의견을 내는, 그리고 그 결과가 다음 phase 의 입력이 되어야 하는** 작업을 위해 만들어졌습니다.
+
+## 2. 구조
+
+### 2.1 repo 레이아웃
+
+```
+okstra/                                    npm 패키지 = repo 루트 (0.3.0 부터)
+├── package.json                           name: "okstra", publish 단위
+├── bin/okstra                             노드 CLI 진입점
+├── src/                                   설치자/리졸버 (install, paths, doctor, check-project, uninstall)
+├── tools/build.mjs                        runtime/ 동기화 스크립트 (prepack 에서 호출)
+├── runtime/                               (gitignored, 빌드 산출물; npm tarball 에는 포함)
+│   ├── python/                            ← scripts/{okstra_project, okstra_ctl, okstra_token_usage, lib}
+│   ├── bin/                               ← scripts/*.{sh,py}
+│   ├── agents/                            ← agents/ (lead SKILL.md + workers/)
+│   ├── skills/                            ← skills/ (사용자 노출 스킬 11종)
+│   ├── prompts/, templates/, validators/  ← 동명 디렉터리
+│   └── BUILD.json                         빌드 stamp
+├── scripts/                               python+bash 런타임 원본
+│   ├── okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
+│   ├── okstra.sh, okstra-codex-exec.sh, okstra-gemini-exec.sh, okstra-central.sh
+│   └── okstra-token-usage.py, okstra-error-log.py
+├── skills/                                Claude Code 스킬 마크다운 원본
+│   ├── okstra-setup/SKILL.md              부트스트랩 (프로젝트별 1회)
+│   ├── okstra-run/SKILL.md                task 시작
+│   ├── okstra-status/SKILL.md             진행 현황
+│   ├── okstra-history/, okstra-schedule/, okstra-time-summary/, okstra-report-finder/
+│   └── okstra-context-loader/, okstra-team-contract/, okstra-convergence/, okstra-report-writer/
+├── agents/                                lead + workers
+├── prompts/, templates/, validators/
+├── tests/, tests-e2e/
+├── .claude-plugin/plugin.json             skills 채널(보조) 매니페스트
+├── .github/workflows/{release-please.yml, release.yml}
+├── release-please-config.json, .release-please-manifest.json
+├── RELEASING.md, CHANGELOG.md, README.md
+└── CHANGES.md
+```
+
+### 2.2 설치 후 사용자 머신 레이아웃
+
+```
+~/.okstra/                                 okstra install 이 채우는 런타임 home
+├── version                                package 버전 stamp
+├── lib/python/                            okstra_project/, okstra_ctl/, ...
+├── bin/                                   okstra.sh, codex-exec, gemini-exec, ...
+├── installed-skills.json                  설치된 스킬 manifest (uninstall 용)
+├── recent.jsonl, active.jsonl             실행 인덱스
+├── projects/                              프로젝트별 메타 미러
+├── archive/                               완료된 run 보관
+└── .locks/                                task 단위 mutex
+
+~/.claude/skills/                          Claude Code 가 자동 발견
+├── okstra-setup/SKILL.md
+├── okstra-run/SKILL.md
+└── ... (11종)
+
+<프로젝트 루트>/.project-docs/okstra/      대상 프로젝트의 okstra metadata
+├── project.json                           {projectId, projectRoot, ...} (okstra-setup 이 작성)
+├── discovery/{task-catalog,latest-task}.json
+└── tasks/<task-group>/<task-id>/         task bundle (run history, manifest, reports)
+```
+
+### 2.3 단일 권위 요약
+
+| 자원 | 위치 | 책임자 |
+|---|---|---|
+| 런타임 코드(python+bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
+| agents/prompts/templates/validators | npm 패키지의 `runtime/<...>/` | `okstra` 패키지 자체 (복사 없음, `okstra paths` 로 조회) |
+| 스킬 마크다운 | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (+ `installed-skills.json` 매니페스트) |
+| 프로젝트 메타 | `<프로젝트>/.project-docs/okstra/` | `okstra-setup` 스킬 + 프로젝트 자체 |
+| 실행 인덱스 | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
+| task 단위 락 | `~/.okstra/.locks/<task-key>.lock` | `prepare_task_bundle` |
+
+## 3. 사용 매뉴얼
+
+### 3.1 최초 셋업 (머신당 1회)
+
+```bash
+npx -y okstra@latest install
+```
+
+위 한 명령으로 다음이 한꺼번에 깔립니다.
+
+- `~/.okstra/{lib/python, bin, version}` — python + bash 런타임
+- `~/.claude/skills/<name>/SKILL.md` × 11 — 스킬 마크다운
+- `~/.okstra/installed-skills.json` — 매니페스트
+
+이미 깔린 상태에서 다시 실행해도 됩니다(per-file hash 비교로 변경분만 갱신, idempotent).
+
+검증:
+
+```bash
+npx -y okstra@latest doctor
+```
+
+`result: OK` 가 나오면 정상. FAIL 항목 있으면 그 안내대로(보통 install 재실행).
+
+### 3.2 프로젝트 등록 (프로젝트당 1회)
+
+대상 프로젝트 디렉터리에서 Claude Code 세션 열고:
+
+```
+/okstra-setup
+```
+
+스킬이 인터랙티브하게:
+
+1. okstra 런타임 상태 확인 (위 3.1 미실행 시 안내)
+2. `projectId` 묻기 (자유 식별자 — `INV-1234`, `fontsninja`, `okstra` 등)
+3. `<프로젝트>/.project-docs/okstra/project.json` 생성
+
+이후의 모든 진입점 스킬은 이 파일이 없으면 "먼저 `/okstra-setup` 을 실행하세요" 라고 거부합니다.
+
+### 3.3 일상 명령
+
+Claude Code 세션 안에서 / 슬래시 명령 또는 자연어 트리거:
+
+| 명령 | 용도 |
+|---|---|
+| `/okstra-run` | 새 task 시작 (또는 기존 task 다음 phase 이어가기) |
+| `/okstra-status` | 프로젝트 전체 또는 특정 task 의 phase/상태 조회, workStatus 변경 |
+| `/okstra-history` | 과거 task 목록, 재개 후보 확인 |
+| `/okstra-schedule` | task-group 단위 작업 계획표 생성 |
+| `/okstra-time-summary` | task 의 소요 시간 분석 (lead, 워커별) |
+| `/okstra-report-finder` | task-key 로 최종 보고서 위치 조회 / 보고서 읽기 |
+
+내부적으로 lead 가 phase 진행 중 호출하는 helper 스킬 4종(`okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`) 은 사용자가 직접 호출할 일이 거의 없습니다.
+
+### 3.4 CLI 모드 (선택)
+
+Claude Code 가 아닌 별도 터미널에서 task 를 띄울 때:
+
+```bash
+~/.okstra/bin/okstra.sh \
+  --project-id <id> \
+  --task-group <group> \
+  --task-id <id> \
+  --task-type <error-analysis|implementation-planning|...> \
+  --task-brief ./brief.md
+```
+
+새 `claude` 프로세스를 띄워 lead 로 동작시킵니다. 인자 자세히는 [Required arguments](#required-arguments) 섹션 참조.
+
+### 3.5 운영 명령
+
+| 명령 | 용도 |
+|---|---|
+| `npx -y okstra@latest paths` | 런타임 경로 조회 (JSON 또는 `--field <name>` / `--shell`) |
+| `npx -y okstra@latest doctor` | 진단 (런타임 + 스킬 + python import) |
+| `npx -y okstra@latest ensure-installed` | 매 호출 시 idempotent 검증 + 필요 시 자동 install (스킬 내부에서 호출) |
+| `npx -y okstra@latest check-project` | 현재 디렉터리에 okstra-setup 이 완료됐는지 검사 |
+| `npx -y okstra@latest uninstall` | 런타임 + 스킬 제거. user data(recent.jsonl, projects/ 등) 보존 |
+| `npx -y okstra@latest uninstall --purge -y` | 전부 제거 (user data 포함) |
+
+릴리스 절차는 [`RELEASING.md`](RELEASING.md) 참조.
+
+---
 
 ## At a glance
 
@@ -155,7 +326,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 ### Skills (`skills/`, `agents/`)
 
 - [`agents/SKILL.md`](agents/SKILL.md) — main okstra skill (cross-verify 트리거).
-- [`skills/setup-okstra/SKILL.md`](skills/setup-okstra/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
+- [`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-{status,history,convergence,schedule,context-loader,team-contract,report-finder,report-writer,time-summary}/SKILL.md` — phase 진행·status·history 보조 skill.
 - 플러그인 매니페스트: [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 0.3.0 부터는 `npx okstra install` 한 명령이 동일 결과를 보장하므로 일반 셋업에는 이 채널이 필요 없다.

package/bin/okstra

@@ -7,22 +7,24 @@ const COMMANDS = new Map([
   ["ensure-installed", () => import("../src/install.mjs").then((m) => m.runEnsureInstalled)],
   ["uninstall", () => import("../src/uninstall.mjs").then((m) => m.runUninstall)],
   ["doctor", () => import("../src/doctor.mjs").then((m) => m.run)],
+  ["check-project", () => import("../src/check-project.mjs").then((m) => m.run)],
 ]);
 
-const USAGE = `okstra-cli — runtime installer and path resolver for okstra skills
+const USAGE = `okstra — runtime installer + path/setup resolver for okstra skills
 
 Usage:
   okstra <command> [options]
 
 Commands:
-  install                Install okstra runtime into ~/.okstra
+  install                Install okstra runtime + skills into ~/.okstra + ~/.claude/skills
   ensure-installed       Verify install is fresh; reinstall if stale (idempotent)
-  uninstall              Remove installed runtime (user data preserved by default)
-  paths                  Print runtime paths (agents/pythonpath/bin/home/version)
+  uninstall              Remove installed runtime + skills (user data preserved by default)
+  paths                  Print runtime paths (workspace/agents/pythonpath/bin/home/version)
   doctor                 Diagnostic check of the installed runtime
+  check-project          Verify current project has .project-docs/okstra/project.json
 
 Global options:
-  --version              Print okstra-cli version and exit
+  --version              Print okstra version and exit
   --help                 Print this help
 
 Run 'okstra <command> --help' for command-specific options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.3.0",
-  "builtAt": "2026-05-11T15:55:55.785Z",
+  "package": "0.4.0",
+  "builtAt": "2026-05-12T03:09:54.795Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/skills/okstra-history/SKILL.md

@@ -11,6 +11,25 @@ description: Use when the user asks to list past okstra runs, check execution hi
 - When re-running or resuming a previous execution
 - When checking the execution status of each task
 
+## Step 0: Verify okstra runtime + project setup
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
+use `projectRoot` to locate `.project-docs/okstra/discovery/task-catalog.json`.
+
 ## Step 1: Read the Task Catalog
 
 1. Read `.project-docs/okstra/discovery/task-catalog.json`.

package/runtime/skills/okstra-report-finder/SKILL.md

@@ -11,6 +11,25 @@ description: Use when the user provides a task key and needs to find the final r
 - 이전 okstra 보고서를 읽고 후속 작업을 진행할 때
 - 보고서 내용을 기반으로 구현, 수정, 추가 검증을 시작할 때
 
+## Step 0: Verify okstra runtime + project setup
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` (JSON `{ok, projectRoot, projectJsonPath, projectId}`) —
+`projectRoot` 로 catalog/manifest 위치를 잡는다.
+
 ## Step 1: Task Key로 Report 경로 찾기
 
 task-key 형식: `<project-id>:<task-group>:<task-id>`

package/runtime/skills/okstra-run/SKILL.md

@@ -30,21 +30,28 @@ Every step reads disk afresh. The `OKSTRA_*` env vars below identify the
 - `<PROJECT_ROOT>/.project-docs/okstra/discovery/{task-catalog,latest-task}.json`
 - `<task-root>/task-manifest.json`
 
-## Step 0: Resolve okstra runtime paths
+## Step 0: Verify okstra runtime + project setup
 
 Do NOT hard-code or guess any okstra path. Every run loads them fresh from
 the single authority — `okstra`:
 
 ```bash
-# 1) Ensure okstra runtime is fresh (idempotent, cached when up-to-date)
+# 1) Ensure runtime is fresh (idempotent, cached when up-to-date)
 npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; run: npx okstra@latest install" >&2
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
   exit 1
 }
 
 # 2) Load all runtime paths into the shell as OKSTRA_* exports
 eval "$(npx -y okstra@latest paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
+
+# 3) Verify the current project has okstra metadata (project.json + projectId)
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
 ```
 
 After Step 0 the following are guaranteed:
@@ -56,6 +63,7 @@ After Step 0 the following are guaranteed:
 | `$OKSTRA_PYTHONPATH` | already exported as `PYTHONPATH` |
 | `$OKSTRA_BIN` | bash entrypoints (`okstra.sh`, codex/gemini exec wrappers) |
 | `$OKSTRA_HOME` | `~/.okstra` (recent.jsonl, locks, projects/, archive/) |
+| `$OKSTRA_PROJECT_INFO` | JSON: `{ok, projectRoot, projectJsonPath, projectId}` — parse and reuse instead of re-resolving in Step 1 |
 
 ## Step 1: Resolve PROJECT_ROOT and projectId
 

package/runtime/skills/okstra-schedule/SKILL.md

@@ -35,6 +35,28 @@ The default mode is lightweight (single Claude lead synthesis). The `--cross-ver
 
 If `--title` is omitted, derive a default title from `task-group` (e.g. `uploadFont` → `uploadFont — Work Schedule`).
 
+## Step 0: Verify okstra runtime + project setup
+
+Run before anything else in this skill:
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
+use `projectRoot` to locate `.project-docs/okstra/discovery/task-catalog.json`
+and the task-group directory.
+
 ## Process Procedure
 
 ### Step 0: Verify model (HARD GATE)

package/runtime/skills/{setup-okstra → okstra-setup}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: setup-okstra
-description: One-time bootstrap for okstra in a new project or on a new machine — installs the okstra runtime via npx and creates the project's .project-docs/okstra/project.json. Trigger words include "setup okstra", "initialize okstra", "okstra init", "first time okstra setup", "configure okstra here".
+name: okstra-setup
+description: One-time bootstrap for okstra in a new project or on a new machine — installs the okstra runtime via npx and creates the project's .project-docs/okstra/project.json. Trigger words include "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time okstra setup", "configure okstra here".
 ---
 
-# setup-okstra
+# okstra-setup
 
 One-time bootstrap. Run when okstra is being used for the first time on this
 machine, or when adopting okstra in a new project.

package/runtime/skills/okstra-status/SKILL.md

@@ -11,6 +11,28 @@ description: Use when the user asks for overall okstra task status, current life
 - When user want to check the current phase, next phase, blockers, and resume points for a specific `task-key`
 - When user want to check which tasks are pending approval or which tasks can be resumed
 
+## Step 0: Verify okstra runtime + project setup
+
+Before any other step, ensure both the okstra runtime and the current
+project's okstra metadata are in place:
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
+parse and reuse it instead of re-resolving in the steps below.
+
 ## Step 1: Overall Project Status
 
 To view the overall project status, first read `.project-docs/okstra/discovery/task-catalog.json`.

package/runtime/skills/okstra-time-summary/SKILL.md

@@ -26,6 +26,25 @@ Two sources, both already collected by `okstra`:
 
 If a run never reached Phase 7, its `team-state` will not have `durationMs` filled in. Mark such runs as `unavailable` rather than guessing.
 
+## Step 0: Verify okstra runtime + project setup
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` (JSON `{ok, projectRoot, projectJsonPath, projectId}`)
+gives `projectRoot` for locating `.project-docs/okstra/discovery/task-catalog.json`.
+
 ## Step 1: Resolve task-id → timeline path
 
 1. If the user gave a full `task-key` (`<project-id>:<task-group>:<task-id>`), use it directly.

package/src/check-project.mjs

@@ -0,0 +1,188 @@
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra check-project — verify that the current project has okstra setup
+
+Usage:
+  okstra check-project              Resolve PROJECT_ROOT from cwd, look for
+                                    .project-docs/okstra/project.json,
+                                    print JSON status to stdout.
+  okstra check-project --cwd <dir>  Use <dir> as the search starting point
+                                    instead of process cwd.
+  okstra check-project --json       Same as default (kept for symmetry with
+                                    'paths --json').
+  okstra check-project --quiet      Suppress stdout on success; exit code
+                                    alone reports state.
+
+Exit codes:
+  0   project.json found, projectId present
+  1   project.json missing or unreadable (project setup not done)
+  2   PROJECT_ROOT could not be resolved from cwd (no project marker
+      ancestor; user should pass --cwd or run from within a project)
+
+User-facing skills should call this after 'ensure-installed' and refuse
+to proceed if the exit code is non-zero, directing the user to
+'/okstra-setup' first.
+`;
+
+function runProcess(cmd, args, env) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString()));
+    child.stderr.on("data", (b) => (stderr += b.toString()));
+    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), quiet: false, json: true };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--quiet" || a === "-q") opts.quiet = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--cwd") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) throw new Error("--cwd requires a path");
+      opts.cwd = next;
+      i++;
+    } else {
+      throw new Error(`unknown argument '${a}'`);
+    }
+  }
+  return opts;
+}
+
+function emit(opts, payload) {
+  if (opts.quiet) return;
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const opts = parseArgs(args);
+  const paths = await resolvePaths();
+
+  const probe = await runProcess(
+    "python3",
+    [
+      "-c",
+      [
+        "import json, sys",
+        "from okstra_project import resolve_project_root, project_json_path, ResolverError",
+        "try:",
+        "    pr = resolve_project_root(explicit_root='', cwd=sys.argv[1])",
+        "    print('PROJECT_ROOT', pr)",
+        "    print('PROJECT_JSON', project_json_path(pr))",
+        "except ResolverError as e:",
+        "    print('RESOLVER_ERROR', e)",
+      ].join("\n"),
+      opts.cwd,
+    ],
+    { PYTHONPATH: paths.pythonpath },
+  );
+
+  if (probe.code !== 0) {
+    emit(opts, {
+      ok: false,
+      stage: "python",
+      reason: `python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`,
+    });
+    return 1;
+  }
+
+  const lines = probe.stdout.trim().split("\n");
+  const tagOf = (key) =>
+    lines
+      .find((l) => l.startsWith(key + " "))
+      ?.slice(key.length + 1)
+      .trim() ?? null;
+
+  const resolverError = tagOf("RESOLVER_ERROR");
+  if (resolverError) {
+    emit(opts, {
+      ok: false,
+      stage: "resolve",
+      reason: resolverError,
+      cwd: opts.cwd,
+    });
+    return 2;
+  }
+
+  const projectRoot = tagOf("PROJECT_ROOT");
+  const projectJsonPath = tagOf("PROJECT_JSON");
+  if (!projectRoot || !projectJsonPath) {
+    emit(opts, {
+      ok: false,
+      stage: "parse",
+      reason: "could not parse python output",
+      raw: probe.stdout,
+    });
+    return 1;
+  }
+
+  if (!(await fileExists(projectJsonPath))) {
+    emit(opts, {
+      ok: false,
+      stage: "project_json_missing",
+      reason: `${projectJsonPath} not found — run /okstra-setup in this project first`,
+      projectRoot,
+      projectJsonPath,
+    });
+    return 1;
+  }
+
+  let projectId = null;
+  try {
+    const data = JSON.parse(await fs.readFile(projectJsonPath, "utf8"));
+    projectId = typeof data?.projectId === "string" ? data.projectId : null;
+  } catch (err) {
+    emit(opts, {
+      ok: false,
+      stage: "project_json_invalid",
+      reason: `failed to parse ${projectJsonPath}: ${err.message}`,
+      projectRoot,
+      projectJsonPath,
+    });
+    return 1;
+  }
+
+  if (!projectId) {
+    emit(opts, {
+      ok: false,
+      stage: "project_json_invalid",
+      reason: `${projectJsonPath} missing projectId field`,
+      projectRoot,
+      projectJsonPath,
+    });
+    return 1;
+  }
+
+  emit(opts, {
+    ok: true,
+    projectRoot,
+    projectJsonPath,
+    projectId,
+  });
+  return 0;
+}

package/src/doctor.mjs

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
-const REQUIRED_SKILLS = ["setup-okstra", "okstra-run"];
+const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
 
 const USAGE = `okstra doctor — diagnose the installed runtime
 

package/src/install.mjs

@@ -430,8 +430,8 @@ export async function runEnsureInstalled(args) {
   }
   if (!(await dirExists(paths.pythonpath))) reasons.push(`missing ${paths.pythonpath}`);
   if (!(await dirExists(paths.agents))) reasons.push(`missing agents dir ${paths.agents}`);
-  if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "setup-okstra", "SKILL.md")))) {
-    reasons.push(`missing ${CLAUDE_SKILLS_DIR}/setup-okstra/SKILL.md`);
+  if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
+    reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
   }
 
   if (reasons.length === 0) {

package/src/uninstall.mjs

@@ -13,7 +13,7 @@ const BIN_ENTRYPOINTS = [
 ];
 
 const FALLBACK_SKILL_NAMES = [
-  "setup-okstra",
+  "okstra-setup",
   "okstra-run",
   "okstra-status",
   "okstra-history",
@@ -103,7 +103,7 @@ export async function runUninstall(args) {
   if (opts.purge) {
     if (!opts.yes && !opts.dryRun) {
       const ok = await promptConfirm(
-        `purge entire ${paths.home} AND ~/.claude/skills/{okstra-*,setup-okstra}? user data will be lost.`,
+        `purge entire ${paths.home} AND ~/.claude/skills/{okstra-*,okstra-setup}? user data will be lost.`,
       );
       if (!ok) {
         process.stdout.write("aborted.\n");