Commit Push Close

commit-push-close

Four-step ship for one GitHub-issue iteration (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 to the current branch. 4. Close the GitHub issue with a comment explaining how to test it.

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 closing the issue directly.

Issue-close comment format

Posted as a comment on the issue right before closing:

Closed by <SHA> on `<branch>`.

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

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

Notes: <follow-ups or known gaps; omit line if none>

Rules for How to test:

• Concrete, runnable steps a reviewer can copy. Name the screen, command, endpoint, or button.
• If the change is UI: where to click, what to enter, what to see.
• If the change is API/server: the exact curl or request, expected status/payload.
• If the change is internal/refactor with no user-facing surface: how to verify via tests (pnpm test path/to/file, etc.) 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 posting — do not invent one.

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 (sanity-check the repo)

2. Resolve or create the issue — check, in order: branch name (e.g. feat/123-..., agent/PROJ-456-...), recent commits on this branch, conversation context. If no issue can be located, 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.

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

5. Draft the issue-close comment — summary + how-to-test from the diff (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.

6. Show the user the drafts and wait for approval before any write action. This is one combined confirmation, not three:

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

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

8. Commit with HEREDOC:

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

   Issue: #123

   Decisions:
   - ...

   Files:
   - ...
   EOF
   )"

9. Push the current branch:

• Tracks a remote → git push.
• No upstream → git push -u origin <branch>.
• If the current branch is `main` or `master`: stop and confirm separately before pushing.

10. Close the issue — capture the new commit SHA, then:

    SHA=$(git rev-parse --short HEAD)
    gh issue close <num> --comment "$(cat <<EOF
    Closed by ${SHA} on \`<branch>\`.

    **Summary**
    ...

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

Use an unquoted heredoc (<<EOF, not <<'EOF') so ${SHA} interpolates. Escape any literal backticks/$ inside the body.

11. Report — one line: <SHA> pushed to <branch>; issue #<num> closed. 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

Close comment:

Closed by a1b2c3d on `feat/204-signup-wire`.

**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

Close comment:

Closed by 9f0e1a2 on `feat/418-idempotency`.

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

**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 marking the iteration done, verify:

• [ ] Issue resolved (or created inline) + labels read/created → one category label + ready state label
• [ ] 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, 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 (or, on main/master, was confirmed separately)
• [ ] Issue closed with comment containing Summary + How to test
• [ ] 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.