From cdf3afaa45b07d24480b89841481fb758bdeb374 Mon Sep 17 00:00:00 2001 From: "Earl Tankard, Jr., Ph.D" <45021016+primetimetank21@users.noreply.github.com> Date: Sat, 13 Jun 2026 00:39:52 -0400 Subject: [PATCH 1/2] chore: scrub residual squad/cast-name references (#481) Removes 3 squad-product skills entirely (.copilot/skills/): - architectural-proposals/ - client-compatibility/ - release-process/ Trims 5 skills to remove squad branding while preserving transferable patterns: - docs-standards: neutralized "Squad" adjectives, kept Microsoft Style Guide rules - gh-auth-isolation: already generic (no squad-specific examples found) - git-workflow: generalized .squad/ state section to "project state files" - github-multi-account: replaced .squad/bin path with ~/.local/bin, generic repo example - secret-handling: replaced all ~9 .squad/ path examples with generic "committed files" terminology Additional changes: - Removed orphaned SQUAD_WORKTREES section from CONTRIBUTING.md (lines 214-255) - Reworded setup.sh comment: "Pluto's installer" -> "installer script" - Fixed test label in test_windows_setup.ps1: "squad BEGIN and END markers" -> "dev-setup BEGIN and END markers" - Cleaned up orphaned references to deleted release-process skill in changelog-fold-completeness Remaining squad references are intentional: - gosquad alias in .aliases and README.md (deliberate KEEP, not in scope) - .squad/skills/ references in Clone HQ infrastructure docs (out of scope) ASCII-only verified: no non-ASCII characters detected. Shellcheck: PASS on scripts/linux/setup.sh. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../skills/architectural-proposals/SKILL.md | 151 ------- .../changelog-fold-completeness/SKILL.md | 6 +- .copilot/skills/client-compatibility/SKILL.md | 89 ---- .copilot/skills/docs-standards/SKILL.md | 20 +- .copilot/skills/git-workflow/SKILL.md | 10 +- .copilot/skills/github-multi-account/SKILL.md | 17 +- .copilot/skills/release-process/SKILL.md | 423 ------------------ .copilot/skills/secret-handling/SKILL.md | 24 +- CONTRIBUTING.md | 46 -- scripts/linux/setup.sh | 2 +- tests/test_windows_setup.ps1 | 2 +- 11 files changed, 40 insertions(+), 750 deletions(-) delete mode 100644 .copilot/skills/architectural-proposals/SKILL.md delete mode 100644 .copilot/skills/client-compatibility/SKILL.md delete mode 100644 .copilot/skills/release-process/SKILL.md diff --git a/.copilot/skills/architectural-proposals/SKILL.md b/.copilot/skills/architectural-proposals/SKILL.md deleted file mode 100644 index 61dc4bde..00000000 --- a/.copilot/skills/architectural-proposals/SKILL.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: "architectural-proposals" -description: "How to write comprehensive architectural proposals that drive alignment before code is written" -domain: "architecture, product-direction" -confidence: "high" -source: "earned (2026-02-21 interactive shell proposal)" -tools: - - name: "view" - description: "Read existing codebase, prior decisions, and team context before proposing changes" - when: "Always read .squad/decisions.md, relevant PRDs, and current architecture docs before writing proposal" - - name: "create" - description: "Create proposal in docs/proposals/ with structured format" - when: "After gathering context, before any implementation work begins" ---- - -## Context - -Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when: -- Architecture shifts invalidate existing assumptions -- Product direction changes require new foundation -- Multiple waves/milestones will be affected by a decision -- External dependencies (Copilot CLI, SDK APIs) change - -## Patterns - -### Proposal Structure (docs/proposals/) - -**Required sections:** -1. **Problem Statement** -- Why current state is broken (specific, measurable evidence) -2. **Proposed Architecture** -- Solution with technical specifics (not hand-waving) -3. **What Changes** -- Impact on existing work (waves, milestones, modules) -4. **What Stays the Same** -- Preserve existing functionality (no regression) -5. **Key Decisions Needed** -- Explicit choices with recommendations -6. **Risks and Mitigations** -- Likelihood + impact + mitigation strategy -7. **Scope** -- What's in v1, what's deferred (timeline clarity) - -**Optional sections:** -- Implementation Plan (high-level milestones) -- Success Criteria (measurable outcomes) -- Open Questions (unresolved items) -- Appendix (prior art, alternatives considered) - -### Tone Ceiling Enforcement - -**Always:** -- Cite specific evidence (user reports, performance data, failure modes) -- Justify recommendations with technical rationale -- Acknowledge trade-offs (no perfect solutions) -- Be specific about APIs, libraries, file paths - -**Never:** -- Hype ("revolutionary", "game-changing") -- Hand-waving ("we'll figure it out later") -- Unsubstantiated claims ("users will love this") -- Vague timelines ("soon", "eventually") - -### Wave Restructuring Pattern - -When a proposal invalidates existing wave structure: -1. **Acknowledge the shift:** "This becomes Wave 0 (Foundation)" -2. **Cascade impacts:** Adjust downstream waves (Wave 1, Wave 2, Wave 3) -3. **Preserve non-blocking work:** Identify what can proceed in parallel -4. **Update dependencies:** Document new blocking relationships - -**Example (Interactive Shell):** -- Wave 0 (NEW): Interactive Shell -- blocks all other waves -- Wave 1 (ADJUSTED): npm Distribution -- shell bundled in cli.js -- Wave 2 (DEFERRED): SquadUI -- waits for shell foundation -- Wave 3 (ADJUSTED): Public Docs -- now documents shell as primary interface - -### Decision Framing - -**Format:** "Recommendation: X (recommended) or alternatives?" - -**Components:** -- Recommendation (pick one, justify) -- Alternatives (what else was considered) -- Decision rationale (why recommended option wins) -- Needs sign-off from (which agents/roles must approve) - -**Example:** -``` -### 1. Terminal UI Library: `ink` (recommended) or alternatives? - -**Recommendation:** `ink` -**Alternatives:** `blessed`, raw readline -**Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. - -**Needs sign-off from:** Brady (product direction), Fortier (runtime performance) -``` - -### Risk Documentation - -**Format per risk:** -- **Risk:** Specific failure mode -- **Likelihood:** Low / Medium / High (not percentages) -- **Impact:** Low / Medium / High -- **Mitigation:** Concrete actions (measurable) - -**Example:** -``` -### Risk 2: SDK Streaming Reliability - -**Risk:** SDK streaming events might drop messages or arrive out of order. -**Likelihood:** Low (SDK is production-grade). -**Impact:** High -- broken streaming makes shell unusable. - -**Mitigation:** -- Add integration test: Send 1000-message stream, verify all deltas arrive in order -- Implement fallback: If streaming fails, fall back to polling session state -- Log all SDK events to `.squad/orchestration-log/sdk-events.jsonl` for debugging -``` - -## Examples - -**File references from interactive shell proposal:** -- Full proposal: `docs/proposals/squad-interactive-shell.md` -- User directive: `.squad/decisions/inbox/copilot-directive-2026-02-21T202535Z.md` -- Team decisions: `.squad/decisions.md` -- Current architecture: `docs/architecture/module-map.md`, `docs/prd-23-release-readiness.md` - -**Key patterns demonstrated:** -1. Read user directive first (understand the "why") -2. Survey current architecture (module map, existing waves) -3. Research SDK APIs (exploration task to validate feasibility) -4. Document problem with specific evidence (unreliable handoffs, zero visibility, UX mismatch) -5. Propose solution with technical specifics (ink components, SDK session management, spawn.ts module) -6. Restructure waves when foundation shifts (Wave 0 becomes blocker) -7. Preserve backward compatibility (squad.agent.md still works, VS Code mode unchanged) -8. Frame decisions explicitly (5 key decisions with recommendations) -9. Document risks with mitigations (5 risks, each with concrete actions) -10. Define scope (what's in v1 vs. deferred) - -## Anti-Patterns - -**Avoid:** -- [ ] Proposals without problem statements (solution-first thinking) -- [ ] Vague architecture ("we'll use a shell") -- be specific (ink components, session registry, spawn.ts) -- [ ] Ignoring existing work -- always document impact on waves/milestones -- [ ] No risk analysis -- every architecture has risks, document them -- [ ] Unbounded scope -- draw the v1 line explicitly -- [ ] Missing decision ownership -- always say "needs sign-off from X" -- [ ] No backward compatibility plan -- users don't care about your replatform -- [ ] Hand-waving timelines ("a few weeks") -- be specific (2-3 weeks, 1 engineer full-time) - -**Red flags in proposal reviews:** -- "Users will love this" (citation needed) -- "We'll figure out X later" (scope creep incoming) -- "This is revolutionary" (tone ceiling violation) -- No section on "What Stays the Same" (regression risk) -- No risks documented (wishful thinking) diff --git a/.copilot/skills/changelog-fold-completeness/SKILL.md b/.copilot/skills/changelog-fold-completeness/SKILL.md index 5beddb1e..f9124f07 100644 --- a/.copilot/skills/changelog-fold-completeness/SKILL.md +++ b/.copilot/skills/changelog-fold-completeness/SKILL.md @@ -168,9 +168,7 @@ never failed to find missing entries when applied. ## Placement decision This skill lives in `.copilot/skills/` (process automation level) rather than project-specific -workflow. Rationale: the fold step is performed during a release cut -- it is release-process -governance, not day-to-day workflow. The release automation is responsible for ensuring the -fold is gated on completeness. +workflow. The release automation is responsible for ensuring the fold is gated on completeness. Compare with other append-based hygiene checks which govern individual contributions. @@ -180,8 +178,6 @@ Compare with other append-based hygiene checks which govern individual contribut `--base develop`; if any PR was misrouted (base=main), the gh queries in Steps 4-5 will miss it; verify develop ancestry with `git log $LAST_TAG..develop --merges` as the authoritative source. -- `.copilot/skills/release-process/SKILL.md` -- the full release runbook; this skill - is a pre-step for the fold phase of that runbook. - `.squad/skills/history-md-pre-size-check/SKILL.md` -- companion hygiene check (contributor-level); ensures history files are within gate before the sprint closes and before the release audit. diff --git a/.copilot/skills/client-compatibility/SKILL.md b/.copilot/skills/client-compatibility/SKILL.md deleted file mode 100644 index 130bd600..00000000 --- a/.copilot/skills/client-compatibility/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -name: "client-compatibility" -description: "Platform detection and adaptive spawning for CLI vs VS Code vs other surfaces" -domain: "orchestration" -confidence: "high" -source: "extracted" ---- - -## Context - -Squad runs on multiple Copilot surfaces (CLI, VS Code, JetBrains, GitHub.com). The coordinator must detect its platform and adapt spawning behavior accordingly. Different tools are available on different platforms, requiring conditional logic for agent spawning, SQL usage, and response timing. - -## Patterns - -### Platform Detection - -Before spawning agents, determine the platform by checking available tools: - -1. **CLI mode** -- `task` tool is available -> full spawning control. Use `task` with `agent_type`, `mode`, `model`, `description`, `prompt` parameters. Collect results via `read_agent`. - -2. **VS Code mode** -- `runSubagent` or `agent` tool is available -> conditional behavior. Use `runSubagent` with the task prompt. Drop `agent_type`, `mode`, and `model` parameters. Multiple subagents in one turn run concurrently (equivalent to background mode). Results return automatically -- no `read_agent` needed. - -3. **Fallback mode** -- neither `task` nor `runSubagent`/`agent` available -> work inline. Do not apologize or explain the limitation. Execute the task directly. - -If both `task` and `runSubagent` are available, prefer `task` (richer parameter surface). - -### VS Code Spawn Adaptations - -When in VS Code mode, the coordinator changes behavior in these ways: - -- **Spawning tool:** Use `runSubagent` instead of `task`. The prompt is the only required parameter -- pass the full agent prompt (charter, identity, task, hygiene, response order) exactly as you would on CLI. -- **Parallelism:** Spawn ALL concurrent agents in a SINGLE turn. They run in parallel automatically. This replaces `mode: "background"` + `read_agent` polling. -- **Model selection:** Accept the session model. Do NOT attempt per-spawn model selection or fallback chains -- they only work on CLI. In Phase 1, all subagents use whatever model the user selected in VS Code's model picker. -- **Scribe:** Cannot fire-and-forget. Batch Scribe as the LAST subagent in any parallel group. Scribe is light work (file ops only), so the blocking is tolerable. -- **Launch table:** Skip it. Results arrive with the response, not separately. By the time the coordinator speaks, the work is already done. -- **`read_agent`:** Skip entirely. Results return automatically when subagents complete. -- **`agent_type`:** Drop it. All VS Code subagents have full tool access by default. Subagents inherit the parent's tools. -- **`description`:** Drop it. The agent name is already in the prompt. -- **Prompt content:** Keep ALL prompt structure -- charter, identity, task, hygiene, response order blocks are surface-independent. - -### Feature Degradation Table - -| Feature | CLI | VS Code | Degradation | -|---------|-----|---------|-------------| -| Parallel fan-out | `mode: "background"` + `read_agent` | Multiple subagents in one turn | None -- equivalent concurrency | -| Model selection | Per-spawn `model` param (4-layer hierarchy) | Session model only (Phase 1) | Accept session model, log intent | -| Scribe fire-and-forget | Background, never read | Sync, must wait | Batch with last parallel group | -| Launch table UX | Show table -> results later | Skip table -> results with response | UX only -- results are correct | -| SQL tool | Available | Not available | Avoid SQL in cross-platform code paths | -| Response order bug | Critical workaround | Possibly necessary (unverified) | Keep the block -- harmless if unnecessary | - -### SQL Tool Caveat - -The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitHub.com. Any coordinator logic or agent workflow that depends on SQL (todo tracking, batch processing, session state) will silently fail on non-CLI surfaces. Cross-platform code paths must not depend on SQL. Use filesystem-based state (`.squad/` files) for anything that must work everywhere. - -## Examples - -**Example 1: CLI parallel spawn** -```typescript -// Coordinator detects task tool available -> CLI mode -task({ agent_type: "general-purpose", mode: "background", model: "claude-sonnet-4.5", ... }) -task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4.5", ... }) -// Later: read_agent for both -``` - -**Example 2: VS Code parallel spawn** -```typescript -// Coordinator detects runSubagent available -> VS Code mode -runSubagent({ prompt: "...Fenster charter + task..." }) -runSubagent({ prompt: "...Hockney charter + task..." }) -runSubagent({ prompt: "...Scribe charter + task..." }) // Last in group -// Results return automatically, no read_agent -``` - -**Example 3: Fallback mode** -```typescript -// Neither task nor runSubagent available -> work inline -// Coordinator executes the task directly without spawning -``` - -## Anti-Patterns - -- [ ] Using SQL tool in cross-platform workflows (breaks on VS Code/JetBrains/GitHub.com) -- [ ] Attempting per-spawn model selection on VS Code (Phase 1 -- only session model works) -- [ ] Fire-and-forget Scribe on VS Code (must batch as last subagent) -- [ ] Showing launch table on VS Code (results already inline) -- [ ] Apologizing or explaining platform limitations to the user -- [ ] Using `task` when only `runSubagent` is available -- [ ] Dropping prompt structure (charter/identity/task) on non-CLI platforms diff --git a/.copilot/skills/docs-standards/SKILL.md b/.copilot/skills/docs-standards/SKILL.md index a0c24dd9..a10e8efd 100644 --- a/.copilot/skills/docs-standards/SKILL.md +++ b/.copilot/skills/docs-standards/SKILL.md @@ -1,6 +1,6 @@ --- name: "docs-standards" -description: "Microsoft Style Guide + Squad-specific documentation patterns" +description: "Microsoft Style Guide + documentation patterns" domain: "documentation" confidence: "high" source: "earned (PAO charter, multiple doc PR reviews)" @@ -8,7 +8,7 @@ source: "earned (PAO charter, multiple doc PR reviews)" ## Context -Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability. +Documentation follows the Microsoft Style Guide with project-specific conventions. Consistency across docs builds trust and improves discoverability. ## Patterns @@ -19,7 +19,7 @@ Squad documentation follows the Microsoft Style Guide with Squad-specific conven - **Present tense:** "The system routes..." not "The system will route..." - **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements) -### Squad Formatting Patterns +### Documentation Formatting Patterns - **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data - **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy - **Experimental warnings:** Features in preview get callout at top @@ -35,31 +35,31 @@ Squad documentation follows the Microsoft Style Guide with Squad-specific conven ? **Correct:** ```markdown -# Getting started with Squad +# Getting started with the project > ! **Experimental:** This feature is in preview. Try this: \`\`\`bash -squad init +init \`\`\` -Squad helps you build AI teams... +This project helps you build... --- -## Install Squad +## Install the tool Run the following command... ``` ? **Incorrect:** ```markdown -# Getting Started With Squad // Title case +# Getting Started With the Project // Title case -Squad is a tool which will help users... // Third person, future tense +The tool is designed to help users... // Third person, future tense -You can install Squad with npm & configure it... // Ampersand in prose +You can install it with npm & configure it... // Ampersand in prose ``` ## Anti-Patterns diff --git a/.copilot/skills/git-workflow/SKILL.md b/.copilot/skills/git-workflow/SKILL.md index 77885b77..ac9cea8c 100644 --- a/.copilot/skills/git-workflow/SKILL.md +++ b/.copilot/skills/git-workflow/SKILL.md @@ -114,12 +114,12 @@ gh pr create --base develop --title "fix: stamp bug" --body "Closes #195" --draf All PRs target `develop` independently. Multiple worktrees don't interfere with each other's filesystem. -### .squad/ State in Worktrees +### Project State Files in Worktrees -The `.squad/` directory (if present) exists in each worktree as a copy. This is safe because: -- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs) -- Each process appends to its own section; union merge reconciles on PR merge to develop -- **Rule:** Never rewrite or reorder `.squad/` files in a worktree -- append only +Project-specific state files (if present) exist in each worktree as a copy. To avoid conflicts on merge: +- Configure `.gitattributes` to use `merge=union` for append-only files +- Each process appends its own section; union merge reconciles sections on PR merge +- **Rule:** Never rewrite or reorder state files in a worktree -- append only ### Cleanup After Merge diff --git a/.copilot/skills/github-multi-account/SKILL.md b/.copilot/skills/github-multi-account/SKILL.md index f78a8c9d..5a738adc 100644 --- a/.copilot/skills/github-multi-account/SKILL.md +++ b/.copilot/skills/github-multi-account/SKILL.md @@ -2,7 +2,7 @@ name: github-multi-account description: Detect and set up account-locked gh aliases for multi-account GitHub. The AI reads this skill, detects accounts, asks the user which is personal/work, and runs the setup automatically. confidence: high -source: https://github.com/tamirdresher/squad-skills/tree/main/plugins/github-multi-account +source: earned (multi-account patterns from GitHub CLI documentation) author: tamirdresher --- @@ -45,7 +45,7 @@ Set-Alias ghw gh-work } # 3. Create CMD wrappers -$binDir = Join-Path $env:USERPROFILE ".squad\bin" +$binDir = Join-Path $env:USERPROFILE ".local\bin" if (!(Test-Path $binDir)) { New-Item -ItemType Directory -Path $binDir -Force | Out-Null } "@echo off`ngh auth switch --user $personal >nul 2>&1`ngh %*" | Out-File "$binDir\ghp.cmd" -Encoding ascii "@echo off`ngh auth switch --user $work >nul 2>&1`ngh %*" | Out-File "$binDir\ghw.cmd" -Encoding ascii @@ -84,12 +84,15 @@ ghw api user --jq '.login' # should show work username ## Repo-Specific Account Binding -This repo (`bradygaster/squad`) is bound to the **bradygaster** (personal) account. -All `gh` operations in this repo MUST use `ghp` / `gh-personal`. +Each repository is bound to a specific account based on ownership. +All `gh` operations in that repo MUST use the appropriate alias (personal or work). + +Example: if `owner/repo` is your personal project, use `ghp` / `gh-personal`. + +## For Automation Agents -## For Squad Agents At the TOP of any script touching GitHub, define: ```powershell -function gh-personal { gh auth switch --user bradygaster 2>$null | Out-Null; gh @args } -function gh-work { gh auth switch --user bradyg_microsoft 2>$null | Out-Null; gh @args } +function gh-personal { gh auth switch --user $personal 2>$null | Out-Null; gh @args } +function gh-work { gh auth switch --user $work 2>$null | Out-Null; gh @args } ``` diff --git a/.copilot/skills/release-process/SKILL.md b/.copilot/skills/release-process/SKILL.md deleted file mode 100644 index 5eb066b2..00000000 --- a/.copilot/skills/release-process/SKILL.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -name: "release-process" -description: "Step-by-step release checklist for Squad -- prevents v0.8.22-style disasters" -domain: "release-management" -confidence: "high" -source: "team-decision" ---- - -## Context - -This is the **definitive release runbook** for Squad. Born from the v0.8.22 release disaster (4-part semver mangled by npm, draft release never triggered publish, wrong NPM_TOKEN type, 6+ hours of broken `latest` dist-tag). - -**Rule:** No agent releases Squad without following this checklist. No exceptions. No improvisation. - ---- - -## Pre-Release Validation - -Before starting ANY release work, validate the following: - -### 1. Version Number Validation - -**Rule:** Only 3-part semver (major.minor.patch) or prerelease (major.minor.patch-tag.N) are valid. 4-part versions (0.8.21.4) are NOT valid semver and npm will mangle them. - -```bash -# Check version is valid semver -node -p "require('semver').valid('0.8.22')" -# Output: '0.8.22' = valid -# Output: null = INVALID, STOP - -# For prerelease versions -node -p "require('semver').valid('0.8.23-preview.1')" -# Output: '0.8.23-preview.1' = valid -``` - -**If `semver.valid()` returns `null`:** STOP. Fix the version. Do NOT proceed. - -### 2. NPM_TOKEN Verification - -**Rule:** NPM_TOKEN must be an **Automation token** (no 2FA required). User tokens with 2FA will fail in CI with EOTP errors. - -```bash -# Check token type (requires npm CLI authenticated) -npm token list -``` - -Look for: -- [x] `read-write` tokens with NO 2FA requirement = Automation token (correct) -- [ ] Tokens requiring OTP = User token (WRONG, will fail in CI) - -**How to create an Automation token:** -1. Go to npmjs.com -> Settings -> Access Tokens -2. Click "Generate New Token" -3. Select **"Automation"** (NOT "Publish") -4. Copy token and save as GitHub secret: `NPM_TOKEN` - -**If using a User token:** STOP. Create an Automation token first. - -### 3. Branch and Tag State - -**Rule:** Release from `main` branch. Ensure clean state, no uncommitted changes, latest from origin. - -```bash -# Ensure on main and clean -git checkout main -git pull origin main -git status # Should show: "nothing to commit, working tree clean" - -# Check tag doesn't already exist -git tag -l "v0.8.22" -# Output should be EMPTY. If tag exists, release already done or collision. -``` - -**If tag exists:** STOP. Either release was already done, or there's a collision. Investigate before proceeding. - -### 4. Disable bump-build.mjs - -**Rule:** `bump-build.mjs` is for dev builds ONLY. It must NOT run during release builds (it increments build numbers, creating 4-part versions). - -```bash -# Set env var to skip bump-build.mjs -export SKIP_BUILD_BUMP=1 - -# Verify it's set -echo $SKIP_BUILD_BUMP -# Output: 1 -``` - -**For Windows PowerShell:** -```powershell -$env:SKIP_BUILD_BUMP = "1" -``` - -**If not set:** `bump-build.mjs` will run and mutate versions. This causes disasters (see v0.8.22). - ---- - -## Release Workflow - -### Step 1: Version Bump - -Update version in all 3 package.json files (root + both workspaces) in lockstep. - -```bash -# Set target version (no 'v' prefix) -VERSION="0.8.22" - -# Validate it's valid semver BEFORE proceeding -node -p "require('semver').valid('$VERSION')" -# Must output the version string, NOT null - -# Update all 3 package.json files -npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version - -# Verify all 3 match -grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json -# All 3 should show: "version": "0.8.22" -``` - -**Checkpoint:** All 3 package.json files have identical versions. Run `semver.valid()` one more time to be sure. - -### Step 2: Commit and Tag - -```bash -# Commit version bump -git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json -git commit -m "chore: bump version to $VERSION - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" - -# Create tag (with 'v' prefix) -git tag -a "v$VERSION" -m "Release v$VERSION" - -# Push commit and tag -git push origin main -git push origin "v$VERSION" -``` - -**Checkpoint:** Tag created and pushed. Verify with `git tag -l "v$VERSION"`. - -### Step 3: Create GitHub Release - -**CRITICAL:** Release must be **published**, NOT draft. Draft releases don't trigger `publish.yml` workflow. - -```bash -# Create GitHub Release (NOT draft) -gh release create "v$VERSION" \ - --title "v$VERSION" \ - --notes "Release notes go here" \ - --latest - -# Verify release is PUBLISHED (not draft) -gh release view "v$VERSION" -# Output should NOT contain "(draft)" -``` - -**If output contains `(draft)`:** STOP. Delete the release and recreate without `--draft` flag. - -```bash -# If you accidentally created a draft, fix it: -gh release edit "v$VERSION" --draft=false -``` - -**Checkpoint:** Release is published (NOT draft). The `release: published` event fired and triggered `publish.yml`. - -### Step 4: Monitor Workflow - -The `publish.yml` workflow should start automatically within 10 seconds of release creation. - -```bash -# Watch workflow runs -gh run list --workflow=publish.yml --limit 1 - -# Get detailed status -gh run view --log -``` - -**Expected flow:** -1. `publish-sdk` job runs -> publishes `@bradygaster/squad-sdk` -2. Verify step runs with retry loop (up to 5 attempts, 15s interval) to confirm SDK on npm registry -3. `publish-cli` job runs -> publishes `@bradygaster/squad-cli` -4. Verify step runs with retry loop to confirm CLI on npm registry - -**If workflow fails:** Check the logs. Common issues: -- EOTP error = wrong NPM_TOKEN type (use Automation token) -- Verify step timeout = npm propagation delay (retry loop should handle this, but propagation can take up to 2 minutes in rare cases) -- Version mismatch = package.json version doesn't match tag - -**Checkpoint:** Both jobs succeeded. Workflow shows green checkmarks. - -### Step 5: Verify npm Publication - -Manually verify both packages are on npm with correct `latest` dist-tag. - -```bash -# Check SDK -npm view @bradygaster/squad-sdk version -# Output: 0.8.22 - -npm dist-tag ls @bradygaster/squad-sdk -# Output should show: latest: 0.8.22 - -# Check CLI -npm view @bradygaster/squad-cli version -# Output: 0.8.22 - -npm dist-tag ls @bradygaster/squad-cli -# Output should show: latest: 0.8.22 -``` - -**If versions don't match:** Something went wrong. Check workflow logs. DO NOT proceed with GitHub Release announcement until npm is correct. - -**Checkpoint:** Both packages show correct version. `latest` dist-tags point to the new version. - -### Step 6: Test Installation - -Verify packages can be installed from npm (real-world smoke test). - -```bash -# Create temp directory -mkdir /tmp/squad-release-test && cd /tmp/squad-release-test - -# Test SDK installation -npm init -y -npm install @bradygaster/squad-sdk -node -p "require('@bradygaster/squad-sdk/package.json').version" -# Output: 0.8.22 - -# Test CLI installation -npm install -g @bradygaster/squad-cli -squad --version -# Output: 0.8.22 - -# Cleanup -cd - -rm -rf /tmp/squad-release-test -``` - -**If installation fails:** npm registry issue or package metadata corruption. DO NOT announce release until this works. - -**Checkpoint:** Both packages install cleanly. Versions match. - -### Step 7: Sync dev to Next Preview - -After main release, sync dev to the next preview version. - -```bash -# Checkout dev -git checkout dev -git pull origin dev - -# Bump to next preview version (e.g., 0.8.23-preview.1) -NEXT_VERSION="0.8.23-preview.1" - -# Validate semver -node -p "require('semver').valid('$NEXT_VERSION')" -# Must output the version string, NOT null - -# Update all 3 package.json files -npm version $NEXT_VERSION --workspaces --include-workspace-root --no-git-tag-version - -# Commit -git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json -git commit -m "chore: bump dev to $NEXT_VERSION - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" - -# Push -git push origin dev -``` - -**Checkpoint:** dev branch now shows next preview version. Future dev builds will publish to `@preview` dist-tag. - ---- - -## Manual Publish (Fallback) - -If `publish.yml` workflow fails or needs to be bypassed, use `workflow_dispatch` to manually trigger publish. - -```bash -# Trigger manual publish -gh workflow run publish.yml -f version="0.8.22" - -# Monitor the run -gh run watch -``` - -**Rule:** Only use this if automated publish failed. Always investigate why automation failed and fix it for next release. - ---- - -## Rollback Procedure - -If a release is broken and needs to be rolled back: - -### 1. Unpublish from npm (Nuclear Option) - -**WARNING:** npm unpublish is time-limited (24 hours) and leaves the version slot burned. Only use if version is critically broken. - -```bash -# Unpublish (requires npm owner privileges) -npm unpublish @bradygaster/squad-sdk@0.8.22 -npm unpublish @bradygaster/squad-cli@0.8.22 -``` - -### 2. Deprecate on npm (Preferred) - -**Preferred approach:** Mark version as deprecated, publish a hotfix. - -```bash -# Deprecate broken version -npm deprecate @bradygaster/squad-sdk@0.8.22 "Broken release, use 0.8.22.1 instead" -npm deprecate @bradygaster/squad-cli@0.8.22 "Broken release, use 0.8.22.1 instead" - -# Publish hotfix version -# (Follow this runbook with version 0.8.22.1) -``` - -### 3. Delete GitHub Release and Tag - -```bash -# Delete GitHub Release -gh release delete "v0.8.22" --yes - -# Delete tag locally and remotely -git tag -d "v0.8.22" -git push origin --delete "v0.8.22" -``` - -### 4. Revert Commit on main - -```bash -# Revert version bump commit -git checkout main -git revert HEAD -git push origin main -``` - -**Checkpoint:** Tag and release deleted. main branch reverted. npm packages deprecated or unpublished. - ---- - -## Common Failure Modes - -### EOTP Error (npm OTP Required) - -**Symptom:** Workflow fails with `EOTP` error. -**Root cause:** NPM_TOKEN is a User token with 2FA enabled. CI can't provide OTP. -**Fix:** Replace NPM_TOKEN with an Automation token (no 2FA). See "NPM_TOKEN Verification" above. - -### Verify Step 404 (npm Propagation Delay) - -**Symptom:** Verify step fails with 404 even though publish succeeded. -**Root cause:** npm registry propagation delay (5-30 seconds). -**Fix:** Verify step now has retry loop (5 attempts, 15s interval). Should auto-resolve. If not, wait 2 minutes and re-run workflow. - -### Version Mismatch (package.json ? tag) - -**Symptom:** Verify step fails with "Package version (X) does not match target version (Y)". -**Root cause:** package.json version doesn't match the tag version. -**Fix:** Ensure all 3 package.json files were updated in Step 1. Re-run `npm version` if needed. - -### 4-Part Version Mangled by npm - -**Symptom:** Published version on npm doesn't match package.json (e.g., 0.8.21.4 became 0.8.2-1.4). -**Root cause:** 4-part versions are NOT valid semver. npm's parser misinterprets them. -**Fix:** NEVER use 4-part versions. Only 3-part (0.8.22) or prerelease (0.8.23-preview.1). Run `semver.valid()` before ANY commit. - -### Draft Release Didn't Trigger Workflow - -**Symptom:** Release created but `publish.yml` never ran. -**Root cause:** Release was created as a draft. Draft releases don't emit `release: published` event. -**Fix:** Edit release and change to published: `gh release edit "v$VERSION" --draft=false`. Workflow should trigger immediately. - ---- - -## Validation Checklist - -Before starting ANY release, confirm: - -- [ ] Version is valid semver: `node -p "require('semver').valid('VERSION')"` returns the version string (NOT null) -- [ ] NPM_TOKEN is an Automation token (no 2FA): `npm token list` shows `read-write` without OTP requirement -- [ ] Branch is clean: `git status` shows "nothing to commit, working tree clean" -- [ ] Tag doesn't exist: `git tag -l "vVERSION"` returns empty -- [ ] `SKIP_BUILD_BUMP=1` is set: `echo $SKIP_BUILD_BUMP` returns `1` - -Before creating GitHub Release: - -- [ ] All 3 package.json files have matching versions: `grep '"version"' package.json packages/*/package.json` -- [ ] Commit is pushed: `git log origin/main..main` returns empty -- [ ] Tag is pushed: `git ls-remote --tags origin vVERSION` returns the tag SHA - -After GitHub Release: - -- [ ] Release is published (NOT draft): `gh release view "vVERSION"` output doesn't contain "(draft)" -- [ ] Workflow is running: `gh run list --workflow=publish.yml --limit 1` shows "in_progress" - -After workflow completes: - -- [ ] Both jobs succeeded: Workflow shows green checkmarks -- [ ] SDK on npm: `npm view @bradygaster/squad-sdk version` returns correct version -- [ ] CLI on npm: `npm view @bradygaster/squad-cli version` returns correct version -- [ ] `latest` tags correct: `npm dist-tag ls @bradygaster/squad-sdk` shows `latest: VERSION` -- [ ] Packages install: `npm install @bradygaster/squad-cli` succeeds - -After dev sync: - -- [ ] dev branch has next preview version: `git show dev:package.json | grep version` shows next preview - ---- - -## Post-Mortem Reference - -This skill was created after the v0.8.22 release disaster. Full retrospective: `.squad/decisions/inbox/keaton-v0822-retrospective.md` - -**Key learnings:** -1. No release without a runbook = improvisation = disaster -2. Semver validation is mandatory -- 4-part versions break npm -3. NPM_TOKEN type matters -- User tokens with 2FA fail in CI -4. Draft releases are a footgun -- they don't trigger automation -5. Retry logic is essential -- npm propagation takes time - -**Never again.** diff --git a/.copilot/skills/secret-handling/SKILL.md b/.copilot/skills/secret-handling/SKILL.md index 00b19bc2..4f8b4de5 100644 --- a/.copilot/skills/secret-handling/SKILL.md +++ b/.copilot/skills/secret-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: secret-handling -description: Never read .env files or write secrets to .squad/ committed files +description: Never read .env files or write secrets to version-controlled committed files domain: security, file-operations, team-collaboration confidence: high source: earned (issue #267 -- credential leak incident) @@ -8,7 +8,7 @@ source: earned (issue #267 -- credential leak incident) ## Context -Spawned agents have read access to the entire repository, including `.env` files containing live credentials. If an agent reads secrets and writes them to `.squad/` files (decisions, logs, history), Scribe auto-commits them to git, exposing them in remote history. This skill codifies absolute prohibitions and safe alternatives. +Spawned agents have read access to the entire repository, including `.env` files containing live credentials. If an agent reads secrets and writes them to version-controlled files that get auto-committed, they expose credentials in remote history. This skill codifies absolute prohibitions and safe alternatives. ## Patterns @@ -37,7 +37,7 @@ Spawned agents have read access to the entire repository, including `.env` files ### Prohibited Output Patterns -**NEVER write these to `.squad/` files:** +**NEVER write these to committed/tracked files:** | Pattern Type | Examples | Regex Pattern (for scanning) | |--------------|----------|-------------------------------| @@ -57,7 +57,7 @@ Spawned agents have read access to the entire repository, including `.env` files ### Scribe Pre-Commit Validation -**Before committing `.squad/` changes, Scribe MUST:** +**Before committing version-controlled file changes, validation MUST:** 1. **Scan all staged files** for secret patterns (use regex table above) 2. **Check for prohibited file names** (don't commit `.env` even if manually staged) @@ -68,7 +68,7 @@ Spawned agents have read access to the entire repository, including `.env` files ``` ? SECRET DETECTED -- commit blocked - File: .squad/decisions/inbox/river-db-config.md + File: decisions/inbox/river-db-config.md Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod This file contains credentials and MUST NOT be committed. @@ -95,7 +95,7 @@ Spawned agents have read access to the entire repository, including `.env` files A secret was found in git history: Commit: abc1234 - File: .squad/decisions/inbox/agent-config.md + File: decisions/inbox/agent-config.md Pattern: API_KEY=sk-proj-... This requires immediate remediation: @@ -121,7 +121,7 @@ Agent: "What environment variables does this app need?" DATABASE_URL=postgres://user:pass@localhost:5432/db REDIS_URL=redis://localhost:6379 --> Writes to .squad/decisions/inbox/river-env-setup.md: +-> Writes to decisions/inbox/river-env-setup.md: "App requires three environment variables: - OPENAI_API_KEY (OpenAI API key, format: sk-...) - DATABASE_URL (Postgres connection string) @@ -137,7 +137,7 @@ Agent: "What environment variables does this app need?" Agent: (reads .env) DATABASE_URL=postgres://admin:super_secret_pw@prod.example.com:5432/appdb --> Writes to .squad/decisions/inbox/river-db-schema.md: +-> Writes to decisions/inbox/river-db-schema.md: "Database connection: postgres://admin:super_secret_pw@prod.example.com:5432/appdb" ? VIOLATION: Live credential written to committed file @@ -148,7 +148,7 @@ Agent: (reads .env) Agent: (reads .env.example OR asks user) User: "It's a Postgres database, schema is in migrations/" --> Writes to .squad/decisions/inbox/river-db-schema.md: +-> Writes to decisions/inbox/river-db-schema.md: "Database: Postgres (connection configured in .env). Schema defined in db/migrations/." ``` @@ -158,7 +158,7 @@ User: "It's a Postgres database, schema is in migrations/" ```powershell # Stage files -git add .squad/ +git add . # Scan staged content for secrets $stagedContent = git diff --cached @@ -179,7 +179,7 @@ foreach ($pattern in $secretPatterns) { if ($detected) { # Remove from staging, report, exit - git reset HEAD .squad/ + git reset HEAD . Write-Error "Commit blocked -- secret detected in staged files" exit 1 } @@ -196,5 +196,5 @@ git commit -F $msgFile - [ ] Committing first, scanning later -- validation MUST happen before commit - [ ] Silently skipping secret detection -- fail loud, never silent - [ ] Trusting agents to "know better" -- enforce at multiple layers (prompt, hook, architecture) -- [ ] Writing secrets to "temporary" files in `.squad/` -- Scribe commits ALL `.squad/` changes +- [ ] Writing secrets to "temporary" files in version-controlled directories -- all changes get committed - [ ] Extracting "just the host" from a connection string -- still leaks infrastructure topology diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e893bb39..f9767e2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -209,52 +209,6 @@ A direct push to `main` is permitted ONLY when ALL of the following conditions a --- ---- - -## Parallel Work - -### Why worktree isolation matters - -In past work, concurrent development on different issues in the same working tree caused branch-checkout race conditions. Wrong content landed on the wrong branch, and PRs had to be closed and recreated. - -### How to enable it - -Set `SQUAD_WORKTREES=1` before starting work where parallel development is expected: - -```bash -export SQUAD_WORKTREES=1 -``` - -Or add it permanently to your `.env` / shell profile. The devcontainer sets it by default in `remoteEnv`. - -When enabled, coordinators or automation can create an isolated `git worktree` for each issue. Branch checkouts inside one worktree never affect any other. - -### Worktree path convention - -``` -{repo-parent}/{repo-name}-{issue-number} -``` - -**Example:** for issue #56 inside `/workspaces/dev-setup`, the worktree is created at: - -``` -/workspaces/dev-setup-56/ -``` - -Each worktree has its own index and working files but shares the same `.git` object store with the main repo -- no extra disk space for history, just the working tree. - -### Cleaning up - -Worktrees are not automatically removed. After a PR is merged, clean up with: - -```bash -git worktree remove /workspaces/dev-setup-56 -``` - -Or list all active worktrees with `git worktree list`. - ---- - ## Test Harness Pattern Bash test files in `tests/*.sh` follow a **tally-based harness convention**: each assertion diff --git a/scripts/linux/setup.sh b/scripts/linux/setup.sh index 660300b0..0e7a0d92 100755 --- a/scripts/linux/setup.sh +++ b/scripts/linux/setup.sh @@ -86,7 +86,7 @@ main() { run_tool "auth" run_tool "copilot-cli" - # Apply dotfiles if Pluto's installer exists + # Apply dotfiles if installer script exists local dotfiles_script="${REPO_ROOT}/config/dotfiles/install.sh" if [[ -f "$dotfiles_script" ]]; then log_info "Applying dotfiles..." diff --git a/tests/test_windows_setup.ps1 b/tests/test_windows_setup.ps1 index c26a5089..043e6d03 100644 --- a/tests/test_windows_setup.ps1 +++ b/tests/test_windows_setup.ps1 @@ -875,7 +875,7 @@ Test-Scenario "N-2: Write-PowerShellProfile writes to the PS 7+ profile path" { } } -Test-Scenario "N-3: Profile content heredoc includes the squad BEGIN and END markers" { +Test-Scenario "N-3: Profile content heredoc includes the dev-setup BEGIN and END markers" { if ($profileToolContent -notmatch '# BEGIN dev-setup profile') { throw "profile.ps1 does not contain '# BEGIN dev-setup profile' marker" } From 68680af5b918f562f35a0952e46451a97198c8e5 Mon Sep 17 00:00:00 2001 From: "Earl Tankard, Jr., Ph.D" <45021016+primetimetank21@users.noreply.github.com> Date: Sat, 13 Jun 2026 00:43:53 -0400 Subject: [PATCH 2/2] chore: remove dangling .squad/ cross-refs from changelog-fold skill (#481) Remove three dead cross-references to HQ-internal skills and retros that do not exist in dev-setup: - .squad/skills/gh-pr-base-develop/SKILL.md - .squad/skills/history-md-pre-size-check/SKILL.md - .squad/retros/2026-05-18-sprint-17-retro.md Also remove the now-empty "Related Skills" section. The References section is preserved with only dev-setup-relevant items. Changelog-fold recipe and guidance remain unchanged. Verified: git grep confirms zero remaining .squad/ or product references in the file and throughout .copilot/ Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .copilot/skills/changelog-fold-completeness/SKILL.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/.copilot/skills/changelog-fold-completeness/SKILL.md b/.copilot/skills/changelog-fold-completeness/SKILL.md index f9124f07..5e94cd22 100644 --- a/.copilot/skills/changelog-fold-completeness/SKILL.md +++ b/.copilot/skills/changelog-fold-completeness/SKILL.md @@ -172,21 +172,9 @@ workflow. The release automation is responsible for ensuring the fold is gated o Compare with other append-based hygiene checks which govern individual contributions. -## Related Skills - -- `.squad/skills/gh-pr-base-develop/SKILL.md` -- every PR must pass - `--base develop`; if any PR was misrouted (base=main), the gh queries in Steps 4-5 - will miss it; verify develop ancestry with `git log $LAST_TAG..develop --merges` - as the authoritative source. -- `.squad/skills/history-md-pre-size-check/SKILL.md` -- companion hygiene check - (contributor-level); ensures history files are within gate before the sprint - closes and before the release audit. - ## References - Issue #399 -- formalization request (Sprint 18) -- Sprint 17 retro (`.squad/retros/2026-05-18-sprint-17-retro.md`) -- "Key learnings: - RECURRING: Pre-append history.md size check missing" and release completeness notes - PR #393 (commit 71d2ffe) -- Sprint 17 release (0.9.7); completeness check applied, 5 missing entries added - PR #372 (commit 7172ae7) -- Sprint 16 release (0.9.6); completeness check applied