# Okstra Skills AI Manuals

This directory is a compressed manual for an AI to quickly select and precisely run okstra public skills. The authoritative contract is `skills/*/SKILL.md`; this document is the operational guide for the AI. When the source skills, templates, validators, or CLI registry conflict, prefer the source skills and the actual validator/CLI implementation.

## Verified Sources

- Public skill list: [`src/lib/skill-catalog.mjs`](../../src/lib/skill-catalog.mjs)
- Skill sources: [`skills/`](../../skills/)
- CLI command surface: [`src/cli-registry.mjs`](../../src/cli-registry.mjs)
- brief template: [`templates/reports/brief.template.md`](../../templates/reports/brief.template.md)
- schedule template: [`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md)
- brief validator: [`validators/validate-brief.py`](../../validators/validate-brief.py)
- schedule validator: [`validators/validate-schedule.py`](../../validators/validate-schedule.py)

## Skill Routing

| User intent | Skill to use | Manual |
|---|---|---|
| Install/initialize okstra on a new project or a new machine | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
| Turn requirements, tickets, links, a codebase scan, or an error-zip into an okstra input brief | `okstra-brief-gen` | [`skills/okstra-brief-gen.md`](skills/okstra-brief-gen.md) |
| Start an okstra run or execute the next phase in the current Claude Code session | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
| Manage okstra tasks across multiple projects — bundling, assignment, sync snapshots, child launch packets | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
| Check status, history, report, time, logs, cost, errors, error-zip, run-audit, recap | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
| Collect and aggregate the results of multiple task runs across a task-group (or the whole project) into a synthesized summary | `okstra-rollup` | [`skills/okstra-rollup.md`](skills/okstra-rollup.md) |
| Project-wide recent run coverage, tokens, known cost, CPU, and wall-clock usage by task type | `okstra-usage` | [`skills/okstra-usage.md`](skills/okstra-usage.md) |
| Generate a client-facing work schedule for a whole task-group | `okstra-schedule-gen` | [`skills/okstra-schedule-gen.md`](skills/okstra-schedule-gen.md) |
| Store or search conversations/decisions/preferences/requirements in the global Memory Book | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
| Create or join a global room and send or read addressed messages across host sessions | `okstra-chat` | [`skills/okstra-chat.md`](skills/okstra-chat.md) |
| Manage the implementation-task worktree-based docker compose user-test environment | `okstra-container-build` | [`skills/okstra-container-build.md`](skills/okstra-container-build.md) |
| Answer the unresolved clarification questions an okstra run left behind in-session and record the approval gate | `okstra-user-response` | [`skills/okstra-user-response.md`](skills/okstra-user-response.md) |
| Register a PR body template or generate a PR description from a branch diff (global, git repository) | `okstra-pr-gen` | [`skills/okstra-pr-gen.md`](skills/okstra-pr-gen.md) |
| Review the changed code of one okstra `implementation` stage or of any branch against the coding-preflight rules, and write the result to a file | `okstra-code-review` | [`skills/okstra-code-review.md`](skills/okstra-code-review.md) |

## Shared Execution Rules

1. Run commands as separate Bash calls whenever the source skill requires it. In particular, do not wrap `okstra preflight --runtime claude-code`, `okstra wizard ...`, or `okstra container ...` calls in `&&`, `||`, `$(...)`, a leading variable assignment, `eval`, or `export`.
2. An `okstra <subcmd>` call bootstraps its own Python path. Unless a skill states otherwise, do not build `okstra paths --shell` or `export PYTHONPATH=...`.
3. Most skills except `okstra-setup` do not use an `npx` fallback. If the runtime is missing, tell the user to run `/okstra-setup` and stop. But if it fails with `unknown command: <cmd>`, the `okstra` binary on PATH is older than the skill — point the user to `npm i -g okstra@latest` rather than `/okstra-setup`, and stop.
4. Project artifacts go under `<PROJECT_ROOT>/.okstra/` by default. The exceptions are `okstra-memory` (`~/.okstra/memory-book/`) and `okstra-chat` (`~/.okstra/chat/`).
5. `runtime/` is build output. When fixing a source skill or template, edit the source under `skills/`, `templates/`, `validators/`, `scripts/`, `src/` and apply it via a build.
6. Do not guess the contents of a tracker, URL, file, report, log, zip, template, or validator. Use only what you have confirmed by reading or running with a tool.
7. Read-side skills also produce some artifacts. `okstra-inspect errors` produces an error report Markdown and `okstra-inspect error-zip` produces an anonymized zip. Even in these cases, keep the purpose-specific fixed CLI fields as the source of truth.

## The Order the AI Reads In

1. Pick a skill in this file.
2. Read only the matching `docs/for-ai/skills/<skill>.md`.
3. If the skill requires actual execution, confirm the relevant step in the source [`skills/<skill>/SKILL.md`](../../skills/).
4. When writing a brief or schedule, also confirm the template and the validator.

## Public Skill List

The public skills listed in this AI manual are the following 14:

- `okstra-setup`
- `okstra-brief-gen`
- `okstra-run`
- `okstra-manager`
- `okstra-memory`
- `okstra-chat`
- `okstra-inspect`
- `okstra-rollup`
- `okstra-usage`
- `okstra-schedule-gen`
- `okstra-container-build`
- `okstra-user-response`
- `okstra-pr-gen`
- `okstra-code-review`