@bradygaster/squad-sdk 0.9.3-insider.1 → 0.9.4

package/templates/skills/versioning-policy/SKILL.md

@@ -0,0 +1,119 @@
+---
+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)"
+---
+
+## Context
+
+Squad is a monorepo with two publishable npm packages (`@bradygaster/squad-sdk` and `@bradygaster/squad-cli`) managed via npm workspaces. Version mismatches and prerelease leaks have caused production incidents — most notably PR #640, where a `-build.N` prerelease version silently broke workspace dependency resolution.
+
+This skill codifies the versioning rules every agent must follow.
+
+## 1. Version Format
+
+All packages use **strict semver**: `MAJOR.MINOR.PATCH`
+
+- ✅ `0.9.1`, `1.0.0`, `0.10.0`
+- ❌ `0.9.1-build.4`, `0.9.1-preview.1`, `0.8.6.1-preview`
+
+No prerelease suffixes on `dev` or `main` branches — ever.
+
+## 2. Prerelease Versions Are Ephemeral
+
+The `scripts/bump-build.mjs` script creates `-build.N` versions (e.g., `0.9.1-build.4`) for **local development testing only**.
+
+Rules:
+- `-build.N` versions are created automatically during local `npm run build`
+- They are **never committed** to `dev` or `main`
+- The script skips itself in CI (`CI=true` or `SKIP_BUILD_BUMP=1`)
+- If you see a `-build.N` version in a PR diff, it is a bug — reject the PR
+
+## 3. SDK and CLI Version Sync
+
+Both `@bradygaster/squad-sdk` and `@bradygaster/squad-cli` **MUST have the same version** at all times. The root `package.json` version must also match.
+
+`bump-build.mjs` enforces this by updating all three `package.json` files in lockstep (root + `packages/squad-sdk` + `packages/squad-cli`).
+
+If versions diverge, workspace resolution silently breaks (see §4).
+
+## 4. npm Workspace Semver Footgun
+
+The CLI depends on the SDK via a workspace dependency with a semver range:
+
+```json
+"@bradygaster/squad-sdk": ">=0.9.0"
+```
+
+**Critical:** Per the semver specification, `>=0.9.0` does **NOT** match `0.9.1-build.4`.
+
+Semver prerelease versions (anything with a `-` suffix) are only matched by ranges that explicitly reference the same `MAJOR.MINOR.PATCH` base with a prerelease comparator. A bare `>=0.9.0` range skips all prerelease versions.
+
+**What happens:** When the local SDK has version `0.9.1-build.4`, npm's workspace resolution fails to match the `>=0.9.0` range. npm then **silently installs a stale published version** from the npm registry instead of using the local workspace link. The build succeeds but runs against old SDK code.
+
+This is the root cause of the **PR #640 incident**, where workspace packages appeared linked but were actually running against stale registry versions.
+
+## 5. Who Bumps Versions
+
+**Surgeon (Release Manager) owns all version bumps.**
+
+| Agent | May modify `version` in package.json? |
+|-------|---------------------------------------|
+| Surgeon | ✅ Yes — sole owner of version bumps |
+| Any other agent | ❌ No — unless explicitly fixing a prerelease leak |
+
+If you discover a prerelease version committed to `dev` or `main`, you may fix it (revert to the clean release version) without Surgeon's approval. This is a safety escape hatch, not a license to manage versions.
+
+## 6. Version Bump Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Development phase                                      │
+│  Versions stay at current release: 0.9.1                │
+│  bump-build.mjs creates -build.N locally (not committed)│
+├─────────────────────────────────────────────────────────┤
+│  Pre-release testing                                    │
+│  bump-build.mjs → 0.9.1-build.1, -build.2, ...         │
+│  Local only. Never committed. Never pushed.             │
+├─────────────────────────────────────────────────────────┤
+│  Release                                                │
+│  Surgeon bumps to next version (e.g., 0.9.2 or 0.10.0) │
+│  Tags, publishes to npm registry                        │
+├─────────────────────────────────────────────────────────┤
+│  Post-release                                           │
+│  Versions stay at the new release version (e.g., 0.9.2) │
+│  Development continues on clean version                 │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 7. CI Enforcement
+
+The **`prerelease-version-guard`** CI gate blocks any PR to `dev` or `main` that contains prerelease version strings in `package.json` files.
+
+- The gate scans all three `package.json` files for `-` in the version field
+- PRs with prerelease versions **cannot merge** until the version is cleaned
+- The `skip-version-check` label bypasses the gate — use **only** for the bump-build script's own PR (if applicable), and only with Surgeon's approval
+
+## 8. Incident Reference — PR #640
+
+**PR #640** is the cautionary tale for this entire policy.
+
+**What happened:** Prerelease versions (`0.9.1-build.4`) were committed to a branch. The workspace dependency `>=0.9.0` failed to match the prerelease version per semver spec. npm silently installed a stale published SDK from the registry instead of linking the local workspace copy. Four PRs (#637–#640) attempted iterative patches before the root cause was identified.
+
+**Root cause:** No versioning policy existed. Agents didn't know that prerelease versions break workspace resolution, or that only Surgeon should modify versions.
+
+**Resolution:** This skill, the `prerelease-version-guard` CI gate, and the team decision to centralize version ownership under Surgeon.
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Format | `MAJOR.MINOR.PATCH` — no prerelease on dev/main |
+| Prerelease | `-build.N` is local-only, never committed |
+| Sync | SDK + CLI + root must have identical versions |
+| Ownership | Surgeon bumps versions; others don't touch them |
+| CI gate | `prerelease-version-guard` blocks prerelease PRs |
+| Escape hatch | Any agent may revert a prerelease leak to clean version |
+| Footgun | `>=0.9.0` does NOT match `0.9.1-build.4` per semver |

package/templates/squad.agent.md.template

@@ -19,6 +19,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
   - You may NOT generate domain artifacts (code, designs, analyses) — spawn an agent
   - You may NOT bypass reviewer approval on rejected work
   - You may NOT invent facts or assumptions — ask the user or spawn an agent who knows
+  - You may NOT do work yourself — ALWAYS delegate to a team member, even for small tasks. The only exception is Direct Mode (status checks, factual questions, and simple answers from context — see Response Mode Selection).
 
 Check: Does `.squad/team.md` exist? (fall back to `.ai-team/team.md` for repos migrating from older installs)
 - **No** → Init Mode
@@ -104,7 +105,7 @@ The `union` merge driver keeps all lines from both sides, which is correct for a
 
 **If you wrote code, generated artifacts, or produced domain work without dispatching to an agent, you violated this rule. The coordinator ROUTES — it does not BUILD. No exceptions.**
 
-**On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Pass the team root into every spawn prompt as `TEAM_ROOT` and the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
+**On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Pass the team root and the current datetime (from `<current_datetime>` in your system context) into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Pass the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
 
 **⚡ Context caching:** After the first message in a session, `team.md`, `routing.md`, and `registry.json` are already in your context. Do NOT re-read them on subsequent messages — you already have the roster, routing rules, and cast names. Only re-read if the user explicitly modifies the team (adds/removes members, changes routing).
 
@@ -330,6 +331,7 @@ description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   You are {Name}, the {Role} on this project.
   TEAM ROOT: {team_root}
+  CURRENT_DATETIME: {current_datetime}
   WORKTREE_PATH: {worktree_path}
   WORKTREE_MODE: {true|false}
   **Requested by:** {current user name}
@@ -348,7 +350,7 @@ prompt: |
   ⚠️ RESPONSE ORDER: After ALL tool calls, write a plain text summary as FINAL output.
 ```
 
-For read-only queries, use the explore agent: `agent_type: "explore"` with `"You are {Name}, the {Role}. {question} TEAM ROOT: {team_root}"`
+For read-only queries, use the explore agent: `agent_type: "explore"` with `"You are {Name}, the {Role}. CURRENT_DATETIME: {current_datetime} — {question} TEAM ROOT: {team_root}"`
 
 ### Per-Agent Model Selection
 
@@ -499,7 +501,7 @@ The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitH
 
 MCP (Model Context Protocol) servers extend Squad with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Squad discovers and uses them.
 
-> **Full patterns:** Read `.squad/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, graceful degradation. Read `.squad/templates/mcp-config.md` for config file locations, sample configs, and authentication notes.
+> **Config details:** Read `.squad/templates/mcp-config.md` for config file locations, sample configs, and authentication notes.
 
 #### Detection
 
@@ -623,15 +625,17 @@ Squad and all spawned agents may be running inside a **git worktree** rather tha
 
 **How the Coordinator resolves the team root (on every session start):**
 
-1. Run `git rev-parse --show-toplevel` to get the current worktree root.
-2. Check if `.squad/` exists at that root (fall back to `.ai-team/` for repos that haven't migrated yet).
+1. **Check CWD first** — does `.squad/` exist in the current working directory?
+   - **Yes** → Team root = CWD. This handles monorepos where `.squad/` lives in a subfolder.
+2. If not, run `git rev-parse --show-toplevel` to get the current worktree root.
+3. Check if `.squad/` exists at that root (fall back to `.ai-team/` for repos that haven't migrated yet).
    - **Yes** → use **worktree-local** strategy. Team root = current worktree root.
    - **No** → use **main-checkout** strategy. Discover the main working tree:
      ```
      git worktree list --porcelain
      ```
      The first `worktree` line is the main working tree. Team root = that path.
-3. The user may override the strategy at any time (e.g., *"use main checkout for team state"* or *"keep team state in this worktree"*).
+4. The user may override the strategy at any time (e.g., *"use main checkout for team state"* or *"keep team state in this worktree"*).
 
 **Passing the team root to agents:**
 - The Coordinator includes `TEAM_ROOT: {resolved_path}` in every spawn prompt.
@@ -769,6 +773,7 @@ prompt: |
   {paste contents of .squad/agents/{name}/charter.md here}
   
   TEAM ROOT: {team_root}
+  CURRENT_DATETIME: {current_datetime}
   All `.squad/` paths are relative to this root.
   
   PERSONAL_AGENT: {true|false}  # Whether this is a personal agent
@@ -815,6 +820,7 @@ prompt: |
   Do the work. Respond as {Name}.
   
   ⚠️ OUTPUT: Report outcomes in human terms. Never expose tool internals or SQL.
+  ⚠️ DATES: When writing dates in any file (decisions, history, logs), use ONLY the CURRENT_DATETIME value above. Never infer or guess the date.
   
   AFTER work:
   1. APPEND to .squad/agents/{name}/history.md under "## Learnings":
@@ -871,6 +877,7 @@ description: "📋 Scribe: Log session & merge decisions"
 prompt: |
   You are the Scribe. Read .squad/agents/scribe/charter.md.
   TEAM ROOT: {team_root}
+  CURRENT_DATETIME: {current_datetime}
 
   SPAWN MANIFEST: {spawn_manifest}
 

package/templates/workflows/squad-heartbeat.yml

@@ -1,167 +1,167 @@
-name: Squad Heartbeat (Ralph)
-# ⚠️ SYNC: This workflow is maintained in 4 locations. Changes must be applied to all:
-#   - templates/workflows/squad-heartbeat.yml (source template)
-#   - packages/squad-cli/templates/workflows/squad-heartbeat.yml (CLI package)
-#   - .squad/templates/workflows/squad-heartbeat.yml (installed template)
-#   - .github/workflows/squad-heartbeat.yml (active workflow)
-# Run 'squad upgrade' to sync installed copies from source templates.
-
-on:
-  # React to completed work or new squad work
-  issues:
-    types: [closed, labeled]
-  pull_request:
-    types: [closed]
-
-  # Manual trigger
-  workflow_dispatch:
-
-permissions:
-  issues: write
-  contents: read
-  pull-requests: read
-
-jobs:
-  heartbeat:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Check triage script
-        id: check-script
-        run: |
-          if [ -f ".squad/templates/ralph-triage.js" ]; then
-            echo "has_script=true" >> $GITHUB_OUTPUT
-          else
-            echo "has_script=false" >> $GITHUB_OUTPUT
-            echo "⚠️ ralph-triage.js not found — run 'squad upgrade' to install"
-          fi
-
-      - name: Ralph — Smart triage
-        if: steps.check-script.outputs.has_script == 'true'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          node .squad/templates/ralph-triage.js \
-            --squad-dir .squad \
-            --output triage-results.json
-
-      - name: Ralph — Apply triage decisions
-        if: steps.check-script.outputs.has_script == 'true' && hashFiles('triage-results.json') != ''
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const fs = require('fs');
-            const path = 'triage-results.json';
-            if (!fs.existsSync(path)) {
-              core.info('No triage results — board is clear');
-              return;
-            }
-            
-            const results = JSON.parse(fs.readFileSync(path, 'utf8'));
-            if (results.length === 0) {
-              core.info('📋 Board is clear — Ralph found no untriaged issues');
-              return;
-            }
-            
-            for (const decision of results) {
-              try {
-                await github.rest.issues.addLabels({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: decision.issueNumber,
-                  labels: [decision.label]
-                });
-                
-                await github.rest.issues.createComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: decision.issueNumber,
-                  body: [
-                    '### 🔄 Ralph — Auto-Triage',
-                    '',
-                    `**Assigned to:** ${decision.assignTo}`,
-                    `**Reason:** ${decision.reason}`,
-                    `**Source:** ${decision.source}`,
-                    '',
-                    '> Ralph auto-triaged this issue using routing rules.',
-                    '> To reassign, swap the `squad:*` label.'
-                  ].join('\n')
-                });
-                
-                core.info(`Triaged #${decision.issueNumber} → ${decision.assignTo} (${decision.source})`);
-              } catch (e) {
-                core.warning(`Failed to triage #${decision.issueNumber}: ${e.message}`);
-              }
-            }
-            
-            core.info(`🔄 Ralph triaged ${results.length} issue(s)`);
-
-      # Copilot auto-assign step (uses PAT if available)
-      - name: Ralph — Assign @copilot issues
-        if: success()
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.COPILOT_ASSIGN_TOKEN || secrets.GITHUB_TOKEN }}
-          script: |
-            const fs = require('fs');
-
-            let teamFile = '.squad/team.md';
-            if (!fs.existsSync(teamFile)) {
-              teamFile = '.ai-team/team.md';
-            }
-            if (!fs.existsSync(teamFile)) return;
-
-            const content = fs.readFileSync(teamFile, 'utf8');
-
-            // Check if @copilot is on the team with auto-assign
-            const hasCopilot = content.includes('🤖 Coding Agent') || content.includes('@copilot');
-            const autoAssign = content.includes('<!-- copilot-auto-assign: true -->');
-            if (!hasCopilot || !autoAssign) return;
-
-            // Find issues labeled squad:copilot with no assignee
-            try {
-              const { data: copilotIssues } = await github.rest.issues.listForRepo({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                labels: 'squad:copilot',
-                state: 'open',
-                per_page: 5
-              });
-
-              const unassigned = copilotIssues.filter(i =>
-                !i.assignees || i.assignees.length === 0
-              );
-
-              if (unassigned.length === 0) {
-                core.info('No unassigned squad:copilot issues');
-                return;
-              }
-
-              // Get repo default branch
-              const { data: repoData } = await github.rest.repos.get({
-                owner: context.repo.owner,
-                repo: context.repo.repo
-              });
-
-              for (const issue of unassigned) {
-                try {
-                  await github.request('POST /repos/{owner}/{repo}/issues/{issue_number}/assignees', {
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    issue_number: issue.number,
-                    assignees: ['copilot-swe-agent[bot]'],
-                    agent_assignment: {
-                      target_repo: `${context.repo.owner}/${context.repo.repo}`,
-                      base_branch: repoData.default_branch,
-                      custom_instructions: `Read .squad/team.md (or .ai-team/team.md) for team context and .squad/routing.md (or .ai-team/routing.md) for routing rules.`
-                    }
-                  });
-                  core.info(`Assigned copilot-swe-agent[bot] to #${issue.number}`);
-                } catch (e) {
-                  core.warning(`Failed to assign @copilot to #${issue.number}: ${e.message}`);
-                }
-              }
-            } catch (e) {
-              core.info(`No squad:copilot label found or error: ${e.message}`);
-            }
+name: Squad Heartbeat (Ralph)
+# ⚠️ SYNC: This workflow is maintained in 4 locations. Changes must be applied to all:
+#   - templates/workflows/squad-heartbeat.yml (source template)
+#   - packages/squad-cli/templates/workflows/squad-heartbeat.yml (CLI package)
+#   - .squad/templates/workflows/squad-heartbeat.yml (installed template)
+#   - .github/workflows/squad-heartbeat.yml (active workflow)
+# Run 'squad upgrade' to sync installed copies from source templates.
+
+on:
+  # React to completed work or new squad work
+  issues:
+    types: [closed, labeled]
+  pull_request:
+    types: [closed]
+
+  # Manual trigger
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  contents: read
+  pull-requests: read
+
+jobs:
+  heartbeat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check triage script
+        id: check-script
+        run: |
+          if [ -f ".squad/templates/ralph-triage.js" ]; then
+            echo "has_script=true" >> $GITHUB_OUTPUT
+          else
+            echo "has_script=false" >> $GITHUB_OUTPUT
+            echo "⚠️ ralph-triage.js not found — run 'squad upgrade' to install"
+          fi
+
+      - name: Ralph — Smart triage
+        if: steps.check-script.outputs.has_script == 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          node .squad/templates/ralph-triage.js \
+            --squad-dir .squad \
+            --output triage-results.json
+
+      - name: Ralph — Apply triage decisions
+        if: steps.check-script.outputs.has_script == 'true' && hashFiles('triage-results.json') != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = 'triage-results.json';
+            if (!fs.existsSync(path)) {
+              core.info('No triage results — board is clear');
+              return;
+            }
+            
+            const results = JSON.parse(fs.readFileSync(path, 'utf8'));
+            if (results.length === 0) {
+              core.info('📋 Board is clear — Ralph found no untriaged issues');
+              return;
+            }
+            
+            for (const decision of results) {
+              try {
+                await github.rest.issues.addLabels({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: decision.issueNumber,
+                  labels: [decision.label]
+                });
+                
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: decision.issueNumber,
+                  body: [
+                    '### 🔄 Ralph — Auto-Triage',
+                    '',
+                    `**Assigned to:** ${decision.assignTo}`,
+                    `**Reason:** ${decision.reason}`,
+                    `**Source:** ${decision.source}`,
+                    '',
+                    '> Ralph auto-triaged this issue using routing rules.',
+                    '> To reassign, swap the `squad:*` label.'
+                  ].join('\n')
+                });
+                
+                core.info(`Triaged #${decision.issueNumber} → ${decision.assignTo} (${decision.source})`);
+              } catch (e) {
+                core.warning(`Failed to triage #${decision.issueNumber}: ${e.message}`);
+              }
+            }
+            
+            core.info(`🔄 Ralph triaged ${results.length} issue(s)`);
+
+      # Copilot auto-assign step (uses PAT if available)
+      - name: Ralph — Assign @copilot issues
+        if: success()
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.COPILOT_ASSIGN_TOKEN || secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+
+            let teamFile = '.squad/team.md';
+            if (!fs.existsSync(teamFile)) {
+              teamFile = '.ai-team/team.md';
+            }
+            if (!fs.existsSync(teamFile)) return;
+
+            const content = fs.readFileSync(teamFile, 'utf8');
+
+            // Check if @copilot is on the team with auto-assign
+            const hasCopilot = content.includes('🤖 Coding Agent') || content.includes('@copilot');
+            const autoAssign = content.includes('<!-- copilot-auto-assign: true -->');
+            if (!hasCopilot || !autoAssign) return;
+
+            // Find issues labeled squad:copilot with no assignee
+            try {
+              const { data: copilotIssues } = await github.rest.issues.listForRepo({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                labels: 'squad:copilot',
+                state: 'open',
+                per_page: 5
+              });
+
+              const unassigned = copilotIssues.filter(i =>
+                !i.assignees || i.assignees.length === 0
+              );
+
+              if (unassigned.length === 0) {
+                core.info('No unassigned squad:copilot issues');
+                return;
+              }
+
+              // Get repo default branch
+              const { data: repoData } = await github.rest.repos.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo
+              });
+
+              for (const issue of unassigned) {
+                try {
+                  await github.request('POST /repos/{owner}/{repo}/issues/{issue_number}/assignees', {
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: issue.number,
+                    assignees: ['copilot-swe-agent[bot]'],
+                    agent_assignment: {
+                      target_repo: `${context.repo.owner}/${context.repo.repo}`,
+                      base_branch: repoData.default_branch,
+                      custom_instructions: `Read .squad/team.md (or .ai-team/team.md) for team context and .squad/routing.md (or .ai-team/routing.md) for routing rules.`
+                    }
+                  });
+                  core.info(`Assigned copilot-swe-agent[bot] to #${issue.number}`);
+                } catch (e) {
+                  core.warning(`Failed to assign @copilot to #${issue.number}: ${e.message}`);
+                }
+              }
+            } catch (e) {
+              core.info(`No squad:copilot label found or error: ${e.message}`);
+            }