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

• Run only the checks the change can affect; CI runs the rest. If a check you need cannot run, say so in the PR body.
• For a change to the TypeScript clients, run ./scripts/check_clients.sh before pushing: it runs CI's client checks, including the gallery comparison in CI's Linux image (needs Docker); ./scripts/install_pre_push_hook.sh installs it as an opt-in pre-push hook. For a change to what a user sees on the desktop, also use the verify-desktop-ui skill and fill the Screens field.

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 (references/stacks.md).
   • 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.

Stacks

For two or more PRs that form a true dependency chain, read references/stacks.md before opening them, and again before touching a stack after its base changes or lands.

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. Name the sub-issue the PR closes with Closes #N when one exists; small changes need none.
• 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 the core vibesys product package and for cross-cutting changes. For documentation, use the scope of the area it describes (e.g. docs(ui): ...), or none for general guides. Otherwise use: ui for client-side code (its packages, features, and apps), client for the backend client crate, server for the server package, example for example bundles, website for the docs site (build, theme, and deploy), and the library's package name for a library (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 the bundled serving-systems product skill, confirm its 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.