# okstra

> npm: [`okstra`](https://www.npmjs.com/package/okstra) · install: `npx -y okstra@latest install`

## Index

- [1. Purpose](#purpose)
- [2. Structure](#structure)
  - [2.1 Repo layout](#repo-layout)
  - [2.2 User-machine layout after install](#user-machine-layout-after-install)
  - [2.3 Single-authority map](#single-authority-map)
- [3. Manual](#manual)
  - [3.1 First-time setup (once per machine)](#first-time-setup)
  - [3.2 Register a project (once per project)](#register-a-project)
  - [3.3 Day-to-day commands](#day-to-day-commands)
  - [3.4 CLI mode (optional)](#cli-mode)
  - [3.5 Operations commands](#ops-commands)
- [4. Further reading](#further-reading)

<a id="purpose"></a>
## 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**.

<a id="structure"></a>
## 2. Structure

<a id="repo-layout"></a>
### 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.

<a id="user-machine-layout-after-install"></a>
### 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)
```

<a id="single-authority-map"></a>
### 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` |

<a id="manual"></a>
## 3. Manual

<a id="first-time-setup"></a>
### 3.1 First-time setup (once per machine)

```bash
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:

```bash
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:

```bash
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.

<a id="register-a-project"></a>
### 3.2 Register a project (once per project)

From the CLI:

```bash
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.

<a id="day-to-day-commands"></a>
### 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 and monitor per-container logs (subcommands: `up` / `status` / `logs` / `stop-watcher` / `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.

<a id="cli-mode"></a>
### 3.4 CLI mode (optional)

To start a task outside a Claude Code session:

```bash
~/.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`](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`](docs/cli.md#--executor)).
- `--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`](docs/architecture.md), in the *Task type* section, and [`docs/cli.md#--executor`](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`](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`](docs/architecture/storage-model.md). CLI: [`docs/cli.md#okstra-design-prep`](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`](prompts/lead/convergence.md) and [`docs/cli.md#--no-plan-verification`](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`](scripts/okstra_ctl/improvement_lenses.py). Output section: `## 5.9 Improvement Candidates` (11-column table). Validator: [`validators/validate_improvement_report.py`](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`](docs/cli.md#analysis-sidetrack-task-types).

<a id="ops-commands"></a>
### 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 |

<a id="further-reading"></a>
## 4. Further reading

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