pr-lifecycle

## Context This skill is the **canonical Copilot-agent lifecycle for the Squad repository**. It covers the full path from picking up a GitHub issue to merging a PR. Where older docs (templates, copilot-instructions, CONTRIBUTING.md) conflict with this skill, **this skill takes precedence** for Copilot agents. For advanced scenarios (worktrees, multi-repo coordination), see `.copilot/skills/git-workflow/SKILL.md`. ## Scope ✅ **THIS SKILL COVERS:** - Issue pickup and branch creation - Implementation, build, test, lint workflow - Pre-push safety verification - PR creation with correct target, title, body, and labels - All 11 PR readiness checks (what they check, how to pass, how to fix) - Post-creation maintenance (review feedback, rebasing, CI) - Merge preconditions and cleanup ❌ **THIS SKILL DOES NOT COVER:** - Worktree-based parallel work (see `git-workflow` skill) - Multi-repo coordinated PRs (see `git-workflow` skill) - Release process / publishing (see `.squad/skills/release-process`) - Reviewer lockout protocol (see `.copilot/skills/reviewer-protocol`) - Architectural or security review checklists --- ## Lifecycle Procedure ### Phase 1 — Issue Pickup 1. **Read the issue.** Understand the acceptance criteria before writing code. 2. **Confirm capability fit.** Check your capability profile in `.squad/team.md`. 🟢 = proceed. 🟡 = proceed but flag in PR. 🔴 = comment on issue and stop. 3. **Branch from dev:** ```bash git fetch origin dev git checkout dev git rebase origin/dev git checkout -b squad/{issue-number}-{slug} ``` - Branch name format: `squad/{issue-number}-{kebab-case-slug}` - Example: `squad/42-fix-login-validation` - **Never** branch from `main` 4. **Mark in-progress** (optional): ```bash gh issue edit {number} --add-label "status:in-progress" ``` --- ### Phase 2 — Implementation 1. **Make your changes.** Follow the codebase conventions: - TypeScript strict mode, no `@ts-ignore` - ESM-only, async/await - JSDoc on new public APIs 2. **Build:** ```bash npm run build ``` 3. **Test:** ```bash npm test ``` 4. **Type check:** ```bash npm run lint ``` 5. **Stage specific files only:** ```bash git add path/to/file1.ts path/to/file2.ts ``` - ❌ **NEVER** `git add .`, `git add -A`, or `git commit -a` - ✅ **ALWAYS** name each file explicitly 6. **Pre-push safety check:** ```bash # Verify file count matches intent (expect ≤10 files for most fixes) git diff --cached --stat # Verify NO unintended deletions git diff --cached --diff-filter=D --name-only ``` If you see unexpected files or deletions, unstage them: `git reset HEAD <file>` 7. **Single commit with issue reference:** ```bash git commit -m "Brief description of change Closes #{issue-number} Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" ``` - If you already have multiple commits, squash: `git rebase -i origin/dev` and squash all into one - **Never** use `git reset --soft` to squash — it picks up delta from dev and contaminates the commit 8. **Add changeset (if required):** A changeset is required when your PR modifies files under `packages/squad-sdk/src/` or `packages/squad-cli/src/`. ```bash npx changeset add ``` This prompts for: which packages changed, bump type (patch/minor/major), summary. Or create manually at `.changeset/{descriptive-name}.md`: ```markdown --- '@bradygaster/squad-cli': patch --- Brief description of the change ``` If the changeset creates a second commit, squash it into your main commit. --- ### Phase 3 — PR Creation 1. **Push:** ```bash git push -u origin squad/{issue-number}-{slug} ``` 2. **Create PR targeting dev:** ```bash gh pr create --repo bradygaster/squad --base dev \ --title "fix: brief description (#issue-number)" \ --body "Closes #{issue-number} ## Summary What this PR does and why. ## Changes - File-level description of changes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" ``` 3. **Title conventions:** - Bug fix: `fix: description (#N)` - Feature: `feat: description (#N)` - Docs: `docs: description (#N)` - Chore/infra: `chore: description (#N)` 4. **Labels:** - `fix`, `feat`, `docs`, or `repo-health` for type - `squad:{agent-name}` if working as a squad member - `skip-changelog` only with reviewer approval (escape hatch) 5. **Scope rules by label:** - `repo-health`: Only modify `.github/`, `scripts/`, root config, tests, docs. **Never** modify `packages/*/src/` - `fix` or `feat`: May modify product source. Must include changeset when touching `packages/*/src/` --- ### Phase 4 — PR Readiness An automated readiness check runs on every push and posts a checklist comment on the PR. All 11 checks must pass before review (check 11 is informational-only). #### Check 1: Single Commit | | | |---|---| | **What** | PR must contain exactly 1 commit | | **Pass** | Push a single, squashed commit | | **Fix** | `git rebase -i origin/dev` → squash all commits into one → `git push --force-with-lease` | | **Gotcha** | Never `git reset --soft` to squash — contaminates the commit with unrelated changes | #### Check 2: Not in Draft | | | |---|---| | **What** | PR must not be marked as draft | | **Pass** | Create PR as ready, or convert: `gh pr ready` | | **Fix** | `gh pr ready {number}` or use the GitHub UI | | **Gotcha** | The readiness check still runs on drafts but will show ❌ until you mark ready | #### Check 3: Branch Up to Date | | | |---|---| | **What** | PR branch must not be behind `dev` | | **Pass** | Rebase onto latest dev before pushing | | **Fix** | `git fetch origin dev && git rebase origin/dev && git push --force-with-lease` | | **Gotcha** | After rebasing, the readiness check re-runs automatically on the new push | #### Check 4: Copilot Review | | | |---|---| | **What** | The `copilot-pull-request-reviewer` bot must post an `APPROVED` review | | **Pass** | Wait — Copilot review is triggered automatically on PR creation/push | | **Fix** | If Copilot hasn't reviewed after 5 minutes, push an empty commit to re-trigger: `git commit --allow-empty -m "trigger review" && git push` then squash before merge | | **Gotcha** | Copilot review state is `APPROVED`, `CHANGES_REQUESTED`, or `COMMENTED`. Only `APPROVED` passes | #### Check 5: Changeset Present | | | |---|---| | **What** | PRs that modify `packages/squad-sdk/src/` or `packages/squad-cli/src/` must include a `.changeset/*.md` file or a `CHANGELOG.md` edit | | **Pass** | Run `npx changeset add` and commit the generated file | | **Fix** | `npx changeset add` → select affected package(s) → select bump type → write summary → `git add .changeset/ && git commit --amend --no-edit && git push --force-with-lease` | | **Gotcha** | The `skip-changelog` label bypasses this check but requires reviewer approval. Non-source changes (docs, config, tests) don't need a changeset | #### Check 6: No Merge Conflicts | | | |---|---| | **What** | PR must be cleanly mergeable with the base branch | | **Pass** | Keep branch rebased on dev | | **Fix** | `git fetch origin dev && git rebase origin/dev` → resolve conflicts → `git push --force-with-lease` | | **Gotcha** | GitHub may show `null` mergeability briefly while computing — the check treats this as passing | #### Check 7: Scope Clean | | | |---|---| | **What** | Warns if PR includes `.squad/` or `docs/proposals/` files | | **Pass** | Don't include team state or proposal files in product PRs | | **Fix** | Remove unintended files: `git reset HEAD .squad/ docs/proposals/` then amend your commit | | **Gotcha** | This check is **informational only** — it always passes but flags attention. Including these files is OK if intentional (e.g., updating agent history) | #### Check 8: Copilot Threads Resolved | | | |---|---| | **What** | All review threads opened by `copilot-pull-request-reviewer` must be resolved | | **Pass** | Address each Copilot comment, then click "Resolve conversation" in the GitHub UI | | **Fix** | Go to the PR's "Files changed" tab → find unresolved Copilot threads → fix the code or explain why no change is needed → click "Resolve conversation" | | **Gotcha** | Outdated threads (on code that's since changed) are automatically skipped. Only active, unresolved threads block | #### Check 9: CI Passing | | | |---|---| | **What** | All CI check runs (excluding the readiness check itself) must be green | | **Pass** | Fix any build, test, or lint failures and push | | **Fix** | Read the failing check's logs (`gh run view {run-id} --log-failed`), fix the issue, push | | **Gotcha** | Pending/in-progress checks also show ❌. Wait for all checks to complete before evaluating. The readiness check re-runs after CI completes via `workflow_run` trigger | #### Check 10: Issue Linked | | | |---|---| | **What** | PR body or commit message must reference an issue (`Closes #N`, `Fixes #N`, `Resolves #N`, or `Part of #N`) | | **Pass** | Include `Closes #N` in PR body or commit message | | **Fix** | Edit PR body to add `Closes #{issue-number}`, or amend commit message | | **Gotcha** | Case-insensitive matching. Only closing keywords are recognized | #### Check 11: Protected Files (informational) | | | |---|---| | **What** | Warns when zero-dependency bootstrap files are modified (always passes) | | **Pass** | Always passes — this is informational only | | **Fix** | If flagged, verify the changed bootstrap file still has zero external dependencies | | **Gotcha** | Protected files are listed in `copilot-instructions.md`. The check warns but does not block | --- ### Phase 5 — Post-Creation Maintenance 1. **Handling Copilot review feedback:** - Read each comment carefully - Fix valid issues in your code - Resolve each thread after addressing it - Amend your single commit: `git commit --amend --no-edit && git push --force-with-lease` 2. **Rebasing when behind dev:** ```bash git fetch origin dev git rebase origin/dev # Resolve any conflicts git push --force-with-lease ``` 3. **Re-running CI:** - CI re-runs automatically on every push - To re-run without changes: `gh run rerun {run-id} --failed` 4. **If readiness check is stale:** - The readiness check re-runs on push and after CI completes - If it's stale, push a trivial fix or empty commit to re-trigger --- ### Phase 6 — Merge & Cleanup 1. **Merge preconditions:** - All 11 readiness checks pass (✅ across the board) - Human reviewer has approved (or maintainer merges directly) - No open blocking conversations 2. **Who merges:** - Agents do **not** merge PRs themselves - Maintainers (bradygaster or designated reviewers) merge via GitHub UI - The repo uses squash merge, so commit history is clean regardless 3. **Post-merge cleanup:** ```bash git checkout dev git pull origin dev git branch -d squad/{issue-number}-{slug} git push origin --delete squad/{issue-number}-{slug} ``` 4. **Verify issue auto-close:** - If PR body contains `Closes #{N}`, the issue closes automatically on merge - If not, manually close: `gh issue close {number}` --- ## Examples ### Example: Bug fix PR (no source changes) ```bash # Branch git fetch origin dev && git checkout dev && git rebase origin/dev git checkout -b squad/610-fix-broken-link # Fix # ... edit docs/some-file.md ... # Validate npm run build && npm test # Commit (no changeset needed — docs only) git add docs/some-file.md git diff --cached --stat # verify: 1 file git commit -m "docs: fix broken link in contributing guide Closes #610 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" # Push and PR git push -u origin squad/610-fix-broken-link gh pr create --repo bradygaster/squad --base dev \