plate · diff
git:20260827.5206cb9 to git:20260905.0a0b1f7
107 added, 231 removed. Audit A to A.
---
name: plate
description: >
- 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.
+ Turn finished local work into a commit, an ordinary pull request, or a pull request stack.
+ Use this skill to commit changes or to publish a branch. Use it to open or update a pull request.
+ Use it to create, sync, restack, or submit a pull request stack. You can also run /plate.
+ This skill owns all staging, commits, pushes, pull request creation, and stack changes.
+ /gh owns GitHub inspection, reviews, comments, CI, issues, releases, and repository administration.
license: MIT
---
# /plate
- 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.
+ Plate completes local work before review. It finishes required artifacts, validates, commits safely, and selects the correct publication path.
- ## Inputs and modes
+ ## Routing guard
- - **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.
+ Check ownership before you select a mode.
+ `/plate` owns staging, commits, pushes, ordinary pull request changes, and pull request stack changes.
- 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.
+ - `/plate` never performs code-quality review. It never computes a review surface for its own sake. Review is `/age`.
+ - `/gh` owns GitHub inspection, reviews, comments, CI, merges, issues, workflows, releases, search, and administration.
+ Use `/gh` when no local publication transaction is necessary.
+ - A request that only reads or assesses GitHub or diff state leaves `/plate` before any mode is selected.
+ Thus, routing it here is a plate-owned failure.
+ - Destructive deletion, history rewrites, unsafe force-pushes, and protected-branch changes require explicit user authorization.
- ## New-PR topology policy
+ ## Classify, then load one reference
- For a **new PR**, resolve topology before any commit or branch-layout mutation:
+ Classify every invocation into exactly one mode. Load one reference at a time. Do not read the others.
- 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.
+ | Mode | Trigger | Load |
+ | --- | --- | --- |
+ | Commit-only | Save local work without publishing it | [`references/durable-writes.md`](references/durable-writes.md) |
+ | Topology preflight | Persist the new-PR layout before another workflow creates commits or branches | [`references/topology.md`](references/topology.md) |
+ | New PR | No PR exists for the branch and publication is requested | [`references/topology.md`](references/topology.md) |
+ | Existing PR | Update a PR while preserving its current topology | [`references/ordinary-pr.md`](references/ordinary-pr.md) |
+ | Stack maintenance | Create, sync, restack, submit, recover, or explicitly ship a stack | [`references/stacks.md`](references/stacks.md) |
- This policy is unchanged under `--auto`. Transport any required question
- through
- [`../cheese/references/ask-user-question.md`](../cheese/references/ask-user-question.md).
+ Inspect a stack only as a step of a requested stack change. Route a stack inspection request without a requested change to `/gh`.
- ```yaml
- 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.
- ```
+ New-PR work loads its references in this sequence. Load each reference alone. Close it before you load the next one.
- 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.
+ 1. Load `references/topology.md`. Resolve the topology.
+ 2. Load `references/ordinary-pr.md` for single topology. Load `references/stacks.md` for stacked topology.
+ 3. Load exactly one provider reference from `references/stacks.md` for stacked topology.
+ The provider references are [`gt.md`](references/gt.md), [`git-town.md`](references/git-town.md), and [`gh-stack.md`](references/gh-stack.md).
- 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.
+ When an existing pull request uses a stack, load `references/stacks.md`. Do not use a bare single-branch push.
- 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.
+ ## Hard gate
- ### Repair-worktree topology
+ Accept `--hard` to run `/hard-cheese` immediately before you first share the work for review.
+ Give that gate one JSON context. Include the final artifact inventory, the completion rows, the tracked artifact diff digest, and the quality gate result.
+ Do not give it an earlier implementation snapshot.
- A branch created by the repair pathway
- ([`../cook/references/quality-gates.md`](../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.
+ Read the gate status. Then apply this matrix:
- ## Flow
+ | Gate status | Response |
+ | --- | --- |
+ | `PASS` | Continue to publication |
+ | `LOGGED` | Continue to publication. Record the logged findings in the pull request body |
+ | `ERROR` | Ask the user before you publish. Report the gate error |
+ | `FAILED` | Halt at `quality gate`. Do not publish. Fix the work |
- 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.
+ Ask the `ERROR` question through the shared question transport.
+ See [`../cheese/references/ask-user-question.md`](../cheese/references/ask-user-question.md).
## Tool routing
- - Run `python3 skills/plate/scripts/plate.pyz stack-tools` before
- selecting a stack provider. It probes Graphite, Git Town, and `gh stack`
- without mutating repository state.
- - Use Git and GitHub or the selected provider CLI for repository, remote, PR,
- and stack state.
- - Use the repository code-intelligence backend for tracked artifact edits and
- read-back; use named paths and stale-safe writes instead of shell redirects.
- - Route durable wiki knowledge through `/wiki-ingest`; never hand-edit the
- Hallouminate tree.
- - Keep transient completion and PR-body files under `.cheese/` and unstaged.
-
- ### Generic transaction
-
- 1. **Final writing gate** — inventory, write, and read back every promised or
- required artifact using
- [`references/durable-writes.md`](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. When the repo
- has a hallouminate wiki, sweep `git status` for uncommitted
- `.hallouminate/wiki/` paths — including writes from earlier in the session —
- and stage them unless gitignored. Wiki updates ship with this publication,
- never after it.
- 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`](references/ordinary-pr.md), then read the PR
- back and verify it.
+ - Run `python3 skills/plate/scripts/plate.pyz stack-tools` before you select a stack provider.
+ The command detects Graphite, Git Town, and `gh stack`. It does not change repository state.
+ - Use Git and GitHub for repository, remote, and PR state. Use the selected provider CLI for stack state.
+ - Use the repository code-intelligence backend to edit tracked artifacts. Use the same backend to read them.
+ Select the backend with [`code-intelligence-routing.md`](../cheese/references/code-intelligence-routing.md).
+ Follow this sequence from [`references/durable-writes.md`](references/durable-writes.md): fresh tagged read, one stale-safe write, diff read-back.
+ Use named paths. Do not use shell redirects.
+ - Send durable wiki knowledge through `/wiki-ingest`. Do not edit the Hallouminate tree directly.
+ - Keep temporary completion and PR-body files under `.cheese/`. Do not stage them.
+ - Slash commands are host renderings, not the control model. Name the capability before you show a host example.
+ See [`../cheese/references/harness-portability.md`](../cheese/references/harness-portability.md).
- Commit-only mode stops after verification. It never pushes or opens a PR.
+ ## Generic transaction
- ### Per-layer stack transaction
+ Commit-only work and ordinary PR work use this transaction. Stacked work uses the per-layer transaction in `references/stacks.md`.
- 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.
+ 1. **Final writing gate** — List every promised or required artifact. Write each artifact. Read each artifact back.
+ Follow [`references/durable-writes.md`](references/durable-writes.md). Stop if a required write is missing or unverified.
+ 2. **Validate** — Run the repository's quality gate. Use `just check` in easy-cheese or any repository that defines it.
+ Do not commit or publish when the quality gate fails.
+ 3. **Inspect** — Read the status, complete diff, and recent log. Verify the intended file set.
+ 4. **Stage** — Add only named files. Do not stage the full tree.
+ Keep temporary `.cheese/` reports unstaged. Include tracked wiki and documentation changes.
+ If the repository has a Hallouminate wiki, inspect `git status` for uncommitted `.hallouminate/wiki/` paths.
+ Include writes from earlier in the session. Stage these writes unless Git ignores them.
+ Publish wiki updates with this transaction. Do not publish them later.
+ 5. **Commit** — Use a Conventional Commit message that explains the reason. Do not amend unless the user requests it.
+ Do not bypass hooks.
+ 6. **Verify** — Inspect the status and the committed file set.
+ 7. **Publish when requested** — Follow [`references/ordinary-pr.md`](references/ordinary-pr.md). Read the PR after publication. Verify it.
- Never manufacture split boundaries, move a shared artifact to a convenient
- upper layer, or submit a partially verified chain.
+ Commit-only mode stops after verification. It does not push or open a PR.
## 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:
+ Reject credentials, `.env` files, and unexplained large binaries. Stage every intended path explicitly.
+ Use this format:
```text
type(scope): short description
Optional body when the rationale needs it.
```
- Write the message BLUF and newscaster-flat: the subject states the change up
- front, the optional body carries only the facts a reviewer needs, and nothing
- else — short, concise, no narrative prose, tone, or slang.
-
- 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`](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
+ Write the subject first. Use a neutral tone. State the change first in the subject.
+ Put only required reviewer facts in the optional body. Keep the body short. Omit narrative prose, tone, and slang.
- Resolve metadata through `GIT_DIR="$(git rev-parse --git-dir)"`; never assume
- the repository metadata directory is the literal `.git` path.
+ Use these types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, and `style`.
+ If a hook fails, fix the failure. Re-run the writing and quality gates when artifacts change.
+ Re-stage each named file. Create a new commit.
- | Provider | Installed | Repository signal | Reference |
- | --- | --- | --- | --- |
- | Graphite | `gt --version` | `$GIT_DIR/.graphite_repo_config` | [`gt.md`](references/gt.md) |
- | Git Town | `git town --version` | `git-town.main-branch` config | [`git-town.md`](references/git-town.md) |
- | `gh stack` | `gh extension list` contains `github/gh-stack` | remote enablement is detected on operation | [`gh-stack.md`](references/gh-stack.md) |
+ Use a single-quoted heredoc delimiter for multi-line commit messages. This delimiter protects backticks and dollar signs from shell interpolation.
+ Use an optional `Co-Authored-By: <name> <email>` trailer when the project accepts the harness identity. Otherwise, omit the trailer.
+ After staging, inspect the cached diff. An empty working diff can mean that all changes are staged.
+ Read the cached diff to tell this state from no changes.
- Use the `stack-tools` report on every invocation. If several providers are
- usable, preserve the one already tracking the branch. When none tracks it,
- use the report's `recommended` provider and state the choice. A `gh-stack`
- recommendation still requires its remote enablement check during operation. If
- no provider is usable after stacked was selected, stop with setup instructions;
- do not emulate stacking with plain pushes.
+ Create one commit for each review unit. Use one commit for a single PR and one commit for each stack layer.
+ Do not shape a PR for commit-by-commit review. The system does not track approval for each commit.
+ Quality gates usually run only on the branch tip. Feedback on one commit delays the other commits.
+ Use multiple commits in one PR only for a short series of simple steps. Keep the combined change small.
- ## Existing PR updates
+ ## Halting
- 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.
+ Every halt names the mode, the failed step, and who owns the failure.
+ Name the step with exactly one of: `classify`, `topology`, `durable write`, `quality gate`, `stage/commit`, `publish`, or `terminal validation`.
+ Apply the shared voice rules from [`../age/references/voice.md`](../age/references/voice.md) in halt and completion reports.
- ## Boundaries
+ - **Plate-owned** — This skill selected an incorrect call shape or route.
+ Examples include a malformed write, stale write, skipped read, or unnamed staging path.
+ A full-tree staging path is also Plate-owned. A mismatch between the mode and reference is also Plate-owned.
+ Work for `/age` or `/gh` is a Plate-owned routing error.
+ Use this recovery rule: `Fix the call shape or the routing, then retry that step`.
+ - **Environment-owner** — Authentication, permission, hooks, network, provider enablement, or a shared backend caused the failure.
+ Name the owning system in the report. Never retry it as if the call shape were wrong.
+ Also, never weaken a gate, stage unnamed paths, or skip read-back to bypass the failure.
- - `/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.
+ A failed quality gate proves that the work is not shippable. Therefore, halt at `quality gate`. Then fix the work.
## Completion
- Write the terminal evidence to a transient JSON file, then run
- `python3 skills/plate/scripts/plate.pyz validate-publication <state.json>`.
- Report completion only when it returns normalized evidence with `valid: true`.
+ Write the terminal evidence to a temporary JSON file.
+ Run `python3 skills/plate/scripts/plate.pyz validate-publication <state.json>`.
+ Report completion only when the command returns normalized evidence with `valid: true`.
```json
{
"mode": "new-pr",
"topology": "single",
"provider": "ordinary",
"artifacts": [
{"target": "docs/adr/example.md", "backend": "tilth", "verified": true}
],
"gate": {"command": "just check", "result": "pass"},
"commits": ["0123456789abcdef0123456789abcdef01234567"],
"prs": [
{
"url": "https://github.com/example/repo/pull/42",
"base": "main",
"head": "feature",
"verified": true
}
],
"risk": "none"
}
```
Use empty `commits` or `prs` lists when the selected mode does not create them.
- Topology preflight uses `gate: {"command": "n/a", "result": "n/a"}` because it
- stops before the publication transaction and quality gate.
+ Topology preflight stops before the publication transaction and quality gate.
+ Therefore, use `gate: {"command": "n/a", "result": "n/a"}` for topology preflight.
+
+ See the generated bundle command inventory in [`references/commands.md`](references/commands.md).