# okstra-pr-gen AI Manual

## Sources

- Skill source: [`skills/okstra-pr-gen/SKILL.md`](../../../skills/okstra-pr-gen/SKILL.md)
- Template core (CLI): [`scripts/okstra_ctl/pr_template.py`](../../../scripts/okstra_ctl/pr_template.py)
- Node wrapper: [`src/commands/pr/pr.mjs`](../../../src/commands/pr/pr.mjs)
- Bundled default template: [`src/commands/pr/default.md`](../../../src/commands/pr/default.md)

## Purpose

`okstra-pr-gen` registers PR body templates and generates PR descriptions from a branch diff. Templates live in the user home at `~/.okstra/template/pr/`. This skill is **global** — it does not require `<PROJECT_ROOT>/.okstra/project.json`. PR generation additionally requires the current directory to be a git repository.

## Check CLI availability

A separate Bash call with a literal leading token:

```bash
okstra pr --help
```

If `okstra` is not on PATH: `okstra not installed — run npx okstra@latest install once, then retry`. Every Bash command starts with the literal `okstra` token and passes literal arguments (do not wrap it in `$(...)`/leading `VAR=`/`if`/`eval`/`||`/`&&`).

## Pick the mode (always first)

A 3-option picker via `AskUserQuestion`:

1. `Generate PR` — generate a PR body from a branch diff
2. `Register template` — save a new PR body template
3. `Enter directly` — always last (okstra picker convention)

## Mode A — Generate PR

1. Pick a template: `okstra pr template list`. If the numbered `Templates` rows are empty, use the bundled default. Carry the chosen name as `<template>` (`default` for the bundled one).
2. Pick the base branch: `okstra pr branches`. Build a 3-option picker from the numbered `Recommended` rows plus `Enter directly`. Carry the choice as `<base>`.
3. Generation bundle: `okstra pr gen --base <base> --template <template>`. Read the fixed `Base`, `Current branch`, `Template name`, `Commits`, `Diff stat`, and `Template` sections. Then **read the real diff honestly** (SSOT): `git diff <base>...HEAD` (large diffs section by section). Fill the placeholders from the diff and commits, describing **only actual changes**. Mark a checklist box `[x]` only when the diff supports it (tests touched → tests box, docs touched → docs box). If `Commits` or `Diff stat` is empty, say there is nothing to describe and stop. **Never append AI trailers/footers.**
4. Identifier allowlist for the title and body: only repo-relative source paths (optionally `path:line`), symbol names present in the diff, branch names / commit subjects / SHAs, and issue-tracker ticket ids the reviewer can open. okstra's own artifact identifiers are out of the allowlist — report item ids (`F-001`, `C-001`, `R-001`, `D-0001`, `PREP-001`), run artifact names and their `<task-type>-<seq>` suffixes, phase/stage/worker labels (`final-verification`, `stage-2`, `codex-worker`), and any path under `.okstra/`. They resolve to nothing for a reviewer; restate the substance in code terms instead of citing the id.
5. Output and offer to create the PR: print the filled PR body as a single fenced markdown block. Ask whether to open a PR. **Only on an explicit yes**: write the body to a temp file and run `gh pr create --base <base> --title "<title>" --body-file <path>`. If `gh` is missing or unauthenticated (`gh auth status` fails), leave the text in chat and give manual-creation guidance. **No push/PR creation without the user's confirmation.**

## Mode B — Register template

1. Template name (`AskUserQuestion`, free text) — must match `^[A-Za-z0-9._-]+$`, otherwise re-ask.
2. body — pasted text or an absolute path.
3. Save: `okstra pr template add --name <name> --file <abs-path>` (or, for pasted text, `--content "<body>"`). Add `--yes` only when the user confirmed overwriting a same-named template. Report the saved path (`saved: ...`).

## Output Rules

- Not read-side — write actions (PR creation, template saving) happen only after the user's explicit confirmation.
- Do not invent changes not in the diff. Stop if commit/diffStat is empty.