okstra

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

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 Operations commands
• 4. Further reading

1. Purpose

okstra is a host-aware, multi-provider task runner that cross-verifies work with a lead + worker model. A registered host adapter supplies the lead session, while a separate provider adapter supplies models and worker execution. Claude remains the compatibility default policy, not the owner of the lifecycle.

The design rests on three principles:

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

Role assignments are persisted separately from the host runtime, but the lead provider is always derived from that runtime:

| Provider | Native host | CLI wrapper | Public roles | |---|---|---|---| | Claude | Claude Code | okstra-claude-exec.sh | leader, analyser, designer, planner, implementer, verifier, report-writer, translator | | Codex | Codex | okstra-codex-exec.sh | leader, analyser, designer, planner, implementer, verifier, report-writer, translator | | Antigravity | Antigravity CLI | okstra-antigravity-exec.sh | leader, analyser, critic, implementer, verifier | | Grok | Grok CLI | okstra-grok-exec.sh | leader, read-only analyser, and critic | | Kimi | Kimi CLI | okstra-kimi-exec.sh | leader, read-only analyser, and critic |

Canonical role names are leader, analyser, critic, designer, planner, implementer, verifier, report-writer, and translator. lead is a compatibility alias for leader. executor is a compatibility alias for implementer. New records write only the canonical names.

Role count becomes a RoleInstance ordinal. ModelPool selects one model per ordinal. A pinned model is kept only when the host can bind it exactly. The resulting RoleExecution owns Invocation and Attempt rows and the stored executionLabel. Pane titles use that label. okstra model list and okstra doctor --json report pool state without an inference call.

Grok and Kimi can now lead through their registered host adapters. Their worker roles remain read-only analyser and critic; executor, verifier, and report-writer roles were not added. A real authenticated local invocation still depends on the corresponding CLI being installed and configured.

okstra run <host-id-or-alias> resolves the requested adapter from the host registry and checks its spawn-process readiness before starting it. The installed okstra-run skill instead uses current-session: it declares only the semantic functions the live harness can actually perform (plain_text_input, plus any available native single-select, multi-select, or grouped-question function) and reuses the current lead session. User-installed adapters are discovered only from ~/.okstra/adapters/hosts/<id>/ and ~/.okstra/adapters/providers/<id>/; project-local executable adapter code is ignored.

The next direct-CLI candidates are Mistral Vibe and Qwen Code. DeepSeek V4, GLM-5.2, and MiniMax M2.7 remain API-adapter candidates because their current official coding-agent execution surfaces do not fit Okstra's wrapper contract as directly. Newly published provider models are exposed only after the corresponding local CLI reports them; this keeps model discovery separate from marketing availability.

okstra is not a one-shot code review tool. It is for work that spans multiple phases, needs input from multiple agents, and feeds each phase's output into the next phase.

2. Structure

2.1 Repo layout

okstra/                          npm package = repo root
├── package.json                 name: "okstra"
├── bin/okstra                   Node CLI entry point
├── src/                         TypeScript Node CLI sources (`*.mts`)
├── dist/                        compiled `.mjs` CLI artifacts used by `bin/okstra`
├── tools/build.mjs              runtime/ synchronization script (invoked by prepack)
├── runtime/                     gitignored install payload copied to ~/.okstra
├── scripts/                     Python + Bash runtime sources
├── skills/                      public skill Markdown sources (8 user-facing skills)
├── agents/                      Claude host execution-adapter definitions
├── prompts/, schemas/, templates/, validators/
├── docs/                        English manuals (architecture, CLI, storage, container, performance)
├── 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

The package requires Node.js 22 or newer. TypeScript sources under src/ compile to dist/**/*.mjs before tools/build.mjs rebuilds runtime/ from scripts/, skills/, agents/, prompts/, schemas/, templates/, and validators/. bin/okstra executes dist/; the npm package ships the compiled CLI, runtime payload, documentation, and README.

2.2 User-machine layout after install

~/.okstra/                       runtime home, created by `okstra install`
├── version                      package version stamp
├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
├── bin/                         okstra.sh and Claude/Codex/Antigravity/Grok/Kimi wrappers
├── templates/                   report assets and settings templates
├── prompts/                     lead operating contracts (prompts/lead/*) + coding-preflight resource pack
├── installed-runtimes.json      installed runtime adapter manifest
├── installed-skills.json        installed skill manifest (used by uninstall)
├── installed-agents.json        installed worker agent manifest (used by uninstall)
├── recent.jsonl, active.jsonl   run indexes
├── memory-book/                 global conversation memory (`okstra memory`)
├── projects/                    per-project metadata mirrors
├── worktrees/                   one isolated git worktree per task-key
│                                (shared by all phases; not removed automatically after a run)
├── archive/                     completed runs
└── .locks/                      central/task mutex files

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

~/.claude/agents/                automatically discovered by Claude Code (when `~/.claude` exists)
└── {claude,report-writer,translator}-worker.md   native Claude execution adapters
                                 (provider CLI workers use deterministic 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 runtime/ | the okstra package itself (resolved by 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 indexes | ~/.okstra/{recent,active}.jsonl | prepare_task_bundle |

3. Manual

3.1 First-time setup (once per machine)

npx -y okstra@latest install

This creates ~/.okstra/{lib/python, bin, templates, prompts, version} and the installed asset manifests under ~/.okstra/. Skill installation is based on host homes: if ~/.claude exists, public skills are installed in ~/.claude/skills/ and worker agents in ~/.claude/agents/; ~/.agents/skills/ is always created and receives public skills for Agent-compatible hosts. Only user entry-point skills appear in skill listings. Lead/support operating contracts are installed as runtime resources under ~/.okstra/prompts/, outside skill discovery. Re-running the command is idempotent: per-file hashes are compared and only changed files are updated.

Verify the installation:

npx -y okstra@latest doctor

A result: OK line means the installation is ready. Each FAIL row prints its remediation inline—usually, rerun the install command.

Optional: install the okstra command globally

Every example in this README uses npx -y okstra@latest <cmd>, so a global install is unnecessary. To invoke okstra with a bare okstra command and avoid npx package fetching and version checks on every call, 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 PATH. The runtime (~/.okstra/) and host skill directories (~/.claude/skills/ or ~/.agents/skills/) are still created by okstra install; they are not included in npm i -g. To upgrade later, run npm i -g okstra@latest && okstra install. To remove the global binary, run npm uninstall -g okstra (this leaves ~/.okstra/ intact; remove that with okstra uninstall).

Skill behavior with a global install. Every okstra skill detects a PATH-resolved okstra command and prefers it over npx -y okstra@latest. A global install therefore removes the npx fetch/version-check cost from every skill invocation (Step 0 of okstra-run, okstra-inspect, okstra-schedule-gen, and Step 0 of okstra-setup Step 2). Because each skill uses the installed version directly, you control when upgrades happen; @latest is no longer forced on every call. Run npm i -g okstra@latest && okstra install whenever you want a new release. If okstra is not on PATH, the skills automatically fall back to npx, so environments without a global install continue to work unchanged.

3.2 Register a project (once per project)

From the CLI:

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

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

/okstra-setup

Both commands write <project>/.okstra/project.json. With --project-id, the CLI is non-interactive and can be used in CI; the slash command prompts through AskUserQuestion. Every other user-facing skill refuses to run until this file exists.

3.3 Day-to-day commands

Use these slash commands inside a Claude Code session:

| Command | Purpose | |---|---| | /okstra-brief-gen | Convert a ticket, requirements document, link, or conversation into an okstra-run task brief | | /okstra-run | Start a new task or continue an existing task's next phase | | /okstra-memory | Store, search, and archive global conversation memory in ~/.okstra/memory-book | | /okstra-chat | Create or join a global room and send or read addressed messages across host sessions | | /okstra-inspect | Unified read side. Subcommands: status (phase/state and workStatus updates), history (past tasks, reruns, resumes), report (find/read final reports), time (elapsed-time breakdown), logs (wrapper log sidecar inventory and cleanup suggestions), 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), run-audit (check every run's artifacts against progress invariants, catching runs that ended wrong without ever logging a failure), and recap (run-to-run before/after summary plus free-form Q&A over a task's .okstra artifacts) | | /okstra-rollup | Aggregate every task run in a task group or project, including per-task run counts, duration, errors, group totals, and a cross-task report digest | | /okstra-usage | Show the current project's recent run coverage, raw and billable-equivalent tokens, known USD cost, CPU time, and wall-clock time grouped by task type (default: last 30 days) | | /okstra-schedule-gen | Invoke as /okstra-schedule-gen [task-group] to generate a work schedule for an entire task group. Each non-done task is resolved through the source-aware stage-map response; your unfinished-stage choices are captured in a temporary selection contract, and only the same draft that passes deterministic selection validation followed by independent narrative verification is published | | /okstra-container-build | Deploy a verified task's code as a local Docker Compose group (subcommands: up / status / down) | | /okstra-manager | Coordinate cross-project okstra tasks through manager-owned plans, assignments, one-way project sync snapshots, status, and child launch context packets | | /okstra-pr-gen | Register PR body templates under ~/.okstra/template/pr/ and generate a PR description from a branch diff (subcommands: template / branches / gen). Global skill—needs a Git repo, not a registered okstra project | | /okstra-user-response | Answer a task's open clarification questions in-session and write the response sidecar. The skill reads cited context first, then asks in plain language with each option's outcome through the host's native selection UI. Each answer is dispositioned as answer or reframe; a reframe is carried into the next run as a re-scoped brief | | /okstra-code-review | Review what a diff changed—one okstra implementation stage, or any branch—against this project's coding-preflight rules, and write the result to a file. The orchestrator censuses the diff into an explicit worklist once, four parallel reviewers return a verdict for every cell, and a coverage audit re-dispatches any gap. Result files land under .okstra/tasks/<task-group>/<task-id>/code-reviews/ (stage mode) or .project-docs/code-reviews/<branch>/ (branch mode) | | /okstra-setup | Bootstrap a project as described in §3.2 |

The lead operating contract and support contracts—context loader, team contract, convergence, report writer, and the coding-preflight pack—are no longer installed as agent skills. They are installed as okstra runtime resources under ~/.okstra/prompts/ (prompts/lead/*.md, prompts/coding-preflight/*), and the generated launch prompt gives the lead their absolute paths. Reinstallation prunes legacy copies from agent skill homes, so they are not exposed as slash commands.

3.4 CLI mode (optional)

To start a task outside a Claude Code session:

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

feature-analysis is intentionally omitted from the standalone shell example. Start it with the in-host okstra-run skill: the wizard collects its required feature target and passes that value through the internal Node render boundary. Standalone okstra.sh accepts neither --analysis-target nor --evidence-inputs.

This starts a new claude process in the lead role. For the complete argument list, see okstra.sh --help or docs/cli.md.

Notable workflow flags:

• --role-count <role>=<N> — sets the total instance count for one static role. lead is a compatibility alias for leader.
• --role-model <role>=<modelRef> — pins <provider>/<model> onto role instances in ordinal order. Unknown models fail before any side effect.
• --executor claude|codex|antigravity — compatibility input that selects the implementer provider for --task-type implementation. The other two providers are dispatched as strict read-only verifiers in the same run (docs/cli.md).
• --work-category bugfix|feature|refactor|ops|improvement — directly classifies work when the lifecycle skips the requirements-discovery phase.
• --approve — with --approved-plan, sets frontmatter.approved to true on the plan's report record (final-report-*.data.json) and re-renders the full reading copy from it. Editing that reading copy does not approve the plan. Replaces the removed --ack-approved alias.
• --selected-direction <selection-final-report.md> — starts a new implementation-planning run from a validated implementation-option-selection report. Existing planning reruns continue through --clarification-response.

Major workflow changes added to main after 0.8.0:

• Automatic isolated worktrees for every task type — During preparation, okstra-ctl runs git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment> once per task key to create an isolated working tree and a <work-category-namespace>/<task-id-segment> branch (for example, feature/dev-9436 or fix/dev-7311). The user chooses the base ref with --base-ref, using the same choices as the release-handoff PR base picker: main, dev, staging, preprod, prod, or a custom value. It is required in the first phase; the okstra-run skill collects it through AskUserQuestion, while non-interactive callers must pass --base-ref explicitly. Later non-implementation phases for the same task key (requirements-discovery → error-analysis → implementation-option-selection → implementation-planning → final-verification → release-handoff) reuse the same path and branch. implementation runs are stage-isolated: each run executes one stage in its own .../<task>/stage-<N>/ worktree on a <work-category-namespace>/<task>-s<N> branch, so independent stages with depends-on (none) can run concurrently without sharing a tree. The registry reserves both task keys and stage keys with flock. Provisioning is skipped when the caller is already in another worktree or project_root is not a Git repository; stage isolation degrades to a flat path in those cases. Manual cleanup: git worktree remove <path> → git branch -D <branch> plus release/removal of the registry entry. Details: docs/architecture.md, in the Task type section, and docs/cli.md#--executor.
• release-handoff lifecycle phase — runs immediately after final-verification returns verdict=accepted. The current Okstra lead drafts the candidate messages and PR body inline, then uses the selected host adapter's user-prompt operation for the delivery choices. Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (--no-verify), and release publication (gh release, npm publish, and similar commands) are prohibited. This phase does not edit source code. Profile: prompts/profiles/release-handoff.md.
• Configurable PR body template (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (--pr-template-path or the okstra-run Step 6 prompt) → prTemplatePath in <project_root>/.okstra/project.json → prTemplatePath in ~/.okstra/config.json → the installed default at ~/.okstra/templates/pr/pr-body.template.md. Register a template with okstra config set pr-template-path <path> [--scope project|global]; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with ~/. okstra config get pr-template-path --scope all prints every scoped value and the effective winner. The default template contains ## Summary, ## Changes, ## Test plan, and ## Linked issues, plus HTML comment guidance that the lead removes immediately before PR creation.
• Profile worker-roster validation — --workers <csv> and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's Required workers: block. Requesting a worker absent from the profile—for example, codex or antigravity for release-handoff—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
• Host-aware lead adapters — okstra-run resolves the current harness through the same dynamic host registry used by the terminal front door. Claude Code, Codex, Antigravity, Grok, and Kimi keep their matching provider assignment native; external remains the explicit all-CLI host. Host and provider are separate axes, and every non-native worker assignment runs through the deterministic okstra worker-dispatch process boundary. leadAssignment and every workerAssignments[] row record provider, model, and runner. okstra codex-dispatch remains a compatibility alias for the provider-neutral dispatcher.
• Per-invocation duty contracts — every Okstra-owned LLM call composes three independently managed inputs: a persisted model assignment, a functional duty contract from prompts/duties/, and call-specific task instructions. The final prompt and adjacent metadata carry exactly five SHA-256 digests (catalog, assignment, duty, instruction, prompt). Code-owned process launches fail before execution when verification fails; host-native calls record a verified-specification link without claiming that Okstra observed the bytes delivered by the host. Standalone code-review and schedule-verification calls use the same contract under .okstra/agent-invocations/.
• Implementation direction selection before detailed planning — implementation-option-selection is a read-only lifecycle phase between error analysis and planning. Comparison mode evaluates the merged raw candidates and displays at most three ranked directions. Every displayed direction has coveragePercent == 100, scopePrecisionPercent == 100, no unmapped commitment, and no contradicted requirement. The user confirms one direction in a separate DIRECTION SELECTION response before a new planning run starts with --selected-direction. implementation-planning then expands that one direction into files, stages, validation, and rollback, and the resulting plan still requires its own approval. A preselected direction is validated without generating alternatives. Existing approved plans without planningContract: selected-direction keep the legacy --implementation-option execution path.
• Multi-stage implementation-planning / implementation — implementation-planning always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with depends-on (none) can be implemented concurrently in separate implementation runs. Each implementation invocation runs a single stage, selected with --stage <auto|N>, and creates an evidence sidecar at carry/stage-<N>.json for automatic carry-in to the next stage. The implementation-planning run directory accumulates consumers.jsonl reverse links that record which run consumed each stage.
• AI-prepared design preparation (implementation-planning → implementation) — implementation-planning detects which stages need design input (domain contract, DB/table schema, external interface, transaction/consistency, transformation mapping, lifecycle, rollout/observability, manual user test) and has the AI draft a concrete proposal first, instead of handing the user an empty design document. Each item is assessed as ready, provisional, blocked, or not-applicable; a simple task may declare no-design-inputs. Phase 7 materializes an Okstra-owned request under design-prep-requests/, and okstra design-prep <list|show|write> or the okstra-run wizard records the confirmed answer as an append-only revision under design-prep-inputs/—neither path ever edits the approved planning snapshot. Before creating its worktree, implementation resolves only the items its selected stage cites in stageRefs: safe provisional assumptions are injected into the executor prompt so work proceeds, while an unsafe open decision makes only that stage wait or replan. A markerless legacy plan continues with a legacy-unassessed warning. Storage authorities: docs/architecture/storage-model.md. CLI: docs/cli.md#okstra-design-prep.
• Phase 6 plan-body verification (implementation-planning only) — Immediately after the report-writer worker drafts the final report and before the user approval gate, the lead performs one post-verification round. A selected-direction plan starts with P-Dir-1; a legacy candidate plan retains P-Opt-*. Both branches add P-Step-*, P-Dep-*, P-Val-*, and P-Rb-* items and ask every analyzer worker for an AGREE, DISAGREE(a-e), or SUPPLEMENT verdict. The aggregate result is passed, passed-with-dissent, blocked-by-disagreement, or aborted-non-result. The frontmatter approved field is always published as false; a blocking result keeps it false and becomes a row in ## 1. Clarification Items. A one-stage no-design-inputs plan keeps extraction and one verification round but sets gating=false, so the self-fix loop and a sweep batch do not run. For fast iteration, skip the round entirely with --no-plan-verification. Contract details: the "Plan-body verification mode" section of prompts/lead/convergence.md and docs/cli.md#--no-plan-verification.
• Brief as translation layer + Step 6.5 reporter batch confirmation — okstra-brief-gen converts external input—an issue ticket, requirements document, or user message—verbatim and marks okstra-added content as labeled augmentation. Step 6.5 asks the user to confirm in one batch whether that conversion changed meaning and records the result in Reporter Confirmations. Every analysis profile requires this section before phase analysis begins; validators/validate-brief.py enforces the requirement.
• Artifact-home rule (.okstra/) — <project>/.okstra/ is the only project artifact root owned by okstra. Anything outside this root is not okstra memory and may be read only when explicitly cited in Source Material or Reporter Confirmations. Writing outside the root requires the same explicit requested path. Internal equivalents are glossary.md for terminology and decisions/<NNNN>-<slug>.md for decision records, evaluated during implementation-planning.
• Single-owner report inputs and separate human views — New runs use report contract v3. The report writer authors narrative Markdown while approval, activity, execution, convergence, design-preparation, and plan-body state remain in separate single-owner artifacts. Phase 7 validates those inputs and atomically assembles final-report-<task-type>-<seq>.data.json against schemas/final-report-v3.0.schema.json, then derives a task-specific human HTML view. The full reading copy Markdown still uses templates/reports/final-report-v2.template.md and is rendered on demand with okstra render-final-report. Each of the eleven task types owns a dedicated template under templates/reports/html/tasks/. Historical schemas/final-report-v2.0.schema.json and schema v1 reports remain readable; new runs do not write them.
• improvement-discovery task type (sidetrack entry point) — Within a codebase scope and priority-lens allowlist, multi-worker consensus produces N improvement candidates, with a default of eight and a hard cap of 12. This is a sidetrack entry point outside PHASE_SEQUENCE; the user selects candidates and starts each under a new task ID with requirements-discovery, implementation-option-selection, or error-analysis. Lens enum SSOT: scripts/okstra_ctl/improvement_lenses.py. Output section: ## 5.9 Improvement Candidates (11-column table). Validator: validators/validate_improvement_report.py.
• Read-only analysis task types (independent sidetracks) — project-analysis maps the current project's components, dependencies, entry points, data stores, external systems, and feature index. feature-analysis traces one existing feature through flows, domain rules, state changes, integrations, and test coverage. change-impact-analysis maps the blast radius of a proposed change across preserved behavior, dependencies, tests, and operations. These are independent sidetracks outside PHASE_SEQUENCE, not lifecycle phases. No edits, tests, builds, migrations, or deployments are allowed against the target project. Start analysis runs through /okstra-run; its wizard owns target and evidence collection before calling the internal Node render command. The final report remains immutable: the HTML Analysis Review records accept, revision, or reject in a user-response sidecar. A revision request prioritizes a same-task, same-type full rerun; that rerun reanalyzes the whole confirmed scope and resolves every affected report ID instead of patching only the disputed rows. Input details: docs/cli.md.

3.5 Operations commands

| Command | Purpose | |---|---| | npx -y okstra@latest paths | Print runtime paths (--field <name> or --shell) | | npx -y okstra@latest doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>] | Diagnose runtime, skills, Python imports, and model-pool state. codex, antigravity, and external exclude Claude skill checks; --phase adds readiness checks for implementation, final-verification, release-handoff, and improvement-discovery. JSON includes modelPool and never sends an inference call | | npx -y okstra@latest model list [--role <role>] [--host <host>] [--json] | List catalog models and exact-binding availability without an inference call | | npx -y okstra@latest model default set\|unset <role> ... --scope project\|global | Write or remove role model defaults in .okstra/project.json or ~/.okstra/config.json | | npx -y okstra@latest ensure-installed | Run an idempotent check and automatically reinstall stale assets (skills call this internally) | | npx -y okstra@latest setup --project-id <id> | Register the current project in .okstra/project.json | | npx -y okstra@latest check-project | Verify that the current project was registered with setup | | npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all] | Read or write okstra settings. The current key is pr-template-path, which updates prTemplatePath in project.json or ~/.okstra/config.json | | npx -y okstra@latest memory <add\|list\|search\|show\|archive> | Store, search, and archive global conversation memory in ~/.okstra/memory-book | | npx -y okstra@latest context-cost <task-key\|task-root> [--project-root <path>] | Estimate lead, worker, and report-writer context/read costs for a task bundle | | npx -y okstra@latest render-views <final-report.data.json\|final-report.md> | Render schema v2 data directly with its task-specific human template, or use the schema v1 / quick-report compatibility path (Phase 7 step 1.5; idempotent) | | npx -y okstra@latest token-usage ... | Collect and substitute run token usage through the installed Python token-usage CLI wrapper | | npx -y okstra@latest uninstall | Remove the runtime and skills while preserving user data such as recent.jsonl and projects/ | | npx -y okstra@latest uninstall --purge -y | Remove all assets, including user data |

4. Further reading

• docs/architecture.md — detailed manual covering prompt and team contracts, storage, task-type phase rules, lifecycle, and workflow.
• docs/cli.md — complete reference for okstra.sh arguments, options, and interactive input flow.
• RELEASING.md — version cutting and publication through release-please or the manual fallback.
• CHANGELOG.md — per-release change history.