---
name: open-pr
description: Prepare and open VibeSys pull requests from local repo changes. Use when the user asks to create, open, publish, submit, or draft a PR for this repository, including tasks that need branch hygiene, targeted validation, PR intent reflection, PR template completion, commit/push, GitHub pull request creation, native GitHub stacks for dependent PRs, or maintaining a stack after its base changes or lands.
---

# Open PR

## Overview

Open a pull request for VibeSys changes without losing user work. Keep the scope narrow, recover the intended reason for the change, use the repository PR template, and make verification explicit.

## Workflow

1. Inspect state:
   - Run `git status --short --branch`.
   - Identify the current branch and upstream with `git branch --show-current` and `git remote -v`.
   - Review unstaged, staged, and untracked files before editing, staging, or committing.
   - Preserve unrelated user changes. Stage only files that belong to the requested PR.

2. Create or confirm a branch:
   - If already on an appropriate feature branch, stay on it.
   - If on `main`, `master`, or a generic branch, create a focused branch with the default Codex prefix: `vic/<short-topic>`.
   - Do not overwrite or reset a branch unless the user explicitly asks.

3. Understand the diff:
   - Use `git diff --stat`, `git diff`, and `git diff --staged` as needed.
   - Check whether generated-looking artifacts changed and verify they are intentional.
   - For prompt or skill changes, read the affected prompt/skill content as user-visible behavior.

4. Reflect on intent:
   - Gather PR motivation from the existing conversation, user request, issue links, commit history, changed files, tests, and any docs touched by the diff.
   - Treat intent as the most important part of the PR description. The `Problem` section should explain why the change exists, not merely restate which files changed.
   - Separate known intent from inference. If the reason, target user, review concern, issue linkage, rollout risk, or correctness contract is uncertain, ask the user for clarification before writing or opening the PR.
   - Ask concise questions for anything material that cannot be recovered from context unless the user explicitly asks not to be contacted.
   - Do not invent motivation to make the PR body sound complete. Use "not applicable" or a clear limitation only when the uncertainty is minor and does not change reviewer understanding.

5. Run the smallest relevant checks:
   - Prefer narrow tests first, then broaden only when the change crosses boundaries.
   - Common checks:

```bash
./scripts/format.sh
./scripts/check_format.sh
./scripts/check_lint.sh
uv run pytest path/to/test.py
uv run pytest -k keyword
uv run pytest
```

6. Commit intentionally:
   - Stage only the PR's files.
   - Re-run `git diff --staged` before committing.
   - Use a concise imperative commit subject.
   - If checks could not run, keep the commit message normal and explain the gap in the PR body.

7. Push:
   - Push the current branch to the default remote, normally `origin`.
   - Set upstream on first push: `git push -u origin <branch>`.

8. Open the PR:
   - Prefer the GitHub app/tooling when available; use `gh pr create` only as a fallback.
   - Default to a draft PR unless the user explicitly asks for a ready PR.
   - Target the repository's default base branch unless the user specifies another base.
   - Use `.github/pull_request_template.md` and fill every section.
   - Apply labels at creation (`gh pr create --label ...` or `gh pr edit
     --add-label` right after). Pick from the repository's existing labels
     (`gh label list`); do not create new ones. Every PR gets exactly one
     kind label:
     - `bug` when the `Problem` section describes existing incorrect
       behavior, or the closing issue is labeled `bug`.
     - `enhancement` for new capability, a new surface, new tooling, or a
       redesign.
     - `refactor` for a structural change with no intended behavior change.
     - `documentation` for docs-only diffs.
     Mirror the closing issue's area labels (`area/*`, `workload/*`,
     `app/*`, and similar) when the PR closes an issue that carries them.
   - When opening a dependent series, create every PR with its complete body,
     then register the series as a native GitHub stack as described below.
   - When the PR is a follow-up to someone else's merged or open PR (a more
     robust fix for the same bug, a refactor that makes that bug
     unrepresentable, or a hardening of its tests), notify the original
     author. Link the original PR in the `Problem` section and @-mention its
     author there, then post a short FYI comment on the original PR with
     `gh pr comment <original> --body ...` that mentions the author, links
     the follow-up, and says in one or two sentences why it is the more
     robust fix. Keep the tone informational; it is a courtesy, not a
     request for changes.

## Native GitHub Stacks

Use a native GitHub stack when two or more PRs form a true dependency chain in
the same repository. Keep the bottom PR based on the trunk and each later PR
based on the preceding PR's head branch. Do not stack PRs merely because they
are related or opened together.

1. Ensure the official extension is available. Install it when missing:
   `gh extension install github/gh-stack`.
2. Open each PR normally so its title, draft state, and repository-template
   body are deliberate and complete.
3. Link the open PRs in bottom-to-top order:
   `gh stack link --base <trunk> <bottom-pr> <...> <top-pr>`.
   Pass PR numbers or URLs. Omit `--open` unless the user requested ready PRs.
4. Verify each direct base with
   `gh pr view <pr> --json number,baseRefName,headRefName,isDraft,state,url`.
5. Verify remote stack membership with
   `gh api repos/{owner}/{repo}/pulls/<pr> --jq '.stack'`, then inspect the
   reported stack using
   `gh api repos/{owner}/{repo}/stacks/<stack-number>` and confirm its trunk
   and exact bottom-to-top PR order. `gh stack view` reflects local tracking
   and is not sufficient verification after `gh stack link`.

For every intentionally independent PR opened alongside stacked work, target
the trunk, do not pass it to `gh stack link`, and verify that its remote
`.stack` value is `null`.

## Maintaining a stack

PRs land through the GitHub merge queue with squash merge, bottom-up. A child
branch therefore still holds the pre-squash commits of any parent that has
already landed.

- Ask how the stack will be landed (queue order, squash) and which PRs are
  enqueued before touching any stack branch or resolving conflicts across
  branches.
- Never push to a branch that is queued or about to be queued: the push drops
  it from the queue.
- After a parent lands or changes, move the child onto the new parent tip so
  the already-squashed commits are dropped:
  `git rebase --onto <new-parent-tip> <old-parent-tip> <child>`, then
  `git push --force-with-lease`. Do not merge the parent forward into the
  child: that drags pre-squash history in and conflicts with the squashed
  commits on the trunk.
- Force-with-lease on a stack branch is safe only when nobody else pushes to
  it. Ask the user before force-pushing.
- After changing a base PR, check each child against the new base tip with
  `git merge-tree --write-tree <base> <head>` (exit 0 means clean). A child
  that was clean against its old base can conflict with the updated one. Use
  this before trusting or dismissing GitHub's mergeable state, which can lag
  by a minute: poll past `UNKNOWN`.
- Keep child PRs in draft until the stack has been rebased onto the current
  base. Mark a PR ready only after verifying its mergeable state.

## PR Body

Use this repository's template headings exactly:

- `Problem`: Lead with intent. Explain the maintainer or user pain, why the change is needed, what context led to it, and any issue links. This is the highest-priority section of the PR body.
- `Solution`: Describe the high-level design, important boundaries, tradeoffs, and what reviewers should inspect.
- `Design`: Use this subsection under `Solution` to answer the `software-design` checkpoint: owning module, public interface added or changed, direction of data and dependencies, new coupling or `tach.toml` edges, and known drift left untouched or filed as an issue. Write `n/a: <reason>` for a question that does not apply.
- `Architecture`: Use this subsection under `Solution` to describe the ownership model and major components involved in the solution. For nontrivial control flow or cross-boundary changes, include a Mermaid diagram or equivalent sketch that shows how the pieces interact.
- `Verification`: Summarize automated tests, manual checks, benchmarks, or why a check was not run.
- `Correctness properties`: List invariants, contracts, expected behaviors, and compatibility constraints preserved or introduced.
- `Testing`: List exact commands/workflows and their results.

## PR Title

PRs are squash-merged, so the PR title becomes the commit subject on `main`. Use:

```
<type>(<optional scope>): <imperative summary>
```

- `type`: one of `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`. Lowercase.
- `scope`: optional, lowercase. Omit it for `src/vibesys` (the core package) and for cross-cutting changes. For documentation under `docs/`, use the scope of the area it describes (e.g. `docs(ui): ...`), or none for general guides. Otherwise use: `ui` for client-side code under `clients/` (TUI, core-state), `client` for the backend client crate, `server` for `src/server`, `example` for `examples/`, `website` for `website/` (the docs site build, theme, and deploy), and the library directory name for `libs/` (e.g. `vs-sandbox`, `vs-project`).
- Summary: imperative mood, lowercase first word, no trailing period, about 72 characters or fewer, describing the behavior change rather than the files touched.
- Do not add the PR number; GitHub appends it on squash merge.
- Each PR in a stack gets its own type based on what that PR does.

Examples: `feat(ui): resize the docked chat pane by columns`, `fix: retry synthesized implementer responses instead of spending a round`.

Avoid generic summaries such as "update files" or "fix tests."

## VibeSys Review Notes

- Mention changes to external contracts: manifests, metadata, feature flags, CLI flags, evaluator interfaces, model-serving example bundle shape, prompt output, or skill routing.
- For prompt changes, include the snapshot diff or state that snapshots were not applicable.
- For config, metadata, feature flags, and persisted state, verify both valid input and failure cases when touched.
- For `resources/skills/serving-systems/`, confirm the subtree authoring guide was followed.
- Do not include unrelated refactors, broad cleanup, or reverted user work in the PR.

## Handoff

End with the PR URL, draft/ready status, labels applied, branch name, commit hash, and verification run. If any check was skipped or failed, state that plainly with the reason.
For stacked work, also report the stack number and PR order. For independent
work created alongside a stack, state that remote stack membership is absent.