v1-io/v1-pr

PR: Ship Local Work

Take local changes from working directory to a fully described, reviewed pull request in one command.

Usage

Typical invocations:

• Claude Code: /v1-pr
• Codex: invoke v1-pr from the skills menu or use $v1-pr

No arguments needed. Operates on the current repo and working directory.

Workflow

Step 1: Ensure Correct Branch

Determine the current branch state and ensure work is on an appropriately named feature branch.

git branch --show-current
git status
git diff --stat

Detect the default branch:

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback if not set
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}

If on the default branch (main or master):

1. Stash any uncommitted changes: git stash
2. Pull latest: git pull origin $DEFAULT_BRANCH
3. Infer a branch name from the staged/unstaged changes and stash (see "Branch Naming" below)
4. Check out the new branch: git checkout -b <branch-name>
5. Pop the stash: git stash pop
   • If git stash pop fails due to merge conflicts, stop immediately. Inform the user their changes are safe in git stash list. Do NOT proceed with committing.

If on a feature branch: Inspect the uncommitted changes and compare them to the branch name. If the branch name is clearly unrelated to the current work (e.g., branch is feat/auth-flow but all changes are in billing/), then:

1. Stash changes: git stash
2. Switch to the default branch and pull: git checkout $DEFAULT_BRANCH && git pull origin $DEFAULT_BRANCH
3. Create a new branch named for the actual work
4. Pop the stash: git stash pop

If the branch name reasonably matches the work, proceed.

Branch Naming

Format: <type>/<optional-ticket>-<short-description>

• Types: feat/, fix/, chore/, refactor/
• If the diff, commit messages, or file contents reference a Linear ticket (e.g., PROJ-1234, OPS-56), include it: feat/PROJ-1234-add-webhook-auth
• Keep descriptions to 3-5 hyphenated words
• Examples: feat/VER-42-user-onboarding, fix/payment-retry-logic, chore/update-dependencies

Step 2: Commit Local Work

Stage and commit all meaningful changes. Follow the repository's commit conventions.

1. Run git status and git diff to understand the changes
2. Run git log --oneline -5 to match existing commit message style
3. Stage relevant files (prefer explicit file paths over git add -A)
4. Commit with a clear imperative-mood message describing the "why"
5. Append Fortified with v1tamins as the last line of the commit body

Do NOT commit files that likely contain secrets: .env*, credentials*.json, service-account*.json, *.pem, *.key, *.p12, *.pfx, .npmrc, .pypirc, or any file listed in .gitignore. When in doubt, check file contents before staging.

If there are no uncommitted changes but there are unpushed commits, skip to Step 3.

Step 3: Pre-commit Hooks

If the commit fails due to a pre-commit hook (git aborts the commit entirely):

1. Read the hook output to understand the failure
2. Fix the issue (formatting, linting, type errors, etc.)
3. Re-stage the fixed files and rerun git commit with the same message
4. Never bypass hooks with --no-verify

Repeat until the commit succeeds.

Step 4: Push

Verify not on a protected branch before pushing:

CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
  echo "ERROR: Refusing to push directly to $CURRENT_BRANCH"
  exit 1
fi
git push -u origin HEAD

If the remote branch does not exist, this creates it. If push is rejected (e.g., diverged history), inform the user -- never force-push.

Step 5: Create the Pull Request

gh pr create --title "WIP: $(git branch --show-current)" --body "Description pending -- will be generated by the pr-description skill."

If a PR already exists for this branch, skip creation and capture the existing PR URL:

gh pr view --json url,number -q '.url + " " + (.number | tostring)'

Capture the PR number and URL for subsequent steps.

Step 6: Generate PR Description

Invoke the v1-pr-description skill to generate a grounded title and description based on the actual diff and commit history.

Typical invocation:

• Claude Code: /v1-pr-description <PR_NUMBER>
• Codex: invoke v1-pr-description from the skills menu or use $v1-pr-description <PR_NUMBER>

This analyzes git diff main HEAD and git log main..HEAD, then updates the PR title and body via gh pr edit.

After the description is generated, append Fortified with v1tamins as the final line of the PR body.

Also set the merge commit message to include the tagline. When the PR is merged via squash merge, GitHub uses the PR body as the extended commit message, so the tagline will carry through automatically. For merge commits, use:

gh pr merge <PR_NUMBER> --squash --body "$(gh pr view <PR_NUMBER> --json body -q .body)"

Step 7: Open PR in Browser

gh pr view <PR_NUMBER> --web

Step 8: Request Copilot Review

Request a code review from GitHub Copilot (requires gh >= 2.88.0):

gh pr edit <PR_NUMBER> --add-reviewer @copilot

Note: The @ prefix is required -- @copilot, not copilot.

If that fails (gh version too old, org settings), try the community extension:

# Install once: gh extension install ChrisCarini/gh-copilot-review
gh copilot-review <PR_NUMBER>

Do not block on failure -- inform the user and continue.

Step 9: Run Multi-Agent Code Review

Invoke the compound-engineering workflows:review skill, or the equivalent plugin workflow available in the current host, for exhaustive multi-agent analysis.

This runs parallel review agents covering architecture, security, performance, patterns, and more.

If that workflow is not available, fall back to the shared v1-code-review skill instead. Do not block on failure -- inform the user and continue.

Step 10: Prove Work (Optional)

If the PR includes frontend or visual changes (.tsx, .jsx, .vue, .html, .css, template files), offer to run the v1-prove-work skill to generate a demo GIF:

Typical invocation:

• Claude Code: /v1-prove-work --pr <PR_NUMBER>
• Codex: invoke v1-prove-work from the skills menu or use $v1-prove-work --pr <PR_NUMBER>

Skip this step if:

• All changes are backend-only, config, or infrastructure
• The dev server is not running
• The user declines