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:

   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):

   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:

   npm run build

3. Test:

   npm test

4. Type check:

   npm run lint

5. Stage specific files only:

   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:

   # 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:

   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/.

   npx changeset add

   This prompts for: which packages changed, bump type (patch/minor/major), summary.

   Or create manually at .changeset/{descriptive-name}.md:

   ---
   '@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:

   git push -u origin squad/{issue-number}-{slug}

2. Create PR targeting dev:

   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

Check 2: Not in Draft

Check 3: Branch Up to Date

Check 4: Copilot Review

Check 5: Changeset Present

Check 6: No Merge Conflicts

Check 7: Scope Clean

Check 8: Copilot Threads Resolved

Check 9: CI Passing