feat(ci): automated PR readiness checks — contributor feedback before review

.github/workflows/squad-pr-readiness.yml

@@ -0,0 +1,46 @@
+name: Squad PR Readiness
+
+on:
+  pull_request_target:
+    branches: [dev, main, insider]
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+# NOTE: Using pull_request_target so we get a write token even for fork PRs.
+# This is safe because we never check out or execute PR code — all data
+# comes from the GitHub API.
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  statuses: read
+  checks: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  readiness:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Skip if the PR is from a bot account (dependabot, renovate, etc.)
+    if: github.actor != 'dependabot[bot]'
+    steps:
+      - name: Checkout scripts
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: scripts/pr-readiness.mjs
+          sparse-checkout-cone-mode: false
+      - name: Check PR readiness
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+          PR_DRAFT: ${{ github.event.pull_request.draft }}
+          PR_LABELS: ${{ toJson(github.event.pull_request.labels) }}
+          REPO_OWNER: ${{ github.repository_owner }}
+          REPO_NAME: ${{ github.event.repository.name }}
+          RUN_NAME: ${{ github.workflow }}
+        run: node scripts/pr-readiness.mjs

CONTRIBUTING.md

@@ -156,6 +156,22 @@ The Co-authored-by trailer is **required** for all commits (added by Copilot CLI
 5. Wait for CI checks to pass
 6. Request review from the team (agents will respond via comments)
 
+### PR Readiness Checklist
+
+An automated readiness check runs on every PR and posts a checklist comment. Address all items before requesting review:
+
+| Check | What it means |
+|-------|---------------|
+| **Single commit** | Squash your commits into one clean commit, or the repo will squash on merge |
+| **Not in draft** | Mark your PR as "Ready for review" when it's done |
+| **Branch up to date** | Rebase on latest `dev` (`git fetch upstream && git rebase upstream/dev`) |
+| **Copilot review** | Wait for the Copilot reviewer bot to post its review |
+| **Changeset present** | Run `npx changeset add` if you changed files in `packages/squad-sdk/src/` or `packages/squad-cli/src/` |
+| **No merge conflicts** | Resolve any conflicts with the target branch |
+| **CI passing** | All CI checks (build, test, lint) must be green |
+
+The readiness check is **informational** — it helps you self-serve before a human reviewer looks at your PR. See `.github/PR_REQUIREMENTS.md` for the full requirements spec.
+
 ## Code Style & Conventions
 
 Squad follows strict TypeScript conventions: