okstra 0.3.0 → 0.5.0

package/docs/kr/cli.md

@@ -0,0 +1,400 @@
+# okstra — CLI 인자 / 옵션 매뉴얼 (한국어)
+
+> 이 문서는 [README.kr.md](../../README.kr.md) 의 보충 문서입니다. 내부 아키텍처와 storage / workflow 계약은 [architecture.md](architecture.md) 를 참고하세요.
+
+---
+
+## Command forms
+
+기본 명령(첫 진입 / full args):
+
+```bash
+scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--related-tasks taskA,taskB] [--clarification-response <previous-final-report>] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+```
+
+후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> [--task-type <task-type>]
+```
+
+Clarification 답변 즉시 재실행:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
+```
+
+interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니다.
+
+- 필수 인자가 비어 있으면 stdin으로 직접 입력을 받습니다.
+- 입력이 모두 준비되면 실행 전 요약을 보여줍니다.
+- `y` 또는 `yes`를 입력했을 때만 실제 생성 또는 실행 단계로 진행합니다.
+- interactive가 아닌 실행에서는 누락 인자를 prompt하지 않고 에러로 종료합니다.
+- `--yes`를 사용하면 prompt와 confirmation을 모두 건너뛰지만, 이때는 모든 필수 인자가 반드시 이미 채워져 있어야 합니다.
+- 우선순위는 `명시적 CLI 인자 > interactive prompt 또는 non-interactive 에러`입니다.
+
+## Required arguments
+
+### `--project-id`
+
+전역에서 고유해야 하는 프로젝트 ID입니다. 첫 실행 시 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 에 자기 등록(self-registration)되며, 동일 PROJECT_ROOT 에서 재실행할 때 인자값과 저장된 `projectId` 가 다르면 즉시 에러로 종료합니다.
+
+예:
+
+- `fontradar-v2-api`
+- `jobs`
+
+### `--task-group`
+
+관련 task를 묶는 논리 그룹입니다.
+
+예:
+
+- `feature-8858`
+- `bugfix-auth`
+- `tasks`
+
+### `--task-id`
+
+같은 그룹 안에서 안정적으로 재사용할 task 식별자입니다.
+
+예:
+
+- `email-recipient-loss`
+- `8852`
+
+### `--task-type`
+
+이번 run의 목적과 profile 선택, run directory 세그먼트, lifecycle phase 라우팅을 결정하는 단일 입력값입니다.
+표준 값과 phase별 책임은 위 [Task type](#task-type) 섹션을 참고합니다.
+
+### `--task-brief`
+
+분석의 기준이 되는 task brief 문서 경로입니다.
+상대 경로는 대상 프로젝트 루트를 기준으로 해석됩니다.
+
+예:
+
+- `.project-docs/linear/feature/8858/okstra-task-brief.md`
+- `.project-docs/tasks/8852/BUG_REPORT.md`
+
+### `--yes`
+
+interactive prompt와 confirmation을 생략합니다.
+
+대신 아래 조건이 강제됩니다.
+
+- `project-id`
+- `task-group`
+- `task-id`
+- `task-type`
+- `brief-path`
+
+즉, 필수 인자가 하나라도 비어 있으면 prompt하지 않고 즉시 종료합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --yes --render-only --task-type error-analysis --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+## Optional arguments and options
+
+### `--task-key`
+
+기존 task에 대한 후속 phase를 시작할 때 `--project-id`/`--task-group`/`--task-id`를 한 번에 전달하는 단축 형식입니다.
+
+- 입력 형식: `<project-id>:<task-group>:<task-id>`
+- 동작:
+  - 세 ID로 split하여 `PROJECT_ID`/`TASK_GROUP`/`TASK_ID`에 채웁니다.
+  - 명시적으로 같은 값들이 함께 들어오면 일치할 때만 허용하고, 충돌하면 즉시 에러로 종료합니다.
+  - 해당 task의 `task-manifest.json`이 존재하면 누락된 `--task-brief`를 manifest의 `taskBriefPath` 로, 누락된 `--task-type`을 `workflow.nextRecommendedPhase` 로 자동 채웁니다.
+  - manifest가 없으면(첫 진입) 기존 누락-인자 검증이 그대로 동작합니다(=full args 강제).
+- 명시적으로 전달된 인자가 항상 manifest 값보다 우선합니다.
+- `nextRecommendedPhase`가 `pending-routing-decision` 또는 `done-or-follow-up`이면 자동 채움하지 않고, 사용자가 명시적으로 `--task-type`을 주거나 brief을 보강한 뒤 다시 실행해야 합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852
+```
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
+```
+
+### `--clarification-response`
+
+이전 run의 final report(`Section 5. Clarification Requests for the Next Run`에 사용자가 답변을 inline으로 채운 파일)를 다음 run으로 carry-in합니다.
+
+- 입력: `<previous-run>/reports/final-report-<task-type>-<seq>.md` 경로
+- 동작: 파일을 현재 run의 `instruction-set/clarification-response.md`로 복사하고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
+- 사용 시점: `requirements-discovery`, `error-analysis`처럼 미해결 질문을 남기는 phase 이후, 사용자가 답변을 채워 다음 phase로 넘길 때.
+
+예:
+
+```bash
+scripts/okstra.sh \
+  --task-type implementation-planning \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md \
+  --clarification-response .project-docs/okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
+```
+
+### `--resume-clarification`
+
+직전 `requirements-discovery` 또는 `error-analysis` run의 final report를 즉시 편집하고, 같은 phase를 자동으로 재실행합니다. `--clarification-response` 경로를 사용자가 직접 들고 다닐 필요가 없습니다.
+
+- 입력: task identity (`--project-id` + `--task-group` + `--task-id`, 또는 `--task-key <p>:<g>:<i>`)
+- 동작 순서:
+  1. task의 `runs/{requirements-discovery,error-analysis}/reports/final-report-*.md` 중 가장 최신 timestamp 파일을 자동 선택합니다.
+  2. `$EDITOR`(미설정 시 `vi`)로 해당 파일을 엽니다. 사용자는 Section 5의 `Q*` 행에 답변을 inline으로 채운 뒤 저장하고 종료합니다.
+  3. okstra가 같은 task-type으로 자기 자신을 `exec` 재호출하면서 편집된 파일을 `--clarification-response`로 carry-in 합니다.
+  4. 이후 confirmation, render, Claude handoff 흐름은 일반 실행과 동일합니다.
+- 명시적 `--task-type`을 함께 주면 그 task type의 reports/ 만 검색합니다. 생략 시 `error-analysis` → `requirements-discovery` 순으로 검색하고 timestamp가 더 큰 보고서를 사용합니다.
+- 다음 옵션과 함께 쓸 수 없습니다: `--render-only`, `--clarification-response`, `--approved-plan`.
+- `EDITOR`를 비대화형 도구(예: `true`)로 설정하면 답변 편집을 건너뛴 채 곧바로 재실행됩니다. 디버깅용으로만 권장합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key jobs:tasks:8852
+```
+
+```bash
+EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --task-group tasks --task-id 8852
+```
+
+내부적으로는 다음과 동등합니다.
+
+```bash
+$EDITOR <project-root>/.project-docs/okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
+scripts/okstra.sh --task-type <same-type> \
+  --project-id <p> --task-group <g> --task-id <i> \
+  --task-brief <from manifest> \
+  --clarification-response <edited final-report-<latest>.md>
+```
+
+### `--project-root`
+
+대상 프로젝트의 절대 경로입니다. 명시하지 않으면 `okstra.sh` 가 다음 우선순위로 자동 해석합니다.
+
+1. cwd 또는 그 조상 디렉토리 중 `.project-docs/okstra/project.json` 보유 위치를 찾아 PROJECT_ROOT 로 채택합니다.
+2. 위가 실패하면 `git rev-parse --show-toplevel` 결과를 사용합니다.
+3. 모두 실패하면 즉시 에러로 종료합니다.
+
+해석된 PROJECT_ROOT 에서 첫 실행이라면 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 이 다음 스키마로 자동 생성됩니다.
+
+```json
+{
+  "projectId": "<--project-id 인자 값>",
+  "projectRoot": "<resolved absolute path>",
+  "createdAt": "<ISO8601 UTC>",
+  "updatedAt": "<ISO8601 UTC>"
+}
+```
+
+이미 존재하면 `projectId` 일치 검사 후 `projectRoot`/`updatedAt` 만 갱신합니다. `projectId` 가 다르면 즉시 에러로 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
+```
+
+### `--directive`
+
+사용자 의도를 자유 텍스트로 lead·worker·downstream skill에 전달하는 채널입니다. 값은 `instruction-set/analysis-material.md` 끝에 `## Directive` 섹션으로 임베딩되고, 동시에 `instruction-set/directive.txt`로 백업됩니다.
+
+용도:
+
+- 기본 heuristic을 뒤집고 싶을 때 — 예: "단일 XL task여도 Gantt 그려줘 (Phase 2개, 총 ~10d)", "Gantt 생략 사유를 명시해줘" (참고: `## Cumulative Timeline`은 schedule contract에서 제거되었으므로 더 이상 toggle 대상이 아닙니다)
+- 분석/계획의 강조점 지시 — 예: "rollout 리스크 우선 분석", "test 커버리지 부재를 별도 finding으로"
+- Phase/Step 분할이나 day 추정을 미리 제시 — 예: "Part 1: 4d, measure: 0.5d, Part 2: 4d, ops: 1d"
+
+해석 규칙:
+
+- lead·worker는 `analysis-material.md`를 이미 end-to-end로 읽으므로 별도 작업 없이 자동 전파됩니다.
+- skill 측은 자체 contract보다 user prompt를 **우선** 적용해야 하며 (예: `okstra-schedule` 스킬의 "Directive override (highest priority)" 절), heuristic을 뒤집은 경우 결과 문서에 그 사실을 한 줄로 표시합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning ... \
+  --directive "Phase 2개(Part 1 ~4d, Part 2 ~5d, 순차)로 총 ~10d. Gantt 꼭 그려줘 (임계 경로 표시)."
+```
+
+### `--workers`
+
+이번 run에서 사용할 worker 목록을 직접 지정합니다.
+생략하면 기본값 `claude,codex,gemini,report-writer`를 사용합니다.
+지정하면 전달한 worker subset만 dedupe 후 기록됩니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--claude-model`
+
+`Claude worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CLAUDE_MODEL` 또는 fallback `sonnet`을 사용합니다.
+
+### `--lead-model`
+
+`Claude lead`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_LEAD_MODEL` 또는 fallback `opus`를 사용합니다.
+
+### `--codex-model`
+
+`Codex worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CODEX_MODEL` 또는 fallback `gpt-5.5`를 사용합니다.
+
+### `--gemini-model`
+
+`Gemini worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_GEMINI_MODEL` 또는 fallback `auto`를 사용합니다.
+
+### `--report-writer-model`
+
+`Report writer worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` 또는 lead 기본값을 사용합니다.
+
+중앙 기본값 환경 변수는 아래와 같습니다.
+
+- `OKSTRA_DEFAULT_LEAD_MODEL`
+- `OKSTRA_DEFAULT_CLAUDE_MODEL`
+- `OKSTRA_DEFAULT_CODEX_MODEL`
+- `OKSTRA_DEFAULT_GEMINI_MODEL`
+- `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
+
+fallback 기본값은 아래와 같습니다.
+
+- `Claude lead`: `opus`
+- `Report writer worker`: `opus`
+- `Claude worker`: `sonnet`
+- `Codex worker`: `gpt-5.5`
+- `Gemini worker`: `auto`
+
+### `--related-tasks`
+
+간단한 연관 task 식별자 목록을 쉼표로 전달합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,reply-ui --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+연관 task는 참고용 메타데이터이며 현재 task key를 대체하지 않습니다.
+
+### `--render-only`
+
+실제 Claude 실행 없이 프롬프트와 task bundle만 생성합니다.
+
+이 모드에서는 아래를 수행하지 않습니다.
+
+- Claude 실행
+- `final-report-<task-type>-<seq>.md` 생성
+- `final-<task-type>-<seq>.status` 생성
+
+하지만 아래는 수행합니다.
+
+- stable task root 생성 또는 갱신
+- `task-manifest.json` 생성 또는 갱신
+- `task-index.md` 생성 또는 갱신
+- `instruction-set/` 생성 또는 갱신
+- `instruction-set/reference-expectations.md` 생성 또는 갱신
+- `instruction-set/final-report-template.md` 생성 또는 갱신
+- current `manifests/run-manifest-<task-type>-<seq>.json` 기록
+- `history/timeline.json` 갱신
+- project-level discovery pointer 생성 또는 갱신
+
+### `--refresh-assets`
+
+project-local `.claude/skills/`와 `.claude/agents/` 아래의 okstra mapped asset을 workspace source 기준으로 다시 생성합니다.
+기본 rerun에서는 기존 project-local asset을 유지합니다.
+
+
+## Interactive input flow
+
+interactive terminal에서 필수 인자 일부를 생략하면 `okstra`가 아래 항목을 순서대로 물을 수 있습니다.
+
+- `Project ID`
+- `Task Group`
+- `Task ID`
+- `Task Type`
+- `Task Brief Path`
+
+예를 들어 아래처럼 실행할 수 있습니다.
+
+```bash
+scripts/okstra.sh --render-only --task-type error-analysis
+```
+
+그러면 누락된 필수값을 stdin으로 입력받은 뒤, 최종 요약과 confirmation을 거쳐 진행합니다.
+
+## Confirmation flow
+
+interactive 실행에서는 실제 파일 생성 전에 아래 성격의 요약을 보여줍니다.
+
+- render-only 여부
+- task type
+- project id
+- task group
+- task id
+- task brief path
+- analysis target
+- related tasks
+- selected workers
+- lead model
+- configured worker models
+- task key
+- task root
+- current run dir
+
+이후 `Continue? [y/yes]:` 프롬프트가 표시되며, `y` 또는 `yes`가 아니면 실행하지 않고 종료합니다.
+
+`--yes`를 사용하면 이 confirmation flow 자체를 건너뜁니다.
+
+
+---
+
+## okstra Control Center — 설치 / 자주 쓰는 명령
+
+## okstra Control Center
+
+`okstra-ctl` 은 사용자 홈의 `~/.okstra/` 인덱스를 사용해 모든 타깃 프로젝트의 okstra run 을 가로질러 조회·모니터링·재실행할 수 있는 CLI 다.
+
+### 설치 (전역 wrapper)
+
+`okstra` 와 동일하게 `~/.local/bin/` 아래에 wrapper 를 두면 어디서든 호출 가능하다.
+
+```bash
+cat > ~/.local/bin/okstra-ctl <<'WRAPPER'
+#!/usr/bin/env bash
+exec /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-ctl.sh "$@"
+WRAPPER
+chmod +x ~/.local/bin/okstra-ctl
+```
+
+(`~/.local/bin` 이 `PATH` 에 포함되어 있어야 한다.)
+
+### 자주 쓰는 명령
+
+| 목적 | 명령 |
+|---|---|
+| 작업한 프로젝트 목록 | `okstra-ctl projects` |
+| 최근 run 검색 | `okstra-ctl list --since 7d` |
+| 특정 프로젝트만 | `okstra-ctl list --project fontradar` |
+| 진행 중 run 보기 | `okstra-ctl tail active` |
+| 단일 run 결과 메타 | `okstra-ctl show <runId-or-prefix>` |
+| 결과 보고서 경로 | `okstra-ctl open <runId-or-prefix>` |
+| 단일 재실행 | `okstra-ctl rerun <runId-or-prefix> --yes` |
+| 다중 재실행 | `okstra-ctl rerun --filter --project X --status failed --yes` |
+| 가장 최근 재실행 | `okstra-ctl rerun last --project X --task-group Y --yes` |
+| 백필/재스캔 | `okstra-ctl reindex` |
+| 활성 run 재조정 | `okstra-ctl reconcile [--project <id|all>]` |
+| 배치 진행 | `okstra-ctl batch status <batch-id>` |
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -16,7 +16,9 @@
     "bin/",
     "src/",
     "runtime/",
-    "README.md"
+    "docs/",
+    "README.md",
+    "README.kr.md"
   ],
   "engines": {
     "node": ">=18"

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.3.0",
-  "builtAt": "2026-05-11T15:55:55.785Z",
+  "package": "0.5.0",
+  "builtAt": "2026-05-12T04:37:48.519Z",
   "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.