okstra 0.2.0 → 0.4.0

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

@@ -0,0 +1,138 @@
+---
+name: okstra-setup
+description: One-time bootstrap for okstra in a new project or on a new machine — installs the okstra runtime via npx and creates the project's .project-docs/okstra/project.json. Trigger words include "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time okstra setup", "configure okstra here".
+---
+
+# okstra-setup
+
+One-time bootstrap. Run when okstra is being used for the first time on this
+machine, or when adopting okstra in a new project.
+
+## 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/runtime/skills/okstra-status/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: okstra-status
+description: Use when the user asks for overall okstra task status, current lifecycle phase, next recommended phase, blockers, approval state, status for a specific task key, OR wants to update a task's workStatus (todo / in-progress / blocked / done). Trigger words include "okstra status", "task status", "current phase", "next phase", "what is pending", "resume point", "okstra status set", "okstra mark", "<task-id> done", "<task-id> in-progress", "<task-id> 진행중", "<task-id> 완료".
+---
+
+# OKSTRA Status
+
+## When to Use
+
+- When user wants to view the progress of the entire project
+- When user want to check the current phase, next phase, blockers, and resume points for a specific `task-key`
+- When user want to check which tasks are pending approval or which tasks can be resumed
+
+## Step 0: Verify okstra runtime + project setup
+
+Before any other step, ensure both the okstra runtime and the current
+project's okstra metadata are in place:
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
+parse and reuse it instead of re-resolving in the steps below.
+
+## Step 1: Overall Project Status
+
+To view the overall project status, first read `.project-docs/okstra/discovery/task-catalog.json`.
+
+Extract the following fields from each task.
+
+| Field | Description |
+|------|------|
+| `taskKey` | `<project-id>:<task-group>:<task-id>` |
+| `taskType` | latest task type |
+| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown |
+| `currentStatus` | task-level status |
+| `currentPhase` | lifecycle current phase |
+| `currentPhaseState` | lifecycle phase state |
+| `nextRecommendedPhase` | next recommended phase |
+| `routingStatus` | routing decision status |
+| `awaitingApproval` | approval 대기 여부 |
+| `latestRunStatus` | latest run status |
+| `latestReportPath` | latest report path |
+| `latestResumeCommandPath` | latest resume command |
+| `workStatus` | user-managed work status (todo / in-progress / blocked / done; default in-progress) |
+| `updatedAt` | last update time |
+
+Sort by:
+
+1. `updatedAt` Descending
+2. Next, `taskKey`
+
+출력 형식:
+
+```markdown
+## okstra Status — <project-id>
+
+| # | Task Key | Category | Phase | Phase State | Task Status | workStatus | Next | Routing | Approval | Last Run |
+|---|----------|----------|-------|-------------|-------------|------------|------|---------|----------|----------|
+| 1 | proj:group:id | bugfix | error-analysis | completed | completed | in-progress | implementation-planning | not-applicable | no | completed |
+| 2 | proj:group:id2 | feature | requirements-discovery | prepared | instruction-set-generated | done | pending-routing-decision | pending | yes | prepared |
+```
+
+## Step 2: Specific Task Status
+
+Given a specific `task-key` or `task-group + task-id`:
+
+1. If possible, quickly look it up in `task-catalog.json`.
+2. If necessary, read `.project-docs/okstra/tasks/<task-group>/<task-id>/task-manifest.json` directly.
+3. If you need the latest run information, read `history/timeline.json` along with the latest run manifest.
+
+Required fields:
+
+- `taskKey`
+- `taskType`
+- `workCategory`
+- `currentStatus`
+- `latestRunStatus`
+- `workflow.currentPhase`
+- `workflow.currentPhaseState`
+- `workflow.phaseStates`
+- `workflow.lastCompletedPhase`
+- `workflow.nextRecommendedPhase`
+- `workflow.awaitingApproval`
+- `workflow.routingStatus`
+- `workflow.lastSafeCheckpoint`
+- `workStatus`
+- `workStatusUpdatedAt`
+- `workStatusNote`
+- `latestReportPath`
+- `latestResumeCommandPath`
+- `historyTimelinePath`
+
+Output format:
+
+```markdown
+## okstra Task Status — <task-key>
+
+- Work category: `<category>`
+- Current phase: `<phase>`
+- Current phase state: `<phase-state>`
+- Last completed phase: `<phase-or-->`
+- Next recommended phase: `<phase>`
+- Awaiting approval: `<yes|no>`
+- Routing status: `<routing-status>`
+- Task status: `<task-status>`
+- Latest run status: `<run-status>`
+- Latest report: `<relative-path-or-->`
+- Resume command: `<relative-path-or-->`
+- workStatus: `<todo|in-progress|blocked|done>` (updated `<workStatusUpdatedAt-or-->`)
+- workStatus note: `<workStatusNote-or-->`
+
+### Phase States
+
+- `requirements-discovery`: `<state>`
+- `error-analysis`: `<state>`
+- `implementation-planning`: `<state>`
+- `implementation`: `<state>`
+- `final-verification`: `<state>`
+
+### Safe Resume Checkpoint
+
+- Label: `<checkpoint-label>`
+- Run manifest: `<relative-path-or-->`
+- Team state: `<relative-path-or-->`
+- Report: `<relative-path-or-->`
+- Resume command: `<relative-path-or-->`
+```
+
+## Step 3: Resume and Next-Step Guidance
+
+The status response always includes one of the following options:
+
+1. **Resume current run**
+- If `latestResumeCommandPath` exists, display that path.
+2. **Restart current phase**
+- Indicates whether the task can be re-run with the same `task-key` and the current `taskType`.
+3. **Start next phase**
+- If `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, or `final-verification`, that phase is proposed as the next candidate for the Okstra run.
+4. **Need more information**
+- If `nextRecommendedPhase` is `pending-routing-decision` or `routingStatus` is `pending`, this indicates that additional information is required.
+
+## Step 4: Update workStatus
+
+The skill MUST recognize requests to change a task's `workStatus` and update the corresponding `task-manifest.json`.
+
+### Trigger Patterns (recognize both)
+
+**Natural language (Korean / English)**:
+- "DEV-6827 done으로 바꿔줘"
+- "PROD-1623을 blocked로 표시"
+- "DEV-9047 진행중"
+- "Mark DEV-6827 as done"
+
+**Explicit command**:
+- `okstra status set <task-id> <status>`
+- `okstra status set <task-group> <task-id> <status>` (used to disambiguate)
+- `okstra mark <task-id> <status>`
+- `okstra status set <task-id> <status> --note "<note>"`
+
+Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
+
+### Procedure
+
+1. **Validate status value**. If not in the enum, output an error and the allowed values list. Do not modify any file.
+
+2. **Look up the task** in `.project-docs/okstra/discovery/task-catalog.json` by `task-id` (case-insensitive on both `task-id` and `task-group`).
+   - If the user provided `<task-group>` explicitly, scope the lookup to that group (case-insensitive).
+   - If a single match is found → proceed.
+   - If multiple matches across different `task-group` values → list the groups and ask the user to retry with the explicit form. Example output:
+     ```
+     <TASK-ID>은 여러 task-group에 존재합니다:
+       - <group1>
+       - <group2>
+     다음 형식으로 다시 시도하세요: okstra status set <task-group> <TASK-ID> <status>
+     ```
+     Stop without modifying any file.
+   - If no match → output `<TASK-ID>를 찾을 수 없습니다.` and stop.
+
+3. **Open the matching `task-manifest.json`** at `.project-docs/okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json`.
+
+4. **Update fields at the manifest root**:
+   - `workStatus` ← new status value
+   - `workStatusUpdatedAt` ← current ISO-8601 UTC timestamp (e.g. `2026-05-01T10:23:45Z`)
+   - `workStatusNote`:
+     - If `--note` is provided → set the field to its value.
+     - If `--note` is NOT provided → leave any existing `workStatusNote` field untouched (do not delete, do not blank). If the field did not exist before, do not create it.
+
+   **Manifest preservation rules** (critical to avoid silent corruption):
+   - Use a targeted in-place edit (e.g. the Edit tool with old_string/new_string anchors).
+   - Do NOT round-trip the file through `JSON.parse` + `JSON.stringify` — that reorders keys, drops trailing newlines, and normalizes spacing.
+   - Preserve the existing key order, indentation style, and trailing newline of the file exactly.
+
+5. **Confirm in Korean**:
+
+   ```
+   ✓ <TASK-ID> workStatus: <previous> → <new>
+   ✓ task-manifest.json 업데이트됨
+   ```
+
+   Use `<previous>` = `(없음)` if the field was absent before.
+
+### Default Value Convention
+
+If `workStatus` is missing or empty in any manifest, treat it as `in-progress` for read purposes. Do not back-fill the field on read; only write it when the user explicitly issues an update.
+
+### Catalog Sync Note
+
+This skill updates `task-manifest.json` only. `discovery/task-catalog.json` may become stale until it is regenerated by another tool. Downstream consumers (e.g. `okstra-schedule`) should re-read each manifest directly to obtain the authoritative `workStatus`.
+
+---
+
+## Output Rules
+
+- Responses should be concise and written in Korean.
+- Use project-relative paths whenever possible.
+- If there is no recent report, display `--`.
+- If a specific task does not exist, explicitly state that it cannot be found based on `task-catalog.json`.
+- If `awaitingApproval` is true, clearly indicate that the task is awaiting user approval.