commit-push-pr

by @Anshin-Health-Solutions in Development

# Install this skill:

npx skills add Anshin-Health-Solutions/superpai --skill "commit-push-pr"

Install specific skill from multi-skill repository

# Description

End-to-end workflow for staging specific files, writing a conventional commit with HEREDOC formatting, pushing with tracking, and opening a pull request via the GitHub CLI. Enforces safety rules against git add -A and force pushes.

# SKILL.md

name: commit-push-pr
description: End-to-end workflow for staging specific files, writing a conventional commit with HEREDOC formatting, pushing with tracking, and opening a pull request via the GitHub CLI. Enforces safety rules against git add -A and force pushes.
triggers:
- /commit-push-pr
- /commit
- /push
- /pr
- "create a pull request"
- "commit and push"
- "open a PR"

Commit, Push & PR

Purpose

This skill enforces a disciplined, safe, and auditable path from working changes to an open pull request. It exists because "git add -A && git commit -m 'stuff'" is how secrets get committed and histories become unreadable. Every step here is intentional. The workflow applies to any git repository hosted on GitHub.

Phase 1: Pre-Flight Checks

Before touching git, gather information:

# 1. Understand what changed
git status

# 2. Review the full diff before staging anything
git diff

# 3. Check existing staged content
git diff --cached

# 4. Understand recent commit style to match it
git log --oneline -10

Never skip the diff review. You are responsible for knowing what you are committing. If git status shows unexpected files (e.g., .env, *.key, credentials.json), do not proceed — alert the user immediately.

Phase 2: Stage Specific Files

NEVER use git add -A or git add .. These commands indiscriminately stage everything including:
- Environment files (.env, .env.local, .env.production)
- Compiled artifacts (dist/, build/, .next/)
- Editor configuration (.vscode/settings.json with secrets)
- Test fixtures with real data
- Binary files that bloat history

Instead, stage files by explicit name:

# Stage individual files
git add src/components/UserCard.tsx
git add src/hooks/useAuth.ts
git add tests/UserCard.test.tsx

# Stage a directory when you own every file in it
git add src/features/billing/

# Stage portions of a file interactively (when only some hunks belong in this commit)
git add -p src/utils/api.ts

If you find yourself wanting to stage 20+ files at once, stop. Consider whether this should be multiple commits with distinct purposes.

Phase 3: Write a Conventional Commit

Conventional Commit Format

<type>(<scope>): <short description>

<body — explain WHY, not what>

<footer>

Type prefixes:

Type	When to Use
`feat`	A new feature visible to users or consumers
`fix`	A bug fix
`refactor`	Code change that neither adds a feature nor fixes a bug
`test`	Adding or modifying tests only
`docs`	Documentation only
`ci`	CI/CD pipeline changes
`chore`	Maintenance, dependency updates, tooling
`perf`	Performance improvement
`build`	Build system or external dependency changes

Rules for the short description:
- Maximum 72 characters
- Imperative mood: "add feature" not "added feature" or "adds feature"
- No period at the end
- Lowercase after the colon

HEREDOC Commit Command

Always use HEREDOC to preserve exact formatting, blank lines between sections, and the Co-Authored-By trailer:

git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 PKCE flow for single-page app clients

Replaces the implicit grant flow which is deprecated in OAuth 2.1.
PKCE prevents authorization code interception attacks without
requiring a client secret, making it safe for public clients.

Closes #142

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

The 'EOF' (quoted) delimiter prevents shell variable expansion inside the message. This is correct and intentional.

Co-Authored-By Line

Always include this trailer line as the last line of the commit body:

Co-Authored-By: Claude Opus 4.6 <[email protected]>

This attributes AI assistance in the git history, which is required by many organizations for audit and compliance purposes.

Phase 4: Push with Tracking

First Push of a New Branch

Use -u to set the upstream tracking reference:

git push -u origin feat/oauth-pkce-flow

After this, subsequent pushes on the same branch only need:

git push

Safety Rules for Push

NEVER use --force or -f on shared branches (main, dev, staging)
NEVER use --force-with-lease without explicit user instruction
If the push is rejected because the remote is ahead, investigate with git log origin/<branch>..HEAD before pulling
NEVER push directly to main — always push to a feature branch and open a PR

Verify Push Success

# Confirm local and remote are aligned
git log --oneline -5
git log --oneline origin/feat/oauth-pkce-flow -5

Phase 5: Open a Pull Request

Use the GitHub CLI (gh). Never construct pull requests manually through the API unless gh is unavailable.

Pre-PR Checklist

# Verify you are on the correct branch
git branch --show-current

# Ensure the branch is pushed and tracking
git status

# Review what commits will be in the PR
git log main..HEAD --oneline

gh pr create Command

Use a HEREDOC for the body to preserve markdown formatting:

gh pr create \
  --title "feat(auth): add OAuth2 PKCE flow for SPA clients" \
  --base main \
  --head feat/oauth-pkce-flow \
  --body "$(cat <<'EOF'
## Summary

- Replaces deprecated implicit grant flow with PKCE (RFC 7636)
- Adds `generateCodeChallenge` and `generateCodeVerifier` utilities
- Updates the auth callback handler to validate the code verifier
- Removes the client secret requirement for public SPA clients

## Test Plan

- [ ] Unit tests pass: `bun test src/auth/`
- [ ] PKCE flow completes end-to-end in the dev environment
- [ ] Existing sessions are not invalidated by this change
- [ ] Token refresh still works after PKCE login
- [ ] Verify no client secret appears in browser network logs

## References

- Closes #142
- RFC 7636: https://datatracker.ietf.org/doc/html/rfc7636
- OAuth 2.1 deprecation note: https://oauth.net/2.1/

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

PR Template Sections (Always Include)

Every PR must have at minimum:

Summary — bullet list of what changed and why
Test Plan — checklist of manual and automated verification steps
References — linked issues, relevant RFCs, documentation

Optional sections when applicable:
- Breaking Changes — if the PR changes any public API or data schema
- Screenshots — for UI changes, before and after
- Migration Steps — if consumers of this code must update their usage
- Rollback Plan — for high-risk changes

Phase 6: Post-PR Steps

# Confirm the PR was created and get its URL
gh pr view --web

# List open PRs to verify
gh pr list

# Check CI status on the PR
gh pr checks

# If CI fails, push additional commits to the same branch — do NOT close and reopen
git add src/auth/pkce.ts
git commit -m "$(cat <<'EOF'
fix(auth): handle missing code_verifier in session storage

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"
git push

Output Format

When this skill completes, report:

COMMIT-PUSH-PR COMPLETE

Branch: feat/<name>
Commits: <count> new commit(s)
  - <short hash> <subject>
Push: origin/feat/<name> (tracking set)
PR: <GitHub PR URL>
Status: OPEN | DRAFT
CI: PASSING | PENDING | FAILING

Next: Resolve reviewer comments or wait for CI to pass.

Integration Notes

If a pre-commit hook fails, fix the issue and create a NEW commit — never use --no-verify to bypass hooks
If the repository uses signed commits (gpg or ssh), the HEREDOC pattern is fully compatible
For repositories that require draft PRs, add --draft to the gh pr create command
If gh is not authenticated, run gh auth login first — do not proceed without it
This skill pairs with /clean-gone to prune stale remote-tracking branches after PRs are merged

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.