okstra 0.2.0 → 0.3.0

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "okstra",
-  "version": "0.2.0",
-  "description": "Runtime installer and path resolver for okstra cross-verification skills",
+  "version": "0.3.0",
+  "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Devonshin/okstra.git",
-    "directory": "packages/okstra"
+    "url": "git+https://github.com/Devonshin/okstra.git"
   },
   "type": "module",
   "bin": {
@@ -23,8 +22,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepack": "node scripts/build.mjs",
-    "test": "node --test test/"
+    "build": "node tools/build.mjs",
+    "prepack": "node tools/build.mjs"
   }
 }

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.2.0",
-  "builtAt": "2026-05-11T14:50:08.756Z",
+  "package": "0.3.0",
+  "builtAt": "2026-05-11T15:55:55.785Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/skills/okstra-context-loader/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: okstra-context-loader
+description: Use when okstra Phase 1 starts, or when the user asks for an okstra task bundle path, task-manifest location, or the current/latest okstra run artifacts.
+user-invocable: false
+---
+
+# OKSTRA Context Loader
+
+## When to Use
+
+- When starting okstra Skill Phase 1 (Task-bundle intake)
+- When the user needs to know the okstra task bundle path
+- When you need to derive all artifact paths based on `task-manifest.json`
+
+## Step 1: Locating the Task Bundle
+
+### Default Location Rules
+
+- AI documentation root: `.project-docs/`
+- Project-level latest-task pointer: `.project-docs/okstra/discovery/latest-task.json`
+- Project-level task catalog: `.project-docs/okstra/discovery/task-catalog.json`
+- okstra task root: `.project-docs/okstra/tasks/`
+- Task path pattern: `.project-docs/okstra/tasks/<task-group>/<task-id>/`
+
+### Task Identification
+1. If the user specifies the `task-manifest.json` path or the task root path, that path is used.
+2. If the user specifies only the task key, the expected task root is calculated by converting the `task-group` and `task-id` to lowercase and applying the slug rule (`[^a-z0-9]+` → `-`), and the corresponding `task-manifest.json` is opened.
+3. If the user attempts to find a task based on `task-group` + `task-id` or `task-id`, `.project-docs/okstra/discovery/task-catalog.json` is read to find candidates.
+4. If multiple candidates are found based on `task-id` alone, the situation is ambiguous, so `task-group` or the full `taskKey` is required.
+5. If the user has not provided an explicit task key/path, first read `.project-docs/okstra/discovery/latest-task.json` using the current-task convenience pointer.
+6. Even if the latest-task pointer is missing or corrupted, but the task catalog exists, first check the list of prepared task bundles based on the catalog. Do not use the legacy `CLAUDE.md`, project guide, or task scan fallback.
+
+## Step 2: Read task-manifest.json
+
+task-manifest.json is the canonical metadata source. The following fields must be extracted from this file:
+
+| Field | Description |
+|------|------|
+| `taskKey` | `<project-id>:<task-group>:<task-id>` |
+| `projectId` | Project ID |
+| `taskGroup` | Task group |
+| `taskId` | Task ID |
+| `taskType` | Analysis type (requirements-discovery, error-analysis, final-verification, implementation-planning) |
+| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown |
+| `recommendedWorkers` | List of selected workers |
+| `currentStatus` | Current task status |
+| `workflow.phaseSequence` | Ordered lifecycle phases for the task |
+| `workflow.currentPhase` | Current lifecycle phase |
+| `workflow.currentPhaseState` | Current lifecycle phase state |
+| `workflow.phaseStates` | Phase-by-phase lifecycle state map |
+| `workflow.lastCompletedPhase` | Last completed lifecycle phase |
+| `workflow.nextRecommendedPhase` | Next recommended lifecycle phase |
+| `workflow.awaitingApproval` | Approval wait marker |
+| `workflow.routingStatus` | Routing decision status |
+| `workflow.lastSafeCheckpoint` | Safe resume checkpoint metadata |
+| `instructionSetPath` | Instruction-set path |
+| `referenceExpectationsPath` | config/deployment expectation artifact path |
+| `latestRunPath` | latest run path |
+| `latestRunStatus` | latest run status |
+| `latestRunPromptsPath` | latest run prompt directory path |
+| `latestReportPath` | latest report path |
+| `latestResumeCommandPath` | resume helper path |
+| `historyTimelinePath` | timeline path |
+| `resultContract` | team contract and expected artifact metadata |
+| `resultContract.requiredWorkerRoles[*].promptPath` | worker prompt history path by role |
+| `convergence` | convergence loop settings (enabled, maxRounds, verificationMode). `maxRounds` 기본값은 phase-aware: `requirements-discovery`는 `1`, 그 외는 `2`. 자세한 내용은 [okstra-convergence](../okstra-convergence/SKILL.md) 참고 |
+
+## Step 3: Directory Structure Rules
+
+After identifying the task root in `task-manifest.json`, derive all paths according to the following rules:
+
+```
+<task-root>/
+├── task-manifest.json          (canonical metadata)
+├── task-index.md               (human-readable summary, non-canonical)
+├── instruction-set/
+│   ├── analysis-profile.md     (analysis guide by task type)
+│   ├── analysis-material.md    (analysis materials)
+│   ├── reference-expectations.md (config/deployment expected values)
+│   ├── task-brief.md          (task brief)
+│   └── final-report-template.md (Final Report Template)
+├── runs/
+│   └── <task-type>/            (Run scope isolated per task-type, e.g. error-analysis)
+│       ├── manifests/          (run-manifest-<task-type>-<seq>.json)
+│       ├── state/              (team-state-<task-type>-<seq>.json, convergence-<task-type>-<seq>.json)
+│       ├── prompts/            (claude-execution-prompt-<task-type>-<seq>.md and worker prompt history files)
+│       ├── reports/            (final-report-<task-type>-<seq>.md)
+│       ├── status/             (final-<task-type>-<seq>.status)
+│       ├── sessions/           (claude-resume-<task-type>-<seq>.sh)
+│       ├── logs/               (errors-<task-type>-<seq>.jsonl, optional)
+│       └── worker-results/
+│           ├── claude-worker-<task-type>-<seq>.md
+│           ├── codex-worker-<task-type>-<seq>.md
+│           ├── gemini-worker-<task-type>-<seq>.md
+│           └── report-writer-worker-<task-type>-<seq>.md
+└── history/
+    └── timeline.json
+```
+
+### File Naming Conventions
+
+- Run-level artifact files use the `-<task-type>-<seq>` suffix, where `<seq>` is a 3-digit zero-padded sequence number (`001`, `002`, …) scanned **per-category directory** (`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`). Re-runs of the same task-type never overwrite each other's artifacts.
+- Because each category directory has its own counter, the `<seq>` for `manifests/` may differ from the `<seq>` for `reports/` if a previous run only wrote some categories. The shared run identifier across categories is the manifest `runDateTimeSegment` field (still ISO timestamp), not a filename infix.
+- Worker result files use the same `-<task-type>-<seq>` filename suffix as other run-level artifacts (counter scoped to `worker-results/`).
+- Worker prompt history files use role + suffix names such as `claude-worker-prompt-<task-type>-<seq>.md`.
+- A single `runs/<task-type>/` directory is reused for every run of that task type; the per-run separation comes entirely from the per-category sequence-number infix inside each typed subdirectory.
+
+### Finding the Latest Run
+
+1. If a `latest-task` pointer exists, prioritize the path to the latest run, latest run manifest, or latest team-state recorded there.
+2. If entering via an explicit task key/path, locate the current run based on the latest run metadata in `task-manifest.json`.
+3. Only if necessary, directly check `manifests/`, `state/`, `prompts/`, `reports/`, and `sessions/` within the relevant run directory.
+
+## Step 4: Instruction Set Reading Order
+
+After verifying `task-manifest.json`, read the instruction set in the following order:
+
+1. `instruction-set/analysis-profile.md` (analysis guide by task type)
+2. `instruction-set/analysis-material.md` (analysis materials, if available)
+3. `instruction-set/reference-expectations.md` (config/deployment expected values)
+4. `instruction-set/task-brief.md` (task brief)
+5. `instruction-set/final-report-template.md` (report template)
+
+## Step 5: Read Run Manifest and Team State
+
+1. Current run manifest: The latest run manifest pointed to by the discovery pointer or task-manifest
+2. Current team state: The latest team-state pointed to by the discovery pointer or task-manifest
+3. Extract the worker prompt directory path and per-worker prompt history paths from the current run manifest and team-state
+4. If an existing run report is available, use it solely as historical context.
+
+## Output
+
+Information to be obtained after executing this skill:
+- task key, task type, work category, workflow lifecycle snapshot, analysis profile
+- List of selected workers and model assignments by role
+- Absolute/relative paths of all artifacts (including latest-task pointer, task catalog, prompt directory, per-worker prompt history files, resume command, and timeline)
+- Reference list of config files/deployment manifests and task-level expected values
+- Current run status and presence of existing worker results
+- Current run prompt history contract for attempted workers
+- Resume command path: `runs/<task-type>/sessions/claude-resume-<task-type>-<seq>.sh`

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

@@ -0,0 +1,289 @@
+---
+name: okstra-convergence
+description: Use when okstra Phase 5.5 needs iterative cross-verification between workers, or when worker findings must be classified by consensus level before final synthesis.
+user-invocable: false
+---
+
+# OKSTRA Convergence
+
+## When to Use
+
+- When the okstra skill Phase 5.5 (convergence loop) begins
+- Immediately after all workers have completed Phases 4 and 5
+- When findings need to be systematically classified by consensus level
+
+## Configuration
+
+Configure this in the `convergence` block of `task-manifest.json`. If the block is missing, the default values are used.
+
+| Setting | Default | Description |
+|------|--------|------|
+| `enabled` | `true` | If `false`, skip the convergence loop and use the existing consensus/divergence method |
+| `maxRounds` | phase-aware: `1` for `requirements-discovery`, `2` otherwise (range 1–3) | Maximum number of re-verification rounds. Discovery's routing/missing-input outputs gain little from a second round; other phases (especially `error-analysis`) keep `2`. Lead resolves the effective value when the manifest omits the key and records it in `config.maxRounds` of the convergence state artifact. |
+| `verificationMode` | `"lightweight"` | `"lightweight"` or `"full-reanalysis"` |
+
+## Finding Category
+
+| Category | Definition | Included in Report |
+|------|------|------------|
+| `full-consensus` | All participating workers agree | Required |
+| `partial-consensus` | Majority of workers agree; dissenting opinions are recorded | Required |
+| `contested` | No consensus reached even after max rounds; each worker's position is recorded | Required |
+| `worker-unique` | Only the discoverer confirms; others oppose or remain unverified | Required |
+
+## Convergence Algorithm
+
+### Round 0: Parse worker results
+
+Read the worker result files generated in Phase 4/5 and extract individual findings.
+
+1. In the "Findings" section of each worker's results, identify individual items by number (F-001, F-002, ...).
+2. For each finding, record the summary, evidence (file path, line number, basis), and the worker who identified it.
+3. Claude Lead groups findings based on semantic similarity:
+  - When 2 or more workers report the same or similar findings → immediately reach `full consensus`
+  - Only one worker confirms → `unique`, enter the verification queue
+4. When grouping is ambiguous, prefer splitting over merging (avoid over-merging).
+
+### Round 1-N: Re-verification Loop
+
+```
+FOR round = 1 to convergence.maxRounds:
+  IF the verification queue is empty:
+    BREAK (early convergence)
+
+  FOR each worker W (excluding the report writer):
+    List of findings W must verify = items in the verification queue for which W is not the discoverer
+    IF the list is empty:
+      SKIP
+    Send a re-verification request to W (batch: spawn once per worker)
+    Collect responses: AGREE / DISAGREE / SUPPLEMENT for each finding
+
+  FOR each finding F in the verification queue:
+    Vote aggregation:
+      - All AGREE or SUPPLEMENT → full consensus
+      - Majority AGREE or SUPPLEMENT → partial consensus
+      - All DISAGREE → worker-unique
+      - Mixed results → Carry over to next round (or marked as contested if this is the final round)
+
+  Update convergence state (record current round results)
+```
+
+### Convergence Test
+
+- If the validation queue is empty → Convergence complete (`converged`)
+- Upon reaching the maximum number of rounds → Apply final classification to remaining unresolved findings:
+  - Majority agreement → `partial-consensus`
+  - Otherwise → `contested`
+
+## Verification Mode
+
+### Lightweight (Default)
+
+Decisions are made based solely on the findings and evidence presented by other reviewers. The original code or data is not reanalyzed.
+
+Advantages: Fast and cost-effective
+Disadvantages: Accuracy decreases if evidence is insufficient
+
+### Full Re-analysis (opt-in)
+
+Use the findings as a guide, but reanalyze the original code/data yourself.
+
+Advantages: High accuracy
+Disadvantages: 2–3 times the cost, increased time
+
+## Re-verification Agent Dispatch
+
+### Sponsorship Optimization
+
+Processing is performed by spawning each worker once per round. All findings to be verified by that worker are included in a single prompt.
+
+```text
+Agent(
+  description: "Re-verify findings for <task-key> round <N>",
+  prompt: "<re-verification prompt with findings batch>",
+  name: "<role-slug>-reverify-r<N>",
+  subagent_type: "<same as initial execution>",
+  team_name: "okstra-<task-key>",
+  model: "<same as initial execution>",
+  mode: "auto"
+)
+```
+
+- Agent Teams mode: Spawn within an existing team
+- Fallback mode: Spawn with `run_in_background: true` and no `team_name`
+
+### Required reverify-prompt anchor headers (BLOCKING)
+
+Every reverify prompt MUST start with the same 5 anchor headers used in the initial Phase 4 dispatch — in this exact order, before any other content:
+
+```
+**Project Root:** <absolute-path>
+**Prompt History Path:** runs/<task-type>/prompts/<role-slug>-reverify-r<N>-<task-type>-<seq>.md
+**Result Path:** runs/<task-type>/worker-results/<role-slug>-reverify-r<N>-<task-type>-<seq>.md
+Assigned worker prompt history path: <Project Root>/<Prompt History Path>
+**Model:** <role>, <modelExecutionValue>
+```
+
+`<modelExecutionValue>` MUST be resolved from one of these canonical sources, in priority order:
+
+1. `task-manifest.json` → `resultContract.requiredWorkerRoles[].modelExecutionValue` for the receiving role
+2. `team-state-<task-type>-<seq>.json` → `workers[].usage.cliModel` for that role (initial run's actual execution value)
+3. The `**Model:**` line of the initial Phase 4 prompt for that role (read from its persisted prompt-history file)
+
+If none of the three is available, **abort the reverify dispatch for that role** and record a `contract-violation` event via `okstra-error-log.py append-observed`. Do NOT guess, do NOT fall back to training-data defaults — for codex this would silently produce `o4-mini` instead of the assigned `gpt-5.5`-class model, which is a real bug class observed in production.
+
+For Codex/Gemini wrapper subagents, the `**Model:** <role>, <modelExecutionValue>` line is what their wrapper extracts to pass into the underlying CLI's `--model` flag. Omitting it forces the wrapper to fall back to its own training-data knowledge of the CLI's historical default.
+
+### Reverify prompt: required-reading suppression (BLOCKING)
+
+Reverify prompts MUST NOT inject the Phase 2 `[Required reading]` clause:
+
+- **Lightweight mode**: the clause directly contradicts the "Do NOT re-analyze the original source materials" instruction below. Including it forces workers to re-read the entire instruction-set per round per worker (3 workers × 2 rounds × 5+ files in the worst case) for no quality gain.
+- **Full-reanalysis mode**: workers DO need to re-read source materials, but only the analysis-worker file list (no `final-report-template.md`). If lead chooses to inject a reading clause here, it MUST mirror the audience-scoped enumeration in [okstra/SKILL.md](../../SKILL.md) Phase 2 (no template).
+
+This is the single largest avoidable cost in `requirements-discovery` and `error-analysis` runs. Treat as BLOCKING.
+
+### Lightweight Re-verification Prompt
+
+```
+You are <worker-role> performing re-verification for <task-key> (round <N>).
+
+## Instructions
+
+Review the following findings discovered by other workers.
+For EACH finding, respond with exactly one verdict:
+
+- **AGREE**: The finding is valid based on the evidence presented
+- **DISAGREE**: The finding is incorrect or unsupported (explain briefly why)
+- **SUPPLEMENT**: The finding is valid AND you have additional supporting evidence or context
+
+Do NOT re-analyze the original source materials. Judge based on the evidence provided.
+
+## Findings to verify
+
+### F-001: <one-line summary>
+**Origin**: <worker role>
+**Evidence**: <file paths, line numbers, reasoning from origin worker>
+
+### F-002: <one-line summary>
+**Origin**: <worker role>
+**Evidence**: <...>
+
+## Response format
+
+For each finding, respond as:
+
+### F-001
+**Verdict**: AGREE | DISAGREE | SUPPLEMENT
+**Explanation**: <2-3 sentences>
+
+### F-002
+**Verdict**: ...
+```
+
+### Full Re-analysis Re-verification Prompt
+
+```
+You are <worker-role> performing deep re-verification for <task-key> (round <N>).
+
+## Instructions
+
+Independently verify the following findings by examining the original materials.
+Use each finding as a starting point, NOT as a confirmed conclusion.
+
+## Task bundle paths
+- Instruction set: <instruction-set path>
+- Task brief: <task-brief path>
+- Analysis material: <analysis-material path>
+- Reference expectations: <reference-expectations path>
+
+## Findings to verify
+
+### F-001: <one-line summary>
+**Origin**: <worker role>
+**Original evidence**: <file paths, line numbers>
+
+### F-002: <one-line summary>
+**Origin**: <worker role>
+**Original evidence**: <...>
+
+## Response format
+
+For each finding:
+
+### F-001
+**Verdict**: AGREE | DISAGREE | SUPPLEMENT
+**Your evidence**: <your independent evidence trail with file paths and line numbers>
+**Explanation**: <detailed analysis>
+```
+
+## Convergence State Artifact
+
+Save it to `runs/<task-type>/state/convergence-<task-type>-<seq>.json`.
+
+```json
+{
+  "schemaVersion": "1.0",
+  "taskKey": "<task-key>",
+  "config": {
+    "enabled": true,
+    "maxRounds": 2,
+    "verificationMode": "lightweight"
+  },
+  "findings": [
+    {
+      "findingId": "F-001",
+      "summary": "<one-line summary>",
+      "category": "<bug|risk|missing|observation|...>",
+      "originWorker": "<worker-id>",
+      "originEvidence": "<evidence text>",
+      "classification": "full-consensus",
+      "rounds": [
+        {
+          "round": 1,
+          "votes": {
+            "<worker-id>": {
+              "verdict": "agree",
+              "explanation": "<brief>"
+            }
+          }
+        }
+      ],
+      "consensusWorkers": ["worker-a", "worker-b", "worker-c"],
+      "dissentingWorkers": []
+    }
+  ],
+  "roundHistory": [
+    {
+      "round": 1,
+      "verificationsRequested": 4,
+      "verificationsCompleted": 4,
+      "newConsensus": 2,
+      "remainingInQueue": 1,
+      "earlyExit": false
+    }
+  ],
+  "finalState": "converged",
+  "totalRounds": 1,
+  "summary": {
+    "fullConsensus": 5,
+    "partialConsensus": 1,
+    "contested": 0,
+    "workerUnique": 1
+  }
+}
+```
+
+## Output
+
+Information to be passed to Phase 6 after executing this skill:
+
+- Final classification of all findings (4-category)
+- Round history and votes per worker for each finding
+- Path to the convergence state artifact
+- Convergence summary (count per category)
+- Whether early convergence occurred and the total number of rounds
+
+## Convergence Disabled
+
+If `convergence.enabled: false`, this skill is skipped. Phase 6 operates using the existing consensus/divergence method.

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

@@ -0,0 +1,118 @@
+---
+name: okstra-history
+description: Use when the user asks to list past okstra runs, check execution history, review previous cross-verification results, or wants to re-run a past okstra task. Trigger words include "okstra history", "past runs", "run history", "re-run", "list tasks".
+---
+
+# OKSTRA History
+
+## When to Use
+
+- When a user views the history of past okstra executions
+- When re-running or resuming a previous execution
+- When checking the execution status of each task
+
+## Step 1: Read the Task Catalog
+
+1. Read `.project-docs/okstra/discovery/task-catalog.json`.
+2. Sort the `tasks` array in reverse order by `updatedAt` and display it.
+3. Extract the following fields from each task:
+
+| Field | Description |
+|------|------|
+| `taskKey` | Task identifier (`<project-id>:<task-group>:<task-id>`) |
+| `taskType` | Analysis type |
+| `currentStatus` | Task-level status |
+| `latestRunStatus` | Latest run status |
+| `updatedAt` | Last update time |
+| `latestReportPath` | Latest report path |
+| `latestResumeCommandPath` | Resume command path |
+
+4. Output format:
+
+```markdown
+## okstra Task History — <project-id>
+
+| # | Task Key | Type | Status | Last Run | Report |
+|---|----------|------|--------|----------|--------|
+| 1 | proj:group:id | error-analysis | completed | 2026-04-05 22:59 | .project-docs/.../final-report-*.md |
+| 2 | proj:group:id2 | final-verification | prepared | 2026-04-04 15:30 | -- |
+```
+
+5. If `task-catalog.json` is missing, it responds with "There is no okstra execution history. Please run okstra.sh first."
+
+## Step 2: Run History by Task
+
+When a user selects a specific task or requests detailed history:
+
+1. Retrieve the `historyTimelinePath` path for the task from the task catalog.
+2. Read the `runs` array from `timeline.json`.
+3. Fields to extract from each run:
+
+| Field | Description |
+|------|------|
+| `runTimestamp` | Execution time (ISO 8601) |
+| `runDateTimeSegment` | YYYY-MM-DD_HH-MM-SS |
+| `taskType` | `--task-type` argument value |
+| `status` | Run status |
+| `reportPath` | Report Path |
+| `resumeCommandPath` | resume Command path |
+| `relatedTasks` | List of related tasks |
+
+4. Output format:
+
+```markdown
+## Runs for <task-key>
+
+| # | Timestamp | Type | Status | Report |
+|---|-----------|------|--------|--------|
+| 1 | 2026-04-05 22:59 | error-analysis | completed | .../final-report-*.md |
+| 2 | 2026-04-04 15:30 | error-analysis | error | -- |
+```
+
+## Step 3: Create a re-execution command
+
+To re-run a specific run:
+
+1. Read the run-manifest JSON from the `runManifestPath` of that run.
+2. Extract the required arguments:
+   - `projectId` → `--project-id`
+   - `taskGroup` → `--task-group`
+   - `taskId` → `--task-id`
+   - `taskType` → `--task-type`
+   - `taskBriefPath` → `--task-brief`
+3. Extract the optional arguments:
+   - `recommendedWorkers` → `--workers` (comma-separated)
+   - `relatedTasks` → `--related-tasks` (if present)
+   - model overrides → `--claude-model`, `--codex-model`, `--gemini-model` (if different from default)
+4. Display the assembled command:
+
+```bash
+okstra.sh \
+  --project-id <project-id> \
+  --task-group <task-group> \
+  --task-id <task-id> \
+  --task-type <task-type> \
+  --task-brief <brief-path> \
+  --workers <worker-list>
+```
+
+5. Once the user confirms, execute it using the Bash tool.
+
+## Step 4: Resume
+
+To resume a paused session:
+
+1. Check `latestResumeCommandPath` in the task catalog or timeline.
+2. Verify that the resume script file actually exists.
+3. If it exists, display the execution command:
+   ```bash
+   bash <resume-command-path>
+   ```
+4. If it does not exist, display the message: "No resume script found. Please run it again."
+
+## Output Rules
+
+- Display concisely in a table format
+- Dates in `YYYY-MM-DD HH:MM` format
+- Display status as-is (`completed`, `prepared`, `error`, `not-run`, etc.)
+- Display `--` if no report is available

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

@@ -0,0 +1,68 @@
+---
+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 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>`
+```
+
+이후 사용자 요청에 따라 보고서를 읽고 후속 작업을 진행한다.