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 Gemini 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/                      Claude Code skill markdown sources (13 skills)
├── agents/                      lead SKILL.md + workers/
├── 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, gemini-exec, ...
├── templates/                   report assets, settings template, okstra.CLAUDE.md
├── 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
├── 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
└── okstra-*/SKILL.md            13 skills total (see §3.3)

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

<project-root>/.project-docs/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/<name>/SKILL.md | okstra install (tracked in installed-skills.json) | | Worker agent markdown | ~/.claude/agents/<worker>.md | okstra install (tracked in installed-agents.json) | | Project metadata | <project>/.project-docs/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, version}, the 13 skill markdown files under ~/.claude/skills/, the 4 worker agents under ~/.claude/agents/, and the installed-asset manifests in ~/.okstra/. 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 the Claude skills (~/.claude/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>/.project-docs/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 | 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-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) | | /okstra-schedule | Generate a work schedule for an entire task-group | | /okstra-setup | Per-project bootstrap (§3.2) |

Four support skills — okstra-context-loader, okstra-team-contract, okstra-convergence, okstra-report-writer — are marked user-invocable: false and do not appear as slash commands. Claude still invokes them automatically via natural-language triggers or okstra phase flow.

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|gemini — 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-prefix>-<task-id-segment> 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 phase of the same task-key (requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. A global registry at ~/.okstra/worktrees/registry.json (flock-guarded) reserves task-keys and branches 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. Manual cleanup: git worktree remove <path> → git branch -D <branch> plus releasing/removing the task-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>/.project-docs/okstra/project.json prTemplatePath → ~/.okstra/config.json prTemplatePath → bundled skill default at ~/.claude/skills/okstra-run/templates/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 / gemini 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.
• 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 now runs one additional verification round: it extracts P-Opt-* / P-Step-* / P-Dep-* / P-Val-* / P-Rb-* items from the consolidated ## 4.5 plan 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; when the gate is blocked-by-disagreement or aborted-non-result the writer MUST keep it false (the validator refuses any report that publishes approved: true under such a gate) and convert majority-disagree items into ## 5. Clarification Items rows with Blocks=approval. Disable for fast iteration with --no-plan-verification (default: enabled). Details: skills/okstra-convergence/SKILL.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 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 (.project-docs/okstra/) — okstra's project artifact root is only <project>/.project-docs/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).
• Dual-format final-report views — after Phase 7 writes final-report-<task-type>-<seq>.md, okstra render-views automatically emits two sibling views in the same reports/ directory: a slim Markdown for downstream AI input and a self-contained HTML (inline CSS/JS, no external URLs) for human review. The HTML lets a reviewer fill in ## 5. 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 | Diagnose runtime + skills + python import | | 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 (.project-docs/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 render-views <final-report.md> | Regenerate the slim-MD + HTML sibling views 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.