/plate

Skill metadata

• License: MIT
• Source: skills/plate/SKILL.md

When to invoke: Turn finished local work into a commit, an ordinary pull request, or a stacked pull-request chain. Use when asked to commit, save changes, open or update a PR, publish a branch, create/sync/restack/submit a PR stack, or run /plate. Owns all staging, committing, pushing, PR creation, and stack-aware mutation. GitHub inspection, review, comments, CI, issues, releases, and repository administration remain /gh.

---

Plate is the final local-to-review transaction: finish required artifacts, validate, commit safely, then publish through the repository’s ordinary or stack-aware path.

Inputs and modes

• Commit-only — save local work without publishing it.
• Topology preflight — answer and persist the new-PR layout before another workflow creates commits or branches.
• New PR — no PR exists for the branch and publication is requested.
• Existing PR — update a PR while preserving its current topology.
• Stack maintenance — create, inspect, sync, restack, submit, recover, or explicitly ship a stack through its provider.

Accept --hard to run /hard-cheese immediately before the first share-for-review operation. Give that gate the final artifact inventory and verification rows, not an earlier implementation-only snapshot.

New-PR topology policy

For a new PR, resolve topology before any commit or branch-layout mutation:

1. Honor an explicit user choice from the current request or verified workflow state. It is authoritative, so persist it and skip the topology question.
2. Otherwise inspect the finished work’s review shape:
   • First classify each production change as semantics-altering (features, fixes, or externally observable contract changes) or semantics-preserving (behavior-preserving refactors, mechanical internal moves or renames, formatting-only changes). A diff containing both is never one review unit, however small: preserved behavior and changed behavior demand different review scrutiny. Fix-ups done “along the way” get their own change; they never ride along on a feature or fix. Treat any move or rename that changes an externally observable name, path, API, configuration key, serialized shape, command, or documented contract as semantics-altering.
   • Choose single and proceed without asking when the change is one cohesive review unit: its implementation, tests, docs, and durable artifacts all serve one behavior or contract, and splitting them would leave incomplete behavior or force reviewers to reconstruct the whole.
   • Recommend stacked when the change has independently reviewable ordered layers. Each layer needs a named purpose, its own validation, and a stable boundary: a lower layer can be understood on its own, and later layers build on it without mixing unrelated concerns. A change is also stack-sized when one review would combine distinct concerns that have honest ordered boundaries — canonically, a semantics-preserving layer below the semantics-altering layer that depends on the reorganization. Do not use line-count or file-count thresholds.
3. Ask one single-versus-stacked question when stacked is recommended or the review shape is genuinely ambiguous. For a stack recommendation, name the proposed layers and recommend Stacked PRs. For ambiguity, state the competing evidence and recommend the best-supported option rather than choosing silently.

This policy is unchanged under --auto. Transport any required question through ../cheese/references/ask-user-question.md.

question:
  id: plate-layout
  prompt: How should this work be plated for review?
  recommended: <single | stacked>
  multi: false
  options:
    - id: single
      label: Single PR
      description: Keep the cohesive change as one branch and one review unit.
    - id: stacked
      label: Stacked PRs
      description: Split the named layers into ordered branches and dependent PRs.

A supplied pr_plan is evidence for a stack recommendation and may provide explicit commit/file boundaries. It cannot override an explicit user choice or another verified topology resolution. If stacked is selected but neither the user nor the plan supplies clear boundaries, ask for the split rather than inventing it.

A prior /plate topology preflight for the same run is the resolution, whether it was explicit, inferred as cohesive, or confirmed after a question. Persist it as plate_layout: single | stacked in workflow state and copy it into any later pr_plan. At terminal publication, verify both values agree and reuse the resolution; do not ask twice. A missing, conflicting, or unverified record re-runs this policy rather than automatically asking.

For an Existing PR, detect its ordinary or stacked topology and do not ask the layout question. Preserve that topology and use its matching update path. Commit-only isolated workers also do not ask because publication is out of scope.

Repair-worktree topology

A branch created by the repair pathway (../cook/references/quality-gates.md § Repair pathway; branch name worktree-agent-repair-*) resolves topology through that pathway’s mechanical file-overlap check before this section’s policy: no shared files (or the originating run branch is already gone) plates an ordinary independent PR against main; shared files at or under the small-repair threshold harvest onto the run branch instead of publishing; shared files over threshold restack with the repair as the base PR through the stack machinery below. Any other branch uses the policy above unchanged.

Flow

1. Classify — commit-only, topology preflight, new PR, existing PR, or stack maintenance.
2. Resolve topology — honor an explicit choice, infer an obviously cohesive single PR, ask when stacked is recommended or shape is ambiguous, or detect existing topology from PR and stack metadata.
3. Choose the transaction:
   • Commit-only and ordinary PR work use the generic transaction below.
   • Stacked work uses the per-layer stack transaction below.
   • Topology preflight persists the resolution, reads it back, and stops before any commit, branch mutation, push, or PR operation.

Generic transaction

1. Final writing gate — inventory, write, and read back every promised or required artifact using references/durable-writes.md. Halt if any required write is missing or unverified.
2. Validate — run the repository’s shippability gate. In easy-cheese and any repo that defines it, this is just check. Never commit or publish on red.
3. Inspect — read status, diff, and recent log; verify the intended file set.
4. Stage — add named files only. Never stage the whole tree. Keep transient .cheese/ reports unstaged; include tracked wiki/docs writes.
5. Commit — use a Conventional Commit message focused on why. Do not amend unless explicitly requested and do not bypass hooks.
6. Verify — inspect status and the committed file set.
7. Publish when requested — use references/ordinary-pr.md, then read the PR back and verify it.

Commit-only mode stops after verification. It never pushes or opens a PR.

Per-layer stack transaction

1. Select the configured provider and read its reference.
2. Require explicit split boundaries. Partition paths and commits by layer; place shared durable writes on the bottom/common layer or an explicit wiring layer. Classify the production implementation decision; tests, docs, and durable artifacts inherit its layer when they directly verify or describe it. Every layer’s implementation either preserves semantics or alters them, never both, and semantics-preserving layers sit below the semantic changes that depend on their reorganization.
3. Create or adopt provider lineage in the approved bottom-to-top order.
4. For each layer, bottom to top:
   1. Check out its provider-tracked branch.
   2. Run the final writing gate for that layer and read every write back.
   3. Run the repository quality gate.
   4. Inspect the layer diff and stage only its named paths.
   5. Create a new Conventional Commit without skipping hooks.
   6. Verify the commit’s paths and the layer’s parent.
5. Inspect or restack the complete chain through the provider.
6. Submit the complete chain once all layers are verified. Read back every PR, base/head pair, and provider stack map.

Never manufacture split boundaries, move a shared artifact to a convenient upper layer, or submit a partially verified chain.

Commit contract

Before staging, inspect git status, the complete diff, and recent commits. Reject credentials, .env files, and unexplained large binaries. Stage every intended path explicitly. Use:

type(scope): short description

Optional body when the rationale needs it.

Allowed types: feat, fix, refactor, chore, docs, test, style. If a hook fails, fix it, re-run the writing and quality gates when artifacts changed, re-stage named files, and create a new commit.

Use a single-quoted heredoc delimiter for multi-line commit messages so shell interpolation cannot alter backticks or dollar signs. An optional Co-Authored-By: <name> <email> trailer may use the harness identity when the project accepts it; otherwise omit it. After staging, inspect the cached diff. If the working diff is empty, distinguish “nothing to commit” from “everything is staged” by checking the cached diff.

Structure one commit per review unit: one for a single PR, one per stack layer. Do not shape a PR for commit-by-commit review — per-commit approval state is untracked, quality gates usually run only on the branch tip, and feedback on any one commit holds the rest hostage. Multiple commits in one PR are reserved for a short series of simple, non-controversial steps that stay small taken together.

Ordinary PR publication

Read references/ordinary-pr.md. Draft the title and body from the validated diff and commits; the body labels the change as semantics-preserving or semantics-altering and states what the reviewer must verify. Write the PR body to a file and use gh pr create --body-file; never embed a markdown heredoc in --body. Push the named branch, create the PR with explicit base/head, then read it back with gh pr view to verify number, URL, base, head, and state.

Stack provider detection

Resolve metadata through GIT_DIR="$(git rev-parse --git-dir)"; never assume the repository metadata directory is the literal .git path.

Provider	Installed	Repository signal	Reference
Graphite	gt --version	$GIT_DIR/.graphite_repo_config	gt.md
Git Town	git town --version	git-town.main-branch config	git-town.md
gh stack	gh extension list contains github/gh-stack	remote enablement is detected on operation	gh-stack.md

Run probes on every invocation. If several providers are usable, preserve the one already tracking the branch. When none tracks it, prefer Graphite, then Git Town, then gh stack, and state the choice. If no provider is usable after stacked was selected, stop with setup instructions; do not emulate stacking with plain pushes.

Existing PR updates

Use gh pr view --json number,baseRefName,headRefName,url to detect the PR, then inspect provider metadata. Ordinary PR: use the generic transaction and push its named head branch. Stack: use the per-layer transaction and provider submission; never use a bare single-branch push inside the stack.

Boundaries

• /plate owns staging, commits, pushes, ordinary PR creation/update, and stack creation/update/sync/recovery. Provider-native stack shipping runs here only when the user explicitly requests the merge.
• /gh owns GitHub inspection, review, comments, CI, ordinary merge, issues, workflows, releases, search, and administration when no local publication transaction is required.
• /plate never performs code-quality review; use /age.
• Destructive deletion, history rewrites, force-push outside a provider’s lease-safe stack flow, and protected-branch mutation require explicit user authorization.

Completion

Report mode, topology/provider, artifact completion rows, quality-gate result, commit SHA(s), PR URL(s) when published, and any remaining risk.

Durable writes

Publication is forbidden until every promised artifact and every durable fact discovered during implementation has been written and read back.

Inventory

Build one list from upstream handoffs/specs, promised reports or generated files, ADR/domain-model decisions, release notes, and implementation-time architecture, convention, protocol, or gotcha knowledge. Classify each item as required or optional and tracked or transient.

Backend cascade

1. When the consumer repository exposes a hallouminate wiki, invoke the explicit user-visible /wiki-ingest handoff/capability. Do not duplicate its curation algorithm or hand-edit .hallouminate/wiki.
2. If hallouminate or /wiki-ingest is unavailable, write the tracked fallback from skills/mold/references/adr.md: docs/adr/<slug>-NNN.md. A cumulative domain model uses the repository’s existing tracked domain-model path.
3. Other promised tracked artifacts go to their contractually named paths.
4. .cheese/ reports are transient evidence. Keep them unstaged.

Verification

Read back every required write from the same backend after writing. Compare the target, essential contents, and expected revision. Emit one completion row per item in the exact shape {target, backend, verified}. verified is true only after successful read-back.

Halt before just check, staging, commit, push, or PR creation when a required write is missing, a write call failed, or read-back cannot verify it. Optional write failures are reported but never silently promoted to complete.

Stack placement

Tracked knowledge shared by every PR belongs on the bottom/common branch or an explicit wiring branch that all dependent PRs inherit. PR-specific artifacts belong on the branch whose behavior requires them. The completion rows must name that placement before the stack is submitted.

/hard-cheese handoff

When --hard is active, pass the final inventory, completion rows, tracked artifact diff, and quality-gate result into /hard-cheese before publication.

gh stack publication

Use when the github/gh-stack extension is installed and the repository accepts its remote operations. Exit code 4 means the GitHub API or preview is unavailable; halt and report the enablement requirement.

Initialize and inspect

Initialize or adopt with:

gh stack init --base <trunk>
gh stack init --adopt --base <trunk>
gh stack init --prefix <prefix> --numbered --base <trunk>

--numbered requires --prefix. Add branches with gh stack add <branch> without combined staging/commit flags, stage named paths, and create normal new commits. Inspect with gh stack view --short or gh stack view --json.

Resolve local tracking paths from GIT_DIR="$(git rev-parse --git-dir)". Tracking lives at $GIT_DIR/gh-stack; rebase recovery state lives at $GIT_DIR/gh-stack-rebase-state. Neither is committed.

Remote selection and publication

Select the intended remote explicitly when it is not unambiguously origin. Use the same --remote <name> on push, submit, sync, and link operations.

Publish all branches and PRs with gh stack submit --auto --open --remote <name> after Plate has resolved stacked topology and every title/body is known. Here --auto skips only provider metadata prompts; it never overrides Plate’s explicit-choice and review-shape policy. Omit --open for drafts.

Use gh stack push --remote <name> only to update an already-created stack without changing PR metadata. Both operations are stack-aware and lease-safe; never use a bare single-branch push.

Install, authenticate, and detect

• Install with gh extension install github/gh-stack; upgrade using gh extension upgrade gh-stack.
• Use full gh stack commands; do not assume the optional gs alias.
• Authenticate through gh auth login; the extension uses OAuth, not personal access tokens.
• Detect via gh extension list. Repository enablement has no documented preflight; translate remote exit code 4 into the API/preview failure.
• Resolve all local metadata with git rev-parse --git-dir.

Command map

Need	Command
Initialize/adopt	gh stack init [--adopt] [--base <branch>] [--prefix <text> --numbered]
Add top branch	gh stack add <branch>
Inspect	gh stack view --short or gh stack view --json
Pull collaborator stack	gh stack checkout <PR-or-branch>
Push branches only	gh stack push --remote <name>
Create/update PRs	gh stack submit [--auto] [--open] --remote <name>
Sync remote/local state	gh stack sync --remote <name>
Cascade local rebase	gh stack rebase
Reorder/drop/rename/fold	gh stack modify
Link existing branches/PRs	gh stack link --base <base> --remote <name> <items...>
Remove stack tracking	gh stack unstack
Navigate	gh stack up, down, top, bottom, or switch

submit defaults new PRs to draft; --open marks them ready for review. push updates branches without PR metadata. link creates the server relationship without adopting local tracking.

Exit handling

Code	Meaning	Response
0	Success	Verify stack and PRs
1	Generic error	Preserve stderr and halt; do not reinterpret
2	Not in a stack	Re-detect or adopt; do not emulate
3	Rebase conflict	Use provider recovery
4	API/preview unavailable	Report enablement or auth
5	Invalid arguments or flags	Read installed-command help, correct input, retry once
6	Ambiguous membership	Ask which stack
7	Rebase active	Resume or abort provider operation
8	Stack locked	Wait; do not mutate concurrently

Unknown non-zero exits are failures: preserve the command, code, and stderr, then halt rather than treating them as success.

Conflict recovery

On a rebase conflict, resolve and stage named paths, then use gh stack rebase --continue or gh stack rebase --abort. A bare git rebase --continue is never correct because gh stack must update its rebase state. For modify conflicts, use gh stack modify --continue or gh stack modify --abort.

Plate recipes

Create a two-layer stack

1. Initialize the bottom with gh stack init --base <trunk>.
2. Write common artifacts, validate, stage named paths, and commit.
3. Add the top branch, then repeat the transaction for top-specific work.
4. Inspect with gh stack view --json.
5. Submit with explicit remote and verify the stack map and every PR/base pair.

Update a lower layer

Navigate down, create a new commit, run gh stack rebase, inspect, then use push or submit according to whether PR metadata changed.

Link externally managed branches

Use gh stack link --base <base> --remote <name> <branches-or-PRs>. This does not adopt local tracking.

After a bottom PR merges

Run gh stack sync --remote <name>, inspect the stack, and submit again only when local commits remain unpublished. GitHub enforces bottom-up merges and cascades the remaining branches server-side.

Shared durable writes belong on the bottom/common branch or explicit wiring branch before submission. Confirm uncertain syntax with gh stack <command> --help.

Git Town publication

Use when git-town is installed and git-town.main-branch is configured. Lineage lives in local git-town-branch.<name>.parent config.

Mandatory agent mode

Append --non-interactive to every state-changing Git Town command and supply names, parents, messages, and merge choices explicitly. Use --dry-run first for risky sync or reorganization when supported. If required input is missing, stop and ask; never allow an agent-run command to wait on a prompt.

Start the bottom branch with git town hack <name> --non-interactive and extend with git town append <name> --non-interactive. Stage named paths and create normal new commits; avoid combined all-files or rewrite flags.

Inspect with git town branch. Publish the chain with git town propose --stack --non-interactive. Sync/restack with git town sync --stack --non-interactive; use --no-push only when publication is not authorized. Never push one stack branch directly.

Install, configure, and detect

• Install with brew install git-town, choco install git-town, or scoop install git-town; check git town --version.
• Configure with git town config setup, or set trunk directly using git config --local git-town.main-branch <trunk>.
• On GitHub, prefer git-town.github-connector gh to reuse authenticated CLI access; environment tokens are preferable in ephemeral systems.
• Usability requires the executable and a non-empty git-town.main-branch. Inspect parents with git config --get-regexp '^git-town-branch\.'.
• Resolve repository metadata with git rev-parse --git-dir when inspecting git-owned state; never assume a literal metadata path.

Git Town is forge-agnostic. Configure git-town.forge-type when forge auto-detection is wrong.

Branch creation, types, and configuration

Need	Command
Start bottom from trunk	git town hack <name> --non-interactive
Extend current stack	git town append <name> --non-interactive
Insert below current	git town prepend <name> --non-interactive
Create local-only work	add --prototype to hack/append/prepend
Record/change parent	git town set-parent <parent> --non-interactive
Detach as perennial	git town set-parent --none --non-interactive
Inspect lineage/types	git town branch
Read a parent	git town config get-parent [branch]
Rename	git town rename <name> --non-interactive
Delete	git town delete --non-interactive; explicit approval required
Interrupted state	git town status --pending

Branch types are feature, prototype, parked, contribution, and observed, stored in git-town-branch.<name>.branchtype. Long-lived shared branches belong in git-town.perennial-branches. Repository defaults may live in git-town.toml; forge/auth settings use git-town.forge-type, git-town.github-connector, and the matching token setting or environment variable.

Prototype branches remain local until proposed. Do not silently convert a prototype to a published feature branch.

Sync variants

Scope or behavior	Command
Current branch	git town sync --non-interactive
Current stack	git town sync --stack --non-interactive
Every branch	git town sync --all --non-interactive
Skip trunk/perennial pull-in	git town sync --detached --non-interactive
Restack locally without push	git town sync --stack --no-push --non-interactive
Prune branches that become empty	git town sync --prune --non-interactive
Open/update stack PRs	git town propose --stack --non-interactive

Use --all, --detached, and --prune only when their wider scope or deletion behavior is intended and verified.

Ship

git town ship --non-interactive merges the current branch through the forge. --to-parent ships into a non-perennial parent; an explicit message can be provided when required. Prefer the forge UI plus git town sync --stack --non-interactive for routine merges. Run ship through Plate only when the user explicitly requested provider-native stack shipping, verify the target and merge strategy, and confirm the installed syntax with git town ship --help.

Conflict recovery

When sync, propose, or ship halts, inspect git town status --pending. Resolve and stage named paths, then use git town continue, git town skip, or git town undo as directed by the pending operation. A bare git rebase --continue is never correct because it does not advance Git Town’s branch walk.

Git Town can force-update rebased stack branches; coordinate when teammates also write them. Shared durable writes belong on the bottom/common branch or an explicit wiring branch before propose or sync.

Plate recipes

Create a two-layer stack

1. Run git town hack <bottom> --non-interactive.
2. Write common artifacts, validate, stage named paths, and commit.
3. Run git town append <top> --non-interactive; repeat for top-only work.
4. Run git town branch to verify parents.
5. Run git town propose --stack --non-interactive, then verify PR bases.

Adopt an existing branch

Sync it, set its parent non-interactively, inspect lineage, append branches if requested, then propose the stack.

Update a lower branch

Switch to it, create a new commit, then sync the stack non-interactively so descendants and remote PRs follow.

Squash merges can create phantom conflicts because child history no longer matches the merged commit. Configure git-town.auto-resolve or use a compatible merge strategy when the repository accepts it. Confirm version-specific syntax with git town <command> --help.

Graphite publication

Use when gt is installed, Graphite tracks the current stack, and test -f "$(git rev-parse --git-dir)/.graphite_repo_config" succeeds.

Agent-safe discipline

Graphite is interactive by default. Pass --no-interactive and supply branch names, messages, bases, and reviewers explicitly. If an operation still needs an editor or picker, stop and ask rather than hanging or guessing.

Create branches with gt create <name> without all-files commit flags. Stage named paths, then create a normal new commit. For a tracked branch update, gt modify -c -m "<message>" creates a new commit and restacks descendants. Bare gt modify amends; use it only when the user explicitly requests a history rewrite. Hooks remain enabled.

Inspect with gt log short. Restack with gt restack; sync trunk and prune merged branches with gt sync. Submit the whole chain with gt submit --stack. Its lease-aware push is the publication path; do not push one stack branch separately.

Install, authenticate, and detect

• Install with brew install withgraphite/tap/graphite or npm install -g @withgraphite/graphite-cli@stable.
• Check gt --version; use gt upgrade on supported releases.
• Authenticate with gt auth --token <token>; ephemeral environments prefer GRAPHITE_AUTH_TOKEN.
• Initialize once with gt init; it records trunk at $(git rev-parse --git-dir)/.graphite_repo_config.
• The provider is usable only when the executable and resolved marker exist.

Command map

Need	Command
Start/extend a stack	gt create <name>
Adopt an existing branch	gt track --parent <parent>
Remove tracking	gt untrack
Inspect	gt log short or gt ls
Navigate	gt up, gt down, gt top, gt bottom
Check out	gt checkout <branch>
New commit + restack	gt modify -c -m "<message>" after named staging
Restack descendants	gt restack
Fetch trunk, prune, restack	gt sync
Submit all PRs	gt submit --stack
Update open PRs only	gt submit --stack --update-only
Preview	gt submit --stack --dry-run

Submission may add --draft, --publish, or explicit reviewers. Retain the default lease check rather than selecting true force.

Reorganization

Use Graphite commands so lineage remains correct:

Need	Command and rule
Move a branch and descendants	gt move --onto <parent>
Reorder	gt reorder; user-driven editor only
Split	gt split -c, gt split -h, or gt split -f; verify every resulting boundary
Absorb staged hunks downstack	gt absorb after named staging; keep confirmation enabled
Fold into parent	gt fold; explicit history-rewrite approval required
Squash current layer	gt squash; explicit history-rewrite approval required
Remove branch, keep changes	gt pop; explicit destructive approval required
Undo last Graphite mutation	gt undo; inspect before and after
Delete branch	gt delete; explicit branch-deletion approval required

After any split, absorb, move, fold, squash, pop, or undo, inspect gt log short, validate affected layers, and resubmit only after lineage and commit paths match the approved split.

Collaboration, frozen branches, and multiple trunks

gt get <branch> fetches a collaborator’s submitted stack. Retrieved branches are frozen by default; inspect them without mutation. Use gt unfreeze only after the user confirms ownership/coordination, and gt freeze to restore the read-only collaboration posture. gt get -U opts into immediate editability; never choose it silently.

For repositories with several trunks, add one with gt trunk --add <branch>. Use gt log --all or gt checkout --all for cross-trunk inspection, but select the intended trunk explicitly before creating lineage. Graphite refuses to mutate a branch checked out in another worktree; report that worktree rather than bypassing the refusal. gt undo history is per worktree.

Conflict recovery

Resolve and stage each conflicted path by name, then run gt continue or gt abort. A bare git rebase --continue is never the recovery path because Graphite must advance its stack metadata. There is no documented gt skip; abort and isolate the branch instead.

Plate recipes

Create a two-layer stack

1. From clean trunk, run gt create <bottom>.
2. Write bottom/common artifacts, validate, stage named paths, and commit.
3. Run gt create <top>; repeat the per-layer transaction for top-only work.
4. Inspect with gt log short.
5. Publish with gt submit --stack and verify every PR/base pair.

Update a lower layer

Check out the lower branch, stage named paths, create a new commit with gt modify -c, run gt restack, inspect, then gt submit --stack.

After the bottom PR merges

Run gt sync, inspect gt log short, then submit only if local commits remain unpublished.

Shared durable writes belong on the bottom/common branch or an explicit wiring branch. Confirm version-specific syntax with gt <command> --help.

Ordinary PR publication

Use this path only after the final writing gate, green project gate, named-file staging, commit, and commit verification.

New PR

1. Confirm /plate resolved the new PR as single: explicitly, by cohesive-shape inference, or after a user question.
2. Resolve trunk and current branch; reject publication from trunk.
3. Draft a title and body covering purpose, verification, durable artifacts, and residual risks.
4. Write the body to a temporary or transient file and pass --body-file.
5. Push the named branch without force.
6. Create with explicit base and head:

gh pr create --title "<title>" --body-file <body-path> --base <base> --head <head>

1. Verify with gh pr view --json number,url,title,baseRefName,headRefName,state.

Do not use --fill when it would omit artifact or verification details.

Existing ordinary PR

Do not ask the layout question. Read its base/head with gh pr view, commit the validated named files, push the exact head branch, then read the PR back. Update title/body only when the new work makes existing metadata inaccurate.

Failures

Authentication or permission failures halt publication with the exact command and error. A rejected push is not permission to force-push: fetch and explain the divergence. Never create a duplicate PR when one already exists.

Metadata and lifecycle

Publication-relevant GitHub operations remain here:

• Add --draft when explicitly requested.
• Add --reviewer <login> or --assignee <login> only from supplied publication metadata.
• Use gh pr edit <number> --title <title> --body-file <path> when verified commits make existing metadata inaccurate.
• Use gh pr ready <number> only when asked to publish a draft.
• gh pr checks may verify publication context; CI triage, review, comments, and merge remain /gh.

Query the current head for an existing PR before creation. If found, switch to the existing-PR path rather than relying on a failed create call.

Body contract

Record purpose, user-visible behavior, test/gate results, durable artifact completion rows, risks, follow-ups, and any stack relationship. Keep the body file transient unless the repo explicitly tracks PR templates or release artifacts; leave it unstaged after verification.

Write for the reviewer’s verification pass:

• A semantics-preserving change (behavior-preserving refactor, mechanical internal move or rename with no public contract change, formatting-only change) says so in its first line, names the mechanism, and states the invariant to verify: behavior unchanged, plus a mechanism-specific check such as nothing dropped or duplicated during a move. This tells the reviewer to scan for accidental semantic drift rather than infer intent line by line.
• A semantics-altering change names the behavior or contract that changed and its observable verification, so scrutiny lands on the changed logic rather than on inferring intent line by line.
• A change that is not self-contained links its context — spike branch, plan, or the stack siblings that show the abstraction in use — instead of leaving the reviewer to ask what it is for.

Push verification

Read remote/upstream before pushing. Push the exact named head branch. Verify local status and the PR’s head/base. A successful CLI exit without a matching PR head SHA is incomplete.