@bradygaster/squad-sdk 0.8.17 → 0.8.18

package/templates/workflows/squad-ci.yml

@@ -0,0 +1,24 @@
+name: Squad CI
+
+on:
+  pull_request:
+    branches: [dev, preview, main, insider]
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [dev, insider]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run tests
+        run: node --test test/*.test.js

package/templates/workflows/squad-docs.yml

@@ -0,0 +1,50 @@
+name: Squad Docs — Build & Deploy
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [preview]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/squad-docs.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install build dependencies
+        run: npm install --no-save markdown-it markdown-it-anchor
+
+      - name: Build docs site
+        run: node docs/build.js --out _site --base /squad
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/templates/workflows/squad-heartbeat.yml

@@ -0,0 +1,316 @@
+name: Squad Heartbeat (Ralph)
+
+on:
+  # DISABLED: Cron heartbeat commented out pre-migration — re-enable when ready
+  # schedule:
+  #   # Every 30 minutes — adjust or remove if not needed
+  #   - cron: '*/30 * * * *'
+
+  # 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: Ralph — Check for squad work
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            // Read team roster — check .squad/ first, fall back to .ai-team/
+            let teamFile = '.squad/team.md';
+            if (!fs.existsSync(teamFile)) {
+              teamFile = '.ai-team/team.md';
+            }
+            if (!fs.existsSync(teamFile)) {
+              core.info('No .squad/team.md or .ai-team/team.md found — Ralph has nothing to monitor');
+              return;
+            }
+
+            const content = fs.readFileSync(teamFile, 'utf8');
+
+            // Check if Ralph is on the roster
+            if (!content.includes('Ralph') || !content.includes('🔄')) {
+              core.info('Ralph not on roster — heartbeat disabled');
+              return;
+            }
+
+            // Parse members from roster
+            const lines = content.split('\n');
+            const members = [];
+            let inMembersTable = false;
+            for (const line of lines) {
+              if (line.match(/^##\s+(Members|Team Roster)/i)) {
+                inMembersTable = true;
+                continue;
+              }
+              if (inMembersTable && line.startsWith('## ')) break;
+              if (inMembersTable && line.startsWith('|') && !line.includes('---') && !line.includes('Name')) {
+                const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+                if (cells.length >= 2 && !['Scribe', 'Ralph'].includes(cells[0])) {
+                  members.push({
+                    name: cells[0],
+                    role: cells[1],
+                    label: `squad:${cells[0].toLowerCase()}`
+                  });
+                }
+              }
+            }
+
+            if (members.length === 0) {
+              core.info('No squad members found — nothing to monitor');
+              return;
+            }
+
+            // 1. Find untriaged issues (labeled "squad" but no "squad:{member}" label)
+            const { data: squadIssues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: 'squad',
+              state: 'open',
+              per_page: 20
+            });
+
+            const memberLabels = members.map(m => m.label);
+            const untriaged = squadIssues.filter(issue => {
+              const issueLabels = issue.labels.map(l => l.name);
+              return !memberLabels.some(ml => issueLabels.includes(ml));
+            });
+
+            // 2. Find assigned but unstarted issues (has squad:{member} label, no assignee)
+            const unstarted = [];
+            for (const member of members) {
+              try {
+                const { data: memberIssues } = await github.rest.issues.listForRepo({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  labels: member.label,
+                  state: 'open',
+                  per_page: 10
+                });
+                for (const issue of memberIssues) {
+                  if (!issue.assignees || issue.assignees.length === 0) {
+                    unstarted.push({ issue, member });
+                  }
+                }
+              } catch (e) {
+                // Label may not exist yet
+              }
+            }
+
+            // 3. Find squad issues missing triage verdict (no go:* label)
+            const missingVerdict = squadIssues.filter(issue => {
+              const labels = issue.labels.map(l => l.name);
+              return !labels.some(l => l.startsWith('go:'));
+            });
+
+            // 4. Find go:yes issues missing release target
+            const goYesIssues = squadIssues.filter(issue => {
+              const labels = issue.labels.map(l => l.name);
+              return labels.includes('go:yes') && !labels.some(l => l.startsWith('release:'));
+            });
+
+            // 4b. Find issues missing type: label
+            const missingType = squadIssues.filter(issue => {
+              const labels = issue.labels.map(l => l.name);
+              return !labels.some(l => l.startsWith('type:'));
+            });
+
+            // 5. Find open PRs that need attention
+            const { data: openPRs } = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              per_page: 20
+            });
+
+            const squadPRs = openPRs.filter(pr =>
+              pr.labels.some(l => l.name.startsWith('squad'))
+            );
+
+            // Build status summary
+            const summary = [];
+            if (untriaged.length > 0) {
+              summary.push(`🔴 **${untriaged.length} untriaged issue(s)** need triage`);
+            }
+            if (unstarted.length > 0) {
+              summary.push(`🟡 **${unstarted.length} assigned issue(s)** have no assignee`);
+            }
+            if (missingVerdict.length > 0) {
+              summary.push(`⚪ **${missingVerdict.length} issue(s)** missing triage verdict (no \`go:\` label)`);
+            }
+            if (goYesIssues.length > 0) {
+              summary.push(`⚪ **${goYesIssues.length} approved issue(s)** missing release target (no \`release:\` label)`);
+            }
+            if (missingType.length > 0) {
+              summary.push(`⚪ **${missingType.length} issue(s)** missing \`type:\` label`);
+            }
+            if (squadPRs.length > 0) {
+              const drafts = squadPRs.filter(pr => pr.draft).length;
+              const ready = squadPRs.length - drafts;
+              if (drafts > 0) summary.push(`🟡 **${drafts} draft PR(s)** in progress`);
+              if (ready > 0) summary.push(`🟢 **${ready} PR(s)** open for review/merge`);
+            }
+
+            if (summary.length === 0) {
+              core.info('📋 Board is clear — Ralph found no pending work');
+              return;
+            }
+
+            core.info(`🔄 Ralph found work:\n${summary.join('\n')}`);
+
+            // Auto-triage untriaged issues
+            for (const issue of untriaged) {
+              const issueText = `${issue.title}\n${issue.body || ''}`.toLowerCase();
+              let assignedMember = null;
+              let reason = '';
+
+              // Simple keyword-based routing
+              for (const member of members) {
+                const role = member.role.toLowerCase();
+                if ((role.includes('frontend') || role.includes('ui')) &&
+                    (issueText.includes('ui') || issueText.includes('frontend') ||
+                     issueText.includes('css') || issueText.includes('component'))) {
+                  assignedMember = member;
+                  reason = 'Matches frontend/UI domain';
+                  break;
+                }
+                if ((role.includes('backend') || role.includes('api') || role.includes('server')) &&
+                    (issueText.includes('api') || issueText.includes('backend') ||
+                     issueText.includes('database') || issueText.includes('endpoint'))) {
+                  assignedMember = member;
+                  reason = 'Matches backend/API domain';
+                  break;
+                }
+                if ((role.includes('test') || role.includes('qa')) &&
+                    (issueText.includes('test') || issueText.includes('bug') ||
+                     issueText.includes('fix') || issueText.includes('regression'))) {
+                  assignedMember = member;
+                  reason = 'Matches testing/QA domain';
+                  break;
+                }
+              }
+
+              // Default to Lead
+              if (!assignedMember) {
+                const lead = members.find(m =>
+                  m.role.toLowerCase().includes('lead') ||
+                  m.role.toLowerCase().includes('architect')
+                );
+                if (lead) {
+                  assignedMember = lead;
+                  reason = 'No domain match — routed to Lead';
+                }
+              }
+
+              if (assignedMember) {
+                // Add member label
+                await github.rest.issues.addLabels({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issue.number,
+                  labels: [assignedMember.label]
+                });
+
+                // Post triage comment
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issue.number,
+                  body: [
+                    `### 🔄 Ralph — Auto-Triage`,
+                    '',
+                    `**Assigned to:** ${assignedMember.name} (${assignedMember.role})`,
+                    `**Reason:** ${reason}`,
+                    '',
+                    `> Ralph auto-triaged this issue via the squad heartbeat. To reassign, swap the \`squad:*\` label.`
+                  ].join('\n')
+                });
+
+                core.info(`Auto-triaged #${issue.number} → ${assignedMember.name}`);
+              }
+            }
+
+      # 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}`);
+            }

package/templates/workflows/squad-insider-release.yml

@@ -0,0 +1,61 @@
+name: Squad Insider Release
+
+on:
+  push:
+    branches: [insider]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run tests
+        run: node --test test/*.test.js
+
+      - name: Read version from package.json
+        id: version
+        run: |
+          VERSION=$(node -e "console.log(require('./package.json').version)")
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          INSIDER_VERSION="${VERSION}-insider+${SHORT_SHA}"
+          INSIDER_TAG="v${INSIDER_VERSION}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "short_sha=$SHORT_SHA" >> "$GITHUB_OUTPUT"
+          echo "insider_version=$INSIDER_VERSION" >> "$GITHUB_OUTPUT"
+          echo "insider_tag=$INSIDER_TAG" >> "$GITHUB_OUTPUT"
+          echo "📦 Base Version: $VERSION (Short SHA: $SHORT_SHA)"
+          echo "🏷️ Insider Version: $INSIDER_VERSION"
+          echo "🔖 Insider Tag: $INSIDER_TAG"
+
+      - name: Create git tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ steps.version.outputs.insider_tag }}" -m "Insider Release ${{ steps.version.outputs.insider_tag }}"
+          git push origin "${{ steps.version.outputs.insider_tag }}"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ steps.version.outputs.insider_tag }}" \
+            --title "${{ steps.version.outputs.insider_tag }}" \
+            --notes "This is an insider/development build of Squad. Install with:\`\`\`bash\nnpx github:bradygaster/squad#${{ steps.version.outputs.insider_tag }}\n\`\`\`\n\n**Note:** Insider builds may be unstable and are intended for early adopters and testing only." \
+            --prerelease
+
+      - name: Verify release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release view "${{ steps.version.outputs.insider_tag }}"
+          echo "✅ Insider Release ${{ steps.version.outputs.insider_tag }} created and verified."

package/templates/workflows/squad-issue-assign.yml

@@ -0,0 +1,161 @@
+name: Squad Issue Assign
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  assign-work:
+    # Only trigger on squad:{member} labels (not the base "squad" label)
+    if: startsWith(github.event.label.name, 'squad:')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Identify assigned member and trigger work
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const issue = context.payload.issue;
+            const label = context.payload.label.name;
+
+            // Extract member name from label (e.g., "squad:ripley" → "ripley")
+            const memberName = label.replace('squad:', '').toLowerCase();
+
+            // Read team roster — check .squad/ first, fall back to .ai-team/
+            let teamFile = '.squad/team.md';
+            if (!fs.existsSync(teamFile)) {
+              teamFile = '.ai-team/team.md';
+            }
+            if (!fs.existsSync(teamFile)) {
+              core.warning('No .squad/team.md or .ai-team/team.md found — cannot assign work');
+              return;
+            }
+
+            const content = fs.readFileSync(teamFile, 'utf8');
+            const lines = content.split('\n');
+
+            // Check if this is a coding agent assignment
+            const isCopilotAssignment = memberName === 'copilot';
+
+            let assignedMember = null;
+            if (isCopilotAssignment) {
+              assignedMember = { name: '@copilot', role: 'Coding Agent' };
+            } else {
+              let inMembersTable = false;
+              for (const line of lines) {
+                if (line.match(/^##\s+(Members|Team Roster)/i)) {
+                  inMembersTable = true;
+                  continue;
+                }
+                if (inMembersTable && line.startsWith('## ')) {
+                  break;
+                }
+                if (inMembersTable && line.startsWith('|') && !line.includes('---') && !line.includes('Name')) {
+                  const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+                  if (cells.length >= 2 && cells[0].toLowerCase() === memberName) {
+                    assignedMember = { name: cells[0], role: cells[1] };
+                    break;
+                  }
+                }
+              }
+            }
+
+            if (!assignedMember) {
+              core.warning(`No member found matching label "${label}"`);
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                body: `⚠️ No squad member found matching label \`${label}\`. Check \`.squad/team.md\` (or \`.ai-team/team.md\`) for valid member names.`
+              });
+              return;
+            }
+
+            // Post assignment acknowledgment
+            let comment;
+            if (isCopilotAssignment) {
+              comment = [
+                `### 🤖 Routed to @copilot (Coding Agent)`,
+                '',
+                `**Issue:** #${issue.number} — ${issue.title}`,
+                '',
+                `@copilot has been assigned and will pick this up automatically.`,
+                '',
+                `> The coding agent will create a \`copilot/*\` branch and open a draft PR.`,
+                `> Review the PR as you would any team member's work.`,
+              ].join('\n');
+            } else {
+              comment = [
+                `### 📋 Assigned to ${assignedMember.name} (${assignedMember.role})`,
+                '',
+                `**Issue:** #${issue.number} — ${issue.title}`,
+                '',
+                `${assignedMember.name} will pick this up in the next Copilot session.`,
+                '',
+                `> **For Copilot coding agent:** If enabled, this issue will be worked automatically.`,
+                `> Otherwise, start a Copilot session and say:`,
+                `> \`${assignedMember.name}, work on issue #${issue.number}\``,
+              ].join('\n');
+            }
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issue.number,
+              body: comment
+            });
+
+            core.info(`Issue #${issue.number} assigned to ${assignedMember.name} (${assignedMember.role})`);
+
+      # Separate step: assign @copilot using PAT (required for coding agent)
+      - name: Assign @copilot coding agent
+        if: github.event.label.name == 'squad:copilot'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.COPILOT_ASSIGN_TOKEN }}
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const issue_number = context.payload.issue.number;
+
+            // Get the default branch name (main, master, etc.)
+            const { data: repoData } = await github.rest.repos.get({ owner, repo });
+            const baseBranch = repoData.default_branch;
+
+            try {
+              await github.request('POST /repos/{owner}/{repo}/issues/{issue_number}/assignees', {
+                owner,
+                repo,
+                issue_number,
+                assignees: ['copilot-swe-agent[bot]'],
+                agent_assignment: {
+                  target_repo: `${owner}/${repo}`,
+                  base_branch: baseBranch,
+                  custom_instructions: '',
+                  custom_agent: '',
+                  model: ''
+                },
+                headers: {
+                  'X-GitHub-Api-Version': '2022-11-28'
+                }
+              });
+              core.info(`Assigned copilot-swe-agent to issue #${issue_number} (base: ${baseBranch})`);
+            } catch (err) {
+              core.warning(`Assignment with agent_assignment failed: ${err.message}`);
+              // Fallback: try without agent_assignment
+              try {
+                await github.rest.issues.addAssignees({
+                  owner, repo, issue_number,
+                  assignees: ['copilot-swe-agent']
+                });
+                core.info(`Fallback assigned copilot-swe-agent to issue #${issue_number}`);
+              } catch (err2) {
+                core.warning(`Fallback also failed: ${err2.message}`);
+              }
+            }