Commit Push Pr

commit-push-pr

Ship one GitHub-issue iteration as a reviewable PR (with an inline create-if-missing step for the issue):

1. Resolve or create the GitHub issue. 2. Commit the diff with a structured message. 3. Push the current branch (auto-create one off main/master first). 4. Open a PR with Closes #N, a summary, and a how-to-test plan.

Shared ship policy

Read `references/ship-policy.md` first. It holds the rules both ship skills share and that this workflow depends on: Label validation, Authorship policy, Env parity policy, Inline issue creation, Naming anchor, Commit message format, Pre-commit safety, and the Response footer. This SKILL.md only covers what is specific to opening a PR.

PR title and body

Title mirrors the commit subject:

<same text as commit subject>

Body:

Closes #<num>

## Summary
<one or two sentences — what changed and why>

## Decisions
- <only non-obvious choices; omit section if none>

## How to test
1. <step>
2. <step>
3. <expected result>

## Notes
- <follow-ups or known gaps; omit section if none>

Rules for How to test:

• Concrete, runnable steps a reviewer can copy. Name the screen, command, endpoint, or button.
• UI: where to click, what to enter, what to see.
• API/server: exact curl or request, expected status/payload.
• Internal/refactor with no user-facing surface: pnpm test path/to/file (or equivalent) plus what should still work end-to-end.
• 3–6 steps. If you can't write a real test plan from the diff, ask the user before opening the PR — do not invent one.

The Closes #N line is mandatory and must be on its own line near the top of the body so GitHub auto-links and auto-closes the issue on merge. If linking multiple issues, list them as Closes #1, closes #2 (each needs its own closes keyword).

Workflow

1. Read state — run in parallel:

• git status (no -uall)
• git diff (staged + unstaged)
• git log -5 --oneline
• git branch --show-current
• git remote get-url origin
• Detect default branch: gh repo view --json defaultBranchRef -q .defaultBranchRef.name (fallback: main).

2. Resolve or create the issue — branch name → recent commits → conversation context. If none, switch to Inline issue creation (references/ship-policy.md) for valid small ad hoc work, then use the returned number for the rest of the workflow (commit Issue: line, PR Closes #<num>).

3. Read issue labels — for issues that already existed, run gh issue view <num> --json state,labels,title,url and validate against the Label validation table in references/ship-policy.md. If labels are missing/conflicting or the state is needs-triage, needs-info, or wontfix, stop and route back to /triage. For issues just created inline, skip this step — labels were set at creation.

4. Branch handling — if the current branch is main or master (or the detected default branch):

• Stop before staging anything.
• Propose a feature branch name: issue/<issue-num>-<slug> where <slug> is a short kebab-case derivation of the issue title (≤ 5 words).
• Wait for the user to confirm the name (offer to edit).
• git checkout -b <branch> — uncommitted changes follow the checkout into the new branch.

Otherwise, continue on the current branch.

5. Draft the commit message from the issue title and diff, per Commit message format in references/ship-policy.md. For ad hoc inline issues, the new issue title and commit subject must match (see Naming anchor).

6. Draft the PR title and body — title mirrors the commit subject with no routing marker; body has Closes #N, summary, optional decisions, how-to-test, optional notes (format above). If the test plan isn't obvious, ask the user before continuing.

Before presenting drafts, run the Authorship policy scrub and, if env files/keys changed, the Env parity policy sync pass — both in references/ship-policy.md.

7. Show the user the drafts and wait for one combined approval. Do not stage, push, or call gh pr create before approval:

• Existing issue: commit message + PR title + PR body.
• Inline-created issue: new-issue title + new-issue body + chosen category/state labels + commit message + PR title + PR body. After approval, create the issue first, then commit/push/PR in order.

8. Pre-commit safety — apply every check in Pre-commit safety (references/ship-policy.md) before staging.

9. Commit with HEREDOC:

   git commit -m "$(cat <<'EOF'
   <subject>

   Issue: #123

   Decisions:
   - ...

   Files:
   - ...
   EOF
   )"

10. Push the current branch:

• Tracks a remote → git push.
• No upstream → git push -u origin <branch>.

11. Open the PR against the detected default branch:

    gh pr create \
      --base "<default-branch>" \
      --head "<current-branch>" \
      --title "<subject>" \
      --body "$(cat <<'EOF'
    Closes #123

    ## Summary
    ...

    ## How to test
    1. ...
    2. ...
    3. ...
    EOF
    )"

• If a PR already exists for this branch (gh pr list --head <branch> --json number), do not create a duplicate. Update the existing PR's title/body with gh pr edit <num> instead, and report that path back.

12. Report — one line: <SHA> pushed to <branch>; PR #<pr-num> opened (Closes #<issue-num>). Then append the Response footer from references/ship-policy.md (1-6 advisory suggestions).

Examples

Minimal

Commit:

wire signup form to /api/users

Issue: #204

Files:
- app/signup/page.tsx — submit handler + error state
- lib/api/users.ts — POST /users client

PR title: wire signup form to /api/users

PR body:

Closes #204

## Summary
Signup form now POSTs to /api/users and surfaces server errors inline.

## How to test
1. `pnpm dev`, open http://localhost:3000/signup
2. Submit with a duplicate email — expect inline "email already in use"
3. Submit with a fresh email — expect redirect to /welcome

Full

Commit:

add idempotency keys to checkout flow

Issue: #418

Decisions:
- Stored keys in Redis (24h TTL) over Postgres — read path is hot
- Reused existing `x-request-id` header instead of a new one

Files:
- server/checkout/handler.ts — key check before charge
- server/checkout/handler.test.ts — replay + race tests
- infra/redis.ts — TTL helper

Notes:
- Stripe webhook path still unguarded — next iteration

PR title: add idempotency keys to checkout flow

PR body:

Closes #418

## Summary
Checkout charges are now idempotent on `x-request-id`; replays return the original result instead of double-charging.

## Decisions
- Stored keys in Redis (24h TTL) over Postgres — the read path is hot
- Reused existing `x-request-id` header instead of introducing a new one

## How to test
1. `pnpm test server/checkout/handler.test.ts` — all green
2. Hit `POST /checkout` twice with the same `x-request-id` — second call returns the first response, no second Stripe charge
3. Hit twice with different IDs — two distinct charges as before

## Notes
- Stripe webhook path still unguarded — see follow-up #419

Checklist

Before reporting done, verify:

• [ ] Issue resolved (or created inline) + labels read/created → one category label + ready state label
• [ ] If on default branch, a feature branch was created and confirmed
• [ ] Commit subject mirrors the GitHub issue title as closely as practical and has no routing marker
• [ ] Issue: line present in commit body
• [ ] No co-author or AI/tool attribution text in commit message, PR title/body, issue content, comments, release notes, or docs
• [ ] If env keys changed: .env, .env.staging, .env.production were synchronized for add/remove/change operations
• [ ] If env keys changed: .sample.env or .example.env updated with latest keys + safe placeholders
• [ ] If env keys changed: README/docs references updated; any gitignored env files were still updated locally and reported
• [ ] No secret files staged
• [ ] Hooks ran (no --no-verify)
• [ ] Push succeeded with upstream set
• [ ] PR body has Closes #<num> on its own line near the top
• [ ] PR body has Summary + How to test
• [ ] No duplicate PR created (existing PR was edited instead)
• [ ] Final report line printed
• [ ] Optional Suggested next skills footer included (1-6 advisory suggestions, no gating)

Shared Ship Policy

Shared rules for the commit-push-close and commit-push-pr skills. Both ship one GitHub-issue iteration; they differ only in the final step (close the issue with a comment vs. open a PR with Closes #N). Everything in this file applies to both.

Where a rule says ship output, it means the commit message plus the skill's final artifact — the issue-close comment for commit-push-close, or the PR title and body for commit-push-pr.

This file is duplicated in both commit-push-close/references/ and commit-push-pr/references/ so each skill installs self-contained. Keep the two copies byte-identical when editing.

Label validation

Routing state lives in the linked issue's labels. Do not add HITL: or AFK: to commit subjects, branch names, PR titles, or GitHub issue titles.

Read state with: gh issue view <num> --json state,labels,title,url. Match label names exactly.

Authorship policy (all supported coding agents)

Apply this policy to outputs from every supported coding-agent path: Codex CLI, Claude CLI, Antigravity CLI, Cursor CLI, Opencode CLI, and GitHub Copilot CLI.

• Never keep co-author, generated-by, or AI attribution text in authored output.
• Forbidden patterns include Co-authored-by:, Co-Authored-By:, Made with [Cursor], Made-with:, Generated by, AI-assisted, and agent signature footer lines.
• If any tool auto-injects attribution, scrub and regenerate the draft before presenting it and before running any commit/close/PR command.

Env parity policy (.env family + sample/example + docs)

When env keys are touched in any way (add/remove/rename/value-contract change), enforce all of the following in the same iteration:

• Keep key sets synchronized across .env, .env.staging, and .env.production (do not update only one file).
• Keep .sample.env or .example.env updated with the latest keys and safe placeholder values.
• Update README/docs where env keys, setup steps, or env behavior are referenced.
• If .env.staging / .env.production are gitignored in that repo, still update local filesystem copies and report them explicitly as local-only updates.

Inline issue creation

Inline issue creation is only for small ad hoc work that started from a short request with no linked GitHub issue. Planned work should already have gone through /to-prd and /to-issues; if a planned issue is missing, not ready, ambiguous, cross-project, or multi-slice, stop and route back to /feature-prompt or /to-issues instead of fabricating a ship-time issue. Use /triage only when an existing issue needs label/state repair, reporter follow-up, ready-for-human, wontfix, or an agent brief.

Do not use the ship flow to resolve planning ambiguity. If scope is still broad or unclear, route to /feature-prompt first. If blockers are high-fidelity ("needs to feel/see it"), route to /handoff + /prototype before returning to ship.

When the workflow can't locate an issue for valid ad hoc work, create one before committing. Do not invent an issue number, and do not continue without an issue.

1. Draft from the diff:

• Title — imperative, concise, no HITL:/AFK: marker. This title becomes the commit subject (and the PR title when shipping as a PR), so make it specific and traceable.
• Body — generate from the original request, final diff, decisions made during the fix, files changed, and validation/how-to-test. Keep under ~20 lines.

2. Choose labels:

• Category: bug for broken behavior; enhancement for new feature/improvement. If unclear, ask.
• State: ready-for-agent when the agent completed the work autonomously; ready-for-human when human judgment, external access, or manual review was required.

3. Show the user the draft (title + body + chosen labels) and wait for approval. Fold this into the single combined approval in the workflow — don't ask twice. 4. Create with:

   gh issue create \
     --title "<title>" \
     --body "$(cat <<'EOF'
   <body>
   EOF
   )" \
     --label "<category-label>" \
     --label "<state-label>"

5. Capture the returned issue number from the URL/output and use it as <num> for the rest of the workflow. Skip the "read state" call — the label was set at creation.

Naming anchor

Use the GitHub issue title as the naming anchor:

• Existing issue: commit subject (and PR title, when shipping as a PR) should match the issue title as closely as practical.
• PRD slice issue: preserve Slice NNNN, <PROJECT-CODE>, ADR-<adr-number>, (#<prd-issue-number>), and the short heading. If the full Slice NNNN of <PROJECT-CODE> ADR-<adr-number> <adr-name> (#<prd-issue-number>): <Short heading> title is too long for a commit subject, shorten only the <adr-name> portion; keep the slice number, project code, ADR number, PRD issue number, and short heading intact.
• Ad hoc inline issue: the new issue title, commit subject, and PR title (when shipping as a PR) must be the same text unless a hard tool limit prevents it.
• Never add HITL: or AFK: to any of these names.

Commit message format

<issue title or closest practical match>

Issue: #<num>

Decisions:
- <key decision 1>
- <key decision 2>

Files:
- <path> — <one-line why>
- <path> — <one-line why>

Notes:
- <blocker, follow-up, or signal for next iteration>

Rules:

• Subject mirrors the GitHub issue title as closely as practical, no HITL: or AFK: marker.
• Always keep the subject and the Issue: line. Omit any other section that has nothing to say.
• Never add co-author or AI/tool attribution anywhere in authored output (commit message, PR title/body, issue body, comments, release notes, docs) across all supported coding agents.
• Files: lists meaningful changes, not every touched file.
• Notes: is for the next iteration. Skip if truly nothing.
• Body under ~20 lines.

Pre-commit safety

• Refuse to stage secret-pattern files by default: .env, .env.* (except .env.example), *.pem, *.key, id_rsa*, credentials*.json, *secret*.
• Exception for repo-approved env templates/config maps: only stage .env / .env.staging / .env.production when they are intentionally tracked, non-secret, and explicitly user-approved.
• Stage explicitly by path — never git add -A / git add ..
• Verify the ship output (commit message plus the issue-close comment or PR title/body) contains no co-author or AI/tool attribution text (Co-authored-by:, Made with [Cursor], Made-with:, Generated by, AI-assisted, or similar signature lines).
• For env-key changes, verify key parity across .env, .env.staging, .env.production; verify .sample.env or .example.env key parity; verify README/docs references are updated.
• If .env.staging / .env.production are gitignored, confirm local filesystem copies were still updated and report that local-only status.
• Honor hooks. Never --no-verify. If a hook fails, fix the underlying issue and create a NEW commit (do not amend).

Response footer

End the final response with Suggested next skills (optional) containing 1-6 advisory recommendations. Keep it recommendation-only (no gating). Choose next steps from workflow context, for example /release-notes, /handoff, or /triage.