docs: standardize PR delivery workflow

.agents/skills/finish-pr/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: finish-pr
+description: Use when a non-trivial code change is substantially complete and needs a final diff audit, documentation check, verification record, or pull request description.
+---
+
+# Finish PR
+
+Prepare reviewer-facing delivery from repository evidence.
+
+## Workflow
+
+1. Read `AGENTS.md`, `CLAUDE.md`, and `.github/pull_request_template.md`.
+2. Determine the PR base branch or repository default branch. Inspect `git status`,
+   commits since the merge base, the complete merge-base diff, and important files
+   in context. Include submodule pointer changes; do not treat only unstaged files
+   as the change.
+3. Audit comments in changed code. Add or update only comments that explain
+   non-obvious invariants, concurrency, ownership/lifetime, ordering, durability,
+   recovery/retry, performance, or compatibility. Do not narrate syntax.
+4. Run the relevant build, tests, formatting, and documentation checks from
+   `CLAUDE.md`. Record exact commands and outcomes. State checks not run.
+5. Fill the repository PR template from the final diff.
+
+## Quality gate
+
+- Describe concrete behavior and named components; avoid “updated logic.”
+- Explain material decisions and tradeoffs without inventing rejected designs.
+- Cover compatibility, regression/operational risk, rollback, and the best review
+  entry points.
+- Verify every claim against the final diff and current command output.
+- Keep trivial changes concise; make non-trivial changes complete.
+- Draft only unless the user explicitly asks to publish or update the PR.

.agents/skills/finish-pr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Finish PR"
+  short_description: "Finalize changes for reviewer-ready delivery"
+  default_prompt: "Use $finish-pr to audit the final diff and prepare the pull request."

.agents/skills/respond-to-review/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: respond-to-review
+description: Use when pull request review comments, requested changes, or reviewer questions need to be investigated, addressed, or answered.
+---
+
+# Respond to Review
+
+Resolve feedback against the current code and report exactly what changed.
+
+## Workflow
+
+1. Read repository instructions and collect every in-scope review comment with
+   its file, line, author, and thread status.
+2. Inspect the referenced code, callers, tests, and relevant diff before deciding
+   whether the feedback is valid. Do not implement comments blindly.
+3. Classify each item as accepted, already addressed, technically inapplicable,
+   or requiring user/product direction. Give evidence for disagreements.
+4. For accepted items, make the smallest root-cause fix, update necessary
+   explanatory comments/docs, and run focused regression checks plus required
+   repository checks.
+5. Re-read the final diff and draft a response that maps each review item to the
+   concrete change and verification result. Call out unresolved items and unrun
+   checks explicitly.
+
+Do not resolve threads, post comments, push, or update a PR unless the user asks.

.agents/skills/respond-to-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Respond to Review"
+  short_description: "Resolve feedback and report exact follow-up changes"
+  default_prompt: "Use $respond-to-review to address review feedback and draft the response."

.claude/skills/finish-pr

@@ -0,0 +1 @@
+../../.agents/skills/finish-pr

.claude/skills/respond-to-review

@@ -0,0 +1 @@
+../../.agents/skills/respond-to-review

.github/pull_request_template.md

@@ -0,0 +1,44 @@
+## Context
+
+<!-- What problem does this solve, and why does it matter? -->
+
+## Behavior before and after
+
+<!-- Describe observable behavior changes and compatibility implications. -->
+
+## Implementation
+
+<!-- Explain the main control/data flow and the components changed. -->
+
+## Design decisions and alternatives
+
+<!-- Why this approach? Note meaningful tradeoffs or rejected alternatives. -->
+
+## Test plan
+
+- [ ] Unit/TCL tests
+- [ ] Integration or manual validation
+- [ ] Formatting/build checks
+- [ ] Compatibility or performance validation, when relevant
+
+Commands and results:
+
+```text
+<!-- Paste exact commands and outcomes. State checks that were not run. -->
+```
+
+## Risk assessment
+
+<!-- Regression surface, failure modes, operational concerns, and gaps. -->
+
+## Rollback plan
+
+<!-- Revert, configuration change, migration rollback, or "revert this PR". -->
+
+## Reviewer guide
+
+<!-- Point reviewers to the highest-value files, functions, and invariants. -->
+
+## Follow-up work
+
+<!-- Known limitations or deliberately deferred work. Use "None" if applicable. -->

AGENTS.md

@@ -34,3 +34,33 @@ Discoverability note: nothing states this default except the startup banner
 (`Running logs will be written to the following path: …/install/logs`). `--help`
 only documents `--log_dir` as the *override*, never the default. To send logs
 elsewhere, pass `--log_dir=<dir>` (or `--logtostderr` to log to stderr instead).
+
+## Documentation and delivery
+
+A non-trivial coding task is complete only after implementation, verification,
+and reviewer-facing documentation are consistent with the final diff.
+
+### Code comments
+
+- Document non-obvious invariants, concurrency and memory-ordering assumptions,
+  ownership/lifetime rules, failure and retry behavior, compatibility constraints,
+  and hot-path tradeoffs. Explain **why**, not syntax.
+- For transaction or storage changes, call out lock ordering, reader/writer
+  visibility, durability boundaries, crash consistency, and idempotency when
+  relevant.
+- Add documentation comments to new public APIs and externally visible types.
+- Do not add comments that merely restate the code. Update stale nearby comments
+  when behavior changes.
+
+### Final delivery
+
+- Derive summaries and pull request text from the final merge-base diff, not
+  memory or only unstaged changes.
+- Report the problem, observable behavior, implementation, material design
+  decisions, exact verification performed, risks, rollback, and reviewer focus.
+- State unrun checks and uncertainty explicitly; never claim a test passed unless
+  it was run in the current workspace.
+- When a change touches `data_substrate`, review and land that repository's change
+  first, then update the submodule pointer.
+- In Codex, use `$finish-pr` and `$respond-to-review`; in Claude Code, invoke the
+  same shared skills as `/finish-pr` and `/respond-to-review`.