From ebedf74a245b87e089dcc9687aaa5dc04125a2d1 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Fri, 13 Feb 2026 12:11:23 -0800 Subject: [PATCH 1/2] chore: unignore .ai-team/ for dev branches, update contributing guide - Removed .ai-team/ from .gitignore so team files can be committed on dev/feature branches - Updated CONTRIBUTING.md to reflect guard workflow as enforcement (not .gitignore) - Updated guard workflow error message in both live and template copies - .npmignore still excludes .ai-team/ from the published package --- .github/workflows/squad-main-guard.yml | 5 +- .gitignore | 9 ++-- CONTRIBUTING.md | 60 ++++++++++++------------ templates/workflows/squad-main-guard.yml | 5 +- 4 files changed, 41 insertions(+), 38 deletions(-) diff --git a/.github/workflows/squad-main-guard.yml b/.github/workflows/squad-main-guard.yml index 9f7f65117..196cd8f8d 100644 --- a/.github/workflows/squad-main-guard.yml +++ b/.github/workflows/squad-main-guard.yml @@ -81,8 +81,9 @@ jobs: 'git push', '```', '', - '> ⚠️ `.ai-team/` is in `.gitignore` but files previously force-added with `git add -f`', - '> remain tracked. `git rm --cached` untracks them without deleting your local copies.', + '> ⚠️ `.ai-team/` is committed on `dev` and feature branches by design.', + '> The guard workflow is the enforcement mechanism that keeps these files off `main` and `preview`.', + '> `git rm --cached` untracks them from this PR without deleting your local copies.', ]; core.setFailed(lines.join('\n')); diff --git a/.gitignore b/.gitignore index 712e81311..4fc15770b 100644 --- a/.gitignore +++ b/.gitignore @@ -10,11 +10,10 @@ Thumbs.db # Node (if we add tooling later) node_modules/ -# Squad team state (created at runtime, never committed) -# ⚠️ NEVER force-add these files (git add -f .ai-team/). -# Previously force-added files remain tracked even with this rule. -# If tracked files leak in, remove them: git rm --cached -r .ai-team/ -.ai-team/ +# Squad team state — committed on dev and feature branches, +# blocked from main/preview by squad-main-guard.yml workflow. +# ⚠️ NEVER merge .ai-team/ into main or preview. +# The guard workflow will fail the PR if you try. # Squad Squad templates (internal, not distributed) .ai-team-templates/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e047ffdb1..715db4741 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,8 +62,8 @@ Squad uses a three-tier branch structure to protect production and staging while | Branch | Purpose | Protection | Files Allowed | |--------|---------|------------|---------------| -| **`dev`** | Development & integration | None | ✅ Everything | -| **`feature/squad/{issue}-{slug}`** | Feature work | None — merge to dev | ✅ Everything | +| **`dev`** | Development & integration | None | ✅ Everything (including `.ai-team/`) | +| **`feature/squad/{issue}-{slug}`** | Feature work | None — merge to dev | ✅ Everything (including `.ai-team/`) | | **`preview`** | Staging & release candidate | Guard checks for `.ai-team/`, `team-docs/` (except blog/) | ✅ Most files — see [Protected Files](#whats-protected) | | **`main`** | Production & releases | Guard checks for `.ai-team/`, `team-docs/` (except blog/) | ✅ Most files — see [Protected Files](#whats-protected) | @@ -97,15 +97,15 @@ git push origin squad/42-auth-refresh ### 🚫 CRITICAL: Files Blocked from `main` and `preview` -These files are **runtime team state** and belong on development branches only: +These files are **runtime team state** and live on `dev` and feature branches. They are committed to git and flow freely between `dev` and feature branches, but the **guard workflow** (`squad-main-guard.yml`) blocks them from reaching `main` or `preview`: -| Path | Reason | Merged to main? | -|------|--------|-----------------| -| **`.ai-team/**`** | Agent charters, routing, decisions, history, casting registry | ❌ NEVER | -| **`team-docs/` (except `team-docs/blog/`** | Internal team documentation, sprint plans, notes | ❌ NEVER | -| **`team-docs/blog/**`** | Public blog content | ✅ YES — blog posts are public | +| Path | Reason | Committed to `dev`? | Merged to `main`/`preview`? | +|------|--------|---------------------|---------------------------| +| **`.ai-team/**`** | Agent charters, routing, decisions, history, casting registry | ✅ YES | ❌ NEVER — guard blocks | +| **`team-docs/` (except `team-docs/blog/`** | Internal team documentation, sprint plans, notes | ✅ YES | ❌ NEVER — guard blocks | +| **`team-docs/blog/**`** | Public blog content | ✅ YES | ✅ YES | -**Why?** `.ai-team/` contains persistent agent knowledge, routing rules, and decision history. It's internal infrastructure. If it leaks to `main`, you're shipping developer metadata as product. `team-docs/` is working notes — only blog content is publication-ready. +**Why?** `.ai-team/` contains persistent agent knowledge, routing rules, and decision history. It's internal infrastructure that belongs on development branches — not in production. The guard workflow is the enforcement mechanism, not `.gitignore`. `.ai-team/` is NOT in `.gitignore` — it's a normal part of the `dev` branch. The `.npmignore` file ensures it's excluded from the published npm package. ### ✅ Files That Flow Freely @@ -171,7 +171,7 @@ If you accidentally (or intentionally) target `preview` or `main`, the **guard w If the guard blocks your PR because it contains `.ai-team/` or `team-docs/` files: ```bash -# Remove .ai-team/ from git (keeps local copies safe) +# Remove .ai-team/ from this PR (keeps local copies and dev branch copies safe) git rm --cached -r .ai-team/ # Remove team-docs/ except blog/ @@ -183,7 +183,7 @@ git commit -m "chore: remove internal team files from PR" git push ``` -The workflow will re-run and pass. Your local `.ai-team/` and `team-docs/` files remain untouched. +The workflow will re-run and pass. Your local `.ai-team/` and `team-docs/` files remain untouched, and they continue to exist on `dev` normally. --- @@ -289,18 +289,18 @@ You don't need to add these yourself — the Lead will triage and label issues. ``` squad/ -├── .ai-team/ 🚫 BLOCKED from main/preview -│ ├── agents/ -│ │ ├── {name}/charter.md 🚫 BLOCKED -│ │ └── {name}/history.md 🚫 BLOCKED -│ ├── team.md 🚫 BLOCKED -│ ├── routing.md 🚫 BLOCKED -│ ├── decisions.md 🚫 BLOCKED +├── .ai-team/ ✅ Committed on dev & feature branches +│ ├── agents/ 🚫 Guard blocks from main/preview +│ │ ├── {name}/charter.md 🚫 Guard blocks from main/preview +│ │ └── {name}/history.md 🚫 Guard blocks from main/preview +│ ├── team.md 🚫 Guard blocks from main/preview +│ ├── routing.md 🚫 Guard blocks from main/preview +│ ├── decisions.md 🚫 Guard blocks from main/preview │ └── ... │ -├── team-docs/ 🚫 BLOCKED (except blog/) -│ ├── sprint-plan.md 🚫 BLOCKED -│ ├── roadmap.md 🚫 BLOCKED +├── team-docs/ 🚫 Guard blocks from main/preview (except blog/) +│ ├── sprint-plan.md 🚫 Guard blocks from main/preview +│ ├── roadmap.md 🚫 Guard blocks from main/preview │ └── blog/ ✅ ALLOWED (public content) │ └── 001-launch.md ✅ ALLOWED │ @@ -342,7 +342,7 @@ When you open a PR to `main` or `preview`, the workflow `.github/workflows/squad - ✅ **Pass:** "No forbidden paths found" — you're good to merge - ❌ **Fail:** Lists forbidden files and shows `git rm --cached` fix -The guard is **not a suggestion** — it's a hard stop. But it's easy to fix if it blocks you (see [Fixing a Blocked PR](#fixing-a-blocked-pr)). +The guard is **not a suggestion** — it's a hard stop. This is the primary enforcement mechanism that keeps `.ai-team/` and internal `team-docs/` off `main` and `preview`. But it's easy to fix if it blocks you (see [Fixing a Blocked PR](#fixing-a-blocked-pr)). --- @@ -350,12 +350,14 @@ The guard is **not a suggestion** — it's a hard stop. But it's easy to fix if ### Q: I accidentally committed `.ai-team/` to my feature branch. Do I have to delete it? -**A:** No! `.ai-team/` is in `.gitignore`, so it won't push to GitHub unless you force-add it. Just keep your feature branch clean: +**A:** Nope — `.ai-team/` files are **supposed** to be committed on `dev` and feature branches! They're part of the normal development workflow. The guard workflow (`squad-main-guard.yml`) prevents them from reaching `main` or `preview`. Just don't PR them to those branches. + +If you're creating a PR to `main` or `preview` and the guard blocks it, remove the files from that PR only: ```bash -git rm --cached -r .ai-team/ # Untrack if force-added -git checkout dev # Switch back to dev -# Your local .ai-team/ remains untouched +git rm --cached -r .ai-team/ # Untrack from this PR +git commit -m "chore: remove .ai-team/ from release PR" +git push ``` ### Q: Can I PR to `main` directly? @@ -364,7 +366,7 @@ git checkout dev # Switch back to dev ### Q: The guard blocked my PR. What now? -**A:** Your PR contains `.ai-team/` or `team-docs/` files that shouldn't be in `main`/`preview`. Follow [Fixing a Blocked PR](#fixing-a-blocked-pr) — it's three `git rm --cached` commands and a push. The workflow will re-run and pass. +**A:** Your PR targets `main` or `preview` and contains `.ai-team/` or `team-docs/` files. These files live on `dev` and feature branches but must not reach production. Follow [Fixing a Blocked PR](#fixing-a-blocked-pr) — it's three `git rm --cached` commands and a push. The workflow will re-run and pass. ### Q: I want to commit `team-docs/sprint-plan.md` — can I do that? @@ -389,9 +391,9 @@ Welcome aboard. Make Squad better. 🚀 ## Summary: What You Need to Know 1. **Clone from `dev`, create `squad/{issue}-{slug}` branch, PR back to `dev`** -2. **Never commit `.ai-team/` or internal `team-docs/` to `main` or `preview` — the guard will block it** +2. **`.ai-team/` files are committed on `dev` and feature branches — the guard workflow blocks them from `main`/`preview`** 3. **Run `npm test` before pushing** 4. **Follow conventional commits (feat:, fix:, docs:, etc.)** -5. **If the guard blocks your PR, run `git rm --cached` and push again** +5. **If the guard blocks your PR to `main`/`preview`, run `git rm --cached` and push again** That's it. Happy contributing. diff --git a/templates/workflows/squad-main-guard.yml b/templates/workflows/squad-main-guard.yml index 9f7f65117..196cd8f8d 100644 --- a/templates/workflows/squad-main-guard.yml +++ b/templates/workflows/squad-main-guard.yml @@ -81,8 +81,9 @@ jobs: 'git push', '```', '', - '> ⚠️ `.ai-team/` is in `.gitignore` but files previously force-added with `git add -f`', - '> remain tracked. `git rm --cached` untracks them without deleting your local copies.', + '> ⚠️ `.ai-team/` is committed on `dev` and feature branches by design.', + '> The guard workflow is the enforcement mechanism that keeps these files off `main` and `preview`.', + '> `git rm --cached` untracks them from this PR without deleting your local copies.', ]; core.setFailed(lines.join('\n')); From f0474b86e7498fd8a51882b3597684ea671f9a3a Mon Sep 17 00:00:00 2001 From: bradygaster Date: Fri, 13 Feb 2026 12:12:17 -0800 Subject: [PATCH 2/2] =?UTF-8?q?chore:=20trim=20npm=20package=20=E2=80=94?= =?UTF-8?q?=20exclude=20docs,=20CONTRIBUTING.md,=20.gitignore?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Removed docs/ from package.json files allowlist (read on GitHub, not runtime) - Added CONTRIBUTING.md, .gitignore, docs/ to .npmignore (belt-and-suspenders) - Package: 82 files / 205.7kB -> 30 files / 75.1kB (63% smaller) --- .npmignore | 9 ++++++++- package.json | 1 - 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.npmignore b/.npmignore index 2099314bf..9aae519b2 100644 --- a/.npmignore +++ b/.npmignore @@ -1,6 +1,6 @@ # Squad Squad — team state and development files # These are excluded from the distributed package. -# The product ships: index.js, templates/, docs/, CHANGELOG.md, .github/agents/squad.agent.md +# The product ships: index.js, templates/, CHANGELOG.md, .github/agents/squad.agent.md # (also enforced by package.json "files" field) # Squad Squad (the AI team that builds Squad) @@ -10,13 +10,20 @@ # Internal team docs (proposals, sprint plans — never shipped) team-docs/ +# Public docs (read on GitHub, not needed at runtime) +docs/ + # Tests test/ # Git/repo config not needed at runtime +.gitignore .gitattributes .github/workflows/ +# Repo contributor docs (not needed by users) +CONTRIBUTING.md + # Editor / OS .vscode/ .DS_Store diff --git a/package.json b/package.json index 1c3289287..ed50bc5ab 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,6 @@ "index.js", ".github/agents/squad.agent.md", "templates/**/*", - "docs/**/*", "CHANGELOG.md" ], "scripts": {