docs(skill): add versioning policy — prevents prerelease version incidents by diberry · Pull Request #689 · bradygaster/squad

diberry · 2026-03-29T16:26:44Z

Versioning Policy Skill

Adds .squad/skills/versioning-policy/SKILL.md ΓÇö a comprehensive versioning policy for the Squad monorepo.

Why this is needed

The repo had no documented versioning policy, which caused two incidents:

PR feat(sdk): StorageProvider abstraction — complete migration + example providers #640: A prerelease version (\

Fork PR: diberry#117

Merge Order

These 3 PRs form a dependency chain — merge in this order:

PR: fix(sdk,cli): remove prerelease version suffixes (from fork PR feat: Extract cold-path sections from squad.agent.md (#98) #116) — fixes dev branch versions
PR: feat(ci): add workspace integrity, prerelease guard, and export smoke gates (from fork PR chore: Remove .ai-team/ deprecation banner (#71) #115) — adds CI enforcement
PR: docs(skill): add versioning policy (from fork PR chore: standardize timestamps to ISO 8601 UTC #117) — documents the rules

Fork-specific workflow skills for PR hygiene: - fork-first-pipeline: review on fork before opening upstream PRs - bleed-check: twice-daily cross-branch audit for stowaway files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Adds Step 5.5 REBASE with guidance on rebasing feature branches against origin/dev to avoid full-file rewrites on shared files. Includes Shared File Strategy for surgical additions and When Rebase Fails recovery steps. Updates anti-patterns table to flag 'Skip rebase before upstream'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…, conventions) - Fork-first-pipeline: Added serial branch operations warning, force-add note for gitignored skills, stale comments check - Bleed-check: Added high-risk shared files callout, convention gate checks, CI path debugging pattern Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Dual Reviewer Gate: both Flight and FIDO must approve - Convention Issues Are Blockers: /docs/ prefix, double blanks, table order, whitespace - Review→Fix→Re-review Loop: both reviewers must re-review after fixes - Reviewer Lockout: locked authors cannot self-fix after rejection - Known PAO Quirks: watch for .squad/ files, /docs/ prefix, verification before push - Review Comments: formal PR comment format and verdict options - Tamir Reviewer Rule: only on upstream PRs with source material - Commit Hygiene: one commit, amend fixups, force-push safely, verify before push Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

When a PR completes the full fork pipeline (Flight+FIDO approved, bleed check passed, squashed, rebased, moved to upstream targeting Brady's dev), the upstream PR should be undrafted immediately. The upstream PR is the final presentation — draft PRs signal incomplete work, but at this stage all iteration is finished on the fork. Add gh pr ready command to Step 7 (UPSTREAM) as the final action after opening the upstream PR. Add anti-pattern entry for leaving upstream PRs in draft. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Validates that the squad-main-guard.yml workflow was properly removed: - v0.5.4 migration in index.js correctly targets and deletes the guard - TEMPLATE_MANIFEST has no reference to squad-main-guard.yml - SDK init and CLI init/upgrade never create the guard workflow - No remaining workflow templates block .squad/ paths on push to main 10 tests covering guard removal, template manifest, init/upgrade safety, and workflow template scanning. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Updated fork-first-pipeline skill with PR bradygaster#640 retrospective learnings - .squad/ decisions and state synced - Merged inbox decisions into decisions.md and decisions-archive.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Prevents .squad/ stowaways on feature branches. Learned from 3 incidents on PR bradygaster#640. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- .github/PR_REQUIREMENTS.md: versioned canonical spec (from #106 PRD) - .github/PULL_REQUEST_TEMPLATE.md: author-facing checklist Addresses Challenger FATAL finding: spec must be versioned, not mutable issue. Part of #106. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This reverts commit 8097c96.

Adds .github/PR_REQUIREMENTS.md (versioned spec with 6 categories, CRUD-on-CLI/SDK user-facing definition, waiver process, exemptions) and .github/PULL_REQUEST_TEMPLATE.md (author-facing checklist). Part 1 of 2 for repo health -- #104 will automate enforcement. Closes Phase 2 of #106 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Part 2 of 2 for repo health. Adds two automated CI enforcement gates to squad-ci.yml: 1. CHANGELOG gate -- requires CHANGELOG.md update when SDK/CLI source changes 2. Exports map check -- verifies package.json exports match barrel files Both feature-flagged (vars.SQUAD_CHANGELOG_CHECK, vars.SQUAD_EXPORTS_CHECK) with skip labels. Includes test coverage for check-exports-map.mjs. Refs #104 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Closes #103 Adds samples-build CI job that validates all 11 samples compile when SDK changes. - Loops samples/ directories with npm install/build/test - Feature-flagged via skip-samples-build label - 15-minute timeout, --ignore-scripts, npm cache - Accepted Copilot suggestions: cache-dependency-path, workspace root install Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Codifies semver versioning rules for SDK and CLI packages: - MAJOR.MINOR.PATCH only on dev/main (no prerelease suffixes) - bump-build.mjs -build.N versions are local-only, never committed - SDK + CLI versions must stay in sync (workspace resolution footgun) - Surgeon owns version bumps; other agents hands-off - prerelease-version-guard CI gate enforces the policy Motivated by PR bradygaster#640 (prerelease broke workspace resolution) and PR #116 (prerelease leak on release branch). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds documentation and policy artifacts intended to prevent prerelease/versioning incidents in the Squad monorepo, but also introduces new CI gating and test enforcement beyond the stated “docs(skill)” scope.

Changes:

Add a new versioning policy skill and related decision record.
Add CI gates + helper script for CHANGELOG enforcement, SDK exports-map validation, and sample build/test validation.
Add new tests covering guard-workflow removal and exports-map checker execution; plus docs clarifying Nap vs /compact.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
test/guard-removal.test.ts	New tests asserting guard workflow removal and absence across init/upgrade/templates.
test/check-exports-map.test.ts	New test that runs the exports-map checker script and validates output shape.
scripts/check-exports-map.mjs	New script that compares SDK barrel dirs (`src/*/index.ts`) to `package.json` exports.
docs/src/content/docs/features/context-hygiene.md	Updates Nap description and adds a note linking to Nap vs `/compact`.
docs/src/content/docs/concepts/nap-vs-compact.md	New Concepts page explaining the difference between Nap and `/compact`.
.squad/skills/versioning-policy/SKILL.md	New skill documenting semver/prerelease rules and incident context.
.squad/skills/fork-first-pipeline/SKILL.md	New skill describing a fork-first PR workflow/pipeline.
.squad/decisions/inbox/retro-copilot-git-safety.md	Deletes inbox entry (content appears moved into decisions log).
.squad/decisions/inbox/flight-versioning-policy.md	New decision record formalizing the versioning policy.
.squad/decisions/inbox/booster-ci-deletion-guard.md	Deletes inbox entry (content appears moved into decisions log).
.squad/decisions.md	Removes older blocks, appends new directives/decisions (incl. CI guard + skills-dir decisions).
.squad/decisions-archive.md	Archives older decisions that were removed from `.squad/decisions.md`.
.github/workflows/squad-ci.yml	Adds new CI jobs: changelog gate, exports-map check, and samples build/test gate.
.github/PULL_REQUEST_TEMPLATE.md	Adds a structured PR template/checklist.
.github/PR_REQUIREMENTS.md	Adds a canonical PR requirements spec documenting required gates and waivers.
.copilot/skills/bleed-check/SKILL.md	New skill documenting “bleed check” process and conventions.

Copilot · 2026-03-29T16:32:10Z

docs/src/content/docs/features/context-hygiene.md


 ## Nap

-**What it does:** Summarizes accumulated work into smaller, more efficient memory files. This is the same as running `/compact` in the CLI or `squad nap` from the command line.
+**What it does:** Summarizes accumulated work in `.squad/` team state files into smaller, more efficient memory files. This compresses your persistent team knowledge — agent histories, decisions, and logs across multiple sessions.

 When you tell the team to "take a nap," each agent:



This page describes skills/state under .squad/ (and later, Reskill reviewing .squad/skills/), but current init/skill discovery uses .copilot/skills/ as the primary skills location. Please update the wording to reference .copilot/skills/ (and mention .squad/skills/ only as legacy/back-compat if applicable) so the docs match actual behavior.

Copilot · 2026-03-29T16:32:10Z

.squad/decisions.md

+## Decision
+
+Skill discovery now reads BOTH `.copilot/skills/` and `.squad/skills/`, merging results. On name conflicts, `.copilot/skills/` wins (first-dir-wins priority).
+
+## Rationale
+
+- `.copilot/skills/` is the canonical write location (tools/index.ts, fresh init)
+- `.squad/skills/` has historical content and upstream compatibility
+- Silently dropping either directory loses team knowledge
+- The merge is additive — no breaking change for existing users
+
+## Impact
+
+- All skill writes should target `.copilot/skills/` (squad.agent.md updated)
+- `.squad/skills/` is effectively read-only legacy
+- Over time, skills naturally consolidate into `.copilot/skills/`
+- No migration needed — the runtime merge handles both dirs transparently


This decision block states that skill discovery already reads/merges BOTH .copilot/skills/ and .squad/skills/ and that the runtime merge is already in place, but the current implementation of LocalSkillSource.skillsDir is still either/or (it returns .copilot/skills when present and never reads .squad/skills). This creates contradictory guidance (especially next to the following 'Proposed' decision). Consider updating this section to reflect current behavior (or mark it as future/Proposed) to avoid misleading agents.

Suggested change

## Decision

Skill discovery now reads BOTH `.copilot/skills/` and `.squad/skills/`, merging results. On name conflicts, `.copilot/skills/` wins (first-dir-wins priority).

## Rationale

- `.copilot/skills/` is the canonical write location (tools/index.ts, fresh init)

- `.squad/skills/` has historical content and upstream compatibility

- Silently dropping either directory loses team knowledge

- The merge is additive — no breaking change for existing users

## Impact

- All skill writes should target `.copilot/skills/` (squad.agent.md updated)

- `.squad/skills/` is effectively read-only legacy

- Over time, skills naturally consolidate into `.copilot/skills/`

- No migration needed — the runtime merge handles both dirs transparently

## Decision (Target State)

Skill discovery should read BOTH `.copilot/skills/` and `.squad/skills/`, merging results. On name conflicts, `.copilot/skills/` wins (first-dir-wins priority).

## Rationale

- `.copilot/skills/` is the canonical write location (tools/index.ts, fresh init)

- `.squad/skills/` has historical content and upstream compatibility

- Silently dropping either directory loses team knowledge

- The merge is additive — no breaking change for existing users once implemented

## Impact (when implemented)

- All skill writes will target `.copilot/skills/` (squad.agent.md updated)

- `.squad/skills/` will be effectively read-only legacy

- Over time, skills will naturally consolidate into `.copilot/skills/`

- No manual migration will be needed — the planned runtime merge will handle both dirs transparently once shipped

Copilot · 2026-03-29T16:32:11Z

.squad/skills/versioning-policy/SKILL.md

+---
+name: "versioning-policy"
+description: "Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents"
+domain: "release, versioning, npm, CI"
+confidence: "medium"
+source: "earned (PR #640 workspace resolution incident, PR #116 prerelease leak, CI gate implementation)"
+---
+


This new skill is added under .squad/skills/, but the runtime prefers .copilot/skills/ whenever it exists (LocalSkillSource returns .copilot/skills first). In a typical initialized repo .copilot/skills will exist, so this skill will be silently undiscoverable. Add/copy the skill under .copilot/skills/versioning-policy/SKILL.md (or update skill discovery to merge both dirs).

Copilot · 2026-03-29T16:32:11Z

.squad/skills/fork-first-pipeline/SKILL.md

+## 9-Step Pipeline
+
+\\\
+BRANCH → FORK PR → PREFLIGHT → REVIEW → FIX → BLEED CHECK → CLEAN → UPSTREAM → DONE
+\\\
+
+### Step 1: BRANCH
+Create a feature branch locally:
+\\\ash
+git checkout -b squad/{issue-number}-{slug}
+\\\
+
+### Step 2: FORK PR
+Push to fork and open PR **against your fork's dev branch**:
+\\\ash
+git push origin {branch-name}
+gh pr create --base dev --draft  # Opens on fork/dev, not upstream
+\\\


This file contains malformed code-fence markup like \\\ and \\\� a sh instead of standard triple-backtick fences (```bash). As written, the command examples won’t render correctly and include stray control characters. Replace these with proper Markdown code fences.

Copilot · 2026-03-29T16:32:11Z

test/guard-removal.test.ts

+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  mkdirSync, writeFileSync, readFileSync, rmSync,


writeFileSync is imported but never used. This will trip no-unused-vars/TS unused import checks in lint. Remove the unused import (or use it).

Suggested change

mkdirSync, writeFileSync, readFileSync, rmSync,

mkdirSync, readFileSync, rmSync,

Copilot · 2026-03-29T16:32:12Z

.github/workflows/squad-ci.yml

+      - name: Check skip label
+        if: steps.flag.outputs.skip == 'false'
+        id: label
+        run: |
+          LABELS=$(gh pr view ${{ github.event.pull_request.number }} --json labels --jq '.labels[].name' 2>/dev/null || echo "")
+          if echo "$LABELS" | grep -q "skip-changelog"; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Skipping CHANGELOG gate (skip-changelog label present)"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}


The skip-label checks use gh pr view ... --json labels, but the workflow-level permissions only grants contents: read. With restricted permissions, GITHUB_TOKEN may not be allowed to read PR metadata, causing label detection to fail (and skip labels to never work). Prefer using github.event.pull_request.labels (as done later in samples-build) or add pull-requests: read permissions.

Copilot · 2026-03-29T16:32:12Z

.github/workflows/squad-ci.yml

+      - name: Check for SDK source changes
+        if: steps.flag.outputs.skip == 'false' && steps.label.outputs.skip != 'true'
+        id: changes
+        run: |
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+          # Three-dot diff (base...head) finds the merge-base automatically,
+          # so it works correctly even when the PR branch contains merge
+          # commits from syncing with the base branch.
+          SDK_CHANGED=$(git diff --name-only "$BASE"..."$HEAD" | grep -E '^packages/squad-sdk/src/' || true)
+          if [ -z "$SDK_CHANGED" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "No SDK source changes detected -- exports check not applicable"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            echo "SDK source files changed:"
+            echo "$SDK_CHANGED"
+          fi
+
+      - name: Verify exports map matches barrel files
+        if: steps.flag.outputs.skip == 'false' && steps.label.outputs.skip != 'true' && steps.changes.outputs.skip != 'true'
+        run: node scripts/check-exports-map.mjs
+


exports-map-check will currently fail for any PR that touches packages/squad-sdk/src/ because check-exports-map.mjs treats every src/<dir>/index.ts barrel as requiring a package.json export, but the SDK already has barrels like platform/, remote/, roles/, streams/, and upstream/ without matching exports. Either add the missing exports entries (if these are meant to be public) or adjust the script/gate to only enforce newly introduced barrels (or an allowlist) so existing intentional internal barrels don’t block unrelated SDK changes.

Copilot · 2026-03-29T16:32:12Z

.github/workflows/squad-ci.yml

+  changelog-gate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+


PR description/title indicate this PR is documentation-only (versioning policy skill), but this change adds multiple new CI gates (changelog/exports/samples) and a new workflow script. If the merge plan is to land CI enforcement in a separate PR (as described), these workflow changes should be split out to match that scope and avoid surprising reviewers/merge conflicts.

Copilot · 2026-03-29T16:32:12Z

docs/src/content/docs/concepts/nap-vs-compact.md

+---
+title: Nap vs /compact
+description: How Squad nap and Copilot CLI /compact solve different memory problems at different layers.
+---
+
+# Nap vs /compact
+
+Users hit memory limits in two ways: the chat gets too big, or agent memory piles up over time.


A new Concepts page was added, but it is not referenced in docs/src/navigation.ts under the Concepts section. If navigation is meant to be curated via NAV_SECTIONS, this page will be hard to discover from the sidebar. Add a Concepts nav entry for concepts/nap-vs-compact.

Copilot · 2026-03-29T16:32:13Z

.copilot/skills/bleed-check/SKILL.md

+All open PRs by **diberry** targeting **bradygaster/squad**
+
+Query:
+\\\ash
+gh pr list --author diberry --repo bradygaster/squad --base dev --state open
+\\\
+
+## Process
+
+### 1. List PRs
+Fetch all open PRs from diberry targeting bradygaster/squad.
+
+### 2. For Each PR: Check File List
+Retrieve the file list:
+\\\ash
+gh pr view {pr-number} --repo bradygaster/squad --json files
+\\\
+
+### 3. Flag Stowaways
+Check each file against the PR's stated purpose (from title/description). Red flags:
+
+| Red Flag | Example | Why It's Bad |
+|---|---|---|
+| \.squad/\ files | \.squad/decisions/...\, \.squad/agents/...\ | Should not ship in app PRs |
+| Navigation entries | \.squad/routing.md\ changes | Wrong PR can cause nav breakage |
+| Test expectations | \.squad/agents/*/expected-output\ | Unmaintainable across PRs |
+| Full-file rewrites | Accidental large refactors | Out of scope, causes merge debt |
+| Build artifacts | \dist/\, \uild/\, \.next/\ | Should be in \.gitignore\ |
+| Root-level strays | Unexpected \.env.local\, \secrets.json\ | Likely accidental commits |
+
+### 3.5: Convention Gate Checks
+
+While auditing files, also check for house-style violations. **These are blockers, not nits — per team directive.**
+
+| Convention | Rule | Blocker? |
+|-----------|------|----------|
+| Internal link format | Use bare paths like `/features/memory`, not `/docs/features/memory` | ✅ Yes |
+| Blank lines | Single blank line between sections (not double) | ✅ Yes |
+| Entry duplication | Each nav entry appears exactly once | ✅ Yes |
+| Stale TDD comments | Clean up "RED PHASE", "TODO: implement", "WIP" markers before merge | ✅ Yes |
+
+### 3.6: CI Path Debugging Pattern
+
+When CI reports a step as successful but tests fail on a missing file, path mismatches often indicate cross-branch contamination or stale config:
+
+Example: CI says "generator succeeded — output at docs/public/" but the test looks for docs/dist/ and fails.
+
+**Check actual path**:
+\\\ash
+ls -la docs/public/
+ls -la docs/dist/
+grep "outDir" build.config.ts
+grep "docs/dist" test/docs-build.test.ts
+\\\


This skill doc uses malformed code-fence markup (\\\� a sh, \\\ash, etc.) and includes stray control characters (e.g. \b in \b uild). These will render incorrectly and make copy/paste unreliable. Convert these sections to standard triple-backtick code blocks and remove the stray escape/control characters.

diberry · 2026-03-29T16:43:48Z

Superseded by new PR with clean branch from upstream/dev (no fork-specific commits).

Copilot bot and others added 14 commits March 27, 2026 13:40

skill: add branch segregation rule to fork-first-pipeline

ac1576b

Prevents .squad/ stowaways on feature branches. Learned from 3 incidents on PR bradygaster#640. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Revert "feat: add PR requirements spec and PR template (#106 Phase 2)"

accd5c2

This reverts commit 8097c96.

Copilot AI review requested due to automatic review settings March 29, 2026 16:26

Copilot started reviewing on behalf of diberry March 29, 2026 16:27 View session

Copilot AI reviewed Mar 29, 2026

View reviewed changes

diberry closed this Mar 29, 2026

diberry mentioned this pull request Mar 29, 2026

docs(skill): add versioning policy #692

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(skill): add versioning policy — prevents prerelease version incidents#689

docs(skill): add versioning policy — prevents prerelease version incidents#689
diberry wants to merge 14 commits intobradygaster:devfrom
diberry:squad/versioning-policy

diberry commented Mar 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

diberry commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	mkdirSync, writeFileSync, readFileSync, rmSync,
	mkdirSync, readFileSync, rmSync,

Conversation

diberry commented Mar 29, 2026

Versioning Policy Skill

Why this is needed

Merge Order

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

diberry commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants