Add contributor PR template and guide (#744)

4ca4b7cf7fab702b3d71854cb1601f47d6d3fbdf · 2026-05-08 13:45:29 -0700 · Trevin Chow
Files touched

A .github/pull_request_template.md
M AGENTS.md
A CONTRIBUTING.md
M README.md
Diff

commit 4ca4b7cf7fab702b3d71854cb1601f47d6d3fbdf
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Fri May 8 13:45:29 2026 -0700

    Add contributor PR template and guide (#744)
---
 .github/pull_request_template.md | 47 ++++++++++++++++++++++++++++++++++++++++
 AGENTS.md                        |  8 +++++++
 CONTRIBUTING.md                  | 30 +++++++++++++++++++++++++
 README.md                        |  9 +-------
 4 files changed, 86 insertions(+), 8 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..94d46973
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,47 @@
+<!--
+Maintainer-owned PRs may use a shorter body. Community PRs must keep these sections.
+Write for reviewers: explain why this change is right, not every line that changed.
+-->
+
+## Intent
+
+<!-- What problem does this solve? Link the issue if one exists. -->
+
+Issue:
+
+<!-- Use Closes/Fixes only when this PR fully resolves the issue. Use Refs or N/A otherwise. -->
+
+## Approach
+
+<!-- Explain the fix shape or design choice. Avoid a file-by-file change list. -->
+
+## Scope
+
+Primary area:
+
+Why this belongs in this repo:
+
+<!-- Printed-CLI-only fixes belong in the generated CLI or public library repo. If the symptom came from a printed CLI, explain the general Printing Press behavior this changes. -->
+
+## Risk
+
+<!-- What could this break? Include generated output, MCP surface, auth, catalog, publish flow, verifier, scorer, or release behavior if relevant. -->
+
+N/A
+
+## Output Contract
+
+<!-- Required only if this PR changes templates, generated files, manifests, command output, MCP schemas, scorecard output, catalog rendering, or pipeline artifacts. Otherwise write "N/A". -->
+
+N/A
+
+## Verification
+
+<!-- List commands actually run. Say "Not run" with a reason if not run. -->
+
+## AI / Automation Disclosure
+
+- [ ] No AI or automation was used
+- [ ] Human-reviewed: AI or automation was used, and a human reviewed the work for intent, fit, and obvious issues before submission
+- [ ] AI-reviewed only: an AI agent reviewed the work, but no human reviewed it before submission
+- [ ] Fully automated: generated and submitted without human review for this specific change
diff --git a/AGENTS.md b/AGENTS.md
index 3edabac0..cf40f8ad 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -124,6 +124,14 @@ Format: `type(scope): description`. Both type and scope are required.
 
 Every commit and PR title must include one of the allowed scopes. GitHub squash-and-merge uses the PR title as the squash commit message, and `.github/workflows/pr-title.yml` enforces the format.
 
+## Pull Requests
+- Community PRs must keep and complete `.github/pull_request_template.md`.
+- Maintainer-owned PRs may use a shorter body and omit the community template sections.
+- A maintainer-owned PR is one opened by, or explicitly on behalf of, a trusted maintainer account with write/admin access to this repository.
+- Do not treat GitHub's `CONTRIBUTOR` author association as exempt; repeat external contributors still use the community PR template unless a maintainer says otherwise.
+- If unsure whether a PR is exempt, keep the template.
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the human-facing contributor guide and AI / automation disclosure definitions.
+
 ## Versioning
 Releases are automated by release-please. Never manually edit version numbers.
 - The plugin version lives in exactly two places and must stay in sync: `.claude-plugin/plugin.json` -> `version`, and `internal/version/version.go` -> `var Version` (annotated `x-release-please-version`; goreleaser injects via ldflags).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..4e2facb1
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for helping improve the Printing Press. This repository contains the generator, templates, binary, skills, catalog, tests, and docs that produce printed CLIs. Printed-CLI-only fixes belong in the generated CLI or public library repo, not here.
+
+## Before Opening a PR
+
+- Check for an existing issue or PR that already covers the same work.
+- Read [AGENTS.md](AGENTS.md) for the repository conventions, especially the machine vs printed CLI boundary, golden-output rules, commit style, and verification expectations.
+- For larger behavior changes, open or comment on an issue first so the scope is clear before implementation.
+
+## Pull Requests
+
+Community PRs must keep and complete the repository PR template. The template is meant to help reviewers see intent, approach, repo fit, risk, output-contract impact, verification, and AI/automation status without reading a file-by-file change log.
+
+Maintainer-owned PRs may use a shorter body. A maintainer-owned PR is one opened by, or explicitly on behalf of, a trusted maintainer account with write/admin access to this repository.
+
+Do not treat GitHub's `CONTRIBUTOR` author association as exempt. Repeat external contributors still use the community PR template unless a maintainer says otherwise. If you are unsure whether a PR is exempt, keep the template.
+
+## AI / Automation Disclosure
+
+The PR template asks for one disclosure choice:
+
+- **No AI or automation was used**: the work was authored manually.
+- **Human-reviewed**: AI or automation was used, and a human reviewed the work for intent, fit, and obvious issues before submission. This does not mean a maintainer-level code review or line-by-line diff audit.
+- **AI-reviewed only**: an AI agent reviewed the work, but no human reviewed it before submission.
+- **Fully automated**: the change was generated and submitted without human review for this specific change.
+
+## Verification
+
+List the commands actually run. If verification was skipped, say why. For changes that affect templates, generated artifacts, command output, manifests, MCP schemas, scorecard output, catalog rendering, or pipeline artifacts, explain the output-contract decision and run `scripts/golden.sh verify` unless the PR explains why golden coverage is not applicable.
diff --git a/README.md b/README.md
index 6197e67f..1d5f1f53 100644
--- a/README.md
+++ b/README.md
@@ -498,14 +498,7 @@ Each newly published CLI ships a root `AGENTS.md` operating guide, a research ma
 
 ## Contributing
 
-Bug reports, feature requests, and PRs are welcome. A few conventions to know before opening a PR:
-
-- **Conventional commits + scopes.** PR titles follow `type(scope): description` with `cli`, `skills`, or `ci` as the scope. The `PR Title` GitHub Action enforces this. See [AGENTS.md](AGENTS.md) for the full rule set.
-- **Releases are automated.** release-please opens release PRs as conventional commits accumulate. Don't manually edit version numbers — three files stay in sync via release-please annotations.
-- **Pre-commit and pre-push hooks.** `lefthook install --reset-hooks-path` wires up `gofmt` (pre-commit) and `golangci-lint` (pre-push). The same lint config runs in CI.
-- **Conventions and glossary live in [AGENTS.md](AGENTS.md).** Read it before larger changes — terminology like "machine vs printed CLI", "absorb gate", and "shipcheck" is documented there.
-
-For larger changes, opening an issue first to align on scope is helpful.
+Bug reports, feature requests, and PRs are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR; it explains the PR template, AI / automation disclosure, and the repo boundary between the Printing Press and printed CLIs. [AGENTS.md](AGENTS.md) carries the full developer conventions, glossary, commit style, and verification rules.
 
 ## Development
← a00e97b1 fix(cli): populate manifest.Category from spec when catalog · back to Cli Printing Press · fix(generator): use simple backticks in auth_client_credenti 64363921 →