okstra 0.1.0 → 0.3.0

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

@@ -0,0 +1,119 @@
+---
+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", "얼마나 걸렸", "시간 분석".
+---
+
+# OKSTRA Time Summary
+
+Aggregate elapsed work time for a given task, grouped by **task type** and broken down by **worker** (lead, intake, claude-worker, codex-worker, gemini-worker, 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`.
+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 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. Read the `team-state` file at `teamStatePath` (relative to the project root).
+2. Extract:
+   - `taskType` from the timeline entry (authoritative).
+   - `leadUsage.durationMs` and `leadUsage.{startedAt,endedAt}`.
+   - For each `worker` in `workers[]`: `workerId`, `agent`, `usage.durationMs`.
+3. If the team-state file is missing, or all `durationMs` values are 0/absent, 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 |
+| `Total` | sum of (lead + all workers) across those runs |
+| `Lead` | sum of `leadUsage.durationMs` |
+| `Workers` | sum of all `workers[].usage.durationMs` |
+
+Add a final `Grand total` row.
+
+### B. Per worker breakdown (per task type)
+
+For each task type, list one row per `workerId` actually present, plus `lead` and (if non-zero) `intake`. Aggregate `durationMs` across all runs of that task type.
+
+| Worker | Runs | Total | Avg/run |
+|--------|------|-------|---------|
+
+Use the `workerId` from team-state (e.g. `claude`, `codex`, `gemini`, `report-writer`). When the same `workerId` ran with different `agent` values across runs, append the agent in parentheses (`claude (claude)`, `codex (codex)`).
+
+## 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 | Total     | Lead     | Intake   | Workers  |
+|------------------------|------|-----------|----------|----------|----------|
+| requirements-discovery | 2    | 00:34:12  | 00:12:08 | 00:01:00 | 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:04:06** | 01:05:49 | 00:01:00 | 01:57:17 |
+
+### Per worker — requirements-discovery
+
+| Worker         | Runs | Total    | Avg/run  |
+|----------------|------|----------|----------|
+| lead           | 2    | 00:12:08 | 00:06:04 |
+| intake         | 1    | 00:01:00 | 00:01:00 |
+| 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)
+```
+
+If the `Intake` column is all zero across every task type, omit that column entirely.
+
+## 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.

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

@@ -0,0 +1,138 @@
+---
+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".
+---
+
+# setup-okstra
+
+One-time bootstrap. Run when okstra is being used for the first time on this
+machine, or when adopting okstra in a new project.
+
+## When to use
+
+- `~/.okstra/version` is missing or stale → okstra runtime is not installed yet.
+- The current project has no `.project-docs/okstra/project.json` yet.
+- The user says "set up okstra here", "first time", "okstra init", etc.
+
+## When NOT to use
+
+- A task is already in flight → use [`okstra-run`](../okstra-run/SKILL.md) or
+  [`okstra-status`](../okstra-status/SKILL.md).
+- Day-to-day usage in a project that already has `project.json` — skip this skill.
+
+## Prerequisites
+
+Inform the user up-front and confirm before continuing:
+
+- **Node 18+** required (runs `npx`). If missing, point to `brew install node`
+  or `nvm`.
+- **Python 3.10+** required (runs the okstra core).
+- The current working directory must be inside the project that will host the
+  okstra metadata. If unsure, ask with `AskUserQuestion` for an absolute project
+  root before proceeding.
+
+## Step 1: Install okstra
+
+```bash
+npx -y okstra@latest install
+```
+
+This single command populates everything the user needs:
+
+- `~/.okstra/{lib/python, bin, version}` — python + bash runtime
+- `~/.claude/skills/<name>/SKILL.md` — all 11 okstra skills (incl. this one)
+- `~/.okstra/installed-skills.json` — manifest for safe uninstall
+
+The skill should run this even if `~/.okstra/version` already exists —
+`install` is idempotent (per-file hash skip), so re-running is cheap and
+ensures the install matches the package version currently on disk.
+
+Show the final summary line back to the user (`version stamp: x.y.z`).
+
+If install fails, surface the stderr verbatim. Do NOT try to "fix" it by
+running the legacy `okstra-install.sh` — that path is dev-only.
+
+## Step 2: Load runtime paths
+
+```bash
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+```
+
+After this, `$OKSTRA_WORKSPACE`, `$OKSTRA_AGENTS_DIR`, `$OKSTRA_PYTHONPATH`,
+`$OKSTRA_BIN`, `$OKSTRA_HOME` are all set. Do not hardcode any of these — read
+them from the env vars.
+
+## Step 3: Resolve PROJECT_ROOT
+
+```bash
+python3 - <<'PY'
+from okstra_project import resolve_project_root, ResolverError
+try:
+    pr = resolve_project_root(explicit_root="", cwd=".")
+    print(f"OK\t{pr}")
+except ResolverError as e:
+    print(f"FAIL\t{e}")
+PY
+```
+
+- `OK` line → use that as `PROJECT_ROOT`.
+- `FAIL` line → ask the user (`AskUserQuestion`, free text) for an absolute
+  project root. Re-run with `explicit_root=<their answer>`.
+
+## Step 4: Inspect or create `project.json`
+
+```bash
+PROJECT_JSON="$PROJECT_ROOT/.project-docs/okstra/project.json"
+if [ -f "$PROJECT_JSON" ]; then
+  cat "$PROJECT_JSON"
+fi
+```
+
+If the file exists, print its `projectId`/`projectRoot` and ask whether to
+keep or overwrite. Default is to keep — okstra refuses to change `projectId`
+on an existing project (see `okstra_project.resolver.upsert_project_json`),
+so overwriting requires manually deleting the file first.
+
+If the file does NOT exist, ask via `AskUserQuestion`:
+
+- **Question**: `"Project id for okstra (e.g. INV-1234, fontsninja, okstra)"`
+- **Validate**: slugified must contain at least one alphanumeric character.
+
+Then create the file:
+
+```bash
+python3 - <<PY
+from pathlib import Path
+from okstra_project import upsert_project_json
+result = upsert_project_json(Path("$PROJECT_ROOT"), "$PROJECT_ID")
+print(result)
+PY
+```
+
+## Step 5: Verify
+
+```bash
+npx -y okstra@latest doctor
+```
+
+If all checks return `OK`, the setup is complete. If any check fails, surface
+the output and let the user decide whether to re-run install or skip.
+
+## Step 6: Hand-off
+
+Inform the user with a short summary:
+
+> okstra is ready. Runtime: `~/.okstra` (version stamp). Project metadata:
+> `<PROJECT_ROOT>/.project-docs/okstra/project.json` (`projectId`). Run
+> `/okstra-run` to start your first task.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `command not found: npx` | Node missing | Install node 18+. |
+| `okstra ensure-installed` keeps reinstalling | `~/.okstra/version` write fails (permissions) | Check `~/.okstra` ownership and writability. |
+| `ResolverError: project_id required` | empty answer to Step 4 prompt | Re-ask Step 4. |
+| `projectId 불일치` | `project.json` already exists with a different id | Decide which id is canonical; manually edit the file or pick the existing id. |
+| `npx okstra@latest install` succeeds but `doctor` shows FAIL | runtime/{python,bin,skills} sync not yet performed (pre-release package) | Use dev install: clone the repo and run `node bin/okstra install --link <repo>`. |

package/src/doctor.mjs

@@ -1,8 +1,12 @@
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
+import { homedir } from "node:os";
 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 USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
@@ -15,6 +19,7 @@ Checks:
   - okstra_ctl module importable
   - bash entrypoints present and executable in $HOME/.okstra/bin
   - agents/ directory exists inside the okstra package
+  - canonical skills present at $HOME/.claude/skills/<name>/SKILL.md
   - version stamp matches package version
 `;
 
@@ -104,6 +109,16 @@ export async function run(args) {
     await check("bin: okstra-codex-exec.sh", () => checkBashEntry(paths.bin, "okstra-codex-exec.sh")),
     await check("bin: okstra-gemini-exec.sh", () => checkBashEntry(paths.bin, "okstra-gemini-exec.sh")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
+    ...(await Promise.all(
+      REQUIRED_SKILLS.map((name) =>
+        check(`skill: ${name}`, async () => {
+          const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
+          return (await pathExists(p))
+            ? { ok: true, detail: p }
+            : { ok: false, detail: `not found: ${p}` };
+        }),
+      ),
+    )),
     await check("version stamp", async () =>
       paths.version === paths.package
         ? { ok: true, detail: paths.version }

package/src/install.mjs

@@ -1,9 +1,13 @@
 import { promises as fs } from "node:fs";
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join, relative, resolve as resolveAbs } from "node:path";
 import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
 
+const SKILLS_MANIFEST_REL = "installed-skills.json";
+const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
@@ -25,13 +29,16 @@ Usage:
   okstra install --refresh    Re-copy even files that match by hash
 
 Effect (copy mode):
-  ${"$HOME"}/.okstra/lib/python   <- packages/okstra/runtime/python
-  ${"$HOME"}/.okstra/bin           <- packages/okstra/runtime/bin
+  ${"$HOME"}/.okstra/lib/python   <- runtime/python
+  ${"$HOME"}/.okstra/bin           <- runtime/bin
+  ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
+  ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
   ${"$HOME"}/.okstra/version       <- installed package version stamp
 
 Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
+  ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name>   (symlink dir)
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
   ${"$HOME"}/.okstra/version          <- installed package version stamp
 
@@ -208,6 +215,9 @@ async function installLinkMode(repoPath, paths, opts) {
     if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
   }
 
+  const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
+  await writeSkillsManifest(paths.home, skillResult.installed, { dryRun });
+
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -229,6 +239,79 @@ async function fileExists(p) {
   }
 }
 
+async function listSkillDirs(skillsRoot) {
+  try {
+    const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+async function writeSkillsManifest(home, names, opts) {
+  const { dryRun = false } = opts ?? {};
+  const data = {
+    version: 1,
+    installedAt: new Date().toISOString(),
+    skills: Array.from(new Set(names)).sort(),
+  };
+  if (dryRun) {
+    process.stdout.write(`[dry-run] write skills manifest: ${data.skills.length} entries\n`);
+    return;
+  }
+  await writeFileAtomic(
+    join(home, SKILLS_MANIFEST_REL),
+    JSON.stringify(data, null, 2) + "\n",
+    0o644,
+  );
+}
+
+async function installSkillsCopy(runtimeRoot, opts) {
+  const { refresh, dryRun, quiet } = opts;
+  const srcRoot = join(runtimeRoot, "skills");
+  const names = await listSkillDirs(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  skills: runtime/skills empty — skipped\n");
+    return { installed: [] };
+  }
+  let copied = 0;
+  let skipped = 0;
+  for (const name of names) {
+    const r = await copyTreeIfChanged(
+      join(srcRoot, name),
+      join(CLAUDE_SKILLS_DIR, name),
+      { refresh, dryRun, mode: 0o644 },
+    );
+    copied += r.copied;
+    skipped += r.skipped;
+  }
+  if (!quiet) {
+    process.stdout.write(
+      `  skills: copied=${copied} skipped=${skipped} -> ${CLAUDE_SKILLS_DIR}/ (${names.length} skills)\n`,
+    );
+  }
+  return { installed: names };
+}
+
+async function installSkillsLink(repoAbs, opts) {
+  const { dryRun, quiet } = opts;
+  const srcRoot = join(repoAbs, "skills");
+  const names = await listSkillDirs(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  skills: <repo>/skills missing — skipped\n");
+    return { installed: [] };
+  }
+  if (!dryRun) await fs.mkdir(CLAUDE_SKILLS_DIR, { recursive: true });
+  for (const name of names) {
+    const src = join(srcRoot, name);
+    const dst = join(CLAUDE_SKILLS_DIR, name);
+    const action = await ensureSymlink(src, dst, { dryRun });
+    if (!quiet) process.stdout.write(`  skills/${name}: ${action}\n`);
+  }
+  return { installed: names };
+}
+
 function parseInstallArgs(args) {
   const result = {
     dryRun: false,
@@ -309,6 +392,9 @@ export async function runInstall(args) {
     );
   }
 
+  const skillResult = await installSkillsCopy(runtimeRoot, opts);
+  await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });
+
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
   }
@@ -344,6 +430,9 @@ 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 (reasons.length === 0) {
     if (!quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);

package/src/paths.mjs

@@ -14,8 +14,8 @@ Usage:
 Fields:
   agents       Absolute path to agents/. Default: <workspace>/agents.
   workspace    Directory containing prompts/, templates/, validators/,
-               agents/. Equals packages/okstra/runtime in copy mode,
-               or the dev-link repo path in dev mode.
+               agents/. Equals the package's runtime/ directory in copy
+               mode, or the dev-link repo path in dev mode.
   pythonpath   $HOME/.okstra/lib/python
   bin          $HOME/.okstra/bin
   home         $HOME/.okstra

package/src/uninstall.mjs

@@ -1,4 +1,5 @@
 import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
@@ -11,13 +12,35 @@ const BIN_ENTRYPOINTS = [
   "okstra-error-log.py",
 ];
 
-const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra
+const FALLBACK_SKILL_NAMES = [
+  "setup-okstra",
+  "okstra-run",
+  "okstra-status",
+  "okstra-history",
+  "okstra-schedule",
+  "okstra-context-loader",
+  "okstra-team-contract",
+  "okstra-convergence",
+  "okstra-report-writer",
+  "okstra-report-finder",
+  "okstra-time-summary",
+];
+
+const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+const SKILLS_MANIFEST_REL = "installed-skills.json";
+
+const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra and ~/.claude/skills
 
 Usage:
-  okstra uninstall              Remove lib/, bin/{known entries}, version, dev-link
-                                Preserves user data: recent.jsonl, active.jsonl,
-                                projects/, archive/, state.json, .locks/
-  okstra uninstall --purge      Remove the entire ~/.okstra directory (DESTRUCTIVE)
+  okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
+                                dev-link, installed-skills.json} AND
+                                ~/.claude/skills/<name> for every entry in
+                                the install manifest (fallback: hard-coded
+                                okstra-* names). Preserves user data:
+                                recent.jsonl, active.jsonl, projects/,
+                                archive/, state.json, .locks/
+  okstra uninstall --purge      Remove the entire ~/.okstra directory AND
+                                ~/.claude/skills/<okstra-*> (DESTRUCTIVE).
                                 Requires -y or an interactive confirmation
   okstra uninstall --dry-run    Print the plan without touching disk
   okstra uninstall -y           Skip confirmation prompt for --purge
@@ -79,7 +102,9 @@ export async function runUninstall(args) {
 
   if (opts.purge) {
     if (!opts.yes && !opts.dryRun) {
-      const ok = await promptConfirm(`purge entire ${paths.home}? user data will be lost.`);
+      const ok = await promptConfirm(
+        `purge entire ${paths.home} AND ~/.claude/skills/{okstra-*,setup-okstra}? user data will be lost.`,
+      );
       if (!ok) {
         process.stdout.write("aborted.\n");
         return 1;
@@ -87,6 +112,10 @@ export async function runUninstall(args) {
     }
     if (!opts.quiet) process.stdout.write(`purging ${paths.home}\n`);
     await removePath(paths.home, opts);
+    // Skills live outside ~/.okstra — purge those too with the fallback list.
+    for (const name of FALLBACK_SKILL_NAMES) {
+      await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
+    }
     return 0;
   }
 
@@ -112,6 +141,19 @@ export async function runUninstall(args) {
       }
     }
   }
+
+  // Remove the skills we own. Manifest is authoritative; fall back to the
+  // hard-coded okstra-* names if it is missing (e.g. an install from an old
+  // version that did not write the manifest).
+  const skillNames = await readSkillsManifest(paths.home);
+  if (!opts.quiet) {
+    process.stdout.write(`  skills: removing ${skillNames.length} entries from ${CLAUDE_SKILLS_DIR}\n`);
+  }
+  for (const name of skillNames) {
+    await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
+  }
+  await removePath(join(paths.home, SKILLS_MANIFEST_REL), opts);
+
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);
 
@@ -120,3 +162,14 @@ export async function runUninstall(args) {
   }
   return 0;
 }
+
+async function readSkillsManifest(home) {
+  try {
+    const raw = await fs.readFile(join(home, SKILLS_MANIFEST_REL), "utf8");
+    const data = JSON.parse(raw);
+    if (Array.isArray(data?.skills)) return data.skills;
+  } catch {
+    /* fall through */
+  }
+  return FALLBACK_SKILL_NAMES;
+}