okstra 0.2.0 → 0.4.0

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

@@ -0,0 +1,87 @@
+---
+name: okstra-report-finder
+description: Use when the user provides a task key and needs to find the final report path, or wants to read a previous okstra report to continue work based on its findings. Trigger words include "find report", "show report for", "read the okstra report", "continue from report".
+---
+
+# OKSTRA Report Finder
+
+## When to Use
+
+- 사용자가 task-key를 주고 해당 최종 보고서를 찾을 때
+- 이전 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>`
+
+### 방법 A: task-catalog.json (빠름)
+
+1. `.project-docs/okstra/discovery/task-catalog.json`을 읽는다.
+2. `tasks` 배열에서 `taskKey`가 일치하는 항목을 찾는다.
+3. `latestReportPath` 필드가 최신 보고서 경로이다.
+
+### 방법 B: task-manifest.json (직접)
+
+task-catalog가 없거나 최신이 아닌 경우:
+
+1. task-key에서 task-group과 task-id를 추출한다.
+2. `.project-docs/okstra/tasks/<task-group>/<task-id>/task-manifest.json`을 읽는다.
+3. `latestReportPath` 필드가 최신 보고서 경로이다.
+
+### 방법 C: timeline.json (특정 run의 보고서)
+
+특정 날짜나 run의 보고서가 필요한 경우:
+
+1. `.project-docs/okstra/tasks/<task-group>/<task-id>/history/timeline.json`을 읽는다.
+2. `runs` 배열에서 원하는 run을 찾는다 (날짜, 상태 등으로 필터).
+3. `reportPath` 필드가 해당 run의 보고서 경로이다.
+
+## Step 2: Report 존재 확인
+
+1. 찾은 경로에 파일이 실제로 존재하는지 확인한다.
+2. 존재하면 경로를 표시하고 읽을지 사용자에게 확인한다.
+3. 존재하지 않으면:
+   - `task-manifest.json`의 `currentStatus`를 확인한다.
+   - status가 `completed`가 아니면: "이 task는 아직 완료되지 않았습니다 (status: `<status>`)."
+   - 파일만 없으면: "보고서 파일이 존재하지 않습니다: `<path>`"
+
+## Step 3: Report 읽기 및 후속 작업 안내
+
+보고서를 읽은 후 사용자에게 가능한 후속 작업을 안내한다:
+
+1. **구현 진행**: 보고서의 "권장 다음 단계" 섹션 기반으로 코드 수정
+2. **추가 검증**: 같은 task-key로 새 okstra run 실행 (`okstra-history` 스킬로 재실행 커맨드 생성)
+3. **관련 task 확인**: 보고서의 관련 task 참조가 있으면 해당 task의 보고서도 조회
+
+## Output
+
+```markdown
+## Report for <task-key>
+
+- Status: `<status>`
+- Report path: `<relative-path>`
+- Run date: `<YYYY-MM-DD HH:MM>`
+- Task type: `<task-type>`
+```
+
+이후 사용자 요청에 따라 보고서를 읽고 후속 작업을 진행한다.

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

@@ -0,0 +1,256 @@
+---
+name: okstra-report-writer
+description: Use when okstra is in Phase 6 or Phase 7 — writing the final synthesis report, persisting artifacts, or updating manifests.
+user-invocable: false
+---
+
+# OKSTRA Report Writer
+
+## File-author ownership (BLOCKING)
+
+The final-report file at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md` is authored by the `Report writer worker` subagent when that worker is in the run's roster. Claude lead reviews the file but does NOT write it itself in that case. Lead-authored fallback is permitted only after a real Report writer worker dispatch attempt with a recorded non-`completed` terminal status (`error` / `timeout` / `not-run`) and a logged reason (`okstra-error-log.py`).
+
+If you are reading this skill **as the report-writer-worker subagent**, YOU are the one calling the `Write` tool against the result path. Do not return the report inline — the file on disk is the canonical artifact.
+
+If you are reading this skill **as Claude lead**, your job in Phase 6 is to (a) prepare the report-writer prompt, (b) dispatch the Report writer worker per the Phase 6 dispatch template in SKILL.md, (c) review the produced file in Phase 7. Do not call `Write` against the final-report path yourself when Report writer worker is in the roster.
+
+## When to Use
+
+- During Phase 6 of the OKSTRA skill (final report assembly)
+- During Phase 7 of the OKSTRA skill (artifact persistence — verification only when Report writer worker is in roster)
+- When verifying the structure of the final report
+
+## Phase 6 dispatch template (Report writer worker)
+
+Lead dispatches the report-writer worker via the Agent tool. Lead does NOT write the final-report file when this worker is in the roster.
+
+```text
+Agent(
+  description: "Author final report for <task-key>",
+  prompt: "<report-writer prompt: see this skill + Required reading clause + Available MCP Servers section>",
+  name: "report-writer",
+  subagent_type: "report-writer-worker",
+  team_name: "okstra-<task-key>",   # omit if team is not alive — see Resume-safe dispatch
+  model: "opus",
+  mode: "auto"
+)
+```
+
+The prompt MUST include, in this order at the top:
+
+1. `**Project Root:** <absolute-path>`
+2. `**Prompt History Path:** <project-relative-path>` (under current run `prompts/`)
+3. `**Result Path:** runs/<task-type>/reports/final-report-<task-type>-<seq>.md` — canonical final-report file (user-facing)
+4. `**Worker Result Path:** runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` — mandatory validator-checked worker-results audit file
+5. `Assigned worker prompt history path: <absolute-path>`
+6. `**Model:** Report writer worker, <modelExecutionValue>` (resolved per Phase 5.5 anchor-header rules)
+7. The full `[Required reading]` clause (see [okstra-team-contract](../okstra-team-contract/SKILL.md)) including `final-report-template.md`.
+8. The verbatim `## Available MCP Servers` block from the task brief, if present.
+9. The convergence classifications (Full/Partial/Contested/Worker-Unique) and pointers to all worker result files under `worker-results/`.
+10. For implementation-planning runs: a literal block listing the 8 required English section headings the validator scans for (`Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`). The writer must use these exact substrings as section headings (Korean translation in parentheses is allowed).
+11. An explicit instruction: `You are the author of TWO files: (a) the final-report file at <Result Path>, (b) the worker-results file at <Worker Result Path>. Write both directly using your Write tool. Do not return the report inline. The validator fails the run when (b) is missing.`
+
+### Resume-safe dispatch
+
+A resumed lead session can ALWAYS dispatch a fresh Report writer worker. The Agent tool does not require a previously created Team to be alive:
+
+- If `TeamCreate` for `okstra-<task-key>` still succeeds (or the team is still listed), include `team_name` in the dispatch.
+- If `TeamCreate` reports the name is taken or the team is gone, omit `team_name` from the dispatch — the worker still runs as a background subagent and its session is still recoverable by `agentName: "report-writer"` in `okstra-token-usage.py`.
+- Do NOT skip dispatch because of any team-related error. Record the team status in team-state and proceed without `team_name`.
+
+### Lead-authored fallback (only if dispatch failed)
+
+Lead-authored fallback is permitted only if all of the following are true and recorded in team-state:
+
+1. A Report writer worker dispatch was actually attempted (Agent call was issued).
+2. The attempt recorded a terminal status of `error`, `timeout`, or `not-run` with a concrete reason (tool error message, timeout duration, or external blocker).
+3. The reason is logged via `okstra-error-log.py append-observed --error-type cli-failure ...` (or `tool-failure` if the failure was internal).
+
+Speculative reasons such as "session resume constraint", "team object no longer exists", or "lead can do it faster" are NOT valid.
+
+## Phase 7 token-usage collector (BLOCKING)
+
+At the start of Phase 7, run the token-usage collector with the final-report substitution flag. This step is BLOCKING — both the team-state aggregation AND the final-report placeholder substitution happen here, in one invocation:
+
+```bash
+python3 scripts/okstra-token-usage.py \
+  <runDirectoryPath>/state/team-state-<task-type>-<seq>.json \
+  --write --summary \
+  --substitute-final-report <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
+```
+
+This:
+
+- Populates `leadUsage`, every `workers[].usage`, and `usageSummary` in team-state from session transcripts.
+- Substitutes the 10 token-related placeholders (`{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`) in the final-report file with concrete values from the freshly computed usageSummary.
+
+Skipping `--substitute-final-report` is the recurring root cause of reports shipping with literal `{{LEAD_TOTAL_TOKENS}}` etc. in their Token Usage Summary table. Always pass the flag — never run the collector without it during Phase 7.
+
+The final-report file MUST already exist before this step runs (it's authored by Report writer worker in Phase 6, or by Lead in the documented fallback case). The status file can be written after this step completes.
+
+## Final Report Structure
+
+The final report follows the structure below. If `instruction-set/final-report-template.md` exists, that format takes precedence.
+
+### Report Header
+
+```markdown
+# <task-key> - Multi-Agent Cross Verification Final Report
+- Date: <ISO 8601 timestamp>
+- Task Key: <task-key>
+- Task Type: <task-type>
+- Author: `<Report writer worker if in roster, else Claude lead>`
+- Lead model: `<lead-model>`
+- Preparation Method: Final report authored by Report writer worker (or lead-authored fallback — record the documented dispatch failure reason here when applicable)
+```
+
+### Agent-Specific Execution Status Table
+
+```markdown
+| Agent | Role | Model | Status | 처리 토큰 | 환산 토큰 | 비용 (USD) | Duration | Summary of Key Findings |
+|-------|------|-------|--------|-----------|-----------|------------|----------|------------------------|
+| Claude Code | Claude lead | opus | completed | 10,479,327 | 1,769,798 | $26.55 | 59m 12s | Final synthesis status |
+| Claude Code | Claude worker | sonnet | completed | 1,941,396 | 475,136 | $1.43 | 13m 33s | Key findings summary |
+| Codex | Codex worker | gpt-5.5 | completed | 2,274,011 (CLI: 5,261,833) | 586,223 | $8.79 (+ CLI $4.20) | 22m 06s | Key findings summary |
+| Gemini | Gemini worker | auto | completed | 3,107,795 | 746,623 | $11.20 | 22m 06s | Key findings summary |
+| Claude Code | Report writer | opus | completed | 665,497 | 267,210 | $4.01 | 4m 20s | Report organization |
+```
+
+Table Generation Rules:
+- The first row is always `Claude lead` with data from `leadUsage`; subsequent rows follow `recommendedWorkers` / `resultContract.requiredWorkerRoles` order.
+- Agent labels: Claude worker/Report writer → "Claude Code", Codex worker → "Codex", Gemini worker → "Gemini".
+- **처리 토큰** = `usage.totalTokens` (input + output + cache_creation + cache_read; the raw volume processed).
+- **환산 토큰** = `usage.billableEquivalentTokens` (cache reads weighted at 0.1×, cache_creation 1.25×, output 5×; useful as a single number for "how big was this session in cost terms").
+- **비용 (USD)** = `usage.estimatedCostUsd`. For Codex/Gemini workers that actually invoked the CLI, append `(+ CLI $X.XX)` from `usage.cliEstimatedCostUsd`.
+- For Codex/Gemini workers, append `(CLI: <cliTotalTokens>)` to the 처리 토큰 cell when `usage.cliTotalTokens` is set.
+- Status values are retrieved from team-state; format duration as `Xm Ys` from `usage.durationMs`.
+- Workers with status `not-run` or with `source: "unavailable"` show `--` for tokens/cost/duration; quote the `note` underneath the table if useful.
+
+### Token Usage Summary Section
+
+Place this section immediately after the execution status table.
+
+```markdown
+### 토큰 사용량 요약
+
+| 항목 | 처리 토큰 | 환산 토큰 (input 기준) | 비용 (USD) |
+|------|-----------|------------------------|------------|
+| Lead | 10,479,327 | 1,769,798 | $26.55 |
+| Worker 합계 | 7,988,699 | 2,075,192 | $25.43 |
+| **전체 합계** | **18,468,026** | **3,844,990** | **$51.97** |
+| Codex/Gemini CLI 추가 비용 |  |  | $0.00 |
+
+> **읽는 법**: "처리 토큰"은 모델이 실제로 처리한 raw 토큰 합계(input + output + cache_creation + cache_read). 긴 세션에서는 cache_read가 95% 이상을 차지해 숫자가 커 보입니다. "환산 토큰"은 cache_read를 0.1×, cache_creation을 1.25×, output을 5×로 가중한 input-등가 토큰으로, 비용 감각에 가깝습니다. 비용은 공시 가격(Anthropic/OpenAI/Google) 기준 추정치입니다.
+```
+
+Token Summary Generation Rules:
+- All values come from `usageSummary` (populated by `scripts/okstra-token-usage.py` at the start of Phase 7). Do not estimate or invent.
+- **Lead** row: `usageSummary.leadTotalTokens` / `usageSummary.leadBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.lead`.
+- **Worker 합계** row: `usageSummary.workerTotalTokens` / `usageSummary.workerBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.claudeWorkers`.
+- **전체 합계** row: `usageSummary.grandTotalTokens` / `usageSummary.grandBillableEquivalentTokens` / sum of `lead + claudeWorkers`.
+- **Codex/Gemini CLI 추가 비용** row: `usageSummary.estimatedCostUsd.cliWorkers`. If 0, still show the row so the reader sees that no CLI work was billed under those providers (or that CLI fallback occurred).
+- Format tokens with comma separators (e.g., `32,500`); format USD with two decimals (e.g., `$1.43`).
+- If `lead` or any `worker.usage` has `source: "unavailable"`, show `--` for that row and append a one-line note (`reason: <note>`).
+- If pricing for a model is unknown, the script omits `estimatedCostUsd` for that block — show `N/A` in that column and add a note like `pricing missing for model <model>`.
+
+### Implementation-planning section heading contract (BLOCKING)
+
+When the run's `task-type` is `implementation-planning`, the final report MUST contain section headings whose **lines include each of the 8 literal English substrings below**. The validator (`validators/validate-run.py`) does plain substring matching on the report text — 7-of-8 missing was a real, repeatedly observed failure mode caused by translating the headings to Korean.
+
+| # | Required substring | Recommended heading form |
+|---|--------------------|--------------------------|
+| 1 | `Option Candidates` | `### Option Candidates (옵션 후보)` |
+| 2 | `Trade-off` | `### Trade-off Matrix (트레이드오프 매트릭스)` |
+| 3 | `Recommended Option` | `### Recommended Option (권장 옵션)` |
+| 4 | `Stepwise Execution Order` | `### Stepwise Execution Order (단계별 실행 순서)` |
+| 5 | `Dependency` | `### Dependency / Migration Risk (의존성·마이그레이션 위험)` |
+| 6 | `Validation Checklist` | `### Validation Checklist (검증 체크리스트)` |
+| 7 | `Rollback` | `### Rollback Strategy (롤백 전략)` |
+| 8 | `User Approval Request` | `### User Approval Request (사용자 승인 요청)` |
+
+The Korean translation in parentheses is optional but the English keyword is mandatory. The body of each section is written in Korean per the writing rules below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
+
+The final-report template `okstra-final-report.template.md` Section 4.5 already encodes this contract — copy that block verbatim and fill in.
+
+### Mandatory worker-results file (BLOCKING)
+
+You (the report-writer-worker subagent) MUST also write a worker-results audit file at the path the lead provides as `**Worker Result Path:**`, defaulting to:
+
+```
+runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md
+```
+
+This file is checked by the validator whenever the role's terminal status is `completed`. Without it the run fails with `report-writer is completed but worker result file is missing`.
+
+The file content is short: it begins with the standard worker-result header from `okstra-team-contract`, then names the canonical final-report path you wrote, lists the input artifacts you reconciled, and records any structural deviations from `final-report-template.md`. Do NOT duplicate the full final-report body here — it's an audit pointer, not a second copy.
+
+Skipping this file because "the real report is in `reports/`" is wrong. Both files are required.
+
+### Main Body Section
+
+Section numbering matches `okstra-final-report.template.md`. Section 0 is the carry-in reconciliation that runs first when a clarification response was provided; sections 1–7 follow the template's main body order.
+
+0. **Clarification Response Carried In** - if `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty, read `instruction-set/clarification-response.md`, reconcile every prior `Q*` row, and record the outcome (`resolved`/`obsolete`) plus the new evidence in this section before drafting the verdict
+1. **Problem or Verification Summary** - Key summary based on the brief and data (3–5 bullet points)
+2. **Cross Verification Results** (Use 4 categories when convergence is enabled, per `okstra-convergence`)
+   - Full Consensus: Findings agreed upon by all workers
+   - Partial Consensus: Agreed upon by a majority of workers; dissenting opinions are specified
+   - Contested: No consensus after max rounds; each worker’s position specified
+   - Worker-Unique: Verified only by the discoverer; verification history specified
+   - In runs with convergence disabled, maintain the existing Consensus/Differences format
+3. **Final Verdict** - Conclusion based on comprehensive evidence; direction provided
+4. **Evidence and Detailed Analysis**
+   - Key Evidence: File path, line number, actual evidence
+   - If explicit expected values are present in `reference-expectations.md`, specify whether they match or differ from the expected values in config files / deployment manifests
+   - Supporting evidence or alternative interpretations
+5. **Missing Information and Risks** - Uncertain/I don't know items
+6. **Clarification Requests for the Next Run** - structured Q&A table the user fills inline before reruns
+   - Required for `task-type` `error-analysis` and `requirements-discovery` whenever blocking uncertainty remains
+   - Optional for other task-types; explicitly state "no clarification needed" when none
+   - Follow the table format from `final-report-template.md` exactly (columns: Question ID, Blocking, Why this matters, Question, Expected answer shape, Status, Answer)
+   - Use stable `Q1`, `Q2`, ... ids and never delete prior ids on rerun; mark them `resolved` or `obsolete` instead
+7. **Recommended Next Steps** - Actions by Priority
+
+### Writing Guidelines
+
+- Write in Markdown (actively use tables, bullet points, and code blocks)
+- Write the final report body in Korean.
+- Keep technical identifiers such as file paths, code symbols, model names, and status values in their original form when needed.
+- If only one worker is usable, perform a reduced-confidence synthesis
+- If evidence is insufficient, explicitly state "I don't know"
+- If expected values are present in `reference-expectations.md`, list matches, gaps, and missing evidence separately
+- If `reference-expectations.md` is explicitly empty, report the absence of expected states as missing information
+- If there are no substantive differences between workers, state "No difference"
+- Write the actual analysis text instead of a meta-description
+- Do not make unfounded assertions
+- Include findings from all four categories. Do not omit "contested" or "worker-unique" findings
+- Include the convergence round history and a summary of votes by worker for each finding
+- The report writer worker does not participate in the re-verification vote. It is responsible only for drafting the final report
+
+## Artifact Persistence Checklist
+
+Persistence steps that must be performed in Phase 7:
+
+- [ ] 1. **Draft final report**: Save to `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`
+- [ ] 2. **Update team state**: Update `runs/<task-type>/state/team-state-<task-type>-<seq>.json`
+   - Final status, start/end times, and result file paths for each worker
+   - Overall run status
+- [ ] 3. **Update run manifest**: Update `runs/<task-type>/manifests/run-manifest-<task-type>-<seq>.json`
+- [ ] 4. **Update task-manifest.json**: Reflect task-level status and workflow lifecycle metadata
+   - Update `workCategory` if the run produced a confident classification
+   - Update `workflow.currentPhase`, `workflow.currentPhaseState`, `workflow.lastCompletedPhase`, and `workflow.phaseStates`
+   - Update `workflow.nextRecommendedPhase`, `workflow.awaitingApproval`, and `workflow.routingStatus`
+   - Update `workflow.lastSafeCheckpoint` to the best resume point for the current task
+- [ ] 5. **Update task-index.md**: Refresh human-readable summary
+- [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)
+- [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
+
+### Response after Persistence
+
+Provide a concise report in Korean covering the following:
+- Completion status
+- Final report path
+- Team-state path
+- Validator results
+- Resume command path
+- Remaining blockers (if any)

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

@@ -0,0 +1,231 @@
+---
+name: okstra-run
+description: Use when the user wants to start an okstra task (cross-verification run) directly from the current Claude Code session — without spawning a new claude process. Equivalent in effect to `okstra.sh --task-type ...` but driven through interactive prompts. Trigger words include "okstra run", "okstra start", "start okstra", "begin okstra task", "run okstra in this session", "okstra here".
+---
+
+# OKSTRA Run (in-session)
+
+Launch an okstra task — gather inputs interactively, render the full task bundle through the single python entrypoint, then take over as `Claude lead` in the current session.
+
+**Single authority**: this skill and `okstra.sh` both call the exact same python function `okstra_ctl.run.prepare_task_bundle()`. The skill does NOT shell out to `okstra.sh` — that would create a second orchestration path and reintroduce env-var leakage between the parent claude session and child bash.
+
+## When to Use
+
+- The user is already inside a Claude Code session and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
+- Continue an existing task (next phase) without leaving the current claude session.
+
+## When NOT to Use
+
+- User explicitly asks to spawn a new terminal / new claude — use `okstra-history` Step 4 (resume command) or instruct them to run `okstra.sh` in another terminal.
+- User wants status only — use `okstra-status`.
+- User wants past runs — use `okstra-history`.
+
+## Authority Files (disk-only — no env var caching for per-run identity)
+
+Every step reads disk afresh. The `OKSTRA_*` env vars below identify the
+**runtime installation** (stable across runs) — they are NOT per-task identity.
+
+- `~/.okstra/version` — okstra runtime version stamp
+- `<PROJECT_ROOT>/.project-docs/okstra/project.json`
+- `<PROJECT_ROOT>/.project-docs/okstra/discovery/{task-catalog,latest-task}.json`
+- `<task-root>/task-manifest.json`
+
+## 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 runtime is fresh (idempotent, cached when up-to-date)
+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
+}
+
+# 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:
+
+| Variable | Meaning |
+|---|---|
+| `$OKSTRA_WORKSPACE` | passed to python as `workspace_root` (prompts/, templates/, validators/, agents/ root) |
+| `$OKSTRA_AGENTS_DIR` | source dir of worker `*.md` (subagent definitions) |
+| `$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
+
+```bash
+python3 - <<'PY'
+import sys, json
+from okstra_project import resolve_project_root, ResolverError
+try:
+    pr = resolve_project_root(explicit_root="", cwd=".")
+except ResolverError as e:
+    print(f"FAIL\t{e}"); raise SystemExit(0)
+print(f"OK\t{pr}")
+PY
+```
+
+- If `OK`: read `<PROJECT_ROOT>/.project-docs/okstra/project.json` and extract `projectId`.
+- If `FAIL`: ask the user (`AskUserQuestion`, free text) for an absolute project-root path; rerun the resolver with `explicit_root=<their input>`.
+
+## Step 2: Choose task — existing vs new
+
+```bash
+python3 -c "
+import json, sys
+from pathlib import Path
+from okstra_project import list_project_tasks, read_latest_task
+pr = Path(sys.argv[1])
+tasks = list_project_tasks(pr)
+latest = read_latest_task(pr)
+print(json.dumps({'tasks': tasks, 'latest': latest}))
+" "$PROJECT_ROOT"
+```
+
+Use `AskUserQuestion`:
+
+- **Label**: "Which task?"
+- **Options**: each existing task with label `"<taskKey>  ·  <currentPhase or taskType>  ·  next: <nextRecommendedPhase>"`; mark the `latest` entry with `(latest)`. Final option: `"Start a brand-new task"`. Limit to 8 candidates per page; add `"More..."` if more exist.
+
+For an existing pick, read its `task-manifest.json` to capture `taskType` and `workflow.nextRecommendedPhase`.
+
+## Step 3: For new tasks — collect identity
+
+Skip if continuing existing.
+
+`AskUserQuestion` (free text, one at a time):
+
+1. `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`
+2. `"Task id (e.g. login-error-analysis, dev-9043)"` → `task_id`
+
+Validate that slugified `task_group` and `task_id` each contain at least one alphanumeric character. Re-ask if not.
+
+## Step 4: Choose task-type
+
+`AskUserQuestion` with five fixed options:
+
+| Option | Description |
+|---|---|
+| `requirements-discovery` | Classify request and route to next safe phase |
+| `error-analysis` | Evidence-based root-cause analysis (no code changes) |
+| `implementation-planning` | Plan options + request user approval |
+| `implementation` | Execute approved plan (requires `--approved-plan`) |
+| `final-verification` | Acceptance + residual-risk review |
+
+For existing tasks, present `nextRecommendedPhase` as the first option (recommended default).
+
+If `implementation` chosen, ask one more `AskUserQuestion`:
+- `"Path to the approved final-report.md (must contain APPROVED marker)"` — the underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`.
+
+## Step 5: Brief path
+
+- New task: `AskUserQuestion` (free text) `"Path to the task brief markdown (relative to project root)"`. Verify file exists; re-ask on failure.
+- Existing task: default to the manifest's `taskBriefPath`. Show it; ask whether to keep or change.
+
+## Step 6 (optional): Directive / workers / models / related / clarification
+
+Single `AskUserQuestion` first: `"Use default workers and models, or customize?"`
+
+- `Use defaults` → all overrides remain empty.
+- `Customize` → ask each in turn (free text, blank = use default):
+  - workers CSV (subset of `claude,codex,gemini,report-writer`)
+  - `lead-model`, `claude-model`, `codex-model`, `gemini-model`, `report-writer-model`
+  - `directive`
+  - `related-tasks` CSV
+  - `clarification-response` path (relevant for follow-up `requirements-discovery` / `error-analysis` runs)
+
+## Step 7: Call `prepare_task_bundle` directly
+
+This is the single line that materializes the entire task bundle. **Pass `render_only=True`** — the current claude session itself takes over as lead; we do not exec a new claude.
+
+```bash
+python3 - <<PY
+import os
+from pathlib import Path
+from okstra_ctl.run import PrepareInputs, prepare_task_bundle
+from okstra_ctl.path_resolve import resolve_user_file
+
+project_root = Path("<project-root>")
+brief_abs = resolve_user_file("<brief-path-from-user>", project_root)
+clarification_abs = resolve_user_file("<clarification-or-empty>", project_root) if "<clarification-or-empty>" else None
+
+out = prepare_task_bundle(PrepareInputs(
+    workspace_root=Path(os.environ["OKSTRA_WORKSPACE"]),
+    project_root=project_root,
+    project_id="<project-id>",
+    task_group="<task-group>",
+    task_id="<task-id>",
+    task_type="<task-type>",
+    brief_path=brief_abs,
+    directive="<directive or empty>",
+    workers_override="<workers csv or empty>",
+    lead_model="...", claude_model="...", codex_model="...",
+    gemini_model="...", report_writer_model="...",
+    related_tasks_raw="...",
+    approved_plan_path="<approved-plan-or-empty>",
+    clarification_response_path=str(clarification_abs) if clarification_abs else "",
+    render_only=True,
+))
+
+# Print key paths so the next step can read them.
+ctx = out.ctx
+print("TASK_ROOT", ctx["TASK_ROOT"])
+print("INSTRUCTION_SET_DIR", ctx["INSTRUCTION_SET_DIR"])
+print("LEAD_PROMPT", str(Path(ctx["INSTRUCTION_SET_DIR"]) / "claude-execution-prompt.md"))
+PY
+```
+
+The python function is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
+
+## Step 8: Take over as Claude lead
+
+Read these files (do not paraphrase) and enter `Claude lead` mode:
+
+1. `<INSTRUCTION_SET_DIR>/claude-execution-prompt.md` — the lead prompt
+2. `<INSTRUCTION_SET_DIR>/analysis-profile.md` — per-task-type allowed outputs / forbidden actions
+3. `<INSTRUCTION_SET_DIR>/analysis-material.md` — task brief + directive
+4. `<INSTRUCTION_SET_DIR>/reference-expectations.md`
+5. `<INSTRUCTION_SET_DIR>/final-report-template.md`
+
+Then proceed through the phases exactly as the lead prompt directs (Phase 1 context → Phase 2+ worker dispatch → final synthesis → final report).
+
+Inform the user with one short line:
+> Took over as Claude lead for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
+
+## Concurrency
+
+- `prepare_task_bundle` serializes per-task via `~/.okstra/.locks/<task-key>.lock`. Concurrent skill invocations on the same task wait; different tasks proceed in parallel.
+- The skill must NOT call `okstra.sh` or any other bash entrypoint that would re-implement the orchestration. The python function is the single authority.
+- No env var carries identity across steps — every step re-reads disk authority.
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `okstra runtime missing: ...` | First run on this machine, or stale install | `npx okstra@latest install` once, retry. |
+| `OKSTRA_PYTHONPATH unbound` / `ModuleNotFoundError: okstra_project` | Step 0 was skipped or env vars dropped | Re-run Step 0; never invoke python without exporting `PYTHONPATH=$OKSTRA_PYTHONPATH`. |
+| `task root not found for <key>` | catalog entry stale or task-key typo | Re-run Step 2; show available keys from `list_project_tasks` |
+| `PROJECT_ROOT 를 해석할 수 없습니다` | cwd outside okstra project, no git toplevel | Ask user for absolute path |
+| `approved plan has no recognised user-approval marker` | `implementation` without proper approval | Ask user to add `APPROVED` to the plan, or pick a different task-type |
+| `task brief not found` | brief-path doesn't resolve relative to cwd or project-root | Re-ask Step 5 |
+| record_start failed | `~/.okstra` lock or disk issue | Non-fatal — bundle is valid; warn and continue |
+
+## Output Rules
+
+- Echo each `AskUserQuestion` outcome on one short line so user sees what was captured.
+- Never invent identity; re-ask if blank.
+- After Step 8, begin the lead workflow without re-summarizing the skill itself.