okstra

npm: okstra · install: npx -y okstra@latest install

한국어 매뉴얼: README.kr.md

Index

• 1. Purpose
• 2. Structure
  • 2.1 Repo layout
  • 2.2 User-machine layout after install
  • 2.3 Single-authority map
• 3. Manual
  • 3.1 First-time setup (once per machine)
  • 3.2 Register a project (once per project)
  • 3.3 Day-to-day commands
  • 3.4 CLI mode (optional)
  • 3.5 Ops commands
• 4. Further reading

1. Purpose

okstra is a structured task-execution runner for Claude Code that cross-verifies work with a lead + worker model. The Claude lead drives phase progression and dispatches independent analysis workers — Claude and Codex by default (with Antigravity available as an opt-in extra) — plus a dedicated report-writer for the final synthesis.

The design rests on three principles:

• Single entry point (prepare_task_bundle): every caller — skill, bash CLI, in-session — produces the same task directory layout, manifest, and validation paths.
• Persistent task identity: a stable <project-id>/<task-group>/<task-id> key carries context across phases, sessions, and model upgrades.
• Mandatory lead/worker contract: output schemas and validation are bound to templates/ + validators/; the worker roster is fixed per phase.

okstra is not a one-shot code reviewer. It targets work that spans multiple phases, needs multiple agents to weigh in, and where each phase's output feeds the next.

2. Structure

2.1 Repo layout

okstra/                          npm package = repo root
├── package.json                 name: "okstra"
├── bin/okstra                   Node CLI entrypoint
├── src/                         Node CLI command modules (install, wizard, config, render, token usage, ...)
├── tools/build.mjs              runtime/ sync script (invoked by prepack)
├── runtime/                     gitignored install payload copied to ~/.okstra
├── scripts/                     python + bash runtime sources
├── skills/                      public skill markdown sources (9 user-facing skills)
├── agents/                      worker agent markdown sources
├── prompts/, schemas/, templates/, validators/
├── tests/, tests-e2e/
├── .claude-plugin/plugin.json   secondary skills-CLI channel manifest
├── .github/workflows/           release-please.yml, release.yml
└── RELEASING.md, CHANGELOG.md, README.md, README.kr.md

runtime/ is rebuilt from scripts/, skills/, agents/, prompts/, schemas/, templates/, and validators/ by tools/build.mjs during prepack. It is the install payload copied into ~/.okstra; the npm package also ships the Node CLI (bin/, src/), docs, and READMEs.

2.2 User-machine layout after install

~/.okstra/                       runtime home, populated by `okstra install`
├── version                      package version stamp
├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
├── bin/                         okstra.sh, codex-exec, antigravity-exec, ...
├── templates/                   report assets, settings template
├── installed-runtimes.json      manifest of installed runtime adapters
├── installed-skills.json        manifest of installed skills (used by uninstall)
├── installed-agents.json        manifest of installed worker agents (used by uninstall)
├── recent.jsonl, active.jsonl   run index
├── memory-book/                 global conversation memory (okstra memory)
├── projects/                    per-project metadata mirror
├── worktrees/                   one isolated git worktree per task-key
│                                (shared by all phases; not auto-removed)
├── archive/                     completed runs
└── .locks/                      central/task mutex files

~/.claude/skills/                discovered automatically by Claude Code (if ~/.claude exists)
~/.agents/skills/                discovered by Agent-compatible hosts (created by install)
└── okstra-*/SKILL.md            user-facing skills only (setup/brief/run/memory/inspect/schedule/container/manager)

~/.claude/agents/                discovered automatically by Claude Code (if ~/.claude exists)
└── {claude,codex,antigravity,report-writer}-worker.md   subagent definitions
                                 (required for Claude Code multi-agent dispatch)

<project-root>/.okstra/
├── project.json                 {projectId, projectRoot, ...} (written by /okstra-setup)
├── discovery/{task-catalog,latest-task}.json
├── glossary.md                  okstra-owned project terminology
├── decisions/<NNNN>-<slug>.md   okstra-owned decision records
└── tasks/<task-group>/<task-id>/   task bundle (runs, manifest, reports)

2.3 Single-authority map

| Resource | Location | Owner | |---|---|---| | Runtime code (python + bash) | ~/.okstra/{lib/python, bin} | okstra install | | agents/prompts/schemas/templates/validators | npm package's runtime/ | the okstra package (resolved via okstra paths) | | Skill markdown | ~/.claude/skills or ~/.agents/skills | okstra install (tracked per target in installed-skills.json) | | Worker agent markdown | ~/.claude/agents/<worker>.md | okstra install when ~/.claude exists (tracked in installed-agents.json) | | Project metadata | <project>/.okstra/ | /okstra-setup + the project itself | | Run index | ~/.okstra/{recent,active}.jsonl | prepare_task_bundle |

3. Manual

3.1 First-time setup (once per machine)

npx -y okstra@latest install

Provisions ~/.okstra/{lib/python, bin, templates, prompts, version} and the installed-asset manifests in ~/.okstra/. Skill installation is host-home driven: if ~/.claude exists, okstra copies public skills to ~/.claude/skills/ and worker agents to ~/.claude/agents/; it always creates ~/.agents/skills/ and copies public skills there for Agent-compatible hosts. Lead/support contracts ship as runtime resources under ~/.okstra/prompts/ and are not agent skills. Re-running is idempotent — per-file hashes are compared and only changed files are touched.

Verify:

npx -y okstra@latest doctor

A result: OK line means you're ready. Any FAIL row prints its remediation in-line (usually: rerun install).

Optional: install the okstra command globally

Every example in this README uses npx -y okstra@latest <cmd> so you don't need a global install. If you'd rather type a bare okstra (and skip npx's fetch / version-check on each invocation), install it globally:

npm i -g okstra
okstra --version       # confirm the CLI is on PATH
okstra install          # same as 'npx -y okstra@latest install'

The global install only registers the Node CLI on your PATH. The runtime (~/.okstra/) and host skill directories (~/.claude/skills/ or ~/.agents/skills/) are still provisioned by okstra install — they are not part of npm i -g. To upgrade later: npm i -g okstra@latest && okstra install. To remove the global binary: npm uninstall -g okstra (leaves ~/.okstra/ untouched; remove that with okstra uninstall).

Skill behaviour with a global install. All okstra skills auto-detect a PATH-resolved okstra and prefer it over npx -y okstra@latest. That means a global install removes the per-call npx fetch / version-check from every skill invocation (Step 0 of okstra-run, okstra-inspect, okstra-schedule, okstra-setup Step 2). Since the skill uses your globally installed version directly, you control upgrade timing — @latest is no longer forced on each call. Run npm i -g okstra@latest && okstra install whenever you want to pull a new release. If okstra is not on PATH the skill silently falls back to npx, so machines without a global install keep working unchanged.

3.2 Register a project (once per project)

From the CLI:

cd <your project>
npx -y okstra@latest setup --project-id <id>     # e.g. INV-1234, my-app, okstra

Or, inside a Claude Code session, invoke the equivalent slash command:

/okstra-setup

Both write <project>/.okstra/project.json. The CLI is non-interactive when --project-id is given (use it in CI); the slash command prompts via AskUserQuestion. Every other user-facing skill refuses to proceed until that file exists.

3.3 Day-to-day commands

User-facing slash commands inside a Claude Code session:

| Command | Use | |---|---| | /okstra-brief-gen | Turn a ticket, requirements doc, link, or conversation into an okstra-run task brief | | /okstra-run | Start a new task (or resume the next phase of an existing one) | | /okstra-memory | Store/search/archive global conversation memory in ~/.okstra/memory-book | | /okstra-inspect | Unified read-side. Sub-commands: status (phase / state, workStatus update), history (past runs, re-run, resume), report (find/read final-report), time (elapsed-time breakdown), logs (wrapper log sidecar inventory + cleanup), cost (task bundle context/read cost), errors (aggregate run error logs into a report), error-zip (collect cross-project error logs into an anonymized zip and summarize clusters), recap (run-to-run before/after summary + free-form Q&A over a task's .okstra artifacts) | | /okstra-rollup | Roll up run results across every task in a task-group (or the whole project) — per-task runs/time/errors plus group totals — and synthesize a cross-task digest from the report files | | /okstra-schedule | Generate a work schedule for an entire task-group | | /okstra-container-build | Deploy a verified task's code as a local docker compose group and watch each container's logs (sub-commands: up / status / logs / stop-watcher / down) | | /okstra-graphify | Build and query a knowledge graph over the project's own .okstra/ memory (final reports, decisions/*.md, glossary.md), scoped to .okstra/ with outputs under .okstra/graph/ (sub-commands: build / query / path / explain / mcp / wiki) | | /okstra-manager | Coordinate cross-project okstra tasks through manager-owned plans, assignments, one-way project sync snapshots, status, and child launch context packets | | /okstra-setup | Per-project bootstrap (§3.2) |

The lead operating contract and its support contracts — context-loader, team-contract, convergence, report-writer, and the coding-preflight pack — are not installed as agent skills. They ship as okstra runtime resources under ~/.okstra/prompts/ (prompts/lead/*.md and prompts/coding-preflight/*) and the generated launch prompt hands the lead their absolute paths. Reinstalling prunes any earlier copies of these from the agent skill homes, so they never appear as slash commands.

3.4 CLI mode (optional)

To kick off a task from outside a Claude Code session:

~/.okstra/bin/okstra.sh \
  --project-id <id> \
  --task-group <group> \
  --task-id <id> \
  --task-type <requirements-discovery|improvement-discovery|error-analysis|implementation-planning|implementation|final-verification|release-handoff> \
  --base-ref <branch|tag|sha> \
  --task-brief ./brief.md

Spawns a fresh claude process and hands it the lead role. Full argument list: okstra.sh --help, or the Required arguments section in the Korean manual.

Notable flags added in 0.7.0 / 0.8.0:

• --executor claude|codex|antigravity — pick the provider that mutates files during --task-type implementation. The other two providers are still dispatched as read-only verifiers (see docs/kr/cli.md).
• --work-category bugfix|feature|refactor|ops|improvement — classify a task when the lifecycle skips requirements-discovery.
• --approve — combined with --approved-plan, flips the plan's YAML frontmatter approved field from false to true (replaces the removed --ack-approved alias and the older [ ] Approved checkbox marker).

Recent workflow additions (post-0.8.0, on main):

• Isolated task worktree for every task-type — prepare automatically runs git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/ on a fresh branch <work-category-namespace>/<task-id-segment> (e.g. feature/dev-9436, fix/dev-7311) branched from the user-chosen base ref (--base-ref, mirroring the release-handoff PR-base picker: main / dev / staging / preprod / prod / any local ref) the first time a task-key is seen. --base-ref is required on first phase; the okstra-run skill collects it via AskUserQuestion, non-interactive callers must pass the flag explicitly. Every subsequent non-implementation phase of the same task-key (requirements-discovery → error-analysis → implementation-planning → final-verification → release-handoff) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. implementation runs are stage-isolated instead — each run owns exactly one stage in its own .../<task>/stage-<N>/ worktree on branch <work-category-namespace>/<task>-s<N>, so independent (depends-on (none)) stages can be implemented in parallel across simultaneous runs without sharing a tree. A global registry at ~/.okstra/worktrees/registry.json (flock-guarded) reserves task-keys and stage-keys across concurrent runs; all path/branch segments are sanitised (/, :, etc. → -). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or project_root is not a git repo, provisioning no-ops (stage isolation degrades to the flat path too). Manual cleanup: git worktree remove <path> → git branch -D <branch> plus releasing/removing the key from the registry. Details: docs/kr/architecture.md (Task type section) and docs/kr/cli.md#--executor.
• release-handoff lifecycle phase — runs after final-verification returns verdict=accepted. The lead drafts a commit message and PR body via a Claude worker, then prompts the user with AskUserQuestion for three choices: action (commit only / commit + PR / skip), PR base branch (staging / preprod / prod / main / dev / free-form), and message handling (use as-is / edit then proceed / cancel). Only user-selected mutating git/gh commands run. Force-push, base-branch direct push, hook bypass (--no-verify), and release publishing (gh release, npm publish, ...) are forbidden. Source code is not edited in this phase. Profile: prompts/profiles/release-handoff.md.
• Configurable PR body template (release-handoff) — the PR body is filled from a markdown template chosen in priority order: per-run override (--pr-template-path or the okstra-run Step 6 prompt) → <project_root>/.okstra/project.json prTemplatePath → ~/.okstra/config.json prTemplatePath → bundled skill default at ~/.claude/skills/templates/prd/pr-body.template.md. Register a template with okstra config set pr-template-path <path> [--scope project|global] (project scope accepts paths relative to the project root; global scope requires absolute or ~/-prefixed). okstra config get pr-template-path --scope all reports every scope plus the effective winner. The bundled default ships ## Summary / ## Changes / ## Test plan / ## Linked issues with HTML comment guidance that the lead strips before opening the PR.
• Profile-roster worker validation — --workers <csv> (and the okstra-run Step 6 worker prompt) are now restricted to the worker IDs declared by the chosen profile's Required workers: block. Asking for codex / antigravity on a profile that does not list them (e.g. release-handoff) is rejected with a clear error, and the interactive prompt only offers workers the profile actually accepts.
• Experimental Codex lead adapter — okstra codex-run <render-bundle args...> prepares a leadRuntime=codex task bundle without launching Claude Code. okstra codex-dispatch --project-root <dir> --run-manifest <path> can then run the supported Codex-side subset of the roster (Codex/Antigravity CLI workers by default; Codex report-writer only with --enable-codex-report-writer --report-writer-codex-model <model>). Successful Codex report-writer dispatch runs token/cost substitution, HTML view rendering, follow-up stub generation, and run validation in order. This shares the same manifests/schemas as the Claude lead path; it does not clone the project into a separate Codex-specific fork.
• Multi-stage implementation-planning / implementation — implementation-planning always produces a Stage Map plus N stage sections; each stage has ≤6 steps and stages whose depends-on (none) can be executed in parallel by separate implementation runs. Each implementation invocation picks one stage (via --stage <auto|N>) and emits an evidence sidecar (carry/stage-<N>.json) that the next stage automatically inherits. The implementation-planning run directory accumulates a consumers.jsonl reverse-link showing which implementation runs consumed which stage.
• Phase 6 plan-body verification (implementation-planning only) — after the Report writer worker authors the final-report draft and before the user approval gate, the lead runs one additional verification round: it extracts P-Opt-* / P-Step-* / P-Dep-* / P-Val-* / P-Rb-* items from the consolidated ## 5.5 implementation plan deliverables body and dispatches them to every analyser worker as AGREE / DISAGREE(a-e) / SUPPLEMENT. The aggregated gate result is one of passed / passed-with-dissent / blocked-by-disagreement / aborted-non-result. The frontmatter approved flag is always emitted as false; blocking gate results keep it false and become ## 1. Clarification Items rows. Details: prompts/lead/convergence.md "Plan-body verification mode" and docs/kr/cli.md#--no-plan-verification.
• Brief as translation layer + reporter batch confirmation (Step 6.5) — okstra-brief-gen now produces the brief as a translation layer that preserves external inputs (issue ticket, requirements doc, user message) verbatim while labelling okstra augmentations. A new Step 6.5 walks the user through a single batch confirmation of any rewordings, recorded in a Reporter Confirmations section. Every analysis profile blocks phase entry until this section exists (validator: validators/validate-brief.py).
• Artifact-home rule (.okstra/) — okstra's project artifact root is only <project>/.okstra/. Anything outside that root is not okstra memory; it may be read only when explicitly cited as Source Material or Reporter Confirmations, and writes require the same explicit request path. okstra-internal equivalents: glossary.md for terminology and decisions/<NNNN>-<slug>.md for decision records (evaluated in implementation-planning).
• Self-contained HTML final-report view — after Phase 7 writes final-report-<task-type>-<seq>.md, okstra render-views automatically emits a sibling self-contained HTML view (inline CSS/JS, no external URLs) in the same reports/ directory for human review. The HTML lets a reviewer fill in ## 1. Clarification Items decisions and export them to runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md, which the next phase consumes as input. The original MD is never modified by view generation.
• improvement-discovery task-type (sidetrack entry-point) — Discover ranked improvement candidates within a codebase scope and lens whitelist via multi-worker consensus (default top-8, hard cap 12). Outside PHASE_SEQUENCE; the user selects candidates and opens each as a new task with requirements-discovery, implementation-planning, or error-analysis. Lens enum SSOT: scripts/okstra_ctl/improvement_lenses.py. Output section: ## 4.9 Improvement Candidates (10-column table). Validator: validators/validate_improvement_report.py.

3.5 Ops commands

| Command | Use | |---|---| | npx -y okstra@latest paths | Print runtime paths (--field <name> or --shell) | | npx -y okstra@latest doctor [--runtime claude-code\|codex\|all] [--phase <phase>] | Diagnose runtime + skills + python import; codex skips Claude skill checks. --phase adds readiness checks for implementation, final-verification, release-handoff, or improvement-discovery | | npx -y okstra@latest ensure-installed | Idempotent check, auto-reinstall if stale (skills call this internally) | | npx -y okstra@latest setup --project-id <id> | Register the current project (.okstra/project.json) | | npx -y okstra@latest check-project | Verify the current project has been registered with setup | | npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all] | Read / write okstra settings; initial key pr-template-path (writes prTemplatePath to project.json or ~/.okstra/config.json) | | npx -y okstra@latest memory <add\|list\|search\|show\|archive> | Store and find global conversation memory in ~/.okstra/memory-book | | npx -y okstra@latest context-cost <task-key\|task-root> [--project-root <path>] | Estimate lead/worker/report-writer context and read cost for a task bundle | | npx -y okstra@latest render-views <final-report.md> | Regenerate the self-contained HTML sibling view from a final-report MD (Phase 7 step 1.5; idempotent) | | npx -y okstra@latest token-usage ... | Collect/substitute token usage for a run; wraps the installed Python token usage CLI | | npx -y okstra@latest uninstall | Remove runtime + skills; preserves user data (recent.jsonl, projects/, …) | | npx -y okstra@latest uninstall --purge -y | Remove everything including user data |

4. Further reading

• README.kr.md — Korean translation of this README.
• docs/kr/architecture.md — internal architecture, prompt/team contracts, storage model, task-type phase rules, lifecycle (Korean).
• docs/kr/cli.md — full okstra.sh argument reference and interactive input flow (Korean).
• RELEASING.md — how versions are cut and published (release-please + manual fallback).
• CHANGELOG.md — release-by-release change log.