# okstra-setup AI Manual

## Source

- Skill source: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
- project registration impl: `src/commands/lifecycle/setup.mjs`
- install/ensure-installed impl: `src/commands/lifecycle/install.mjs`

## Purpose

`okstra-setup` handles two things.

1. Machine-level runtime install: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
2. Project-level registration: `<PROJECT_ROOT>/.okstra/project.json`

It is not a day-to-day task-running skill. If a task is already prepared, route to `okstra-run` or `okstra-inspect`.

## When to use

Use it when:

- The user asks for "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time setup".
- `~/.okstra/version` is missing or looks stale.
- The current project has no `.okstra/project.json`.

Do not use it when:

- The user wants to start a task run. Use `okstra-run` instead.
- The user wants to view status/history/report. Use `okstra-inspect` instead.
- `.okstra/project.json` already exists and only day-to-day usage is needed.

## Pre-run checks

Tell the user that Node 18+ and Python 3.10+ are required. If it is unclear whether the current working directory is inside the project that will host the okstra metadata, confirm the project root first.

Install command:

```bash
npx -y okstra@latest install --runtime claude-code
```

Treat this command as idempotent. Even if already installed, re-run it to align the runtime, skill, and agent payload with the current package version (agent payload = the `~/.claude/agents/<worker>.md` worker definitions + the `~/.okstra/installed-agents.json` manifest). If it fails, show the stderr to the user verbatim. Do not fall back to the legacy `okstra-install.sh`.

## Command invocation rule

After `okstra install`, every subsequent command must begin with the literal `okstra` token.

Allowed forms:

```bash
okstra preflight
okstra setup --yes --project-root /abs/project --project-id my-project
okstra doctor --runtime claude-code
```

Forms to avoid:

- `export PYTHONPATH=...`
- `eval "$(okstra paths --shell)"`
- shell variables like `$PROJECT_ROOT`
- `$(...)` command substitution
- okstra calls wrapped in `if`, `&&`, `||`

Because `okstra <subcmd>` bootstraps its own Python path, do not use `okstra paths --shell` in this skill. If you need the okstra home, run `okstra paths --field home` as a separate call and carry the printed path.

## Project root resolution

Run first:

```bash
okstra preflight
```

Handle the result:

- `Okstra preflight: ready`: already a registered project. Show `Project root`, `Project JSON`, and `Project ID` to the user and confirm whether to keep it.
- `Okstra preflight: failed` with `Stage: resolve`: get an absolute project root from the user and re-run `okstra preflight --cwd /abs/path`.
- `Okstra preflight: failed` with `Stage: project_json_missing`: proceed with the normal create path.
- any other failure stage: show `Reason` verbatim and follow `Recovery`.

## Create or keep project.json

If `<PROJECT_ROOT>/.okstra/project.json` exists, show `projectId` and `projectRoot` and confirm whether to keep or overwrite. The default is keep. Changing the existing `projectId` requires deleting the file, so do not overwrite automatically.

If the file does not exist, ask for a project id. The answer must be non-empty and contain at least one alphanumeric character. Calling `okstra setup --yes` with an empty value fails, so re-ask.

Create command:

```bash
okstra setup --yes --project-root /abs/project --project-id my-project
```

## Optional configuration

Per the source, Step 3.5 is optional configuration performed only when the user explicitly wants it — read `references/project-config.md` in the skill directory for the detailed procedure. If the defaults are enough, skip it and go to doctor.

Optional settings:

- `worktreeSyncDirs`: a list of project-relative directories to symlink into the task worktree. The default is `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
- `qaCommands`: check-only lint/format/typecheck/test commands the implementation verifier runs.
- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns
  Okstra uses to attempt Tier 3 automatically; real DB/API verification remains
  a user-owned advisory when the environment is unavailable or the result is
  non-PASS.
- PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
- final report language: `okstra config set report-language <en|ko|auto> --scope project`
- `architecture.style`: the project's declared architecture — `hexagonal`,
  `layered`, or `none` (default `none` when absent, unrecognized, or
  unreadable). `okstra setup` never writes it; hand-add it to `project.json`
  and the upsert preserves it. Declaring a style promotes that architecture's
  placement rules from advisory to a binding planning + verification
  constraint — under `hexagonal` an extracted variation point must be a port,
  under `layered` the dependency direction is worker-judged with no machine
  check. See section F of `references/project-config.md`.
- `reviewRulePacks`: absolute paths to the project's own review rule packs (a
  team PR-review skill's `SKILL.md`). Without a declaration a pack applies only
  when the task brief cites its exact path; declared here it applies to every
  run, and the two channels are a union. Read by `implementation-planning`, the
  executor preflight, the implementation verifier, and `final-verification`.
  `okstra setup` never writes it. `okstra doctor --phase <phase>` fails when a
  declared path is not readable. See section G of
  `references/project-config.md`.

If `qaCommands.cmd` contains a token implying mutation, the verifier refuses it. The actual authority for the deny-list is `scripts/okstra_ctl/qa_commands.py`.

## Automatic Claude settings symlink

`okstra setup` provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to `~/.okstra/templates/settings.local.json`. If an existing regular file is present, it backs it up as `.bak.<timestamp>` and then places the symlink. If a failure message appears, the user must manually merge the existing project-specific rules.

## Verify

Run last:

```bash
okstra doctor --runtime claude-code
```

If every check is OK, report setup complete. If any check fails, show the output verbatim and let the user decide whether to reinstall or skip.

## Completion message

Keep it short and include the following.

- runtime location: `~/.okstra` (also show the `version stamp: x.y.z` line from the install summary)
- project metadata: `<PROJECT_ROOT>/.okstra/project.json`
- `projectId`
- next step: `/okstra-run`

## Common failure handling

| Symptom | Handling |
|---|---|
| `command not found: npx` | Point to installing Node 18+ |
| `--project-id is required` | Re-ask for the project id and re-run with a non-empty value |
| `projectId mismatch` | Confirm with the user which id is canonical. Do not delete automatically |
| `.okstra/` write EACCES | Explain the ownership/writability problem |
| `.claude/settings.local.json` symlink warning | Show the backup file and symlink state to the user and guide a manual merge |