docs: add fork contribution workflow to CONTRIBUTING.md

.changeset/docs-fork-contribution-workflow.md

@@ -0,0 +1,12 @@
+---
+"@bradygaster/squad-cli": patch
+---
+
+docs: add fork contribution workflow to CONTRIBUTING.md
+
+Closes five gaps discovered during PR #217:
+- Fork-first setup instructions (fork → clone → upstream remote)
+- PR must target `dev` branch, not `main` (`gh pr create --base dev`)
+- Changeset is a required step in the PR process checklist
+- `bradygaster/dev` now correctly described as the PR target for all contributions
+- New "Keeping Your Fork in Sync" section with rebase-on-upstream/dev instructions

.squad/agents/kobayashi/charter.md

@@ -52,6 +52,29 @@ Squad uses a dev-first, three-branch workflow:
 - Cross-repo work → separate sibling clones, not worktrees
 - See `.squad/skills/git-workflow/SKILL.md` for full procedures
 
+### Fork Contributor Procedure
+
+When contributing to bradygaster/squad from a fork:
+
+1. **Branch base:** Always create from `upstream/dev`, NOT `upstream/main`:
+   ```bash
+   git fetch upstream dev
+   git checkout -b username/issue-slug upstream/dev
+   ```
+2. **Changeset:** Run `npx changeset add` and commit the result BEFORE first push.
+3. **PR command:** Always specify base and head explicitly:
+   ```bash
+   gh pr create --base dev --repo bradygaster/squad --head username:branch-name
+   ```
+4. **Rebase before PR:** If branch diverged from `upstream/dev`, rebase before opening:
+   ```bash
+   git fetch upstream
+   git rebase --onto upstream/dev {wrong-ancestor-commit}
+   git push origin branch-name --force-with-lease
+   ```
+
+❌ **Never open a PR targeting `main` from a fork.** `main` is the release branch — it only receives merges from `dev`.
+
 ## Guardrails — Hard Rules
 
 **NEVER:**

.squad/agents/kobayashi/history.md

@@ -1053,3 +1053,29 @@ Restricts workflow installation in \`squad init\` to only Squad-framework workfl
 - Version bumps not part of feature PR — revert if accidental, changesets handle release versioning
 - PR target can be Brady's integration branch (bradygaster/dev) not just main/dev/insiders — confirms Brady's workflow practice
 - Co-authored-by trailer only required when Copilot actually authors commits (not for human contributors)
+
+### Fork Contribution Procedure
+
+Always create feature branches from `upstream/dev`, not `upstream/main`:
+```bash
+git fetch upstream
+git checkout -b username/issue-slug upstream/dev
+```
+
+Always run `npx changeset add` (or create `.changeset/*.md` manually) before the first push.
+
+PR command for fork contributions — always specify base and head explicitly:
+```bash
+gh pr create --base dev --repo bradygaster/squad --head username:branch-name
+```
+
+If a branch was accidentally created from the wrong ancestor, rebase it onto `upstream/dev`:
+```bash
+git rebase --onto upstream/dev {wrong-ancestor-commit} HEAD
+git push origin branch-name --force-with-lease
+```
+
+To fix a PR already opened against the wrong base:
+```bash
+gh pr edit {pr-number} --base dev
+```

CONTRIBUTING.md

@@ -35,9 +35,32 @@ Each package has independent versioning via changesets. A change to squad-sdk ma
 
 ### 1. Clone and Install
 
+**Step 1: Fork the repo on GitHub**
+
+Go to https://github.com/bradygaster/squad and click "Fork" to create your own copy.
+
+**Step 2: Clone your fork**
+
 ```bash
-git clone https://github.com/bradygaster/squad.git
+git clone git@github.com:{yourusername}/squad.git
 cd squad
+```
+
+**Step 3: Add upstream remote**
+
+```bash
+git remote add upstream git@github.com:bradygaster/squad.git
+```
+
+**Step 4: Fetch the dev branch**
+
+```bash
+git fetch upstream dev
+```
+
+**Step 5: Install dependencies**
+
+```bash
 npm install
 ```
 
@@ -73,6 +96,18 @@ npm run test:watch
 npm run lint
 ```
 
+### 5. Keeping Your Fork in Sync
+
+Before opening or updating a PR, rebase your branch on the latest upstream dev:
+
+```bash
+git fetch upstream
+git rebase upstream/dev
+git push origin your-branch --force-with-lease
+```
+
+Always rebase before opening or updating a PR to ensure your changes are based on the latest integration branch.
+
 ## Development Workflow
 
 ### Creating a Feature Branch
@@ -114,11 +149,12 @@ The Co-authored-by trailer is **required** for all commits (added by Copilot CLI
 
 ### Pull Request Process
 
-1. Push your branch: `git push origin bradygaster/217-readme-help-update`
-2. Create a PR: `gh pr create`
-3. Link the issue: Add `Closes #217` to PR description
-4. Wait for CI checks to pass
-5. Request review from the team (agents will respond via comments)
+1. Add a changeset: `npx changeset add` (required before PR — see Changesets section)
+2. Push your branch: `git push origin {yourusername}/217-readme-help-update`
+3. Create a PR with explicit base and head: `gh pr create --base dev --repo bradygaster/squad --head {yourusername}:your-branch`
+4. Link the issue: Add `Closes #217` to PR description
+5. Wait for CI checks to pass
+6. Request review from the team (agents will respond via comments)
 
 ## Code Style & Conventions
 
@@ -213,7 +249,7 @@ You don't need to manually version — changesets handle it.
 
 - **main** — Stable, published releases. All merges include changesets.
 - **insider** — Pre-release features, edge cases. Tag releases as `@insider`.
-- **bradygaster/dev** — Brady's integration branch (team usage).
+- **bradygaster/dev** — Integration branch. **All PRs from forks must target this branch**, not `main`.
 - **user/issue-slug** — Feature branches from users or agents.
 
 ## Continuous Integration