| name | create-pr |
| description | Turn a dirty working tree into a clean pull request against `main`: survey every change, group the files into Conventional Commits by blast radius (one concern per commit), run the gate, branch off `main`, capture a visual for any user-visible change, push, and open the PR. Trigger when the user says "/create-pr", "create a PR", "open a pull request", "commit and PR these changes", "group these into commits and ship them", or has a dirty working tree they want landed. Stops at "PR open"; building images and deploying to prod is a separate flow.
|
create-pr
One shared skill for Claude and Codex. The workflow itself lives in the docs, not here — this file only points at it so
both tools run the same steps. Read, in order:
- docs/agent-workflows.md → Create a PR — the whole flow: survey,
group into commits (with the grouping heuristics and Conventional Commit type table), run the gate, branch, commit,
capture a visual, push, open the PR. Includes the
gh auth recipe for an unauthenticated shell.
- docs/gitops.md — branch → PR → merge-queue mechanics:
main is squash-merge-only, and
CI arms auto-merge when the PR opens.
Load-bearing rules from those docs:
- Never commit to
main — before the first edit run navigator dev worktree-env up --branch <topic>. The CLI branches
a harness-supplied checkout in place or creates a sibling worktree when the caller did not supply one.
- Run the matching gate first. For Rust run
cargo fmt, cargo clippy --workspace --all-targets -- -D warnings, and
cargo nextest run --workspace plus cargo test -p features (total line coverage stays ≥ 90.1%; the default nextest
profile prints failures only). For any .md run cargo run -p cli -- validate <path>. No PR opens on a red tree.
- Verify coverage locally — a green
cargo test does not prove it. The floor rides inside the
cargo test (workspace) check (cargo llvm-cov --fail-under-lines 90.1), and harness-gated browser/e2e tests
(new_client_or_skip) skip in CI's coverage pass, so code covered only by them reads as uncovered. Spin up only
what CI's coverage job does (Docker for the testcontainer DB, plus the OPA binary the policy tests use — no KIND
stack) and measure before pushing; give handlers/routes a non-gated covering test through the router. A test that
needs the full KIND stack skips in that job just like the e2e, so it won't count. The floor is on the whole workspace,
not your diff, so it will not catch an uncovered change on its own — cover what you wrote regardless. See the full
note in the doc's Create a PR gate.
- Group by blast radius: one reviewable concern per commit, staging explicit paths (never
git add -A).
- Capture a live walkthrough of any user-visible change into
/tmp/navigator-screenshots/, look at it yourself, and
embed it in the PR body via gh image (GitHub user-attachments) — never commit the artifact. Default to a GIF of
the real interaction ([[web-preview]] §5); fall back to a still only when the change is genuinely static, with no
keypress, click, or state transition to show. Before/after stills of an interaction are not a substitute — they show
two states but never the input between them.
- For authenticated screenshots, follow the worktree login flow in
AGENTS.md: grant staff against the same DATABASE_URL as
web, log in through Keycloak, and avoid synthetic app cookies.
- Do not arm auto-merge. Push,
gh pr create --base main, report the PR URL, and stop. CI enables auto-merge on
open and the merge queue owns when it lands; never run gh pr merge yourself.
