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:

./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.