okstra 0.36.0 → 0.36.1

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

@@ -1,172 +0,0 @@
----
-name: okstra-time-summary
-description: Use when the user asks how long an okstra task took, time spent per task type, per-worker elapsed time, or for a duration/runtime breakdown of a specific task-id. Trigger words include "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석".
-user-invocable: false
----
-
-# OKSTRA Time Summary
-
-Aggregate elapsed work time for a given task, grouped by **task type** and broken down by **worker** (lead, claude, codex, gemini, report-writer).
-
-## When to Use
-
-- The user provides a `task-id` (or `task-key`) and asks how long the task took.
-- The user wants to see time spent per phase / task type for a single task.
-- The user wants a per-worker time breakdown for a task's runs.
-
-## Data Sources
-
-Two sources, both already collected by `okstra`:
-
-1. `.project-docs/okstra/tasks/<task-group>/<task-id>/history/timeline.json`
-   — lists every run with `runTimestamp`, `taskType`, `status`, `teamStatePath`, and `taskRootPath`. Both path fields may be either project-root-relative or task-root-relative depending on which version of `render.py` wrote the manifest.
-2. Each run's `.../runs/<task-type>/state/team-state-<suffix>.json`
-   — populated by `scripts/okstra-token-usage.py` at Phase 7. Contains:
-   - `leadUsage.{startedAt, endedAt, durationMs}`
-   - `workers[].{workerId, agent, usage.{startedAt, endedAt, durationMs}}`
-
-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
-
-Run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
-
-1. `okstra ensure-installed`
-   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
-
-2. `okstra check-project --json`
-   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
-
-   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
-   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.project-docs/okstra/discovery/task-catalog.json`.
-
-Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
-
-## 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.
-2. Otherwise read `.project-docs/okstra/discovery/task-catalog.json` and find the entry whose `taskId` matches.
-3. If multiple entries match, list candidates (`taskKey`, `taskType`, `updatedAt`) and ask the user to pick.
-4. From the chosen entry, read `historyTimelinePath`.
-
-If `task-catalog.json` is missing, respond: "No okstra history found. Run `scripts/okstra.sh` first."
-
-## Step 2: Walk runs and collect durations
-
-For each entry in `timeline.json`'s `runs` array:
-
-1. Resolve the `team-state` file using a two-step lookup:
-   a. First try `<projectRoot>/<teamStatePath>`.
-   b. If that file does not exist, fall back to `<projectRoot>/<taskRootPath>/<teamStatePath>` (the manifest's `taskRootPath` field is the task-root relative to project root; `teamStatePath` written by `render.py` is task-root-relative in many runs).
-   Either path satisfies the lookup. If neither resolves to an existing file, treat the run as `unavailable`.
-2. Extract:
-   - `taskType` from the timeline entry (authoritative).
-   - `leadUsage.durationMs` and `leadUsage.{startedAt,endedAt}`.
-   - For each `worker` in `workers[]`: `workerId`, `agent`, `usage.durationMs`.
-   Read defensively. `usage` (and `leadUsage`) may be:
-   - a normal `usage_block` with `durationMs >= 0`,
-   - a `na_block` with `{"source": "unavailable", "durationMs": 0, "note": ...}` when Phase 7 collection failed,
-   - missing entirely (older team-state files), or `None`.
-   Always normalize via `(block or {}).get("durationMs", 0) or 0`, and treat a `source == "unavailable"` block as zero contribution.
-3. If the team-state file is missing, or every `durationMs` for the run is `0`/absent (i.e. `leadUsage` and every `workers[].usage` are zero or unavailable), record the run under `unavailable` with its `runTimestamp` and `taskType`.
-
-## Step 3: Aggregate
-
-Build two tables:
-
-### A. Per task-type summary
-
-For each distinct `taskType` across runs:
-
-| Column | Computation |
-|--------|-------------|
-| `Runs` | count of runs of that task type that contributed any duration |
-| `CPU sum` | sum of (lead + all workers) across those runs — see note below |
-| `Lead` | sum of `leadUsage.durationMs` |
-| `Workers` | sum of all `workers[].usage.durationMs` |
-
-Add a final `Grand total` row.
-
-**Note on `CPU sum` vs wall-clock**: workers run as children of the lead session, so the lead's `durationMs` window OVERLAPS its workers' windows. `CPU sum = Lead + Workers` is therefore an additive CPU-style sum, not the wall-clock elapsed time the user actually waited.
-
-Worked example for one run with three concurrent workers:
-
-```
-lead       [================================]  durationMs = 1800000 (30:00)
-claude       [============]                     durationMs =  720000 (12:00)
-codex        [==============]                   durationMs =  840000 (14:00)
-gemini       [========]                         durationMs =  480000 (08:00)
-```
-
-- `CPU sum` for the run = `1800000 + 720000 + 840000 + 480000` = `3840000` (`01:04:00`)
-- Wall-clock for the run = `max(endedAt) − min(startedAt)` ≈ `30:00`
-
-Always report `CPU sum` in the by-task-type table. If the user explicitly asks for wall-clock, compute it per run as `max(leadUsage.endedAt, max(workers[].usage.endedAt)) − min(leadUsage.startedAt, min(workers[].usage.startedAt))` and surface it separately — never silently substitute it for `CPU sum`.
-
-### B. Per worker breakdown (per task type)
-
-For each task type, list one row per `workerId` actually present, plus `lead`. Aggregate `durationMs` across all runs of that task type.
-
-| Worker | Runs | Total | Avg/run |
-|--------|------|-------|---------|
-
-- `Runs` denominator = number of runs of this task type in which this worker recorded a **nonzero** `durationMs`. A run where the worker's block was `na_block`, missing, or `0` does NOT count.
-- If `Runs == 0` for a worker, **omit the row entirely** rather than dividing by zero.
-- `Avg/run = Total / Runs` (integer ms, then format to `HH:MM:SS`).
-
-Use the `workerId` from team-state. The valid worker enum is `lead, claude, codex, gemini, report-writer`.
-
-Display rule for `workerId` vs `agent`:
-- If every run of this task type used `agent == workerId` for this row, display the bare `workerId` (e.g. `claude`).
-- If `agent` differs from `workerId` (e.g. a `claude` worker slot ran with `agent == "sonnet-eval"`), display `workerId (agent)` — and if multiple distinct agents were used across runs, comma-join them: `claude (sonnet-eval, opus-eval)`.
-
-Never write `claude (claude)` — the parenthesized agent is shown only when it adds information.
-
-### Timestamp parsing
-
-When you need `startedAt` / `endedAt` (e.g. for wall-clock or chronological sort within a task type), normalize the ISO-8601 string before comparing: replace a trailing `Z` with `+00:00`, accept explicit offsets as-is, and parse via `datetime.fromisoformat(s.replace("Z", "+00:00"))`. Strings without an offset are assumed UTC. Mixed-form comparisons must be done as `datetime` objects, never as raw strings.
-
-## Step 4: Format output
-
-- Convert `durationMs` to `HH:MM:SS` (zero-pad). Example: `7384000ms` → `02:03:04`.
-- Sort task types by their order of first appearance in the timeline (chronological, not alphabetical).
-- If any runs were `unavailable`, append a final note listing them with reason (`team-state missing`, `Phase 7 not reached`, etc.).
-
-### Output template
-
-```markdown
-## Time summary — <task-key>
-
-### By task type
-
-| Task type              | Runs | CPU sum   | Lead     | Workers  |
-|------------------------|------|-----------|----------|----------|
-| requirements-discovery | 2    | 00:33:12  | 00:12:08 | 00:21:04 |
-| error-analysis         | 1    | 00:18:45  | 00:08:11 | 00:10:34 |
-| implementation         | 3    | 02:11:09  | 00:45:30 | 01:25:39 |
-| **Grand total**        | 6    | **03:03:06** | 01:05:49 | 01:57:17 |
-
-`CPU sum` adds the lead window to each worker window even though they overlap; it is not a wall-clock total.
-
-### Per worker — requirements-discovery
-
-| Worker         | Runs | Total    | Avg/run  |
-|----------------|------|----------|----------|
-| lead           | 2    | 00:12:08 | 00:06:04 |
-| claude         | 2    | 00:09:12 | 00:04:36 |
-| codex          | 2    | 00:07:40 | 00:03:50 |
-| gemini         | 2    | 00:03:12 | 00:01:36 |
-| report-writer  | 2    | 00:01:00 | 00:00:30 |
-
-### Per worker — error-analysis
-...
-
-> Unavailable: 1 run (implementation / 2026-04-30_03-03-48) — team-state has no durationMs (Phase 7 not reached)
-```
-
-## Output Rules
-
-- Always render durations as `HH:MM:SS`; never raw milliseconds.
-- Never invent or estimate `durationMs`. Missing → `--`.
-- Never sum across `unavailable` runs into the totals — those are reported only in the trailing note.
-- Show the resolved `<task-key>` in the heading so the user can confirm disambiguation.