From 8a16abef4d35f7e1bb15911e461095c9a3b75804 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 13:18:36 -0700 Subject: [PATCH 01/12] chore: decouple squad automation from cast names Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/PR_REQUIREMENTS.md | 26 ++-- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/dependabot.yml | 14 +-- .../squad-routing-guard.instructions.md | 41 ++++--- .github/workflows/squad-triage.yml | 111 ++++++++++++------ .../skills/e2e-template-testing/SKILL.md | 2 +- .squad-templates/spawn-reference.md | 2 +- .squad-templates/workflows/squad-triage.yml | 111 ++++++++++++------ .../templates/skills/agent-conduct/SKILL.md | 2 +- .../templates/skills/docs-standards/SKILL.md | 2 +- .../skills/e2e-template-testing/SKILL.md | 2 +- .../templates/skills/external-comms/SKILL.md | 34 +++--- .../templates/skills/humanizer/SKILL.md | 8 +- .../skills/retro-enforcement/SKILL.md | 6 +- .../skills/versioning-policy/SKILL.md | 4 +- .../squad-cli/templates/spawn-reference.md | 2 +- .../templates/workflows/squad-triage.yml | 111 ++++++++++++------ .../templates/skills/agent-conduct/SKILL.md | 2 +- .../templates/skills/docs-standards/SKILL.md | 2 +- .../skills/e2e-template-testing/SKILL.md | 2 +- .../templates/skills/external-comms/SKILL.md | 34 +++--- .../templates/skills/humanizer/SKILL.md | 8 +- .../skills/retro-enforcement/SKILL.md | 4 +- .../skills/versioning-policy/SKILL.md | 4 +- .../squad-sdk/templates/spawn-reference.md | 2 +- .../templates/workflows/squad-triage.yml | 111 ++++++++++++------ .../skills/e2e-template-testing/SKILL.md | 2 +- templates/spawn-reference.md | 2 +- templates/workflows/squad-triage.yml | 111 ++++++++++++------ test/recast-identity-neutrality.test.ts | 76 ++++++++++++ 30 files changed, 557 insertions(+), 283 deletions(-) create mode 100644 test/recast-identity-neutrality.test.ts diff --git a/.github/PR_REQUIREMENTS.md b/.github/PR_REQUIREMENTS.md index 966211a94..28dd134e7 100644 --- a/.github/PR_REQUIREMENTS.md +++ b/.github/PR_REQUIREMENTS.md @@ -90,7 +90,8 @@ Requirements are ordered by review flow. All marked **REQUIRED** must be satisfi - [ ] `docs/src/navigation.ts` updated if a new docs page is added - [ ] Docs build test updated if a new feature page is added (`test/docs-build.test.ts`, run via `npm test`) -**Enforced by**: Manual PR review (FIDO, Flight) + future automated checks in #104 +**Enforced by**: Manual review by the current Quality and Lead role owners + +future automated checks in #104 ### e) Package / Exports (REQUIRED for new modules — manual review) @@ -149,25 +150,27 @@ Add to PR description under a `## Waivers` section: - Item waived: (d) Documentation CHANGELOG entry - Reason: Security fix needs urgent release (CVE-2024-XXXXX) -- Approval by: [Flight/FIDO to be stated in PR review comment] +- Approval by: [current Lead/Quality role owner, stated in a PR review comment] ``` ### Waiver Approval Authority -- **Flight (architecture decisions)**: Internal refactors, infrastructure, module reorganization -- **FIDO (quality decisions)**: Bug fixes, test improvements, samples, CI changes +- **Lead role owner (architecture decisions)**: Internal refactors, + infrastructure, module reorganization +- **Quality role owner (quality decisions)**: Bug fixes, test improvements, + samples, CI changes - **Both**: External API changes, breaking changes ### Waiver Approval Examples | Scenario | Waivable Items | Approver | |----------|----------------|----------| -| Internal refactor (no API change) | Documentation, Samples | Flight | -| Security fix | Documentation, Samples (with follow-up issue) | FIDO | -| Test infrastructure change | Documentation, Exports, Samples | FIDO | -| CI/GitHub Actions update | Documentation, Exports, Samples | FIDO | -| Documentation-only change | Code Quality (tests), Exports, Samples | FIDO | -| Non-breaking SDK bugfix | Samples | FIDO | +| Internal refactor (no API change) | Documentation, Samples | Lead role owner | +| Security fix | Documentation, Samples (with follow-up issue) | Quality role owner | +| Test infrastructure change | Documentation, Exports, Samples | Quality role owner | +| CI/GitHub Actions update | Documentation, Exports, Samples | Quality role owner | +| Documentation-only change | Code Quality (tests), Exports, Samples | Quality role owner | +| Non-breaking SDK bugfix | Samples | Quality role owner | ### Self-Waiving Is Not Allowed @@ -214,7 +217,8 @@ For migration PRs (> 20 files): include test output summary in the PR descriptio **Automation dependency**: 9 of 18 requirements are manual-only. Issue #104 (PR completeness gates) is the critical path to automated enforcement. Until #104 ships, this spec depends on reviewer discipline. -**Mitigation**: Phase 4 (Flight/FIDO checklist) codifies consistent judgment. Regular enforcement audits catch drift. +**Mitigation**: The Lead/Quality review checklist codifies consistent judgment. +Regular enforcement audits catch drift. ### 2. Theater Risk diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cebbf6ba2..9a7e56aff 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -51,4 +51,4 @@ ### Waivers - + diff --git a/.github/dependabot.yml b/.github/dependabot.yml index dea6876fb..af826700f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -8,7 +8,7 @@ updates: time: "08:00" timezone: "Etc/UTC" open-pull-requests-limit: 5 - labels: ["dependencies", "squad:belanna"] + labels: ["dependencies"] commit-message: prefix: "deps" groups: @@ -37,7 +37,7 @@ updates: time: "08:00" timezone: "Etc/UTC" open-pull-requests-limit: 5 - labels: ["dependencies", "squad:belanna"] + labels: ["dependencies"] commit-message: prefix: "deps" groups: @@ -67,7 +67,7 @@ updates: time: "08:00" timezone: "Etc/UTC" open-pull-requests-limit: 5 - labels: ["dependencies", "squad:belanna"] + labels: ["dependencies"] commit-message: prefix: "deps" groups: @@ -85,7 +85,7 @@ updates: time: "08:00" timezone: "Etc/UTC" open-pull-requests-limit: 5 - labels: ["dependencies", "squad:belanna"] + labels: ["dependencies"] commit-message: prefix: "deps" groups: @@ -103,7 +103,7 @@ updates: time: "08:00" timezone: "Etc/UTC" open-pull-requests-limit: 5 - labels: ["dependencies", "squad:belanna"] + labels: ["dependencies"] commit-message: prefix: "deps" groups: @@ -121,7 +121,7 @@ updates: time: "08:00" timezone: "Etc/UTC" open-pull-requests-limit: 5 - labels: ["dependencies", "squad:belanna"] + labels: ["dependencies"] commit-message: prefix: "deps" groups: @@ -145,7 +145,7 @@ updates: time: "08:00" timezone: "Etc/UTC" open-pull-requests-limit: 5 - labels: ["dependencies", "squad:belanna"] + labels: ["dependencies"] commit-message: prefix: "ci" groups: diff --git a/.github/instructions/squad-routing-guard.instructions.md b/.github/instructions/squad-routing-guard.instructions.md index cd11b2372..10d1f82ed 100644 --- a/.github/instructions/squad-routing-guard.instructions.md +++ b/.github/instructions/squad-routing-guard.instructions.md @@ -39,33 +39,31 @@ Does the work type match a specialist domain? (See §3 + .squad/routing.md) ## Step 3 — Routing Table -Read `.squad/routing.md` for the project-specific routing table. For generic Squad questions: - -| Work type | Route to | Examples | -|-----------|----------|---------| -| Core runtime, adapter, spawn orchestration | **EECOM** | CopilotClient, session pool, tools module | -| Prompt architecture, coordinator logic | **Procedures** | Agent charters, spawn templates, response tier selection | -| Type system, TypeScript strictness | **CONTROL** | Discriminated unions, generics, tsconfig | -| SDK integration | **CAPCOM** | @github/copilot-sdk usage, CopilotSession lifecycle | -| Tests & quality, CI/CD | **FIDO** | Test coverage, Vitest, edge cases, CI/CD gates | -| Docs, README, API docs | **PAO** | README, getting-started, demos, contributor recognition | -| Architecture, product direction, review | **Flight** | Architectural decisions, code review, scope/trade-offs | -| Session logging, decision merge, DispatchGuard audit | **Scribe** | Auto — never needs explicit routing | -| Work queue, backlog, DispatchGuard verdict alerts | **Ralph** | GitHub issues, PR state, idle-watch, violations | - -**Full project routing table:** `.squad/routing.md` +Read `.squad/routing.md` and use its current `Work Type` and `Route To`/`Agent` +columns. That file is the only authoritative work-to-agent mapping. Do not cache +agent names in this instruction file or infer ownership from a previous cast. + +Before routing: + +1. Confirm the destination appears in the active `## Members` table in + `.squad/team.md`. +2. Use the member name exactly as written there when constructing a + `squad:{slug}` label or spawning the agent. +3. If no routing row matches, use the active Lead identified by role in + `team.md`. If no Lead exists, handle the task as generic work rather than + inventing an owner. ### Examples — what NOT to grab ``` ❌ "Fix the TypeScript compilation error in src/adapter/" - → Core runtime → Route to EECOM + → Look up the current runtime owner in routing.md ❌ "Add tests for the casting module" - → Tests & quality → Route to FIDO + → Look up the current quality owner in routing.md ❌ "Update the README with the new CLI flags" - → Docs → Route to PAO + → Look up the current documentation owner in routing.md ✅ "What does .squad/routing.md say about label taxonomy?" → Trivial lookup question — answer directly @@ -80,11 +78,12 @@ Read `.squad/routing.md` for the project-specific routing table. For generic Squ When you determine a task belongs to a specialist, do NOT silently attempt it. Instead: -1. **State clearly** which agent owns it and why: - > "This task (TypeScript type error) belongs to **CONTROL**. I'll note the routing and stop here." +1. **State clearly** which current agent owns it and why: + > "This task matches the type-system route and belongs to **{current member name}**." 2. **Surface the routing path** to the user: - > To proceed: apply the `squad:control` label on issue #NNN, or spawn CONTROL directly with the task context. + > To proceed: apply that member's current `squad:{slug}` label on issue #NNN, + > or spawn the member directly with the task context. 3. **Do not partially complete the task** then hand off — partial work in the wrong agent context creates merge conflicts and inconsistency. diff --git a/.github/workflows/squad-triage.yml b/.github/workflows/squad-triage.yml index 527442647..124de6106 100644 --- a/.github/workflows/squad-triage.yml +++ b/.github/workflows/squad-triage.yml @@ -137,6 +137,71 @@ jobs: function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } + function tableCells(line) { + return line.split('|').slice(1, -1).map(cell => cell.trim()); + } + + function routingRules(markdown) { + const routingLines = markdown.split('\n'); + const rules = []; + + for (let index = 0; index < routingLines.length; index++) { + const line = routingLines[index]; + if (!line.trim().startsWith('|')) continue; + + const headers = tableCells(line).map(cell => cell.toLowerCase()); + const workTypeIndex = headers.indexOf('work type'); + const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const examplesIndex = headers.indexOf('examples'); + if (workTypeIndex < 0 || routeIndex < 0) continue; + + for (let rowIndex = index + 2; rowIndex < routingLines.length; rowIndex++) { + const row = routingLines[rowIndex]; + if (!row.trim().startsWith('|')) break; + const cells = tableCells(row); + const workType = cells[workTypeIndex] || ''; + const routeCell = cells[routeIndex] || ''; + const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; + if (!workType || !routeCell) continue; + + const destinations = members.filter(member => + routeCell.toLowerCase().includes(member.name.toLowerCase()) + ); + for (const member of destinations) { + rules.push({ member, workType, examples }); + } + } + break; + } + + return rules; + } + + function routeScore(issueText, rule) { + const stopWords = new Set([ + 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', + 'work', 'owner', 'agent', 'support', 'management', + ]); + const phrases = rule.workType + .toLowerCase() + .split(/[,/&]+/) + .map(value => value.trim()) + .filter(value => value.length >= 4); + const keywords = `${rule.workType} ${rule.examples}` + .toLowerCase() + .match(/[a-z0-9@.+#-]+/g) || []; + + let score = phrases.reduce( + (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), + 0 + ); + for (const keyword of new Set(keywords)) { + if (keyword.length < 3 || stopWords.has(keyword)) continue; + if (issueText.includes(keyword)) score++; + } + return score; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -169,43 +234,17 @@ jobs: } } - // If not routed to @copilot, use keyword-based routing + // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - 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') || - issueText.includes('button') || issueText.includes('page') || - issueText.includes('layout') || issueText.includes('design'))) { - assignedMember = member; - triageReason = 'Issue relates to frontend/UI work'; - break; - } - if ((role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || - issueText.includes('database') || issueText.includes('endpoint') || - issueText.includes('server') || issueText.includes('auth'))) { - assignedMember = member; - triageReason = 'Issue relates to backend/API work'; - break; - } - if ((role.includes('test') || role.includes('qa') || role.includes('quality')) && - (issueText.includes('test') || issueText.includes('bug') || - issueText.includes('fix') || issueText.includes('regression') || - issueText.includes('coverage'))) { - assignedMember = member; - triageReason = 'Issue relates to testing/quality work'; - break; - } - if ((role.includes('devops') || role.includes('infra') || role.includes('ops')) && - (issueText.includes('deploy') || issueText.includes('ci') || - issueText.includes('pipeline') || issueText.includes('docker') || - issueText.includes('infrastructure'))) { - assignedMember = member; - triageReason = 'Issue relates to DevOps/infrastructure work'; - break; - } + const scoredRoutes = routingRules(routingContent) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length > 0) { + const best = scoredRoutes[0]; + assignedMember = best.rule.member; + triageReason = `Matched routing rule "${best.rule.workType}"`; } } diff --git a/.squad-templates/skills/e2e-template-testing/SKILL.md b/.squad-templates/skills/e2e-template-testing/SKILL.md index 8a027af3c..d775922ff 100644 --- a/.squad-templates/skills/e2e-template-testing/SKILL.md +++ b/.squad-templates/skills/e2e-template-testing/SKILL.md @@ -536,7 +536,7 @@ Fix: always include `--allow-all-tools` (or `--yolo` / `--allow-all`) in Step 4 commands, or export `COPILOT_ALLOW_ALL=1` before running E2E sessions. This also applies when `copilot --agent squad` is launched as a subprocess from -inside a Copilot CLI background agent (e.g. Sims running via the `task` tool) — +inside a Copilot CLI background agent (e.g. a test engineer running via the `task` tool) — the flag is still needed. ### `--allow-all-paths` for repos outside the CWD diff --git a/.squad-templates/spawn-reference.md b/.squad-templates/spawn-reference.md index f036d1216..b5e1748bc 100644 --- a/.squad-templates/spawn-reference.md +++ b/.squad-templates/spawn-reference.md @@ -24,7 +24,7 @@ When `create_session` is available, spawn commit-producing agents as **sub-sessi - **Task** (`task` tool): Pure analysis, coordination, read-only research, or quick one-shot work **Sub-session parameters:** -- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "EECOM refactoring auth", "Flight reviewing arch") +- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "Runtime Engineer refactoring auth", "Lead reviewing architecture") - **`coordinate_with_creator`**: `true` (always — enables cross-session messaging) - **`notify_on_idle`**: `"once"` (coordinator gets notified when agent finishes) - **`kickoff.prompt`**: The full agent prompt (same as task prompt below) diff --git a/.squad-templates/workflows/squad-triage.yml b/.squad-templates/workflows/squad-triage.yml index bf88bae55..2b6beb800 100644 --- a/.squad-templates/workflows/squad-triage.yml +++ b/.squad-templates/workflows/squad-triage.yml @@ -104,6 +104,71 @@ jobs: function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } + function tableCells(line) { + return line.split('|').slice(1, -1).map(cell => cell.trim()); + } + + function routingRules(markdown) { + const routingLines = markdown.split('\n'); + const rules = []; + + for (let index = 0; index < routingLines.length; index++) { + const line = routingLines[index]; + if (!line.trim().startsWith('|')) continue; + + const headers = tableCells(line).map(cell => cell.toLowerCase()); + const workTypeIndex = headers.indexOf('work type'); + const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const examplesIndex = headers.indexOf('examples'); + if (workTypeIndex < 0 || routeIndex < 0) continue; + + for (let rowIndex = index + 2; rowIndex < routingLines.length; rowIndex++) { + const row = routingLines[rowIndex]; + if (!row.trim().startsWith('|')) break; + const cells = tableCells(row); + const workType = cells[workTypeIndex] || ''; + const routeCell = cells[routeIndex] || ''; + const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; + if (!workType || !routeCell) continue; + + const destinations = members.filter(member => + routeCell.toLowerCase().includes(member.name.toLowerCase()) + ); + for (const member of destinations) { + rules.push({ member, workType, examples }); + } + } + break; + } + + return rules; + } + + function routeScore(issueText, rule) { + const stopWords = new Set([ + 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', + 'work', 'owner', 'agent', 'support', 'management', + ]); + const phrases = rule.workType + .toLowerCase() + .split(/[,/&]+/) + .map(value => value.trim()) + .filter(value => value.length >= 4); + const keywords = `${rule.workType} ${rule.examples}` + .toLowerCase() + .match(/[a-z0-9@.+#-]+/g) || []; + + let score = phrases.reduce( + (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), + 0 + ); + for (const keyword of new Set(keywords)) { + if (keyword.length < 3 || stopWords.has(keyword)) continue; + if (issueText.includes(keyword)) score++; + } + return score; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -136,43 +201,17 @@ jobs: } } - // If not routed to @copilot, use keyword-based routing + // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - 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') || - issueText.includes('button') || issueText.includes('page') || - issueText.includes('layout') || issueText.includes('design'))) { - assignedMember = member; - triageReason = 'Issue relates to frontend/UI work'; - break; - } - if ((role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || - issueText.includes('database') || issueText.includes('endpoint') || - issueText.includes('server') || issueText.includes('auth'))) { - assignedMember = member; - triageReason = 'Issue relates to backend/API work'; - break; - } - if ((role.includes('test') || role.includes('qa') || role.includes('quality')) && - (issueText.includes('test') || issueText.includes('bug') || - issueText.includes('fix') || issueText.includes('regression') || - issueText.includes('coverage'))) { - assignedMember = member; - triageReason = 'Issue relates to testing/quality work'; - break; - } - if ((role.includes('devops') || role.includes('infra') || role.includes('ops')) && - (issueText.includes('deploy') || issueText.includes('ci') || - issueText.includes('pipeline') || issueText.includes('docker') || - issueText.includes('infrastructure'))) { - assignedMember = member; - triageReason = 'Issue relates to DevOps/infrastructure work'; - break; - } + const scoredRoutes = routingRules(routingContent) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length > 0) { + const best = scoredRoutes[0]; + assignedMember = best.rule.member; + triageReason = `Matched routing rule "${best.rule.workType}"`; } } diff --git a/packages/squad-cli/templates/skills/agent-conduct/SKILL.md b/packages/squad-cli/templates/skills/agent-conduct/SKILL.md index 87ef3fda3..df87276a0 100644 --- a/packages/squad-cli/templates/skills/agent-conduct/SKILL.md +++ b/packages/squad-cli/templates/skills/agent-conduct/SKILL.md @@ -13,7 +13,7 @@ Every squad agent must follow these two hard rules. They were previously duplica ## Patterns ### Product Isolation Rule (hard rule) -Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to agent names (Flight, EECOM, FIDO, etc.) in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot"). +Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to cast-specific agent names in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot"). ### Peer Quality Check (hard rule) Before finishing work, verify your changes don't break existing tests. Run the test suite for files you touched. If CI has been failing, check your changes aren't contributing to the problem. When you learn from mistakes, update your history.md. diff --git a/packages/squad-cli/templates/skills/docs-standards/SKILL.md b/packages/squad-cli/templates/skills/docs-standards/SKILL.md index c30c54e4b..09039a014 100644 --- a/packages/squad-cli/templates/skills/docs-standards/SKILL.md +++ b/packages/squad-cli/templates/skills/docs-standards/SKILL.md @@ -3,7 +3,7 @@ name: "docs-standards" description: "Microsoft Style Guide + Squad-specific documentation patterns" domain: "documentation" confidence: "high" -source: "earned (PAO charter, multiple doc PR reviews)" +source: "earned (documentation reviews)" --- ## Context diff --git a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md index 8a027af3c..d775922ff 100644 --- a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md @@ -536,7 +536,7 @@ Fix: always include `--allow-all-tools` (or `--yolo` / `--allow-all`) in Step 4 commands, or export `COPILOT_ALLOW_ALL=1` before running E2E sessions. This also applies when `copilot --agent squad` is launched as a subprocess from -inside a Copilot CLI background agent (e.g. Sims running via the `task` tool) — +inside a Copilot CLI background agent (e.g. a test engineer running via the `task` tool) — the flag is still needed. ### `--allow-all-paths` for repos outside the CWD diff --git a/packages/squad-cli/templates/skills/external-comms/SKILL.md b/packages/squad-cli/templates/skills/external-comms/SKILL.md index 9ac372dca..3d625a1f8 100644 --- a/packages/squad-cli/templates/skills/external-comms/SKILL.md +++ b/packages/squad-cli/templates/skills/external-comms/SKILL.md @@ -1,16 +1,16 @@ --- name: "external-comms" -description: "PAO workflow for scanning, drafting, and presenting community responses with human review gate" +description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" domain: "community, communication, workflow" confidence: "low" -source: "manual (RFC #426 — PAO External Communications)" +source: "manual (external communications workflow)" tools: - name: "github-mcp-server-list_issues" description: "List open issues for scan candidates and lightweight triage" when: "Use for recent open issue scans before thread-level review" - name: "github-mcp-server-issue_read" description: "Read the full issue, comments, and labels before drafting" - when: "Use after selecting a candidate so PAO has complete thread context" + when: "Use after selecting a candidate so the communications owner has complete thread context" - name: "github-mcp-server-search_issues" description: "Search for candidate issues or prior squad responses" when: "Use when filtering by keywords, labels, or duplicate response checks" @@ -23,10 +23,10 @@ tools: Phase 1 is **draft-only mode**. -- PAO scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. -- **Human review gate is mandatory** — PAO never posts autonomously. +- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — the communications owner never posts autonomously. - Every action is logged to `.squad/comms/audit/`. -- This workflow is triggered manually only ("PAO, check community") — no automated or Ralph-triggered activation in Phase 1. +- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. ## Patterns @@ -47,7 +47,7 @@ Discussions use the GitHub Discussions API, which differs from issues: - **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions - **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) -- **Answers vs comments:** In Q&A discussions, PAO drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. - **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. ### 2. Classify @@ -107,7 +107,7 @@ Use the humanizer skill for every draft. ### Thread-Read Verification -Before drafting, PAO MUST verify complete thread coverage: +Before drafting, the communications owner MUST verify complete thread coverage: 1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. 2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. @@ -120,7 +120,7 @@ Before drafting, PAO MUST verify complete thread coverage: Show drafts for review in this exact format: ```text -📝 PAO — Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -139,9 +139,9 @@ Each full draft must begin with the thread summary line: Wait for explicit human direction before anything is posted. -- `pao approve 1 3` — approve drafts 1 and 3 -- `pao edit 2` — edit draft 2 -- `pao skip` — skip all +- `comms approve 1 3` — approve drafts 1 and 3 +- `comms edit 2` — edit draft 2 +- `comms skip` — skip all - `banana` — freeze all pending (safe word) ### Rollback — Bad Post Recovery @@ -152,12 +152,12 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` 2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content -3. **Draft replacement** (if needed): PAO drafts a corrected response, goes through normal review cycle +3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle 4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case **Safe word — `banana`:** - Immediately freezes all pending drafts in the review queue -- No new scans or drafts until `pao resume` is issued +- No new scans or drafts until `comms resume` is issued - Audit entry logged with halter identity and reason ### 6. Post @@ -165,7 +165,7 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: After approval: - Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. -- PAO helps by preparing the CLI command. +- The communications owner helps by preparing the CLI command. - Write the audit entry after the posting action. ### 7. Audit @@ -190,7 +190,7 @@ gh issue list --state open --json number,title,author,labels,comments --limit 20 ### Example review table ```text -📝 PAO — Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -319,7 +319,7 @@ That context will help us narrow down what's happening. Appreciate it! - ❌ Posting without human review (NEVER — this is the cardinal rule) - ❌ Drafting without reading full thread (context is everything) -- ❌ Ignoring confidence flags (🔴 items need Flight/human review) +- ❌ Ignoring confidence flags (🔴 items need Lead or human review) - ❌ Scanning closed issues (only open items) - ❌ Responding to issues labeled `squad:internal` or `wontfix` - ❌ Skipping audit logging (every action must be recorded) diff --git a/packages/squad-cli/templates/skills/humanizer/SKILL.md b/packages/squad-cli/templates/skills/humanizer/SKILL.md index 4dbb854df..f3bfaa06c 100644 --- a/packages/squad-cli/templates/skills/humanizer/SKILL.md +++ b/packages/squad-cli/templates/skills/humanizer/SKILL.md @@ -3,16 +3,16 @@ name: "humanizer" description: "Tone enforcement patterns for external-facing community responses" domain: "communication, tone, community" confidence: "low" -source: "manual (RFC #426 — PAO External Communications)" +source: "manual (external communications workflow)" --- ## Context -Use this skill whenever PAO drafts external-facing responses for issues or discussions. +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. - Tone must be warm, helpful, and human-sounding — never robotic or corporate. - Brady's constraint applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. ## Patterns @@ -98,7 +98,7 @@ We'll dig deeper and update this thread. - ❌ Dismissive: "This works as designed" without empathy - ❌ Over-promising: "We'll ship this next week" without commitment from the team - ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Squad Team" +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" - ❌ Excessive emoji: More than 1-2 emoji per response - ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead - ❌ Link-dumping: Pasting URLs without context ("See: https://...") diff --git a/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md b/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md index eccfea3d4..e7d319276 100644 --- a/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md +++ b/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md @@ -44,7 +44,7 @@ Call `Test-RetroOverdue` **at the start of every round**, before building the wo ```powershell # At round start — before any work queue construction if (Test-RetroOverdue -LogDir ".squad/log" -WindowDays 7) { - Write-Host "[RETRO] Retrospective overdue. Running before other work." + Write-Host "[RETROSPECTIVE] Retrospective overdue. Running before other work." # Spawn retro facilitator Invoke-RetroSession -Mode "catch-up" @@ -86,7 +86,7 @@ function Test-RetroActionItemsCreated { $openCheckboxes = [regex]::Matches($content, '- \[ \]') if ($openCheckboxes.Count -gt 0) { - Write-Warning "[RETRO] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues" + Write-Warning "[RETROSPECTIVE] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues" return $false } @@ -145,4 +145,4 @@ function Invoke-RoundStart { | **Trigger** | Coordinator round start | | **Dependencies** | `.squad/log/` directory, GitHub Issues API | | **Tested in** | tamirdresher/tamresearch1 (production, March 2026) | -| **Outcome** | Retro cadence restored; action item completion 0% → 100% | +| **Outcome** | Retro cadence restored; action item completion 0% → 100% | diff --git a/packages/squad-cli/templates/skills/versioning-policy/SKILL.md b/packages/squad-cli/templates/skills/versioning-policy/SKILL.md index 499de8555..59de6f54b 100644 --- a/packages/squad-cli/templates/skills/versioning-policy/SKILL.md +++ b/packages/squad-cli/templates/skills/versioning-policy/SKILL.md @@ -91,7 +91,7 @@ Stable `0.14.0` is a separate immutable package version and GitHub tag. ## 6. Ownership -Surgeon (Release Manager) owns release version changes. Other agents may update +The current Release Manager owns release version changes. Other agents may update versions only when explicitly assigned release work or when reverting an accidentally committed local `-build.N` version. @@ -120,4 +120,4 @@ publishing. | Sync | Root, SDK, CLI, and lockfile workspace versions must match | | Dependency | Preview CLI range and lockfile entry must be `>=VERSION` | | Local build | `-build.N` is local-only and never committed | -| Ownership | Surgeon owns planned release version changes | +| Ownership | The current Release Manager owns planned release version changes | diff --git a/packages/squad-cli/templates/spawn-reference.md b/packages/squad-cli/templates/spawn-reference.md index f036d1216..b5e1748bc 100644 --- a/packages/squad-cli/templates/spawn-reference.md +++ b/packages/squad-cli/templates/spawn-reference.md @@ -24,7 +24,7 @@ When `create_session` is available, spawn commit-producing agents as **sub-sessi - **Task** (`task` tool): Pure analysis, coordination, read-only research, or quick one-shot work **Sub-session parameters:** -- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "EECOM refactoring auth", "Flight reviewing arch") +- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "Runtime Engineer refactoring auth", "Lead reviewing architecture") - **`coordinate_with_creator`**: `true` (always — enables cross-session messaging) - **`notify_on_idle`**: `"once"` (coordinator gets notified when agent finishes) - **`kickoff.prompt`**: The full agent prompt (same as task prompt below) diff --git a/packages/squad-cli/templates/workflows/squad-triage.yml b/packages/squad-cli/templates/workflows/squad-triage.yml index bf88bae55..2b6beb800 100644 --- a/packages/squad-cli/templates/workflows/squad-triage.yml +++ b/packages/squad-cli/templates/workflows/squad-triage.yml @@ -104,6 +104,71 @@ jobs: function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } + function tableCells(line) { + return line.split('|').slice(1, -1).map(cell => cell.trim()); + } + + function routingRules(markdown) { + const routingLines = markdown.split('\n'); + const rules = []; + + for (let index = 0; index < routingLines.length; index++) { + const line = routingLines[index]; + if (!line.trim().startsWith('|')) continue; + + const headers = tableCells(line).map(cell => cell.toLowerCase()); + const workTypeIndex = headers.indexOf('work type'); + const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const examplesIndex = headers.indexOf('examples'); + if (workTypeIndex < 0 || routeIndex < 0) continue; + + for (let rowIndex = index + 2; rowIndex < routingLines.length; rowIndex++) { + const row = routingLines[rowIndex]; + if (!row.trim().startsWith('|')) break; + const cells = tableCells(row); + const workType = cells[workTypeIndex] || ''; + const routeCell = cells[routeIndex] || ''; + const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; + if (!workType || !routeCell) continue; + + const destinations = members.filter(member => + routeCell.toLowerCase().includes(member.name.toLowerCase()) + ); + for (const member of destinations) { + rules.push({ member, workType, examples }); + } + } + break; + } + + return rules; + } + + function routeScore(issueText, rule) { + const stopWords = new Set([ + 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', + 'work', 'owner', 'agent', 'support', 'management', + ]); + const phrases = rule.workType + .toLowerCase() + .split(/[,/&]+/) + .map(value => value.trim()) + .filter(value => value.length >= 4); + const keywords = `${rule.workType} ${rule.examples}` + .toLowerCase() + .match(/[a-z0-9@.+#-]+/g) || []; + + let score = phrases.reduce( + (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), + 0 + ); + for (const keyword of new Set(keywords)) { + if (keyword.length < 3 || stopWords.has(keyword)) continue; + if (issueText.includes(keyword)) score++; + } + return score; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -136,43 +201,17 @@ jobs: } } - // If not routed to @copilot, use keyword-based routing + // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - 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') || - issueText.includes('button') || issueText.includes('page') || - issueText.includes('layout') || issueText.includes('design'))) { - assignedMember = member; - triageReason = 'Issue relates to frontend/UI work'; - break; - } - if ((role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || - issueText.includes('database') || issueText.includes('endpoint') || - issueText.includes('server') || issueText.includes('auth'))) { - assignedMember = member; - triageReason = 'Issue relates to backend/API work'; - break; - } - if ((role.includes('test') || role.includes('qa') || role.includes('quality')) && - (issueText.includes('test') || issueText.includes('bug') || - issueText.includes('fix') || issueText.includes('regression') || - issueText.includes('coverage'))) { - assignedMember = member; - triageReason = 'Issue relates to testing/quality work'; - break; - } - if ((role.includes('devops') || role.includes('infra') || role.includes('ops')) && - (issueText.includes('deploy') || issueText.includes('ci') || - issueText.includes('pipeline') || issueText.includes('docker') || - issueText.includes('infrastructure'))) { - assignedMember = member; - triageReason = 'Issue relates to DevOps/infrastructure work'; - break; - } + const scoredRoutes = routingRules(routingContent) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length > 0) { + const best = scoredRoutes[0]; + assignedMember = best.rule.member; + triageReason = `Matched routing rule "${best.rule.workType}"`; } } diff --git a/packages/squad-sdk/templates/skills/agent-conduct/SKILL.md b/packages/squad-sdk/templates/skills/agent-conduct/SKILL.md index 87ef3fda3..df87276a0 100644 --- a/packages/squad-sdk/templates/skills/agent-conduct/SKILL.md +++ b/packages/squad-sdk/templates/skills/agent-conduct/SKILL.md @@ -13,7 +13,7 @@ Every squad agent must follow these two hard rules. They were previously duplica ## Patterns ### Product Isolation Rule (hard rule) -Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to agent names (Flight, EECOM, FIDO, etc.) in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot"). +Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to cast-specific agent names in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot"). ### Peer Quality Check (hard rule) Before finishing work, verify your changes don't break existing tests. Run the test suite for files you touched. If CI has been failing, check your changes aren't contributing to the problem. When you learn from mistakes, update your history.md. diff --git a/packages/squad-sdk/templates/skills/docs-standards/SKILL.md b/packages/squad-sdk/templates/skills/docs-standards/SKILL.md index c30c54e4b..09039a014 100644 --- a/packages/squad-sdk/templates/skills/docs-standards/SKILL.md +++ b/packages/squad-sdk/templates/skills/docs-standards/SKILL.md @@ -3,7 +3,7 @@ name: "docs-standards" description: "Microsoft Style Guide + Squad-specific documentation patterns" domain: "documentation" confidence: "high" -source: "earned (PAO charter, multiple doc PR reviews)" +source: "earned (documentation reviews)" --- ## Context diff --git a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md index 8a027af3c..d775922ff 100644 --- a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md @@ -536,7 +536,7 @@ Fix: always include `--allow-all-tools` (or `--yolo` / `--allow-all`) in Step 4 commands, or export `COPILOT_ALLOW_ALL=1` before running E2E sessions. This also applies when `copilot --agent squad` is launched as a subprocess from -inside a Copilot CLI background agent (e.g. Sims running via the `task` tool) — +inside a Copilot CLI background agent (e.g. a test engineer running via the `task` tool) — the flag is still needed. ### `--allow-all-paths` for repos outside the CWD diff --git a/packages/squad-sdk/templates/skills/external-comms/SKILL.md b/packages/squad-sdk/templates/skills/external-comms/SKILL.md index 9ac372dca..3d625a1f8 100644 --- a/packages/squad-sdk/templates/skills/external-comms/SKILL.md +++ b/packages/squad-sdk/templates/skills/external-comms/SKILL.md @@ -1,16 +1,16 @@ --- name: "external-comms" -description: "PAO workflow for scanning, drafting, and presenting community responses with human review gate" +description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" domain: "community, communication, workflow" confidence: "low" -source: "manual (RFC #426 — PAO External Communications)" +source: "manual (external communications workflow)" tools: - name: "github-mcp-server-list_issues" description: "List open issues for scan candidates and lightweight triage" when: "Use for recent open issue scans before thread-level review" - name: "github-mcp-server-issue_read" description: "Read the full issue, comments, and labels before drafting" - when: "Use after selecting a candidate so PAO has complete thread context" + when: "Use after selecting a candidate so the communications owner has complete thread context" - name: "github-mcp-server-search_issues" description: "Search for candidate issues or prior squad responses" when: "Use when filtering by keywords, labels, or duplicate response checks" @@ -23,10 +23,10 @@ tools: Phase 1 is **draft-only mode**. -- PAO scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. -- **Human review gate is mandatory** — PAO never posts autonomously. +- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — the communications owner never posts autonomously. - Every action is logged to `.squad/comms/audit/`. -- This workflow is triggered manually only ("PAO, check community") — no automated or Ralph-triggered activation in Phase 1. +- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. ## Patterns @@ -47,7 +47,7 @@ Discussions use the GitHub Discussions API, which differs from issues: - **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions - **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) -- **Answers vs comments:** In Q&A discussions, PAO drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. - **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. ### 2. Classify @@ -107,7 +107,7 @@ Use the humanizer skill for every draft. ### Thread-Read Verification -Before drafting, PAO MUST verify complete thread coverage: +Before drafting, the communications owner MUST verify complete thread coverage: 1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. 2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. @@ -120,7 +120,7 @@ Before drafting, PAO MUST verify complete thread coverage: Show drafts for review in this exact format: ```text -📝 PAO — Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -139,9 +139,9 @@ Each full draft must begin with the thread summary line: Wait for explicit human direction before anything is posted. -- `pao approve 1 3` — approve drafts 1 and 3 -- `pao edit 2` — edit draft 2 -- `pao skip` — skip all +- `comms approve 1 3` — approve drafts 1 and 3 +- `comms edit 2` — edit draft 2 +- `comms skip` — skip all - `banana` — freeze all pending (safe word) ### Rollback — Bad Post Recovery @@ -152,12 +152,12 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` 2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content -3. **Draft replacement** (if needed): PAO drafts a corrected response, goes through normal review cycle +3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle 4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case **Safe word — `banana`:** - Immediately freezes all pending drafts in the review queue -- No new scans or drafts until `pao resume` is issued +- No new scans or drafts until `comms resume` is issued - Audit entry logged with halter identity and reason ### 6. Post @@ -165,7 +165,7 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: After approval: - Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. -- PAO helps by preparing the CLI command. +- The communications owner helps by preparing the CLI command. - Write the audit entry after the posting action. ### 7. Audit @@ -190,7 +190,7 @@ gh issue list --state open --json number,title,author,labels,comments --limit 20 ### Example review table ```text -📝 PAO — Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -319,7 +319,7 @@ That context will help us narrow down what's happening. Appreciate it! - ❌ Posting without human review (NEVER — this is the cardinal rule) - ❌ Drafting without reading full thread (context is everything) -- ❌ Ignoring confidence flags (🔴 items need Flight/human review) +- ❌ Ignoring confidence flags (🔴 items need Lead or human review) - ❌ Scanning closed issues (only open items) - ❌ Responding to issues labeled `squad:internal` or `wontfix` - ❌ Skipping audit logging (every action must be recorded) diff --git a/packages/squad-sdk/templates/skills/humanizer/SKILL.md b/packages/squad-sdk/templates/skills/humanizer/SKILL.md index 4dbb854df..f3bfaa06c 100644 --- a/packages/squad-sdk/templates/skills/humanizer/SKILL.md +++ b/packages/squad-sdk/templates/skills/humanizer/SKILL.md @@ -3,16 +3,16 @@ name: "humanizer" description: "Tone enforcement patterns for external-facing community responses" domain: "communication, tone, community" confidence: "low" -source: "manual (RFC #426 — PAO External Communications)" +source: "manual (external communications workflow)" --- ## Context -Use this skill whenever PAO drafts external-facing responses for issues or discussions. +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. - Tone must be warm, helpful, and human-sounding — never robotic or corporate. - Brady's constraint applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. ## Patterns @@ -98,7 +98,7 @@ We'll dig deeper and update this thread. - ❌ Dismissive: "This works as designed" without empathy - ❌ Over-promising: "We'll ship this next week" without commitment from the team - ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Squad Team" +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" - ❌ Excessive emoji: More than 1-2 emoji per response - ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead - ❌ Link-dumping: Pasting URLs without context ("See: https://...") diff --git a/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md b/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md index 8801e45b0..e7d319276 100644 --- a/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md +++ b/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md @@ -44,7 +44,7 @@ Call `Test-RetroOverdue` **at the start of every round**, before building the wo ```powershell # At round start — before any work queue construction if (Test-RetroOverdue -LogDir ".squad/log" -WindowDays 7) { - Write-Host "[RETRO] Retrospective overdue. Running before other work." + Write-Host "[RETROSPECTIVE] Retrospective overdue. Running before other work." # Spawn retro facilitator Invoke-RetroSession -Mode "catch-up" @@ -86,7 +86,7 @@ function Test-RetroActionItemsCreated { $openCheckboxes = [regex]::Matches($content, '- \[ \]') if ($openCheckboxes.Count -gt 0) { - Write-Warning "[RETRO] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues" + Write-Warning "[RETROSPECTIVE] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues" return $false } diff --git a/packages/squad-sdk/templates/skills/versioning-policy/SKILL.md b/packages/squad-sdk/templates/skills/versioning-policy/SKILL.md index 499de8555..59de6f54b 100644 --- a/packages/squad-sdk/templates/skills/versioning-policy/SKILL.md +++ b/packages/squad-sdk/templates/skills/versioning-policy/SKILL.md @@ -91,7 +91,7 @@ Stable `0.14.0` is a separate immutable package version and GitHub tag. ## 6. Ownership -Surgeon (Release Manager) owns release version changes. Other agents may update +The current Release Manager owns release version changes. Other agents may update versions only when explicitly assigned release work or when reverting an accidentally committed local `-build.N` version. @@ -120,4 +120,4 @@ publishing. | Sync | Root, SDK, CLI, and lockfile workspace versions must match | | Dependency | Preview CLI range and lockfile entry must be `>=VERSION` | | Local build | `-build.N` is local-only and never committed | -| Ownership | Surgeon owns planned release version changes | +| Ownership | The current Release Manager owns planned release version changes | diff --git a/packages/squad-sdk/templates/spawn-reference.md b/packages/squad-sdk/templates/spawn-reference.md index f036d1216..b5e1748bc 100644 --- a/packages/squad-sdk/templates/spawn-reference.md +++ b/packages/squad-sdk/templates/spawn-reference.md @@ -24,7 +24,7 @@ When `create_session` is available, spawn commit-producing agents as **sub-sessi - **Task** (`task` tool): Pure analysis, coordination, read-only research, or quick one-shot work **Sub-session parameters:** -- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "EECOM refactoring auth", "Flight reviewing arch") +- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "Runtime Engineer refactoring auth", "Lead reviewing architecture") - **`coordinate_with_creator`**: `true` (always — enables cross-session messaging) - **`notify_on_idle`**: `"once"` (coordinator gets notified when agent finishes) - **`kickoff.prompt`**: The full agent prompt (same as task prompt below) diff --git a/packages/squad-sdk/templates/workflows/squad-triage.yml b/packages/squad-sdk/templates/workflows/squad-triage.yml index bf88bae55..2b6beb800 100644 --- a/packages/squad-sdk/templates/workflows/squad-triage.yml +++ b/packages/squad-sdk/templates/workflows/squad-triage.yml @@ -104,6 +104,71 @@ jobs: function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } + function tableCells(line) { + return line.split('|').slice(1, -1).map(cell => cell.trim()); + } + + function routingRules(markdown) { + const routingLines = markdown.split('\n'); + const rules = []; + + for (let index = 0; index < routingLines.length; index++) { + const line = routingLines[index]; + if (!line.trim().startsWith('|')) continue; + + const headers = tableCells(line).map(cell => cell.toLowerCase()); + const workTypeIndex = headers.indexOf('work type'); + const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const examplesIndex = headers.indexOf('examples'); + if (workTypeIndex < 0 || routeIndex < 0) continue; + + for (let rowIndex = index + 2; rowIndex < routingLines.length; rowIndex++) { + const row = routingLines[rowIndex]; + if (!row.trim().startsWith('|')) break; + const cells = tableCells(row); + const workType = cells[workTypeIndex] || ''; + const routeCell = cells[routeIndex] || ''; + const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; + if (!workType || !routeCell) continue; + + const destinations = members.filter(member => + routeCell.toLowerCase().includes(member.name.toLowerCase()) + ); + for (const member of destinations) { + rules.push({ member, workType, examples }); + } + } + break; + } + + return rules; + } + + function routeScore(issueText, rule) { + const stopWords = new Set([ + 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', + 'work', 'owner', 'agent', 'support', 'management', + ]); + const phrases = rule.workType + .toLowerCase() + .split(/[,/&]+/) + .map(value => value.trim()) + .filter(value => value.length >= 4); + const keywords = `${rule.workType} ${rule.examples}` + .toLowerCase() + .match(/[a-z0-9@.+#-]+/g) || []; + + let score = phrases.reduce( + (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), + 0 + ); + for (const keyword of new Set(keywords)) { + if (keyword.length < 3 || stopWords.has(keyword)) continue; + if (issueText.includes(keyword)) score++; + } + return score; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -136,43 +201,17 @@ jobs: } } - // If not routed to @copilot, use keyword-based routing + // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - 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') || - issueText.includes('button') || issueText.includes('page') || - issueText.includes('layout') || issueText.includes('design'))) { - assignedMember = member; - triageReason = 'Issue relates to frontend/UI work'; - break; - } - if ((role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || - issueText.includes('database') || issueText.includes('endpoint') || - issueText.includes('server') || issueText.includes('auth'))) { - assignedMember = member; - triageReason = 'Issue relates to backend/API work'; - break; - } - if ((role.includes('test') || role.includes('qa') || role.includes('quality')) && - (issueText.includes('test') || issueText.includes('bug') || - issueText.includes('fix') || issueText.includes('regression') || - issueText.includes('coverage'))) { - assignedMember = member; - triageReason = 'Issue relates to testing/quality work'; - break; - } - if ((role.includes('devops') || role.includes('infra') || role.includes('ops')) && - (issueText.includes('deploy') || issueText.includes('ci') || - issueText.includes('pipeline') || issueText.includes('docker') || - issueText.includes('infrastructure'))) { - assignedMember = member; - triageReason = 'Issue relates to DevOps/infrastructure work'; - break; - } + const scoredRoutes = routingRules(routingContent) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length > 0) { + const best = scoredRoutes[0]; + assignedMember = best.rule.member; + triageReason = `Matched routing rule "${best.rule.workType}"`; } } diff --git a/templates/skills/e2e-template-testing/SKILL.md b/templates/skills/e2e-template-testing/SKILL.md index 8a027af3c..d775922ff 100644 --- a/templates/skills/e2e-template-testing/SKILL.md +++ b/templates/skills/e2e-template-testing/SKILL.md @@ -536,7 +536,7 @@ Fix: always include `--allow-all-tools` (or `--yolo` / `--allow-all`) in Step 4 commands, or export `COPILOT_ALLOW_ALL=1` before running E2E sessions. This also applies when `copilot --agent squad` is launched as a subprocess from -inside a Copilot CLI background agent (e.g. Sims running via the `task` tool) — +inside a Copilot CLI background agent (e.g. a test engineer running via the `task` tool) — the flag is still needed. ### `--allow-all-paths` for repos outside the CWD diff --git a/templates/spawn-reference.md b/templates/spawn-reference.md index f036d1216..b5e1748bc 100644 --- a/templates/spawn-reference.md +++ b/templates/spawn-reference.md @@ -24,7 +24,7 @@ When `create_session` is available, spawn commit-producing agents as **sub-sessi - **Task** (`task` tool): Pure analysis, coordination, read-only research, or quick one-shot work **Sub-session parameters:** -- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "EECOM refactoring auth", "Flight reviewing arch") +- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "Runtime Engineer refactoring auth", "Lead reviewing architecture") - **`coordinate_with_creator`**: `true` (always — enables cross-session messaging) - **`notify_on_idle`**: `"once"` (coordinator gets notified when agent finishes) - **`kickoff.prompt`**: The full agent prompt (same as task prompt below) diff --git a/templates/workflows/squad-triage.yml b/templates/workflows/squad-triage.yml index bf88bae55..2b6beb800 100644 --- a/templates/workflows/squad-triage.yml +++ b/templates/workflows/squad-triage.yml @@ -104,6 +104,71 @@ jobs: function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } + function tableCells(line) { + return line.split('|').slice(1, -1).map(cell => cell.trim()); + } + + function routingRules(markdown) { + const routingLines = markdown.split('\n'); + const rules = []; + + for (let index = 0; index < routingLines.length; index++) { + const line = routingLines[index]; + if (!line.trim().startsWith('|')) continue; + + const headers = tableCells(line).map(cell => cell.toLowerCase()); + const workTypeIndex = headers.indexOf('work type'); + const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const examplesIndex = headers.indexOf('examples'); + if (workTypeIndex < 0 || routeIndex < 0) continue; + + for (let rowIndex = index + 2; rowIndex < routingLines.length; rowIndex++) { + const row = routingLines[rowIndex]; + if (!row.trim().startsWith('|')) break; + const cells = tableCells(row); + const workType = cells[workTypeIndex] || ''; + const routeCell = cells[routeIndex] || ''; + const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; + if (!workType || !routeCell) continue; + + const destinations = members.filter(member => + routeCell.toLowerCase().includes(member.name.toLowerCase()) + ); + for (const member of destinations) { + rules.push({ member, workType, examples }); + } + } + break; + } + + return rules; + } + + function routeScore(issueText, rule) { + const stopWords = new Set([ + 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', + 'work', 'owner', 'agent', 'support', 'management', + ]); + const phrases = rule.workType + .toLowerCase() + .split(/[,/&]+/) + .map(value => value.trim()) + .filter(value => value.length >= 4); + const keywords = `${rule.workType} ${rule.examples}` + .toLowerCase() + .match(/[a-z0-9@.+#-]+/g) || []; + + let score = phrases.reduce( + (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), + 0 + ); + for (const keyword of new Set(keywords)) { + if (keyword.length < 3 || stopWords.has(keyword)) continue; + if (issueText.includes(keyword)) score++; + } + return score; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -136,43 +201,17 @@ jobs: } } - // If not routed to @copilot, use keyword-based routing + // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - 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') || - issueText.includes('button') || issueText.includes('page') || - issueText.includes('layout') || issueText.includes('design'))) { - assignedMember = member; - triageReason = 'Issue relates to frontend/UI work'; - break; - } - if ((role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || - issueText.includes('database') || issueText.includes('endpoint') || - issueText.includes('server') || issueText.includes('auth'))) { - assignedMember = member; - triageReason = 'Issue relates to backend/API work'; - break; - } - if ((role.includes('test') || role.includes('qa') || role.includes('quality')) && - (issueText.includes('test') || issueText.includes('bug') || - issueText.includes('fix') || issueText.includes('regression') || - issueText.includes('coverage'))) { - assignedMember = member; - triageReason = 'Issue relates to testing/quality work'; - break; - } - if ((role.includes('devops') || role.includes('infra') || role.includes('ops')) && - (issueText.includes('deploy') || issueText.includes('ci') || - issueText.includes('pipeline') || issueText.includes('docker') || - issueText.includes('infrastructure'))) { - assignedMember = member; - triageReason = 'Issue relates to DevOps/infrastructure work'; - break; - } + const scoredRoutes = routingRules(routingContent) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length > 0) { + const best = scoredRoutes[0]; + assignedMember = best.rule.member; + triageReason = `Matched routing rule "${best.rule.workType}"`; } } diff --git a/test/recast-identity-neutrality.test.ts b/test/recast-identity-neutrality.test.ts new file mode 100644 index 000000000..c02684a2d --- /dev/null +++ b/test/recast-identity-neutrality.test.ts @@ -0,0 +1,76 @@ +import { readdirSync, readFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { describe, expect, it } from 'vitest'; + +const retiredNames = [ + 'Flight', + 'EECOM', + 'FIDO', + 'PAO', + 'CAPCOM', + 'CONTROL', + 'Booster', + 'Surgeon', + 'Belanna', + 'GNC', + 'RETRO', + 'INCO', + 'GUIDO', + 'VOX', + 'DSKY', + 'Sims', + 'Handbook', +]; + +const identityNeutralFiles = [ + '.github/instructions/squad-routing-guard.instructions.md', + '.github/PR_REQUIREMENTS.md', + '.github/PULL_REQUEST_TEMPLATE.md', + '.github/dependabot.yml', +]; + +const templateRoots = [ + '.squad-templates', + 'templates', + 'packages/squad-cli/templates', + 'packages/squad-sdk/templates', +]; + +function filesUnder(directory: string): string[] { + return readdirSync(directory, { withFileTypes: true }).flatMap(entry => { + const path = join(directory, entry.name); + return entry.isDirectory() ? filesUnder(path) : [path]; + }); +} + +describe('re-cast identity neutrality', () => { + it.each(identityNeutralFiles)('%s does not bind policy to a cast name', file => { + const content = readFileSync(file, 'utf8'); + for (const name of retiredNames) { + expect(content).not.toMatch(new RegExp(`\\b${name}\\b`, 'i')); + } + }); + + it('shipped templates do not contain cast-specific agent names', () => { + const templateFiles = templateRoots.flatMap(filesUnder); + + for (const file of templateFiles) { + const content = readFileSync(file, 'utf8'); + for (const name of retiredNames) { + expect(content, `${file} contains ${name}`).not.toMatch( + new RegExp(`\\b${name}\\b`) + ); + } + } + }); + + it('triage derives ownership from routing.md instead of role-name heuristics', () => { + const workflow = readFileSync('.github/workflows/squad-triage.yml', 'utf8'); + + expect(workflow).toContain('function routingRules(markdown)'); + expect(workflow).toContain('Matched routing rule'); + expect(workflow).not.toContain("role.includes('frontend')"); + expect(workflow).not.toContain("role.includes('backend')"); + expect(workflow).not.toContain("role.includes('devops')"); + }); +}); From 24882a52b52ddb5844a731620189bfc92715a859 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 13:28:37 -0700 Subject: [PATCH 02/12] fix: update canonical identity-neutral skills Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../identity-neutral-squad-templates.md | 8 +++++ .squad/skills/external-comms/SKILL.md | 34 +++++++++---------- .squad/skills/humanizer/SKILL.md | 8 ++--- .squad/skills/versioning-policy/SKILL.md | 4 +-- test/recast-identity-neutrality.test.ts | 1 + 5 files changed, 32 insertions(+), 23 deletions(-) create mode 100644 .changeset/identity-neutral-squad-templates.md diff --git a/.changeset/identity-neutral-squad-templates.md b/.changeset/identity-neutral-squad-templates.md new file mode 100644 index 000000000..0b92fc3da --- /dev/null +++ b/.changeset/identity-neutral-squad-templates.md @@ -0,0 +1,8 @@ +--- +"@bradygaster/squad-cli": patch +"@bradygaster/squad-sdk": patch +--- + +Make shipped Squad templates and issue-routing automation independent of the +repository's current agent cast so teams can be re-cast without stale names, +labels, or ownership rules. diff --git a/.squad/skills/external-comms/SKILL.md b/.squad/skills/external-comms/SKILL.md index 9ac372dca..3d625a1f8 100644 --- a/.squad/skills/external-comms/SKILL.md +++ b/.squad/skills/external-comms/SKILL.md @@ -1,16 +1,16 @@ --- name: "external-comms" -description: "PAO workflow for scanning, drafting, and presenting community responses with human review gate" +description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" domain: "community, communication, workflow" confidence: "low" -source: "manual (RFC #426 — PAO External Communications)" +source: "manual (external communications workflow)" tools: - name: "github-mcp-server-list_issues" description: "List open issues for scan candidates and lightweight triage" when: "Use for recent open issue scans before thread-level review" - name: "github-mcp-server-issue_read" description: "Read the full issue, comments, and labels before drafting" - when: "Use after selecting a candidate so PAO has complete thread context" + when: "Use after selecting a candidate so the communications owner has complete thread context" - name: "github-mcp-server-search_issues" description: "Search for candidate issues or prior squad responses" when: "Use when filtering by keywords, labels, or duplicate response checks" @@ -23,10 +23,10 @@ tools: Phase 1 is **draft-only mode**. -- PAO scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. -- **Human review gate is mandatory** — PAO never posts autonomously. +- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — the communications owner never posts autonomously. - Every action is logged to `.squad/comms/audit/`. -- This workflow is triggered manually only ("PAO, check community") — no automated or Ralph-triggered activation in Phase 1. +- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. ## Patterns @@ -47,7 +47,7 @@ Discussions use the GitHub Discussions API, which differs from issues: - **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions - **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) -- **Answers vs comments:** In Q&A discussions, PAO drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. - **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. ### 2. Classify @@ -107,7 +107,7 @@ Use the humanizer skill for every draft. ### Thread-Read Verification -Before drafting, PAO MUST verify complete thread coverage: +Before drafting, the communications owner MUST verify complete thread coverage: 1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. 2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. @@ -120,7 +120,7 @@ Before drafting, PAO MUST verify complete thread coverage: Show drafts for review in this exact format: ```text -📝 PAO — Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -139,9 +139,9 @@ Each full draft must begin with the thread summary line: Wait for explicit human direction before anything is posted. -- `pao approve 1 3` — approve drafts 1 and 3 -- `pao edit 2` — edit draft 2 -- `pao skip` — skip all +- `comms approve 1 3` — approve drafts 1 and 3 +- `comms edit 2` — edit draft 2 +- `comms skip` — skip all - `banana` — freeze all pending (safe word) ### Rollback — Bad Post Recovery @@ -152,12 +152,12 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` 2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content -3. **Draft replacement** (if needed): PAO drafts a corrected response, goes through normal review cycle +3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle 4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case **Safe word — `banana`:** - Immediately freezes all pending drafts in the review queue -- No new scans or drafts until `pao resume` is issued +- No new scans or drafts until `comms resume` is issued - Audit entry logged with halter identity and reason ### 6. Post @@ -165,7 +165,7 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: After approval: - Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. -- PAO helps by preparing the CLI command. +- The communications owner helps by preparing the CLI command. - Write the audit entry after the posting action. ### 7. Audit @@ -190,7 +190,7 @@ gh issue list --state open --json number,title,author,labels,comments --limit 20 ### Example review table ```text -📝 PAO — Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -319,7 +319,7 @@ That context will help us narrow down what's happening. Appreciate it! - ❌ Posting without human review (NEVER — this is the cardinal rule) - ❌ Drafting without reading full thread (context is everything) -- ❌ Ignoring confidence flags (🔴 items need Flight/human review) +- ❌ Ignoring confidence flags (🔴 items need Lead or human review) - ❌ Scanning closed issues (only open items) - ❌ Responding to issues labeled `squad:internal` or `wontfix` - ❌ Skipping audit logging (every action must be recorded) diff --git a/.squad/skills/humanizer/SKILL.md b/.squad/skills/humanizer/SKILL.md index 4dbb854df..f3bfaa06c 100644 --- a/.squad/skills/humanizer/SKILL.md +++ b/.squad/skills/humanizer/SKILL.md @@ -3,16 +3,16 @@ name: "humanizer" description: "Tone enforcement patterns for external-facing community responses" domain: "communication, tone, community" confidence: "low" -source: "manual (RFC #426 — PAO External Communications)" +source: "manual (external communications workflow)" --- ## Context -Use this skill whenever PAO drafts external-facing responses for issues or discussions. +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. - Tone must be warm, helpful, and human-sounding — never robotic or corporate. - Brady's constraint applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. ## Patterns @@ -98,7 +98,7 @@ We'll dig deeper and update this thread. - ❌ Dismissive: "This works as designed" without empathy - ❌ Over-promising: "We'll ship this next week" without commitment from the team - ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Squad Team" +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" - ❌ Excessive emoji: More than 1-2 emoji per response - ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead - ❌ Link-dumping: Pasting URLs without context ("See: https://...") diff --git a/.squad/skills/versioning-policy/SKILL.md b/.squad/skills/versioning-policy/SKILL.md index 499de8555..59de6f54b 100644 --- a/.squad/skills/versioning-policy/SKILL.md +++ b/.squad/skills/versioning-policy/SKILL.md @@ -91,7 +91,7 @@ Stable `0.14.0` is a separate immutable package version and GitHub tag. ## 6. Ownership -Surgeon (Release Manager) owns release version changes. Other agents may update +The current Release Manager owns release version changes. Other agents may update versions only when explicitly assigned release work or when reverting an accidentally committed local `-build.N` version. @@ -120,4 +120,4 @@ publishing. | Sync | Root, SDK, CLI, and lockfile workspace versions must match | | Dependency | Preview CLI range and lockfile entry must be `>=VERSION` | | Local build | `-build.N` is local-only and never committed | -| Ownership | Surgeon owns planned release version changes | +| Ownership | The current Release Manager owns planned release version changes | diff --git a/test/recast-identity-neutrality.test.ts b/test/recast-identity-neutrality.test.ts index c02684a2d..e8ac980d7 100644 --- a/test/recast-identity-neutrality.test.ts +++ b/test/recast-identity-neutrality.test.ts @@ -30,6 +30,7 @@ const identityNeutralFiles = [ ]; const templateRoots = [ + '.squad/skills', '.squad-templates', 'templates', 'packages/squad-cli/templates', From cac49ceaaa187b9fbcacb6261dc40059a11cbabb Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 13:39:40 -0700 Subject: [PATCH 03/12] fix: address identity routing review Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/agents/squad.agent.md | 2 +- .github/workflows/squad-triage.yml | 82 ++++++++++------ .../skills/e2e-template-testing/SKILL.md | 2 +- .squad-templates/squad.agent.md | 2 +- .squad-templates/workflows/squad-triage.yml | 82 ++++++++++------ .squad/comms/tests/tone-validation-spec.md | 6 +- .squad/skills/tiered-memory/SKILL.md | 9 +- .../skills/e2e-template-testing/SKILL.md | 2 +- .../templates/skills/tiered-memory/SKILL.md | 9 +- .../templates/squad.agent.md.template | 2 +- .../templates/workflows/squad-triage.yml | 82 ++++++++++------ .../skills/e2e-template-testing/SKILL.md | 2 +- .../templates/skills/tiered-memory/SKILL.md | 9 +- .../templates/squad.agent.md.template | 2 +- .../templates/workflows/squad-triage.yml | 82 ++++++++++------ .../skills/e2e-template-testing/SKILL.md | 2 +- templates/squad.agent.md.template | 2 +- templates/workflows/squad-triage.yml | 82 ++++++++++------ test/recast-identity-neutrality.test.ts | 93 ++++++++++++++++++- 19 files changed, 374 insertions(+), 180 deletions(-) diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md index 38e1f9adb..a2bf7384c 100644 --- a/.github/agents/squad.agent.md +++ b/.github/agents/squad.agent.md @@ -219,7 +219,7 @@ When spawning agents, include the role emoji in the `description` parameter to m - `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` -The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture diff --git a/.github/workflows/squad-triage.yml b/.github/workflows/squad-triage.yml index 124de6106..003c03be6 100644 --- a/.github/workflows/squad-triage.yml +++ b/.github/workflows/squad-triage.yml @@ -123,25 +123,34 @@ jobs: routingContent = fs.readFileSync(routingFile, 'utf8'); } - // Find the Lead - const lead = members.find(m => - m.role.toLowerCase().includes('lead') || - m.role.toLowerCase().includes('architect') || - m.role.toLowerCase().includes('coordinator') - ); - - if (!lead) { - core.warning('No Lead role found in team roster — cannot triage'); - return; + function findLead(teamMembers) { + return teamMembers.find(member => { + const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; + return roleWords.includes('lead'); + }); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function tableCells(line) { - return line.split('|').slice(1, -1).map(cell => cell.trim()); + const cells = line.trim().split('|'); + if (cells[0] === '') cells.shift(); + if (cells[cells.length - 1] === '') cells.pop(); + return cells.map(cell => cell.trim()); + } + + function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); } - function routingRules(markdown) { + function routingRules(markdown, teamMembers) { const routingLines = markdown.split('\n'); const rules = []; @@ -164,8 +173,12 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinations = members.filter(member => - routeCell.toLowerCase().includes(member.name.toLowerCase()) + const destinationNames = routeCell + .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) + .map(normalizeRouteDestination) + .filter(Boolean); + const destinations = teamMembers.filter(member => + destinationNames.includes(normalizeRouteDestination(member.name)) ); for (const member of destinations) { rules.push({ member, workType, examples }); @@ -202,6 +215,26 @@ jobs: return score; } + function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { + const scoredRoutes = routingRules(routingContent, teamMembers) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) { + return { member: lead, workType: null }; + } + + const best = scoredRoutes[0]; + return { member: best.rule.member, workType: best.rule.workType }; + } + + const lead = findLead(members); + if (!lead) { + core.warning('No Lead role found in team roster — cannot triage'); + return; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -236,22 +269,11 @@ jobs: // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - const scoredRoutes = routingRules(routingContent) - .map(rule => ({ rule, score: routeScore(issueText, rule) })) - .filter(candidate => candidate.score > 0) - .sort((left, right) => right.score - left.score); - - if (scoredRoutes.length > 0) { - const best = scoredRoutes[0]; - assignedMember = best.rule.member; - triageReason = `Matched routing rule "${best.rule.workType}"`; - } - } - - // Default to Lead if no routing match - if (!assignedMember) { - assignedMember = lead; - triageReason = 'No specific domain match — assigned to Lead for further analysis'; + const assignment = selectRoutingAssignment(issueText, routingContent, members, lead); + assignedMember = assignment.member; + triageReason = assignment.workType + ? `Matched routing rule "${assignment.workType}"` + : 'No specific domain match — assigned to Lead for further analysis'; } const isCopilot = assignedMember.name === '@copilot'; diff --git a/.squad-templates/skills/e2e-template-testing/SKILL.md b/.squad-templates/skills/e2e-template-testing/SKILL.md index d775922ff..0523fd340 100644 --- a/.squad-templates/skills/e2e-template-testing/SKILL.md +++ b/.squad-templates/skills/e2e-template-testing/SKILL.md @@ -391,7 +391,7 @@ when the agent has been running too long. per agent run.** For a plan with multiple copilot-session scenarios, run them in separate agents — not in sequence within a single agent. -If your scenario plan has N copilot-session scenarios, request N separate sims +If your scenario plan has N copilot-session scenarios, request N separate test agents to run them in parallel (one scenario each). Static scenarios may be batched up to 4 per agent. diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md index 38e1f9adb..a2bf7384c 100644 --- a/.squad-templates/squad.agent.md +++ b/.squad-templates/squad.agent.md @@ -219,7 +219,7 @@ When spawning agents, include the role emoji in the `description` parameter to m - `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` -The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture diff --git a/.squad-templates/workflows/squad-triage.yml b/.squad-templates/workflows/squad-triage.yml index 2b6beb800..627626aaf 100644 --- a/.squad-templates/workflows/squad-triage.yml +++ b/.squad-templates/workflows/squad-triage.yml @@ -90,25 +90,34 @@ jobs: routingContent = fs.readFileSync(routingFile, 'utf8'); } - // Find the Lead - const lead = members.find(m => - m.role.toLowerCase().includes('lead') || - m.role.toLowerCase().includes('architect') || - m.role.toLowerCase().includes('coordinator') - ); - - if (!lead) { - core.warning('No Lead role found in team roster — cannot triage'); - return; + function findLead(teamMembers) { + return teamMembers.find(member => { + const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; + return roleWords.includes('lead'); + }); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function tableCells(line) { - return line.split('|').slice(1, -1).map(cell => cell.trim()); + const cells = line.trim().split('|'); + if (cells[0] === '') cells.shift(); + if (cells[cells.length - 1] === '') cells.pop(); + return cells.map(cell => cell.trim()); + } + + function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); } - function routingRules(markdown) { + function routingRules(markdown, teamMembers) { const routingLines = markdown.split('\n'); const rules = []; @@ -131,8 +140,12 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinations = members.filter(member => - routeCell.toLowerCase().includes(member.name.toLowerCase()) + const destinationNames = routeCell + .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) + .map(normalizeRouteDestination) + .filter(Boolean); + const destinations = teamMembers.filter(member => + destinationNames.includes(normalizeRouteDestination(member.name)) ); for (const member of destinations) { rules.push({ member, workType, examples }); @@ -169,6 +182,26 @@ jobs: return score; } + function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { + const scoredRoutes = routingRules(routingContent, teamMembers) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) { + return { member: lead, workType: null }; + } + + const best = scoredRoutes[0]; + return { member: best.rule.member, workType: best.rule.workType }; + } + + const lead = findLead(members); + if (!lead) { + core.warning('No Lead role found in team roster — cannot triage'); + return; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -203,22 +236,11 @@ jobs: // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - const scoredRoutes = routingRules(routingContent) - .map(rule => ({ rule, score: routeScore(issueText, rule) })) - .filter(candidate => candidate.score > 0) - .sort((left, right) => right.score - left.score); - - if (scoredRoutes.length > 0) { - const best = scoredRoutes[0]; - assignedMember = best.rule.member; - triageReason = `Matched routing rule "${best.rule.workType}"`; - } - } - - // Default to Lead if no routing match - if (!assignedMember) { - assignedMember = lead; - triageReason = 'No specific domain match — assigned to Lead for further analysis'; + const assignment = selectRoutingAssignment(issueText, routingContent, members, lead); + assignedMember = assignment.member; + triageReason = assignment.workType + ? `Matched routing rule "${assignment.workType}"` + : 'No specific domain match — assigned to Lead for further analysis'; } const isCopilot = assignedMember.name === '@copilot'; diff --git a/.squad/comms/tests/tone-validation-spec.md b/.squad/comms/tests/tone-validation-spec.md index 4e8edd5d9..b52bd44cf 100644 --- a/.squad/comms/tests/tone-validation-spec.md +++ b/.squad/comms/tests/tone-validation-spec.md @@ -54,11 +54,11 @@ Drafts of specific types MUST contain these patterns: | Test ID | Scenario | Expected Behavior | |---------|----------|------------------| | T5.1 | Draft without human review | BLOCKED — cannot post | -| T5.2 | `pao approve` command without draft ID | Error message | +| T5.2 | `comms approve` command without draft ID | Error message | | T5.3 | Concurrent review sessions | SQLite lock prevents race | | T5.4 | Stale lock (>1 hour) | Auto-cleanup, new session allowed | | T5.5 | `banana` issued (safe word) | All pending drafts frozen | -| T5.6 | `pao resume` after banana | Drafts unfrozen | +| T5.6 | `comms resume` after banana | Drafts unfrozen | ### T6: Audit Trail Completeness @@ -150,5 +150,5 @@ Before launch, ALL of the following must be true: - [ ] Rollback workflow (delete-and-repost) tested end-to-end - [ ] Review gate SQLite schema tested with concurrent access - [ ] Audit trail format validated against template -- [ ] `banana` / `pao resume` flow tested end-to-end +- [ ] `banana` / `comms resume` flow tested end-to-end - [ ] At least one full scan→draft→review→post cycle completed successfully diff --git a/.squad/skills/tiered-memory/SKILL.md b/.squad/skills/tiered-memory/SKILL.md index 5921eb80a..badc64671 100644 --- a/.squad/skills/tiered-memory/SKILL.md +++ b/.squad/skills/tiered-memory/SKILL.md @@ -205,10 +205,10 @@ Include when: ## Escalation If blocked or uncertain: -- Architecture questions → @picard -- Security concerns → @worf -- Infrastructure/deployment → @belanna -- Memory/history questions → @scribe +- Architecture questions → current architecture owner from `routing.md` +- Security concerns → current security owner from `routing.md` +- Infrastructure/deployment → current delivery owner from `routing.md` +- Memory/history questions → current memory owner from `routing.md` --- @@ -218,4 +218,3 @@ If blocked or uncertain: - Cold adds a summary; only include when history is relevant - Wiki adds variable size; only include specific relevant docs - Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn - diff --git a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md index d775922ff..0523fd340 100644 --- a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md @@ -391,7 +391,7 @@ when the agent has been running too long. per agent run.** For a plan with multiple copilot-session scenarios, run them in separate agents — not in sequence within a single agent. -If your scenario plan has N copilot-session scenarios, request N separate sims +If your scenario plan has N copilot-session scenarios, request N separate test agents to run them in parallel (one scenario each). Static scenarios may be batched up to 4 per agent. diff --git a/packages/squad-cli/templates/skills/tiered-memory/SKILL.md b/packages/squad-cli/templates/skills/tiered-memory/SKILL.md index 5921eb80a..badc64671 100644 --- a/packages/squad-cli/templates/skills/tiered-memory/SKILL.md +++ b/packages/squad-cli/templates/skills/tiered-memory/SKILL.md @@ -205,10 +205,10 @@ Include when: ## Escalation If blocked or uncertain: -- Architecture questions → @picard -- Security concerns → @worf -- Infrastructure/deployment → @belanna -- Memory/history questions → @scribe +- Architecture questions → current architecture owner from `routing.md` +- Security concerns → current security owner from `routing.md` +- Infrastructure/deployment → current delivery owner from `routing.md` +- Memory/history questions → current memory owner from `routing.md` --- @@ -218,4 +218,3 @@ If blocked or uncertain: - Cold adds a summary; only include when history is relevant - Wiki adds variable size; only include specific relevant docs - Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn - diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template index 38e1f9adb..a2bf7384c 100644 --- a/packages/squad-cli/templates/squad.agent.md.template +++ b/packages/squad-cli/templates/squad.agent.md.template @@ -219,7 +219,7 @@ When spawning agents, include the role emoji in the `description` parameter to m - `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` -The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture diff --git a/packages/squad-cli/templates/workflows/squad-triage.yml b/packages/squad-cli/templates/workflows/squad-triage.yml index 2b6beb800..627626aaf 100644 --- a/packages/squad-cli/templates/workflows/squad-triage.yml +++ b/packages/squad-cli/templates/workflows/squad-triage.yml @@ -90,25 +90,34 @@ jobs: routingContent = fs.readFileSync(routingFile, 'utf8'); } - // Find the Lead - const lead = members.find(m => - m.role.toLowerCase().includes('lead') || - m.role.toLowerCase().includes('architect') || - m.role.toLowerCase().includes('coordinator') - ); - - if (!lead) { - core.warning('No Lead role found in team roster — cannot triage'); - return; + function findLead(teamMembers) { + return teamMembers.find(member => { + const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; + return roleWords.includes('lead'); + }); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function tableCells(line) { - return line.split('|').slice(1, -1).map(cell => cell.trim()); + const cells = line.trim().split('|'); + if (cells[0] === '') cells.shift(); + if (cells[cells.length - 1] === '') cells.pop(); + return cells.map(cell => cell.trim()); + } + + function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); } - function routingRules(markdown) { + function routingRules(markdown, teamMembers) { const routingLines = markdown.split('\n'); const rules = []; @@ -131,8 +140,12 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinations = members.filter(member => - routeCell.toLowerCase().includes(member.name.toLowerCase()) + const destinationNames = routeCell + .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) + .map(normalizeRouteDestination) + .filter(Boolean); + const destinations = teamMembers.filter(member => + destinationNames.includes(normalizeRouteDestination(member.name)) ); for (const member of destinations) { rules.push({ member, workType, examples }); @@ -169,6 +182,26 @@ jobs: return score; } + function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { + const scoredRoutes = routingRules(routingContent, teamMembers) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) { + return { member: lead, workType: null }; + } + + const best = scoredRoutes[0]; + return { member: best.rule.member, workType: best.rule.workType }; + } + + const lead = findLead(members); + if (!lead) { + core.warning('No Lead role found in team roster — cannot triage'); + return; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -203,22 +236,11 @@ jobs: // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - const scoredRoutes = routingRules(routingContent) - .map(rule => ({ rule, score: routeScore(issueText, rule) })) - .filter(candidate => candidate.score > 0) - .sort((left, right) => right.score - left.score); - - if (scoredRoutes.length > 0) { - const best = scoredRoutes[0]; - assignedMember = best.rule.member; - triageReason = `Matched routing rule "${best.rule.workType}"`; - } - } - - // Default to Lead if no routing match - if (!assignedMember) { - assignedMember = lead; - triageReason = 'No specific domain match — assigned to Lead for further analysis'; + const assignment = selectRoutingAssignment(issueText, routingContent, members, lead); + assignedMember = assignment.member; + triageReason = assignment.workType + ? `Matched routing rule "${assignment.workType}"` + : 'No specific domain match — assigned to Lead for further analysis'; } const isCopilot = assignedMember.name === '@copilot'; diff --git a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md index d775922ff..0523fd340 100644 --- a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md @@ -391,7 +391,7 @@ when the agent has been running too long. per agent run.** For a plan with multiple copilot-session scenarios, run them in separate agents — not in sequence within a single agent. -If your scenario plan has N copilot-session scenarios, request N separate sims +If your scenario plan has N copilot-session scenarios, request N separate test agents to run them in parallel (one scenario each). Static scenarios may be batched up to 4 per agent. diff --git a/packages/squad-sdk/templates/skills/tiered-memory/SKILL.md b/packages/squad-sdk/templates/skills/tiered-memory/SKILL.md index 5921eb80a..badc64671 100644 --- a/packages/squad-sdk/templates/skills/tiered-memory/SKILL.md +++ b/packages/squad-sdk/templates/skills/tiered-memory/SKILL.md @@ -205,10 +205,10 @@ Include when: ## Escalation If blocked or uncertain: -- Architecture questions → @picard -- Security concerns → @worf -- Infrastructure/deployment → @belanna -- Memory/history questions → @scribe +- Architecture questions → current architecture owner from `routing.md` +- Security concerns → current security owner from `routing.md` +- Infrastructure/deployment → current delivery owner from `routing.md` +- Memory/history questions → current memory owner from `routing.md` --- @@ -218,4 +218,3 @@ If blocked or uncertain: - Cold adds a summary; only include when history is relevant - Wiki adds variable size; only include specific relevant docs - Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn - diff --git a/packages/squad-sdk/templates/squad.agent.md.template b/packages/squad-sdk/templates/squad.agent.md.template index 38e1f9adb..a2bf7384c 100644 --- a/packages/squad-sdk/templates/squad.agent.md.template +++ b/packages/squad-sdk/templates/squad.agent.md.template @@ -219,7 +219,7 @@ When spawning agents, include the role emoji in the `description` parameter to m - `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` -The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture diff --git a/packages/squad-sdk/templates/workflows/squad-triage.yml b/packages/squad-sdk/templates/workflows/squad-triage.yml index 2b6beb800..627626aaf 100644 --- a/packages/squad-sdk/templates/workflows/squad-triage.yml +++ b/packages/squad-sdk/templates/workflows/squad-triage.yml @@ -90,25 +90,34 @@ jobs: routingContent = fs.readFileSync(routingFile, 'utf8'); } - // Find the Lead - const lead = members.find(m => - m.role.toLowerCase().includes('lead') || - m.role.toLowerCase().includes('architect') || - m.role.toLowerCase().includes('coordinator') - ); - - if (!lead) { - core.warning('No Lead role found in team roster — cannot triage'); - return; + function findLead(teamMembers) { + return teamMembers.find(member => { + const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; + return roleWords.includes('lead'); + }); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function tableCells(line) { - return line.split('|').slice(1, -1).map(cell => cell.trim()); + const cells = line.trim().split('|'); + if (cells[0] === '') cells.shift(); + if (cells[cells.length - 1] === '') cells.pop(); + return cells.map(cell => cell.trim()); + } + + function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); } - function routingRules(markdown) { + function routingRules(markdown, teamMembers) { const routingLines = markdown.split('\n'); const rules = []; @@ -131,8 +140,12 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinations = members.filter(member => - routeCell.toLowerCase().includes(member.name.toLowerCase()) + const destinationNames = routeCell + .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) + .map(normalizeRouteDestination) + .filter(Boolean); + const destinations = teamMembers.filter(member => + destinationNames.includes(normalizeRouteDestination(member.name)) ); for (const member of destinations) { rules.push({ member, workType, examples }); @@ -169,6 +182,26 @@ jobs: return score; } + function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { + const scoredRoutes = routingRules(routingContent, teamMembers) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) { + return { member: lead, workType: null }; + } + + const best = scoredRoutes[0]; + return { member: best.rule.member, workType: best.rule.workType }; + } + + const lead = findLead(members); + if (!lead) { + core.warning('No Lead role found in team roster — cannot triage'); + return; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -203,22 +236,11 @@ jobs: // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - const scoredRoutes = routingRules(routingContent) - .map(rule => ({ rule, score: routeScore(issueText, rule) })) - .filter(candidate => candidate.score > 0) - .sort((left, right) => right.score - left.score); - - if (scoredRoutes.length > 0) { - const best = scoredRoutes[0]; - assignedMember = best.rule.member; - triageReason = `Matched routing rule "${best.rule.workType}"`; - } - } - - // Default to Lead if no routing match - if (!assignedMember) { - assignedMember = lead; - triageReason = 'No specific domain match — assigned to Lead for further analysis'; + const assignment = selectRoutingAssignment(issueText, routingContent, members, lead); + assignedMember = assignment.member; + triageReason = assignment.workType + ? `Matched routing rule "${assignment.workType}"` + : 'No specific domain match — assigned to Lead for further analysis'; } const isCopilot = assignedMember.name === '@copilot'; diff --git a/templates/skills/e2e-template-testing/SKILL.md b/templates/skills/e2e-template-testing/SKILL.md index d775922ff..0523fd340 100644 --- a/templates/skills/e2e-template-testing/SKILL.md +++ b/templates/skills/e2e-template-testing/SKILL.md @@ -391,7 +391,7 @@ when the agent has been running too long. per agent run.** For a plan with multiple copilot-session scenarios, run them in separate agents — not in sequence within a single agent. -If your scenario plan has N copilot-session scenarios, request N separate sims +If your scenario plan has N copilot-session scenarios, request N separate test agents to run them in parallel (one scenario each). Static scenarios may be batched up to 4 per agent. diff --git a/templates/squad.agent.md.template b/templates/squad.agent.md.template index 38e1f9adb..a2bf7384c 100644 --- a/templates/squad.agent.md.template +++ b/templates/squad.agent.md.template @@ -219,7 +219,7 @@ When spawning agents, include the role emoji in the `description` parameter to m - `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` -The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture diff --git a/templates/workflows/squad-triage.yml b/templates/workflows/squad-triage.yml index 2b6beb800..627626aaf 100644 --- a/templates/workflows/squad-triage.yml +++ b/templates/workflows/squad-triage.yml @@ -90,25 +90,34 @@ jobs: routingContent = fs.readFileSync(routingFile, 'utf8'); } - // Find the Lead - const lead = members.find(m => - m.role.toLowerCase().includes('lead') || - m.role.toLowerCase().includes('architect') || - m.role.toLowerCase().includes('coordinator') - ); - - if (!lead) { - core.warning('No Lead role found in team roster — cannot triage'); - return; + function findLead(teamMembers) { + return teamMembers.find(member => { + const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; + return roleWords.includes('lead'); + }); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function tableCells(line) { - return line.split('|').slice(1, -1).map(cell => cell.trim()); + const cells = line.trim().split('|'); + if (cells[0] === '') cells.shift(); + if (cells[cells.length - 1] === '') cells.pop(); + return cells.map(cell => cell.trim()); + } + + function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); } - function routingRules(markdown) { + function routingRules(markdown, teamMembers) { const routingLines = markdown.split('\n'); const rules = []; @@ -131,8 +140,12 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinations = members.filter(member => - routeCell.toLowerCase().includes(member.name.toLowerCase()) + const destinationNames = routeCell + .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) + .map(normalizeRouteDestination) + .filter(Boolean); + const destinations = teamMembers.filter(member => + destinationNames.includes(normalizeRouteDestination(member.name)) ); for (const member of destinations) { rules.push({ member, workType, examples }); @@ -169,6 +182,26 @@ jobs: return score; } + function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { + const scoredRoutes = routingRules(routingContent, teamMembers) + .map(rule => ({ rule, score: routeScore(issueText, rule) })) + .filter(candidate => candidate.score > 0) + .sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) { + return { member: lead, workType: null }; + } + + const best = scoredRoutes[0]; + return { member: best.rule.member, workType: best.rule.workType }; + } + + const lead = findLead(members); + if (!lead) { + core.warning('No Lead role found in team roster — cannot triage'); + return; + } + // Build triage context const memberList = members.map(m => `- **${m.name}** (${m.role}) → label: \`squad:${slugify(m.name)}\`` @@ -203,22 +236,11 @@ jobs: // If not routed to @copilot, score the repository's current routing table. if (!assignedMember) { - const scoredRoutes = routingRules(routingContent) - .map(rule => ({ rule, score: routeScore(issueText, rule) })) - .filter(candidate => candidate.score > 0) - .sort((left, right) => right.score - left.score); - - if (scoredRoutes.length > 0) { - const best = scoredRoutes[0]; - assignedMember = best.rule.member; - triageReason = `Matched routing rule "${best.rule.workType}"`; - } - } - - // Default to Lead if no routing match - if (!assignedMember) { - assignedMember = lead; - triageReason = 'No specific domain match — assigned to Lead for further analysis'; + const assignment = selectRoutingAssignment(issueText, routingContent, members, lead); + assignedMember = assignment.member; + triageReason = assignment.workType + ? `Matched routing rule "${assignment.workType}"` + : 'No specific domain match — assigned to Lead for further analysis'; } const isCopilot = assignedMember.name === '@copilot'; diff --git a/test/recast-identity-neutrality.test.ts b/test/recast-identity-neutrality.test.ts index e8ac980d7..d141f9000 100644 --- a/test/recast-identity-neutrality.test.ts +++ b/test/recast-identity-neutrality.test.ts @@ -1,5 +1,6 @@ import { readdirSync, readFileSync } from 'node:fs'; import { join } from 'node:path'; +import { runInNewContext } from 'node:vm'; import { describe, expect, it } from 'vitest'; const retiredNames = [ @@ -37,6 +38,28 @@ const templateRoots = [ 'packages/squad-sdk/templates', ]; +const broadlyScannableTemplateNames = retiredNames.filter( + name => !['Flight', 'CONTROL', 'RETRO'].includes(name) +); + +const contextualTemplateNameChecks = [ + { name: 'Flight', pattern: /(? Member | undefined; + selectRoutingAssignment: ( + issueText: string, + routingContent: string, + members: Member[], + lead: Member + ) => RoutingAssignment; +}; + function filesUnder(directory: string): string[] { return readdirSync(directory, { withFileTypes: true }).flatMap(entry => { const path = join(directory, entry.name); @@ -44,6 +67,24 @@ function filesUnder(directory: string): string[] { }); } +function triageHelpers(workflow: string): TriageHelpers { + const start = workflow.indexOf(' function findLead'); + const end = workflow.indexOf(' const lead = findLead'); + expect(start).toBeGreaterThanOrEqual(0); + expect(end).toBeGreaterThan(start); + + const context: { result?: TriageHelpers } = {}; + runInNewContext( + `${workflow.slice(start, end)} + result = { findLead, selectRoutingAssignment };`, + context + ); + if (!context.result) { + throw new Error('Unable to load triage helpers from workflow'); + } + return context.result; +} + describe('re-cast identity neutrality', () => { it.each(identityNeutralFiles)('%s does not bind policy to a cast name', file => { const content = readFileSync(file, 'utf8'); @@ -57,21 +98,67 @@ describe('re-cast identity neutrality', () => { for (const file of templateFiles) { const content = readFileSync(file, 'utf8'); - for (const name of retiredNames) { + for (const name of broadlyScannableTemplateNames) { expect(content, `${file} contains ${name}`).not.toMatch( - new RegExp(`\\b${name}\\b`) + new RegExp(`\\b${name}\\b`, 'i') ); } + for (const check of contextualTemplateNameChecks) { + expect(content, `${file} contains ${check.name}`).not.toMatch(check.pattern); + } } }); it('triage derives ownership from routing.md instead of role-name heuristics', () => { const workflow = readFileSync('.github/workflows/squad-triage.yml', 'utf8'); - expect(workflow).toContain('function routingRules(markdown)'); + expect(workflow).toContain('function routingRules(markdown, teamMembers)'); expect(workflow).toContain('Matched routing rule'); expect(workflow).not.toContain("role.includes('frontend')"); expect(workflow).not.toContain("role.includes('backend')"); expect(workflow).not.toContain("role.includes('devops')"); }); + + it('executes routing matches, exact destinations, and Lead fallback', () => { + const workflow = readFileSync('.github/workflows/squad-triage.yml', 'utf8'); + const helpers = triageHelpers(workflow); + const architect = { name: 'Architect', role: 'Architect' }; + const lead = { name: 'Team Lead', role: 'Technical Lead' }; + const runtime = { name: 'Runtime Engineer', role: 'Runtime' }; + const ann = { name: 'Ann', role: 'Documentation' }; + const anna = { name: 'Anna', role: 'Documentation' }; + const members = [architect, lead, runtime, ann, anna]; + const routing = [ + '| Work Type | Agent | Examples', + '| --- | --- | ---', + '| Core runtime | Runtime Engineer 🔧 | adapter, session pool', + '| Docs | Anna 📚 | readme, documentation', + ].join('\n'); + + expect(helpers.findLead(members)).toEqual(lead); + expect( + helpers.selectRoutingAssignment( + 'adapter session pool regression', + routing, + members, + lead + ) + ).toEqual({ member: runtime, workType: 'Core runtime' }); + expect( + helpers.selectRoutingAssignment( + 'readme documentation update', + routing, + members, + lead + ) + ).toEqual({ member: anna, workType: 'Docs' }); + expect( + helpers.selectRoutingAssignment( + 'unclassified request', + routing, + members, + lead + ) + ).toEqual({ member: lead, workType: null }); + }); }); From 174f1f947d6e4ba024412378940adcbce86e83f4 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 15:21:08 -0700 Subject: [PATCH 04/12] fix: isolate product assets from team state Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../identity-neutral-squad-templates.md | 8 +- .dockerignore | 2 +- .github/PR_REQUIREMENTS.md | 30 +- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/agents/squad.agent.md | 18 +- .github/workflows/squad-ci.yml | 5 +- .github/workflows/squad-heartbeat.yml | 6 +- .github/workflows/squad-triage.yml | 85 ++-- .squad-templates/machine-capabilities.md | 2 +- .squad-templates/model-selection-reference.md | 8 +- .squad-templates/notes-protocol.md | 11 +- .squad-templates/ralph-triage.js | 20 +- .../skills/agent-collaboration/SKILL.md | 42 ++ .../skills/agent-conduct/SKILL.md | 24 + .../skills/architectural-proposals/SKILL.md | 151 ++++++ .../skills/ci-validation-gates/SKILL.md | 84 ++++ .squad-templates/skills/cli-wiring/SKILL.md | 47 ++ .../skills/client-compatibility/SKILL.md | 89 ++++ .../skills/coordinator-init-mode/SKILL.md | 99 ++++ .../skills/coordinator-response-mode/SKILL.md | 97 ++++ .../coordinator-source-of-truth/SKILL.md | 45 ++ .../cross-machine-coordination/SKILL.md | 442 ++++++++++++++++++ .../skills/cross-squad-communication/SKILL.md | 399 ++++++++++++++++ .squad-templates/skills/cross-squad/SKILL.md | 174 +++++++ .../skills/distributed-mesh/SKILL.md | 287 ++++++++++++ .../skills/distributed-mesh/mesh.json.example | 30 ++ .../skills/distributed-mesh/sync-mesh.ps1 | 111 +++++ .../skills/distributed-mesh/sync-mesh.sh | 104 +++++ .../skills/docs-standards/SKILL.md | 71 +++ .../skills/e2e-template-testing/SKILL.md | 4 +- .squad-templates/skills/economy-mode/SKILL.md | 115 +++++ .../skills/error-recovery/SKILL.md | 99 ++++ .../skills/external-comms/SKILL.md | 329 +++++++++++++ .../skills/fact-checking/SKILL.md | 61 +++ .../skills/gh-auth-isolation/SKILL.md | 183 ++++++++ .../skills/gh-aw-enlistment/SKILL.md | 347 ++++++++++++++ .squad-templates/skills/git-workflow/SKILL.md | 204 ++++++++ .../skills/github-multi-account/SKILL.md | 95 ++++ .../skills/history-hygiene/SKILL.md | 36 ++ .squad-templates/skills/humanizer/SKILL.md | 105 +++++ .squad-templates/skills/init-mode/SKILL.md | 104 +++++ .../skills/iterative-retrieval/SKILL.md | 165 +++++++ .../skills/model-selection/SKILL.md | 125 +++++ .../skills/notification-routing/SKILL.md | 105 +++++ .../skills/personal-squad/SKILL.md | 66 +++ .../skills/pr-review-response/SKILL.md | 268 +++++++++++ .../skills/pr-screenshots/SKILL.md | 149 ++++++ .../skills/project-conventions/SKILL.md | 56 +++ .../skills/ralph-two-pass-scan/SKILL.md | 43 ++ .squad-templates/skills/reflect/SKILL.md | 229 +++++++++ .../skills/release-process/SKILL.md | 237 ++++++++++ .squad-templates/skills/reskill/SKILL.md | 92 ++++ .../skills/retro-enforcement/SKILL.md | 148 ++++++ .../skills/reviewer-protocol/SKILL.md | 79 ++++ .../skills/secret-handling/SKILL.md | 200 ++++++++ .../skills/session-recovery/SKILL.md | 155 ++++++ .../skills/squad-commands/SKILL.md | 303 ++++++++++++ .squad-templates/skills/squad-help/SKILL.md | 97 ++++ .../skills/squad-version-check/SKILL.md | 169 +++++++ .squad-templates/skills/squad/SKILL.md | 299 ++++++++++++ .../skills/test-discipline/SKILL.md | 37 ++ .../skills/tiered-memory/SKILL.md | 220 +++++++++ .../skills/versioning-policy/SKILL.md | 123 +++++ .../skills/windows-compatibility/SKILL.md | 98 ++++ .squad-templates/spawn-reference.md | 2 +- .squad-templates/squad.agent.md | 18 +- .squad-templates/workflows/squad-triage.yml | 85 ++-- .squad/comms/tests/tone-validation-spec.md | 6 +- .squad/skills/external-comms/SKILL.md | 34 +- .squad/skills/humanizer/SKILL.md | 8 +- .squad/skills/tiered-memory/SKILL.md | 9 +- .squad/skills/versioning-policy/SKILL.md | 4 +- package.json | 4 +- .../src/cli/shell/components/Separator.tsx | 2 +- .../shell/components/ThinkingIndicator.tsx | 2 +- .../squad-cli/src/cli/shell/useAnimation.ts | 2 +- .../templates/machine-capabilities.md | 2 +- .../templates/model-selection-reference.md | 8 +- .../squad-cli/templates/notes-protocol.md | 11 +- packages/squad-cli/templates/ralph-triage.js | 20 +- .../skills/architectural-proposals/SKILL.md | 2 +- .../skills/ci-validation-gates/SKILL.md | 4 +- .../skills/client-compatibility/SKILL.md | 4 +- .../cross-machine-coordination/SKILL.md | 2 +- .../skills/e2e-template-testing/SKILL.md | 4 +- .../templates/skills/external-comms/SKILL.md | 34 +- .../templates/skills/history-hygiene/SKILL.md | 10 +- .../templates/skills/humanizer/SKILL.md | 10 +- .../templates/skills/init-mode/SKILL.md | 22 +- .../skills/notification-routing/SKILL.md | 2 +- .../skills/project-conventions/SKILL.md | 56 +++ .../templates/skills/reskill/SKILL.md | 2 +- .../skills/reviewer-protocol/SKILL.md | 36 +- .../skills/squad-version-check/SKILL.md | 4 +- .../templates/skills/test-discipline/SKILL.md | 2 +- .../squad-cli/templates/spawn-reference.md | 2 +- .../templates/squad.agent.md.template | 18 +- .../templates/workflows/squad-triage.yml | 85 ++-- packages/squad-sdk/src/config/init.ts | 2 +- packages/squad-sdk/src/ralph/triage.ts | 15 +- .../templates/machine-capabilities.md | 2 +- .../templates/model-selection-reference.md | 8 +- .../squad-sdk/templates/notes-protocol.md | 11 +- packages/squad-sdk/templates/ralph-triage.js | 20 +- .../skills/architectural-proposals/SKILL.md | 2 +- .../skills/ci-validation-gates/SKILL.md | 4 +- .../skills/client-compatibility/SKILL.md | 4 +- .../cross-machine-coordination/SKILL.md | 2 +- .../skills/e2e-template-testing/SKILL.md | 4 +- .../templates/skills/external-comms/SKILL.md | 34 +- .../templates/skills/history-hygiene/SKILL.md | 10 +- .../templates/skills/humanizer/SKILL.md | 10 +- .../skills/notification-routing/SKILL.md | 2 +- .../templates/skills/reskill/SKILL.md | 2 +- .../skills/reviewer-protocol/SKILL.md | 36 +- .../skills/squad-version-check/SKILL.md | 4 +- .../templates/skills/test-discipline/SKILL.md | 2 +- .../squad-sdk/templates/spawn-reference.md | 2 +- .../templates/squad.agent.md.template | 18 +- .../templates/workflows/squad-triage.yml | 85 ++-- scripts/size-regression-guard.mjs | 5 +- scripts/sync-skill-templates.mjs | 9 +- scripts/sync-templates.mjs | 17 +- squad.config.ts | 89 ---- templates/machine-capabilities.md | 2 +- templates/model-selection-reference.md | 8 +- templates/notes-protocol.md | 11 +- templates/ralph-triage.js | 20 +- templates/skills/agent-collaboration/SKILL.md | 42 ++ templates/skills/agent-conduct/SKILL.md | 24 + .../skills/architectural-proposals/SKILL.md | 151 ++++++ templates/skills/ci-validation-gates/SKILL.md | 84 ++++ templates/skills/cli-wiring/SKILL.md | 47 ++ .../skills/client-compatibility/SKILL.md | 89 ++++ .../skills/coordinator-init-mode/SKILL.md | 99 ++++ .../skills/coordinator-response-mode/SKILL.md | 97 ++++ .../coordinator-source-of-truth/SKILL.md | 45 ++ .../cross-machine-coordination/SKILL.md | 442 ++++++++++++++++++ .../skills/cross-squad-communication/SKILL.md | 399 ++++++++++++++++ templates/skills/cross-squad/SKILL.md | 174 +++++++ templates/skills/distributed-mesh/SKILL.md | 287 ++++++++++++ .../skills/distributed-mesh/mesh.json.example | 30 ++ .../skills/distributed-mesh/sync-mesh.ps1 | 111 +++++ .../skills/distributed-mesh/sync-mesh.sh | 104 +++++ templates/skills/docs-standards/SKILL.md | 71 +++ .../skills/e2e-template-testing/SKILL.md | 4 +- templates/skills/economy-mode/SKILL.md | 115 +++++ templates/skills/error-recovery/SKILL.md | 99 ++++ templates/skills/external-comms/SKILL.md | 329 +++++++++++++ templates/skills/fact-checking/SKILL.md | 61 +++ templates/skills/gh-auth-isolation/SKILL.md | 183 ++++++++ templates/skills/gh-aw-enlistment/SKILL.md | 347 ++++++++++++++ templates/skills/git-workflow/SKILL.md | 204 ++++++++ .../skills/github-multi-account/SKILL.md | 95 ++++ templates/skills/history-hygiene/SKILL.md | 36 ++ templates/skills/humanizer/SKILL.md | 105 +++++ templates/skills/init-mode/SKILL.md | 104 +++++ templates/skills/iterative-retrieval/SKILL.md | 165 +++++++ templates/skills/model-selection/SKILL.md | 125 +++++ .../skills/notification-routing/SKILL.md | 105 +++++ templates/skills/personal-squad/SKILL.md | 66 +++ templates/skills/pr-review-response/SKILL.md | 268 +++++++++++ templates/skills/pr-screenshots/SKILL.md | 149 ++++++ templates/skills/project-conventions/SKILL.md | 56 +++ templates/skills/ralph-two-pass-scan/SKILL.md | 43 ++ templates/skills/reflect/SKILL.md | 229 +++++++++ templates/skills/release-process/SKILL.md | 237 ++++++++++ templates/skills/reskill/SKILL.md | 92 ++++ templates/skills/retro-enforcement/SKILL.md | 148 ++++++ templates/skills/reviewer-protocol/SKILL.md | 79 ++++ templates/skills/rework-rate/SKILL.md | 82 ---- templates/skills/secret-handling/SKILL.md | 200 ++++++++ templates/skills/session-recovery/SKILL.md | 155 ++++++ templates/skills/squad-commands/SKILL.md | 303 ++++++++++++ templates/skills/squad-help/SKILL.md | 97 ++++ templates/skills/squad-version-check/SKILL.md | 169 +++++++ templates/skills/squad/SKILL.md | 299 ++++++++++++ templates/skills/test-discipline/SKILL.md | 37 ++ templates/skills/tiered-memory/SKILL.md | 220 +++++++++ templates/skills/versioning-policy/SKILL.md | 123 +++++ .../skills/windows-compatibility/SKILL.md | 98 ++++ templates/spawn-reference.md | 2 +- templates/squad.agent.md.template | 18 +- templates/workflows/squad-triage.yml | 85 ++-- test/catalog-refresh.test.ts | 1 - test/ci/changelog-gate.test.ts | 4 +- test/cross-squad.test.ts | 2 +- test/e2e-runbook-hygiene.test.ts | 197 -------- test/gh-aw-enlistment-skill.test.ts | 2 +- test/gh-aw-plan-lifecycle.test.ts | 27 +- test/gh-aw-research-online.test.ts | 6 - test/ralph-triage.test.ts | 96 ++-- test/recast-identity-neutrality.test.ts | 242 +++++++--- test/squad-agent-roster.test.ts | 2 +- test/state/archival.test.ts | 8 - test/template-sync.test.ts | 81 ++-- workflows/shared/squad-planning-ontology.md | 2 +- workflows/squad-deps-worker.md | 6 +- workflows/squad.md | 2 +- 199 files changed, 15870 insertions(+), 1030 deletions(-) create mode 100644 .squad-templates/skills/agent-collaboration/SKILL.md create mode 100644 .squad-templates/skills/agent-conduct/SKILL.md create mode 100644 .squad-templates/skills/architectural-proposals/SKILL.md create mode 100644 .squad-templates/skills/ci-validation-gates/SKILL.md create mode 100644 .squad-templates/skills/cli-wiring/SKILL.md create mode 100644 .squad-templates/skills/client-compatibility/SKILL.md create mode 100644 .squad-templates/skills/coordinator-init-mode/SKILL.md create mode 100644 .squad-templates/skills/coordinator-response-mode/SKILL.md create mode 100644 .squad-templates/skills/coordinator-source-of-truth/SKILL.md create mode 100644 .squad-templates/skills/cross-machine-coordination/SKILL.md create mode 100644 .squad-templates/skills/cross-squad-communication/SKILL.md create mode 100644 .squad-templates/skills/cross-squad/SKILL.md create mode 100644 .squad-templates/skills/distributed-mesh/SKILL.md create mode 100644 .squad-templates/skills/distributed-mesh/mesh.json.example create mode 100644 .squad-templates/skills/distributed-mesh/sync-mesh.ps1 create mode 100644 .squad-templates/skills/distributed-mesh/sync-mesh.sh create mode 100644 .squad-templates/skills/docs-standards/SKILL.md create mode 100644 .squad-templates/skills/economy-mode/SKILL.md create mode 100644 .squad-templates/skills/error-recovery/SKILL.md create mode 100644 .squad-templates/skills/external-comms/SKILL.md create mode 100644 .squad-templates/skills/fact-checking/SKILL.md create mode 100644 .squad-templates/skills/gh-auth-isolation/SKILL.md create mode 100644 .squad-templates/skills/gh-aw-enlistment/SKILL.md create mode 100644 .squad-templates/skills/git-workflow/SKILL.md create mode 100644 .squad-templates/skills/github-multi-account/SKILL.md create mode 100644 .squad-templates/skills/history-hygiene/SKILL.md create mode 100644 .squad-templates/skills/humanizer/SKILL.md create mode 100644 .squad-templates/skills/init-mode/SKILL.md create mode 100644 .squad-templates/skills/iterative-retrieval/SKILL.md create mode 100644 .squad-templates/skills/model-selection/SKILL.md create mode 100644 .squad-templates/skills/notification-routing/SKILL.md create mode 100644 .squad-templates/skills/personal-squad/SKILL.md create mode 100644 .squad-templates/skills/pr-review-response/SKILL.md create mode 100644 .squad-templates/skills/pr-screenshots/SKILL.md create mode 100644 .squad-templates/skills/project-conventions/SKILL.md create mode 100644 .squad-templates/skills/ralph-two-pass-scan/SKILL.md create mode 100644 .squad-templates/skills/reflect/SKILL.md create mode 100644 .squad-templates/skills/release-process/SKILL.md create mode 100644 .squad-templates/skills/reskill/SKILL.md create mode 100644 .squad-templates/skills/retro-enforcement/SKILL.md create mode 100644 .squad-templates/skills/reviewer-protocol/SKILL.md create mode 100644 .squad-templates/skills/secret-handling/SKILL.md create mode 100644 .squad-templates/skills/session-recovery/SKILL.md create mode 100644 .squad-templates/skills/squad-commands/SKILL.md create mode 100644 .squad-templates/skills/squad-help/SKILL.md create mode 100644 .squad-templates/skills/squad-version-check/SKILL.md create mode 100644 .squad-templates/skills/squad/SKILL.md create mode 100644 .squad-templates/skills/test-discipline/SKILL.md create mode 100644 .squad-templates/skills/tiered-memory/SKILL.md create mode 100644 .squad-templates/skills/versioning-policy/SKILL.md create mode 100644 .squad-templates/skills/windows-compatibility/SKILL.md create mode 100644 packages/squad-cli/templates/skills/project-conventions/SKILL.md delete mode 100644 squad.config.ts create mode 100644 templates/skills/agent-collaboration/SKILL.md create mode 100644 templates/skills/agent-conduct/SKILL.md create mode 100644 templates/skills/architectural-proposals/SKILL.md create mode 100644 templates/skills/ci-validation-gates/SKILL.md create mode 100644 templates/skills/cli-wiring/SKILL.md create mode 100644 templates/skills/client-compatibility/SKILL.md create mode 100644 templates/skills/coordinator-init-mode/SKILL.md create mode 100644 templates/skills/coordinator-response-mode/SKILL.md create mode 100644 templates/skills/coordinator-source-of-truth/SKILL.md create mode 100644 templates/skills/cross-machine-coordination/SKILL.md create mode 100644 templates/skills/cross-squad-communication/SKILL.md create mode 100644 templates/skills/cross-squad/SKILL.md create mode 100644 templates/skills/distributed-mesh/SKILL.md create mode 100644 templates/skills/distributed-mesh/mesh.json.example create mode 100644 templates/skills/distributed-mesh/sync-mesh.ps1 create mode 100644 templates/skills/distributed-mesh/sync-mesh.sh create mode 100644 templates/skills/docs-standards/SKILL.md create mode 100644 templates/skills/economy-mode/SKILL.md create mode 100644 templates/skills/error-recovery/SKILL.md create mode 100644 templates/skills/external-comms/SKILL.md create mode 100644 templates/skills/fact-checking/SKILL.md create mode 100644 templates/skills/gh-auth-isolation/SKILL.md create mode 100644 templates/skills/gh-aw-enlistment/SKILL.md create mode 100644 templates/skills/git-workflow/SKILL.md create mode 100644 templates/skills/github-multi-account/SKILL.md create mode 100644 templates/skills/history-hygiene/SKILL.md create mode 100644 templates/skills/humanizer/SKILL.md create mode 100644 templates/skills/init-mode/SKILL.md create mode 100644 templates/skills/iterative-retrieval/SKILL.md create mode 100644 templates/skills/model-selection/SKILL.md create mode 100644 templates/skills/notification-routing/SKILL.md create mode 100644 templates/skills/personal-squad/SKILL.md create mode 100644 templates/skills/pr-review-response/SKILL.md create mode 100644 templates/skills/pr-screenshots/SKILL.md create mode 100644 templates/skills/project-conventions/SKILL.md create mode 100644 templates/skills/ralph-two-pass-scan/SKILL.md create mode 100644 templates/skills/reflect/SKILL.md create mode 100644 templates/skills/release-process/SKILL.md create mode 100644 templates/skills/reskill/SKILL.md create mode 100644 templates/skills/retro-enforcement/SKILL.md create mode 100644 templates/skills/reviewer-protocol/SKILL.md delete mode 100644 templates/skills/rework-rate/SKILL.md create mode 100644 templates/skills/secret-handling/SKILL.md create mode 100644 templates/skills/session-recovery/SKILL.md create mode 100644 templates/skills/squad-commands/SKILL.md create mode 100644 templates/skills/squad-help/SKILL.md create mode 100644 templates/skills/squad-version-check/SKILL.md create mode 100644 templates/skills/squad/SKILL.md create mode 100644 templates/skills/test-discipline/SKILL.md create mode 100644 templates/skills/tiered-memory/SKILL.md create mode 100644 templates/skills/versioning-policy/SKILL.md create mode 100644 templates/skills/windows-compatibility/SKILL.md delete mode 100644 test/e2e-runbook-hygiene.test.ts diff --git a/.changeset/identity-neutral-squad-templates.md b/.changeset/identity-neutral-squad-templates.md index 0b92fc3da..c319ac322 100644 --- a/.changeset/identity-neutral-squad-templates.md +++ b/.changeset/identity-neutral-squad-templates.md @@ -3,6 +3,8 @@ "@bradygaster/squad-sdk": patch --- -Make shipped Squad templates and issue-routing automation independent of the -repository's current agent cast so teams can be re-cast without stale names, -labels, or ownership rules. +Make shipped Squad templates, build inputs, CI policy, and issue-routing +automation independent of the repository's current team state so teams can be +re-cast without changing package artifacts or required checks. Product-owned +skills now have one exact canonical set, while live-team tests and stale +cast-specific configuration are removed. diff --git a/.dockerignore b/.dockerignore index 3492f3eae..79583ac11 100644 --- a/.dockerignore +++ b/.dockerignore @@ -9,7 +9,7 @@ docs/dist coverage .git .github -.squad/.scratch +.squad *.log *.tsbuildinfo .env diff --git a/.github/PR_REQUIREMENTS.md b/.github/PR_REQUIREMENTS.md index 28dd134e7..86274a574 100644 --- a/.github/PR_REQUIREMENTS.md +++ b/.github/PR_REQUIREMENTS.md @@ -90,8 +90,8 @@ Requirements are ordered by review flow. All marked **REQUIRED** must be satisfi - [ ] `docs/src/navigation.ts` updated if a new docs page is added - [ ] Docs build test updated if a new feature page is added (`test/docs-build.test.ts`, run via `npm test`) -**Enforced by**: Manual review by the current Quality and Lead role owners + -future automated checks in #104 +**Enforced by**: Manual review by the current Quality and Lead role owners + +future automated checks in #104 ### e) Package / Exports (REQUIRED for new modules — manual review) @@ -150,27 +150,27 @@ Add to PR description under a `## Waivers` section: - Item waived: (d) Documentation CHANGELOG entry - Reason: Security fix needs urgent release (CVE-2024-XXXXX) -- Approval by: [current Lead/Quality role owner, stated in a PR review comment] +- Approval by: [current Lead/Quality role owner, stated in a PR review comment] ``` ### Waiver Approval Authority -- **Lead role owner (architecture decisions)**: Internal refactors, - infrastructure, module reorganization -- **Quality role owner (quality decisions)**: Bug fixes, test improvements, - samples, CI changes +- **Lead role owner (architecture decisions)**: Internal refactors, + infrastructure, module reorganization +- **Quality role owner (quality decisions)**: Bug fixes, test improvements, + samples, CI changes - **Both**: External API changes, breaking changes ### Waiver Approval Examples | Scenario | Waivable Items | Approver | |----------|----------------|----------| -| Internal refactor (no API change) | Documentation, Samples | Lead role owner | -| Security fix | Documentation, Samples (with follow-up issue) | Quality role owner | -| Test infrastructure change | Documentation, Exports, Samples | Quality role owner | -| CI/GitHub Actions update | Documentation, Exports, Samples | Quality role owner | -| Documentation-only change | Code Quality (tests), Exports, Samples | Quality role owner | -| Non-breaking SDK bugfix | Samples | Quality role owner | +| Internal refactor (no API change) | Documentation, Samples | Lead role owner | +| Security fix | Documentation, Samples (with follow-up issue) | Quality role owner | +| Test infrastructure change | Documentation, Exports, Samples | Quality role owner | +| CI/GitHub Actions update | Documentation, Exports, Samples | Quality role owner | +| Documentation-only change | Code Quality (tests), Exports, Samples | Quality role owner | +| Non-breaking SDK bugfix | Samples | Quality role owner | ### Self-Waiving Is Not Allowed @@ -217,8 +217,8 @@ For migration PRs (> 20 files): include test output summary in the PR descriptio **Automation dependency**: 9 of 18 requirements are manual-only. Issue #104 (PR completeness gates) is the critical path to automated enforcement. Until #104 ships, this spec depends on reviewer discipline. -**Mitigation**: The Lead/Quality review checklist codifies consistent judgment. -Regular enforcement audits catch drift. +**Mitigation**: The Lead/Quality review checklist codifies consistent judgment. +Regular enforcement audits catch drift. ### 2. Theater Risk diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9a7e56aff..7e110a1f0 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -51,4 +51,4 @@ ### Waivers - + diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md index a2bf7384c..708edca2b 100644 --- a/.github/agents/squad.agent.md +++ b/.github/agents/squad.agent.md @@ -176,11 +176,11 @@ For each squad member with assigned issues, note them in the session context. Wh **The user should never see a blank screen while agents work.** Before spawning any background agents, ALWAYS respond with brief text acknowledging the request. Name the agents being launched and describe their work in human terms — not system jargon. This acknowledgment is REQUIRED, not optional. -- **Single agent:** `"Fenster's on it — looking at the error handling now."` +- **Single agent:** `"Runtime Engineer is on it — looking at the error handling now."` - **Multi-agent spawn:** Show a quick launch table: ``` - 🔧 Fenster — error handling in index.js - 🧪 Hockney — writing test cases + 🔧 Runtime Engineer — error handling in index.js + 🧪 Quality Engineer — writing test cases 📋 Scribe — logging session ``` @@ -214,9 +214,9 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use 👤 as fallback **Examples:** -- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"` -- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"` -- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` +- `name: "lead"`, `description: "🏗️ Lead: Reviewing architecture proposal"` +- `name: "runtime-engineer"`, `description: "🔧 Runtime Engineer: Refactoring auth module"` +- `name: "quality-engineer"`, `description: "🧪 Quality Engineer: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. @@ -234,7 +234,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa **NOT directives** (route normally): - Work requests ("build X", "fix Y", "test Z", "add a feature") - Questions ("how does X work?", "what did the team do?") -- Agent-directed tasks ("Ripley, refactor the API") +- Agent-directed tasks ("Runtime Engineer, refactor the API") **When you detect a directive:** @@ -288,7 +288,7 @@ The routing table determines **WHO** handles work. After routing, use Response M | Signal | Action | |--------|--------| -| Names someone ("Ripley, fix the button") | Spawn that agent | +| Names someone ("Experience Engineer, fix the button") | Spawn that agent | | Personal agent by name (user addresses a personal agent) | Route to personal agent in consult mode — they advise, project agent executes changes | | "Team" or multi-domain question | Spawn 2-3+ relevant agents in parallel, synthesize | | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) | @@ -654,7 +654,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without dispatching via the platform's tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Dispatch to the real agent and let it respond. 3. **Never skip dispatching (via `task` or `runSubagent`) for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "experience-engineer"` is right. `"General purpose task"` is wrong — `"Experience Engineer: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict. ### After Agent Work diff --git a/.github/workflows/squad-ci.yml b/.github/workflows/squad-ci.yml index 70e7e0a30..c99abf2fb 100644 --- a/.github/workflows/squad-ci.yml +++ b/.github/workflows/squad-ci.yml @@ -269,8 +269,9 @@ jobs: # require a changeset (or CHANGELOG update). The top-level templates/ tree is # the primary sync target of .squad-templates/ (see scripts/sync-templates.mjs) — # an append-only superset whose entire tree is governed squad scaffolding, not - # unrelated content. Agent charters under .squad/agents/ are likewise governed. - SDK_CLI_PATH_REGEX='^packages/squad-(sdk|cli)/src/|^packages/squad-(sdk|cli)/templates/|^\.squad-templates/|^templates/|^\.squad/agents/.+/charter\.md$' + # unrelated content. Live .squad/ team state is deliberately excluded: + # re-casting a team must not require a product package changeset. + SDK_CLI_PATH_REGEX='^packages/squad-(sdk|cli)/src/|^packages/squad-(sdk|cli)/templates/|^\.squad-templates/|^templates/' SDK_CLI_CHANGED=$(echo "$CHANGED" | grep -E "$SDK_CLI_PATH_REGEX" || true) if [ -z "$SDK_CLI_CHANGED" ]; then echo "✅ Not applicable (no SDK/CLI source or template changes)" >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/squad-heartbeat.yml b/.github/workflows/squad-heartbeat.yml index 48bea9d89..e2dea5bce 100644 --- a/.github/workflows/squad-heartbeat.yml +++ b/.github/workflows/squad-heartbeat.yml @@ -97,11 +97,11 @@ jobs: - name: Check triage script id: check-script run: | - if [ -f ".squad/templates/ralph-triage.js" ]; then + if [ -f "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" + echo "⚠️ product-owned ralph-triage.js not found" fi - name: Ralph — Smart triage @@ -109,7 +109,7 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - node .squad/templates/ralph-triage.js \ + node templates/ralph-triage.js \ --squad-dir .squad \ --output triage-results.json diff --git a/.github/workflows/squad-triage.yml b/.github/workflows/squad-triage.yml index 003c03be6..c3c88f3cb 100644 --- a/.github/workflows/squad-triage.yml +++ b/.github/workflows/squad-triage.yml @@ -124,10 +124,12 @@ jobs: } function findLead(teamMembers) { - return teamMembers.find(member => { + const hasRoleToken = (member, token) => { const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; - return roleWords.includes('lead'); - }); + return roleWords.includes(token); + }; + return teamMembers.find(member => hasRoleToken(member, 'lead')) || + teamMembers.find(member => hasRoleToken(member, 'architect')); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } @@ -160,7 +162,12 @@ jobs: const headers = tableCells(line).map(cell => cell.toLowerCase()); const workTypeIndex = headers.indexOf('work type'); - const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const routeIndex = headers.findIndex(header => + header === 'route to' || + header === 'agent' || + header === 'primary' || + header === 'primary agent' + ); const examplesIndex = headers.indexOf('examples'); if (workTypeIndex < 0 || routeIndex < 0) continue; @@ -173,16 +180,11 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinationNames = routeCell - .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) - .map(normalizeRouteDestination) - .filter(Boolean); - const destinations = teamMembers.filter(member => - destinationNames.includes(normalizeRouteDestination(member.name)) + const destinationName = normalizeRouteDestination(routeCell); + const member = teamMembers.find(candidate => + normalizeRouteDestination(candidate.name) === destinationName ); - for (const member of destinations) { - rules.push({ member, workType, examples }); - } + if (member) rules.push({ member, workType, examples }); } break; } @@ -191,28 +193,34 @@ jobs: } function routeScore(issueText, rule) { - const stopWords = new Set([ - 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', - 'work', 'owner', 'agent', 'support', 'management', + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', ]); - const phrases = rule.workType - .toLowerCase() - .split(/[,/&]+/) - .map(value => value.trim()) - .filter(value => value.length >= 4); - const keywords = `${rule.workType} ${rule.examples}` - .toLowerCase() - .match(/[a-z0-9@.+#-]+/g) || []; - - let score = phrases.reduce( - (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), - 0 - ); - for (const keyword of new Set(keywords)) { - if (keyword.length < 3 || stopWords.has(keyword)) continue; - if (issueText.includes(keyword)) score++; + + function tokens(value) { + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + } + + function containsPhrase(haystack, needle) { + if (needle.length === 0 || needle.length > haystack.length) return false; + return haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); } - return score; + + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter(token => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.examples.split(/[,;]+/)] + .flatMap(phrase => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + + return rawPhrases.reduce((best, phrase) => { + const phraseTokens = tokens(phrase); + if (!containsPhrase(issueTokens, phraseTokens)) return best; + const specificity = phraseTokens.length * 100; + return Math.max(best, specificity); + }, 0); } function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { @@ -225,7 +233,16 @@ jobs: return { member: lead, workType: null }; } - const best = scoredRoutes[0]; + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter(candidate => candidate.score === bestScore); + const bestMembers = new Set(bestRoutes.map(candidate => + normalizeRouteDestination(candidate.rule.member.name) + )); + if (bestMembers.size !== 1) { + return { member: lead, workType: null }; + } + + const best = bestRoutes[0]; return { member: best.rule.member, workType: best.rule.workType }; } diff --git a/.squad-templates/machine-capabilities.md b/.squad-templates/machine-capabilities.md index b770fd04b..65f3c478a 100644 --- a/.squad-templates/machine-capabilities.md +++ b/.squad-templates/machine-capabilities.md @@ -47,7 +47,7 @@ squad watch --interval 5 Ralph will log skipped issues: ``` ⏭️ Skipping #42 "Train ML model" — missing: gpu -✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule) +✓ Triaged #43 "Fix CSS layout" → Experience Engineer (routing-rule) ``` ## How It Works diff --git a/.squad-templates/model-selection-reference.md b/.squad-templates/model-selection-reference.md index 43eba9e5e..ffc51eb71 100644 --- a/.squad-templates/model-selection-reference.md +++ b/.squad-templates/model-selection-reference.md @@ -85,11 +85,11 @@ If you've exhausted the fallback chain and reached the platform default fallback When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-5) — refactoring auth module -🎨 Redfoot (gpt-5.6-sol · vision) — designing color system +🔧 Runtime Engineer (claude-sonnet-5) — refactoring auth module +🎨 Experience Engineer (gpt-5.6-sol · vision) — designing color system 📋 Scribe (gpt-5.6-luna · fast) — logging session -⚡ Keaton (gpt-5.6-sol · bumped for architecture) — reviewing proposal -📝 McManus (gpt-5.6-luna · fast) — updating docs +⚡ Lead (gpt-5.6-sol · bumped for architecture) — reviewing proposal +📝 Docs Engineer (gpt-5.6-luna · fast) — updating docs ``` Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name. diff --git a/.squad-templates/notes-protocol.md b/.squad-templates/notes-protocol.md index 5a1d03a5f..800066f80 100644 --- a/.squad-templates/notes-protocol.md +++ b/.squad-templates/notes-protocol.md @@ -28,11 +28,8 @@ Each agent writes to its own namespace to prevent conflicts: | Namespace | Owner | Purpose | |-----------|-------|---------| -| `refs/notes/squad/data` | Data | Architecture decisions, implementation choices | -| `refs/notes/squad/worf` | Worf | Security reviews, vulnerability assessments | -| `refs/notes/squad/seven` | Seven | Documentation quality, API contract decisions | +| `refs/notes/squad/{agent-id}` | Current agent | Agent-owned decisions and implementation context | | `refs/notes/squad/ralph` | Ralph | Work-round progress, task-state annotations | -| `refs/notes/squad/q` | Q | Devil's advocate findings, risk assessments | | `refs/notes/squad/research` | Any agent | Research notes that should survive branch deletion | | `refs/notes/squad/review` | Any agent | Code review context (mirrors Gerrit's pattern) | @@ -47,7 +44,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision | research | review | progress | security", "content": "..." @@ -58,7 +55,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision", "decision": "Use JWT RS256 for auth middleware", @@ -76,7 +73,7 @@ Set `"promote_to_permanent": true` to signal Ralph to copy this to ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "research", "topic": "JWT vs session tokens", diff --git a/.squad-templates/ralph-triage.js b/.squad-templates/ralph-triage.js index 863da3d7d..2e05eb971 100644 --- a/.squad-templates/ralph-triage.js +++ b/.squad-templates/ralph-triage.js @@ -58,11 +58,19 @@ function normalizeEol(content) { function slugify(text) { return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function parseRoutingRules(routingMd) { - const table = parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i); + const table = + parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i) || + parseTableSection(routingMd, /^##\s*routing\s*table\b/i); if (!table) return []; const workTypeIndex = findColumnIndex(table.headers, ['work type', 'type']); - const agentIndex = findColumnIndex(table.headers, ['agent', 'route to', 'route']); + const agentIndex = findColumnIndex(table.headers, [ + 'agent', + 'route to', + 'route', + 'primary agent', + 'primary', + ]); const examplesIndex = findColumnIndex(table.headers, ['examples', 'example']); if (workTypeIndex < 0 || agentIndex < 0) return []; @@ -564,4 +572,10 @@ if (require.main === module) { }); } -module.exports = { resolveGithubApiBase }; +module.exports = { + parseModuleOwnership, + parseRoster, + parseRoutingRules, + resolveGithubApiBase, + triageIssue, +}; diff --git a/.squad-templates/skills/agent-collaboration/SKILL.md b/.squad-templates/skills/agent-collaboration/SKILL.md new file mode 100644 index 000000000..054463cf8 --- /dev/null +++ b/.squad-templates/skills/agent-collaboration/SKILL.md @@ -0,0 +1,42 @@ +--- +name: "agent-collaboration" +description: "Standard collaboration patterns for all squad agents — worktree awareness, decisions, cross-agent communication" +domain: "team-workflow" +confidence: "high" +source: "extracted from charter boilerplate — identical content in 18+ agent charters" +--- + +## Context + +Every agent on the team follows identical collaboration patterns for worktree awareness, decision recording, and cross-agent communication. These were previously duplicated in every charter's Collaboration section (~300 bytes × 18 agents = ~5.4KB of redundant context). Now centralized here. + +The coordinator's spawn prompt already instructs agents to read decisions.md and their history.md. This skill adds the patterns for WRITING decisions and requesting help. + +## Patterns + +### Worktree Awareness +Use the `TEAM ROOT` path provided in your spawn prompt. All `.squad/` paths are relative to this root. If TEAM ROOT is not provided (rare), run `git rev-parse --show-toplevel` as fallback. Never assume CWD is the repo root. + +### Decision Recording +After making a decision that affects other team members, write it to: +`.squad/decisions/inbox/{your-name}-{brief-slug}.md` + +Format: +``` +### {date}: {decision title} +**By:** {Your Name} +**What:** {the decision} +**Why:** {rationale} +``` + +### Cross-Agent Communication +If you need another team member's input, say so in your response. The coordinator will bring them in. Don't try to do work outside your domain. + +### Reviewer Protocol +If you have reviewer authority and reject work: the original author is locked out from revising that artifact. A different agent must own the revision. State who should revise in your rejection response. + +## Anti-Patterns +- Don't read all agent charters — you only need your own context + decisions.md +- Don't write directly to `.squad/decisions.md` — always use the inbox drop-box +- Don't modify other agents' history.md files — that's Scribe's job +- Don't assume CWD is the repo root — always use TEAM ROOT diff --git a/.squad-templates/skills/agent-conduct/SKILL.md b/.squad-templates/skills/agent-conduct/SKILL.md new file mode 100644 index 000000000..df87276a0 --- /dev/null +++ b/.squad-templates/skills/agent-conduct/SKILL.md @@ -0,0 +1,24 @@ +--- +name: "agent-conduct" +description: "Shared hard rules enforced across all squad agents" +domain: "team-governance" +confidence: "high" +source: "reskill extraction — Product Isolation Rule and Peer Quality Check appeared in all 20 agent charters" +--- + +## Context + +Every squad agent must follow these two hard rules. They were previously duplicated in every charter. Now they live here as a shared skill, loaded once. + +## Patterns + +### Product Isolation Rule (hard rule) +Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to cast-specific agent names in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot"). + +### Peer Quality Check (hard rule) +Before finishing work, verify your changes don't break existing tests. Run the test suite for files you touched. If CI has been failing, check your changes aren't contributing to the problem. When you learn from mistakes, update your history.md. + +## Anti-Patterns +- Don't hardcode dev team agent names in product code or tests +- Don't skip test verification before declaring work done +- Don't ignore pre-existing CI failures that your changes may worsen diff --git a/.squad-templates/skills/architectural-proposals/SKILL.md b/.squad-templates/skills/architectural-proposals/SKILL.md new file mode 100644 index 000000000..4128ff096 --- /dev/null +++ b/.squad-templates/skills/architectural-proposals/SKILL.md @@ -0,0 +1,151 @@ +--- +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:** Product Lead (product direction), Runtime Engineer (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/.squad-templates/skills/ci-validation-gates/SKILL.md b/.squad-templates/skills/ci-validation-gates/SKILL.md new file mode 100644 index 000000000..9c120ac1d --- /dev/null +++ b/.squad-templates/skills/ci-validation-gates/SKILL.md @@ -0,0 +1,84 @@ +--- +name: "ci-validation-gates" +description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22" +domain: "ci-cd" +confidence: "high" +source: "earned knowledge from the v0.8.22 release incident" +--- + +## Context + +CI workflows must be defensive. These patterns were learned from the v0.8.22 release incident where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. The reusable lessons are centralized here rather than tied to individual agent charters. + +## Patterns + +### Semver Validation Gate +Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them. + +```yaml +- name: Validate semver + run: | + VERSION="${{ github.event.release.tag_name }}" + VERSION="${VERSION#v}" + if ! npx semver "$VERSION" > /dev/null 2>&1; then + echo "❌ Invalid semver: $VERSION" + echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid." + exit 1 + fi + echo "✅ Valid semver: $VERSION" +``` + +### NPM Token Type Verification +NPM_TOKEN MUST be an Automation token, not a User token with 2FA: +- User tokens require OTP — CI can't provide it → EOTP error +- Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation +- Verify before first publish in any workflow + +### Retry Logic for npm Registry Propagation +npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable. +- Propagation: typically 5-30s, up to 2min in rare cases +- All verify steps: 5 attempts, 15-second intervals +- Log each attempt: "Attempt 1/5: Checking package..." +- Exit loop on success, fail after max attempts + +```yaml +- name: Verify package (with retry) + run: | + MAX_ATTEMPTS=5 + WAIT_SECONDS=15 + for attempt in $(seq 1 $MAX_ATTEMPTS); do + echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..." + if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then + echo "✅ Package verified" + exit 0 + fi + [ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS + done + echo "❌ Failed to verify after $MAX_ATTEMPTS attempts" + exit 1 +``` + +### Draft Release Detection +Draft releases don't emit `release: published` event. Workflows MUST: +- Trigger on `release: published` (NOT `created`) +- If using workflow_dispatch: verify release is published via GitHub API before proceeding + +### Build Script Protection +Set `SKIP_BUILD_BUMP=1` (or `$env:SKIP_BUILD_BUMP = "1"` on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions. + +## Known Failure Modes (v0.8.22 Incident) + +| # | What Happened | Root Cause | Prevention | +|---|---------------|-----------|------------| +| 1 | 4-part version published, npm mangled it | No semver validation gate | `npx semver` check before every publish | +| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only | +| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals | +| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases | +| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 | + +## Anti-Patterns +- ❌ Publishing without semver validation gate +- ❌ Single-shot verification without retry +- ❌ Hard-coded secrets in workflows +- ❌ Silent CI failures — every error needs actionable output with remediation +- ❌ Assuming npm publish is instantly queryable diff --git a/.squad-templates/skills/cli-wiring/SKILL.md b/.squad-templates/skills/cli-wiring/SKILL.md new file mode 100644 index 000000000..5b315b02d --- /dev/null +++ b/.squad-templates/skills/cli-wiring/SKILL.md @@ -0,0 +1,47 @@ +# Skill: CLI Command Wiring + +**Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. + +## Checklist — Adding a New CLI Command + +1. **Create command file** in `packages/squad-cli/src/cli/commands/.ts` + - Export a `run(cwd, options)` async function (or class with static methods for utility modules) + +2. **Add routing block** in `packages/squad-cli/src/cli-entry.ts` inside `main()`: + ```ts + if (cmd === '') { + const { run } = await import('./cli/commands/.js'); + // parse args, call function + await run(process.cwd(), options); + return; + } + ``` + +3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`): + ```ts + console.log(` ${BOLD}${RESET} `); + console.log(` Usage: [flags]`); + ``` + +4. **Verify both exist** — the recurring bug is doing step 1 but missing steps 2-3. + +## Wiring Patterns by Command Type + +| Type | Example | How to wire | +|------|---------|-------------| +| Standard command | `export.ts`, `build.ts` | `run*()` function, parse flags from `args` | +| Placeholder command | `loop`, `cast` (alias: `hire`) | Inline in cli-entry.ts, prints pending message | +| Utility/check module | `rc-tunnel.ts`, `copilot-bridge.ts` | Wire as diagnostic check (e.g., `isDevtunnelAvailable()`) | +| Subcommand of another | `init-remote.ts` | Already used inside parent + standalone alias | + +## Common Import Pattern + +```ts +import { BOLD, RESET, DIM, RED, GREEN, YELLOW } from './cli/core/output.js'; +``` + +Use dynamic `await import()` for command modules to keep startup fast (lazy loading). + +## History + +- **#237 / PR #244:** 4 commands wired (rc, copilot-bridge, init-remote, rc-tunnel). aspire, link, loop, cast (née hire) were already present. diff --git a/.squad-templates/skills/client-compatibility/SKILL.md b/.squad-templates/skills/client-compatibility/SKILL.md new file mode 100644 index 000000000..62e6b09ab --- /dev/null +++ b/.squad-templates/skills/client-compatibility/SKILL.md @@ -0,0 +1,89 @@ +--- +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: "...Runtime Engineer charter + task..." }) +runSubagent({ prompt: "...Quality Engineer 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/.squad-templates/skills/coordinator-init-mode/SKILL.md b/.squad-templates/skills/coordinator-init-mode/SKILL.md new file mode 100644 index 000000000..46585cd42 --- /dev/null +++ b/.squad-templates/skills/coordinator-init-mode/SKILL.md @@ -0,0 +1,99 @@ +--- +name: "coordinator-init-mode" +description: "The complete two-phase Init Mode protocol the Squad coordinator runs when no team exists yet in the current repo. Phase 1 = propose the team (no files created, wait for user confirm). Phase 2 = create .squad/ scaffolding, casting state, .gitattributes for merge drivers, and the always-on built-ins (Scribe, Ralph, Rai, Fact Checker). Loaded on demand when the coordinator detects no .squad/team.md exists." +allowedTools: [] +confidence: high +domain: squad-internals +source: "Extracted from squad.agent.md as part of the slimming effort (bradygaster/squad#1308). Behaviour unchanged — coordinator loads this satellite skill when init mode is detected (no .squad/team.md present)." +--- + +> **Load this skill when:** you detect that no `.squad/team.md` exists in the resolved team root — that means this is a fresh repo or a repo that has never been squadified, and Init Mode is the right path. The short stub in `squad.agent.md` tells you to load this skill; the full two-phase protocol lives here. +> +> **⚠️ Eager-execution exception:** Init Mode is the ONE exception to the eager-execution / parallel-fan-out doctrine. Phase 1 MUST end with a user confirmation before any file is created. Do not bypass. + +## Phase 1: Propose the Team + +No team exists yet. **Propose one — but DO NOT create any files until the user confirms.** + +1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey {user}, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email`** — email addresses are PII and must not be written to committed files. +2. Ask: *"What are you building? (language, stack, what it does)"* +3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see the canonical Casting reference at `.squad/templates/casting-reference.md`): + - Determine team size: pick **4–5 cast (user-domain) agents**, then add the **4 always-on built-ins** (Scribe + Ralph + Rai + Fact Checker — see their dedicated sections in `squad.agent.md`). A typical fresh squad has **8–9 total roster entries**, not 4–5. + - Determine assignment shape from the user's project description. + - Derive resonance signals from the session and repo context. + - Select a universe. Allocate character names from that universe. + - Scribe is always "Scribe" — exempt from casting. + - Ralph is always "Ralph" — exempt from casting. + - Rai is always "Rai" — exempt from casting. + - Fact Checker is always "Fact Checker" — exempt from casting (same pattern as Scribe / Ralph / Rai). +4. Propose the team with their cast names. Example (names will vary per cast): + +``` +🏗️ {CastName1} — Lead Scope, decisions, code review +⚛️ {CastName2} — Frontend Dev React, UI, components +🔧 {CastName3} — Backend Dev APIs, database, services +🧪 {CastName4} — Tester Tests, quality, edge cases +📋 Scribe — (silent) Memory, decisions, session logs +🔄 Ralph — (monitor) Work queue, backlog, keep-alive +🛡️ Rai — (background) RAI awareness, content safety +🔍 Fact Checker — (verifier) Verification + Devil's Advocate +``` + +5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu. + + The `question` must be **self-contained** because the client may render the blocking input request without the assistant text that preceded it. + + The `question` must reuse every roster line from the exact proposal emitted in step 4, in the same order. Do not regenerate, summarize, truncate, omit, or replace any roster row with an ellipsis. Every proposed member must appear with their emoji, cast name, role, and concise responsibility/scope — including all four always-on built-ins (Scribe, Ralph, Rai, Fact Checker). + + Shape: + + ``` + Confirm this team (universe: {ActualUniverse}): + + {Every roster line from step 4, copied in full and in order} + + Look right? + ``` + + Never use a bare "Look right?" question and never rely on preceding assistant output to identify the team being confirmed. + + - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]` + +**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.** + +--- + +## Phase 2: Create the Team + +**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes"). + +> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. **Do NOT enter Phase 2 until the user confirms.** + +6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: `team.md`, `routing.md`, `ceremonies.md`, `decisions.md`, `decisions/inbox/`, `casting/`, `agents/`, `orchestration-log/`, `skills/`, `log/`, `rai/`). + +**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id). + +**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing. Rai's charter is seeded from the `Rai-charter.md` template, and `.squad/rai/policy.md` is seeded from `rai-policy.md`. Fact Checker's charter is seeded from `fact-checker-charter.md` and `.squad/fact-checker/policy.md` is seeded from `fact-checker-policy.md`. + +**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks. + +**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches: + +``` +.squad/decisions.md merge=union +.squad/agents/*/history.md merge=union +.squad/log/** merge=union +.squad/orchestration-log/** merge=union +.squad/rai/audit-trail.md merge=union +``` + +The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically. + +7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"* + +8. **Post-setup input sources** (optional — ask after team is created, not during casting): + - **PRD/spec:** *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow. + - **GitHub issues:** *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow. + - **Human members:** *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section. + - **Copilot agent:** *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment. + - These are additive. **Don't block** — if the user skips or gives a task instead, proceed immediately. diff --git a/.squad-templates/skills/coordinator-response-mode/SKILL.md b/.squad-templates/skills/coordinator-response-mode/SKILL.md new file mode 100644 index 000000000..4dff3b800 --- /dev/null +++ b/.squad-templates/skills/coordinator-response-mode/SKILL.md @@ -0,0 +1,97 @@ +--- +name: "coordinator-response-mode" +description: "Selecting WHO handles work is the Routing table; selecting HOW they handle it (Direct, Lightweight, Standard, Full) is Response Mode. This skill contains the complete decision table, exemplar prompts for each mode, the Lightweight spawn template, and the upgrade rules. Squad coordinator loads this on demand once routing has identified the agent — to pick the right ceremony level for the task." +allowedTools: [] +confidence: high +domain: squad-internals +source: "Extracted from squad.agent.md as part of the slimming effort (bradygaster/squad#1308). Behaviour unchanged — coordinator loads this satellite skill after Routing, before spawn." +--- + +> **Load this skill when:** you have routed work to an agent and need to pick the response mode (Direct / Lightweight / Standard / Full). The 1-line stub in `squad.agent.md` is for awareness; this skill is the full decision table + templates. + +## Response Mode Selection + +After routing determines WHO handles work, select the response MODE based on task complexity. **Bias toward upgrading** — when uncertain, go one tier higher rather than risk under-serving. + +| Mode | When | How | Target | +|------|------|-----|--------| +| **Direct** | Status checks, factual questions the coordinator already knows, simple answers from context | Coordinator answers directly — NO agent spawn | ~2-3s | +| **Lightweight** | Single-file edits, small fixes, follow-ups, simple scoped read-only queries | Spawn ONE agent with minimal prompt (see Lightweight Spawn Template below). Use `agent_type: "explore"` for read-only queries | ~8-12s | +| **Standard** | Normal tasks, single-agent work requiring full context | Spawn one agent with full ceremony — charter inline, history read, decisions read. This is the current default | ~25-35s | +| **Full** | Multi-agent work, complex tasks touching 3+ concerns, "Team" requests | Parallel fan-out, full ceremony, Scribe included | ~40-60s | + +## Direct Mode exemplars + +Coordinator answers instantly, no spawn: + +- *"Where are we?"* → Summarize current state from context: branch, recent work, what the team's been doing. A user favorite — make it instant. +- *"How many tests do we have?"* → Run a quick command, answer directly. +- *"What branch are we on?"* → `git branch --show-current`, answer directly. +- *"Who's on the team?"* → Answer from `team.md` already in context. +- *"What did we decide about X?"* → Answer from `decisions.md` already in context. + +## Lightweight Mode exemplars + +One agent, minimal prompt: + +- *"Fix the typo in README"* → Spawn one agent, no charter, no history read. +- *"Add a comment to line 42"* → Small scoped edit, minimal context needed. +- *"What does this function do?"* → `agent_type: "explore"` (Haiku model, fast). +- Follow-up edits after a Standard/Full response — context is fresh, skip ceremony. + +## Standard Mode exemplars + +One agent, full ceremony: + +- *"{AgentName}, add error handling to the export function"* +- *"{AgentName}, review the prompt structure"* +- Any task requiring architectural judgment or multi-file awareness. + +## Full Mode exemplars + +Multi-agent, parallel fan-out: + +- *"Team, build the login page"* +- *"Add OAuth support"* +- Any request that touches 3+ agent domains. + +## Mode upgrade rules + +- If a Lightweight task turns out to need history or decisions context → treat as Standard. +- If uncertain between Direct and Lightweight → choose Lightweight. +- If uncertain between Lightweight and Standard → choose Standard. +- **Never downgrade mid-task.** If you started Standard, finish Standard. + +## Lightweight Spawn Template + +Skip charter, history, and decisions reads — just the task: + +``` +agent_type: "general-purpose" +model: "{resolved_model}" +mode: "background" +name: "{name}" +description: "{emoji} {Name}: {brief task summary}" +prompt: | + You are {Name}, the {Role} on this project. + TEAM ROOT: {team_root} + CURRENT_DATETIME: + WORKTREE_PATH: {worktree_path} + WORKTREE_MODE: {true|false} + **Requested by:** {current user name} + + {% if WORKTREE_MODE %} + **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches. + {% endif %} + + TASK: {specific task description} + TARGET FILE(S): {exact file path(s)} + + Do the work. Keep it focused. + If you made a meaningful decision, persist it with `memory.write` (class: `decision`) when available, or fall back to `squad_decide` / `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`. Do not run git notes, switch branches, or write mutable `.squad/` state by hand. + + ⚠️ OUTPUT: Report outcomes in human terms. Never expose tool internals or SQL. + ⚠️ 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}. CURRENT_DATETIME: — {question} TEAM ROOT: {team_root}"` diff --git a/.squad-templates/skills/coordinator-source-of-truth/SKILL.md b/.squad-templates/skills/coordinator-source-of-truth/SKILL.md new file mode 100644 index 000000000..3a992ba0a --- /dev/null +++ b/.squad-templates/skills/coordinator-source-of-truth/SKILL.md @@ -0,0 +1,45 @@ +--- +name: "coordinator-source-of-truth" +description: "The complete file-by-file source-of-truth hierarchy for Squad: which files are authoritative, which are derived/append-only, who may write each one, who may read each one, and the precedence rules when they conflict. Squad coordinator loads this on demand when it needs to resolve a write conflict, decide where a piece of state belongs, or answer a 'who owns this file' question." +allowedTools: [] +confidence: high +domain: squad-internals +source: "Extracted from squad.agent.md as part of the slimming effort (bradygaster/squad#1308). Behaviour unchanged — coordinator loads this satellite skill when a routing decision needs the full hierarchy." +--- + +> **Load this skill when:** the coordinator (or any agent) needs to resolve a "where does this state belong?" or "who is allowed to write this file?" question — e.g., when about to write `.squad/decisions.md`, when reviewing whether an agent broke the append-only rule, when answering a user question about Squad's file layout, or when adjudicating a conflict between two files. The short summary in `squad.agent.md` is for routing; this skill is the full reference. + +## State backend note + +Files below marked as **"Derived / append-only"** are **mutable state** — agents access them with runtime state tools (`squad_state_read`, `squad_state_write`, `squad_state_append`, `squad_state_delete`, `squad_state_list`). The runtime decides whether the configured backend stores them on disk, git-native state, or an external provider. Files marked as **"Authoritative"** are **static config** and always live on disk regardless of backend. + +## File hierarchy + +| File | Status | Who May Write | Who May Read | +|------|--------|---------------|--------------| +| `.github/agents/squad.agent.md` | **Authoritative governance.** All roles, handoffs, gates, and enforcement rules. | Repo maintainer (human) | Squad (Coordinator) | +| `.squad/decisions.md` | **Authoritative decision ledger.** Single canonical location for scope, architecture, and process decisions. | Squad (Coordinator) — append only | All agents | +| `.squad/team.md` | **Authoritative roster.** Current team composition. | Squad (Coordinator) | All agents | +| `.squad/routing.md` | **Authoritative routing.** Work assignment rules. | Squad (Coordinator) | Squad (Coordinator) | +| `.squad/ceremonies.md` | **Authoritative ceremony config.** Definitions, triggers, and participants for team ceremonies. | Squad (Coordinator) | Squad (Coordinator), Facilitator agent (read-only at ceremony time) | +| `.squad/casting/policy.json` | **Authoritative casting config.** Universe allowlist and capacity. | Squad (Coordinator) | Squad (Coordinator) | +| `.squad/casting/registry.json` | **Authoritative name registry.** Persistent agent-to-name mappings. | Squad (Coordinator) | Squad (Coordinator) | +| `.squad/casting/history.json` | **Derived / append-only.** Universe usage history and assignment snapshots. | Squad (Coordinator) — append only | Squad (Coordinator) | +| `.squad/agents/{name}/charter.md` | **Authoritative agent identity.** Per-agent role and boundaries. | Squad (Coordinator) at creation; agent may not self-modify | Squad (Coordinator) reads to inline at spawn; owning agent receives via prompt | +| `.squad/agents/{name}/history.md` | **Derived / append-only.** Personal learnings. Never authoritative for enforcement. | Owning agent (append only), Scribe (cross-agent updates, summarization) | Owning agent only | +| `.squad/agents/{name}/history-archive.md` | **Derived / append-only.** Archived history entries. Preserved for reference. | Scribe | Owning agent (read-only) | +| `.squad/orchestration-log/` | **Derived / append-only.** Agent routing evidence. Never edited after write. | Scribe | All agents (read-only) | +| `.squad/log/` | **Derived / append-only.** Session logs. Diagnostic archive. Never edited after write. | Scribe | All agents (read-only) | +| `.squad/templates/` | **Reference.** Format guides for runtime files. Not authoritative for enforcement. | Squad (Coordinator) at init | Squad (Coordinator) | +| `.squad/rai/policy.md` | **Authoritative RAI policy.** Check categories, terminology standards, and opt-out rules. | Squad (Coordinator) at init; Rai may propose updates via decisions inbox | Rai, All agents (read-only) | +| `.squad/rai/audit-trail.md` | **Derived / append-only.** RAI review evidence log. Redacted — never contains raw secrets or harmful content. | Rai (append only) | Rai, Squad (Coordinator) | +| `.squad/fact-checker/policy.md` | **Authoritative verification + Devil's Advocate policy.** Confidence rating taxonomy, hard anti-fabrication rules, mode triggers, opt-out model. | Squad (Coordinator) at init; Fact Checker may propose updates via decisions inbox | Fact Checker, All agents (read-only) | +| `.squad/fact-checker/audit-trail.md` | **Derived / append-only.** Verification verdicts + DA brief evidence log. Succinct — verdict + citation, never raw source material. | Fact Checker (append only) | Fact Checker, Squad (Coordinator) | +| `.squad/plugins/marketplaces.json` | **Authoritative plugin config.** Registered marketplace sources. | Squad CLI (`squad plugin marketplace`) | Squad (Coordinator) | + +## Rules + +1. **If `squad.agent.md` and any other file conflict, `squad.agent.md` wins.** It is the only file with hard governance authority. +2. **Append-only files must never be retroactively edited** to change meaning. They are diagnostic and audit-trail material. Corrections go in a new entry that references the prior one. +3. **Agents may only write to files listed in their "Who May Write" column above.** Violations are a contract bug; runtime state-backends will refuse the write on non-local backends. +4. **Non-coordinator agents may propose decisions** in their responses, but only Squad (Coordinator) records accepted decisions in `.squad/decisions.md`. diff --git a/.squad-templates/skills/cross-machine-coordination/SKILL.md b/.squad-templates/skills/cross-machine-coordination/SKILL.md new file mode 100644 index 000000000..d9242c44b --- /dev/null +++ b/.squad-templates/skills/cross-machine-coordination/SKILL.md @@ -0,0 +1,442 @@ +--- +name: "cross-machine-coordination" +description: "Enables squad agents on different machines to share work via git-based task queuing" +domain: "orchestration" +confidence: "medium" +source: "manual" +--- + +# Skill: Cross-Machine Coordination Pattern + +**Skill ID:** `cross-machine-coordination` +**Owner:** Ralph (Work Monitor) +**Squad Integration:** All agents +**Status:** Specification (ready for implementation) + +--- + +## Overview + +Enables squad agents running on different machines (laptop, DevBox, Azure VM) to securely share work, coordinate execution, and pass results without manual intervention. + +**Pattern:** Git-based task queuing + GitHub Issues supplement + +--- + +## Usage + +### For Task Sources (Orchestrating Machine) + +**To assign work to DevBox:** + +```bash +# Create task file +cat > .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-voice-clone.yaml << 'EOF' +id: gpu-voice-clone-001 +source_machine: laptop-machine +target_machine: devbox +priority: high +created_at: 2026-03-14T15:30:00Z +task_type: gpu_workload +payload: + command: "python scripts/voice-clone.py --input voice.wav --output cloned.wav" + expected_duration_min: 15 + resources: + gpu: true + memory_gb: 8 +status: pending +EOF + +# Commit & push +git add .squad/cross-machine/tasks/ +git commit -m "Cross-machine task: GPU voice cloning [squad:machine-devbox]" +git push origin main +``` + +Ralph on DevBox will: +1. Pull the task on next cycle (5-10 min) +2. Validate schema & command whitelist +3. Execute the GPU workload +4. Write result to `.squad/cross-machine/results/gpu-voice-clone-001.yaml` +5. Commit & push the result + +--- + +### For Task Executors (DevBox, Azure VMs) + +Ralph automatically watches `.squad/cross-machine/tasks/` for work targeted at this machine. + +**On each cycle (5-10 min):** + +```python +# Pseudo-code (Ralph implementation) +1. git pull origin main +2. Load all .yaml files in .squad/cross-machine/tasks/ +3. Filter for status=pending AND target_machine=HOSTNAME +4. For each task: + a. Validate schema (must have: id, source_machine, target_machine, payload) + b. Validate command against whitelist + c. Execute task (with timeout) + d. Write result to .squad/cross-machine/results/{id}.yaml + e. Commit & push result +``` + +--- + +### For Urgent/Ad-Hoc Tasks + +**Use GitHub Issues with `squad:machine-{name}` label:** + +```bash +# Create issue +gh issue create \ + --title "GPU: Clone voice profile from sample.wav" \ + --body "Execute voice cloning on DevBox. Input: /path/to/voice-input.wav" \ + --label "squad:machine-devbox" \ + --label "urgent" +``` + +Ralph on DevBox will: +1. Detect issue with `squad:machine-devbox` label +2. Parse task from issue body +3. Execute task +4. Comment with result +5. Close issue + +--- + +## File Formats + +### Task File (YAML) + +**Location:** `.squad/cross-machine/tasks/{timestamp}-{machine}-{task-id}.yaml` + +**Required Fields:** +```yaml +id: {task-id} # Unique identifier (alphanumeric + dash) +source_machine: {hostname} # Where task was created +target_machine: {hostname} # Where task will execute +priority: high|normal|low # Execution priority +created_at: 2026-03-14T15:30:00Z # ISO 8601 timestamp +task_type: gpu_workload|script|... # Category +payload: + command: "..." # Shell command to execute + expected_duration_min: 15 # Timeout (minutes) + resources: + gpu: true|false + memory_gb: 8 + cpu_cores: 4 +status: pending|executing|completed|failed +``` + +**Optional Fields:** +```yaml +description: "Human-readable task description" +timeout_override_min: 120 # Override default timeout +retry_count: 3 # Retry failed tasks +``` + +### Result File (YAML) + +**Location:** `.squad/cross-machine/results/{task-id}.yaml` + +```yaml +id: {task-id} # Links back to task +target_machine: devbox # Executed on +completed_at: 2026-03-14T15:45:00Z # When it finished +status: completed|failed|timeout # Outcome +exit_code: 0 # Shell exit code +stdout: "..." # Captured output +stderr: "..." # Captured errors +duration_seconds: 900 # How long it took +artifacts: + - path: "/path/to/artifacts/..." # Location of results + type: audio|text|model|... + size_mb: 2.5 +``` + +--- + +## Security Model + +### Validation Pipeline + +All tasks go through: + +1. **Schema Validation** + - YAML structure matches spec + - Required fields present + - No unexpected fields (reject) + +2. **Command Whitelist** + - Only approved commands allowed + - Path validation (no `../../` escapes) + - Environment variable sanitization + - No inline shell operators (`&&`, `|`, `>`) + +3. **Resource Limits** + - Timeout enforced (default: 60 min) + - Memory cap: 16GB (adjustable) + - CPU threads: 4 (adjustable) + - Disk write: 100GB (adjustable) + +4. **Execution Isolation** + - Runs as unprivileged user + - Temp directory cleaned after execution + - Network access: read-only (no outbound writes) + +5. **Audit Trail** + - All executions logged to git + - Commit signed with Ralph's key + - Result stored immutably + +### Threat Mitigations + +| Threat | Mitigation | +|--------|-----------| +| **Malicious task injection** | Branch protection + PR review before merge | +| **Credential leakage** | Pre-commit secret scan + environment scrubbing | +| **Resource exhaustion** | Timeout + memory limits | +| **Code injection** | Command whitelist + no shell evaluation | +| **Result tampering** | Git commit history is immutable | + +--- + +## Configuration + +Ralph reads config from `.squad/config.json`: + +```json +{ + "cross_machine": { + "enabled": true, + "poll_interval_seconds": 300, + "this_machine": "devbox", + "max_concurrent_tasks": 2, + "task_timeout_minutes": 60, + "command_whitelist": [ + "python scripts/voice-clone.py", + "python scripts/data-process.py", + "bash scripts/cleanup.sh" + ], + "result_ttl_days": 30 + } +} +``` + +--- + +## Examples + +### Example 1: GPU Voice Cloning (Laptop → DevBox) + +**1. Laptop creates task:** + +```yaml +# .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-001.yaml +id: gpu-voice-clone-001 +source_machine: laptop-machine +target_machine: devbox +priority: high +created_at: 2026-03-14T15:30:00Z +task_type: gpu_workload +payload: + command: "python scripts/voice-clone.py --input voice.wav --output cloned.wav" + expected_duration_min: 15 + resources: + gpu: true + memory_gb: 8 +status: pending +``` + +**2. Laptop commits & pushes:** + +```bash +git add .squad/cross-machine/tasks/ +git commit -m "Task: GPU voice cloning [squad:machine-devbox]" +git push origin main +``` + +**3. DevBox Ralph (5 min later):** + +``` +[Ralph Watch Cycle] +- Pulled origin/main +- Detected: gpu-voice-clone-001 (status: pending, target: devbox) +- Validation: ✅ Schema OK, command whitelisted +- Executing: python scripts/voice-clone.py ... +- [15 minutes of processing] +- Completed: exit code 0 +- Writing result... +- Committing & pushing... +``` + +**4. Laptop Ralph (next cycle) sees result:** + +```yaml +# .squad/cross-machine/results/gpu-voice-clone-001.yaml +id: gpu-voice-clone-001 +target_machine: devbox +completed_at: 2026-03-14T15:45:00Z +status: completed +exit_code: 0 +stdout: "Voice cloning completed. Output written to /tmp/cloned.wav" +stderr: "" +duration_seconds: 900 +artifacts: + - path: "/path/to/artifacts/voice-clone-001/output.wav" + type: audio + size_mb: 2.5 +``` + +--- + +### Example 2: Urgent Debug Request (Human → DevBox via Issue) + +**Create issue:** + +```bash +gh issue create \ + --title "DevBox: Debug voice model failure" \ + --body "Error: Model failed to load on last run. Please check /tmp/model.log and report findings." \ + --label "squad:machine-devbox" \ + --label "urgent" +``` + +**DevBox Ralph detects → executes → comments:** + +``` +✅ Executed on devbox at 2026-03-14 15:47:00 +Command: python scripts/debug-model.py + +Result: +------ +Model file: /tmp/model-v2.bin (OK) +Checksum: a1b2c3d4e5f6 (matches expected) +Memory available: 12 GB (sufficient) + +ERROR FOUND: Config file permission issue + - File: ~/.config/voice/model.yaml + - Permissions: -rw------- (owner-only) + - Expected: -rw-r--r-- (world-readable for service) + +FIX: Run: chmod 644 ~/.config/voice/model.yaml +``` + +--- + +## Error Handling + +### Task Execution Failures + +If a task fails (exit code != 0): + +1. Result written with `status: failed` + exit code +2. stderr captured in result +3. Committed to git for audit +4. Source machine can retry by re-pushing task with `status: pending` + +### Stalled Tasks + +If a task doesn't complete within timeout: + +1. Process killed +2. Result written with `status: timeout` +3. stderr: "Execution exceeded X minutes" +4. Source can investigate or retry + +### Network Failures + +If git push/pull fails: + +- Ralph retries on next cycle +- Tasks queue locally until connectivity restored +- No tasks lost (stored in local repo) + +--- + +## Monitoring & Debugging + +### Check Task Queue + +```bash +ls -la .squad/cross-machine/tasks/ +cat .squad/cross-machine/tasks/*.yaml | grep -E "^(id|status|target_machine):" +``` + +### Check Results + +```bash +ls -la .squad/cross-machine/results/ +cat .squad/cross-machine/results/{task-id}.yaml +``` + +### View Execution History + +```bash +git log --oneline .squad/cross-machine/ | head -20 +``` + +### Monitor Ralph Cycles + +```bash +tail -f .squad/log/ralph-watch.log | grep "cross-machine" +``` + +--- + +## Integration with Ralph Watch + +Ralph automatically includes this pattern in its watch loop: + +``` +Ralph Watch Cycle (every 5-10 min): +1. Fetch GitHub issues with squad:machine-* labels +2. Poll .squad/cross-machine/tasks/ +3. For each matching task: + - Validate + - Execute + - Write result + - Commit & push +4. Update status in issue (if applicable) +5. Sleep until next cycle +``` + +No manual Ralph configuration needed — just create task files or issues with the right labels. + +--- + +## Migration from Manual Handoff + +**Before (today):** +- Laptop → user manually copies file to Teams chat +- user pastes into target terminal +- user copies output back +- user pastes result manually + +**After (with this pattern):** +- Laptop Ralph writes task file → git push +- DevBox Ralph auto-executes → git push result +- Laptop Ralph auto-reads result +- 0 human intervention needed + +--- + +## Future Enhancements + +Potential expansions (Phase 2+): + +1. **Task Priorities:** Execution order based on priority field +2. **Serial Pipelines:** Machine A → B → C task chains +3. **GPU Availability Polling:** Query DevBox before submitting work +4. **Cost Tracking:** Log resource usage per task +5. **Notification Webhooks:** Alert on task completion +6. **Web Dashboard:** Real-time task status visualization + +--- + +## Questions? + +Refer to research report: `research/active/cross-machine-agents/README.md` + +Contact: the research and documentation owner or Ralph (Work Monitor) diff --git a/.squad-templates/skills/cross-squad-communication/SKILL.md b/.squad-templates/skills/cross-squad-communication/SKILL.md new file mode 100644 index 000000000..9286d5fa2 --- /dev/null +++ b/.squad-templates/skills/cross-squad-communication/SKILL.md @@ -0,0 +1,399 @@ +--- +name: "cross-squad-communication" +description: "Protocol for sending queries, delegating tasks, and sharing context between independent Squad instances across different repositories" +domain: "multi-repo coordination" +confidence: "medium" +source: "Ported from tamirdresher/squad-skills (plugins/cross-squad-communication). Companion to the registry-aware cross-squad skill — this one teaches the actual communication protocols once a peer is discovered. Pattern 0 (synchronous CLI) is the only end-to-end-validated pattern; Patterns 1, 2, 3 are documented from design but require live validation against your own setup before relying on them in production. See the Validation Status section at the bottom of this skill." +--- + +## Context + +When multiple repositories each have their own Squad (AI team), they need to exchange information: knowledge queries, PR reviews, task delegation, and dependency analysis. Each squad has its own agents, MCP tools, and issue tracker — there is no shared runtime. + +> **Companion skill — read first:** `cross-squad/SKILL.md` covers **discovery** of peer squads via `squad registry add/list/remove`. This skill picks up after a peer is known and covers the **communication protocols** themselves — the four numbered patterns below: Pattern 0 (synchronous CLI), Pattern 1 (read-only knowledge query), Pattern 2 (git-based async), and Pattern 3 (GitHub-issue-based delegation). A separate non-numbered appendix (Cross-Repo Dependency Scan) is provided as a related analysis tool, not a communication pattern. The two skills are designed to be used together. + +**When this skill applies:** +- A squad agent needs information from another squad-enabled repo +- A task needs to be delegated to another squad +- Cross-repo dependency analysis is needed +- PR review requests span repo boundaries + +**Key constraint:** Each squad has its own runtime, MCP tools, and issue tracker. Cross-squad communication can be **synchronous** (via CLI session targeting the other repo) or **asynchronous** (file-based or issue-based). The coordinator decides which approach fits. + +--- + +## Patterns + +### Decision Tree: Choosing the Right Pattern + +``` +Is the target repo cloned locally? +├─ NO → Use Pattern 3 (Issue-Based) or Pattern 2 (Git-Based Async) +└─ YES + ├─ Is this a quick query / knowledge lookup? + │ └─ YES → Use Pattern 0 (Synchronous CLI) — fastest + ├─ Does the work need to persist as artifacts? + │ └─ YES → Use Pattern 2 (Git-Based Async) + ├─ Is it a long-running analysis or multi-cycle task? + │ └─ YES → Use Pattern 2 (Git-Based Async) + └─ Is the target squad's Ralph running? + ├─ YES → Pattern 2 or 3 (async processing available) + └─ NO → Pattern 0 (Synchronous CLI) or Pattern 1 (Read-Only) +``` + +--- + +## Universal rule: every `copilot` spawn into a peer squad MUST pass `--agent squad` + +The `copilot` CLI accepts `--agent ` to select a custom agent (see `copilot --help`). Squad installs ship `.github/agents/squad.agent.md`, which is loaded **only when `--agent squad` is specified**. Without it the spawned session runs as a generic Copilot CLI session that does NOT load the peer's `team.md`, routing, MCP tools, casting, or coordinator behaviour — so you get an off-the-shelf model answering, not the peer's Squad. **Every command example in this skill that spawns `copilot` into a peer repo includes `--agent squad`; do not strip it.** + +This rule also applies anywhere else you spawn `copilot` into a Squad-initialised repo (not just cross-squad protocols) — e.g., `squad init`'s post-init tip and any automation that invokes the CLI on a squadified folder. The only case where you may omit `--agent` is when resuming an existing session (`copilot --resume `) — the resumed session preserves its original agent context. + +--- + +### Pattern 0: Synchronous CLI Session (Fastest for Interactive Queries) + +For quick knowledge queries, decision lookups, or short analyses — spawn a Copilot CLI session with the working directory set to the target squad's repo. This lets you send a prompt and get a response within the same session, using the target repo's full context. + +This is the same technique used by `ralph-watch.ps1`: write the prompt to a temp file, then invoke the CLI with that file as input. The key insight is that setting the working directory to the target repo gives the CLI session access to that squad's `.squad/` metadata, codebase, and conventions. + +**Protocol:** +1. Write prompt to a temp file (avoids argument-splitting issues, as learned in `ralph-watch.ps1`) +2. Read the file into a string and invoke `copilot -p ` with `-C ` set to the target repo (`-p` takes prompt text, NOT a file path) AND `--agent squad` so the spawned session uses the peer squad's coordinator (without `--agent` you get a generic Copilot CLI session that doesn't load the peer's `team.md`, MCP tools, or skills) +3. Receive response in the same session + +**Invocation:** +```powershell +# Spawn a Copilot CLI session targeting another squad's repo +$targetRepo = "C:\repos\platform-squad-repo" +$promptFile = New-TemporaryFile +@" +You are working in a Squad-enabled repository. +Read .squad/team.md and .squad/decisions.md first. + +[CROSS-SQUAD REQUEST] +From: research-squad +Request Type: knowledge_query +Query: What is the current architecture of the platform? What services does it expose? +Response Format: Brief structured summary +"@ | Out-File $promptFile -Encoding utf8 + +# Option A: copilot with prompt file (read file into string; -p takes text, not a path) +# --agent squad is REQUIRED: the target is another Squad install, so the spawned +# session must use that squad's coordinator (not a generic Copilot CLI session). +copilot -C $targetRepo --agent squad -p (Get-Content $promptFile -Raw) --allow-all-tools + +# Option B: Start-Process for non-blocking (ralph-watch.ps1 style) +Start-Process pwsh -ArgumentList "-NoProfile -Command `"copilot -C '$targetRepo' --agent squad -p (Get-Content '$promptFile' -Raw) --allow-all-tools`"" -Wait + +# Option C: Pipe directly (stdin is the prompt text) +"What is the platform architecture?" | copilot -C $targetRepo --agent squad --allow-all-tools +``` + +**When to use synchronous vs async:** + +| Scenario | Pattern | Why | +|----------|---------|-----| +| Quick knowledge query | Synchronous CLI (Pattern 0) | Fast answer, no overhead | +| "What did you decide about X?" | Synchronous CLI (Pattern 0) | Read decisions.md via the target squad's context | +| PR review request | Either (Pattern 0 or 2/3) | Sync for quick feedback, async for thorough review | +| Task delegation (do work in their repo) | Async (Pattern 2 or 3) | Work needs to persist beyond the session | +| Long-running analysis | Async (Pattern 2) | May take multiple cycles | +| Target repo not locally cloned | Async (Pattern 3) | Can't set working directory to a remote repo | + +**The coordinator decides which pattern to use based on:** +1. Is the target repo cloned locally? → If yes, sync CLI is available +2. Is this a quick query or a long task? → Quick = sync, long = async +3. Does the work need to persist? → If yes, use async (creates artifacts) +4. Is the target squad's Ralph running? → Needed for async processing + +**Requirements:** +- Target repo must be cloned locally (for `copilot -C `) +- Target repo must be Squad-initialised (`.squad/config.json` + `.github/agents/squad.agent.md` present), so `--agent squad` resolves to the peer's coordinator +- Prompt file avoids argument-splitting bugs (see `ralph-watch.ps1` lines 2166-2184) + +**Response quality:** ⭐⭐⭐⭐⭐ — the CLI session has full context of the target repo, including code, squad metadata, and MCP tools. + +### Liveness Protocol for Pattern 0 + +The synchronous CLI session requires monitoring to avoid false timeouts. With 7+ MCP servers initializing and `.squad/` metadata being read, startup can take 30-60 seconds. A hard timeout kills valid sessions before they complete. Instead, monitor the agency session's activity log directory. + +**Health Check Approach:** + +Instead of a fixed wall-clock timeout, monitor the agency session log directory for activity: + +```powershell +# The Copilot CLI creates a session log directory at ~/.copilot/logs/. +# Older `agency` runtimes wrote to ~/.agency/logs/; fall back to that +# location if the new path doesn't exist yet on the user's machine. +# e.g., ~/.copilot/logs/session_20260325_071211_57824 +$copilotLogs = "$env:USERPROFILE\.copilot\logs" +$agencyLogs = "$env:USERPROFILE\.agency\logs" +$logRoot = if (Test-Path $copilotLogs) { $copilotLogs } elseif (Test-Path $agencyLogs) { $agencyLogs } else { $null } +if ($logRoot) { + $logDir = Get-ChildItem $logRoot -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 1 +} +$lastSize = 0 +$stallCount = 0 + +while ($proc -and -not $proc.HasExited) { + Start-Sleep -Seconds 15 + $currentSize = (Get-ChildItem $logDir -Recurse -File | Measure-Object -Property Length -Sum).Sum + + if ($currentSize -eq $lastSize) { + $stallCount++ + if ($stallCount -ge 4) { # 60s with no progress + Write-Warning "Session stalled — no log activity for 60s" + break + } + } else { + $stallCount = 0 + $lastSize = $currentSize + } +} +``` + +**Progress Indicators (What Counts as "Alive"):** + +- New files appearing in the session log directory (e.g., `transcript.log`, `mcp-server-logs/`) +- Log file size increasing (indicates active processing) +- New or modified `.squad/` files in the target repo (e.g., `decisions/inbox.md`, `identity/history.md`) +- Process still running and consuming non-idle CPU time + +**Stall Detection (When to Intervene):** + +- **No log activity for 60s** → Issue a warning; session may be slow but not hung +- **No log activity for 120s** → Likely stuck; consider terminating and checking logs +- **Process exited with non-zero exit code** → Failed; examine `transcript.log` and `stderr` for errors +- **MCP server connection timeout** → Session blocked waiting for an MCP server response + +**Recovery Actions When Stalled:** + +1. **Check for user input waiting:** Inspect logs for prompts or dialogs (shouldn't happen with `--autopilot`) +2. **Check MCP server health:** Review `mcp-server-logs/` for connection errors or timeouts +3. **Retry with `--disable-builtin-mcps` flag:** For lightweight queries that don't require MCP tools + ```powershell + # Retry without MCP servers — faster startup, limited capability + copilot -C $targetRepo --agent squad -p (Get-Content $promptFile -Raw) --disable-builtin-mcps --allow-all-tools + ``` +4. **Increase timeout threshold:** If MCP server initialization is consistently slow (>90s), raise threshold before declaring stall + +--- + +### Pattern 1: Read-Only Knowledge Query (No CLI Needed) + +For questions about another squad's architecture, decisions, or current state — read their `.squad/` metadata directly. + +**Protocol:** +1. Read target repo's `.squad/team.md` → get stack, members, issue source +2. Read `.squad/decisions.md` → get architectural decisions +3. Read `.squad/routing.md` → understand who handles what +4. Read `.squad/identity/now.md` → get current focus +5. Scan code structure if needed (csproj files, directory layout) + +**Requirements:** +- Target repo must be cloned locally or accessible via git +- No authentication needed beyond git read access + +**Example:** +```powershell +# Query another squad's architecture +$targetRepo = "C:\repos\platform-squad-repo" +Get-Content "$targetRepo\.squad\team.md" +Get-Content "$targetRepo\.squad\decisions.md" +Get-Content "$targetRepo\.squad\identity\now.md" +``` + +**Response quality:** ⭐⭐⭐⭐ — excellent for structural/architectural questions. + +--- + +### Pattern 2: Async Task Request (Git-Based) + +For work that needs the target squad to execute (PR reviews, issue analysis, code changes). + +**Protocol:** +1. Create request file in YOUR repo: `.squad/cross-squad/requests/{timestamp}-{target}-{id}.yaml` +2. Commit and push +3. Target squad's Ralph detects on next cycle +4. Target squad processes and writes response to their `.squad/cross-squad/responses/` +5. Your Ralph picks up the response + +**Request File Format:** +```yaml +id: req-2026-06-13-001 +source_squad: research-squad +source_repo: your-org/research-squad-repo +target_squad: platform-squad +target_repo: your-org/platform-squad-repo +request_type: knowledge_query | pr_review | task_delegation | dependency_check +priority: high | normal | low +created_at: 2026-06-13T10:00:00Z +query: "What is the current architecture of the platform?" +routing_hint: "lead" # optional — which agent should handle this +status: pending +``` + +**Response File Format:** +```yaml +id: req-2026-06-13-001 +responding_squad: platform-squad +responding_agent: lead +responded_at: 2026-06-13T10:15:00Z +status: completed | partial | rejected +response: | + The platform architecture consists of... +artifacts: [] # optional file paths +``` + +--- + +### Pattern 3: Issue-Based Delegation (For GitHub-Hosted Repos) + +For repos on GitHub, use issues with labels as the message bus. + +**Protocol:** +1. Create issue in target repo with label `squad:cross-squad` +2. Include source squad identifier and routing hint in issue body +3. Target squad's Ralph picks up and routes to appropriate agent +4. Response posted as issue comment +5. Issue closed when complete + +**Example:** +```bash +gh issue create \ + --repo your-org/platform-squad-repo \ + --title "[Cross-Squad] Architecture query from research-squad" \ + --body "Source: research-squad\nQuery: What services does the platform expose?\nRouting: lead" \ + --label "squad:cross-squad" +``` + +**Limitation:** Only works for repos on GitHub. Other platforms (Azure DevOps, GitLab, etc.) need different approach. + +--- + +### Appendix: Cross-Repo Dependency Scan (Related Analysis Tool — Not a Communication Pattern) + +> This section is intentionally listed as an appendix rather than "Pattern 4" — it is a one-off analysis utility for discovering how two repos relate, not a protocol the coordinator picks from the decision tree above. The four numbered communication patterns are 0–3. + +For discovering how two repos relate to each other. + +**Protocol:** +1. Search both repos for mutual references: + ```powershell + Select-String -Path (Get-ChildItem $repoA -Recurse -Include "*.md","*.cs","*.json","*.csproj") ` + -Pattern $repoB_name + Select-String -Path (Get-ChildItem $repoB -Recurse -Include "*.md","*.cs","*.json","*.csproj") ` + -Pattern $repoA_name + ``` +2. Check shared NuGet packages / npm packages +3. Check shared ADO project or GitHub org +4. Document relationship type: code dependency, operational coupling, shared infra + +--- + +## Discovery Protocol + +Before sending any cross-squad request, verify the target: + +``` +1. Does .squad/team.md exist? → Squad is installed +2. What is the issue_source? → GitHub Issues | ADO | Planner +3. What agents are active? → Check member status column +4. What is the routing table? → Read routing.md +5. What is the current focus? → Read identity/now.md +6. Is Ralph running? → Check for recent commits by Ralph +``` + +If `.squad/team.md` doesn't exist, the repo is not squad-enabled. Fall back to standard human communication. + +--- + +## Platform Compatibility Matrix + +| Source Issue Tracker | Target Issue Tracker | Mechanism | +|---------------------|---------------------|-----------| +| GitHub Issues | GitHub Issues | Issue-based (Pattern 3) | +| GitHub Issues | ADO Work Items | Git-based (Pattern 2) | +| GitHub Issues | Planner | Git-based (Pattern 2) | +| ADO Work Items | GitHub Issues | Issue-based (Pattern 3) via `gh` CLI | +| ADO Work Items | ADO Work Items | ADO cross-project work items | +| Any | Any | Git-based (Pattern 2) — universal fallback | + +--- + +## Examples + +### Example 1: research-squad queries platform-squad architecture + +```powershell +# Step 1: Read metadata (Pattern 1) +$target = "C:\repos\platform-squad-repo" +$team = Get-Content "$target\.squad\team.md" -Raw +$decisions = Get-Content "$target\.squad\decisions.md" -Raw + +# Step 2: Extract answer from metadata +# team.md reveals tech stack and member roles +# decisions.md reveals architectural choices + +# Step 3: If deeper analysis needed, create async request (Pattern 2) +``` + +### Example 2: Request PR review from another squad + +```yaml +# .squad/cross-squad/requests/2026-06-13-platform-squad-pr-review.yaml +id: pr-review-001 +source_squad: research-squad +target_squad: platform-squad +request_type: pr_review +priority: normal +query: "Review PR #54 — package version fix. Check for correctness." +routing_hint: "lead" +status: pending +``` + +--- + +## Anti-Patterns + +### ⚠️ Know when synchronous CLI is NOT the right choice +```powershell +# WRONG — don't use sync CLI for long-running tasks that need artifacts +copilot -C $targetRepo --agent squad -p (Get-Content $promptFile -Raw) --allow-all-tools +# If the task creates files, PRs, or takes multiple cycles → use async (Pattern 2 or 3) + +# WRONG — don't use sync CLI when the target repo isn't cloned locally +copilot -C "C:\not\cloned\yet" --agent squad --allow-all-tools +# If the repo isn't available locally → use issue-based delegation (Pattern 3) +``` +Synchronous CLI sessions (Pattern 0) are valid for quick queries and knowledge lookups. Use async patterns for work that needs to persist or where the target repo isn't available locally. + +### ❌ Don't assume shared MCP tools +Each squad has its own MCP server instances. You cannot invoke another squad's ADO tools or GitHub tools from your session. + +### ❌ Don't skip the discovery step +Always read `team.md` first. The target squad may use a different issue tracker, have different agents, or be in a different state than expected. + +### ❌ Don't send requests to squads without Ralph +If the target squad doesn't have Ralph (Work Monitor) running, async requests will never be processed. Check for recent Ralph activity first. + +### ❌ Don't mix up repo platforms +Different repos may use GitHub Issues vs Azure DevOps Work Items vs Jira. Check `team.md` / repository metadata for the right tooling before sending requests. + +--- + +## Validation Status + +This skill was originally drafted against two prototype squad setups (a GitHub-hosted platform squad with ~10 agents and an Azure DevOps-hosted automation squad with ~4 agents). The protocols are platform-agnostic; the examples in this document use generic names so you can substitute your own repos. Patterns 0 and 1 have been exercised end-to-end in those prototypes; Patterns 2 and 3 are documented from design but have not been end-to-end-validated against a live target repo. + +| Scenario | Result | +|----------|--------| +| Knowledge query (read-only) | ✅ Works via Pattern 1 | +| Step handler discovery | ✅ Works via file scan | +| PR review (basic) | ⚠️ Partial — git log only, no API | +| Backlog enumeration | ⚠️ Partial — depends on issue platform | +| Dependency analysis | ✅ Works via cross-reference scan | +| CLI invocation (sync) + Liveness Protocol | ✅ Works — session launches successfully; log monitoring prevents false timeouts | + +**Confidence: MEDIUM** — Synchronous CLI pattern (Pattern 0) validated end-to-end. Liveness protocol provides operational robustness against slow MCP initialization. Git-based async (Pattern 2) and issue-based (Pattern 3) untested end-to-end. Production readiness requires Ralph integration on both sides. diff --git a/.squad-templates/skills/cross-squad/SKILL.md b/.squad-templates/skills/cross-squad/SKILL.md new file mode 100644 index 000000000..d008e85b8 --- /dev/null +++ b/.squad-templates/skills/cross-squad/SKILL.md @@ -0,0 +1,174 @@ +--- +name: "cross-squad" +description: "Coordinating work across multiple Squad instances — discovery, delegation, and disambiguation when the user says 'squad' (the product) vs casual English 'group of agents'." +domain: "orchestration" +confidence: "medium" +source: "manual" +triggers: + - "spawn N squads" + - "spawn a squad" + - "another squad" + - "two squads of" + - "second squad" + - "fan out to squads" + - "delegate to a squad" + - "set up squads for" + - "create a squad to review" + - "ask the other squad" +tools: + - name: "squad-discover" + description: "List known squads and their capabilities" + when: "When you need to find which squad can handle a task" + - name: "squad-delegate" + description: "Create work in another squad's repository" + when: "When a task belongs to another squad's domain" +--- + +## Context + +> **Read this FIRST any time the user says "squad" as a thing to spawn, delegate to, address, or fan out to** — e.g., *"spawn two squads of designers and devs"*, *"ask the other squad"*, *"delegate to a squad"*. In Squad-PRODUCT vocabulary, "squad" is a **peer** (an independent installation with its own `.squad/`, `team.md`, MCP server, and agents) — NOT a generic English synonym for "team" or "group". Do not fan out raw `task` agents inside your own coordinator context when the user means "another squad". Use the discovery and communication patterns below (and the companion `cross-squad-communication` skill for the actual protocols). + +When an organization runs multiple Squad instances (e.g., platform-squad, frontend-squad, data-squad), those squads need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across squads without creating tight coupling. + +> **Companion skill — for protocol details:** `cross-squad-communication/SKILL.md` covers the four communication patterns (synchronous CLI, read-only knowledge query, git-based async, and GitHub-issue-based delegation) once a peer squad is discovered via the registry below. This skill answers "who?" — the companion answers "how?". + +Cross-squad orchestration applies when: +- A task requires capabilities owned by another squad +- An architectural decision affects multiple squads +- A feature spans multiple repositories with different squads +- A squad needs to request infrastructure, tooling, or support from another squad + +## Disambiguation: "squad" vs ad-hoc agents + +When the user uses the word **"squad" / "squads"** or asks to **"spawn a team"**, the coordinator MUST treat it as a literal reference to a Squad install (a `.squad/` directory with its own roster, casting, and coordinator) — NOT as a casual synonym for "a group of sub-agents". + +### Default behaviour (apply unless explicitly told otherwise) + +| User says | Coordinator does | +|---|---| +| *"spawn two squads of X and Y"* / *"set up squads for X, Y, Z"* | Bootstrap N **real** Squad installs — separate folder + `git init` + `squad init` per squad — then use the cross-squad patterns below (`.squad/manifest.json`, `squad registry add`, `squad delegate`) and the protocols in the `cross-squad-communication` skill | +| *"ask the other squad about X"* / *"delegate to the data squad"* | Discover the peer via `squad registry list` (or by reading a known `.squad/manifest.json`), then use `cross-squad-communication` Pattern 0 / 1 / 2 / 3 — never re-implement the protocol with `task` | +| *"spawn a few agents to do X"* / *"have some agents review X"* / *"in parallel, get sub-agents to..."* | Ad-hoc `task` fan-out is fine — no `.squad/` bootstrap needed. This is the only path where raw `task` is appropriate when the user mentioned a multi-agent activity | + +### Ambiguous? `ask_user`, never silently downgrade + +If the request **could** be either interpretation AND bootstrapping real squads is non-trivial (more than one or two `squad init` runs), you MUST use the `ask_user` tool with a 2-choice prompt before proceeding: + +``` +question: "Should I create separate Squad installs or just dispatch ad-hoc agents?" +choices: + - "Real squads — separate .squad/ per squad (heavier, persistent, can be re-engaged later)" + - "Ad-hoc agents — one-shot `task` dispatch (lighter, ephemeral, no .squad/ created)" +``` + +The cost of asking is one `ask_user`. The cost of getting it wrong is the user has to redo the work. **Never silently pick the cheaper option just because it feels disproportionate for the task size — surface the trade-off and let the user pick.** + +### Anti-patterns (every one of these is a real failure mode observed in production) + +- **Calling `task` sub-agents "squad-alpha" / "squad-beta"** and treating them as squads. Naming something a squad doesn't make it one — a squad has its own `.squad/`, `team.md`, MCP server, and coordinator. If those aren't there, it's not a squad. +- **Matching a prior session's ad-hoc pattern without re-checking current intent.** If you see existing `reviews/squad-alpha/` folders from a previous run, that's a hint, NOT a contract — the user may have meant something different this time. Re-evaluate from scratch. +- **Silently choosing the cheaper interpretation because "bootstrapping two real squads for a 30-line app feels disproportionate".** That's a judgment call for the USER to make, not the coordinator. Use `ask_user`. +- **Loading the `cross-squad` skill, reading it, then doing `task` fan-out anyway** because the eager-execution / parallel-fan-out doctrine pulled you back. The disambiguation rule on this page OVERRIDES the generic fan-out doctrine when "squad" was the trigger. + +## Patterns + +### Discovery via Manifest +Each squad publishes a `.squad/manifest.json` declaring its name, capabilities, and contact information. Squads discover each other through two mechanisms: + +1. **`.squad/squad-registry.json`** — **discovery-only.** Peer squads are findable via `squad discover` and addressable via `squad delegate`, but their skills/decisions/wisdom are NOT loaded into your coordinator. Manage with `squad registry add/list/remove`. +2. **`.squad/upstream.json`** — **discovery + inheritance.** Squads listed here are also discoverable, AND your coordinator inherits their skills/decisions/wisdom/routing at session start. Manage with `squad upstream add/list/remove/sync`. + +Both forms read the peer's manifest via the same code path. The `path` field is the **repository root** (e.g. `../friend-repo`), and Squad appends `.squad/manifest.json` internally. Pointing at the `.squad/` directory works too — Squad accepts both forms (`readManifest` strips a trailing `.squad` if present). + +```json +{ + "name": "platform-squad", + "version": "1.0.0", + "description": "Platform infrastructure team", + "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"], + "contact": { + "repo": "org/platform", + "labels": ["squad:platform"] + }, + "accepts": ["issues", "prs"], + "skills": ["helm-developer", "operator-developer", "pipeline-engineer"] +} +``` + +### Context Sharing +When delegating work, share only what the target squad needs: +- **Capability list**: What this squad can do (from manifest) +- **Relevant decisions**: Only decisions that affect the target squad +- **Handoff context**: A concise description of why this work is being delegated + +Do NOT share: +- Internal team state (casting history, session logs) +- Full decision archives (send only relevant excerpts) +- Authentication credentials or secrets + +### Work Handoff Protocol +1. **Check manifest**: Verify the target squad accepts the work type (issues, PRs) +2. **Create issue**: Use `gh issue create` in the target repo with: + - Title: `[cross-squad] ` + - Label: `squad:cross-squad` (or the squad's configured label) + - Body: Context, acceptance criteria, and link back to originating issue +3. **Track**: Record the cross-squad issue URL in the originating squad's orchestration log +4. **Poll**: Periodically check if the delegated issue is closed/completed + +### Feedback Loop +Track delegated work completion: +- Poll target issue status via `gh issue view` +- Update originating issue with status changes +- Close the feedback loop when delegated work merges + +## Examples + +### Registering a peer squad (no inheritance) +```bash +# Friend's repo is checked out at ../friend-platform/ +squad registry add platform-squad ../friend-platform + +# Verify +squad registry list +squad discover +``` + +### Discovering squads +```bash +# List all squads discoverable from registry + upstreams +squad discover + +# Output: +# platform-squad → org/platform (kubernetes, helm, monitoring) +# frontend-squad → org/frontend (react, nextjs, storybook) +# data-squad → org/data (spark, airflow, dbt) +``` + +### Delegating work +```bash +# Delegate a task to the platform squad +squad delegate platform-squad "Add Prometheus metrics endpoint for the auth service" + +# Creates issue in org/platform with cross-squad label and context +``` + +### Manifest in squad.config.ts +```typescript +export default defineSquad({ + manifest: { + name: 'platform-squad', + capabilities: ['kubernetes', 'helm'], + contact: { repo: 'org/platform', labels: ['squad:platform'] }, + accepts: ['issues', 'prs'], + skills: ['helm-developer', 'operator-developer'], + }, +}); +``` + +## Anti-Patterns +- **Direct file writes across repos** — Never modify another squad's `.squad/` directory. Use issues and PRs as the communication protocol. +- **Tight coupling** — Don't depend on another squad's internal structure. Use the manifest as the public API contract. +- **Unbounded delegation** — Always include acceptance criteria and a timeout. Don't create open-ended requests. +- **Skipping discovery** — Don't hardcode squad locations. Use manifests and the discovery protocol. +- **Sharing secrets** — Never include credentials, tokens, or internal URLs in cross-squad issues. +- **Circular delegation** — Track delegation chains. If squad A delegates to B which delegates back to A, something is wrong. diff --git a/.squad-templates/skills/distributed-mesh/SKILL.md b/.squad-templates/skills/distributed-mesh/SKILL.md new file mode 100644 index 000000000..624db9626 --- /dev/null +++ b/.squad-templates/skills/distributed-mesh/SKILL.md @@ -0,0 +1,287 @@ +--- +name: "distributed-mesh" +description: "How to coordinate with squads on different machines using git as transport" +domain: "distributed-coordination" +confidence: "high" +source: "multi-model-consensus (Opus 4.6, Sonnet 4.5, GPT-5.4)" +--- + +## SCOPE + +**✅ THIS SKILL PRODUCES (exactly these, nothing more):** + +1. **`mesh.json`** — Generated from user answers about zones and squads (which squads participate, what zone each is in, paths/URLs for each), using `mesh.json.example` in this skill's directory as the schema template +2. **`sync-mesh.sh` and `sync-mesh.ps1`** — Copied from this skill's directory into the project root (these are bundled resources, NOT generated code) +3. **Zone 2 state repo initialization** (if applicable) — If the user specified a Zone 2 shared state repo, run `sync-mesh.sh --init` to scaffold the state repo structure +4. **A decision entry** in `.squad/decisions/inbox/` documenting the mesh configuration for team awareness + +**❌ THIS SKILL DOES NOT PRODUCE:** + +- **No application code** — No validators, libraries, or modules of any kind +- **No test files** — No test suites, test cases, or test scaffolding +- **No GENERATING sync scripts** — They are bundled with this skill as pre-built resources. COPY them, don't generate them. +- **No daemons or services** — No background processes, servers, or persistent runtimes +- **No modifications to existing squad files** beyond the decision entry (no changes to team.md, routing.md, agent charters, etc.) + +**Your role:** Configure the mesh topology and install the bundled sync scripts. Nothing more. + +## Context + +When squads are on different machines (developer laptops, CI runners, cloud VMs, partner orgs), the local file-reading convention still works — but remote files need to arrive on your disk first. This skill teaches the pattern for distributed squad communication. + +**When this applies:** +- Squads span multiple machines, VMs, or CI runners +- Squads span organizations or companies +- An agent needs context from a squad whose files aren't on the local filesystem + +**When this does NOT apply:** +- All squads are on the same machine (just read the files directly) + +## Patterns + +### The Core Principle + +> "The filesystem is the mesh, and git is how the mesh crosses machine boundaries." + +The agent interface never changes. Agents always read local files. The distributed layer's only job is to make remote files appear locally before the agent reads them. + +### Three Zones of Communication + +**Zone 1 — Local:** Same filesystem. Read files directly. Zero transport. + +**Zone 2 — Remote-Trusted:** Different host, same org, shared git auth. Transport: `git pull` from a shared repo. This collapses Zone 2 into Zone 1 — files materialize on disk, agent reads them normally. + +**Zone 3 — Remote-Opaque:** Different org, no shared auth. Transport: `curl` to fetch published contracts (SUMMARY.md). One-way visibility — you see only what they publish. + +### Agent Lifecycle (Distributed) + +``` +1. SYNC: git pull (Zone 2) + curl (Zone 3) — materialize remote state +2. READ: cat .mesh/**/state.md — all files are local now +3. WORK: do their assigned work (the agent's normal task, NOT mesh-building) +4. WRITE: update own billboard, log, drops +5. PUBLISH: git add + commit + push — share state with remote peers +``` + +Steps 2–4 are identical to local-only. Steps 1 and 5 are the entire distributed extension. **Note:** "WORK" means the agent performs its normal squad duties — it does NOT mean "build mesh infrastructure." + +### The mesh.json Config + +```json +{ + "squads": { + "auth-squad": { "zone": "local", "path": "../auth-squad/.mesh" }, + "ci-squad": { + "zone": "remote-trusted", + "source": "git@github.com:our-org/ci-squad.git", + "ref": "main", + "sync_to": ".mesh/remotes/ci-squad" + }, + "partner-fraud": { + "zone": "remote-opaque", + "source": "https://partner.dev/squad-contracts/fraud/SUMMARY.md", + "sync_to": ".mesh/remotes/partner-fraud", + "auth": "bearer" + } + } +} +``` + +Three zone types, one file. Local squads need only a path. Remote-trusted need a git URL. Remote-opaque need an HTTP URL. + +### Write Partitioning + +Each squad writes only to its own directory (`boards/{self}.md`, `squads/{self}/*`, `drops/{date}-{self}-*.md`). No two squads write to the same file. Git push/pull never conflicts. If push fails ("branch is behind"), the fix is always `git pull --rebase && git push`. + +### Trust Boundaries + +Trust maps to git permissions: +- **Same repo access** = full mesh visibility +- **Read-only access** = can observe, can't write +- **No access** = invisible (correct behavior) + +For selective visibility, use separate repos per audience (internal, partner, public). Git permissions ARE the trust negotiation. + +### Phased Rollout + +- **Phase 0:** Convention only — document zones, agree on mesh.json fields, manually run `git pull`/`git push`. Zero new code. +- **Phase 1:** Sync script (~30 lines bash or PowerShell) when manual sync gets tedious. +- **Phase 2:** Published contracts + curl fetch when a Zone 3 partner appears. +- **Phase 3:** Never. No MCP federation, A2A, service discovery, message queues. + +**Important:** Phases are NOT auto-advanced. These are project-level decisions — you start at Phase 0 (manual sync) and only move forward when the team decides complexity is justified. + +### Mesh State Repo + +The shared mesh state repo is a plain git repository — NOT a Squad project. It holds: +- One directory per participating squad +- Each directory contains at minimum a SUMMARY.md with the squad's current state +- A root README explaining what the repo is and who participates + +No `.squad/` folder, no agents, no automation. Write partitioning means each squad only pushes to its own directory. The repo is a rendezvous point, not an intelligent system. + +If you want a squad that *observes* mesh health, that's a separate Squad project that lists the state repo as a Zone 2 remote in its `mesh.json` — it does NOT live inside the state repo. + +## Examples + +### Developer Laptop + CI Squad (Zone 2) + +Auth-squad agent wakes up. `git pull` brings ci-squad's latest results. Agent reads: "3 test failures in auth module." Adjusts work. Pushes results when done. **Overhead: one `git pull`, one `git push`.** + +### Two Orgs Collaborating (Zone 3) + +Payment-squad fetches partner's published SUMMARY.md via curl. Reads: "Risk scoring v3 API deprecated April 15. New field `device_fingerprint` required." The consuming agent (in payment-squad's team) reads this information and uses it to inform its work — for example, updating payment integration code to include the new field. Partner can't see payment-squad's internals. + +### Same Org, Shared Mesh Repo (Zone 2) + +Three squads on different machines. One shared git repo holds the mesh. Each squad: `git pull` before work, `git push` after. Write partitioning ensures zero merge conflicts. + +## AGENT WORKFLOW (Deterministic Setup) + +When a user invokes this skill to set up a distributed mesh, follow these steps **exactly, in order:** + +### Step 1: ASK the user for mesh topology + +Ask these questions (adapt phrasing naturally, but get these answers): + +1. **Which squads are participating?** (List of squad names) +2. **For each squad, which zone is it in?** + - `local` — same filesystem (just need a path) + - `remote-trusted` — different machine, same org, shared git access (need git URL + ref) + - `remote-opaque` — different org, no shared auth (need HTTPS URL to published contract) +3. **For each squad, what's the connection info?** + - Local: relative or absolute path to their `.mesh/` directory + - Remote-trusted: git URL (SSH or HTTPS), ref (branch/tag), and where to sync it to locally + - Remote-opaque: HTTPS URL to their SUMMARY.md, where to sync it, and auth type (none/bearer) +4. **Where should the shared state live?** (For Zone 2 squads: git repo URL for the mesh state, or confirm each squad syncs independently) + +### Step 2: GENERATE `mesh.json` + +Using the answers from Step 1, create a `mesh.json` file at the project root. Use `mesh.json.example` from THIS skill's directory (`.squad/skills/distributed-mesh/mesh.json.example`) as the schema template. + +Structure: + +```json +{ + "squads": { + "": { "zone": "local", "path": "" }, + "": { + "zone": "remote-trusted", + "source": "", + "ref": "", + "sync_to": ".mesh/remotes/" + }, + "": { + "zone": "remote-opaque", + "source": "", + "sync_to": ".mesh/remotes/", + "auth": "" + } + } +} +``` + +Write this file to the project root. Do NOT write any other code. + +### Step 3: COPY sync scripts + +Copy the bundled sync scripts from THIS skill's directory into the project root: + +- **Source:** `.squad/skills/distributed-mesh/sync-mesh.sh` +- **Destination:** `sync-mesh.sh` (project root) + +- **Source:** `.squad/skills/distributed-mesh/sync-mesh.ps1` +- **Destination:** `sync-mesh.ps1` (project root) + +These are bundled resources. Do NOT generate them — COPY them directly. + +### Step 4: RUN `--init` (if Zone 2 state repo exists) + +If the user specified a Zone 2 shared state repo in Step 1, run the initialization: + +**On Unix/Linux/macOS:** +```bash +bash sync-mesh.sh --init +``` + +**On Windows:** +```powershell +.\sync-mesh.ps1 -Init +``` + +This scaffolds the state repo structure (squad directories, placeholder SUMMARY.md files, root README). + +**Skip this step if:** +- No Zone 2 squads are configured (local/opaque only) +- The state repo already exists and is initialized + +### Step 5: WRITE a decision entry + +Create a decision file at `.squad/decisions/inbox/-mesh-setup.md` with this content: + +```markdown +### : Mesh configuration + +**By:** (via distributed-mesh skill) + +**What:** Configured distributed mesh with squads across zones + +**Squads:** +- `` — Zone — +- `` — Zone — +- ... + +**State repo:** + +**Why:** +``` + +Write this file. The Scribe will merge it into the main decisions file later. + +### Step 6: STOP + +**You are done.** Do not: +- Generate sync scripts (they're bundled with this skill — COPY them) +- Write validator code +- Write test files +- Create any other modules, libraries, or application code +- Modify existing squad files (team.md, routing.md, charters) +- Auto-advance to Phase 2 or Phase 3 + +Output a simple completion message: + +``` +✅ Mesh configured. Created: +- mesh.json ( squads) +- sync-mesh.sh and sync-mesh.ps1 (copied from skill bundle) +- Decision entry: .squad/decisions/inbox/ + +Run `bash sync-mesh.sh` (or `.\sync-mesh.ps1` on Windows) before agents start to materialize remote state. +``` + +--- + +## Anti-Patterns + +**❌ Code generation anti-patterns:** +- Writing `mesh-config-validator.js` or any validator module +- Writing test files for mesh configuration +- Generating sync scripts instead of copying the bundled ones from this skill's directory +- Creating library modules or utilities +- Building any code that "runs the mesh" — the mesh is read by agents, not executed + +**❌ Architectural anti-patterns:** +- Building a federation protocol — Git push/pull IS federation +- Running a sync daemon or server — Agents are not persistent. Sync at startup, publish at shutdown +- Real-time notifications — Agents don't need real-time. They need "recent enough." `git pull` is recent enough +- Schema validation for markdown — The LLM reads markdown. If the format changes, it adapts +- Service discovery protocol — mesh.json is a file with 10 entries. Not a "discovery problem" +- Auth framework — Git SSH keys and HTTPS tokens. Not a framework. Already configured +- Message queues / event buses — Agents wake, read, work, write, sleep. Nobody's home to receive events +- Any component requiring a running process — That's the line. Don't cross it + +**❌ Scope creep anti-patterns:** +- Auto-advancing phases without user decision +- Modifying agent charters or routing rules +- Setting up CI/CD pipelines for mesh sync +- Creating dashboards or monitoring tools diff --git a/.squad-templates/skills/distributed-mesh/mesh.json.example b/.squad-templates/skills/distributed-mesh/mesh.json.example new file mode 100644 index 000000000..7f5730a88 --- /dev/null +++ b/.squad-templates/skills/distributed-mesh/mesh.json.example @@ -0,0 +1,30 @@ +{ + "squads": { + "auth-squad": { + "zone": "local", + "path": "../auth-squad/.mesh" + }, + "api-squad": { + "zone": "local", + "path": "../api-squad/.mesh" + }, + "ci-squad": { + "zone": "remote-trusted", + "source": "git@github.com:our-org/ci-squad.git", + "ref": "main", + "sync_to": ".mesh/remotes/ci-squad" + }, + "data-squad": { + "zone": "remote-trusted", + "source": "git@github.com:our-org/data-pipeline.git", + "ref": "main", + "sync_to": ".mesh/remotes/data-squad" + }, + "partner-fraud": { + "zone": "remote-opaque", + "source": "https://partner.example.com/squad-contracts/fraud/SUMMARY.md", + "sync_to": ".mesh/remotes/partner-fraud", + "auth": "bearer" + } + } +} diff --git a/.squad-templates/skills/distributed-mesh/sync-mesh.ps1 b/.squad-templates/skills/distributed-mesh/sync-mesh.ps1 new file mode 100644 index 000000000..5f409ef37 --- /dev/null +++ b/.squad-templates/skills/distributed-mesh/sync-mesh.ps1 @@ -0,0 +1,111 @@ +# sync-mesh.ps1 — Materialize remote squad state locally +# +# Reads mesh.json, fetches remote squads into local directories. +# Run before agent reads. No daemon. No service. ~40 lines. +# +# Usage: .\sync-mesh.ps1 [path-to-mesh.json] +# .\sync-mesh.ps1 -Init [path-to-mesh.json] +# Requires: git +param( + [switch]$Init, + [string]$MeshJson = "mesh.json" +) +$ErrorActionPreference = "Stop" + +# Handle -Init mode +if ($Init) { + if (-not (Test-Path $MeshJson)) { + Write-Host "❌ $MeshJson not found" + exit 1 + } + + Write-Host "🚀 Initializing mesh state repository..." + $config = Get-Content $MeshJson -Raw | ConvertFrom-Json + $squads = $config.squads.PSObject.Properties.Name + + # Create squad directories with placeholder SUMMARY.md + foreach ($squad in $squads) { + if (-not (Test-Path $squad)) { + New-Item -ItemType Directory -Path $squad | Out-Null + Write-Host " ✓ Created $squad/" + } else { + Write-Host " • $squad/ exists (skipped)" + } + + $summaryPath = "$squad/SUMMARY.md" + if (-not (Test-Path $summaryPath)) { + "# $squad`n`n_No state published yet._" | Set-Content $summaryPath + Write-Host " ✓ Created $summaryPath" + } else { + Write-Host " • $summaryPath exists (skipped)" + } + } + + # Generate root README.md + if (-not (Test-Path "README.md")) { + $readme = @" +# Squad Mesh State Repository + +This repository tracks published state from participating squads. + +## Participating Squads + +"@ + foreach ($squad in $squads) { + $zone = $config.squads.$squad.zone + $readme += "- **$squad** (Zone: $zone)`n" + } + $readme += @" + +Each squad directory contains a ``SUMMARY.md`` with their latest published state. +State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``. +"@ + $readme | Set-Content "README.md" + Write-Host " ✓ Created README.md" + } else { + Write-Host " • README.md exists (skipped)" + } + + Write-Host "" + Write-Host "✅ Mesh state repository initialized" + exit 0 +} + +$config = Get-Content $MeshJson -Raw | ConvertFrom-Json + +# Zone 2: Remote-trusted — git clone/pull +foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-trusted" }) { + $squad = $entry.Name + $source = $entry.Value.source + $ref = if ($entry.Value.ref) { $entry.Value.ref } else { "main" } + $target = $entry.Value.sync_to + + if (Test-Path "$target/.git") { + git -C $target pull --rebase --quiet 2>$null + if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: pull failed (using stale)" } + } else { + New-Item -ItemType Directory -Force -Path (Split-Path $target -Parent) | Out-Null + git clone --quiet --depth 1 --branch $ref $source $target 2>$null + if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: clone failed (unavailable)" } + } +} + +# Zone 3: Remote-opaque — fetch published contracts +foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-opaque" }) { + $squad = $entry.Name + $source = $entry.Value.source + $target = $entry.Value.sync_to + $auth = $entry.Value.auth + + New-Item -ItemType Directory -Force -Path $target | Out-Null + $params = @{ Uri = $source; OutFile = "$target/SUMMARY.md"; UseBasicParsing = $true } + if ($auth -eq "bearer") { + $tokenVar = ($squad.ToUpper() -replace '-', '_') + "_TOKEN" + $token = [Environment]::GetEnvironmentVariable($tokenVar) + if ($token) { $params.Headers = @{ Authorization = "Bearer $token" } } + } + try { Invoke-WebRequest @params -ErrorAction Stop } + catch { "# ${squad} — unavailable ($(Get-Date))" | Set-Content "$target/SUMMARY.md" } +} + +Write-Host "✓ Mesh sync complete" diff --git a/.squad-templates/skills/distributed-mesh/sync-mesh.sh b/.squad-templates/skills/distributed-mesh/sync-mesh.sh new file mode 100644 index 000000000..802fd2d8d --- /dev/null +++ b/.squad-templates/skills/distributed-mesh/sync-mesh.sh @@ -0,0 +1,104 @@ +#!/bin/bash +# sync-mesh.sh — Materialize remote squad state locally +# +# Reads mesh.json, fetches remote squads into local directories. +# Run before agent reads. No daemon. No service. ~40 lines. +# +# Usage: ./sync-mesh.sh [path-to-mesh.json] +# ./sync-mesh.sh --init [path-to-mesh.json] +# Requires: jq (https://github.com/jqlang/jq), git, curl + +set -euo pipefail + +# Handle --init mode +if [ "${1:-}" = "--init" ]; then + MESH_JSON="${2:-mesh.json}" + + if [ ! -f "$MESH_JSON" ]; then + echo "❌ $MESH_JSON not found" + exit 1 + fi + + echo "🚀 Initializing mesh state repository..." + squads=$(jq -r '.squads | keys[]' "$MESH_JSON") + + # Create squad directories with placeholder SUMMARY.md + for squad in $squads; do + if [ ! -d "$squad" ]; then + mkdir -p "$squad" + echo " ✓ Created $squad/" + else + echo " • $squad/ exists (skipped)" + fi + + if [ ! -f "$squad/SUMMARY.md" ]; then + echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md" + echo " ✓ Created $squad/SUMMARY.md" + else + echo " • $squad/SUMMARY.md exists (skipped)" + fi + done + + # Generate root README.md + if [ ! -f "README.md" ]; then + { + echo "# Squad Mesh State Repository" + echo "" + echo "This repository tracks published state from participating squads." + echo "" + echo "## Participating Squads" + echo "" + for squad in $squads; do + zone=$(jq -r ".squads.\"$squad\".zone" "$MESH_JSON") + echo "- **$squad** (Zone: $zone)" + done + echo "" + echo "Each squad directory contains a \`SUMMARY.md\` with their latest published state." + echo "State is synchronized using \`sync-mesh.sh\` or \`sync-mesh.ps1\`." + } > README.md + echo " ✓ Created README.md" + else + echo " • README.md exists (skipped)" + fi + + echo "" + echo "✅ Mesh state repository initialized" + exit 0 +fi + +MESH_JSON="${1:-mesh.json}" + +# Zone 2: Remote-trusted — git clone/pull +for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-trusted") | .key' "$MESH_JSON"); do + source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON") + ref=$(jq -r ".squads.\"$squad\".ref // \"main\"" "$MESH_JSON") + target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON") + + if [ -d "$target/.git" ]; then + git -C "$target" pull --rebase --quiet 2>/dev/null \ + || echo "⚠ $squad: pull failed (using stale)" + else + mkdir -p "$(dirname "$target")" + git clone --quiet --depth 1 --branch "$ref" "$source" "$target" 2>/dev/null \ + || echo "⚠ $squad: clone failed (unavailable)" + fi +done + +# Zone 3: Remote-opaque — fetch published contracts +for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-opaque") | .key' "$MESH_JSON"); do + source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON") + target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON") + auth=$(jq -r ".squads.\"$squad\".auth // \"\"" "$MESH_JSON") + + mkdir -p "$target" + auth_flag="" + if [ "$auth" = "bearer" ]; then + token_var="$(echo "${squad}" | tr '[:lower:]-' '[:upper:]_')_TOKEN" + [ -n "${!token_var:-}" ] && auth_flag="--header \"Authorization: Bearer ${!token_var}\"" + fi + + eval curl --silent --fail $auth_flag "$source" -o "$target/SUMMARY.md" 2>/dev/null \ + || echo "# ${squad} — unavailable ($(date))" > "$target/SUMMARY.md" +done + +echo "✓ Mesh sync complete" diff --git a/.squad-templates/skills/docs-standards/SKILL.md b/.squad-templates/skills/docs-standards/SKILL.md new file mode 100644 index 000000000..09039a014 --- /dev/null +++ b/.squad-templates/skills/docs-standards/SKILL.md @@ -0,0 +1,71 @@ +--- +name: "docs-standards" +description: "Microsoft Style Guide + Squad-specific documentation patterns" +domain: "documentation" +confidence: "high" +source: "earned (documentation reviews)" +--- + +## Context + +Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability. + +## Patterns + +### Microsoft Style Guide Rules +- **Sentence-case headings:** "Getting started" not "Getting Started" +- **Active voice:** "Run the command" not "The command should be run" +- **Second person:** "You can configure..." not "Users can configure..." +- **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 +- **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 +- **Cross-references at bottom:** Related pages linked after main content + +### Structure +- **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)** + +### Test Sync Rule +- **Always update test assertions:** When adding docs pages to `features/`, `scenarios/`, `guides/`, update corresponding `EXPECTED_*` arrays in `test/docs-build.test.ts` in the same commit + +## Examples + +✓ **Correct:** +```markdown +# Getting started with Squad + +> ⚠️ **Experimental:** This feature is in preview. + +Try this: +\`\`\`bash +squad init +\`\`\` + +Squad helps you build AI teams... + +--- + +## Install Squad + +Run the following command... +``` + +✗ **Incorrect:** +```markdown +# Getting Started With Squad // Title case + +Squad is a tool which will help users... // Third person, future tense + +You can install Squad with npm & configure it... // Ampersand in prose +``` + +## Anti-Patterns + +- Title-casing headings because "it looks nicer" +- Writing in passive voice or third person +- Long paragraphs of dense text (breaks scannability) +- Adding doc pages without updating test assertions +- Using ampersands outside code blocks diff --git a/.squad-templates/skills/e2e-template-testing/SKILL.md b/.squad-templates/skills/e2e-template-testing/SKILL.md index 0523fd340..316d20868 100644 --- a/.squad-templates/skills/e2e-template-testing/SKILL.md +++ b/.squad-templates/skills/e2e-template-testing/SKILL.md @@ -137,13 +137,13 @@ tool calls (including file writes) prompt for confirmation and block. ```powershell # PowerShell (Windows) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." ` +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." ` 2>&1 | Tee-Object evidence/session-task.log ``` ```bash # Bash (macOS/Linux) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." \ +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." \ 2>&1 | tee evidence/session-task.log ``` diff --git a/.squad-templates/skills/economy-mode/SKILL.md b/.squad-templates/skills/economy-mode/SKILL.md new file mode 100644 index 000000000..646038978 --- /dev/null +++ b/.squad-templates/skills/economy-mode/SKILL.md @@ -0,0 +1,115 @@ +--- +name: "economy-mode" +description: "Shifts Layer 3 model selection to cost-optimized alternatives when economy mode is active." +domain: "model-selection" +confidence: "low" +source: "manual" +--- + +## SCOPE + +✅ THIS SKILL PRODUCES: +- A modified Layer 3 model selection table applied when economy mode is active +- `economyMode: true` written to `.squad/config.json` when activated persistently +- Spawn acknowledgments with `💰` indicator when economy mode is active + +❌ THIS SKILL DOES NOT PRODUCE: +- Code, tests, or documentation +- Cost reports or billing artifacts +- Changes to Layer 0, Layer 1, or Layer 2 resolution (user intent always wins) + +## Context + +Economy mode shifts Layer 3 (Task-Aware Auto-Selection) to lower-cost alternatives. It does NOT override persistent config (`defaultModel`, `agentModelOverrides`) or per-agent charter preferences — those represent explicit user intent and always take priority. + +Use this skill when the user wants to reduce costs across an entire session or permanently, without manually specifying models for each agent. + +## Activation Methods + +| Method | How | +|--------|-----| +| Session phrase | "use economy mode", "save costs", "go cheap", "reduce costs" | +| Persistent config | `"economyMode": true` in `.squad/config.json` | +| CLI flag | `squad --economy` | + +**Deactivation:** "turn off economy mode", "disable economy mode", or remove `economyMode` from `config.json`. + +## Economy Model Selection Table + +When economy mode is **active**, Layer 3 auto-selection uses this table instead of the normal defaults: + +| Task Output | Normal Mode | Economy Mode | +|-------------|-------------|--------------| +| Writing code (implementation, refactoring, bug fixes) | `gpt-5.6-terra` | `gpt-5.6-luna` | +| Writing prompts or agent designs | `gpt-5.6-terra` | `gpt-5.6-luna` | +| Docs, planning, triage, changelogs, mechanical ops | `gpt-5.6-luna` | `gpt-5.6-luna` | +| Visual/design work requiring image analysis | `gpt-5.6-sol` | `gpt-5.6-terra` | +| Architecture, code review, security audits | `gpt-5.6-sol` | `gpt-5.6-terra` | +| Scribe / logger / mechanical file ops | `gpt-5.6-luna` | `gpt-5.6-luna` | + +**Prefer `gpt-5.6-luna`** for all economy-mode tasks where cost is the priority. + +## AGENT WORKFLOW + +### On Session Start + +1. READ `.squad/config.json` +2. CHECK for `economyMode: true` — if present, activate economy mode for the session +3. STORE economy mode state in session context + +### On User Phrase Trigger + +**Session-only (no config change):** "use economy mode", "save costs", "go cheap" + +1. SET economy mode active for this session +2. ACKNOWLEDGE: `✅ Economy mode active — using cost-optimized models this session. (Layer 0 and Layer 2 preferences still apply)` + +**Persistent:** "always use economy mode", "save economy mode" + +1. WRITE `economyMode: true` to `.squad/config.json` (merge, don't overwrite other fields) +2. ACKNOWLEDGE: `✅ Economy mode saved — cost-optimized models will be used until disabled.` + +### On Every Agent Spawn (Economy Mode Active) + +1. CHECK Layer 0a/0b first (agentModelOverrides, defaultModel) — if set, use that. Economy mode does NOT override Layer 0. +2. CHECK Layer 1 (session directive for a specific model) — if set, use that. Economy mode does NOT override explicit session directives. +3. CHECK Layer 2 (charter preference) — if set, use that. Economy mode does NOT override charter preferences. +4. APPLY economy table at Layer 3 instead of normal table. +5. INCLUDE `💰` in spawn acknowledgment: `🔧 {Name} ({model} · 💰 economy) — {task}` + +### On Deactivation + +**Trigger phrases:** "turn off economy mode", "disable economy mode", "use normal models" + +1. REMOVE `economyMode` from `.squad/config.json` (if it was persisted) +2. CLEAR session economy mode state +3. ACKNOWLEDGE: `✅ Economy mode disabled — returning to standard model selection.` + +### STOP + +After updating economy mode state and including the `💰` indicator in spawn acknowledgments, this skill is done. Do NOT: +- Change Layer 0, Layer 1, or Layer 2 model choices +- Override charter-specified models +- Generate cost reports or comparisons +- Fall back to premium models via economy mode (economy mode never bumps UP) + +## Config Schema + +`.squad/config.json` economy-related fields: + +```json +{ + "version": 1, + "economyMode": true +} +``` + +- `economyMode` — when `true`, Layer 3 uses the economy table. Optional; absent = economy mode off. +- Combines with `defaultModel` and `agentModelOverrides` — Layer 0 always wins. + +## Anti-Patterns + +- **Don't override Layer 0 in economy mode.** If the user set `defaultModel: "claude-opus-4.6"`, they want quality. Economy mode only affects Layer 3 auto-selection. +- **Don't silently apply economy mode.** Always acknowledge when activated or deactivated. +- **Don't treat economy mode as permanent by default.** Session phrases activate session-only; only "always" or `config.json` persist it. +- **Don't bump premium tasks down too far.** Visual, architecture, and security work shifts from Sol to Terra in economy mode — it does NOT go to fast/cheap models. diff --git a/.squad-templates/skills/error-recovery/SKILL.md b/.squad-templates/skills/error-recovery/SKILL.md new file mode 100644 index 000000000..ebf38825c --- /dev/null +++ b/.squad-templates/skills/error-recovery/SKILL.md @@ -0,0 +1,99 @@ +--- +name: "error-recovery" +description: "Standard recovery patterns for all squad agents. When something fails, adapt — don't just report the failure." +domain: "reliability, agent-coordination" +confidence: "high" +license: MIT +--- + +# Error Recovery Patterns + +Standard recovery patterns for all squad agents. When something fails, **adapt** — don't just report the failure. + +--- + +## 1. Retry with Backoff + +**When:** Transient failures — API timeouts, rate limits, network errors, temporary service unavailability. + +**Pattern:** +1. Wait briefly, then retry (start at 2s, double each attempt) +2. Maximum 3 retries before escalating +3. Log each attempt with the error received + +**Example:** API call returns 429 Too Many Requests → wait 2s → retry → wait 4s → retry → wait 8s → retry → escalate if still failing. + +--- + +## 2. Fallback Alternatives + +**When:** Primary tool or approach fails and an alternative exists. + +**Pattern:** +1. Attempt primary approach +2. On failure, identify alternative tool/method +3. Try the alternative with the same intent +4. Document which alternative was used and why + +**Example:** Primary CLI tool fails → fall back to direct API call for the same operation. + +--- + +## 3. Diagnose-and-Fix + +**When:** Build failures, test failures, linting errors — structured errors with actionable output. + +**Pattern:** +1. Read the full error output carefully +2. Identify the root cause from error messages +3. Attempt a targeted fix +4. Re-run to verify the fix +5. Maximum 3 fix-retry cycles before escalating + +**Example:** Build fails with a type error → check for missing import → add it → rebuild. + +--- + +## 4. Escalate with Context + +**When:** Recovery attempts have been exhausted, or the failure requires human judgment. + +**Pattern:** +1. Summarize what was attempted and what failed +2. Include the exact error messages +3. State what you believe the root cause is +4. Suggest next steps or who might be able to help +5. Hand off to the coordinator or the appropriate specialist + +**Example:** After 3 failed build attempts → "Build fails on line 42 with null reference. Tried X, Y, Z. Likely a design issue in the Foo module. Recommend the code owner review." + +--- + +## 5. Graceful Degradation + +**When:** A non-critical step fails but the overall task can still deliver value. + +**Pattern:** +1. Determine if the failed step is critical to the task outcome +2. If non-critical, log the failure and continue +3. Deliver partial results with a clear note of what was skipped +4. Offer to retry the skipped step separately + +**Example:** Generating a report with 5 sections — section 3 data source is unavailable → produce the report with 4 sections, note that section 3 was skipped and why. + +--- + +## Applying These Patterns + +Each agent should reference these patterns in their charter's `## Error Recovery` section, tailored to their domain. The charter should list the agent's most common failure modes and map each to the appropriate pattern above. + +**Selection guide:** + +| Failure Type | Primary Pattern | Fallback Pattern | +|---|---|---| +| Network/API transient | Retry with Backoff | Escalate with Context | +| Tool/dependency missing | Fallback Alternatives | Escalate with Context | +| Build/test error | Diagnose-and-Fix | Escalate with Context | +| Auth/permissions | Retry with Backoff | Escalate with Context | +| Non-critical data missing | Graceful Degradation | — | +| Unknown/novel error | Escalate with Context | — | diff --git a/.squad-templates/skills/external-comms/SKILL.md b/.squad-templates/skills/external-comms/SKILL.md new file mode 100644 index 000000000..9745028f2 --- /dev/null +++ b/.squad-templates/skills/external-comms/SKILL.md @@ -0,0 +1,329 @@ +--- +name: "external-comms" +description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" +domain: "community, communication, workflow" +confidence: "low" +source: "manual (external communications workflow)" +tools: + - name: "github-mcp-server-list_issues" + description: "List open issues for scan candidates and lightweight triage" + when: "Use for recent open issue scans before thread-level review" + - name: "github-mcp-server-issue_read" + description: "Read the full issue, comments, and labels before drafting" + when: "Use after selecting a candidate so the communications owner has complete thread context" + - name: "github-mcp-server-search_issues" + description: "Search for candidate issues or prior squad responses" + when: "Use when filtering by keywords, labels, or duplicate response checks" + - name: "gh CLI" + description: "Fallback for GitHub issue comments and discussions workflows" + when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete" +--- + +## Context + +Phase 1 is **draft-only mode**. + +- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — the communications owner never posts autonomously. +- Every action is logged to `.squad/comms/audit/`. +- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. + +## Patterns + +### 1. Scan + +Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions. + +- Include **open** issues and discussions only. +- Filter for items with **no squad team response**. +- Limit to items created in the last 7 days. +- Exclude items labeled `squad:internal` or `wontfix`. +- Include discussions **and** issues in the same sweep. +- Phase 1 scope is **issues and discussions only** — do not draft PR replies. + +### Discussion Handling (Phase 1) + +Discussions use the GitHub Discussions API, which differs from issues: + +- **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions +- **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) +- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. + +### 2. Classify + +Determine the response type before drafting. + +- Welcome (new contributor) +- Troubleshooting (bug/help) +- Feature guidance (feature request/how-to) +- Redirect (wrong repo/scope) +- Acknowledgment (confirmed, no fix) +- Closing (resolved) +- Technical uncertainty (unknown cause) +- Empathetic disagreement (pushback on a decision or design) +- Information request (need more reproduction details or context) + +### Template Selection Guide + +| Signal in Issue/Discussion | → Response Type | Template | +|---------------------------|-----------------|----------| +| New contributor (0 prior issues) | Welcome | T1 | +| Error message, stack trace, "doesn't work" | Troubleshooting | T2 | +| "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 | +| Wrong repo, out of scope for Squad | Redirect | T4 | +| Confirmed bug, no fix available yet | Acknowledgment | T5 | +| Fix shipped, PR merged that resolves issue | Closing | T6 | +| Unclear cause, needs investigation | Technical Uncertainty | T7 | +| Author disagrees with a decision or design | Empathetic Disagreement | T8 | +| Need more reproduction info or context | Information Request | T9 | + +Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary. + +### Confidence Classification + +| Confidence | Criteria | Example | +|-----------|----------|---------| +| 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" | +| 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) | +| 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" | + +**Auto-escalation rules:** +- Any mention of competitors → 🔴 +- Any mention of pricing/licensing → 🔴 +- Author has >3 follow-up comments without resolution → 🔴 +- Question references a closed-wontfix issue → 🔴 + +### 3. Draft + +Use the humanizer skill for every draft. + +- Complete **Thread-Read Verification** before writing. +- Read the **full thread**, including all comments, before writing. +- Select the matching template from the **Template Selection Guide** and record the template ID in the review notes. +- Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it. +- Validate the draft against the humanizer anti-patterns. +- Flag long threads (`>10` comments) with `⚠️`. + +### Thread-Read Verification + +Before drafting, the communications owner MUST verify complete thread coverage: + +1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. +2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. +3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}" +4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary +5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column + +### 4. Present + +Show drafts for review in this exact format: + +```text +📝 Community Response Drafts +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +Each full draft must begin with the thread summary line: +`Thread: {N} comments, last activity {date}, {summary of key points}` + +### 5. Human Action + +Wait for explicit human direction before anything is posted. + +- `comms approve 1 3` — approve drafts 1 and 3 +- `comms edit 2` — edit draft 2 +- `comms skip` — skip all +- `banana` — freeze all pending (safe word) + +### Rollback — Bad Post Recovery + +If a posted response turns out to be wrong, inappropriate, or needs correction: + +1. **Delete the comment:** + - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` + - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` +2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content +3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle +4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case + +**Safe word — `banana`:** +- Immediately freezes all pending drafts in the review queue +- No new scans or drafts until `comms resume` is issued +- Audit entry logged with halter identity and reason + +### 6. Post + +After approval: + +- Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. +- The communications owner helps by preparing the CLI command. +- Write the audit entry after the posting action. + +### 7. Audit + +Log every action. + +- Location: `.squad/comms/audit/{timestamp}.md` +- Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table +- Universal required fields: `timestamp`, `action` +- All other fields are conditional on the action type + +## Examples + +These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it. + +### Example scan command + +```bash +gh issue list --state open --json number,title,author,labels,comments --limit 20 +``` + +### Example review table + +```text +📝 Community Response Drafts +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." | +| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." | +| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +### Example audit entry (post action) + +```markdown +--- +timestamp: "2026-03-16T21:30:00Z" +action: "post" +item_number: 426 +draft_id: 1 +reviewer: "@bradygaster" +--- + +## Context (draft, approve, edit, skip, post, delete actions) +- Thread depth: 3 +- Response type: welcome +- Confidence: 🟢 +- Long thread flag: false + +## Draft Content (draft, edit, post actions) +Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install. + +Hey @newdev! Welcome to Squad 👋 Thanks for opening this. +We reproduced the issue in preview builds and we're checking the regression point now. +Let us know if you can share the command you ran right before the failure. + +## Post Result (post, delete actions) +https://github.com/bradygaster/squad/issues/426#issuecomment-123456 +``` + +### T1 — Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{specific acknowledgment or first answer} +Let us know if you have questions — happy to help! +``` + +### T2 — Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### T3 — Feature Guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### T4 — Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### T5 — Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### T6 — Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### T7 — Technical Uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +### T8 — Empathetic Disagreement + +```text +We hear you, {author}. That's a fair concern. + +The current design choice was driven by {reason}. We know it's not ideal for every use case. + +{what alternatives exist or what trade-off was made} + +If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here! +``` + +### T9 — Information Request + +```text +Thanks for reporting this, {author}! + +To help us dig into this, could you share: +- {specific ask 1} +- {specific ask 2} +- {specific ask 3, if applicable} + +That context will help us narrow down what's happening. Appreciate it! +``` + +## Anti-Patterns + +- ❌ Posting without human review (NEVER — this is the cardinal rule) +- ❌ Drafting without reading full thread (context is everything) +- ❌ Ignoring confidence flags (🔴 items need Lead or human review) +- ❌ Scanning closed issues (only open items) +- ❌ Responding to issues labeled `squad:internal` or `wontfix` +- ❌ Skipping audit logging (every action must be recorded) +- ❌ Drafting for issues where a squad member already responded (avoid duplicates) +- ❌ Drafting pull request responses in Phase 1 (issues/discussions only) +- ❌ Treating templates like loose examples instead of reusable drafting assets +- ❌ Asking for more info without specific requests diff --git a/.squad-templates/skills/fact-checking/SKILL.md b/.squad-templates/skills/fact-checking/SKILL.md new file mode 100644 index 000000000..f7f7873e5 --- /dev/null +++ b/.squad-templates/skills/fact-checking/SKILL.md @@ -0,0 +1,61 @@ +--- +name: fact-checking +description: Review and validate claims using counter-hypothesis testing. Use when verifying technical content, checking references, validating API endpoints, or performing quality assurance on deliverables. +license: MIT +compatibility: Requires access to external references and APIs +metadata: + author: squad + version: "1.0.0" + domain: quality, verification + confidence: low + last_validated: "2026-03-01" +--- + +# Skill: Fact Checking + +## Context +Codifies the challenger agent review output format and methodology so any agent performing fact-checking or review produces consistent, structured output. + +## Pattern + +### Review Methodology + +For every claim or deliverable under review: +1. Ask: "What evidence supports this? What would disprove it?" +2. Generate counter-hypotheses and test them against available data +3. Verify URLs, package names, API endpoints, and external references actually exist +4. Flag confidence levels: ✅ Verified, ⚠️ Unverified, ❌ Contradicted + +### Review Output Format + +When reviewing another agent's work, use this template: + +``` +### Fact Check — {deliverable name} +**Claims verified:** {count} +**Issues found:** {count} + +| # | Claim | Status | Evidence/Notes | +|---|-------|--------|---------------| +| 1 | {claim} | ✅/⚠️/❌ | {supporting or contradicting evidence} | + +**Counter-hypotheses tested:** +- {alternative explanation + result} + +**Verdict:** {PASS / PASS WITH NOTES / NEEDS REVISION} +``` + +### Confidence Levels + +- ✅ **Verified** — evidence confirms the claim +- ⚠️ **Unverified** — cannot confirm or deny; suggest verification method +- ❌ **Contradicted** — evidence disproves the claim + +### Ceremony Integration + +Auto-trigger this skill before any architecture decision, or when an agent claim contains superlatives or percentage thresholds (e.g., "saves 75%", "always", "never"). The coordinator spawns the challenger agent with: + +``` +Challenger — fact-check {agent}'s claim: "{claim}" +Cite evidence for every verdict. Max 3 investigation cycles. +``` \ No newline at end of file diff --git a/.squad-templates/skills/gh-auth-isolation/SKILL.md b/.squad-templates/skills/gh-auth-isolation/SKILL.md new file mode 100644 index 000000000..e4ac1abda --- /dev/null +++ b/.squad-templates/skills/gh-auth-isolation/SKILL.md @@ -0,0 +1,183 @@ +--- +name: "gh-auth-isolation" +description: "Safely manage multiple GitHub identities (EMU + personal) in agent workflows" +domain: "security, github-integration, authentication, multi-account" +confidence: "high" +source: "earned (production usage across 50+ sessions with EMU corp + personal GitHub accounts)" +tools: + - name: "gh" + description: "GitHub CLI for authenticated operations" + when: "When accessing GitHub resources requiring authentication" +--- + +## Context + +Many developers use GitHub through an Enterprise Managed User (EMU) account at work while maintaining a personal GitHub account for open-source contributions. AI agents spawned by Squad inherit the shell's default `gh` authentication — which is usually the EMU account. This causes failures when agents try to push to personal repos, create PRs on forks, or interact with resources outside the enterprise org. + +This skill teaches agents how to detect the active identity, switch contexts safely, and avoid mixing credentials across operations. + +## Patterns + +### Detect Current Identity + +Before any GitHub operation, check which account is active: + +```bash +gh auth status +``` + +Look for: +- `Logged in to github.com as USERNAME` — the active account +- `Token scopes: ...` — what permissions are available +- Multiple accounts will show separate entries + +### Extract a Specific Account's Token + +When you need to operate as a specific user (not the default): + +```bash +# Get the personal account token (by username) +gh auth token --user personaluser + +# Get the EMU account token +gh auth token --user corpalias_enterprise +``` + +**Use case:** Push to a personal fork while the default `gh` auth is the EMU account. + +### Push to Personal Repos from EMU Shell + +The most common scenario: your shell defaults to the EMU account, but you need to push to a personal GitHub repo. + +```bash +# 1. Extract the personal token +$token = gh auth token --user personaluser + +# 2. Push using token-authenticated HTTPS +git push https://personaluser:$token@github.com/personaluser/repo.git branch-name +``` + +**Why this works:** `gh auth token --user` reads from `gh`'s credential store without switching the active account. The token is used inline for a single operation and never persisted. + +### Create PRs on Personal Forks + +When the default `gh` context is EMU but you need to create a PR from a personal fork: + +```bash +# Option 1: Use --repo flag (works if token has access) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." --body "..." + +# Option 2: Temporarily set GH_TOKEN for one command +$env:GH_TOKEN = $(gh auth token --user personaluser) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." +Remove-Item Env:\GH_TOKEN +``` + +### Config Directory Isolation (Advanced) + +For complete isolation between accounts, use separate `gh` config directories: + +```bash +# Personal account operations +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login # Login with personal account (one-time setup) +gh repo clone personaluser/repo + +# EMU account operations (default) +Remove-Item Env:\GH_CONFIG_DIR +gh auth status # Back to EMU account +``` + +**Setup (one-time):** +```bash +# Create isolated config for personal account +mkdir ~/.config/gh-public +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login --web --git-protocol https +``` + +### Shell Aliases for Quick Switching + +Add to your shell profile for convenience: + +```powershell +# PowerShell profile +function ghp { $env:GH_CONFIG_DIR = "$HOME/.config/gh-public"; gh @args; Remove-Item Env:\GH_CONFIG_DIR } +function ghe { gh @args } # Default EMU + +# Usage: +# ghp repo clone personaluser/repo # Uses personal account +# ghe issue list # Uses EMU account +``` + +```bash +# Bash/Zsh profile +alias ghp='GH_CONFIG_DIR=~/.config/gh-public gh' +alias ghe='gh' + +# Usage: +# ghp repo clone personaluser/repo +# ghe issue list +``` + +## Examples + +### ✓ Correct: Agent pushes blog post to personal GitHub Pages + +```powershell +# Agent needs to push to personaluser.github.io (personal repo) +# Default gh auth is corpalias_enterprise (EMU) + +$token = gh auth token --user personaluser +git remote set-url origin https://personaluser:$token@github.com/personaluser/personaluser.github.io.git +git push origin main + +# Clean up — don't leave token in remote URL +git remote set-url origin https://github.com/personaluser/personaluser.github.io.git +``` + +### ✓ Correct: Agent creates a PR from personal fork to upstream + +```powershell +# Fork: personaluser/squad, Upstream: bradygaster/squad +# Agent is on branch contrib/fix-docs in the fork clone + +git push origin contrib/fix-docs # Pushes to fork (may need token auth) + +# Create PR targeting upstream +gh pr create --repo bradygaster/squad --head personaluser:contrib/fix-docs ` + --title "docs: fix installation guide" ` + --body "Fixes #123" +``` + +### ✗ Incorrect: Blindly pushing with wrong account + +```bash +# BAD: Agent assumes default gh auth works for personal repos +git push origin main +# ERROR: Permission denied — EMU account has no access to personal repo + +# BAD: Hardcoding tokens in scripts +git push https://personaluser:ghp_xxxxxxxxxxxx@github.com/personaluser/repo.git main +# SECURITY RISK: Token exposed in command history and process list +``` + +### ✓ Correct: Check before you push + +```bash +# Always verify which account has access before operations +gh auth status +# If wrong account, use token extraction: +$token = gh auth token --user personaluser +git push https://personaluser:$token@github.com/personaluser/repo.git main +``` + +## Anti-Patterns + +- ❌ **Hardcoding tokens** in scripts, environment variables, or committed files. Use `gh auth token --user` to extract at runtime. +- ❌ **Assuming the default `gh` auth works** for all repos. EMU accounts can't access personal repos and vice versa. +- ❌ **Switching `gh auth login`** globally mid-session. This changes the default for ALL processes and can break parallel agents. +- ❌ **Storing personal tokens in `.env`** or `.squad/` files. These get committed by Scribe. Use `gh`'s credential store. +- ❌ **Ignoring token cleanup** after inline HTTPS pushes. Always reset the remote URL to avoid persisting tokens. +- ❌ **Using `gh auth switch`** in multi-agent sessions. One agent switching affects all others sharing the shell. +- ❌ **Mixing EMU and personal operations** in the same git clone. Use separate clones or explicit remote URLs per operation. diff --git a/.squad-templates/skills/gh-aw-enlistment/SKILL.md b/.squad-templates/skills/gh-aw-enlistment/SKILL.md new file mode 100644 index 000000000..7f1f0d4ba --- /dev/null +++ b/.squad-templates/skills/gh-aw-enlistment/SKILL.md @@ -0,0 +1,347 @@ +--- +name: "gh-aw-enlistment" +description: "Enlist a repository into Squad by installing the supported GitHub Agentic Workflows (gh-aw) bootstrap — with strict compilation, an explicit safe-update allowlist, and a human-reviewed bootstrap PR. Never auto-merges." +domain: "github-integration, agentic-workflows, ci-bootstrap, safety-gated-automation" +confidence: "high" +source: "Operationalized from the authoritative Squad gh-aw guide (docs/src/content/docs/guide/gh-aw.md) covering the supported install → compile → validate → bootstrap-PR path." +triggers: [set up Squad agentic workflows, enlist this repo in Squad, enlist my repository in Squad, install Squad gh-aw workflows, install Squad agentic workflows, add Squad gh aw workflows, bootstrap Squad in this repo, onboard this repo to Squad, set up /squad slash commands, gh aw add squad] +tools: + - name: "gh" + description: "GitHub CLI — repo identity, Actions permissions, PR creation, review request, and check watching." + when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR." + - name: "gh aw" + description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set." + when: "Installing the six @dev workflows and compiling them into deterministic .lock.yml files." +--- + +## Context + +Use this skill when a user wants to **enlist a repository into Squad** through +**GitHub Agentic Workflows (`gh aw`)** — e.g. "set up Squad agentic workflows", +"enlist this repo in Squad", or "install Squad gh-aw workflows". The end state is +the `/squad` slash command being live on the repo, delivered as a **human-reviewed +bootstrap pull request** — never an auto-merge. + +This skill **operationalizes** the supported bootstrap path. It does not summarize +it: each step below is a gate with explicit success evidence and **STOP conditions**. +The authoritative source is `docs/src/content/docs/guide/gh-aw.md` (mirrored at +`https://bradygaster.github.io/squad/docs/guide/gh-aw/`). If that guide and this +skill ever disagree, the guide wins — re-read it before proceeding. + +**Portability contract:** resolve every repository identifier (owner, repo, default +branch) **at runtime**. Never hardcode a placeholder like `{owner}/{repo}`. The only +fixed identifier is the Squad source itself — `bradygaster/squad/workflows/...@dev` — +because that is where the workflows are published. + +**Idempotency contract:** the bootstrap is re-runnable. Never clobber existing +workflows, prefer detecting prior state over duplicating it, and **stop clearly** on +any unsafe or ambiguous condition rather than guessing. + +## Patterns + +Run these steps in order. Treat every "STOP" as a hard halt: report the exact +condition and wait for a human decision — do not work around it. + +### 0. Preflight — verify before you touch anything + +```bash +# gh is authenticated +gh auth status + +# Capture repository identity and default branch AT RUNTIME +owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')" +default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')" +echo "Repo: ${owner_repo} Default branch: ${default_branch}" + +# The gh-aw extension must be installed (install once if missing) +gh extension list | grep -q 'github/gh-aw' || gh extension install github/gh-aw + +# Git state must be understood and clean enough to isolate the install +git status --short +``` + +> **Portability — extension check:** the `grep -q` above is bash/Git Bash. On Windows +> PowerShell use: +> `if (-not (gh extension list | Select-String -Quiet 'github/gh-aw')) { gh extension install github/gh-aw }` + +- **STOP** if `gh auth status` is not logged in, or is logged in as the wrong + identity for this repo (see the `gh-auth-isolation` skill to operate as a + specific account without switching the global default). +- **STOP** if `owner_repo` or `default_branch` cannot be resolved. +- **STOP** if the working tree has unrelated uncommitted changes you cannot + account for — the bootstrap must land as an isolated, reviewable change. +- Confirm Copilot is enabled for the repository where checkable; the activation + run and the requested `@copilot` review both depend on it. + +### 1. Allow Actions-created PRs while keeping the default token read-only + +Squad opens PRs through GitHub Actions. Enable that **without** widening the +default workflow token: + +```bash +gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \ + -f default_workflow_permissions=read \ + -F can_approve_pull_request_reviews=true +``` + +Without this, Squad still pushes the generated branch but falls back to an issue +with a manual PR link — and a self-authored PR cannot be self-approved. Keep +`default_workflow_permissions=read`; do not set it to `write`. + +### 2. Isolate the install on a bootstrap branch (preserve existing workflows) + +```bash +git switch -c chore/squad-gh-aw-bootstrap +``` + +- If the branch already exists (a re-run), switch to it instead of recreating it. +- **Never overwrite** an existing `.github/workflows/*.md` or `*.lock.yml` that is + not part of the Squad set. `gh aw add` is additive; if you see it about to + replace an unrelated workflow, **STOP**. + +### 3. Install the six supported workflows — in order, dispatcher first + +```bash +gh aw add \ + bradygaster/squad/workflows/squad.md@dev \ + bradygaster/squad/workflows/squad-implement-worker.md@dev \ + bradygaster/squad/workflows/squad-review.md@dev \ + bradygaster/squad/workflows/squad-deps-worker.md@dev \ + bradygaster/squad/workflows/squad-retro.md@dev \ + bradygaster/squad/workflows/squad-improvement-worker.md@dev +``` + +Keep `squad.md` first: `gh aw add` discovers its worker/reviewer dependencies +while compiling it, and the explicit entries confirm the full surface without +creating duplicates. The installed top-level set is exactly: + +- `squad.md` + `squad.lock.yml` +- `squad-implement-worker.md` + `squad-implement-worker.lock.yml` +- `squad-review.md` + `squad-review.lock.yml` +- `squad-deps-worker.md` + `squad-deps-worker.lock.yml` +- `squad-retro.md` + `squad-retro.lock.yml` +- `squad-improvement-worker.md` + `squad-improvement-worker.lock.yml` + +`squad-improvement-worker` is part of the standard, coherent install above — +not a separate opt-in add-on. It stays dormant until a maintainer approves a +governance-scoped retrospective proposal (see the gh-aw guide's retrospective +auto-implementation section); installing it alongside the other five keeps the +full stack consistent and avoids a second bootstrap pass later. + +Report/proposal-only is the default. Ordinary fixes require the explicit +`"squadRetroAutoImplement": "allow"` setting in `.squad/config.json`; +five action issues and three dispatches per wakeup remain separate caps. +An improvement requires `/squad approve-improvement`, `Approved-Revision:` +and exact `Approved-Path:` lines from a human with write/maintain/admin access. +The dispatcher sends nested issue and approval-comment IDs to the worker; +manual retries use those same IDs. `/squad revoke-improvement` is reserved +without dispatch and is rechecked before outputs. Draft PRs and human merge +remain mandatory; closed-unmerged PRs never cause automatic replacements. +See the guide for content-hash calculation and the one-retry recovery policy. + +`@dev` is intentional — it tracks the branch where new modes and fixes land first. + +### 4. Review the first-install safe-update report — approve ONLY the documented entries + +On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: + + +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Action: **`bradygaster/squad/.github/actions/squad-init`** + + +> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets +> the workflows *reference* so you can approve that surface — it is not asking you +> to supply them. Both secrets are optional, they need not exist, and neither is +> required to enlist a repository. Single-repo activation runs on the built-in +> `github.token`. Configure them only for cross-repo access or elevated +> permissions. Auth precedence: GitHub App token, then the PAT, then +> `github.token`. Never block an enlistment waiting for a credential. + +If — and only if — the report contains exactly those documented entries, complete +the one-time approval: + +```bash +gh aw compile --strict --approve # first install only, when the safe-update warning appears +``` + +- **STOP** if the report lists **any other secret** or **any other action**. Do not + approve. Report the unexpected entry verbatim and wait for a human. +- This `--approve` step is *only* the first-install unblock. It is **not** a + substitute for the final strict compile in the next step. + +### 5. Always run the final strict compile WITHOUT `--approve` + +```bash +gh aw compile --strict +``` + +This must run after any first-install approval and before committing. Success +criteria: + +- All six workflows compile successfully. +- The **only** permitted warning is the known `squad.md` bot-trigger warning: it + configures both slash-command and `github-actions[bot]` triggers, and the bot + trigger is required for controlled worker-continuation dispatches. +- **STOP** on any error, or on **any additional warning** beyond that single + documented one. + +### 6. Require all six source/lock pairs to exist + +```bash +for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker; do + test -f ".github/workflows/${workflow}.md" || { echo "MISSING ${workflow}.md"; exit 1; } + test -f ".github/workflows/${workflow}.lock.yml" || { echo "MISSING ${workflow}.lock.yml"; exit 1; } +done +``` + +- **STOP** and rerun `gh aw compile --strict` if any `.lock.yml` is missing. Do not + open or merge the bootstrap PR until all **twelve** files exist and strict + compilation passes. + +> On Windows PowerShell, the `for`/`test -f` loop above is POSIX. Use an +> equivalent guard (e.g. `Test-Path`) or run it under Git Bash; the *logic* — all +> twelve files must exist — is what matters. + +### 7. Inspect generated files, then stage only the documented surfaces + +Downloaded workflow audit data is local diagnostic output — **do not commit it**. +If `.github/aw/logs/` lacks a `.gitignore`, add one there: + +```gitignore +# Ignore all downloaded workflow logs +* + +# But keep this file +!.gitignore +``` + +`gh aw add` may also create `.vscode/settings.json` (enables Copilot for Markdown +workflow files). This is an **optional editor setting** — the stage command below +intentionally leaves it untracked. Delete it if unwanted, or stage it explicitly +if your team wants to share it. Decide deliberately; do not stage it by accident. + +Stage **only** the documented generated surfaces, then verify the staged set: + +```bash +git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/ +git diff --cached --stat +# No deletions should be staged: +test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: staged deletions"; exit 1; } +``` + +- **STOP** if the staged diff shows **unexpected deletions**, **unexpected secrets**, + edits to **unrelated files**, or committed **log/diagnostic output**. Re-scope with + explicit `git add -- ` — never `git add .`, `git add -A`, or `git commit -a`. + +### 8. Commit, push, and open the bootstrap PR to the captured default branch + +```bash +git commit -m "ci: add Squad agentic workflow" +git push -u origin HEAD +gh pr create \ + --base "${default_branch}" \ + --title "ci: add Squad agentic workflow" \ + --body "Installs and strictly compiles the supported Squad GH-AW workflows." +gh pr edit --add-reviewer @copilot +gh pr checks --watch +``` + +- Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded + `main`. +- Request Copilot review, address feedback, and wait for required checks. + +### 9. Never auto-merge — and explain what comes next + +- **Never** merge the bootstrap PR yourself. Merge happens **only** after human + approval. +- Make the two-PR flow explicit to the user: `/squad cast` runs **only after the + bootstrap PR merges**. Casting analyzes the codebase and opens a **separate, + human-reviewed Cast PR** containing the team, routing, charters, the Copilot + agent, and `meet-the-squad.md`. If a work command (`/squad implement`, + `/squad review`) is run before a team exists, it auto-opens that Cast PR first — + merge it and rerun the original command; do not start a second cast. + +## Examples + +### ✓ Correct: runtime-resolved identity, allowlist honored, human-reviewed + +```bash +owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')" +default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')" + +gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \ + -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true + +git switch -c chore/squad-gh-aw-bootstrap +gh aw add \ + bradygaster/squad/workflows/squad.md@dev \ + bradygaster/squad/workflows/squad-implement-worker.md@dev \ + bradygaster/squad/workflows/squad-review.md@dev \ + bradygaster/squad/workflows/squad-deps-worker.md@dev \ + bradygaster/squad/workflows/squad-retro.md@dev \ + bradygaster/squad/workflows/squad-improvement-worker.md@dev + +# Safe-update report shows ONLY the two documented secrets + squad-init → approve once +gh aw compile --strict --approve +gh aw compile --strict # final, no --approve; only the bot-trigger warning remains + +git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/ +git commit -m "ci: add Squad agentic workflow" +git push -u origin HEAD +gh pr create --base "${default_branch}" \ + --title "ci: add Squad agentic workflow" \ + --body "Installs and strictly compiles the supported Squad GH-AW workflows." +gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT merge +``` + +### ✓ Correct: STOP on an undocumented safe-update entry + +```text +gh aw add reports a third secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) + and is NOT the squad-init action. Do NOT run `--approve`. + Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. +``` + +### ✗ Incorrect: hardcoded target and blanket staging + +```bash +# BAD: hardcoded owner/repo and default branch +gh api --method PUT "repos/acme/widgets/actions/permissions/workflow" ... +gh pr create --base main ... # wrong if the default branch isn't `main` + +# BAD: stages logs, .vscode settings, and anything else that changed +git add -A +git commit -m "add squad" +``` + +### ✗ Incorrect: skipping the final strict compile or auto-merging + +```bash +gh aw compile --strict --approve # approved first install... +# ...then committed WITHOUT the final `gh aw compile --strict` (no --approve). WRONG. +gh pr merge --squash # auto-merge before human review. NEVER. +``` + +## Anti-Patterns + +- ❌ **Hardcoding repository identifiers.** Always resolve `owner/repo` and the + default branch at runtime with `gh repo view`. +- ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only + `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. +- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, + `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + else is a STOP. +- ❌ **Treating `--approve` as the final compile.** Always finish with a plain + `gh aw compile --strict` (no `--approve`). +- ❌ **Tolerating extra warnings.** Only the `squad.md` bot-trigger warning is + allowed; every other warning or error halts the run. +- ❌ **Committing diagnostics.** Never commit `.github/aw/logs/` output; add the + log `.gitignore` if missing. +- ❌ **Clobbering existing workflows.** The install is additive; preserve unrelated + `.github/workflows/` files. +- ❌ **Widening the default token.** Keep `default_workflow_permissions=read`. +- ❌ **Auto-merging.** The bootstrap PR and the later Cast PR are both + human-reviewed. `/squad cast` runs only after the bootstrap PR merges. +- ❌ **Opening the PR before all twelve files exist and strict compile passes.** diff --git a/.squad-templates/skills/git-workflow/SKILL.md b/.squad-templates/skills/git-workflow/SKILL.md new file mode 100644 index 000000000..bfa0b8596 --- /dev/null +++ b/.squad-templates/skills/git-workflow/SKILL.md @@ -0,0 +1,204 @@ +--- +name: "git-workflow" +description: "Squad branching model: dev-first workflow with insiders preview channel" +domain: "version-control" +confidence: "high" +source: "team-decision" +--- + +## Context + +Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.** + +| Branch | Purpose | Publishes | +|--------|---------|-----------| +| `main` | Released, tagged, in-npm code only | `npm publish` on tag | +| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge | +| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync | + +## Branch Naming Convention + +Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}` + +Examples: +- `squad/195-fix-version-stamp-bug` +- `squad/42-add-profile-api` + +## Workflow for Issue Work + +1. **Branch from dev:** + ```bash + git checkout dev + git pull origin dev + git checkout -b squad/{issue-number}-{slug} + ``` + +2. **Mark issue in-progress:** + ```bash + gh issue edit {number} --add-label "status:in-progress" + ``` + +3. **Create draft PR targeting dev:** + ```bash + gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft + ``` + +4. **Do the work.** Make changes, write tests, commit with issue reference. + +5. **Push and mark ready:** + ```bash + git push -u origin squad/{issue-number}-{slug} + gh pr ready + ``` + +6. **After merge to dev:** + ```bash + git checkout dev + git pull origin dev + git branch -d squad/{issue-number}-{slug} + git push origin --delete squad/{issue-number}-{slug} + ``` + +## Parallel Multi-Issue Work (Worktrees) + +When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead. + +### When to Use Worktrees vs Sequential + +| Scenario | Strategy | +|----------|----------| +| Single issue | Standard workflow above — no worktree needed | +| 2+ simultaneous issues in same repo | Worktrees — one per issue | +| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) | + +### Setup + +From the main clone (must be on dev or any branch): + +```bash +# Ensure dev is current +git fetch origin dev + +# Create a worktree per issue — siblings to the main clone +git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev +git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev +``` + +**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`). + +Each worktree: +- Has its own working directory and index +- Is on its own `squad/{issue-number}-{slug}` branch from dev +- Shares the same `.git` object store (disk-efficient) + +### Per-Worktree Agent Workflow + +Each agent operates inside its worktree exactly like the single-issue workflow: + +```bash +cd ../squad-195 + +# Work normally — commits, tests, pushes +git add -A && git commit -m "fix: stamp bug (#195)" +git push -u origin squad/195-fix-stamp-bug + +# Create PR targeting dev +gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft +``` + +All PRs target `dev` independently. Agents never interfere with each other's filesystem. + +### .squad/ State in Worktrees + +The `.squad/` directory 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 agent appends to its own section; union merge reconciles on PR merge to dev +- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only + +### Cleanup After Merge + +After a worktree's PR is merged to dev: + +```bash +# From the main clone +git worktree remove ../squad-195 +git worktree prune # clean stale metadata +git branch -d squad/195-fix-stamp-bug +git push origin --delete squad/195-fix-stamp-bug +``` + +If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state. + +--- + +## Multi-Repo Downstream Scenarios + +When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad): + +### Setup + +Clone downstream repos as siblings to the main repo: + +``` +~/work/ + squad-pr/ # main repo + squad-sdk/ # downstream dependency + user-app/ # consumer project +``` + +Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Squad conventions, use `squad/{issue-number}-{slug}`. + +### Coordinated PRs + +- Create PRs in each repo independently +- Link them in PR descriptions: + ``` + Closes #42 + + **Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature) + ``` +- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli) + +### Local Linking for Testing + +Before pushing, verify cross-repo changes work together: + +```bash +# Node.js / npm +cd ../squad-sdk && npm link +cd ../squad-pr && npm link squad-sdk + +# Go +# Use replace directive in go.mod: +# replace github.com/org/squad-sdk => ../squad-sdk + +# Python +cd ../squad-sdk && pip install -e . +``` + +**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs. + +### Worktrees + Multi-Repo + +These compose naturally. You can have: +- Multiple worktrees in the main repo (parallel issues) +- Separate clones for downstream repos +- Each combination operates independently + +--- + +## Anti-Patterns + +- ❌ Branching from main (branch from dev) +- ❌ PR targeting main directly (target dev) +- ❌ Non-conforming branch names (must be squad/{number}-{slug}) +- ❌ Committing directly to main or dev (use PRs) +- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead) +- ❌ Using worktrees for cross-repo work (use separate clones) +- ❌ Leaving stale worktrees after PR merge (clean up immediately) + +## Promotion Pipeline + +- dev → insiders: Automated sync on green build +- dev → main: Manual merge when ready for stable release, then tag +- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent diff --git a/.squad-templates/skills/github-multi-account/SKILL.md b/.squad-templates/skills/github-multi-account/SKILL.md new file mode 100644 index 000000000..0a2158f33 --- /dev/null +++ b/.squad-templates/skills/github-multi-account/SKILL.md @@ -0,0 +1,95 @@ +--- +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 +author: tamirdresher +--- + +# GitHub Multi-Account — AI-Driven Setup + +## When to Activate +When the user has multiple GitHub accounts (check with `gh auth status`). If you see 2+ accounts listed, this skill applies. + +## What to Do (as the AI agent) + +### Step 1: Detect accounts +Run: `gh auth status` +Look for multiple accounts. Note which usernames are listed. + +### Step 2: Ask the user +Ask: "I see you have multiple GitHub accounts: {list them}. Which one is your personal account and which is your work/EMU account?" + +### Step 3: Run the setup automatically +Once the user confirms, do ALL of this for them: + +```powershell +# 1. Define the functions +$personal = "THEIR_PERSONAL_USERNAME" +$work = "THEIR_WORK_USERNAME" + +# 2. Add to PowerShell profile +$profilePath = $PROFILE.CurrentUserAllHosts +if (!(Test-Path $profilePath)) { New-Item -Path $profilePath -Force | Out-Null } +$existing = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue +if ($existing -notmatch "gh-personal") { + $block = @" + +# === GitHub Multi-Account Aliases === +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 } +Set-Alias ghp gh-personal +Set-Alias ghw gh-work +"@ + Add-Content -Path $profilePath -Value $block +} + +# 3. Create CMD wrappers +$binDir = Join-Path $env:USERPROFILE ".squad\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 + +# 4. Add to PATH +$userPath = [Environment]::GetEnvironmentVariable("PATH", "User") +if ($userPath -notmatch [regex]::Escape($binDir)) { + [Environment]::SetEnvironmentVariable("PATH", "$binDir;$userPath", "User") + $env:PATH = "$binDir;$env:PATH" +} + +# 5. Load in current session +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 } +Set-Alias ghp gh-personal +Set-Alias ghw gh-work +``` + +### Step 4: Verify for the user +Run these and show the results: +```powershell +ghp api user --jq '.login' # should show personal username +ghw api user --jq '.login' # should show work username +``` + +### Step 5: Tell the user +"All set! From now on use `ghp` for personal repos and `ghw` for work repos. I'll use them too." + +## After Setup — Usage Rules + +1. **NEVER** use bare `gh` for repo operations — always `ghp` or `ghw` +2. **NEVER** manually `gh auth switch` — the aliases handle it +3. Determine alias by repo owner: + - Personal account repos → `ghp` / `gh-personal` + - Work/EMU account repos → `ghw` / `gh-work` + +## 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`. + +## 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 } +``` diff --git a/.squad-templates/skills/history-hygiene/SKILL.md b/.squad-templates/skills/history-hygiene/SKILL.md new file mode 100644 index 000000000..b0f61417c --- /dev/null +++ b/.squad-templates/skills/history-hygiene/SKILL.md @@ -0,0 +1,36 @@ +--- +name: history-hygiene +description: Record final outcomes to history.md, not intermediate requests or reversed decisions +domain: documentation, team-collaboration +confidence: high +source: earned (release-history correction incident) +--- + +## Context + +History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. A release incident proved this: history retained an obsolete v0.6.0 target after the user had changed it to v0.8.17. Future spawns read the wrong truth and repeated the mistake. + +## Patterns + +- **Record the final outcome**, not the initial request. +- **Wait for confirmation** before writing to history — don't log intermediate states. +- **If a decision reverses**, update the entry immediately — don't leave stale data. +- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened. + +## Examples + +✓ **Correct:** +- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by the user)" +- "Reverted to Node 18 per the user's explicit request on 2024-01-15" + +✗ **Incorrect:** +- "The user directed v0.6.0" (when later reversed) +- Recording what was *requested* instead of what *actually happened* +- Logging entries before outcome is confirmed + +## Anti-Patterns + +- Writing intermediate or "for now" states to disk +- Attributing decisions without confirming final direction +- Treating history like a draft — history is the source of truth +- Assuming readers will cross-reference or verify; they won't diff --git a/.squad-templates/skills/humanizer/SKILL.md b/.squad-templates/skills/humanizer/SKILL.md new file mode 100644 index 000000000..0932510c2 --- /dev/null +++ b/.squad-templates/skills/humanizer/SKILL.md @@ -0,0 +1,105 @@ +--- +name: "humanizer" +description: "Tone enforcement patterns for external-facing community responses" +domain: "communication, tone, community" +confidence: "low" +source: "manual (external communications workflow)" +--- + +## Context + +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. + +- Tone must be warm, helpful, and human-sounding — never robotic or corporate. +- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. + +## Patterns + +1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!") +2. **Active voice** — "We're looking into this" not "This is being investigated" +3. **Second person** — Address the person directly ("you" not "the user") +4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:" +5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues" +6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!" +7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required" +8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence +9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting +10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold) +11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning +12. **Information request** — Ask for specific details, not open-ended "can you provide more info?" +13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link + +## Examples + +### 1. Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{substantive response} +Let us know if you have questions — happy to help! +``` + +### 2. Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### 3. Feature guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### 4. Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### 5. Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### 6. Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### 7. Technical uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +## Anti-Patterns + +- ❌ Corporate speak: "We appreciate your patience as we investigate this matter" +- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..." +- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked" +- ❌ Dismissive: "This works as designed" without empathy +- ❌ Over-promising: "We'll ship this next week" without commitment from the team +- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" +- ❌ Excessive emoji: More than 1-2 emoji per response +- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead +- ❌ Link-dumping: Pasting URLs without context ("See: https://...") +- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information diff --git a/.squad-templates/skills/init-mode/SKILL.md b/.squad-templates/skills/init-mode/SKILL.md new file mode 100644 index 000000000..5f99e7dab --- /dev/null +++ b/.squad-templates/skills/init-mode/SKILL.md @@ -0,0 +1,104 @@ +--- +name: "init-mode" +description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)" +domain: "orchestration" +confidence: "high" +source: "extracted" +tools: + - name: "ask_user" + description: "Confirm team roster with selectable menu" + when: "Phase 1 proposal — requires explicit user confirmation" +--- + +## Context + +Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2). + +## Patterns + +### Phase 1: Propose the Team + +No team exists yet. Propose one — but **DO NOT create any files until the user confirms.** + +1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey {user}, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.** +2. Ask: *"What are you building? (language, stack, what it does)"* +3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section): + - Determine team size (typically 4–5 + Scribe). + - **Default to descriptive names** (Lead, Frontend, Backend, Tester, etc.) unless the user requests a themed universe. + - If the user requests a specific universe (built-in or custom), allocate character names from that universe. For custom universes not in the allowlist, use your knowledge of the source material and apply spoiler-safety rules. + - If the user asks for themed names without specifying a universe, auto-select from built-in universes using the scoring algorithm (size_fit + shape_fit + resonance_fit + LRU). + - Scribe is always "Scribe" — exempt from casting. + - Ralph is always "Ralph" — exempt from casting. +4. Propose the team with their cast names. Example (names will vary per cast): + +``` +🏗️ Lead — Lead Scope, decisions, code review +⚛️ Frontend — Frontend Dev React, UI, components +🔧 Backend — Backend Dev APIs, database, services +🧪 Tester — Tester Tests, quality, edge cases +📋 Scribe — (silent) Memory, decisions, session logs +🔄 Ralph — (monitor) Work queue, backlog, keep-alive +``` + +5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu: + - **question:** *"Look right?"* + - **choices:** `["Yes, cast this team", "Add someone", "Change a role"]` + +**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.** + +### Phase 2: Create the Team + +**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes"). + +> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms. + +6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/). + +**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id). + +**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing. + +**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks. + +**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches: +``` +.squad/decisions.md merge=union +.squad/agents/*/history.md merge=union +.squad/log/** merge=union +.squad/orchestration-log/** merge=union +``` +The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically. + +7. Say: *"✅ Team cast. Try: '{FirstCastName}, set up the project structure'"* + +8. **Post-setup input sources** (optional — ask after team is created, not during casting): + - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow + - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow + - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section + - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment + - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately. + +## Examples + +**Example flow:** +1. Coordinator detects no team.md → Init Mode +2. Runs `git config user.name` → "{user}" +3. Asks: *"Hey {user}, what are you building?"* +4. User: *"TypeScript CLI tool with GitHub API integration"* +5. Coordinator uses descriptive naming by default +6. Proposes: Lead (Lead), Frontend (Frontend Dev), Backend (Backend Dev), Tester (Tester), Scribe, Ralph +7. Uses `ask_user` with choices → user selects "Yes, cast this team" +8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents +9. Says: *"✅ Team cast. Try: 'Lead, set up the project structure'"* + +## Anti-Patterns + +- ❌ Creating files before user confirms Phase 1 +- ❌ Mixing agents from different universes in the same cast +- ❌ Skipping the `ask_user` tool and assuming confirmation +- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role" +- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows) +- ❌ Forgetting to initialize `.squad/casting/` state files +- ❌ Reading or storing `git config user.email` (PII violation) +- ❌ Rejecting a user's universe choice because it is not in the built-in allowlist +- ❌ Auto-selecting a themed universe when the user didn't ask for one (use descriptive names by default) diff --git a/.squad-templates/skills/iterative-retrieval/SKILL.md b/.squad-templates/skills/iterative-retrieval/SKILL.md new file mode 100644 index 000000000..4d8eea993 --- /dev/null +++ b/.squad-templates/skills/iterative-retrieval/SKILL.md @@ -0,0 +1,165 @@ +--- +name: "iterative-retrieval" +description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work." +domain: "agent-coordination" +confidence: "high" +license: MIT +--- + +# Iterative Retrieval Skill + +Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these +handoffs become vague, cycles multiply, and outputs land without being checked. The +**Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and +requires the coordinator to validate agent output before closing an issue. + +--- + +## Spawn Prompt Template + +Every agent spawn must include the following four sections. Copy and fill in the template: + +``` +## Task +{What you need done — concrete and bounded} + +## WHY this matters +{The motivation and context. What system or user goal does this serve? What breaks if skipped?} + +## Success criteria +{How you will know the output is correct. Be explicit — list acceptance criteria, not vibes.} +Example: +- [ ] File X exists and contains Y +- [ ] No regressions in existing tests +- [ ] PR is open targeting main with description matching the issue + +## Escalation path +{What the agent should do if uncertain or stuck. "Stop and ask me" is valid.} +Example: +- If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision +- If blocked by a dependency → label status:blocked, explain in a comment +- If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator +``` + +--- + +## 3-Cycle Protocol + +| Cycle | Description | Exit condition | +|-------|-------------|----------------| +| **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. | +| **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. | +| **3** | Final attempt with all context from cycles 1–2 | Done or escalate — no cycle 4. | + +### Rules + +1. **After each cycle**, the coordinator evaluates the output against the success criteria + before accepting it or spawning the next cycle. +2. **Objective context forward**: each subsequent spawn includes a summary of what was tried + and what is still missing — not just a repeat of the original task. +3. **Cycle 3 exhausted** → escalate: write a summary to `.squad/decisions/inbox/`, label the + issue `status:needs-decision`, and notify the user. + +--- + +## Coordinator Validation Checklist + +Before accepting agent output and closing an issue, the coordinator must check: + +- [ ] All success criteria from the spawn prompt are met +- [ ] PR exists and description matches the issue (if code work) +- [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes) +- [ ] Agent did not silently skip parts of the task +- [ ] If the agent reported uncertainty — was it resolved or escalated? + +If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas. + +--- + +## When to Escalate vs Retry + +**Retry (cycle N+1)** when: +- Output is structurally correct but missing specific items +- Agent misunderstood scope (provide more context and re-run) +- Partial success — clearly identified remaining delta + +**Escalate** when: +- Requirements are fundamentally unclear (decision needed) +- 3 cycles complete without convergence +- Agent returned conflicting results across cycles +- Task requires elevated permissions or external action +- The work depends on another issue that isn't done yet + +--- + +## Issue Dedup Check (Mandatory) + +Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid +duplicates. + +```bash +# Check for existing open issues before creating a new one +gh issue list --search "" --state open +``` + +- If an open issue already covers the same problem → **comment on it** instead of creating a new one. +- If no duplicate → proceed to create the issue. +- Use 2–3 representative keywords from the planned issue title as the search query. + +--- + +## Mandatory Output Requirement (Research-Then-Execute) + +Every research or analysis task completed under this protocol **MUST** end with at least one +concrete action before the cycle is closed. Acceptable follow-up actions: + +- GitHub issue created documenting the findings and next steps +- PR opened implementing a recommendation +- Decision recorded in `.squad/decisions/inbox/` +- Documented recommendation with a named assignee and due date + +**Pure analysis reports without actionable follow-up will be rejected during triage.** +If no action is warranted, the agent must explicitly state why and get coordinator sign-off. + +--- + +## Anti-Patterns + +- **Spawning without WHY** — agents can't prioritise trade-offs without motivation context. +- **Accepting output without validating** — one failed check avoids merging broken work. +- **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent. +- **Vague success criteria** — "looks good" is not a criterion. Use checkboxes. +- **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong. +- **Creating issues without dedup check** — always search before creating. +- **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work. + +--- + +## Examples + +### Good spawn prompt +``` +## Task +Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining +the 3-cycle rule, WHY format, and validation checklist. + +## WHY this matters +The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded +cycles and outputs go unvalidated — leading to stale issues and silent failures. + +## Success criteria +- [ ] Section "Iterative Retrieval Protocol" exists in charter.md +- [ ] Section documents max-3-cycles rule +- [ ] Section documents WHY format requirement +- [ ] Section contains validation checklist (at least 4 items) +- [ ] No other sections of charter.md are modified + +## Escalation path +If the charter.md format is unclear, check another agent charter as a reference. +If uncertain about content, stop and surface to coordinator. +``` + +### Bad spawn prompt (don't do this) +``` +Update the coordinator charter with the iterative retrieval stuff. +``` diff --git a/.squad-templates/skills/model-selection/SKILL.md b/.squad-templates/skills/model-selection/SKILL.md new file mode 100644 index 000000000..18dcebf47 --- /dev/null +++ b/.squad-templates/skills/model-selection/SKILL.md @@ -0,0 +1,125 @@ +--- +name: "model-selection" +description: "Determines which LLM model to use for each agent spawn" +domain: "orchestration" +confidence: "medium" +source: "extracted" +--- + +# Model Selection + +> Determines which LLM model to use for each agent spawn. + +## SCOPE + +✅ THIS SKILL PRODUCES: +- A resolved `model` parameter for every `task` tool call +- Persistent model preferences in `.squad/config.json` +- Spawn acknowledgments that include the resolved model + +❌ THIS SKILL DOES NOT PRODUCE: +- Code, tests, or documentation +- Model performance benchmarks +- Cost reports or billing artifacts + +## Context + +Squad supports a curated model catalog across three tiers (premium, standard, fast). The coordinator must select the right model for each agent spawn. Users can set persistent preferences that survive across sessions. + +## 5-Layer Model Resolution Hierarchy + +Resolution is **first-match-wins** — the highest layer with a value wins. + +| Layer | Name | Source | Persistence | +|-------|------|--------|-------------| +| **0a** | Per-Agent Config | `.squad/config.json` → `agentModelOverrides.{name}` | Persistent (survives sessions) | +| **0b** | Global Config | `.squad/config.json` → `defaultModel` | Persistent (survives sessions) | +| **1** | Session Directive | User said "use X" in current session | Session-only | +| **2** | Charter Preference | Agent's `charter.md` → `## Model` section | Persistent (in charter) | +| **3** | Task-Aware Auto | Code/prompts → Terra, docs → Luna, visual → Sol | Computed per-spawn | +| **4** | Default | `gpt-5.6-luna` | Hardcoded fallback | + +**Key principle:** Layer 0 (persistent config) beats everything. If the user said "always use opus" and it was saved to config.json, every agent gets opus regardless of role or task type. This is intentional — the user explicitly chose quality over cost. + +## AGENT WORKFLOW + +### On Session Start + +1. READ `.squad/config.json` +2. CHECK for `defaultModel` field — if present, this is the Layer 0 override for all spawns +3. CHECK for `agentModelOverrides` field — if present, these are per-agent Layer 0a overrides +4. STORE both values in session context for the duration + +### On Every Agent Spawn + +1. CHECK Layer 0a: Is there an `agentModelOverrides.{agentName}` in config.json? → Use it. +2. CHECK Layer 0b: Is there a `defaultModel` in config.json? → Use it. +3. CHECK Layer 1: Did the user give a session directive? → Use it. +4. CHECK Layer 2: Does the agent's charter have a `## Model` section? → Use it. +5. CHECK Layer 3: Determine task type: +- Code (implementation, tests, refactoring, bug fixes) → `gpt-5.6-terra` +- Prompts, agent designs → `gpt-5.6-terra` +- Visual/design with image analysis → `gpt-5.6-sol` +- Non-code (docs, planning, triage, changelogs) → `gpt-5.6-luna` +6. FALLBACK Layer 4: `gpt-5.6-luna` +7. INCLUDE model in spawn acknowledgment: `🔧 {Name} ({resolved_model}) — {task}` + +### When User Sets a Preference + +**Trigger phrases:** "always use X", "use X for everything", "switch to X", "default to X" + +1. VALIDATE the model ID against the catalog +2. WRITE `defaultModel` to `.squad/config.json` (merge, don't overwrite) +3. ACKNOWLEDGE: `✅ Model preference saved: {model} — all future sessions will use this until changed.` + +**Per-agent trigger:** "use X for {agent}" + +1. VALIDATE model ID +2. WRITE to `agentModelOverrides.{agent}` in `.squad/config.json` +3. ACKNOWLEDGE: `✅ {Agent} will always use {model} — saved to config.` + +### When User Clears a Preference + +**Trigger phrases:** "switch back to automatic", "clear model preference", "use default models" + +1. REMOVE `defaultModel` from `.squad/config.json` +2. ACKNOWLEDGE: `✅ Model preference cleared — returning to automatic selection.` + +### STOP + +After resolving the model and including it in the spawn template, this skill is done. Do NOT: +- Generate model comparison reports +- Run benchmarks or speed tests +- Create new config files (only modify existing `.squad/config.json`) +- Change the model after spawn (fallback chains handle runtime failures) + +## Config Schema + +`.squad/config.json` model-related fields: + +```json +{ + "version": 1, + "defaultModel": "claude-opus-4.6", + "agentModelOverrides": { + "fenster": "claude-sonnet-4.6", + "mcmanus": "claude-haiku-4.5" + } +} +``` + +- `defaultModel` — applies to ALL agents unless overridden by `agentModelOverrides` +- `agentModelOverrides` — per-agent overrides that take priority over `defaultModel` +- Both fields are optional. When absent, Layers 1-4 apply normally. + +## Fallback Chains + +If a model is unavailable (rate limit, plan restriction), retry within the same tier: + +``` +Premium: gpt-5.6-sol → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-4.6 → (omit model param) +Standard: gpt-5.6-terra → claude-sonnet-5 → claude-sonnet-4.6 → gpt-5.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4.5 → gemini-3.1-pro → (omit model param) +Fast: gpt-5.6-luna → claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini → (omit model param) +``` + +**Never fall UP in tier.** A fast task won't land on a premium model via fallback. diff --git a/.squad-templates/skills/notification-routing/SKILL.md b/.squad-templates/skills/notification-routing/SKILL.md new file mode 100644 index 000000000..42c5cb075 --- /dev/null +++ b/.squad-templates/skills/notification-routing/SKILL.md @@ -0,0 +1,105 @@ +--- +name: "notification-routing" +description: "Route agent notifications to specific channels by type — prevent alert fatigue from single-channel flooding" +domain: "communication" +confidence: "high" +source: "earned" +--- + +## Context + +When a Squad grows beyond a few agents, notifications flood a single channel — failure alerts drown in daily +briefings, tech news buries security findings, and everything gets ignored. This is the pub-sub problem: +a single message queue for everything is a recipe for missed alerts. + +The fix is **topic-based routing**: agents tag notifications with a channel type, and a routing function +sends them to the appropriate destination. + +**Trigger symptoms:** +- Important alerts missed because they're buried in routine notifications +- Team members turning off notifications entirely (signal overwhelm) +- Onboarding friction: "where do I look for X?" + +## Patterns + +### Channel Config Schema + +Define a `.squad/teams-channels.json` (or equivalent) mapping notification types to channel identifiers: + +```json +{ + "teamId": "your-team-id", + "channels": { + "notifications": "squad-alerts", + "tech-news": "tech-news", + "security": "security-findings", + "releases": "release-announcements", + "daily-digest": "daily-digest" + } +} +``` + +Place this in `.squad/` (git-tracked, shared across the team). For platforms that use channel IDs instead of +names (Teams, Slack), store the resolved ID alongside the name to avoid name-collision bugs: + +```json +{ + "channels": { + "notifications": { "name": "squad-alerts", "id": "channel-id-opaque-string" } + } +} +``` + +### CHANNEL: Tag Convention + +Agents prefix their output with `CHANNEL:` to signal where the notification should go: + +``` +CHANNEL:security +Security Reviewer found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5 +``` + +### Routing Dispatcher (shell pseudocode) + +```bash +dispatch_notification() { + local raw_output="$1" + local channel="notifications" # default + + if echo "$raw_output" | grep -qE '^CHANNEL:[a-z][a-z0-9-]*'; then + channel=$(echo "$raw_output" | head -1 | cut -d: -f2) + raw_output=$(echo "$raw_output" | tail -n +2) + fi + + send_notification --channel "$channel" --message "$raw_output" +} +``` + +### Provider-Agnostic Adapter + +The routing layer is provider-agnostic. Plug in your platform adapter: + +``` +.squad/notify-adapter.sh # Teams / Slack / Discord / webhook -- swappable +``` + +The routing config and CHANNEL: tags never change. Only the adapter changes per deployment. + +## Anti-Patterns + +**Never send all notification types to one channel:** +``` +send_notification --channel "general" --message "$anything" +``` + +**Never use display names as identifiers (name collision risk):** +``` +send_to_team --name "Squad" --channel "notifications" +``` + +Resolve channel IDs once at setup. Use IDs at runtime. + +## Distributed Systems Pattern + +This is **pub-sub with topic routing** -- the same principle as Kafka topics, RabbitMQ routing keys, and +AWS SNS topic filtering. Route by type. Each consumer subscribes to the topics it cares about. \ No newline at end of file diff --git a/.squad-templates/skills/personal-squad/SKILL.md b/.squad-templates/skills/personal-squad/SKILL.md new file mode 100644 index 000000000..958031e39 --- /dev/null +++ b/.squad-templates/skills/personal-squad/SKILL.md @@ -0,0 +1,66 @@ +--- +name: "personal-squad" +description: "User-level AI agents that travel with you across projects" +domain: "configuration" +confidence: "medium" +source: "manual" +--- + +# Personal Squad — Skill Document + +## What is a Personal Squad? + +A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session. + +## Directory Structure + +``` +~/Library/Application Support/squad/personal-squad/ # macOS +~/.config/squad/personal-squad/ # Linux +%APPDATA%/squad/personal-squad/ # Windows +├── agents/ +│ ├── {agent-name}/ +│ │ ├── charter.md +│ │ └── history.md +│ └── ... +└── config.json # Optional: personal squad config +``` + +## How It Works + +1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory +2. **Merge:** Personal agents are merged into the session cast alongside project agents +3. **Ghost Protocol:** Personal agents can read project state but not write to it +4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery + +## Commands + +- `squad personal init` — Bootstrap a personal squad directory +- `squad personal list` — List your personal agents +- `squad personal add {name} --role {role}` — Add a personal agent +- `squad personal remove {name}` — Remove a personal agent +- `squad cast` — Show the current session cast (project + personal) + +## Ghost Protocol + +See `templates/ghost-protocol.md` for the full rules. Key points: +- Personal agents advise; project agents execute +- No writes to project `.squad/` state +- Transparent origin tagging in logs +- Project agents take precedence on conflicts + +## Configuration + +Optional `config.json` in the personal squad directory: +```json +{ + "defaultModel": "auto", + "ghostProtocol": true, + "agents": {} +} +``` + +## Environment Variables + +- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery +- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path diff --git a/.squad-templates/skills/pr-review-response/SKILL.md b/.squad-templates/skills/pr-review-response/SKILL.md new file mode 100644 index 000000000..dfe290a56 --- /dev/null +++ b/.squad-templates/skills/pr-review-response/SKILL.md @@ -0,0 +1,268 @@ +--- +name: "pr-review-response" +description: "Teaches agents to reply to PR review comment threads after fixing issues, making resolutions traceable" +domain: "pull-requests, code-review, traceability" +confidence: "low" +source: "observed (agents fix review feedback silently — reviewers can't tell which comments were addressed)" +tools: + - name: "github-mcp-server-pull_request_read" + description: "Read PR review threads and comments" + when: "Step 1 — fetching review comments to understand what needs fixing" + - name: "gh api (REST)" + description: "Reply to review comment threads and resolve threads via GraphQL" + when: "Step 3 — posting reply to each comment thread after fixing" +--- + +## Context + +When an agent fixes code in response to PR review comments (from Copilot, a human reviewer, or any GitHub reviewer), the fix alone is not enough. The reviewer needs to see — on the PR thread itself — which comments were addressed and how. Without replies, comments stay visually unresolved, reviewers must re-read the entire diff to verify fixes, and there's no traceable link between feedback and resolution. + +Use this skill whenever: +- You are fixing code based on PR review feedback +- You are addressing Copilot review suggestions +- You are responding to reviewer-requested changes on a PR +- A squad member hands you review comments to resolve + +## SCOPE + +✅ THIS SKILL PRODUCES: +- Reply comments on each review thread explaining the fix +- Optionally resolved threads (via GraphQL when appropriate) +- Commit messages that reference the PR and review context + +❌ THIS SKILL DOES NOT PRODUCE: +- The code fixes themselves (that's the agent's domain work) +- New review comments or reviews +- PR descriptions or summaries + +## Patterns + +### Step 1: Read the review comments + +**Using MCP tools (preferred when available):** + +``` +github-mcp-server-pull_request_read + method: "get_review_comments" + owner: "{owner}" + repo: "{repo}" + pullNumber: {pr_number} +``` + +This returns review threads with metadata: `isResolved`, `isOutdated`, `isCollapsed`, and their associated comments. Each comment has an `id` you'll need for replies. + +**Using gh CLI (fallback):** + +```bash +gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate +``` + +Each comment object contains `id`, `body`, `path`, `line`, and `in_reply_to_id`. Top-level comments have no `in_reply_to_id` — those are the ones you reply to. + +### Step 2: Fix the code + +Make the actual code changes. This is your normal domain work — the skill doesn't prescribe how to fix, only how to communicate the fix. + +**Track what you changed.** For each review comment, note: +- The comment `id` (top-level, not a reply) +- The file and line referenced +- What you actually changed (brief description) +- The commit SHA after pushing (if available) + +### Step 3: Reply to each review thread + +After fixing and committing, reply to **each** review comment thread individually. + +**REST API call (via gh CLI):** + +```bash +gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \ + -f body="Fixed in {sha_short} — {brief description of what was changed}" +``` + +**Important:** `{comment_id}` must be the ID of the **top-level** comment in the thread. You cannot reply to a reply — only to the original review comment. + +**Example replies:** + +```bash +# Specific and traceable +gh api repos/bradygaster/squad/pulls/42/comments/18234/replies \ + -f body="Fixed in a1b2c3d — switched to path.dirname(squadDirInfo.path) for worktree consistency" + +# When applying a suggested code change +gh api repos/bradygaster/squad/pulls/42/comments/18235/replies \ + -f body="Applied suggestion — updated error message to include the file path for debuggability" + +# When pushing back on a suggestion +gh api repos/bradygaster/squad/pulls/42/comments/18236/replies \ + -f body="Considered but not applied — this path needs to stay absolute because worktree resolution depends on it. See detectSquadDir() in detect-squad-dir.ts." +``` + +### Step 4: Resolve threads (optional, GraphQL only) + +Thread resolution is only available via the GitHub GraphQL API. Use this when your fix fully addresses the comment and no further discussion is needed. + +**First, get the thread IDs** (they're different from comment IDs): + +```bash +gh api graphql -f query=' + query { + repository(owner: "{owner}", name: "{repo}") { + pullRequest(number: {pr_number}) { + reviewThreads(first: 100) { + nodes { + id + isResolved + comments(first: 1) { + nodes { body databaseId } + } + } + } + } + } + } +' +``` + +Match thread IDs to comment IDs using `databaseId`, then resolve: + +```bash +gh api graphql -f query=' + mutation { + resolveReviewThread(input: {threadId: "{thread_node_id}"}) { + thread { id isResolved } + } + } +' +``` + +**When to resolve vs. leave open:** +- ✅ Resolve: You fixed exactly what was requested, no ambiguity +- ❌ Don't resolve: You pushed back, applied a different fix, or the comment needs further discussion +- ❌ Don't resolve: The reviewer is a human — let them confirm and resolve themselves + +**Rule of thumb:** Agent-to-agent threads (e.g., Copilot review → agent fix) can be resolved by the fixer. Human reviewer threads should be left for the human to resolve. + +### Step 5: Commit message traceability + +Commit messages should reference the PR context: + +``` +fix: address review feedback on PR #{pr_number} + +- Switched to path.dirname() for worktree path resolution (comment #18234) +- Updated error message to include file path (comment #18235) + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> +``` + +For single-comment fixes, a shorter format works: + +``` +fix: use path.dirname() for worktree consistency (PR #{pr_number} review) + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> +``` + +## AGENT WORKFLOW (Summary) + +1. **READ** — Fetch review threads using MCP tool or `gh api` +2. **FIX** — Make code changes, tracking comment ID → change mapping +3. **COMMIT** — Push with traceable commit message referencing PR and comments +4. **REPLY** — Post individual reply to each thread via `gh api .../replies` +5. **RESOLVE** — (Optional) Resolve agent-to-agent threads via GraphQL +6. **STOP** — Do not batch-reply, do not skip threads, do not resolve human threads + +## Examples + +### Example: Copilot flags a potential null dereference + +**Review comment (id: 55123):** +> `squadDir` could be undefined here. Consider adding a null check. + +**Agent workflow:** +1. Read the comment via `get_review_comments` +2. Add the null check in `src/cli/core/detect-squad-dir.ts` +3. Commit: `fix: add null check for squadDir (PR #99 review)` +4. Reply: + ```bash + gh api repos/bradygaster/squad/pulls/99/comments/55123/replies \ + -f body="Fixed in f4e5d6c — added early return when squadDir is undefined, matching the pattern in loadConfig()" + ``` +5. Resolve the thread (Copilot → agent, safe to resolve) + +### Example: Multiple review comments on one PR + +**Comments:** +- id: 55123 — "Null check needed" on `detect-squad-dir.ts:42` +- id: 55124 — "Consider using path.join()" on `detect-squad-dir.ts:58` +- id: 55125 — "This log message is too verbose" on `output.ts:15` + +**Agent handles each individually:** +```bash +# Fix all three, commit +git add packages/squad-cli/src/cli/core/detect-squad-dir.ts packages/squad-cli/src/cli/core/output.ts +git commit -m "fix: address 3 review comments on PR #99 + +- Added null check for squadDir (comment #55123) +- Switched to path.join() for cross-platform paths (comment #55124) +- Reduced log verbosity to debug level (comment #55125)" + +git push + +# Reply to each thread individually +gh api repos/bradygaster/squad/pulls/99/comments/55123/replies \ + -f body="Fixed — added early return when squadDir is undefined" + +gh api repos/bradygaster/squad/pulls/99/comments/55124/replies \ + -f body="Fixed — switched to path.join(squadDir, 'config.json') for cross-platform consistency" + +gh api repos/bradygaster/squad/pulls/99/comments/55125/replies \ + -f body="Fixed — changed from console.log to debug() so it only shows with --verbose flag" +``` + +### Example: Handling Copilot suggestion blocks + +Copilot sometimes provides `suggestion` blocks with exact code to apply: + +**Review comment (id: 55130):** +```` +Consider using optional chaining: +```suggestion +const name = config?.agent?.name ?? 'default'; +``` +```` + +**Reply format when applying:** +```bash +gh api repos/bradygaster/squad/pulls/99/comments/55130/replies \ + -f body="Applied suggestion — using optional chaining with nullish coalescing" +``` + +**Reply format when not applying:** +```bash +gh api repos/bradygaster/squad/pulls/99/comments/55130/replies \ + -f body="Not applied — config is guaranteed non-null at this point (validated on line 12). Optional chaining would mask errors." +``` + +### Example: Pushing back on a review comment + +Not every review comment should be accepted. When a suggestion is incorrect or doesn't apply: + +```bash +gh api repos/bradygaster/squad/pulls/99/comments/55140/replies \ + -f body="Considered but not applied — this file is in the zero-dependency bootstrap set (see copilot-instructions.md § Protected Files). Adding path.join() would require importing from the SDK, which breaks the bootstrap constraint." +``` + +Do NOT resolve the thread when pushing back. Leave it open for the reviewer to confirm. + +## Anti-Patterns + +- ❌ **Fixing silently** — Making code changes without replying to the review thread. The reviewer has no way to know which comments were addressed. +- ❌ **Batch-replying "all fixed"** — A single comment saying "Addressed all review feedback" on the PR. Each thread needs its own reply so reviewers can verify individually. +- ❌ **Resolving without explaining** — Marking threads resolved without posting a reply first. The resolution gives no context on what was done. +- ❌ **Resolving human reviewer threads** — Only resolve threads from automated reviewers (Copilot, bots). Let human reviewers confirm and resolve their own threads. +- ❌ **Vague replies** — "Fixed" or "Done" without saying what was changed. The reply should be specific enough that the reviewer doesn't need to re-read the diff. +- ❌ **Replying before pushing** — Reply after your fix is committed and pushed, not before. The reply should reference actual committed code. +- ❌ **Ignoring comments you disagree with** — If you don't apply a suggestion, reply explaining why. Silence looks like you missed it. +- ❌ **Replying to replies** — The REST API only supports replying to top-level review comments. Attempting to reply to a reply will fail with a 404. diff --git a/.squad-templates/skills/pr-screenshots/SKILL.md b/.squad-templates/skills/pr-screenshots/SKILL.md new file mode 100644 index 000000000..fc93e8f77 --- /dev/null +++ b/.squad-templates/skills/pr-screenshots/SKILL.md @@ -0,0 +1,149 @@ +--- +name: "pr-screenshots" +description: "Capture Playwright screenshots and embed them in GitHub PR descriptions" +domain: "pull-requests, visual-review, docs, testing" +confidence: "high" +source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)" +--- + +## Context + +When a PR includes visual changes (docs sites, UI components, generated pages), reviewers +need to see what the PR delivers without checking out the branch. Screenshots belong in +the **PR description body**, not as committed files and not as text descriptions. + +Use this skill whenever: +- A PR touches docs site pages (Astro, Starlight, etc.) +- A PR adds or changes UI components +- A PR generates visual artifacts (TypeDoc, Storybook, diagrams) +- Playwright tests already capture screenshots as part of testing + +## Patterns + +### 1. Capture screenshots with Playwright + +If Playwright tests already exist and produce screenshots, reuse those. Otherwise, +write a minimal capture script: + +```javascript +// scripts/capture-pr-screenshots.mjs +import { chromium } from 'playwright'; + +const browser = await chromium.launch(); +const page = await browser.newPage({ viewport: { width: 1280, height: 720 } }); + +const screenshots = [ + { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' }, + { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' }, +]; + +for (const { url, name } of screenshots) { + await page.goto(url, { waitUntil: 'networkidle' }); + await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false }); +} + +await browser.close(); +``` + +### 2. Host screenshots on a temporary branch + +GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary +images directly. Use a temporary orphan branch to host the images: + +```powershell +# Save current branch +$currentBranch = git branch --show-current + +# Create orphan branch with only screenshot files +git checkout --orphan screenshots-temp +git reset +git add screenshots/*.png +git commit -m "screenshots for PR review" +git push origin screenshots-temp --force + +# Build raw URLs +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" +# Each image: $base/{name}.png + +# Return to working branch +git checkout -f $currentBranch +``` + +### 3. Embed in PR description + +Use `gh pr edit` with the raw URLs embedded as markdown images: + +```powershell +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" + +gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @" +## {PR Title} + +### What this PR delivers +- {bullet points of changes} + +--- + +### Screenshots + +#### {Page/Feature Name} +![{alt text}]($base/{name}.png) + +#### {Another Page} +![{alt text}]($base/{another-name}.png) + +--- + +### To verify locally +```bash +{commands to run locally} +``` +"@ +``` + +### 4. Cleanup after merge + +After the PR is merged, delete the temporary branch: + +```bash +git push origin --delete screenshots-temp +``` + +### 5. Gitignore screenshots locally + +Screenshots are build artifacts — never commit them to feature branches: + +```gitignore +# PR screenshots (hosted on temp branch, not committed to features) +screenshots/ +docs/tests/screenshots/ +``` + +## Examples + +### Example: Docs site PR with 3 pages + +1. Start dev server: `cd docs && npm run dev` +2. Run Playwright tests (they capture screenshots as a side effect) +3. Push screenshots to `screenshots-temp` branch +4. Update PR body with embedded `![...]()` image references +5. Reviewer sees the pages inline without checking out the branch + +### Example: Reusing existing Playwright test screenshots + +If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`: + +```powershell +cd docs && npx playwright test tests/api-reference.spec.mjs +# Screenshots now at docs/tests/screenshots/*.png +# Push those to screenshots-temp and embed in PR +``` + +## Anti-Patterns + +- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale +- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting +- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads +- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern +- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see +- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge diff --git a/.squad-templates/skills/project-conventions/SKILL.md b/.squad-templates/skills/project-conventions/SKILL.md new file mode 100644 index 000000000..48a1861da --- /dev/null +++ b/.squad-templates/skills/project-conventions/SKILL.md @@ -0,0 +1,56 @@ +--- +name: "project-conventions" +description: "Core conventions and patterns for this codebase" +domain: "project-conventions" +confidence: "medium" +source: "template" +--- + +## Context + +> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality. + +## Patterns + +### [Pattern Name] + +Describe a key convention or practice used in this codebase. Be specific about what to do and why. + +### Error Handling + + + + + + +### Testing + + + + + + +### Code Style + + + + + + +### File Structure + + + + + + +## Examples + +``` +// Add code examples that demonstrate your conventions +``` + +## Anti-Patterns + + +- **[Anti-pattern]** — Explanation of what not to do and why. diff --git a/.squad-templates/skills/ralph-two-pass-scan/SKILL.md b/.squad-templates/skills/ralph-two-pass-scan/SKILL.md new file mode 100644 index 000000000..dfe282a87 --- /dev/null +++ b/.squad-templates/skills/ralph-two-pass-scan/SKILL.md @@ -0,0 +1,43 @@ +--- +name: "ralph-two-pass-scan" +description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration" +domain: "work-monitoring" +confidence: "high" +source: "extracted" +--- + +# Skill: Ralph — Two-Pass Issue Scanning +**Confidence:** high +**Domain:** work-monitoring +**Last validated:** 2026-03-24 + +## Context +Cuts GitHub API calls from N+1 to ~7 per round (~72% reduction) by separating list scanning from full hydration. +Addresses the scanning inefficiency described in issue #596. + +## Pattern + +### Pass 1 — Lightweight Scan + +``` +gh issue list --state open --json number,title,labels,assignees --limit 100 +``` + +**Skip hydration if ANY of these match:** + +| Condition | Skip reason | +|-----------|-------------| +| `assignees` non-empty AND no `status:needs-review` | Already owned | +| Labels contain `status:blocked` or `status:waiting-external` | Externally gated | +| Labels contain `status:done` or `status:postponed` | Closed loop | +| Title matches stale/noisy pattern (`[chore]`, `[auto]`) | Low-signal | + +### Pass 2 — Selective Hydration + +For each issue surviving Pass 1: + +``` +gh issue view --json number,title,body,labels,assignees,comments,state +``` + +Then apply normal Ralph triage logic. Rule of thumb: hydrate ≤ 30% of scanned list. If more than 30% survive Pass 1, tighten filter rules. diff --git a/.squad-templates/skills/reflect/SKILL.md b/.squad-templates/skills/reflect/SKILL.md new file mode 100644 index 000000000..6a85b5190 --- /dev/null +++ b/.squad-templates/skills/reflect/SKILL.md @@ -0,0 +1,229 @@ +--- +name: reflect +description: Learning capture system that extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes. Use after user corrections ("no", "wrong"), praise ("perfect", "exactly"), or when discovering edge cases. Complements .squad/agents/{agent}/history.md and .squad/decisions.md. +license: MIT +version: 1.0.0-squad +domain: team-memory, learning +confidence: high +--- + +# Reflect Skill + +**Critical learning capture system** for Squad. Prevents repeating mistakes and preserves successful patterns across sessions. + +Analyze conversations and propose improvements to squad knowledge based on what worked, what didn't, and edge cases discovered. **Every correction is a learning opportunity.** + +--- + +## Integration with Squad Architecture + +**Reflect complements existing Squad knowledge systems:** + +1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates) +2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect +3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md + +**Workflow:** +- Use `reflect` during work to capture learnings +- At session end, review captured learnings +- Promote HIGH confidence patterns → lead agent for decision.md review +- Promote agent-specific patterns → `{agent}/history.md` updates + +--- + +## Triggers + +### 🔴 HIGH Priority (Invoke Immediately) + +| Trigger | Example | Why Critical | +|---------|---------|--------------| +| User correction | "no", "wrong", "not like that", "never do" | Captures mistakes to prevent repetition | +| Architectural insight | "you removed that without understanding why" | Documents design decisions (Chesterton's Fence) | +| Immediate fixes | "debug", "root cause", "fix all" | Learns from errors in real-time | + +### 🟡 MEDIUM Priority (Invoke After Multiple) + +| Trigger | Example | Why Important | +|---------|---------|---------------| +| User praise | "perfect", "exactly", "great" | Reinforces successful patterns | +| Tool preferences | "use X instead of Y", "prefer" | Builds workflow preferences | +| Edge cases | "what if X happens?", "don't forget", "ensure" | Captures scenarios to handle | + +### 🟢 LOW Priority (Invoke at Session End) + +| Trigger | Example | Why Useful | +|---------|---------|------------| +| Repeated patterns | Frequent use of specific commands/tools | Identifies workflow preferences | +| Session end | After complex work | Consolidates all session learnings | + +--- + +## Process + +### Phase 1: Identify Learning Target + +Determine what knowledge system should be updated: + +1. **Agent-specific learning** → `.squad/agents/{agent}/history.md` +2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md` +3. **Skill-specific improvement** → Document in session, recommend to skill owner + +### Phase 2: Analyze Conversation + +Scan for learning signals with confidence levels: + +#### HIGH Confidence: Corrections + +User actively steered or corrected output. + +**Detection patterns:** +- Explicit rejection: "no", "not like that", "that's wrong" +- Strong directives: "never do", "always do", "don't ever" +- User provided alternative implementation + +**Example:** +```text +User: "No, use the azure-devops MCP tool instead of raw API calls" +→ [HIGH] + Add constraint: "Prefer azure-devops MCP tools over REST API" +``` + +#### MEDIUM Confidence: Success Patterns + +Output was accepted or praised. + +**Detection patterns:** +- Explicit praise: "perfect", "great", "yes", "exactly" +- User built on output without modification +- Output was committed without changes + +**Example:** +```text +User: "Perfect, that's exactly what I needed" +→ [MED] + Add preference: "Include usage examples in documentation" +``` + +#### MEDIUM Confidence: Edge Cases + +Scenarios not anticipated. + +**Detection patterns:** +- Questions not answered +- Workarounds user had to apply +- Error handling gaps discovered + +#### LOW Confidence: Preferences + +Accumulated patterns over time. + +--- + +### Phase 3: Propose Learnings + +Present findings: + +```text +┌─────────────────────────────────────────────────────────────┐ +│ REFLECTION: {target (agent/decision/skill)} │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ [HIGH] + Add constraint: "{specific constraint}" │ +│ Source: "{quoted user correction}" │ +│ Target: .squad/decisions/inbox/{agent}-{topic}.md │ +│ │ +│ [MED] + Add preference: "{specific preference}" │ +│ Source: "{evidence from conversation}" │ +│ Target: .squad/agents/{agent}/history.md │ +│ │ +│ [LOW] ~ Note for review: "{observation}" │ +│ Source: "{pattern observed}" │ +│ Target: Session notes only │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ Apply changes? [Y/n/edit] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Confidence Threshold:** + +| Threshold | Action | +|-----------|--------| +| ≥1 HIGH signal | Always propose (user explicitly corrected) | +| ≥2 MED signals | Propose (sufficient pattern) | +| ≥3 LOW signals | Propose (accumulated evidence) | +| 1-2 LOW only | Skip (insufficient evidence) | + +### Phase 4: Persist Learnings + +**ALWAYS show changes before applying.** + +After user approval: + +1. **For Agent History:** + - Append to `.squad/agents/{agent}/history.md` under `## Learnings` section + - Format: Date, assignment context, key learning + +2. **For Team Decisions:** + - Create `.squad/decisions/inbox/{agent}-{topic}.md` + - Lead agent reviews and merges to `decisions.md` if appropriate + +3. **For Skills:** + - Document recommendation in session notes + - Squad lead reviews and routes to skill owner + +--- + +## Usage Examples + +### Example 1: User Correction + +**Conversation:** +``` +Agent: "I'll use grep to search the repository" +User: "No, use the code search tools first, grep is too slow" +``` + +**Reflection Output:** +``` +[HIGH] + Add constraint: "Use code intelligence tools before grep" + Source: "No, use the code search tools first, grep is too slow" + Target: .squad/agents/{agent}/history.md +``` + +### Example 2: Success Pattern + +**Conversation:** +``` +Agent: [Creates PR with detailed description and test plan] +User: "Perfect! This is exactly the format I want for all PRs" +``` + +**Reflection Output:** +``` +[MED] + Add preference: "Include test plan in PR descriptions" + Source: User praised detailed PR format + Target: .squad/decisions/inbox/pr-format.md (for team adoption) +``` + +--- + +## When to Use + +✅ **Use reflect when:** +- User says "no", "wrong", "not like that" (HIGH priority) +- User says "perfect", "exactly", "great" (MED priority) +- You discover edge cases or gaps +- Complex work session with multiple learnings +- At end of sprint/milestone to consolidate patterns + +❌ **Don't use reflect when:** +- Simple one-off questions with no pattern +- User is just exploring ideas (no concrete decisions) +- Learning is already captured in history.md/decisions.md + +--- + +## See Also + +- `.squad/decisions.md` — Team-wide decisions +- `.squad/agents/*/history.md` — Agent-specific learnings +- `.squad/routing.md` — Work assignment patterns diff --git a/.squad-templates/skills/release-process/SKILL.md b/.squad-templates/skills/release-process/SKILL.md new file mode 100644 index 000000000..868adb846 --- /dev/null +++ b/.squad-templates/skills/release-process/SKILL.md @@ -0,0 +1,237 @@ +--- +name: "release-process" +description: "Prepare, publish, recover, and verify Squad insider, preview, and stable releases" +domain: "release" +confidence: "high" +source: "earned" +--- + +# Release Process + +This is the canonical Squad release runbook. Squad has three release channels +and two long-lived branches: + +| Source | Version | GitHub | npm | Standalone | Homebrew/WinGet | +|--------|---------|--------|-----|------------|-----------------| +| Insider dispatch from `dev` | Generated `X.Y.Z-insider.N` | Prerelease | `insider` | Yes | Yes | +| Release dispatch from `dev` | `X.Y.Z-preview.N` | Prerelease | `preview` | Yes | Yes | +| Push to `main` by promotion workflow | `X.Y.Z` | Stable/latest | `latest` | Yes | Yes | + +The repository does not use a staging `preview` branch. Preview is a release +channel, not a branch. + +## Non-negotiable rules + +1. Never create release tags or GitHub Releases manually. `squad-release.yml` + creates both. +2. Never reuse a version. A preview such as `0.14.0-preview.1` and stable + `0.14.0` are separate immutable releases. +3. Keep the root, SDK, and CLI versions identical. +4. Set the CLI's SDK dependency floor to `>=VERSION`; prerelease workspaces do + not match an older stable range. +5. Add an exact `## [VERSION]` entry to `CHANGELOG.md`. +6. Merge release preparation to `dev` and wait for CI before dispatching. +7. Keep separate Homebrew casks and WinGet identifiers for each channel. + +## Required credentials + +Configure these GitHub Actions secrets: + +- `NPM_TOKEN`: an automation-capable npm publish token that does not require an + interactive OTP. +- `HOMEBREW_TAP_TOKEN`: a classic GitHub PAT with `public_repo`, owned by an + account that has write access to `bradygaster/homebrew-squad`. +- `WINGET_CREATE_GITHUB_TOKEN`: a classic GitHub PAT with `public_repo`, owned + by the account that maintains `tamirdresher/winget-pkgs`. + +## Prepare a release + +Verify `dev` and `main` share ancestry before changing versions: + +```bash +git fetch origin dev main +git merge-base origin/dev origin/main +``` + +If that command returns no commit, stop and repair ancestry in a separate PR. + +Choose a unique SemVer version and update all package manifests: + +```bash +VERSION=0.14.0-preview.1 +npm version "$VERSION" --workspaces --include-workspace-root --no-git-tag-version +npm pkg set "dependencies.@bradygaster/squad-sdk=>=$VERSION" \ + --workspace @bradygaster/squad-cli +npm install --package-lock-only +``` + +This updates the root package, both workspaces, and the lockfile. Confirm: + +```bash +node -p "require('semver').valid('$VERSION')" +grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json +grep -F "## [$VERSION]" CHANGELOG.md +npm run build +npx vitest run +``` + +Release preparation lands through a normal PR to `dev`. Do not push directly to +`main`. + +## Publish a preview release + +Preview versions must contain a prerelease suffix, for example +`0.14.0-preview.1`. + +After the release-preparation PR is merged and `dev` CI is green: + +```bash +VERSION=0.14.0-preview.1 +gh workflow run squad-release.yml \ + --ref dev \ + -f confirm_tag="v$VERSION" +gh run watch +``` + +The workflow: + +1. Requires the dispatch ref to be `dev`. +2. Rejects a stable `X.Y.Z` version. +3. Creates `v$VERSION` and a GitHub prerelease. +4. Publishes both npm packages with `--tag preview`. +5. Uploads six standalone archives and `SHA256SUMS.txt`. +6. Updates the `squad-preview` Homebrew cask and + `bradygaster.Squad.Preview` WinGet package. + +Install the resulting preview: + +```bash +npm install -g @bradygaster/squad-cli@preview +``` + +The same preview is available through `brew install --cask squad-preview` and +`winget install --id bradygaster.Squad.Preview --exact`. + +## Publish an insider release + +Start an on-demand snapshot from `dev`: + +```bash +gh workflow run squad-insider-publish.yml --ref dev -f dry_run=false +gh run watch +``` + +The workflow computes the next immutable `X.Y.Z-insider.N` version, publishes +npm `insider`, creates a GitHub prerelease, uploads standalone bundles, updates +the `squad-insider` Homebrew cask, and opens or reuses the +`bradygaster.Squad.Insider` WinGet PR. + +## Publish a stable release + +Stable versions must be exactly `X.Y.Z`. Prepare and merge the stable version +to `dev`, then optionally validate the sanitized merge without changing +`main`: + +```bash +gh workflow run squad-promote.yml --ref dev -f dry_run=true +gh run watch +``` + +Start the real promotion: + +```bash +gh workflow run squad-promote.yml --ref dev -f dry_run=false +gh run watch +``` + +`squad-promote.yml`: + +1. Merges `origin/dev` directly into `main`. +2. Removes `.ai-team/`, `.squad/`, `.ai-team-templates/`, `team-docs/`, and + `docs/proposals/` from the release tree. +3. Rejects unresolved conflicts, prerelease versions, mismatched package + versions, and missing changelog entries. +4. Installs dependencies, builds, and runs release tests. +5. Pushes `main` and explicitly dispatches `squad-release.yml`. + +The explicit dispatch is required because GitHub suppresses push-triggered +workflow runs for commits authenticated with `GITHUB_TOKEN`. The release +workflow creates the stable tag and GitHub Release, publishes npm `latest`, +uploads standalone archives, updates Homebrew, and opens or reuses the WinGet +PR. + +## Verify publication + +Use `insider`, `preview`, or `latest` for `DIST_TAG`: + +```bash +VERSION=0.14.0 +DIST_TAG=latest + +npm view @bradygaster/squad-sdk "dist-tags.$DIST_TAG" +npm view @bradygaster/squad-cli "dist-tags.$DIST_TAG" +gh release view "v$VERSION" +``` + +The npm values must equal `VERSION`. The GitHub Release must contain: + +```text +squad-linux-x64.tar.gz +squad-linux-arm64.tar.gz +squad-darwin-x64.tar.gz +squad-darwin-arm64.tar.gz +squad-win32-x64.zip +squad-win32-arm64.zip +SHA256SUMS.txt +``` + +For every release, also verify the channel's Homebrew cask (`squad`, +`squad-preview`, or `squad-insider`) and WinGet identifier +(`bradygaster.Squad`, `.Preview`, or `.Insider`) reference the new version. + +## Recovery + +The top-level release workflow intentionally does not republish after its tag +already exists. Rerun the failed child job, or dispatch the reusable workflow +from the branch that owns that release channel while building from the +immutable tag. + +Stable recovery: + +```bash +VERSION=0.14.0 +gh workflow run squad-npm-publish.yml --ref main \ + -f version="$VERSION" -f source_ref="v$VERSION" +gh workflow run squad-standalone-release.yml --ref main \ + -f upload=true -f release_tag="v$VERSION" -f source_ref="v$VERSION" +``` + +Preview recovery: + +```bash +VERSION=0.14.0-preview.1 +gh workflow run squad-npm-publish.yml --ref dev \ + -f version="$VERSION" -f source_ref="v$VERSION" +gh workflow run squad-standalone-release.yml --ref dev \ + -f upload=true -f release_tag="v$VERSION" -f source_ref="v$VERSION" +``` + +Publication is idempotent. Existing package versions and release assets are +verified rather than overwritten. npm publication fails instead of silently +moving `latest` or `preview` away from an existing version. + +## After a stable release + +Prepare the next development version in a normal PR to `dev`: + +```bash +NEXT_VERSION=0.15.0-preview.1 +npm version "$NEXT_VERSION" --workspaces --include-workspace-root --no-git-tag-version +npm pkg set "dependencies.@bradygaster/squad-sdk=>=$NEXT_VERSION" \ + --workspace @bradygaster/squad-cli +npm install --package-lock-only +``` + +Do not merge `main` back into `dev`; the promotion commit already has `dev` as +its parent, while the stripped internal state intentionally remains only on +`dev`. diff --git a/.squad-templates/skills/reskill/SKILL.md b/.squad-templates/skills/reskill/SKILL.md new file mode 100644 index 000000000..c9e6184de --- /dev/null +++ b/.squad-templates/skills/reskill/SKILL.md @@ -0,0 +1,92 @@ +--- +name: "reskill" +description: "Team-wide charter and history optimization through skill extraction" +domain: "team-optimization" +confidence: "high" +source: "manual — reduce per-agent context overhead" +--- + +## Context + +When the coordinator hears "team, reskill" (or similar: "optimize context", "slim down charters"), trigger a team-wide optimization pass. The goal: reduce per-agent context consumption by extracting shared patterns from charters and histories into reusable skills. + +This is a periodic maintenance activity. Run whenever charter/history bloat is suspected. + +## Process + +### Step 1: Audit +Read all agent charters and histories. Measure byte sizes. Identify: + +- **Boilerplate** — sections repeated across ≥3 charters with <10% variation (collaboration, model, boundaries template) +- **Shared knowledge** — domain knowledge duplicated in 2+ charters (incident postmortems, technical patterns) +- **Mature learnings** — history entries appearing 3+ times across agents that should be promoted to skills + +### Step 2: Extract +For each identified pattern: +1. Create or update a skill at `.squad/skills/{skill-name}/SKILL.md` +2. Follow the skill template format (frontmatter + Context + Patterns + Examples + Anti-Patterns) +3. Set confidence: low (first observation), medium (2+ agents), high (team-wide) + +### Step 3: Trim +**Charters** — target ≤1.5KB per agent: +- Remove Collaboration section entirely (spawn prompt + agent-collaboration skill covers it) +- Remove Voice section (tagline blockquote at top of charter already captures it) +- Trim Model section to single line: `Preferred: {model}` +- Remove "When I'm unsure" boilerplate from Boundaries +- Remove domain knowledge now covered by a skill — add skill reference comment if helpful +- Keep: Identity, What I Own, unique How I Work patterns, Boundaries (domain list only) + +**Histories** — target ≤8KB per agent: +- Apply history-hygiene skill to any history >12KB +- Promote recurring patterns (3+ occurrences across agents) to skills +- Summarize old entries into `## Core Context` section +- Remove session-specific metadata (dates, branch names, requester names) + +### Step 4: Report +Output a savings table: + +| Agent | Charter Before | Charter After | History Before | History After | Saved | +|-------|---------------|---------------|----------------|---------------|-------| + +Include totals and percentage reduction. + +## Patterns + +### Minimal Charter Template (target format after reskill) + +``` +# {Name} — {Role} + +> {Tagline — one sentence capturing voice and philosophy} + +## Identity +- **Name:** {Name} +- **Role:** {Role} +- **Expertise:** {comma-separated list} + +## What I Own +- {bullet list of owned artifacts/domains} + +## How I Work +- {unique patterns and principles — NOT boilerplate} + +## Boundaries +**I handle:** {domain list} +**I don't handle:** {explicit exclusions} + +## Model +Preferred: {model} +``` + +### Skill Extraction Threshold +- **1 charter** → leave in charter (unique to that agent) +- **2 charters** → consider extracting if >500 bytes of overlap +- **3+ charters** → always extract to a shared skill + +## Anti-Patterns +- Don't delete unique per-agent identity or domain-specific knowledge +- Don't create skills for content only one agent uses +- Don't merge unrelated patterns into a single mega-skill +- Don't remove Model preference line (coordinator needs it for model selection) +- Don't touch `.squad/decisions.md` during reskill +- Don't remove the tagline blockquote — it's the charter's soul in one line diff --git a/.squad-templates/skills/retro-enforcement/SKILL.md b/.squad-templates/skills/retro-enforcement/SKILL.md new file mode 100644 index 000000000..e7d319276 --- /dev/null +++ b/.squad-templates/skills/retro-enforcement/SKILL.md @@ -0,0 +1,148 @@ +# Skill: Retro Enforcement + +## Purpose + +Ensure retrospectives happen on schedule and that their action items are tracked in GitHub Issues — not markdown checklists. + +This skill addresses a specific, measured failure mode: **0% completion rate on markdown retro action items across 6 consecutive retrospectives**. GitHub Issues have an 85%+ completion rate in the same squad. The format was the problem, not the people. + +## Core Function: Test-RetroOverdue + +```powershell +function Test-RetroOverdue { + param( + [string]$LogDir = ".squad/log", + [int]$WindowDays = 7, + [string]$Pattern = "*retrospective*" + ) + + $cutoff = (Get-Date).AddDays(-$WindowDays) + + $retroLogs = Get-ChildItem -Path $LogDir -Filter $Pattern -ErrorAction SilentlyContinue | + Where-Object { $_.LastWriteTime -ge $cutoff } + + return ($retroLogs.Count -eq 0) +} +``` + +### Returns +- `$true` — No retro log found within the window. **Retro is overdue. Block other work.** +- `$false` — At least one retro log found within the window. Proceed normally. + +### Detection Logic + +The function checks `.squad/log/` for any file matching `*retrospective*` dated within the last `$WindowDays` days (default: 7). If none is found, the retro is overdue. + +**File naming convention:** `.squad/log/{ISO8601-timestamp}-retrospective.md` + +Example: `.squad/log/2026-03-24T14-45-00Z-retrospective.md` + +## Coordinator Integration + +Call `Test-RetroOverdue` **at the start of every round**, before building the work queue. + +```powershell +# At round start — before any work queue construction +if (Test-RetroOverdue -LogDir ".squad/log" -WindowDays 7) { + Write-Host "[RETROSPECTIVE] Retrospective overdue. Running before other work." + + # Spawn retro facilitator + Invoke-RetroSession -Mode "catch-up" + + # Wait for retro log to be written + # Then resume normal round +} + +# Proceed with normal work queue +$workQueue = Get-PendingIssues | Sort-Object -Property Priority +``` + +### Blocking Semantics + +When `Test-RetroOverdue` returns `$true`: + +1. **Do not start any other work** until the retro completes +2. **Spawn the facilitator agent** (Scribe or designated) with retro mode +3. **Wait for the log file** to be written to `.squad/log/` +4. **Verify action items** were created as GitHub Issues (not markdown) +5. **Resume normal round** after retro log confirmed + +## Action Item Enforcement + +Every retro action item MUST become a GitHub Issue. The facilitator agent is responsible for this. The coordinator verifies. + +### Verification Check + +```powershell +function Test-RetroActionItemsCreated { + param([string]$RetroLogPath) + + $content = Get-Content $RetroLogPath -Raw + + # Check for Issue references (e.g., #1478, https://github.com/.../issues/1478) + $issueRefs = [regex]::Matches($content, '(?:#\d{3,}|issues/\d{3,})') + + # Check for unclosed markdown checkboxes (bad pattern) + $openCheckboxes = [regex]::Matches($content, '- \[ \]') + + if ($openCheckboxes.Count -gt 0) { + Write-Warning "[RETROSPECTIVE] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues" + return $false + } + + return ($issueRefs.Count -gt 0) +} +``` + +### Why Not Markdown Checklists + +From production data in tamirdresher/tamresearch1: + +| Retro | Action Items Format | Completion | +|-------|---------------------|------------| +| 2025-12-05 | Markdown `- [ ]` | 0/4 = **0%** | +| 2025-12-19 | Markdown `- [ ]` | 0/3 = **0%** | +| 2026-01-09 | Markdown `- [ ]` | 0/5 = **0%** | +| 2026-01-23 | Markdown `- [ ]` | 0/4 = **0%** | +| 2026-02-07 | Markdown `- [ ]` | 0/3 = **0%** | +| 2026-02-21 | Markdown `- [ ]` | 0/4 = **0%** | +| 2026-03-24 | GitHub Issues | 4/4 = **100%** (after enforcement) | + +**Root cause:** Markdown checklists have no assignee, no notifications, no close event, and no query surface. They are invisible to every workflow that drives completion. + +## Cadence Enforcement + +### Recommended schedule +- Weekly squads: window = 7 days +- Bi-weekly squads: window = 14 days + +### Ralph integration example + +```powershell +# ralph-watch.ps1 — round start hook +function Invoke-RoundStart { + # 1. Always check retro first + if (Test-RetroOverdue -LogDir "$RepoRoot/.squad/log" -WindowDays 7) { + Write-Host "[RALPH] Retro overdue — enforcing before work queue" + Invoke-RetroSession + return # Re-enter round after retro completes + } + + # 2. Normal work queue + $issues = Get-ReadyIssues + foreach ($issue in $issues) { + Invoke-WorkItem -Issue $issue + } +} +``` + +## Skill Metadata + +| Field | Value | +|-------|-------| +| **Skill ID** | `retro-enforcement` | +| **Category** | Ceremonies / Process | +| **Trigger** | Coordinator round start | +| **Dependencies** | `.squad/log/` directory, GitHub Issues API | +| **Tested in** | tamirdresher/tamresearch1 (production, March 2026) | +| **Outcome** | Retro cadence restored; action item completion 0% → 100% | diff --git a/.squad-templates/skills/reviewer-protocol/SKILL.md b/.squad-templates/skills/reviewer-protocol/SKILL.md new file mode 100644 index 000000000..1f8e98430 --- /dev/null +++ b/.squad-templates/skills/reviewer-protocol/SKILL.md @@ -0,0 +1,79 @@ +--- +name: "reviewer-protocol" +description: "Reviewer rejection workflow and strict lockout semantics" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +When a team member has a **Reviewer** role (e.g., Tester, Code Reviewer, Lead), they may approve or reject work from other agents. On rejection, the coordinator enforces strict lockout rules to ensure the original author does NOT self-revise. This prevents defensive feedback loops and ensures independent review. + +## Patterns + +### Reviewer Rejection Protocol + +When a team member has a **Reviewer** role: + +- Reviewers may **approve** or **reject** work from other agents. +- On **rejection**, the Reviewer may choose ONE of: + 1. **Reassign:** Require a *different* agent to do the revision (not the original author). + 2. **Escalate:** Require a *new* agent be spawned with specific expertise. +- The Coordinator MUST enforce this. If the Reviewer says "someone else should fix this," the original agent does NOT get to self-revise. +- If the Reviewer approves, work proceeds normally. + +### Strict Lockout Semantics + +When an artifact is **rejected** by a Reviewer: + +1. **The original author is locked out.** They may NOT produce the next version of that artifact. No exceptions. +2. **A different agent MUST own the revision.** The Coordinator selects the revision author based on the Reviewer's recommendation (reassign or escalate). +3. **The Coordinator enforces this mechanically.** Before spawning a revision agent, the Coordinator MUST verify that the selected agent is NOT the original author. If the Reviewer names the original author as the fix agent, the Coordinator MUST refuse and ask the Reviewer to name a different agent. +4. **The locked-out author may NOT contribute to the revision** in any form — not as a co-author, advisor, or pair. The revision must be independently produced. +5. **Lockout scope:** The lockout applies to the specific artifact that was rejected. The original author may still work on other unrelated artifacts. +6. **Lockout duration:** The lockout persists for that revision cycle. If the revision is also rejected, the same rule applies again — the revision author is now also locked out, and a third agent must revise. +7. **Deadlock handling:** If all eligible agents have been locked out of an artifact, the Coordinator MUST escalate to the user rather than re-admitting a locked-out author. + +## Examples + +**Example 1: Reassign after rejection** +1. Runtime Engineer writes authentication module +2. Quality Engineer reviews → rejects: "Error handling is missing. Another engineer should fix this." +3. Coordinator: Runtime Engineer is now locked out of this artifact +4. Coordinator spawns a different engineer to revise the authentication module +5. The revision engineer produces v2 +6. Quality Engineer reviews v2 → approves +7. Lockout clears for next artifact + +**Example 2: Escalate for expertise** +1. Original Author writes TypeScript config +2. Lead reviews → rejects: "Need someone with deeper TS knowledge. Escalate." +3. Coordinator: Original Author is now locked out +4. Coordinator spawns new agent (or existing TS expert) to revise +5. New agent produces v2 +6. Lead reviews v2 + +**Example 3: Deadlock handling** +1. Original Author writes module → rejected +2. Revision Engineer revises → rejected +3. Quality Engineer revises → rejected +4. All 3 eligible agents are now locked out +5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]" + +**Example 4: Reviewer accidentally names original author** +1. Original Author writes module → rejected +2. Quality Engineer says: "The original author should fix the error handling" +3. Coordinator: "The original author is locked out. Please name a different agent." +4. Quality Engineer names a revision engineer +5. Coordinator spawns the revision engineer + +## Anti-Patterns + +- ❌ Allowing the original author to self-revise after rejection +- ❌ Treating the locked-out author as an "advisor" or "co-author" on the revision +- ❌ Re-admitting a locked-out author when deadlock occurs (must escalate to user) +- ❌ Applying lockout across unrelated artifacts (scope is per-artifact) +- ❌ Accepting the Reviewer's assignment when they name the original author (must refuse and ask for a different agent) +- ❌ Clearing lockout before the revision is approved (lockout persists through revision cycle) +- ❌ Skipping verification that the revision agent is not the original author diff --git a/.squad-templates/skills/secret-handling/SKILL.md b/.squad-templates/skills/secret-handling/SKILL.md new file mode 100644 index 000000000..b0576f879 --- /dev/null +++ b/.squad-templates/skills/secret-handling/SKILL.md @@ -0,0 +1,200 @@ +--- +name: secret-handling +description: Never read .env files or write secrets to .squad/ committed files +domain: security, file-operations, team-collaboration +confidence: high +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. + +## Patterns + +### Prohibited File Reads + +**NEVER read these files:** +- `.env` (production secrets) +- `.env.local` (local dev secrets) +- `.env.production` (production environment) +- `.env.development` (development environment) +- `.env.staging` (staging environment) +- `.env.test` (test environment with real credentials) +- Any file matching `.env.*` UNLESS explicitly allowed (see below) + +**Allowed alternatives:** +- `.env.example` (safe — contains placeholder values, no real secrets) +- `.env.sample` (safe — documentation template) +- `.env.template` (safe — schema/structure reference) + +**If you need config info:** +1. **Ask the user directly** — "What's the database connection string?" +2. **Read `.env.example`** — shows structure without exposing secrets +3. **Read documentation** — check `README.md`, `docs/`, config guides + +**NEVER assume you can "just peek at .env to understand the schema."** Use `.env.example` or ask. + +### Prohibited Output Patterns + +**NEVER write these to `.squad/` files:** + +| Pattern Type | Examples | Regex Pattern (for scanning) | +|--------------|----------|-------------------------------| +| API Keys | `OPENAI_API_KEY=sk-proj-...`, `GITHUB_TOKEN=ghp_...` | `[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+` | +| Passwords | `DB_PASSWORD=super_secret_123`, `password: "..."` | `(?:PASSWORD|PASS|PWD)[:=]\s*["']?[^\s"']+` | +| Connection Strings | `postgres://user:pass@host:5432/db`, `Server=...;Password=...` | `(?:postgres|mysql|mongodb)://[^@]+@|(?:Server|Host)=.*(?:Password|Pwd)=` | +| JWT Tokens | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` | `eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+` | +| Private Keys | `-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` | `-----BEGIN [A-Z ]+PRIVATE KEY-----` | +| AWS Credentials | `AKIA...`, `aws_secret_access_key=...` | `AKIA[0-9A-Z]{16}|aws_secret_access_key=[^\s]+` | +| Email Addresses | `user@example.com` (PII violation per team decision) | `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` | + +**What to write instead:** +- Placeholder values: `DATABASE_URL=` +- Redacted references: `API key configured (see .env.example)` +- Architecture notes: "App uses JWT auth — token stored in session" +- Schema documentation: "Requires OPENAI_API_KEY, GITHUB_TOKEN (see .env.example for format)" + +### Scribe Pre-Commit Validation + +**Before committing `.squad/` changes, Scribe 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) +3. **If secrets detected:** + - STOP the commit (do NOT proceed) + - Remove the file from staging: `git reset HEAD ` + - Report to user: + ``` + 🚨 SECRET DETECTED — commit blocked + + File: .squad/decisions/inbox/river-db-config.md + Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod + + This file contains credentials and MUST NOT be committed. + Please remove the secret, replace with placeholder, and try again. + ``` + - Exit with error (never silently skip) + +4. **If no secrets detected:** + - Proceed with commit as normal + +**Implementation note for Scribe:** +- Run validation AFTER staging files, BEFORE calling `git commit` +- Use PowerShell `Select-String` or `git diff --cached` to scan staged content +- Fail loud — secret leaks are unacceptable, blocking the commit is correct behavior + +### Remediation — If a Secret Was Already Committed + +**If you discover a secret in git history:** + +1. **STOP immediately** — do not make more commits +2. **Alert the user:** + ``` + 🚨 CREDENTIAL LEAK DETECTED + + A secret was found in git history: + Commit: abc1234 + File: .squad/decisions/inbox/agent-config.md + Pattern: API_KEY=sk-proj-... + + This requires immediate remediation: + 1. Revoke the exposed credential (regenerate API key, rotate password) + 2. Remove from git history (git filter-repo or BFG) + 3. Force-push the cleaned history + + Do NOT proceed with new work until this is resolved. + ``` +3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools +4. **Wait for user confirmation** before resuming work + +## Examples + +### ✓ Correct: Reading Config Schema + +**Agent needs to know what environment variables are required:** + +``` +Agent: "What environment variables does this app need?" +→ Reads `.env.example`: + OPENAI_API_KEY=sk-... + DATABASE_URL=postgres://user:pass@localhost:5432/db + REDIS_URL=redis://localhost:6379 + +→ Writes to .squad/decisions/inbox/river-env-setup.md: + "App requires three environment variables: + - OPENAI_API_KEY (OpenAI API key, format: sk-...) + - DATABASE_URL (Postgres connection string) + - REDIS_URL (Redis connection string) + See .env.example for full schema." +``` + +### ✗ Incorrect: Reading Live Credentials + +**Agent needs to know database schema:** + +``` +Agent: (reads .env) + DATABASE_URL=postgres://admin:super_secret_pw@prod.example.com:5432/appdb + +→ Writes to .squad/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 +``` + +**Correct approach:** +``` +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: + "Database: Postgres (connection configured in .env). Schema defined in db/migrations/." +``` + +### ✓ Correct: Scribe Pre-Commit Validation + +**Scribe is about to commit:** + +```powershell +# Stage files +git add .squad/ + +# Scan staged content for secrets +$stagedContent = git diff --cached +$secretPatterns = @( + '[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+', + '(?:PASSWORD|PASS|PWD)[:=]\s*["'']?[^\s"'']+', + 'eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+' +) + +$detected = $false +foreach ($pattern in $secretPatterns) { + if ($stagedContent -match $pattern) { + $detected = $true + Write-Host "🚨 SECRET DETECTED: $($matches[0])" + break + } +} + +if ($detected) { + # Remove from staging, report, exit + git reset HEAD .squad/ + Write-Error "Commit blocked — secret detected in staged files" + exit 1 +} + +# Safe to commit +git commit -F $msgFile +``` + +## Anti-Patterns + +- ❌ Reading `.env` "just to check the schema" — use `.env.example` instead +- ❌ Writing "sanitized" connection strings that still contain credentials +- ❌ Assuming "it's just a dev environment" makes secrets safe to commit +- ❌ 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 +- ❌ Extracting "just the host" from a connection string — still leaks infrastructure topology diff --git a/.squad-templates/skills/session-recovery/SKILL.md b/.squad-templates/skills/session-recovery/SKILL.md new file mode 100644 index 000000000..05cfbae60 --- /dev/null +++ b/.squad-templates/skills/session-recovery/SKILL.md @@ -0,0 +1,155 @@ +--- +name: "session-recovery" +description: "Find and resume interrupted Copilot CLI sessions using session_store queries" +domain: "workflow-recovery" +confidence: "high" +source: "earned" +tools: + - name: "sql" + description: "Query session_store database for past session history" + when: "Always — session_store is the source of truth for session history" +--- + +## Context + +Squad agents run in Copilot CLI sessions that can be interrupted — terminal crashes, network drops, machine restarts, or accidental window closes. When this happens, in-progress work may be left in a partially-completed state: branches with uncommitted changes, issues marked in-progress with no active agent, or checkpoints that were never finalized. + +Copilot CLI stores session history in a SQLite database called `session_store` (read-only, accessed via the `sql` tool with `database: "session_store"`). This skill teaches agents how to query that store to detect interrupted sessions and resume work. + +## Patterns + +### 1. Find Recent Sessions + +Query the `sessions` table filtered by time window. Include the last checkpoint to understand where the session stopped: + +```sql +SELECT + s.id, + s.summary, + s.cwd, + s.branch, + s.updated_at, + (SELECT title FROM checkpoints + WHERE session_id = s.id + ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint +FROM sessions s +WHERE s.updated_at >= datetime('now', '-24 hours') +ORDER BY s.updated_at DESC; +``` + +### 2. Filter Out Automated Sessions + +Automated agents (monitors, keep-alive, heartbeat) create high-volume sessions that obscure human-initiated work. Exclude them: + +```sql +SELECT s.id, s.summary, s.cwd, s.updated_at, + (SELECT title FROM checkpoints + WHERE session_id = s.id + ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint +FROM sessions s +WHERE s.updated_at >= datetime('now', '-24 hours') + AND s.id NOT IN ( + SELECT DISTINCT t.session_id FROM turns t + WHERE t.turn_index = 0 + AND (LOWER(t.user_message) LIKE '%keep-alive%' + OR LOWER(t.user_message) LIKE '%heartbeat%') + ) +ORDER BY s.updated_at DESC; +``` + +### 3. Search by Topic (FTS5) + +Use the `search_index` FTS5 table for keyword search. Expand queries with synonyms since this is keyword-based, not semantic: + +```sql +SELECT DISTINCT s.id, s.summary, s.cwd, s.updated_at +FROM search_index si +JOIN sessions s ON si.session_id = s.id +WHERE search_index MATCH 'auth OR login OR token OR JWT' + AND s.updated_at >= datetime('now', '-48 hours') +ORDER BY s.updated_at DESC +LIMIT 10; +``` + +### 4. Search by Working Directory + +```sql +SELECT s.id, s.summary, s.updated_at, + (SELECT title FROM checkpoints + WHERE session_id = s.id + ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint +FROM sessions s +WHERE s.cwd LIKE '%my-project%' + AND s.updated_at >= datetime('now', '-48 hours') +ORDER BY s.updated_at DESC; +``` + +### 5. Get Full Session Context Before Resuming + +Before resuming, inspect what the session was doing: + +```sql +-- Conversation turns +SELECT turn_index, substr(user_message, 1, 200) AS ask, timestamp +FROM turns WHERE session_id = 'SESSION_ID' ORDER BY turn_index; + +-- Checkpoint progress +SELECT checkpoint_number, title, overview +FROM checkpoints WHERE session_id = 'SESSION_ID' ORDER BY checkpoint_number; + +-- Files touched +SELECT file_path, tool_name +FROM session_files WHERE session_id = 'SESSION_ID'; + +-- Linked PRs/issues/commits +SELECT ref_type, ref_value +FROM session_refs WHERE session_id = 'SESSION_ID'; +``` + +### 6. Detect Orphaned Issue Work + +Find sessions that were working on issues but may not have completed: + +```sql +SELECT DISTINCT s.id, s.branch, s.summary, s.updated_at, + sr.ref_type, sr.ref_value +FROM sessions s +JOIN session_refs sr ON s.id = sr.session_id +WHERE sr.ref_type = 'issue' + AND s.updated_at >= datetime('now', '-48 hours') +ORDER BY s.updated_at DESC; +``` + +Cross-reference with `gh issue list --label "status:in-progress"` to find issues that are marked in-progress but have no active session. + +### 7. Resume a Session + +Once you have the session ID: + +```bash +# Resume directly +copilot --resume SESSION_ID +``` + +## Examples + +**Recovering from a crash during PR creation:** +1. Query recent sessions filtered by branch name +2. Find the session that was working on the PR +3. Check its last checkpoint — was the code committed? Was the PR created? +4. Resume or manually complete the remaining steps + +**Finding yesterday's work on a feature:** +1. Use FTS5 search with feature keywords +2. Filter to the relevant working directory +3. Review checkpoint progress to see how far the session got +4. Resume if work remains, or start fresh with the context + +## Anti-Patterns + +- ❌ Searching by partial session IDs — always use full UUIDs +- ❌ Resuming sessions that completed successfully — they have no pending work +- ❌ Using `MATCH` with special characters without escaping — wrap paths in double quotes +- ❌ Skipping the automated-session filter — high-volume automated sessions will flood results +- ❌ Assuming FTS5 is semantic search — it's keyword-based; always expand queries with synonyms +- ❌ Ignoring checkpoint data — checkpoints show exactly where the session stopped diff --git a/.squad-templates/skills/squad-commands/SKILL.md b/.squad-templates/skills/squad-commands/SKILL.md new file mode 100644 index 000000000..652786a00 --- /dev/null +++ b/.squad-templates/skills/squad-commands/SKILL.md @@ -0,0 +1,303 @@ +--- +name: squad-commands +description: > + Categorized catalog of common Squad operations. Coordinator reads this + file and presents it as an interactive menu when the user asks for + available commands or help. +domain: squad-operations +confidence: high +source: first-party +triggers: ["squad commands", "what can squad do", "show me squad options", "slash commands"] +--- + +## Menu Presentation Rules + +When the user triggers this skill ("squad commands", "help", "what can squad do", etc.): + +1. **Category-level menu first.** Present category names as an `ask_user` choice list: + ``` + 📋 Squad Commands — pick a category: + 1. Install & Upgrade + 2. Team Management + 3. Issues & PRs + 4. Plugins & Skills + 5. Model & Cost + 6. Sessions & State + ``` +2. **Drill-down.** After selection, show operation titles in that category as a second `ask_user` list. +3. **Direct match skips the menu.** If the user says "how do I upgrade with state backend," match to the specific entry and go straight to argument collection. +4. **Compact fallback.** If `ask_user` is unavailable, render as a markdown table instead. +5. **Back / Cancel.** Include "← Back to categories" in sub-menus. Include "Cancel" in confirmation prompts. Respect "never mind" / "cancel" at any point. + +**Argument collection:** For entries with `args`, iterate the list sequentially. Use `ask_user` with choices when `choices` is provided; free-text prompt otherwise. If the user says "just do it" or "defaults are fine," skip remaining args and use their defaults. + +**Confirmation template:** +``` +⚠️ This will {action-description}. +{what will change} +Proceed? (yes / no) +``` + +--- + +## Install & Upgrade + +### Upgrade Squad CLI + +- **intent:** upgrade squad, update squad, install latest version, get new version +- **summary:** Upgrade Squad CLI to the latest version for your channel +- **action:** shell +- **command:** squad upgrade +- **args:** + - `state-backend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** false +- **platform_caveats:** Requires terminal. In VS Code, open the integrated terminal and run the command directly. + +### Initialize Squad + +- **intent:** set up squad, initialize squad, create team, start squad in this project +- **summary:** Scaffold Squad in the current directory (idempotent) +- **action:** shell +- **command:** squad init +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires terminal. Recommend a standalone terminal for best results. + +### Switch State Backend + +- **intent:** switch state backend, change state storage, use git-notes, use orphan branch +- **summary:** Change where Squad stores mutable state (config.json) +- **action:** file-edit +- **command:** .squad/config.json → stateBackend +- **args:** + - `stateBackend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** true +- **platform_caveats:** May require migration if switching away from worktree. Show current value and new value before confirming. + +--- + +## Team Management + +### Add Team Member + +- **intent:** add team member, hire agent, add agent, add developer, recruit +- **summary:** Add a new agent to the team roster +- **action:** coordinator +- **command:** Add Team Member flow (Init Mode / Team Mode) +- **args:** + - `role`: What role should this agent fill? (e.g., Frontend Dev, Backend Dev, QA Engineer) + - `name`: Preferred name or casting universe? | default: (auto-cast from active universe) +- **confirm:** false + +### Remove Team Member + +- **intent:** remove team member, fire agent, delete agent, remove developer +- **summary:** Remove an agent and delete their charter and history files +- **action:** coordinator +- **command:** Remove Team Member flow +- **args:** + - `member`: Which team member to remove? (name or role) +- **confirm:** true + +### Reassign Roles + +- **intent:** reassign role, change role, swap roles, update team member role +- **summary:** Update a team member's role in team.md and their charter +- **action:** coordinator +- **command:** Update team.md roster + charter.md +- **args:** + - `member`: Which team member? + - `newRole`: New role? +- **confirm:** false + +### Show Roster + +- **intent:** show roster, who is on the team, list team members, show team, capability profile +- **summary:** Display the current team roster and capability profile +- **action:** coordinator +- **command:** Direct Mode — read team.md, answer +- **args:** (none) +- **confirm:** false + +--- + +## Issues & PRs + +### Connect GitHub Repo + +- **intent:** connect github, enable issues, set up issues, link repository, github issues mode +- **summary:** Connect this project to GitHub Issues via gh auth +- **action:** coordinator +- **command:** GitHub Issues Mode (connection flow) +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires `gh auth login` to have been run in the terminal. + +### Triage Issues + +- **intent:** triage issues, review issues, assign issues, label issues +- **summary:** Run the Lead triage flow on open GitHub issues +- **action:** coordinator +- **command:** GitHub Issues Mode → Lead triage +- **args:** (none) +- **confirm:** false + +### Activate Ralph + +- **intent:** activate ralph, start ralph, ralph go, start work monitor, start auto-work +- **summary:** Activate Ralph — Work Monitor — to pick up and run queued issues +- **action:** coordinator +- **command:** Ralph — Work Monitor triggers +- **args:** (none) +- **confirm:** false + +### Set Ralph Polling Interval + +- **intent:** set ralph interval, change ralph timing, how often does ralph check, ralph every N minutes +- **summary:** Tell Ralph how frequently to poll for new work +- **action:** coordinator +- **command:** Ralph trigger: "Ralph, check every N minutes" +- **args:** + - `interval`: How often should Ralph poll? (in minutes) | default: 10 +- **confirm:** false + +### Start Squad Watch + +- **intent:** start watch, squad watch, monitor issues, watch for issues, auto-triage +- **summary:** Start squad watch to continuously poll and triage issues +- **action:** shell +- **command:** squad watch +- **args:** + - `interval`: Poll interval in minutes | default: 10 +- **confirm:** false +- **platform_caveats:** CLI-only — long-running foreground process. Not viable in VS Code without an integrated terminal. Run: `squad watch --interval {n}` in your terminal. + +--- + +## Plugins & Skills + +### Browse Plugin Marketplace + +- **intent:** browse plugins, explore plugins, what plugins are available, plugin marketplace +- **summary:** Browse available plugins in the Squad marketplace +- **action:** shell +- **command:** squad plugin marketplace browse +- **args:** + - `name`: Plugin name to search for | default: (browse all) +- **confirm:** false + +### Add Marketplace Plugin + +- **intent:** add plugin, install plugin, get plugin from marketplace +- **summary:** Add a plugin from the marketplace to this Squad +- **action:** shell +- **command:** squad plugin marketplace add +- **args:** + - `plugin`: Plugin owner/repo (e.g., owner/plugin-name) +- **confirm:** false + +### Remove Marketplace Plugin + +- **intent:** remove plugin, uninstall plugin, delete plugin +- **summary:** Remove an installed marketplace plugin +- **action:** shell +- **command:** squad plugin marketplace remove +- **args:** + - `name`: Plugin name to remove +- **confirm:** true + +### List Marketplace Plugins + +- **intent:** list plugins, show installed plugins, what plugins do I have +- **summary:** List all plugins registered in this Squad +- **action:** shell +- **command:** squad plugin marketplace list +- **args:** (none) +- **confirm:** false + +### List Installed Skills + +- **intent:** list skills, show skills, what skills are installed, skill catalog +- **summary:** List all skills installed in .squad/skills/ and .copilot/skills/ +- **action:** coordinator +- **command:** Direct Mode — list .squad/skills/ and .copilot/skills/ directories +- **args:** (none) +- **confirm:** false + +--- + +## Model & Cost + +### Set Default Model + +- **intent:** set default model, change model, use gpt, use claude, switch model +- **summary:** Set the default model for all agents in config.json +- **action:** file-edit +- **command:** .squad/config.json → defaultModel +- **args:** + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5, gpt-5.3-codex) +- **confirm:** false + +### Override Per-Agent Model + +- **intent:** set model for agent, agent model override, use different model for one agent +- **summary:** Set a model override for a specific agent in config.json +- **action:** file-edit +- **command:** .squad/config.json → agentModelOverrides.{agentName} +- **args:** + - `agent`: Agent name (must match name in team.md) + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5) +- **confirm:** false + +### Clear Model Preference + +- **intent:** clear model, reset model, remove model preference, use default model +- **summary:** Remove a model override from config.json (reverts to system default) +- **action:** file-edit +- **command:** .squad/config.json → remove defaultModel or agentModelOverrides.{agentName} +- **args:** + - `scope`: Clear default or a specific agent? | choices: {default model, specific agent} | default: default model + - `agent`: Agent name (only if scope = specific agent) +- **confirm:** false + +--- + +## Sessions & State + +### Catch-Up Summary + +- **intent:** catch me up, what happened, status, what did the team do, session summary +- **summary:** Summarize recent agent activity and key decisions +- **action:** coordinator +- **command:** Session catch-up flow (lazy scan) +- **args:** (none) +- **confirm:** false + +### Show Recent Decisions + +- **intent:** show decisions, recent decisions, what decisions were made, decision log +- **summary:** Display recent entries from .squad/decisions.md +- **action:** coordinator +- **command:** Direct Mode — read decisions.md, answer +- **args:** (none) +- **confirm:** false + +### Archive Old Decisions + +- **intent:** archive decisions, clean up decisions, move old decisions, compact decisions +- **summary:** Move old decisions from decisions.md to decisions-archive.md +- **action:** coordinator +- **command:** Move entries older than threshold from .squad/decisions.md → .squad/decisions-archive.md +- **args:** + - `olderThan`: Archive decisions older than how many days? | default: 30 +- **confirm:** true + +### Summarize Agent History + +- **intent:** summarize history, what did agent do, agent history, compress history +- **summary:** Spawn an agent to summarize and compress a team member's history file +- **action:** coordinator +- **command:** Spawn agent with history.md summarization task +- **args:** + - `member`: Which team member's history to summarize? +- **confirm:** false diff --git a/.squad-templates/skills/squad-help/SKILL.md b/.squad-templates/skills/squad-help/SKILL.md new file mode 100644 index 000000000..81bc4ae2a --- /dev/null +++ b/.squad-templates/skills/squad-help/SKILL.md @@ -0,0 +1,97 @@ +--- +name: "squad-help" +description: "How to actually use Squad — Squad is a custom Copilot agent (invoked via the task tool with agent_type='Squad'), not a skill. This file explains the right invocation paths for setting up a team, listing squad commands, and initializing Squad in a new project." +allowedTools: [] +confidence: high +domain: squad-onboarding +--- + +# Skill: squad-help + +> **Quick reference.** If you're reading this because a user said "use squad" or "squad" or "set up a squad", you're in the right place — read on for the correct invocation paths. + +--- + +## Squad is a custom agent, not a skill + +The Squad framework registers a **custom Copilot CLI agent** at `.github/agents/squad.agent.md`. The agent is named **`Squad`** and its description is *"Your AI team. Describe what you're building, get a team of specialists that live in your repo."* + +Copilot CLI agents and skills are different things: + +| Thing | How to invoke | Example | +|---|---|---| +| **Skill** | `skill(name)` tool call or natural-language match | `skill(squad-commands)` | +| **Agent** | `task` tool with `agent_type=` | `task(name="...", agent_type="Squad", prompt="...")` | +| **Slash command** | Built-in CLI keyword | `/agent`, `/skills`, `/mcp` | + +Calling `skill(Squad)` will fail with *"Skill not found: Squad"* because Squad is the agent, not a skill. (`/squad` as a slash command also does not exist — only built-in CLI keywords like `/agent`, `/skills`, `/mcp` are slash commands. There's no way to map a skill name to a slash command without a Copilot CLI feature change.) + +--- + +## How to actually use Squad + +Pick the path that matches the user's intent: + +### A) Invoke the Squad coordinator agent (most common) + +The Squad coordinator orchestrates a team of specialists. It routes work to the right agent, scaffolds a team if none exists, and enforces handoffs. + +```text +task( + name="", + agent_type="Squad", + prompt="" +) +``` + +Use this when the user says things like: +- *"Use Squad to build X"* +- *"Set up an AI team for this project"* +- *"Have the Squad coordinator design Y"* +- *"Spawn Squad"* / *"Squad, help me with ..."* + +### B) See what Squad commands exist + +The `squad-commands` skill is a categorized catalog of common Squad operations. The coordinator presents it as an interactive menu. + +Trigger by natural-language match: `"squad commands"`, `"what can squad do"`, `"show me squad options"`, `"slash commands"`, `"what commands are available"`. + +Use this when the user says things like: +- *"What can Squad do?"* +- *"Show me the squad commands"* +- *"squad help"* + +### C) Initialize Squad in a fresh project + +`squad init` is a **shell command**, not a tool call. The user runs it in their terminal in a project that has no `.squad/` directory yet. + +```bash +squad init +``` + +Do **not** try to invoke this from inside an existing Copilot session — `.squad/` is already initialized if you're reading this file. + +--- + +## What NOT to do + +- ❌ Do not call `skill(Squad)`, `skill(squad)`, or `skill(squad-coordinator)` — Squad is not a skill. +- ❌ Do not type `/squad` expecting a slash command — slash commands are CLI keywords, not skill names. Use `/agent` (browse) or invoke the `Squad` agent via the `task` tool. +- ❌ Do not call `task(agent_type="Squad", …)` for tiny tasks the current agent can handle directly. Squad is for work that needs orchestration; trivial edits do not. + +--- + +## How this skill was discovered + +This skill ships from the Squad SDK templates and is wired into `MANIFEST_SKILL_NAMES`. It lives at `.copilot/skills/squad-help/SKILL.md` so the Copilot CLI's `/skills` loader picks it up alongside the other bundled Squad skills. + +If you removed this skill on purpose, the model will fall back to its own reasoning and may make the lookup mistakes described above. + +--- + +## See also + +- `.github/agents/squad.agent.md` — the actual Squad coordinator agent +- `.copilot/skills/squad-commands/SKILL.md` — the command catalog +- `.copilot/skills/squad-conventions/SKILL.md` — conventions for working on the Squad codebase itself +- `.copilot/skills/squad-version-check/SKILL.md` — version-stamping mechanics diff --git a/.squad-templates/skills/squad-version-check/SKILL.md b/.squad-templates/skills/squad-version-check/SKILL.md new file mode 100644 index 000000000..5f3fd785d --- /dev/null +++ b/.squad-templates/skills/squad-version-check/SKILL.md @@ -0,0 +1,169 @@ +--- +name: "squad-version-check" +description: "Internals of how @bradygaster/squad-cli stamps its version, how `squad upgrade` works (what it preserves vs overwrites), and how to probe the npm registry for the latest version from a coordinator prompt." +allowedTools: [] +confidence: medium +domain: squad-internals +source: "validated in bradygaster/squad#1173 recon (2026-05-26)." +--- + +# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics + +**Confidence:** medium +**Discovered by:** repository investigation +**Date:** 2026-05-26 +**Validated in:** Issue #1173 recon (bradygaster/squad) + +--- + +## What This Skill Covers + +Reusable knowledge about how `@bradygaster/squad-cli` stamps its version into `squad.agent.md`, how `squad upgrade` works, what it preserves vs. overwrites, and how to probe the npm registry for the latest version from a coordinator prompt. + +--- + +## Package & Registry Facts + +- **Package name:** `@bradygaster/squad-cli` +- **Registry:** npm (public) +- **CLI binary:** `squad` (registered via `package.json#bin.squad`) +- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase) + +--- + +## Version Stamping Mechanism + +**Source file:** `dist/cli/core/version.js` + +Three functions: + +### `getPackageVersion()` +Walks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist/cli/core/version.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found. + +### `stampVersion(filePath, version)` +Mutates `squad.agent.md` in three places: +1. HTML comment: `` (must be on the line immediately after frontmatter `---`) +2. Identity line: `- **Version:** {version}` +3. Greeting instruction: backtick-quoted `` `Squad v{version}` `` + +**Called by:** both `init` and `upgrade` — after copying the template to the destination. + +### `readInstalledVersion(filePath)` +Reads the stamped version back from `squad.agent.md`: +1. First tries HTML comment format: `//` +2. Falls back to old frontmatter format: `/^version:\s*"([^"]+)"/m` +3. Returns `'0.0.0'` on any error + +--- + +## `squad upgrade` Behavior + +**Source file:** `dist/cli/core/upgrade.js` + +### What gets overwritten: +- `squad.agent.md` — full overwrite from template, then `stampVersion()` +- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled) +- GitHub Actions workflows — from `templates/workflows/`; non-npm projects get type-aware stubs +- Runs `runMigrations()` after file copy + +### What is PRESERVED: +- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned) +- `agents/*/history.md` (individual agent memory) +- `.squad/config.json` — **never touched**; `stateBackend` survives intact +- User-added files not in TEMPLATE_MANIFEST + +### Self-upgrade path (`selfUpgradeCli()`): +Detects npm/pnpm/yarn via `npm_execpath` and `npm_config_user_agent`. Runs: +- npm: `npm install -g @bradygaster/squad-cli@latest` +- pnpm: `pnpm add -g @bradygaster/squad-cli@latest` +- yarn: `yarn global add @bradygaster/squad-cli@latest` +Use `@insider` tag for insider builds. + +### `compareSemver(a, b)` utility (in upgrade.js): +Returns -1/0/1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` < `0.9.5`). Can be ported directly if needed in prompt logic. + +--- + +## `.squad/config.json` — What It Holds + +```json +{ + "version": 1, + "stateBackend": "worktree" +} +``` + +Other optional fields added by the coordinator at runtime: +- `defaultModel` — global model override for all agent spawns +- `agentModelOverrides.{agentName}` — per-agent model override + +The file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences). + +--- + +## Version-Check Probe (npm Registry) + +Use this one-liner from inside a coordinator prompt to fetch dist-tags: + +``` +npm view @bradygaster/squad-cli dist-tags --json +``` + +- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting. +- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`). +- On any error (network failure, registry unreachable, parse error): show normal greeting. + +--- + +## Upstream OS-Specific Cache + +The CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL. + +**One-liner to read the upstream cache:** +``` +node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}" +``` + +Output semantics: +- Valid JSON `{"latestVersion":"X.Y.Z","checkedAt":N}` → cache hit; use `latestVersion` +- `STALE` → cache expired (older than 24h); treat as no data +- `MISS` → cache missing or corrupt; treat as no data + +**OS-specific cache path:** +- Windows: `%APPDATA%\squad-cli\update-check.json` +- Linux: `~/.config/squad-cli/update-check.json` +- macOS: `~/Library/Application Support/squad-cli/update-check.json` + +--- + +## Repo-Local Cache Convention: `.squad/.cache/version-check.json` + +Used by coordinator for `insider`/`preview` channels (the upstream cache only stores `latest`). + +**Schema:** +```json +{ + "checkedAt": "2026-05-26T14:13:28.492Z", + "currentVersion": "0.9.6-insider.2", + "channel": "insider", + "channelVersion": "0.9.7-insider.1" +} +``` + +**TTL:** 24 hours from `checkedAt`. +**Gitignore:** `.squad/.cache/` is listed in `.gitignore` — cache files are never committed. + +--- + +## Key File Paths (installed CLI) + +| Purpose | Path | +|---|---| +| Version utilities | `dist/cli/core/version.js` | +| Upgrade logic | `dist/cli/core/upgrade.js` | +| Init logic | `dist/cli/core/init.js` | +| Template manifest | `dist/cli/core/templates.js` | +| Copilot install helper | `dist/cli/copilot-install.js` | +| squad.agent.md template | `templates/squad.agent.md.template` | +| Session init reference | `templates/session-init-reference.md` | +| All templates | `templates/` | diff --git a/.squad-templates/skills/squad/SKILL.md b/.squad-templates/skills/squad/SKILL.md new file mode 100644 index 000000000..5feadf4c4 --- /dev/null +++ b/.squad-templates/skills/squad/SKILL.md @@ -0,0 +1,299 @@ +--- +name: squad +description: >- + Squad's command catalog and interactive menu. Invoke via /squad (slash command) or natural language ("squad commands", "what can squad do", "show me squad options"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent. +user-invocable: true +allowedTools: [] +--- + +## Menu Presentation Rules + +When the user triggers this skill (via `/squad` slash command, "squad commands", "help", "what can squad do", etc.): + +1. **Category-level menu first.** Present category names as an `ask_user` choice list: + ``` + 📋 Squad Commands — pick a category: + 1. Install & Upgrade + 2. Team Management + 3. Issues & PRs + 4. Plugins & Skills + 5. Model & Cost + 6. Sessions & State + ``` +2. **Drill-down.** After selection, show operation titles in that category as a second `ask_user` list. +3. **Direct match skips the menu.** If the user says "how do I upgrade with state backend," match to the specific entry and go straight to argument collection. +4. **Compact fallback.** If `ask_user` is unavailable, render as a markdown table instead. +5. **Back / Cancel.** Include "← Back to categories" in sub-menus. Include "Cancel" in confirmation prompts. Respect "never mind" / "cancel" at any point. + +**Argument collection:** For entries with `args`, iterate the list sequentially. Use `ask_user` with choices when `choices` is provided; free-text prompt otherwise. If the user says "just do it" or "defaults are fine," skip remaining args and use their defaults. + +**Confirmation template:** +``` +⚠️ This will {action-description}. +{what will change} +Proceed? (yes / no) +``` + +--- + +## Install & Upgrade + +### Upgrade Squad CLI + +- **intent:** upgrade squad, update squad, install latest version, get new version +- **summary:** Upgrade Squad CLI to the latest version for your channel +- **action:** shell +- **command:** squad upgrade +- **args:** + - `state-backend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** false +- **platform_caveats:** Requires terminal. In VS Code, open the integrated terminal and run the command directly. + +### Initialize Squad + +- **intent:** set up squad, initialize squad, create team, start squad in this project +- **summary:** Scaffold Squad in the current directory (idempotent) +- **action:** shell +- **command:** squad init +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires terminal. Recommend a standalone terminal for best results. + +### Switch State Backend + +- **intent:** switch state backend, change state storage, use git-notes, use orphan branch +- **summary:** Change where Squad stores mutable state (config.json) +- **action:** file-edit +- **command:** .squad/config.json → stateBackend +- **args:** + - `stateBackend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** true +- **platform_caveats:** May require migration if switching away from worktree. Show current value and new value before confirming. + +--- + +## Team Management + +### Add Team Member + +- **intent:** add team member, hire agent, add agent, add developer, recruit +- **summary:** Add a new agent to the team roster +- **action:** coordinator +- **command:** Add Team Member flow (Init Mode / Team Mode) +- **args:** + - `role`: What role should this agent fill? (e.g., Frontend Dev, Backend Dev, QA Engineer) + - `name`: Preferred name or casting universe? | default: (auto-cast from active universe) +- **confirm:** false + +### Remove Team Member + +- **intent:** remove team member, fire agent, delete agent, remove developer +- **summary:** Remove an agent and delete their charter and history files +- **action:** coordinator +- **command:** Remove Team Member flow +- **args:** + - `member`: Which team member to remove? (name or role) +- **confirm:** true + +### Reassign Roles + +- **intent:** reassign role, change role, swap roles, update team member role +- **summary:** Update a team member's role in team.md and their charter +- **action:** coordinator +- **command:** Update team.md roster + charter.md +- **args:** + - `member`: Which team member? + - `newRole`: New role? +- **confirm:** false + +### Show Roster + +- **intent:** show roster, who is on the team, list team members, show team, capability profile +- **summary:** Display the current team roster and capability profile +- **action:** coordinator +- **command:** Direct Mode — read team.md, answer +- **args:** (none) +- **confirm:** false + +--- + +## Issues & PRs + +### Connect GitHub Repo + +- **intent:** connect github, enable issues, set up issues, link repository, github issues mode +- **summary:** Connect this project to GitHub Issues via gh auth +- **action:** coordinator +- **command:** GitHub Issues Mode (connection flow) +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires `gh auth login` to have been run in the terminal. + +### Triage Issues + +- **intent:** triage issues, review issues, assign issues, label issues +- **summary:** Run the Lead triage flow on open GitHub issues +- **action:** coordinator +- **command:** GitHub Issues Mode → Lead triage +- **args:** (none) +- **confirm:** false + +### Activate Ralph + +- **intent:** activate ralph, start ralph, ralph go, start work monitor, start auto-work +- **summary:** Activate Ralph — Work Monitor — to pick up and run queued issues +- **action:** coordinator +- **command:** Ralph — Work Monitor triggers +- **args:** (none) +- **confirm:** false + +### Set Ralph Polling Interval + +- **intent:** set ralph interval, change ralph timing, how often does ralph check, ralph every N minutes +- **summary:** Tell Ralph how frequently to poll for new work +- **action:** coordinator +- **command:** Ralph trigger: "Ralph, check every N minutes" +- **args:** + - `interval`: How often should Ralph poll? (in minutes) | default: 10 +- **confirm:** false + +### Start Squad Watch + +- **intent:** start watch, squad watch, monitor issues, watch for issues, auto-triage +- **summary:** Start squad watch to continuously poll and triage issues +- **action:** shell +- **command:** squad watch +- **args:** + - `interval`: Poll interval in minutes | default: 10 +- **confirm:** false +- **platform_caveats:** CLI-only — long-running foreground process. Not viable in VS Code without an integrated terminal. Run: `squad watch --interval {n}` in your terminal. + +--- + +## Plugins & Skills + +### Browse Plugin Marketplace + +- **intent:** browse plugins, explore plugins, what plugins are available, plugin marketplace +- **summary:** Browse available plugins in the Squad marketplace +- **action:** shell +- **command:** squad plugin marketplace browse +- **args:** + - `name`: Plugin name to search for | default: (browse all) +- **confirm:** false + +### Add Marketplace Plugin + +- **intent:** add plugin, install plugin, get plugin from marketplace +- **summary:** Add a plugin from the marketplace to this Squad +- **action:** shell +- **command:** squad plugin marketplace add +- **args:** + - `plugin`: Plugin owner/repo (e.g., owner/plugin-name) +- **confirm:** false + +### Remove Marketplace Plugin + +- **intent:** remove plugin, uninstall plugin, delete plugin +- **summary:** Remove an installed marketplace plugin +- **action:** shell +- **command:** squad plugin marketplace remove +- **args:** + - `name`: Plugin name to remove +- **confirm:** true + +### List Marketplace Plugins + +- **intent:** list plugins, show installed plugins, what plugins do I have +- **summary:** List all plugins registered in this Squad +- **action:** shell +- **command:** squad plugin marketplace list +- **args:** (none) +- **confirm:** false + +### List Installed Skills + +- **intent:** list skills, show skills, what skills are installed, skill catalog +- **summary:** List all skills installed in .squad/skills/ and .github/skills/ +- **action:** coordinator +- **command:** Direct Mode — list .squad/skills/ and .github/skills/ directories +- **args:** (none) +- **confirm:** false + +--- + +## Model & Cost + +### Set Default Model + +- **intent:** set default model, change model, use gpt, use claude, switch model +- **summary:** Set the default model for all agents in config.json +- **action:** file-edit +- **command:** .squad/config.json → defaultModel +- **args:** + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5, gpt-5.3-codex) +- **confirm:** false + +### Override Per-Agent Model + +- **intent:** set model for agent, agent model override, use different model for one agent +- **summary:** Set a model override for a specific agent in config.json +- **action:** file-edit +- **command:** .squad/config.json → agentModelOverrides.{agentName} +- **args:** + - `agent`: Agent name (must match name in team.md) + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5) +- **confirm:** false + +### Clear Model Preference + +- **intent:** clear model, reset model, remove model preference, use default model +- **summary:** Remove a model override from config.json (reverts to system default) +- **action:** file-edit +- **command:** .squad/config.json → remove defaultModel or agentModelOverrides.{agentName} +- **args:** + - `scope`: Clear default or a specific agent? | choices: {default model, specific agent} | default: default model + - `agent`: Agent name (only if scope = specific agent) +- **confirm:** false + +--- + +## Sessions & State + +### Catch-Up Summary + +- **intent:** catch me up, what happened, status, what did the team do, session summary +- **summary:** Summarize recent agent activity and key decisions +- **action:** coordinator +- **command:** Session catch-up flow (lazy scan) +- **args:** (none) +- **confirm:** false + +### Show Recent Decisions + +- **intent:** show decisions, recent decisions, what decisions were made, decision log +- **summary:** Display recent entries from .squad/decisions.md +- **action:** coordinator +- **command:** Direct Mode — read decisions.md, answer +- **args:** (none) +- **confirm:** false + +### Archive Old Decisions + +- **intent:** archive decisions, clean up decisions, move old decisions, compact decisions +- **summary:** Move old decisions from decisions.md to decisions-archive.md +- **action:** coordinator +- **command:** Move entries older than threshold from .squad/decisions.md → .squad/decisions-archive.md +- **args:** + - `olderThan`: Archive decisions older than how many days? | default: 30 +- **confirm:** true + +### Summarize Agent History + +- **intent:** summarize history, what did agent do, agent history, compress history +- **summary:** Spawn an agent to summarize and compress a team member's history file +- **action:** coordinator +- **command:** Spawn agent with history.md summarization task +- **args:** + - `member`: Which team member's history to summarize? +- **confirm:** false diff --git a/.squad-templates/skills/test-discipline/SKILL.md b/.squad-templates/skills/test-discipline/SKILL.md new file mode 100644 index 000000000..9f85fba96 --- /dev/null +++ b/.squad-templates/skills/test-discipline/SKILL.md @@ -0,0 +1,37 @@ +--- +name: "test-discipline" +description: "Update tests when changing APIs — no exceptions" +domain: "quality" +confidence: "high" +source: "earned (test assertion sync violations)" +--- + +## Context + +When APIs or public interfaces change, tests must be updated in the same commit. When test assertions reference file counts or expected arrays, they must be kept in sync with disk reality. Stale tests block CI for other contributors. + +## Patterns + +- **API changes → test updates (same commit):** If you change a function signature, public interface, or exported API, update the corresponding tests before committing +- **Test assertions → disk reality:** When test files contain expected counts (e.g., `EXPECTED_FEATURES`, `EXPECTED_SCENARIOS`), they must match the actual files on disk +- **Add files → update assertions:** When adding docs pages, features, or any counted resource, update the test assertion array in the same commit +- **CI failures → check assertions first:** Before debugging complex failures, verify test assertion arrays match filesystem state + +## Examples + +✓ **Correct:** +- Changed auth API signature → updated auth.test.ts in same commit +- Added `distributed-mesh.md` to features/ → added `'distributed-mesh'` to EXPECTED_FEATURES array +- Deleted two scenario files → removed entries from EXPECTED_SCENARIOS + +✗ **Incorrect:** +- Changed spawn parameters → committed without updating casting.test.ts (CI breaks for next person) +- Added `built-in-roles.md` → left EXPECTED_FEATURES at old count (PR blocked) +- Test says "expected 7 files" but disk has 25 (assertion staleness) + +## Anti-Patterns + +- Committing API changes without test updates ("I'll fix tests later") +- Treating test assertion arrays as static (they evolve with content) +- Assuming CI passing means coverage is correct (stale assertions can pass while being wrong) +- Leaving gaps for other agents to discover diff --git a/.squad-templates/skills/tiered-memory/SKILL.md b/.squad-templates/skills/tiered-memory/SKILL.md new file mode 100644 index 000000000..badc64671 --- /dev/null +++ b/.squad-templates/skills/tiered-memory/SKILL.md @@ -0,0 +1,220 @@ +--- +name: tiered-memory +description: Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn +domain: memory-management, performance +confidence: design (runtime not yet implemented) +source: design proposal +--- + +# Skill: Tiered Agent Memory + +> **Status (v0.10.0):** This skill describes a **design proposal**, not a shipped runtime. Skill files install via `squad init`/`upgrade`, but the underlying tier scaffolding (`.squad/memory/hot/`, `cold/`, `wiki/`), Scribe promotion logic, and spawn-template tier-aware reads are tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264). Until those land, agents continue to load full `history.md` + `decisions.md` on every spawn. + +## Overview + +Squad agents today load their full context history on every spawn, which grows unboundedly across sessions. The Tiered Agent Memory model proposes a three-tier separation so agents only load the bytes that are actually relevant to the current task, with older context kept available on demand. + +--- + +## Memory Tiers + +### 🔥 Hot Tier — Current Session Context +- **Size target:** keep small (~2–4KB typical) +- **Load policy:** Always loaded. Every spawn includes hot memory by default. +- **Contents:** Current task description, active decisions made this session, immediate blockers, last 3–5 actions taken, who you are talking to right now. +- **Lifetime:** Current session only. Discarded after session ends (Scribe promotes relevant parts to Cold). +- **Purpose:** Provide immediate task context without any latency or load decision. + +### ❄️ Cold Tier — Summarized Cross-Session History +- **Size target:** larger summary, not full transcript (~8–12KB typical) +- **Load policy:** Load on demand. Include only when the task explicitly needs history. +- **Contents:** Summarized past sessions (compressed by Scribe), cross-session decisions, recurring patterns, unresolved issues from prior work. +- **Lifetime:** Rolling window (default proposal: 30 days). Eligible entries are then promoted to Wiki. +- **Purpose:** Answer "what have we tried before?" and "what was decided?" without replaying full transcripts. +- **How to include:** Pass `--include-cold` in spawn template or add `## Cold Memory` section. + +### 📚 Wiki Tier — Durable Structured Knowledge +- **Size target:** variable, structured reference docs +- **Load policy:** Async write, selective read. Load only when task requires domain knowledge. +- **Contents:** Architecture decisions (ADRs), agent charters, routing rules, stable conventions, external API contracts, known platform constraints. +- **Lifetime:** Permanent until explicitly deprecated. +- **Purpose:** Authoritative reference. Not history — structured facts. +- **How to include:** Pass `--include-wiki` or reference specific wiki doc paths in spawn template. + +--- + +## When to Load Each Tier + +| Situation | Hot | Cold | Wiki | +|-----------|-----|------|------| +| New task, no prior context needed | ✅ | ❌ | ❌ | +| Resuming interrupted work | ✅ | ✅ | ❌ | +| Debugging a recurring issue | ✅ | ✅ | ❌ | +| Implementing against a spec/ADR | ✅ | ❌ | ✅ | +| Onboarding to unfamiliar subsystem | ✅ | ❌ | ✅ | +| Post-incident review | ✅ | ✅ | ✅ | + +--- + +## Spawn Template Pattern + +The default spawn prompt should include **Hot tier only**: + +``` +## Memory Context + +### Hot (current session) +{hot_context} +``` + +Add `--include-cold` when the task needs history: +``` +## Memory Context + +### Hot (current session) +{hot_context} + +### Cold (summarized history — load on demand) +See: .squad/memory/cold/{agent-name}.md +``` + +Add `--include-wiki` when the task needs domain knowledge: +``` +## Memory Context + +### Hot (current session) +{hot_context} + +### Wiki (durable reference) +See: .squad/memory/wiki/{topic}.md +``` + +--- + +## Integration with Scribe Agent (design — not yet implemented) + +Scribe is the proposed memory coordinator for this system. Once the runtime lands, Scribe will: + +1. **End of session:** Compress Hot → Cold summary (target: ~10% of session verbosity) +2. **Aged cold entries:** Promote Cold → Wiki for decisions/facts that aged into stable knowledge +3. **On-demand wiki writes:** Any agent can request Scribe to write a wiki entry mid-session + +Until then, see the Scribe charter for current behavior: `.squad/agents/scribe/charter.md` + +--- + +## Implementation Checklist (tracked in #1264) + +- [ ] Scribe writes Hot context file at session start (`.squad/memory/hot/{agent}.md`) +- [ ] Scribe compresses and writes Cold summary at session end +- [ ] Spawn templates default to Hot-only +- [ ] Coordinators add `--include-cold` / `--include-wiki` flags as needed +- [ ] Wiki entries stored in `.squad/memory/wiki/` +- [ ] Cold entries stored in `.squad/memory/cold/` with rolling TTL + +--- + +## References + +- Tracking issue: [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — installation gap + runtime status +- Original design spike: [bradygaster/squad#686](https://github.com/bradygaster/squad/issues/686) — tiered memory implementation plan +- Related: [bradygaster/squad#600](https://github.com/bradygaster/squad/issues/600) — context payload growth + +--- + +## Spawn Template + +# Spawn Template: Agent with Tiered Memory + +Use this template when spawning any Squad agent. By default it loads **Hot tier only**. Add optional sections as needed. + +--- + +## Task + +{task_description} + +## WHY + +{why_this_matters} + +## Success Criteria + +- [ ] {criterion_1} +- [ ] {criterion_2} + +--- + +## Memory Context + +### 🔥 Hot (always included) + +> Paste current session context here (~2–4KB target): + +``` +Current task: {task_description} +Active decisions: {decisions_this_session} +Last actions: {last_3_to_5_actions} +Blockers: {current_blockers_or_none} +Talking to: {current_interlocutor} +``` + +--- + +### ❄️ Cold (include when task needs history — add `--include-cold`) + +> Load on demand. Do not inline unless specifically needed. + +Summarized cross-session history is at: +`.squad/memory/cold/{agent-name}.md` + +Include when: +- Resuming interrupted work +- Debugging a recurring issue +- "What have we tried before?" + +**To load cold memory, add this section and fetch the file before spawning:** + +``` +## Cold Memory Summary +{contents_of_.squad/memory/cold/{agent-name}.md} +``` + +--- + +### 📚 Wiki (include when task needs domain knowledge — add `--include-wiki`) + +> Load on demand. Reference specific wiki docs by path. + +Wiki entries are at: `.squad/memory/wiki/` + +Include when: +- Implementing against an ADR or spec +- Onboarding to unfamiliar subsystem +- Need stable conventions or API contracts + +**To load wiki, add this section and reference the specific doc:** + +``` +## Wiki Reference +{contents_of_.squad/memory/wiki/{topic}.md} +``` + +--- + +## Escalation + +If blocked or uncertain: +- Architecture questions → current architecture owner from `routing.md` +- Security concerns → current security owner from `routing.md` +- Infrastructure/deployment → current delivery owner from `routing.md` +- Memory/history questions → current memory owner from `routing.md` + +--- + +## Notes + +- Hot tier is always included; keep it focused +- Cold adds a summary; only include when history is relevant +- Wiki adds variable size; only include specific relevant docs +- Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn diff --git a/.squad-templates/skills/versioning-policy/SKILL.md b/.squad-templates/skills/versioning-policy/SKILL.md new file mode 100644 index 000000000..59de6f54b --- /dev/null +++ b/.squad-templates/skills/versioning-policy/SKILL.md @@ -0,0 +1,123 @@ +--- +name: "versioning-policy" +description: "SemVer rules for Squad's stable, preview, insider, and local package versions" +domain: "release, versioning, npm, CI" +confidence: "high" +source: "earned (PR #640 workspace resolution incident and automated release channels)" +--- + +## Context + +Squad publishes `@bradygaster/squad-sdk` and +`@bradygaster/squad-cli` from one npm workspace. Their versions and the root +version move together. A mismatched prerelease dependency can make npm silently +resolve an older registry SDK instead of the local workspace. + +## 1. Supported versions + +| Use | Version | Committed branch | +|---|---|---| +| Stable release | `MAJOR.MINOR.PATCH` | `main`, and briefly `dev` during promotion | +| Preview release | `MAJOR.MINOR.PATCH-preview.N` | `dev` | +| Insider snapshot | `MAJOR.MINOR.PATCH-insider.N` | Generated by the insider workflow | +| Local build | `MAJOR.MINOR.PATCH-build.N` | Never committed | + +`preview` is a release channel, not a branch. Stable promotion merges a +sanitized release tree directly from `dev` to `main`. + +## 2. Package versions stay in lockstep + +These versions must always be identical: + +- `package.json` +- `packages/squad-sdk/package.json` +- `packages/squad-cli/package.json` +- the corresponding workspace entries in `package-lock.json` + +Use the workspace-aware version command: + +```bash +npm version "$VERSION" --workspaces --include-workspace-root --no-git-tag-version +``` + +Never edit only one package version. + +## 3. Prerelease workspace dependency rule + +The CLI depends on the SDK through a SemVer range. SemVer deliberately excludes +prereleases unless the comparator names a prerelease with the same base version. +For example, `>=0.13.0` does not match `0.14.0-preview.1`. + +For every committed preview version, set both the CLI manifest and lockfile +dependency floor to that exact preview: + +```bash +npm pkg set "dependencies.@bradygaster/squad-sdk=>=$VERSION" \ + --workspace @bradygaster/squad-cli +npm install --package-lock-only +``` + +For `VERSION=0.14.0-preview.1`, the required range is +`>=0.14.0-preview.1`. Before stable promotion, change the version and floor to +`0.14.0` / `>=0.14.0`; never leave a prerelease floor in a stable release. + +This rule prevents the PR #640 failure mode, where the build succeeded against +a stale published SDK rather than the workspace SDK. + +## 4. Local build versions are ephemeral + +`scripts/bump-build.mjs` may create `-build.N` versions for local development. + +- Never commit a `-build.N` version. +- The script skips itself when `CI=true` or `SKIP_BUILD_BUMP=1`. +- If a build changes manifests locally, restore the intended release source + versions before committing. + +## 5. Release lifecycle + +1. On a release-preparation branch from `dev`, set the next + `X.Y.Z-preview.N` version and matching SDK dependency floor. +2. Merge to `dev`, wait for CI, and dispatch `squad-release.yml` from `dev`. +3. Repeat with a new immutable preview version when another candidate is needed. +4. Dispatch `squad-insider-publish.yml` whenever an on-demand development + snapshot is needed; it computes the next immutable `X.Y.Z-insider.N`. +5. Prepare stable `X.Y.Z` and its stable SDK dependency floor on `dev`. +6. Dispatch `squad-promote.yml`; it sanitizes `dev`, pushes `main`, and + explicitly dispatches the stable release. +7. Open the next preview-version PR for continued development. + +A preview such as `0.14.0-preview.1` is never renamed or converted in place. +Stable `0.14.0` is a separate immutable package version and GitHub tag. + +## 6. Ownership + +The current Release Manager owns release version changes. Other agents may update +versions only when explicitly assigned release work or when reverting an +accidentally committed local `-build.N` version. + +## 7. CI enforcement + +CI verifies: + +- root, SDK, and CLI versions match; +- package-lock workspace versions match; +- committed prereleases use approved `preview` or `insider` identifiers; +- a preview CLI dependency and lockfile entry equal `>=VERSION`; +- stable source does not retain a prerelease dependency floor; and +- workspace packages resolve through local links rather than stale registry + packages. + +Release workflows repeat the dependency checks before creating a tag or +publishing. + +## Quick reference + +| Rule | Summary | +|---|---| +| Insider | The workflow generates `X.Y.Z-insider.N` from the stable base version | +| Preview | Commit `X.Y.Z-preview.N` to `dev` for an on-demand prerelease | +| Stable | Only `X.Y.Z` may release from `main` | +| Sync | Root, SDK, CLI, and lockfile workspace versions must match | +| Dependency | Preview CLI range and lockfile entry must be `>=VERSION` | +| Local build | `-build.N` is local-only and never committed | +| Ownership | The current Release Manager owns planned release version changes | diff --git a/.squad-templates/skills/windows-compatibility/SKILL.md b/.squad-templates/skills/windows-compatibility/SKILL.md new file mode 100644 index 000000000..6242b88c4 --- /dev/null +++ b/.squad-templates/skills/windows-compatibility/SKILL.md @@ -0,0 +1,98 @@ +--- +name: "windows-compatibility" +description: "Cross-platform path handling and command patterns" +domain: "platform" +confidence: "high" +source: "earned (multiple Windows-specific bugs: colons in filenames, git -C failures, path separators)" +--- + +## Context + +Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platform-specific assumptions: ISO timestamps with colons (illegal on Windows), `git -C` with Windows paths (unreliable), forward-slash paths in Node.js on Windows. + +## Patterns + +### Filenames & Timestamps +- **Never use colons in filenames:** ISO 8601 format `2026-03-15T05:30:00Z` is illegal on Windows +- **Use `safeTimestamp()` utility:** Replaces colons with hyphens → `2026-03-15T05-30-00Z` +- **Centralize formatting:** Don't inline `.toISOString().replace(/:/g, '-')` — use the utility + +### Git Commands +- **Never use `git -C {path}`:** Unreliable with Windows paths (backslashes, spaces, drive letters) +- **Always `cd` first:** Change directory, then run git commands +- **Check for changes before commit:** `git diff --cached --quiet` (exit 0 = no changes) + +### Commit Messages +- **Never embed newlines in `-m` flag:** Backtick-n (`\n`) fails silently in PowerShell +- **Use temp file + `-F` flag:** Write message to file, commit with `git commit -F $msgFile` + +### Paths +- **Never assume CWD is repo root:** Always use `TEAM ROOT` from spawn prompt or run `git rev-parse --show-toplevel` +- **Use path.join() or path.resolve():** Don't manually concatenate with `/` or `\` + +### Path Comparison (Case Sensitivity) +- **Never use case-sensitive `startsWith` or `===` for path comparison on Windows or macOS:** These filesystems are case-insensitive — `C:\Users\` and `c:\users\` refer to the same location +- **Use platform-aware comparison:** Check `process.platform === 'win32' || process.platform === 'darwin'` and lowercase both sides before comparing +- **Pattern:** + ```typescript + const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin'; + + function pathStartsWith(fullPath: string, prefix: string): boolean { + if (CASE_INSENSITIVE) { + return fullPath.toLowerCase().startsWith(prefix.toLowerCase()); + } + return fullPath.startsWith(prefix); + } + ``` +- **Where it matters:** Security checks (path traversal prevention), rootDir confinement, any path-contains-path validation +- **Linux is case-sensitive:** Do NOT lowercase on Linux — `/Home/` and `/home/` are different directories + +## Examples + +✓ **Correct:** +```javascript +// Timestamp utility +const safeTimestamp = () => new Date().toISOString().replace(/:/g, '-').split('.')[0] + 'Z'; + +// Git workflow (PowerShell) +cd $teamRoot +git add .squad/ +if ($LASTEXITCODE -eq 0) { + $msg = @" +docs(ai-team): session log + +Changes: +- Added decisions +"@ + $msgFile = [System.IO.Path]::GetTempFileName() + Set-Content -Path $msgFile -Value $msg -Encoding utf8 + git commit -F $msgFile + Remove-Item $msgFile +} +``` + +✗ **Incorrect:** +```javascript +// Colon in filename +const logPath = `.squad/log/${new Date().toISOString()}.md`; // ILLEGAL on Windows + +// git -C with Windows path +exec('git -C C:\\src\\squad add .squad/'); // UNRELIABLE + +// Inline newlines in commit message +exec('git commit -m "First line\nSecond line"'); // FAILS silently in PowerShell +``` + +## Anti-Patterns + +- Testing only on one platform (bugs ship to other platforms) +- Assuming Unix-style paths work everywhere +- Using `git -C` because it "looks cleaner" (it doesn't work) +- Skipping `git diff --cached --quiet` check (creates empty commits) +- **Wrong — case-sensitive path check on Windows and macOS:** + ```typescript + if (!resolved.startsWith(rootDir + path.sep)) { + throw new Error('Path traversal blocked'); + } + // Fails: 'c:\\Users\\temp\\file'.startsWith('C:\\Users\\temp\\') → false + ``` diff --git a/.squad-templates/spawn-reference.md b/.squad-templates/spawn-reference.md index b5e1748bc..a89c2dbb1 100644 --- a/.squad-templates/spawn-reference.md +++ b/.squad-templates/spawn-reference.md @@ -61,7 +61,7 @@ Standard spawn via `task` tool — used in CLI, or as fallback when `create_sess - **`agent_type`**: `"general-purpose"` (always — this gives agents full tool access) - **`mode`**: `"background"` (default) or `"sync"` — use `"background"` for all parallelizable work; use `"sync"` only when the result is needed before the next step can proceed -- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Ripley: Design REST API endpoints"`, `"Dallas: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing +- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Runtime Engineer: Design REST API endpoints"`, `"Experience Engineer: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing - **`prompt`**: The full agent prompt (see below) **⚡ Inline the charter.** Before spawning, read the agent's `charter.md` (resolve from team root: `{team_root}/.squad/agents/{name}/charter.md`) and paste its contents directly into the spawn prompt. This eliminates a tool call from the agent's critical path. The agent still reads its own `history.md` and `decisions.md`. diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md index a2bf7384c..708edca2b 100644 --- a/.squad-templates/squad.agent.md +++ b/.squad-templates/squad.agent.md @@ -176,11 +176,11 @@ For each squad member with assigned issues, note them in the session context. Wh **The user should never see a blank screen while agents work.** Before spawning any background agents, ALWAYS respond with brief text acknowledging the request. Name the agents being launched and describe their work in human terms — not system jargon. This acknowledgment is REQUIRED, not optional. -- **Single agent:** `"Fenster's on it — looking at the error handling now."` +- **Single agent:** `"Runtime Engineer is on it — looking at the error handling now."` - **Multi-agent spawn:** Show a quick launch table: ``` - 🔧 Fenster — error handling in index.js - 🧪 Hockney — writing test cases + 🔧 Runtime Engineer — error handling in index.js + 🧪 Quality Engineer — writing test cases 📋 Scribe — logging session ``` @@ -214,9 +214,9 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use 👤 as fallback **Examples:** -- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"` -- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"` -- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` +- `name: "lead"`, `description: "🏗️ Lead: Reviewing architecture proposal"` +- `name: "runtime-engineer"`, `description: "🔧 Runtime Engineer: Refactoring auth module"` +- `name: "quality-engineer"`, `description: "🧪 Quality Engineer: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. @@ -234,7 +234,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa **NOT directives** (route normally): - Work requests ("build X", "fix Y", "test Z", "add a feature") - Questions ("how does X work?", "what did the team do?") -- Agent-directed tasks ("Ripley, refactor the API") +- Agent-directed tasks ("Runtime Engineer, refactor the API") **When you detect a directive:** @@ -288,7 +288,7 @@ The routing table determines **WHO** handles work. After routing, use Response M | Signal | Action | |--------|--------| -| Names someone ("Ripley, fix the button") | Spawn that agent | +| Names someone ("Experience Engineer, fix the button") | Spawn that agent | | Personal agent by name (user addresses a personal agent) | Route to personal agent in consult mode — they advise, project agent executes changes | | "Team" or multi-domain question | Spawn 2-3+ relevant agents in parallel, synthesize | | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) | @@ -654,7 +654,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without dispatching via the platform's tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Dispatch to the real agent and let it respond. 3. **Never skip dispatching (via `task` or `runSubagent`) for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "experience-engineer"` is right. `"General purpose task"` is wrong — `"Experience Engineer: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict. ### After Agent Work diff --git a/.squad-templates/workflows/squad-triage.yml b/.squad-templates/workflows/squad-triage.yml index 627626aaf..579f74d29 100644 --- a/.squad-templates/workflows/squad-triage.yml +++ b/.squad-templates/workflows/squad-triage.yml @@ -91,10 +91,12 @@ jobs: } function findLead(teamMembers) { - return teamMembers.find(member => { + const hasRoleToken = (member, token) => { const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; - return roleWords.includes('lead'); - }); + return roleWords.includes(token); + }; + return teamMembers.find(member => hasRoleToken(member, 'lead')) || + teamMembers.find(member => hasRoleToken(member, 'architect')); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } @@ -127,7 +129,12 @@ jobs: const headers = tableCells(line).map(cell => cell.toLowerCase()); const workTypeIndex = headers.indexOf('work type'); - const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const routeIndex = headers.findIndex(header => + header === 'route to' || + header === 'agent' || + header === 'primary' || + header === 'primary agent' + ); const examplesIndex = headers.indexOf('examples'); if (workTypeIndex < 0 || routeIndex < 0) continue; @@ -140,16 +147,11 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinationNames = routeCell - .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) - .map(normalizeRouteDestination) - .filter(Boolean); - const destinations = teamMembers.filter(member => - destinationNames.includes(normalizeRouteDestination(member.name)) + const destinationName = normalizeRouteDestination(routeCell); + const member = teamMembers.find(candidate => + normalizeRouteDestination(candidate.name) === destinationName ); - for (const member of destinations) { - rules.push({ member, workType, examples }); - } + if (member) rules.push({ member, workType, examples }); } break; } @@ -158,28 +160,34 @@ jobs: } function routeScore(issueText, rule) { - const stopWords = new Set([ - 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', - 'work', 'owner', 'agent', 'support', 'management', + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', ]); - const phrases = rule.workType - .toLowerCase() - .split(/[,/&]+/) - .map(value => value.trim()) - .filter(value => value.length >= 4); - const keywords = `${rule.workType} ${rule.examples}` - .toLowerCase() - .match(/[a-z0-9@.+#-]+/g) || []; - - let score = phrases.reduce( - (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), - 0 - ); - for (const keyword of new Set(keywords)) { - if (keyword.length < 3 || stopWords.has(keyword)) continue; - if (issueText.includes(keyword)) score++; + + function tokens(value) { + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + } + + function containsPhrase(haystack, needle) { + if (needle.length === 0 || needle.length > haystack.length) return false; + return haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); } - return score; + + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter(token => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.examples.split(/[,;]+/)] + .flatMap(phrase => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + + return rawPhrases.reduce((best, phrase) => { + const phraseTokens = tokens(phrase); + if (!containsPhrase(issueTokens, phraseTokens)) return best; + const specificity = phraseTokens.length * 100; + return Math.max(best, specificity); + }, 0); } function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { @@ -192,7 +200,16 @@ jobs: return { member: lead, workType: null }; } - const best = scoredRoutes[0]; + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter(candidate => candidate.score === bestScore); + const bestMembers = new Set(bestRoutes.map(candidate => + normalizeRouteDestination(candidate.rule.member.name) + )); + if (bestMembers.size !== 1) { + return { member: lead, workType: null }; + } + + const best = bestRoutes[0]; return { member: best.rule.member, workType: best.rule.workType }; } diff --git a/.squad/comms/tests/tone-validation-spec.md b/.squad/comms/tests/tone-validation-spec.md index b52bd44cf..4e8edd5d9 100644 --- a/.squad/comms/tests/tone-validation-spec.md +++ b/.squad/comms/tests/tone-validation-spec.md @@ -54,11 +54,11 @@ Drafts of specific types MUST contain these patterns: | Test ID | Scenario | Expected Behavior | |---------|----------|------------------| | T5.1 | Draft without human review | BLOCKED — cannot post | -| T5.2 | `comms approve` command without draft ID | Error message | +| T5.2 | `pao approve` command without draft ID | Error message | | T5.3 | Concurrent review sessions | SQLite lock prevents race | | T5.4 | Stale lock (>1 hour) | Auto-cleanup, new session allowed | | T5.5 | `banana` issued (safe word) | All pending drafts frozen | -| T5.6 | `comms resume` after banana | Drafts unfrozen | +| T5.6 | `pao resume` after banana | Drafts unfrozen | ### T6: Audit Trail Completeness @@ -150,5 +150,5 @@ Before launch, ALL of the following must be true: - [ ] Rollback workflow (delete-and-repost) tested end-to-end - [ ] Review gate SQLite schema tested with concurrent access - [ ] Audit trail format validated against template -- [ ] `banana` / `comms resume` flow tested end-to-end +- [ ] `banana` / `pao resume` flow tested end-to-end - [ ] At least one full scan→draft→review→post cycle completed successfully diff --git a/.squad/skills/external-comms/SKILL.md b/.squad/skills/external-comms/SKILL.md index 3d625a1f8..9ac372dca 100644 --- a/.squad/skills/external-comms/SKILL.md +++ b/.squad/skills/external-comms/SKILL.md @@ -1,16 +1,16 @@ --- name: "external-comms" -description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" +description: "PAO workflow for scanning, drafting, and presenting community responses with human review gate" domain: "community, communication, workflow" confidence: "low" -source: "manual (external communications workflow)" +source: "manual (RFC #426 — PAO External Communications)" tools: - name: "github-mcp-server-list_issues" description: "List open issues for scan candidates and lightweight triage" when: "Use for recent open issue scans before thread-level review" - name: "github-mcp-server-issue_read" description: "Read the full issue, comments, and labels before drafting" - when: "Use after selecting a candidate so the communications owner has complete thread context" + when: "Use after selecting a candidate so PAO has complete thread context" - name: "github-mcp-server-search_issues" description: "Search for candidate issues or prior squad responses" when: "Use when filtering by keywords, labels, or duplicate response checks" @@ -23,10 +23,10 @@ tools: Phase 1 is **draft-only mode**. -- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. -- **Human review gate is mandatory** — the communications owner never posts autonomously. +- PAO scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — PAO never posts autonomously. - Every action is logged to `.squad/comms/audit/`. -- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. +- This workflow is triggered manually only ("PAO, check community") — no automated or Ralph-triggered activation in Phase 1. ## Patterns @@ -47,7 +47,7 @@ Discussions use the GitHub Discussions API, which differs from issues: - **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions - **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) -- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Answers vs comments:** In Q&A discussions, PAO drafts an "answer" (not a comment). The human marks it as accepted answer after posting. - **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. ### 2. Classify @@ -107,7 +107,7 @@ Use the humanizer skill for every draft. ### Thread-Read Verification -Before drafting, the communications owner MUST verify complete thread coverage: +Before drafting, PAO MUST verify complete thread coverage: 1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. 2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. @@ -120,7 +120,7 @@ Before drafting, the communications owner MUST verify complete thread coverage: Show drafts for review in this exact format: ```text -📝 Community Response Drafts +📝 PAO — Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -139,9 +139,9 @@ Each full draft must begin with the thread summary line: Wait for explicit human direction before anything is posted. -- `comms approve 1 3` — approve drafts 1 and 3 -- `comms edit 2` — edit draft 2 -- `comms skip` — skip all +- `pao approve 1 3` — approve drafts 1 and 3 +- `pao edit 2` — edit draft 2 +- `pao skip` — skip all - `banana` — freeze all pending (safe word) ### Rollback — Bad Post Recovery @@ -152,12 +152,12 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` 2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content -3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle +3. **Draft replacement** (if needed): PAO drafts a corrected response, goes through normal review cycle 4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case **Safe word — `banana`:** - Immediately freezes all pending drafts in the review queue -- No new scans or drafts until `comms resume` is issued +- No new scans or drafts until `pao resume` is issued - Audit entry logged with halter identity and reason ### 6. Post @@ -165,7 +165,7 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: After approval: - Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. -- The communications owner helps by preparing the CLI command. +- PAO helps by preparing the CLI command. - Write the audit entry after the posting action. ### 7. Audit @@ -190,7 +190,7 @@ gh issue list --state open --json number,title,author,labels,comments --limit 20 ### Example review table ```text -📝 Community Response Drafts +📝 PAO — Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -319,7 +319,7 @@ That context will help us narrow down what's happening. Appreciate it! - ❌ Posting without human review (NEVER — this is the cardinal rule) - ❌ Drafting without reading full thread (context is everything) -- ❌ Ignoring confidence flags (🔴 items need Lead or human review) +- ❌ Ignoring confidence flags (🔴 items need Flight/human review) - ❌ Scanning closed issues (only open items) - ❌ Responding to issues labeled `squad:internal` or `wontfix` - ❌ Skipping audit logging (every action must be recorded) diff --git a/.squad/skills/humanizer/SKILL.md b/.squad/skills/humanizer/SKILL.md index f3bfaa06c..4dbb854df 100644 --- a/.squad/skills/humanizer/SKILL.md +++ b/.squad/skills/humanizer/SKILL.md @@ -3,16 +3,16 @@ name: "humanizer" description: "Tone enforcement patterns for external-facing community responses" domain: "communication, tone, community" confidence: "low" -source: "manual (external communications workflow)" +source: "manual (RFC #426 — PAO External Communications)" --- ## Context -Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. +Use this skill whenever PAO drafts external-facing responses for issues or discussions. - Tone must be warm, helpful, and human-sounding — never robotic or corporate. - Brady's constraint applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. +- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows. ## Patterns @@ -98,7 +98,7 @@ We'll dig deeper and update this thread. - ❌ Dismissive: "This works as designed" without empathy - ❌ Over-promising: "We'll ship this next week" without commitment from the team - ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" +- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Squad Team" - ❌ Excessive emoji: More than 1-2 emoji per response - ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead - ❌ Link-dumping: Pasting URLs without context ("See: https://...") diff --git a/.squad/skills/tiered-memory/SKILL.md b/.squad/skills/tiered-memory/SKILL.md index badc64671..5921eb80a 100644 --- a/.squad/skills/tiered-memory/SKILL.md +++ b/.squad/skills/tiered-memory/SKILL.md @@ -205,10 +205,10 @@ Include when: ## Escalation If blocked or uncertain: -- Architecture questions → current architecture owner from `routing.md` -- Security concerns → current security owner from `routing.md` -- Infrastructure/deployment → current delivery owner from `routing.md` -- Memory/history questions → current memory owner from `routing.md` +- Architecture questions → @picard +- Security concerns → @worf +- Infrastructure/deployment → @belanna +- Memory/history questions → @scribe --- @@ -218,3 +218,4 @@ If blocked or uncertain: - Cold adds a summary; only include when history is relevant - Wiki adds variable size; only include specific relevant docs - Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn + diff --git a/.squad/skills/versioning-policy/SKILL.md b/.squad/skills/versioning-policy/SKILL.md index 59de6f54b..499de8555 100644 --- a/.squad/skills/versioning-policy/SKILL.md +++ b/.squad/skills/versioning-policy/SKILL.md @@ -91,7 +91,7 @@ Stable `0.14.0` is a separate immutable package version and GitHub tag. ## 6. Ownership -The current Release Manager owns release version changes. Other agents may update +Surgeon (Release Manager) owns release version changes. Other agents may update versions only when explicitly assigned release work or when reverting an accidentally committed local `-build.N` version. @@ -120,4 +120,4 @@ publishing. | Sync | Root, SDK, CLI, and lockfile workspace versions must match | | Dependency | Preview CLI range and lockfile entry must be `>=VERSION` | | Local build | `-build.N` is local-only and never committed | -| Ownership | The current Release Manager owns planned release version changes | +| Ownership | Surgeon owns planned release version changes | diff --git a/package.json b/package.json index ae0580f44..67804ed97 100644 --- a/package.json +++ b/package.json @@ -16,9 +16,9 @@ } }, "scripts": { - "prebuild": "node scripts/bump-build.mjs && node scripts/sync-skill-templates.mjs && node scripts/sync-templates.mjs", + "prebuild": "node scripts/bump-build.mjs", "build": "npm run build -w packages/squad-sdk && npm run build -w packages/squad-cli", - "sync-templates": "node scripts/sync-templates.mjs", + "sync-templates": "node scripts/sync-templates.mjs --sync", "test": "vitest run", "test:watch": "vitest", "bench": "node scripts/run-benchmarks.mjs", diff --git a/packages/squad-cli/src/cli/shell/components/Separator.tsx b/packages/squad-cli/src/cli/shell/components/Separator.tsx index b588b0a15..f10e2d9d1 100644 --- a/packages/squad-cli/src/cli/shell/components/Separator.tsx +++ b/packages/squad-cli/src/cli/shell/components/Separator.tsx @@ -4,7 +4,7 @@ * Consolidates all inline separator rendering (AgentPanel, MessageStream, App.tsx) * into a single reusable component. Uses box-drawing chars that degrade to ASCII. * - * Owned by Cheritto (TUI Engineer). + * Maintained by the TUI engineering owner. */ import React from 'react'; diff --git a/packages/squad-cli/src/cli/shell/components/ThinkingIndicator.tsx b/packages/squad-cli/src/cli/shell/components/ThinkingIndicator.tsx index f1b44dbec..acbe4fd4e 100644 --- a/packages/squad-cli/src/cli/shell/components/ThinkingIndicator.tsx +++ b/packages/squad-cli/src/cli/shell/components/ThinkingIndicator.tsx @@ -5,7 +5,7 @@ * Default label: "Routing to agent..." (covers SDK connection, initial routing). * Activity hints from SDK events or @Agent mentions override the default. * - * Owned by Cheritto (TUI Engineer). Design approved by Marquez. + * Maintained by the TUI engineering owner with UX review. */ import React, { useState, useEffect } from 'react'; diff --git a/packages/squad-cli/src/cli/shell/useAnimation.ts b/packages/squad-cli/src/cli/shell/useAnimation.ts index 7cb7cff4b..1a5c9c986 100644 --- a/packages/squad-cli/src/cli/shell/useAnimation.ts +++ b/packages/squad-cli/src/cli/shell/useAnimation.ts @@ -6,7 +6,7 @@ * * Frame rate capped at ~15fps (67ms intervals) to stay GPU-friendly in Ink. * - * Owned by Cheritto (TUI Engineer). + * Maintained by the TUI engineering owner. */ import { useState, useEffect, useRef } from 'react'; diff --git a/packages/squad-cli/templates/machine-capabilities.md b/packages/squad-cli/templates/machine-capabilities.md index b770fd04b..65f3c478a 100644 --- a/packages/squad-cli/templates/machine-capabilities.md +++ b/packages/squad-cli/templates/machine-capabilities.md @@ -47,7 +47,7 @@ squad watch --interval 5 Ralph will log skipped issues: ``` ⏭️ Skipping #42 "Train ML model" — missing: gpu -✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule) +✓ Triaged #43 "Fix CSS layout" → Experience Engineer (routing-rule) ``` ## How It Works diff --git a/packages/squad-cli/templates/model-selection-reference.md b/packages/squad-cli/templates/model-selection-reference.md index 43eba9e5e..ffc51eb71 100644 --- a/packages/squad-cli/templates/model-selection-reference.md +++ b/packages/squad-cli/templates/model-selection-reference.md @@ -85,11 +85,11 @@ If you've exhausted the fallback chain and reached the platform default fallback When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-5) — refactoring auth module -🎨 Redfoot (gpt-5.6-sol · vision) — designing color system +🔧 Runtime Engineer (claude-sonnet-5) — refactoring auth module +🎨 Experience Engineer (gpt-5.6-sol · vision) — designing color system 📋 Scribe (gpt-5.6-luna · fast) — logging session -⚡ Keaton (gpt-5.6-sol · bumped for architecture) — reviewing proposal -📝 McManus (gpt-5.6-luna · fast) — updating docs +⚡ Lead (gpt-5.6-sol · bumped for architecture) — reviewing proposal +📝 Docs Engineer (gpt-5.6-luna · fast) — updating docs ``` Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name. diff --git a/packages/squad-cli/templates/notes-protocol.md b/packages/squad-cli/templates/notes-protocol.md index 5a1d03a5f..800066f80 100644 --- a/packages/squad-cli/templates/notes-protocol.md +++ b/packages/squad-cli/templates/notes-protocol.md @@ -28,11 +28,8 @@ Each agent writes to its own namespace to prevent conflicts: | Namespace | Owner | Purpose | |-----------|-------|---------| -| `refs/notes/squad/data` | Data | Architecture decisions, implementation choices | -| `refs/notes/squad/worf` | Worf | Security reviews, vulnerability assessments | -| `refs/notes/squad/seven` | Seven | Documentation quality, API contract decisions | +| `refs/notes/squad/{agent-id}` | Current agent | Agent-owned decisions and implementation context | | `refs/notes/squad/ralph` | Ralph | Work-round progress, task-state annotations | -| `refs/notes/squad/q` | Q | Devil's advocate findings, risk assessments | | `refs/notes/squad/research` | Any agent | Research notes that should survive branch deletion | | `refs/notes/squad/review` | Any agent | Code review context (mirrors Gerrit's pattern) | @@ -47,7 +44,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision | research | review | progress | security", "content": "..." @@ -58,7 +55,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision", "decision": "Use JWT RS256 for auth middleware", @@ -76,7 +73,7 @@ Set `"promote_to_permanent": true` to signal Ralph to copy this to ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "research", "topic": "JWT vs session tokens", diff --git a/packages/squad-cli/templates/ralph-triage.js b/packages/squad-cli/templates/ralph-triage.js index 863da3d7d..2e05eb971 100644 --- a/packages/squad-cli/templates/ralph-triage.js +++ b/packages/squad-cli/templates/ralph-triage.js @@ -58,11 +58,19 @@ function normalizeEol(content) { function slugify(text) { return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function parseRoutingRules(routingMd) { - const table = parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i); + const table = + parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i) || + parseTableSection(routingMd, /^##\s*routing\s*table\b/i); if (!table) return []; const workTypeIndex = findColumnIndex(table.headers, ['work type', 'type']); - const agentIndex = findColumnIndex(table.headers, ['agent', 'route to', 'route']); + const agentIndex = findColumnIndex(table.headers, [ + 'agent', + 'route to', + 'route', + 'primary agent', + 'primary', + ]); const examplesIndex = findColumnIndex(table.headers, ['examples', 'example']); if (workTypeIndex < 0 || agentIndex < 0) return []; @@ -564,4 +572,10 @@ if (require.main === module) { }); } -module.exports = { resolveGithubApiBase }; +module.exports = { + parseModuleOwnership, + parseRoster, + parseRoutingRules, + resolveGithubApiBase, + triageIssue, +}; diff --git a/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md b/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md index 46d7b5053..4128ff096 100644 --- a/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md +++ b/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md @@ -86,7 +86,7 @@ When a proposal invalidates existing wave structure: **Alternatives:** `blessed`, raw readline **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. -**Needs sign-off from:** Brady (product direction), Fortier (runtime performance) +**Needs sign-off from:** Product Lead (product direction), Runtime Engineer (runtime performance) ``` ### Risk Documentation diff --git a/packages/squad-cli/templates/skills/ci-validation-gates/SKILL.md b/packages/squad-cli/templates/skills/ci-validation-gates/SKILL.md index 61c07d73e..9c120ac1d 100644 --- a/packages/squad-cli/templates/skills/ci-validation-gates/SKILL.md +++ b/packages/squad-cli/templates/skills/ci-validation-gates/SKILL.md @@ -3,12 +3,12 @@ name: "ci-validation-gates" description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22" domain: "ci-cd" confidence: "high" -source: "extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident" +source: "earned knowledge from the v0.8.22 release incident" --- ## Context -CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here. +CI workflows must be defensive. These patterns were learned from the v0.8.22 release incident where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. The reusable lessons are centralized here rather than tied to individual agent charters. ## Patterns diff --git a/packages/squad-cli/templates/skills/client-compatibility/SKILL.md b/packages/squad-cli/templates/skills/client-compatibility/SKILL.md index da3e94609..62e6b09ab 100644 --- a/packages/squad-cli/templates/skills/client-compatibility/SKILL.md +++ b/packages/squad-cli/templates/skills/client-compatibility/SKILL.md @@ -66,8 +66,8 @@ task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4 **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: "...Runtime Engineer charter + task..." }) +runSubagent({ prompt: "...Quality Engineer charter + task..." }) runSubagent({ prompt: "...Scribe charter + task..." }) // Last in group // Results return automatically, no read_agent ``` diff --git a/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md b/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md index 818438154..d9242c44b 100644 --- a/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md +++ b/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md @@ -439,4 +439,4 @@ Potential expansions (Phase 2+): Refer to research report: `research/active/cross-machine-agents/README.md` -Contact: Seven (Research & Docs) or Ralph (Work Monitor) +Contact: the research and documentation owner or Ralph (Work Monitor) diff --git a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md index 0523fd340..316d20868 100644 --- a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md @@ -137,13 +137,13 @@ tool calls (including file writes) prompt for confirmation and block. ```powershell # PowerShell (Windows) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." ` +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." ` 2>&1 | Tee-Object evidence/session-task.log ``` ```bash # Bash (macOS/Linux) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." \ +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." \ 2>&1 | tee evidence/session-task.log ``` diff --git a/packages/squad-cli/templates/skills/external-comms/SKILL.md b/packages/squad-cli/templates/skills/external-comms/SKILL.md index 3d625a1f8..9745028f2 100644 --- a/packages/squad-cli/templates/skills/external-comms/SKILL.md +++ b/packages/squad-cli/templates/skills/external-comms/SKILL.md @@ -1,16 +1,16 @@ --- name: "external-comms" -description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" +description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" domain: "community, communication, workflow" confidence: "low" -source: "manual (external communications workflow)" +source: "manual (external communications workflow)" tools: - name: "github-mcp-server-list_issues" description: "List open issues for scan candidates and lightweight triage" when: "Use for recent open issue scans before thread-level review" - name: "github-mcp-server-issue_read" description: "Read the full issue, comments, and labels before drafting" - when: "Use after selecting a candidate so the communications owner has complete thread context" + when: "Use after selecting a candidate so the communications owner has complete thread context" - name: "github-mcp-server-search_issues" description: "Search for candidate issues or prior squad responses" when: "Use when filtering by keywords, labels, or duplicate response checks" @@ -23,10 +23,10 @@ tools: Phase 1 is **draft-only mode**. -- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. -- **Human review gate is mandatory** — the communications owner never posts autonomously. +- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — the communications owner never posts autonomously. - Every action is logged to `.squad/comms/audit/`. -- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. +- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. ## Patterns @@ -47,7 +47,7 @@ Discussions use the GitHub Discussions API, which differs from issues: - **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions - **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) -- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. - **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. ### 2. Classify @@ -107,7 +107,7 @@ Use the humanizer skill for every draft. ### Thread-Read Verification -Before drafting, the communications owner MUST verify complete thread coverage: +Before drafting, the communications owner MUST verify complete thread coverage: 1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. 2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. @@ -120,7 +120,7 @@ Before drafting, the communications owner MUST verify complete thread coverage: Show drafts for review in this exact format: ```text -📝 Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -139,9 +139,9 @@ Each full draft must begin with the thread summary line: Wait for explicit human direction before anything is posted. -- `comms approve 1 3` — approve drafts 1 and 3 -- `comms edit 2` — edit draft 2 -- `comms skip` — skip all +- `comms approve 1 3` — approve drafts 1 and 3 +- `comms edit 2` — edit draft 2 +- `comms skip` — skip all - `banana` — freeze all pending (safe word) ### Rollback — Bad Post Recovery @@ -152,12 +152,12 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` 2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content -3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle +3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle 4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case **Safe word — `banana`:** - Immediately freezes all pending drafts in the review queue -- No new scans or drafts until `comms resume` is issued +- No new scans or drafts until `comms resume` is issued - Audit entry logged with halter identity and reason ### 6. Post @@ -165,7 +165,7 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: After approval: - Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. -- The communications owner helps by preparing the CLI command. +- The communications owner helps by preparing the CLI command. - Write the audit entry after the posting action. ### 7. Audit @@ -190,7 +190,7 @@ gh issue list --state open --json number,title,author,labels,comments --limit 20 ### Example review table ```text -📝 Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -319,7 +319,7 @@ That context will help us narrow down what's happening. Appreciate it! - ❌ Posting without human review (NEVER — this is the cardinal rule) - ❌ Drafting without reading full thread (context is everything) -- ❌ Ignoring confidence flags (🔴 items need Lead or human review) +- ❌ Ignoring confidence flags (🔴 items need Lead or human review) - ❌ Scanning closed issues (only open items) - ❌ Responding to issues labeled `squad:internal` or `wontfix` - ❌ Skipping audit logging (every action must be recorded) diff --git a/packages/squad-cli/templates/skills/history-hygiene/SKILL.md b/packages/squad-cli/templates/skills/history-hygiene/SKILL.md index 453a03b4e..b0f61417c 100644 --- a/packages/squad-cli/templates/skills/history-hygiene/SKILL.md +++ b/packages/squad-cli/templates/skills/history-hygiene/SKILL.md @@ -3,12 +3,12 @@ name: history-hygiene description: Record final outcomes to history.md, not intermediate requests or reversed decisions domain: documentation, team-collaboration confidence: high -source: earned (Kobayashi v0.6.0 incident, team intervention) +source: earned (release-history correction incident) --- ## Context -History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake. +History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. A release incident proved this: history retained an obsolete v0.6.0 target after the user had changed it to v0.8.17. Future spawns read the wrong truth and repeated the mistake. ## Patterns @@ -20,11 +20,11 @@ History files (.md files tracking decisions, spawns, outcomes) are read cold by ## Examples ✓ **Correct:** -- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)" -- "Reverted to Node 18 per Brady's explicit request on 2024-01-15" +- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by the user)" +- "Reverted to Node 18 per the user's explicit request on 2024-01-15" ✗ **Incorrect:** -- "Brady directed v0.6.0" (when later reversed) +- "The user directed v0.6.0" (when later reversed) - Recording what was *requested* instead of what *actually happened* - Logging entries before outcome is confirmed diff --git a/packages/squad-cli/templates/skills/humanizer/SKILL.md b/packages/squad-cli/templates/skills/humanizer/SKILL.md index f3bfaa06c..eb28d5db8 100644 --- a/packages/squad-cli/templates/skills/humanizer/SKILL.md +++ b/packages/squad-cli/templates/skills/humanizer/SKILL.md @@ -3,16 +3,16 @@ name: "humanizer" description: "Tone enforcement patterns for external-facing community responses" domain: "communication, tone, community" confidence: "low" -source: "manual (external communications workflow)" +source: "manual (external communications workflow)" --- ## Context -Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. - Tone must be warm, helpful, and human-sounding — never robotic or corporate. -- Brady's constraint applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. +- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. ## Patterns @@ -98,7 +98,7 @@ We'll dig deeper and update this thread. - ❌ Dismissive: "This works as designed" without empathy - ❌ Over-promising: "We'll ship this next week" without commitment from the team - ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" - ❌ Excessive emoji: More than 1-2 emoji per response - ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead - ❌ Link-dumping: Pasting URLs without context ("See: https://...") diff --git a/packages/squad-cli/templates/skills/init-mode/SKILL.md b/packages/squad-cli/templates/skills/init-mode/SKILL.md index 4f937bc65..5f99e7dab 100644 --- a/packages/squad-cli/templates/skills/init-mode/SKILL.md +++ b/packages/squad-cli/templates/skills/init-mode/SKILL.md @@ -24,18 +24,18 @@ No team exists yet. Propose one — but **DO NOT create any files until the user 2. Ask: *"What are you building? (language, stack, what it does)"* 3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section): - Determine team size (typically 4–5 + Scribe). - - Determine assignment shape from the user's project description. - - Derive resonance signals from the session and repo context. - - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.squad/templates/casting/` directory. Prefer custom universes when available. + - **Default to descriptive names** (Lead, Frontend, Backend, Tester, etc.) unless the user requests a themed universe. + - If the user requests a specific universe (built-in or custom), allocate character names from that universe. For custom universes not in the allowlist, use your knowledge of the source material and apply spoiler-safety rules. + - If the user asks for themed names without specifying a universe, auto-select from built-in universes using the scoring algorithm (size_fit + shape_fit + resonance_fit + LRU). - Scribe is always "Scribe" — exempt from casting. - Ralph is always "Ralph" — exempt from casting. 4. Propose the team with their cast names. Example (names will vary per cast): ``` -🏗️ {CastName1} — Lead Scope, decisions, code review -⚛️ {CastName2} — Frontend Dev React, UI, components -🔧 {CastName3} — Backend Dev APIs, database, services -🧪 {CastName4} — Tester Tests, quality, edge cases +🏗️ Lead — Lead Scope, decisions, code review +⚛️ Frontend — Frontend Dev React, UI, components +🔧 Backend — Backend Dev APIs, database, services +🧪 Tester — Tester Tests, quality, edge cases 📋 Scribe — (silent) Memory, decisions, session logs 🔄 Ralph — (monitor) Work queue, backlog, keep-alive ``` @@ -85,11 +85,11 @@ The `union` merge driver keeps all lines from both sides, which is correct for a 2. Runs `git config user.name` → "{user}" 3. Asks: *"Hey {user}, what are you building?"* 4. User: *"TypeScript CLI tool with GitHub API integration"* -5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe -6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph +5. Coordinator uses descriptive naming by default +6. Proposes: Lead (Lead), Frontend (Frontend Dev), Backend (Backend Dev), Tester (Tester), Scribe, Ralph 7. Uses `ask_user` with choices → user selects "Yes, cast this team" 8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents -9. Says: *"✅ Team cast. Try: 'Keaton, set up the project structure'"* +9. Says: *"✅ Team cast. Try: 'Lead, set up the project structure'"* ## Anti-Patterns @@ -100,3 +100,5 @@ The `union` merge driver keeps all lines from both sides, which is correct for a - ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows) - ❌ Forgetting to initialize `.squad/casting/` state files - ❌ Reading or storing `git config user.email` (PII violation) +- ❌ Rejecting a user's universe choice because it is not in the built-in allowlist +- ❌ Auto-selecting a themed universe when the user didn't ask for one (use descriptive names by default) diff --git a/packages/squad-cli/templates/skills/notification-routing/SKILL.md b/packages/squad-cli/templates/skills/notification-routing/SKILL.md index 2b2df1fec..42c5cb075 100644 --- a/packages/squad-cli/templates/skills/notification-routing/SKILL.md +++ b/packages/squad-cli/templates/skills/notification-routing/SKILL.md @@ -56,7 +56,7 @@ Agents prefix their output with `CHANNEL:` to signal where the notificatio ``` CHANNEL:security -Worf found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5 +Security Reviewer found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5 ``` ### Routing Dispatcher (shell pseudocode) diff --git a/packages/squad-cli/templates/skills/project-conventions/SKILL.md b/packages/squad-cli/templates/skills/project-conventions/SKILL.md new file mode 100644 index 000000000..48a1861da --- /dev/null +++ b/packages/squad-cli/templates/skills/project-conventions/SKILL.md @@ -0,0 +1,56 @@ +--- +name: "project-conventions" +description: "Core conventions and patterns for this codebase" +domain: "project-conventions" +confidence: "medium" +source: "template" +--- + +## Context + +> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality. + +## Patterns + +### [Pattern Name] + +Describe a key convention or practice used in this codebase. Be specific about what to do and why. + +### Error Handling + + + + + + +### Testing + + + + + + +### Code Style + + + + + + +### File Structure + + + + + + +## Examples + +``` +// Add code examples that demonstrate your conventions +``` + +## Anti-Patterns + + +- **[Anti-pattern]** — Explanation of what not to do and why. diff --git a/packages/squad-cli/templates/skills/reskill/SKILL.md b/packages/squad-cli/templates/skills/reskill/SKILL.md index 946de0e0b..c9e6184de 100644 --- a/packages/squad-cli/templates/skills/reskill/SKILL.md +++ b/packages/squad-cli/templates/skills/reskill/SKILL.md @@ -3,7 +3,7 @@ name: "reskill" description: "Team-wide charter and history optimization through skill extraction" domain: "team-optimization" confidence: "high" -source: "manual — Brady directive to reduce per-agent context overhead" +source: "manual — reduce per-agent context overhead" --- ## Context diff --git a/packages/squad-cli/templates/skills/reviewer-protocol/SKILL.md b/packages/squad-cli/templates/skills/reviewer-protocol/SKILL.md index 5d589105c..1f8e98430 100644 --- a/packages/squad-cli/templates/skills/reviewer-protocol/SKILL.md +++ b/packages/squad-cli/templates/skills/reviewer-protocol/SKILL.md @@ -38,35 +38,35 @@ When an artifact is **rejected** by a Reviewer: ## Examples **Example 1: Reassign after rejection** -1. Fenster writes authentication module -2. Hockney (Tester) reviews → rejects: "Error handling is missing. Verbal should fix this." -3. Coordinator: Fenster is now locked out of this artifact -4. Coordinator spawns Verbal to revise the authentication module -5. Verbal produces v2 -6. Hockney reviews v2 → approves +1. Runtime Engineer writes authentication module +2. Quality Engineer reviews → rejects: "Error handling is missing. Another engineer should fix this." +3. Coordinator: Runtime Engineer is now locked out of this artifact +4. Coordinator spawns a different engineer to revise the authentication module +5. The revision engineer produces v2 +6. Quality Engineer reviews v2 → approves 7. Lockout clears for next artifact **Example 2: Escalate for expertise** -1. Edie writes TypeScript config -2. Keaton (Lead) reviews → rejects: "Need someone with deeper TS knowledge. Escalate." -3. Coordinator: Edie is now locked out +1. Original Author writes TypeScript config +2. Lead reviews → rejects: "Need someone with deeper TS knowledge. Escalate." +3. Coordinator: Original Author is now locked out 4. Coordinator spawns new agent (or existing TS expert) to revise 5. New agent produces v2 -6. Keaton reviews v2 +6. Lead reviews v2 **Example 3: Deadlock handling** -1. Fenster writes module → rejected -2. Verbal revises → rejected -3. Hockney revises → rejected +1. Original Author writes module → rejected +2. Revision Engineer revises → rejected +3. Quality Engineer revises → rejected 4. All 3 eligible agents are now locked out 5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]" **Example 4: Reviewer accidentally names original author** -1. Fenster writes module → rejected -2. Hockney says: "Fenster should fix the error handling" -3. Coordinator: "Fenster is locked out as the original author. Please name a different agent." -4. Hockney: "Verbal, then" -5. Coordinator spawns Verbal +1. Original Author writes module → rejected +2. Quality Engineer says: "The original author should fix the error handling" +3. Coordinator: "The original author is locked out. Please name a different agent." +4. Quality Engineer names a revision engineer +5. Coordinator spawns the revision engineer ## Anti-Patterns diff --git a/packages/squad-cli/templates/skills/squad-version-check/SKILL.md b/packages/squad-cli/templates/skills/squad-version-check/SKILL.md index 3f3aebb0a..5f3fd785d 100644 --- a/packages/squad-cli/templates/skills/squad-version-check/SKILL.md +++ b/packages/squad-cli/templates/skills/squad-version-check/SKILL.md @@ -4,13 +4,13 @@ description: "Internals of how @bradygaster/squad-cli stamps its version, how `s allowedTools: [] confidence: medium domain: squad-internals -source: "Discovered by Data; validated in bradygaster/squad#1173 recon (2026-05-26)." +source: "validated in bradygaster/squad#1173 recon (2026-05-26)." --- # SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics **Confidence:** medium -**Discovered by:** Data +**Discovered by:** repository investigation **Date:** 2026-05-26 **Validated in:** Issue #1173 recon (bradygaster/squad) diff --git a/packages/squad-cli/templates/skills/test-discipline/SKILL.md b/packages/squad-cli/templates/skills/test-discipline/SKILL.md index d222bed52..9f85fba96 100644 --- a/packages/squad-cli/templates/skills/test-discipline/SKILL.md +++ b/packages/squad-cli/templates/skills/test-discipline/SKILL.md @@ -3,7 +3,7 @@ name: "test-discipline" description: "Update tests when changing APIs — no exceptions" domain: "quality" confidence: "high" -source: "earned (Fenster/Hockney incident, test assertion sync violations)" +source: "earned (test assertion sync violations)" --- ## Context diff --git a/packages/squad-cli/templates/spawn-reference.md b/packages/squad-cli/templates/spawn-reference.md index b5e1748bc..a89c2dbb1 100644 --- a/packages/squad-cli/templates/spawn-reference.md +++ b/packages/squad-cli/templates/spawn-reference.md @@ -61,7 +61,7 @@ Standard spawn via `task` tool — used in CLI, or as fallback when `create_sess - **`agent_type`**: `"general-purpose"` (always — this gives agents full tool access) - **`mode`**: `"background"` (default) or `"sync"` — use `"background"` for all parallelizable work; use `"sync"` only when the result is needed before the next step can proceed -- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Ripley: Design REST API endpoints"`, `"Dallas: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing +- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Runtime Engineer: Design REST API endpoints"`, `"Experience Engineer: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing - **`prompt`**: The full agent prompt (see below) **⚡ Inline the charter.** Before spawning, read the agent's `charter.md` (resolve from team root: `{team_root}/.squad/agents/{name}/charter.md`) and paste its contents directly into the spawn prompt. This eliminates a tool call from the agent's critical path. The agent still reads its own `history.md` and `decisions.md`. diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template index a2bf7384c..708edca2b 100644 --- a/packages/squad-cli/templates/squad.agent.md.template +++ b/packages/squad-cli/templates/squad.agent.md.template @@ -176,11 +176,11 @@ For each squad member with assigned issues, note them in the session context. Wh **The user should never see a blank screen while agents work.** Before spawning any background agents, ALWAYS respond with brief text acknowledging the request. Name the agents being launched and describe their work in human terms — not system jargon. This acknowledgment is REQUIRED, not optional. -- **Single agent:** `"Fenster's on it — looking at the error handling now."` +- **Single agent:** `"Runtime Engineer is on it — looking at the error handling now."` - **Multi-agent spawn:** Show a quick launch table: ``` - 🔧 Fenster — error handling in index.js - 🧪 Hockney — writing test cases + 🔧 Runtime Engineer — error handling in index.js + 🧪 Quality Engineer — writing test cases 📋 Scribe — logging session ``` @@ -214,9 +214,9 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use 👤 as fallback **Examples:** -- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"` -- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"` -- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` +- `name: "lead"`, `description: "🏗️ Lead: Reviewing architecture proposal"` +- `name: "runtime-engineer"`, `description: "🔧 Runtime Engineer: Refactoring auth module"` +- `name: "quality-engineer"`, `description: "🧪 Quality Engineer: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. @@ -234,7 +234,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa **NOT directives** (route normally): - Work requests ("build X", "fix Y", "test Z", "add a feature") - Questions ("how does X work?", "what did the team do?") -- Agent-directed tasks ("Ripley, refactor the API") +- Agent-directed tasks ("Runtime Engineer, refactor the API") **When you detect a directive:** @@ -288,7 +288,7 @@ The routing table determines **WHO** handles work. After routing, use Response M | Signal | Action | |--------|--------| -| Names someone ("Ripley, fix the button") | Spawn that agent | +| Names someone ("Experience Engineer, fix the button") | Spawn that agent | | Personal agent by name (user addresses a personal agent) | Route to personal agent in consult mode — they advise, project agent executes changes | | "Team" or multi-domain question | Spawn 2-3+ relevant agents in parallel, synthesize | | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) | @@ -654,7 +654,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without dispatching via the platform's tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Dispatch to the real agent and let it respond. 3. **Never skip dispatching (via `task` or `runSubagent`) for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "experience-engineer"` is right. `"General purpose task"` is wrong — `"Experience Engineer: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict. ### After Agent Work diff --git a/packages/squad-cli/templates/workflows/squad-triage.yml b/packages/squad-cli/templates/workflows/squad-triage.yml index 627626aaf..579f74d29 100644 --- a/packages/squad-cli/templates/workflows/squad-triage.yml +++ b/packages/squad-cli/templates/workflows/squad-triage.yml @@ -91,10 +91,12 @@ jobs: } function findLead(teamMembers) { - return teamMembers.find(member => { + const hasRoleToken = (member, token) => { const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; - return roleWords.includes('lead'); - }); + return roleWords.includes(token); + }; + return teamMembers.find(member => hasRoleToken(member, 'lead')) || + teamMembers.find(member => hasRoleToken(member, 'architect')); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } @@ -127,7 +129,12 @@ jobs: const headers = tableCells(line).map(cell => cell.toLowerCase()); const workTypeIndex = headers.indexOf('work type'); - const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const routeIndex = headers.findIndex(header => + header === 'route to' || + header === 'agent' || + header === 'primary' || + header === 'primary agent' + ); const examplesIndex = headers.indexOf('examples'); if (workTypeIndex < 0 || routeIndex < 0) continue; @@ -140,16 +147,11 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinationNames = routeCell - .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) - .map(normalizeRouteDestination) - .filter(Boolean); - const destinations = teamMembers.filter(member => - destinationNames.includes(normalizeRouteDestination(member.name)) + const destinationName = normalizeRouteDestination(routeCell); + const member = teamMembers.find(candidate => + normalizeRouteDestination(candidate.name) === destinationName ); - for (const member of destinations) { - rules.push({ member, workType, examples }); - } + if (member) rules.push({ member, workType, examples }); } break; } @@ -158,28 +160,34 @@ jobs: } function routeScore(issueText, rule) { - const stopWords = new Set([ - 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', - 'work', 'owner', 'agent', 'support', 'management', + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', ]); - const phrases = rule.workType - .toLowerCase() - .split(/[,/&]+/) - .map(value => value.trim()) - .filter(value => value.length >= 4); - const keywords = `${rule.workType} ${rule.examples}` - .toLowerCase() - .match(/[a-z0-9@.+#-]+/g) || []; - - let score = phrases.reduce( - (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), - 0 - ); - for (const keyword of new Set(keywords)) { - if (keyword.length < 3 || stopWords.has(keyword)) continue; - if (issueText.includes(keyword)) score++; + + function tokens(value) { + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + } + + function containsPhrase(haystack, needle) { + if (needle.length === 0 || needle.length > haystack.length) return false; + return haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); } - return score; + + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter(token => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.examples.split(/[,;]+/)] + .flatMap(phrase => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + + return rawPhrases.reduce((best, phrase) => { + const phraseTokens = tokens(phrase); + if (!containsPhrase(issueTokens, phraseTokens)) return best; + const specificity = phraseTokens.length * 100; + return Math.max(best, specificity); + }, 0); } function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { @@ -192,7 +200,16 @@ jobs: return { member: lead, workType: null }; } - const best = scoredRoutes[0]; + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter(candidate => candidate.score === bestScore); + const bestMembers = new Set(bestRoutes.map(candidate => + normalizeRouteDestination(candidate.rule.member.name) + )); + if (bestMembers.size !== 1) { + return { member: lead, workType: null }; + } + + const best = bestRoutes[0]; return { member: best.rule.member, workType: best.rule.workType }; } diff --git a/packages/squad-sdk/src/config/init.ts b/packages/squad-sdk/src/config/init.ts index 123b26b6e..7c0408580 100644 --- a/packages/squad-sdk/src/config/init.ts +++ b/packages/squad-sdk/src/config/init.ts @@ -1335,7 +1335,7 @@ ${projectDescription ? `- **Description:** ${projectDescription}\n` : ''}- **Cre `missing from the SDK templates dir (${skillsSrc}): ${missing.join(', ')}. ` + `This is a packaging bug — try \`squad upgrade\` or reinstall the SDK; ` + `if it persists, please report it at https://github.com/bradygaster/squad/issues. ` + - `(Contributors: re-run \`node scripts/sync-skill-templates.mjs\` from the repo root before packaging.)` + `(Contributors: re-run \`node scripts/sync-templates.mjs --sync\` from the repo root before packaging.)` ); } storage.mkdirSync(skillsDir, { recursive: true }); diff --git a/packages/squad-sdk/src/ralph/triage.ts b/packages/squad-sdk/src/ralph/triage.ts index 43de3f424..02045a9aa 100644 --- a/packages/squad-sdk/src/ralph/triage.ts +++ b/packages/squad-sdk/src/ralph/triage.ts @@ -47,14 +47,19 @@ interface ParsedTable { /** Parse routing rules from routing.md content */ export function parseRoutingRules(routingMd: string): RoutingRule[] { - const table = parseTableSection( - routingMd, - /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i, - ); + const table = + parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i) ?? + parseTableSection(routingMd, /^##\s*routing\s*table\b/i); if (!table) return []; const workTypeIndex = findColumnIndex(table.headers, ['work type', 'type']); - const agentIndex = findColumnIndex(table.headers, ['agent', 'route to', 'route']); + const agentIndex = findColumnIndex(table.headers, [ + 'agent', + 'route to', + 'route', + 'primary agent', + 'primary', + ]); const examplesIndex = findColumnIndex(table.headers, ['examples', 'example']); if (workTypeIndex < 0 || agentIndex < 0) return []; diff --git a/packages/squad-sdk/templates/machine-capabilities.md b/packages/squad-sdk/templates/machine-capabilities.md index b770fd04b..65f3c478a 100644 --- a/packages/squad-sdk/templates/machine-capabilities.md +++ b/packages/squad-sdk/templates/machine-capabilities.md @@ -47,7 +47,7 @@ squad watch --interval 5 Ralph will log skipped issues: ``` ⏭️ Skipping #42 "Train ML model" — missing: gpu -✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule) +✓ Triaged #43 "Fix CSS layout" → Experience Engineer (routing-rule) ``` ## How It Works diff --git a/packages/squad-sdk/templates/model-selection-reference.md b/packages/squad-sdk/templates/model-selection-reference.md index 43eba9e5e..ffc51eb71 100644 --- a/packages/squad-sdk/templates/model-selection-reference.md +++ b/packages/squad-sdk/templates/model-selection-reference.md @@ -85,11 +85,11 @@ If you've exhausted the fallback chain and reached the platform default fallback When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-5) — refactoring auth module -🎨 Redfoot (gpt-5.6-sol · vision) — designing color system +🔧 Runtime Engineer (claude-sonnet-5) — refactoring auth module +🎨 Experience Engineer (gpt-5.6-sol · vision) — designing color system 📋 Scribe (gpt-5.6-luna · fast) — logging session -⚡ Keaton (gpt-5.6-sol · bumped for architecture) — reviewing proposal -📝 McManus (gpt-5.6-luna · fast) — updating docs +⚡ Lead (gpt-5.6-sol · bumped for architecture) — reviewing proposal +📝 Docs Engineer (gpt-5.6-luna · fast) — updating docs ``` Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name. diff --git a/packages/squad-sdk/templates/notes-protocol.md b/packages/squad-sdk/templates/notes-protocol.md index 5a1d03a5f..800066f80 100644 --- a/packages/squad-sdk/templates/notes-protocol.md +++ b/packages/squad-sdk/templates/notes-protocol.md @@ -28,11 +28,8 @@ Each agent writes to its own namespace to prevent conflicts: | Namespace | Owner | Purpose | |-----------|-------|---------| -| `refs/notes/squad/data` | Data | Architecture decisions, implementation choices | -| `refs/notes/squad/worf` | Worf | Security reviews, vulnerability assessments | -| `refs/notes/squad/seven` | Seven | Documentation quality, API contract decisions | +| `refs/notes/squad/{agent-id}` | Current agent | Agent-owned decisions and implementation context | | `refs/notes/squad/ralph` | Ralph | Work-round progress, task-state annotations | -| `refs/notes/squad/q` | Q | Devil's advocate findings, risk assessments | | `refs/notes/squad/research` | Any agent | Research notes that should survive branch deletion | | `refs/notes/squad/review` | Any agent | Code review context (mirrors Gerrit's pattern) | @@ -47,7 +44,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision | research | review | progress | security", "content": "..." @@ -58,7 +55,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision", "decision": "Use JWT RS256 for auth middleware", @@ -76,7 +73,7 @@ Set `"promote_to_permanent": true` to signal Ralph to copy this to ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "research", "topic": "JWT vs session tokens", diff --git a/packages/squad-sdk/templates/ralph-triage.js b/packages/squad-sdk/templates/ralph-triage.js index 863da3d7d..2e05eb971 100644 --- a/packages/squad-sdk/templates/ralph-triage.js +++ b/packages/squad-sdk/templates/ralph-triage.js @@ -58,11 +58,19 @@ function normalizeEol(content) { function slugify(text) { return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function parseRoutingRules(routingMd) { - const table = parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i); + const table = + parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i) || + parseTableSection(routingMd, /^##\s*routing\s*table\b/i); if (!table) return []; const workTypeIndex = findColumnIndex(table.headers, ['work type', 'type']); - const agentIndex = findColumnIndex(table.headers, ['agent', 'route to', 'route']); + const agentIndex = findColumnIndex(table.headers, [ + 'agent', + 'route to', + 'route', + 'primary agent', + 'primary', + ]); const examplesIndex = findColumnIndex(table.headers, ['examples', 'example']); if (workTypeIndex < 0 || agentIndex < 0) return []; @@ -564,4 +572,10 @@ if (require.main === module) { }); } -module.exports = { resolveGithubApiBase }; +module.exports = { + parseModuleOwnership, + parseRoster, + parseRoutingRules, + resolveGithubApiBase, + triageIssue, +}; diff --git a/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md b/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md index 46d7b5053..4128ff096 100644 --- a/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md +++ b/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md @@ -86,7 +86,7 @@ When a proposal invalidates existing wave structure: **Alternatives:** `blessed`, raw readline **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. -**Needs sign-off from:** Brady (product direction), Fortier (runtime performance) +**Needs sign-off from:** Product Lead (product direction), Runtime Engineer (runtime performance) ``` ### Risk Documentation diff --git a/packages/squad-sdk/templates/skills/ci-validation-gates/SKILL.md b/packages/squad-sdk/templates/skills/ci-validation-gates/SKILL.md index 61c07d73e..9c120ac1d 100644 --- a/packages/squad-sdk/templates/skills/ci-validation-gates/SKILL.md +++ b/packages/squad-sdk/templates/skills/ci-validation-gates/SKILL.md @@ -3,12 +3,12 @@ name: "ci-validation-gates" description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22" domain: "ci-cd" confidence: "high" -source: "extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident" +source: "earned knowledge from the v0.8.22 release incident" --- ## Context -CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here. +CI workflows must be defensive. These patterns were learned from the v0.8.22 release incident where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. The reusable lessons are centralized here rather than tied to individual agent charters. ## Patterns diff --git a/packages/squad-sdk/templates/skills/client-compatibility/SKILL.md b/packages/squad-sdk/templates/skills/client-compatibility/SKILL.md index da3e94609..62e6b09ab 100644 --- a/packages/squad-sdk/templates/skills/client-compatibility/SKILL.md +++ b/packages/squad-sdk/templates/skills/client-compatibility/SKILL.md @@ -66,8 +66,8 @@ task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4 **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: "...Runtime Engineer charter + task..." }) +runSubagent({ prompt: "...Quality Engineer charter + task..." }) runSubagent({ prompt: "...Scribe charter + task..." }) // Last in group // Results return automatically, no read_agent ``` diff --git a/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md b/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md index 818438154..d9242c44b 100644 --- a/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md +++ b/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md @@ -439,4 +439,4 @@ Potential expansions (Phase 2+): Refer to research report: `research/active/cross-machine-agents/README.md` -Contact: Seven (Research & Docs) or Ralph (Work Monitor) +Contact: the research and documentation owner or Ralph (Work Monitor) diff --git a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md index 0523fd340..316d20868 100644 --- a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md @@ -137,13 +137,13 @@ tool calls (including file writes) prompt for confirmation and block. ```powershell # PowerShell (Windows) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." ` +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." ` 2>&1 | Tee-Object evidence/session-task.log ``` ```bash # Bash (macOS/Linux) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." \ +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." \ 2>&1 | tee evidence/session-task.log ``` diff --git a/packages/squad-sdk/templates/skills/external-comms/SKILL.md b/packages/squad-sdk/templates/skills/external-comms/SKILL.md index 3d625a1f8..9745028f2 100644 --- a/packages/squad-sdk/templates/skills/external-comms/SKILL.md +++ b/packages/squad-sdk/templates/skills/external-comms/SKILL.md @@ -1,16 +1,16 @@ --- name: "external-comms" -description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" +description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" domain: "community, communication, workflow" confidence: "low" -source: "manual (external communications workflow)" +source: "manual (external communications workflow)" tools: - name: "github-mcp-server-list_issues" description: "List open issues for scan candidates and lightweight triage" when: "Use for recent open issue scans before thread-level review" - name: "github-mcp-server-issue_read" description: "Read the full issue, comments, and labels before drafting" - when: "Use after selecting a candidate so the communications owner has complete thread context" + when: "Use after selecting a candidate so the communications owner has complete thread context" - name: "github-mcp-server-search_issues" description: "Search for candidate issues or prior squad responses" when: "Use when filtering by keywords, labels, or duplicate response checks" @@ -23,10 +23,10 @@ tools: Phase 1 is **draft-only mode**. -- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. -- **Human review gate is mandatory** — the communications owner never posts autonomously. +- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — the communications owner never posts autonomously. - Every action is logged to `.squad/comms/audit/`. -- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. +- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. ## Patterns @@ -47,7 +47,7 @@ Discussions use the GitHub Discussions API, which differs from issues: - **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions - **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) -- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. - **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. ### 2. Classify @@ -107,7 +107,7 @@ Use the humanizer skill for every draft. ### Thread-Read Verification -Before drafting, the communications owner MUST verify complete thread coverage: +Before drafting, the communications owner MUST verify complete thread coverage: 1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. 2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. @@ -120,7 +120,7 @@ Before drafting, the communications owner MUST verify complete thread coverage: Show drafts for review in this exact format: ```text -📝 Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -139,9 +139,9 @@ Each full draft must begin with the thread summary line: Wait for explicit human direction before anything is posted. -- `comms approve 1 3` — approve drafts 1 and 3 -- `comms edit 2` — edit draft 2 -- `comms skip` — skip all +- `comms approve 1 3` — approve drafts 1 and 3 +- `comms edit 2` — edit draft 2 +- `comms skip` — skip all - `banana` — freeze all pending (safe word) ### Rollback — Bad Post Recovery @@ -152,12 +152,12 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` 2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content -3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle +3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle 4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case **Safe word — `banana`:** - Immediately freezes all pending drafts in the review queue -- No new scans or drafts until `comms resume` is issued +- No new scans or drafts until `comms resume` is issued - Audit entry logged with halter identity and reason ### 6. Post @@ -165,7 +165,7 @@ If a posted response turns out to be wrong, inappropriate, or needs correction: After approval: - Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. -- The communications owner helps by preparing the CLI command. +- The communications owner helps by preparing the CLI command. - Write the audit entry after the posting action. ### 7. Audit @@ -190,7 +190,7 @@ gh issue list --state open --json number,title,author,labels,comments --limit 20 ### Example review table ```text -📝 Community Response Drafts +📝 Community Response Drafts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | # | Item | Author | Type | Confidence | Read | Preview | @@ -319,7 +319,7 @@ That context will help us narrow down what's happening. Appreciate it! - ❌ Posting without human review (NEVER — this is the cardinal rule) - ❌ Drafting without reading full thread (context is everything) -- ❌ Ignoring confidence flags (🔴 items need Lead or human review) +- ❌ Ignoring confidence flags (🔴 items need Lead or human review) - ❌ Scanning closed issues (only open items) - ❌ Responding to issues labeled `squad:internal` or `wontfix` - ❌ Skipping audit logging (every action must be recorded) diff --git a/packages/squad-sdk/templates/skills/history-hygiene/SKILL.md b/packages/squad-sdk/templates/skills/history-hygiene/SKILL.md index 453a03b4e..b0f61417c 100644 --- a/packages/squad-sdk/templates/skills/history-hygiene/SKILL.md +++ b/packages/squad-sdk/templates/skills/history-hygiene/SKILL.md @@ -3,12 +3,12 @@ name: history-hygiene description: Record final outcomes to history.md, not intermediate requests or reversed decisions domain: documentation, team-collaboration confidence: high -source: earned (Kobayashi v0.6.0 incident, team intervention) +source: earned (release-history correction incident) --- ## Context -History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake. +History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. A release incident proved this: history retained an obsolete v0.6.0 target after the user had changed it to v0.8.17. Future spawns read the wrong truth and repeated the mistake. ## Patterns @@ -20,11 +20,11 @@ History files (.md files tracking decisions, spawns, outcomes) are read cold by ## Examples ✓ **Correct:** -- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)" -- "Reverted to Node 18 per Brady's explicit request on 2024-01-15" +- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by the user)" +- "Reverted to Node 18 per the user's explicit request on 2024-01-15" ✗ **Incorrect:** -- "Brady directed v0.6.0" (when later reversed) +- "The user directed v0.6.0" (when later reversed) - Recording what was *requested* instead of what *actually happened* - Logging entries before outcome is confirmed diff --git a/packages/squad-sdk/templates/skills/humanizer/SKILL.md b/packages/squad-sdk/templates/skills/humanizer/SKILL.md index f3bfaa06c..eb28d5db8 100644 --- a/packages/squad-sdk/templates/skills/humanizer/SKILL.md +++ b/packages/squad-sdk/templates/skills/humanizer/SKILL.md @@ -3,16 +3,16 @@ name: "humanizer" description: "Tone enforcement patterns for external-facing community responses" domain: "communication, tone, community" confidence: "low" -source: "manual (external communications workflow)" +source: "manual (external communications workflow)" --- ## Context -Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. - Tone must be warm, helpful, and human-sounding — never robotic or corporate. -- Brady's constraint applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. +- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. ## Patterns @@ -98,7 +98,7 @@ We'll dig deeper and update this thread. - ❌ Dismissive: "This works as designed" without empathy - ❌ Over-promising: "We'll ship this next week" without commitment from the team - ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" - ❌ Excessive emoji: More than 1-2 emoji per response - ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead - ❌ Link-dumping: Pasting URLs without context ("See: https://...") diff --git a/packages/squad-sdk/templates/skills/notification-routing/SKILL.md b/packages/squad-sdk/templates/skills/notification-routing/SKILL.md index 2b2df1fec..42c5cb075 100644 --- a/packages/squad-sdk/templates/skills/notification-routing/SKILL.md +++ b/packages/squad-sdk/templates/skills/notification-routing/SKILL.md @@ -56,7 +56,7 @@ Agents prefix their output with `CHANNEL:` to signal where the notificatio ``` CHANNEL:security -Worf found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5 +Security Reviewer found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5 ``` ### Routing Dispatcher (shell pseudocode) diff --git a/packages/squad-sdk/templates/skills/reskill/SKILL.md b/packages/squad-sdk/templates/skills/reskill/SKILL.md index 946de0e0b..c9e6184de 100644 --- a/packages/squad-sdk/templates/skills/reskill/SKILL.md +++ b/packages/squad-sdk/templates/skills/reskill/SKILL.md @@ -3,7 +3,7 @@ name: "reskill" description: "Team-wide charter and history optimization through skill extraction" domain: "team-optimization" confidence: "high" -source: "manual — Brady directive to reduce per-agent context overhead" +source: "manual — reduce per-agent context overhead" --- ## Context diff --git a/packages/squad-sdk/templates/skills/reviewer-protocol/SKILL.md b/packages/squad-sdk/templates/skills/reviewer-protocol/SKILL.md index 5d589105c..1f8e98430 100644 --- a/packages/squad-sdk/templates/skills/reviewer-protocol/SKILL.md +++ b/packages/squad-sdk/templates/skills/reviewer-protocol/SKILL.md @@ -38,35 +38,35 @@ When an artifact is **rejected** by a Reviewer: ## Examples **Example 1: Reassign after rejection** -1. Fenster writes authentication module -2. Hockney (Tester) reviews → rejects: "Error handling is missing. Verbal should fix this." -3. Coordinator: Fenster is now locked out of this artifact -4. Coordinator spawns Verbal to revise the authentication module -5. Verbal produces v2 -6. Hockney reviews v2 → approves +1. Runtime Engineer writes authentication module +2. Quality Engineer reviews → rejects: "Error handling is missing. Another engineer should fix this." +3. Coordinator: Runtime Engineer is now locked out of this artifact +4. Coordinator spawns a different engineer to revise the authentication module +5. The revision engineer produces v2 +6. Quality Engineer reviews v2 → approves 7. Lockout clears for next artifact **Example 2: Escalate for expertise** -1. Edie writes TypeScript config -2. Keaton (Lead) reviews → rejects: "Need someone with deeper TS knowledge. Escalate." -3. Coordinator: Edie is now locked out +1. Original Author writes TypeScript config +2. Lead reviews → rejects: "Need someone with deeper TS knowledge. Escalate." +3. Coordinator: Original Author is now locked out 4. Coordinator spawns new agent (or existing TS expert) to revise 5. New agent produces v2 -6. Keaton reviews v2 +6. Lead reviews v2 **Example 3: Deadlock handling** -1. Fenster writes module → rejected -2. Verbal revises → rejected -3. Hockney revises → rejected +1. Original Author writes module → rejected +2. Revision Engineer revises → rejected +3. Quality Engineer revises → rejected 4. All 3 eligible agents are now locked out 5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]" **Example 4: Reviewer accidentally names original author** -1. Fenster writes module → rejected -2. Hockney says: "Fenster should fix the error handling" -3. Coordinator: "Fenster is locked out as the original author. Please name a different agent." -4. Hockney: "Verbal, then" -5. Coordinator spawns Verbal +1. Original Author writes module → rejected +2. Quality Engineer says: "The original author should fix the error handling" +3. Coordinator: "The original author is locked out. Please name a different agent." +4. Quality Engineer names a revision engineer +5. Coordinator spawns the revision engineer ## Anti-Patterns diff --git a/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md b/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md index 3f3aebb0a..5f3fd785d 100644 --- a/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md +++ b/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md @@ -4,13 +4,13 @@ description: "Internals of how @bradygaster/squad-cli stamps its version, how `s allowedTools: [] confidence: medium domain: squad-internals -source: "Discovered by Data; validated in bradygaster/squad#1173 recon (2026-05-26)." +source: "validated in bradygaster/squad#1173 recon (2026-05-26)." --- # SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics **Confidence:** medium -**Discovered by:** Data +**Discovered by:** repository investigation **Date:** 2026-05-26 **Validated in:** Issue #1173 recon (bradygaster/squad) diff --git a/packages/squad-sdk/templates/skills/test-discipline/SKILL.md b/packages/squad-sdk/templates/skills/test-discipline/SKILL.md index d222bed52..9f85fba96 100644 --- a/packages/squad-sdk/templates/skills/test-discipline/SKILL.md +++ b/packages/squad-sdk/templates/skills/test-discipline/SKILL.md @@ -3,7 +3,7 @@ name: "test-discipline" description: "Update tests when changing APIs — no exceptions" domain: "quality" confidence: "high" -source: "earned (Fenster/Hockney incident, test assertion sync violations)" +source: "earned (test assertion sync violations)" --- ## Context diff --git a/packages/squad-sdk/templates/spawn-reference.md b/packages/squad-sdk/templates/spawn-reference.md index b5e1748bc..a89c2dbb1 100644 --- a/packages/squad-sdk/templates/spawn-reference.md +++ b/packages/squad-sdk/templates/spawn-reference.md @@ -61,7 +61,7 @@ Standard spawn via `task` tool — used in CLI, or as fallback when `create_sess - **`agent_type`**: `"general-purpose"` (always — this gives agents full tool access) - **`mode`**: `"background"` (default) or `"sync"` — use `"background"` for all parallelizable work; use `"sync"` only when the result is needed before the next step can proceed -- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Ripley: Design REST API endpoints"`, `"Dallas: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing +- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Runtime Engineer: Design REST API endpoints"`, `"Experience Engineer: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing - **`prompt`**: The full agent prompt (see below) **⚡ Inline the charter.** Before spawning, read the agent's `charter.md` (resolve from team root: `{team_root}/.squad/agents/{name}/charter.md`) and paste its contents directly into the spawn prompt. This eliminates a tool call from the agent's critical path. The agent still reads its own `history.md` and `decisions.md`. diff --git a/packages/squad-sdk/templates/squad.agent.md.template b/packages/squad-sdk/templates/squad.agent.md.template index a2bf7384c..708edca2b 100644 --- a/packages/squad-sdk/templates/squad.agent.md.template +++ b/packages/squad-sdk/templates/squad.agent.md.template @@ -176,11 +176,11 @@ For each squad member with assigned issues, note them in the session context. Wh **The user should never see a blank screen while agents work.** Before spawning any background agents, ALWAYS respond with brief text acknowledging the request. Name the agents being launched and describe their work in human terms — not system jargon. This acknowledgment is REQUIRED, not optional. -- **Single agent:** `"Fenster's on it — looking at the error handling now."` +- **Single agent:** `"Runtime Engineer is on it — looking at the error handling now."` - **Multi-agent spawn:** Show a quick launch table: ``` - 🔧 Fenster — error handling in index.js - 🧪 Hockney — writing test cases + 🔧 Runtime Engineer — error handling in index.js + 🧪 Quality Engineer — writing test cases 📋 Scribe — logging session ``` @@ -214,9 +214,9 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use 👤 as fallback **Examples:** -- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"` -- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"` -- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` +- `name: "lead"`, `description: "🏗️ Lead: Reviewing architecture proposal"` +- `name: "runtime-engineer"`, `description: "🔧 Runtime Engineer: Refactoring auth module"` +- `name: "quality-engineer"`, `description: "🧪 Quality Engineer: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. @@ -234,7 +234,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa **NOT directives** (route normally): - Work requests ("build X", "fix Y", "test Z", "add a feature") - Questions ("how does X work?", "what did the team do?") -- Agent-directed tasks ("Ripley, refactor the API") +- Agent-directed tasks ("Runtime Engineer, refactor the API") **When you detect a directive:** @@ -288,7 +288,7 @@ The routing table determines **WHO** handles work. After routing, use Response M | Signal | Action | |--------|--------| -| Names someone ("Ripley, fix the button") | Spawn that agent | +| Names someone ("Experience Engineer, fix the button") | Spawn that agent | | Personal agent by name (user addresses a personal agent) | Route to personal agent in consult mode — they advise, project agent executes changes | | "Team" or multi-domain question | Spawn 2-3+ relevant agents in parallel, synthesize | | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) | @@ -654,7 +654,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without dispatching via the platform's tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Dispatch to the real agent and let it respond. 3. **Never skip dispatching (via `task` or `runSubagent`) for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "experience-engineer"` is right. `"General purpose task"` is wrong — `"Experience Engineer: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict. ### After Agent Work diff --git a/packages/squad-sdk/templates/workflows/squad-triage.yml b/packages/squad-sdk/templates/workflows/squad-triage.yml index 627626aaf..579f74d29 100644 --- a/packages/squad-sdk/templates/workflows/squad-triage.yml +++ b/packages/squad-sdk/templates/workflows/squad-triage.yml @@ -91,10 +91,12 @@ jobs: } function findLead(teamMembers) { - return teamMembers.find(member => { + const hasRoleToken = (member, token) => { const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; - return roleWords.includes('lead'); - }); + return roleWords.includes(token); + }; + return teamMembers.find(member => hasRoleToken(member, 'lead')) || + teamMembers.find(member => hasRoleToken(member, 'architect')); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } @@ -127,7 +129,12 @@ jobs: const headers = tableCells(line).map(cell => cell.toLowerCase()); const workTypeIndex = headers.indexOf('work type'); - const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const routeIndex = headers.findIndex(header => + header === 'route to' || + header === 'agent' || + header === 'primary' || + header === 'primary agent' + ); const examplesIndex = headers.indexOf('examples'); if (workTypeIndex < 0 || routeIndex < 0) continue; @@ -140,16 +147,11 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinationNames = routeCell - .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) - .map(normalizeRouteDestination) - .filter(Boolean); - const destinations = teamMembers.filter(member => - destinationNames.includes(normalizeRouteDestination(member.name)) + const destinationName = normalizeRouteDestination(routeCell); + const member = teamMembers.find(candidate => + normalizeRouteDestination(candidate.name) === destinationName ); - for (const member of destinations) { - rules.push({ member, workType, examples }); - } + if (member) rules.push({ member, workType, examples }); } break; } @@ -158,28 +160,34 @@ jobs: } function routeScore(issueText, rule) { - const stopWords = new Set([ - 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', - 'work', 'owner', 'agent', 'support', 'management', + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', ]); - const phrases = rule.workType - .toLowerCase() - .split(/[,/&]+/) - .map(value => value.trim()) - .filter(value => value.length >= 4); - const keywords = `${rule.workType} ${rule.examples}` - .toLowerCase() - .match(/[a-z0-9@.+#-]+/g) || []; - - let score = phrases.reduce( - (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), - 0 - ); - for (const keyword of new Set(keywords)) { - if (keyword.length < 3 || stopWords.has(keyword)) continue; - if (issueText.includes(keyword)) score++; + + function tokens(value) { + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + } + + function containsPhrase(haystack, needle) { + if (needle.length === 0 || needle.length > haystack.length) return false; + return haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); } - return score; + + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter(token => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.examples.split(/[,;]+/)] + .flatMap(phrase => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + + return rawPhrases.reduce((best, phrase) => { + const phraseTokens = tokens(phrase); + if (!containsPhrase(issueTokens, phraseTokens)) return best; + const specificity = phraseTokens.length * 100; + return Math.max(best, specificity); + }, 0); } function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { @@ -192,7 +200,16 @@ jobs: return { member: lead, workType: null }; } - const best = scoredRoutes[0]; + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter(candidate => candidate.score === bestScore); + const bestMembers = new Set(bestRoutes.map(candidate => + normalizeRouteDestination(candidate.rule.member.name) + )); + if (bestMembers.size !== 1) { + return { member: lead, workType: null }; + } + + const best = bestRoutes[0]; return { member: best.rule.member, workType: best.rule.workType }; } diff --git a/scripts/size-regression-guard.mjs b/scripts/size-regression-guard.mjs index 3f451222e..634ae1d3c 100644 --- a/scripts/size-regression-guard.mjs +++ b/scripts/size-regression-guard.mjs @@ -226,7 +226,10 @@ function extractFrontmatter(text) { } function measureAlwaysLoadedSkillFrontmatter() { - const skillFiles = [...findSkillFiles('.copilot/skills'), ...findSkillFiles('.squad/skills')]; + const skillFiles = [ + ...findSkillFiles('.copilot/skills'), + ...findSkillFiles('.squad-templates/skills'), + ]; const alwaysOn = []; for (const path of skillFiles) { const text = readText(path); diff --git a/scripts/sync-skill-templates.mjs b/scripts/sync-skill-templates.mjs index fc685e089..a57ab4566 100644 --- a/scripts/sync-skill-templates.mjs +++ b/scripts/sync-skill-templates.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node -import { readdirSync, cpSync, existsSync, statSync } from 'fs'; +import { readdirSync, cpSync, existsSync, mkdirSync, rmSync, statSync } from 'fs'; import { join } from 'path'; import { fileURLToPath } from 'url'; import { dirname } from 'path'; @@ -9,13 +9,14 @@ const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); const rootDir = join(__dirname, '..'); -const skillsSourceDir = join(rootDir, '.squad', 'skills'); +const skillsSourceDir = join(rootDir, '.squad-templates', 'skills'); const targets = [ + join(rootDir, 'templates', 'skills'), join(rootDir, 'packages', 'squad-cli', 'templates', 'skills'), join(rootDir, 'packages', 'squad-sdk', 'templates', 'skills') ]; -console.log('🔄 Syncing skill templates from canonical source...\n'); +console.log('🔄 Syncing skill templates from product-owned canonical source...\n'); if (!existsSync(skillsSourceDir)) { console.error(`❌ Source directory not found: ${skillsSourceDir}`); @@ -36,6 +37,8 @@ console.log(`📁 Found ${skillDirs.length} skill(s): ${skillDirs.join(', ')}\n` for (const target of targets) { console.log(`📦 Syncing to: ${target}`); + rmSync(target, { recursive: true, force: true }); + mkdirSync(target, { recursive: true }); for (const skillName of skillDirs) { const sourcePath = join(skillsSourceDir, skillName); diff --git a/scripts/sync-templates.mjs b/scripts/sync-templates.mjs index 8979a730e..b3cdfe98e 100644 --- a/scripts/sync-templates.mjs +++ b/scripts/sync-templates.mjs @@ -9,11 +9,12 @@ * packages/squad-sdk/templates/ (SDK package) * .github/agents/squad.agent.md (GitHub agent — squad.agent.md only) * - * Only copies files that exist in .squad-templates/. Target directories - * that don't exist are skipped with a warning. + * The managed skills subtree is replaced as an exact set so removed canonical + * skills cannot survive indefinitely in package artifacts. Other template + * paths are copied additively for backward compatibility. */ -import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, statSync } from 'node:fs'; +import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, rmSync, statSync } from 'node:fs'; import { join, dirname, relative } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -27,8 +28,7 @@ const ROOT = join(__dirname, '..'); // --------------------------------------------------------------------------- const explicitFlag = process.argv.includes('--sync'); const envFlag = process.env.SQUAD_SYNC_TEMPLATES === '1'; -const directInvocation = process.argv.length <= 2; -if (!directInvocation && !explicitFlag && !envFlag) { +if (!explicitFlag && !envFlag) { console.log('⛔ sync-templates requires explicit invocation.'); console.log(' Use: node scripts/sync-templates.mjs --sync'); console.log(' Or: SQUAD_SYNC_TEMPLATES=1 node scripts/sync-templates.mjs'); @@ -89,6 +89,13 @@ if (!existsSync(SOURCE)) { const sourceFiles = collectFiles(SOURCE); let totalCopied = 0; +for (const targetDir of MIRROR_TARGETS) { + if (!existsSync(targetDir)) continue; + const managedSkillsDir = join(targetDir, 'skills'); + rmSync(managedSkillsDir, { recursive: true, force: true }); + mkdirSync(managedSkillsDir, { recursive: true }); +} + for (const relFile of sourceFiles) { const srcPath = join(SOURCE, relFile); const targets = []; diff --git a/squad.config.ts b/squad.config.ts deleted file mode 100644 index 5093f3bf8..000000000 --- a/squad.config.ts +++ /dev/null @@ -1,89 +0,0 @@ -import { - defineSquad, - defineTeam, - defineAgent, - defineRouting, - defineCasting, -} from '@bradygaster/squad-sdk'; - -/** - * Squad Configuration — squad-sdk - * - * Converted from .squad/ markdown to SDK-first builder syntax. - * Run `squad build` to regenerate .squad/*.md from this file. - */ -export default defineSquad({ - version: '1.0.0', - - team: defineTeam({ - name: 'squad-sdk', - description: 'The programmable multi-agent runtime for GitHub Copilot.', - projectContext: - '- **Owner:** Brady\n' + - '- **Stack:** TypeScript (strict mode, ESM-only), Node.js ≥20, @github/copilot-sdk, Vitest, esbuild\n' + - '- **Description:** The programmable multi-agent runtime for GitHub Copilot — v1 replatform of Squad beta\n' + - '- **Distribution:** npm (`npm install -g @bradygaster/squad-cli` for CLI, `npm install @bradygaster/squad-sdk` for SDK)\n' + - '- **Created:** 2026-02-21', - members: [ - 'keaton', 'verbal', 'fenster', 'hockney', 'mcmanus', 'kujan', - 'edie', 'kobayashi', 'fortier', 'rabin', 'baer', 'redfoot', - 'strausz', 'saul', 'kovash', 'marquez', 'cheritto', 'breedan', - 'nate', 'waingro', - ], - }), - - agents: [ - defineAgent({ name: 'keaton', role: 'Lead', description: 'Architect, scope-holder, the one who sees the whole board.', status: 'active' }), - defineAgent({ name: 'verbal', role: 'Prompt Engineer', description: 'Crafts prompts, charters, and coordinator logic.', status: 'active' }), - defineAgent({ name: 'fenster', role: 'Core Dev', description: 'Practical, thorough, makes it work then makes it right.', status: 'active' }), - defineAgent({ name: 'hockney', role: 'Tester', description: 'If it is not tested, it does not work.', status: 'active' }), - defineAgent({ name: 'mcmanus', role: 'DevRel', description: 'Docs, messaging, developer experience.', status: 'active' }), - defineAgent({ name: 'kujan', role: 'SDK Expert', description: 'The one who understands the Copilot SDK inside and out.', status: 'active' }), - defineAgent({ name: 'edie', role: 'TypeScript Engineer', description: 'Precise, type-obsessed. Types are contracts. If it compiles, it works.', status: 'active' }), - defineAgent({ name: 'kobayashi', role: 'Git & Release', description: 'Semantic versioning, releases, branch protection.', status: 'active' }), - defineAgent({ name: 'fortier', role: 'Node.js Runtime', description: 'Streaming, event loop health, async iterators, memory profiling.', status: 'active' }), - defineAgent({ name: 'rabin', role: 'Distribution', description: 'npm packaging, esbuild config, global install, marketplace.', status: 'active' }), - defineAgent({ name: 'baer', role: 'Security', description: 'Hook design, PII filters, file-write guards, compliance.', status: 'active' }), - defineAgent({ name: 'redfoot', role: 'Graphic Designer', description: 'Logo, icons, brand assets, design system.', status: 'active' }), - defineAgent({ name: 'strausz', role: 'VS Code Extension', description: 'VS Code Extension API, runSubagent, editor integration.', status: 'active' }), - defineAgent({ name: 'saul', role: 'Aspire & Observability', description: 'Aspire dashboard, OTLP integration, Docker telemetry.', status: 'active' }), - defineAgent({ name: 'kovash', role: 'REPL & Interactive Shell', description: 'Interactive shell, Ink components, session dispatch.', status: 'active' }), - defineAgent({ name: 'marquez', role: 'CLI UX Designer', description: 'Interaction design, copy, spacing, affordances, UX gates.', status: 'active' }), - defineAgent({ name: 'cheritto', role: 'TUI Engineer', description: 'Ink components, layout, input handling, rendering perf.', status: 'active' }), - defineAgent({ name: 'breedan', role: 'E2E Test Engineer', description: 'node-pty harness, Gherkin features, frame snapshots.', status: 'active' }), - defineAgent({ name: 'nate', role: 'Accessibility Reviewer', description: 'Keyboard nav, color contrast, error guidance, shortcut discoverability.', status: 'active' }), - defineAgent({ name: 'waingro', role: 'Product Dogfooder', description: 'Adversarial testing, edge cases, regression scenarios.', status: 'active' }), - ], - - routing: defineRouting({ - rules: [ - { pattern: 'core-runtime', agents: ['@fenster'], description: 'CopilotClient, adapter, session pool, tools module, spawn orchestration' }, - { pattern: 'prompt-architecture', agents: ['@verbal'], description: 'Agent charters, spawn templates, coordinator logic, response tier selection' }, - { pattern: 'type-system', agents: ['@edie'], description: 'Discriminated unions, generics, tsconfig, strict mode, declaration files' }, - { pattern: 'sdk-integration', agents: ['@kujan'], description: '@github/copilot-sdk usage, CopilotSession lifecycle, event handling' }, - { pattern: 'runtime-performance', agents: ['@fortier'], description: 'Streaming, event loop health, session management, async iterators' }, - { pattern: 'testing', agents: ['@hockney'], description: 'Test coverage, Vitest, edge cases, CI/CD, quality gates' }, - { pattern: 'documentation', agents: ['@mcmanus'], description: 'README, API docs, getting-started, demos, tone review' }, - { pattern: 'architecture', agents: ['@keaton'], description: 'Product direction, architectural decisions, code review, scope' }, - { pattern: 'distribution', agents: ['@rabin'], description: 'npm packaging, esbuild config, global install, marketplace prep' }, - { pattern: 'git-releases', agents: ['@kobayashi'], description: 'Semantic versioning, GitHub Releases, CI/CD, branch protection' }, - { pattern: 'security', agents: ['@baer'], description: 'Hook design, PII filters, security review, compliance' }, - { pattern: 'visual-identity', agents: ['@redfoot'], description: 'Logo, icons, brand assets, design system' }, - { pattern: 'observability', agents: ['@saul'], description: 'Aspire dashboard, OTLP integration, Playwright E2E, Docker telemetry' }, - { pattern: 'vscode-integration', agents: ['@strausz'], description: 'VS Code Extension API, runSubagent compatibility' }, - { pattern: 'repl-shell', agents: ['@kovash'], description: 'Interactive shell, Ink components, session dispatch' }, - { pattern: 'cli-ux', agents: ['@marquez'], description: 'Interaction design, copy, spacing, affordances, UX gates' }, - { pattern: 'tui', agents: ['@cheritto'], description: 'Ink components, layout, input handling, focus management' }, - { pattern: 'e2e-tests', agents: ['@breedan'], description: 'node-pty harness, Gherkin features, frame snapshots' }, - { pattern: 'accessibility', agents: ['@nate'], description: 'Keyboard nav, color contrast, error guidance' }, - { pattern: 'hostile-qa', agents: ['@waingro'], description: 'Adversarial testing, edge cases, regression scenarios' }, - ], - defaultAgent: '@keaton', - fallback: 'coordinator', - }), - - casting: defineCasting({ - allowlistUniverses: ['The Usual Suspects', 'Breaking Bad', 'The Wire', 'Firefly'], - overflowStrategy: 'generic', - }), -}); diff --git a/templates/machine-capabilities.md b/templates/machine-capabilities.md index b770fd04b..65f3c478a 100644 --- a/templates/machine-capabilities.md +++ b/templates/machine-capabilities.md @@ -47,7 +47,7 @@ squad watch --interval 5 Ralph will log skipped issues: ``` ⏭️ Skipping #42 "Train ML model" — missing: gpu -✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule) +✓ Triaged #43 "Fix CSS layout" → Experience Engineer (routing-rule) ``` ## How It Works diff --git a/templates/model-selection-reference.md b/templates/model-selection-reference.md index 43eba9e5e..ffc51eb71 100644 --- a/templates/model-selection-reference.md +++ b/templates/model-selection-reference.md @@ -85,11 +85,11 @@ If you've exhausted the fallback chain and reached the platform default fallback When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-5) — refactoring auth module -🎨 Redfoot (gpt-5.6-sol · vision) — designing color system +🔧 Runtime Engineer (claude-sonnet-5) — refactoring auth module +🎨 Experience Engineer (gpt-5.6-sol · vision) — designing color system 📋 Scribe (gpt-5.6-luna · fast) — logging session -⚡ Keaton (gpt-5.6-sol · bumped for architecture) — reviewing proposal -📝 McManus (gpt-5.6-luna · fast) — updating docs +⚡ Lead (gpt-5.6-sol · bumped for architecture) — reviewing proposal +📝 Docs Engineer (gpt-5.6-luna · fast) — updating docs ``` Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name. diff --git a/templates/notes-protocol.md b/templates/notes-protocol.md index 5a1d03a5f..800066f80 100644 --- a/templates/notes-protocol.md +++ b/templates/notes-protocol.md @@ -28,11 +28,8 @@ Each agent writes to its own namespace to prevent conflicts: | Namespace | Owner | Purpose | |-----------|-------|---------| -| `refs/notes/squad/data` | Data | Architecture decisions, implementation choices | -| `refs/notes/squad/worf` | Worf | Security reviews, vulnerability assessments | -| `refs/notes/squad/seven` | Seven | Documentation quality, API contract decisions | +| `refs/notes/squad/{agent-id}` | Current agent | Agent-owned decisions and implementation context | | `refs/notes/squad/ralph` | Ralph | Work-round progress, task-state annotations | -| `refs/notes/squad/q` | Q | Devil's advocate findings, risk assessments | | `refs/notes/squad/research` | Any agent | Research notes that should survive branch deletion | | `refs/notes/squad/review` | Any agent | Code review context (mirrors Gerrit's pattern) | @@ -47,7 +44,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision | research | review | progress | security", "content": "..." @@ -58,7 +55,7 @@ All notes MUST be valid JSON. Minimum required fields: ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "decision", "decision": "Use JWT RS256 for auth middleware", @@ -76,7 +73,7 @@ Set `"promote_to_permanent": true` to signal Ralph to copy this to ```json { - "agent": "Data", + "agent": "{AgentName}", "timestamp": "2026-03-23T14:00:00Z", "type": "research", "topic": "JWT vs session tokens", diff --git a/templates/ralph-triage.js b/templates/ralph-triage.js index 863da3d7d..2e05eb971 100644 --- a/templates/ralph-triage.js +++ b/templates/ralph-triage.js @@ -58,11 +58,19 @@ function normalizeEol(content) { function slugify(text) { return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } function parseRoutingRules(routingMd) { - const table = parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i); + const table = + parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i) || + parseTableSection(routingMd, /^##\s*routing\s*table\b/i); if (!table) return []; const workTypeIndex = findColumnIndex(table.headers, ['work type', 'type']); - const agentIndex = findColumnIndex(table.headers, ['agent', 'route to', 'route']); + const agentIndex = findColumnIndex(table.headers, [ + 'agent', + 'route to', + 'route', + 'primary agent', + 'primary', + ]); const examplesIndex = findColumnIndex(table.headers, ['examples', 'example']); if (workTypeIndex < 0 || agentIndex < 0) return []; @@ -564,4 +572,10 @@ if (require.main === module) { }); } -module.exports = { resolveGithubApiBase }; +module.exports = { + parseModuleOwnership, + parseRoster, + parseRoutingRules, + resolveGithubApiBase, + triageIssue, +}; diff --git a/templates/skills/agent-collaboration/SKILL.md b/templates/skills/agent-collaboration/SKILL.md new file mode 100644 index 000000000..054463cf8 --- /dev/null +++ b/templates/skills/agent-collaboration/SKILL.md @@ -0,0 +1,42 @@ +--- +name: "agent-collaboration" +description: "Standard collaboration patterns for all squad agents — worktree awareness, decisions, cross-agent communication" +domain: "team-workflow" +confidence: "high" +source: "extracted from charter boilerplate — identical content in 18+ agent charters" +--- + +## Context + +Every agent on the team follows identical collaboration patterns for worktree awareness, decision recording, and cross-agent communication. These were previously duplicated in every charter's Collaboration section (~300 bytes × 18 agents = ~5.4KB of redundant context). Now centralized here. + +The coordinator's spawn prompt already instructs agents to read decisions.md and their history.md. This skill adds the patterns for WRITING decisions and requesting help. + +## Patterns + +### Worktree Awareness +Use the `TEAM ROOT` path provided in your spawn prompt. All `.squad/` paths are relative to this root. If TEAM ROOT is not provided (rare), run `git rev-parse --show-toplevel` as fallback. Never assume CWD is the repo root. + +### Decision Recording +After making a decision that affects other team members, write it to: +`.squad/decisions/inbox/{your-name}-{brief-slug}.md` + +Format: +``` +### {date}: {decision title} +**By:** {Your Name} +**What:** {the decision} +**Why:** {rationale} +``` + +### Cross-Agent Communication +If you need another team member's input, say so in your response. The coordinator will bring them in. Don't try to do work outside your domain. + +### Reviewer Protocol +If you have reviewer authority and reject work: the original author is locked out from revising that artifact. A different agent must own the revision. State who should revise in your rejection response. + +## Anti-Patterns +- Don't read all agent charters — you only need your own context + decisions.md +- Don't write directly to `.squad/decisions.md` — always use the inbox drop-box +- Don't modify other agents' history.md files — that's Scribe's job +- Don't assume CWD is the repo root — always use TEAM ROOT diff --git a/templates/skills/agent-conduct/SKILL.md b/templates/skills/agent-conduct/SKILL.md new file mode 100644 index 000000000..df87276a0 --- /dev/null +++ b/templates/skills/agent-conduct/SKILL.md @@ -0,0 +1,24 @@ +--- +name: "agent-conduct" +description: "Shared hard rules enforced across all squad agents" +domain: "team-governance" +confidence: "high" +source: "reskill extraction — Product Isolation Rule and Peer Quality Check appeared in all 20 agent charters" +--- + +## Context + +Every squad agent must follow these two hard rules. They were previously duplicated in every charter. Now they live here as a shared skill, loaded once. + +## Patterns + +### Product Isolation Rule (hard rule) +Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to cast-specific agent names in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot"). + +### Peer Quality Check (hard rule) +Before finishing work, verify your changes don't break existing tests. Run the test suite for files you touched. If CI has been failing, check your changes aren't contributing to the problem. When you learn from mistakes, update your history.md. + +## Anti-Patterns +- Don't hardcode dev team agent names in product code or tests +- Don't skip test verification before declaring work done +- Don't ignore pre-existing CI failures that your changes may worsen diff --git a/templates/skills/architectural-proposals/SKILL.md b/templates/skills/architectural-proposals/SKILL.md new file mode 100644 index 000000000..4128ff096 --- /dev/null +++ b/templates/skills/architectural-proposals/SKILL.md @@ -0,0 +1,151 @@ +--- +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:** Product Lead (product direction), Runtime Engineer (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/templates/skills/ci-validation-gates/SKILL.md b/templates/skills/ci-validation-gates/SKILL.md new file mode 100644 index 000000000..9c120ac1d --- /dev/null +++ b/templates/skills/ci-validation-gates/SKILL.md @@ -0,0 +1,84 @@ +--- +name: "ci-validation-gates" +description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22" +domain: "ci-cd" +confidence: "high" +source: "earned knowledge from the v0.8.22 release incident" +--- + +## Context + +CI workflows must be defensive. These patterns were learned from the v0.8.22 release incident where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. The reusable lessons are centralized here rather than tied to individual agent charters. + +## Patterns + +### Semver Validation Gate +Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them. + +```yaml +- name: Validate semver + run: | + VERSION="${{ github.event.release.tag_name }}" + VERSION="${VERSION#v}" + if ! npx semver "$VERSION" > /dev/null 2>&1; then + echo "❌ Invalid semver: $VERSION" + echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid." + exit 1 + fi + echo "✅ Valid semver: $VERSION" +``` + +### NPM Token Type Verification +NPM_TOKEN MUST be an Automation token, not a User token with 2FA: +- User tokens require OTP — CI can't provide it → EOTP error +- Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation +- Verify before first publish in any workflow + +### Retry Logic for npm Registry Propagation +npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable. +- Propagation: typically 5-30s, up to 2min in rare cases +- All verify steps: 5 attempts, 15-second intervals +- Log each attempt: "Attempt 1/5: Checking package..." +- Exit loop on success, fail after max attempts + +```yaml +- name: Verify package (with retry) + run: | + MAX_ATTEMPTS=5 + WAIT_SECONDS=15 + for attempt in $(seq 1 $MAX_ATTEMPTS); do + echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..." + if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then + echo "✅ Package verified" + exit 0 + fi + [ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS + done + echo "❌ Failed to verify after $MAX_ATTEMPTS attempts" + exit 1 +``` + +### Draft Release Detection +Draft releases don't emit `release: published` event. Workflows MUST: +- Trigger on `release: published` (NOT `created`) +- If using workflow_dispatch: verify release is published via GitHub API before proceeding + +### Build Script Protection +Set `SKIP_BUILD_BUMP=1` (or `$env:SKIP_BUILD_BUMP = "1"` on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions. + +## Known Failure Modes (v0.8.22 Incident) + +| # | What Happened | Root Cause | Prevention | +|---|---------------|-----------|------------| +| 1 | 4-part version published, npm mangled it | No semver validation gate | `npx semver` check before every publish | +| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only | +| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals | +| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases | +| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 | + +## Anti-Patterns +- ❌ Publishing without semver validation gate +- ❌ Single-shot verification without retry +- ❌ Hard-coded secrets in workflows +- ❌ Silent CI failures — every error needs actionable output with remediation +- ❌ Assuming npm publish is instantly queryable diff --git a/templates/skills/cli-wiring/SKILL.md b/templates/skills/cli-wiring/SKILL.md new file mode 100644 index 000000000..5b315b02d --- /dev/null +++ b/templates/skills/cli-wiring/SKILL.md @@ -0,0 +1,47 @@ +# Skill: CLI Command Wiring + +**Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. + +## Checklist — Adding a New CLI Command + +1. **Create command file** in `packages/squad-cli/src/cli/commands/.ts` + - Export a `run(cwd, options)` async function (or class with static methods for utility modules) + +2. **Add routing block** in `packages/squad-cli/src/cli-entry.ts` inside `main()`: + ```ts + if (cmd === '') { + const { run } = await import('./cli/commands/.js'); + // parse args, call function + await run(process.cwd(), options); + return; + } + ``` + +3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`): + ```ts + console.log(` ${BOLD}${RESET} `); + console.log(` Usage: [flags]`); + ``` + +4. **Verify both exist** — the recurring bug is doing step 1 but missing steps 2-3. + +## Wiring Patterns by Command Type + +| Type | Example | How to wire | +|------|---------|-------------| +| Standard command | `export.ts`, `build.ts` | `run*()` function, parse flags from `args` | +| Placeholder command | `loop`, `cast` (alias: `hire`) | Inline in cli-entry.ts, prints pending message | +| Utility/check module | `rc-tunnel.ts`, `copilot-bridge.ts` | Wire as diagnostic check (e.g., `isDevtunnelAvailable()`) | +| Subcommand of another | `init-remote.ts` | Already used inside parent + standalone alias | + +## Common Import Pattern + +```ts +import { BOLD, RESET, DIM, RED, GREEN, YELLOW } from './cli/core/output.js'; +``` + +Use dynamic `await import()` for command modules to keep startup fast (lazy loading). + +## History + +- **#237 / PR #244:** 4 commands wired (rc, copilot-bridge, init-remote, rc-tunnel). aspire, link, loop, cast (née hire) were already present. diff --git a/templates/skills/client-compatibility/SKILL.md b/templates/skills/client-compatibility/SKILL.md new file mode 100644 index 000000000..62e6b09ab --- /dev/null +++ b/templates/skills/client-compatibility/SKILL.md @@ -0,0 +1,89 @@ +--- +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: "...Runtime Engineer charter + task..." }) +runSubagent({ prompt: "...Quality Engineer 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/templates/skills/coordinator-init-mode/SKILL.md b/templates/skills/coordinator-init-mode/SKILL.md new file mode 100644 index 000000000..46585cd42 --- /dev/null +++ b/templates/skills/coordinator-init-mode/SKILL.md @@ -0,0 +1,99 @@ +--- +name: "coordinator-init-mode" +description: "The complete two-phase Init Mode protocol the Squad coordinator runs when no team exists yet in the current repo. Phase 1 = propose the team (no files created, wait for user confirm). Phase 2 = create .squad/ scaffolding, casting state, .gitattributes for merge drivers, and the always-on built-ins (Scribe, Ralph, Rai, Fact Checker). Loaded on demand when the coordinator detects no .squad/team.md exists." +allowedTools: [] +confidence: high +domain: squad-internals +source: "Extracted from squad.agent.md as part of the slimming effort (bradygaster/squad#1308). Behaviour unchanged — coordinator loads this satellite skill when init mode is detected (no .squad/team.md present)." +--- + +> **Load this skill when:** you detect that no `.squad/team.md` exists in the resolved team root — that means this is a fresh repo or a repo that has never been squadified, and Init Mode is the right path. The short stub in `squad.agent.md` tells you to load this skill; the full two-phase protocol lives here. +> +> **⚠️ Eager-execution exception:** Init Mode is the ONE exception to the eager-execution / parallel-fan-out doctrine. Phase 1 MUST end with a user confirmation before any file is created. Do not bypass. + +## Phase 1: Propose the Team + +No team exists yet. **Propose one — but DO NOT create any files until the user confirms.** + +1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey {user}, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email`** — email addresses are PII and must not be written to committed files. +2. Ask: *"What are you building? (language, stack, what it does)"* +3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see the canonical Casting reference at `.squad/templates/casting-reference.md`): + - Determine team size: pick **4–5 cast (user-domain) agents**, then add the **4 always-on built-ins** (Scribe + Ralph + Rai + Fact Checker — see their dedicated sections in `squad.agent.md`). A typical fresh squad has **8–9 total roster entries**, not 4–5. + - Determine assignment shape from the user's project description. + - Derive resonance signals from the session and repo context. + - Select a universe. Allocate character names from that universe. + - Scribe is always "Scribe" — exempt from casting. + - Ralph is always "Ralph" — exempt from casting. + - Rai is always "Rai" — exempt from casting. + - Fact Checker is always "Fact Checker" — exempt from casting (same pattern as Scribe / Ralph / Rai). +4. Propose the team with their cast names. Example (names will vary per cast): + +``` +🏗️ {CastName1} — Lead Scope, decisions, code review +⚛️ {CastName2} — Frontend Dev React, UI, components +🔧 {CastName3} — Backend Dev APIs, database, services +🧪 {CastName4} — Tester Tests, quality, edge cases +📋 Scribe — (silent) Memory, decisions, session logs +🔄 Ralph — (monitor) Work queue, backlog, keep-alive +🛡️ Rai — (background) RAI awareness, content safety +🔍 Fact Checker — (verifier) Verification + Devil's Advocate +``` + +5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu. + + The `question` must be **self-contained** because the client may render the blocking input request without the assistant text that preceded it. + + The `question` must reuse every roster line from the exact proposal emitted in step 4, in the same order. Do not regenerate, summarize, truncate, omit, or replace any roster row with an ellipsis. Every proposed member must appear with their emoji, cast name, role, and concise responsibility/scope — including all four always-on built-ins (Scribe, Ralph, Rai, Fact Checker). + + Shape: + + ``` + Confirm this team (universe: {ActualUniverse}): + + {Every roster line from step 4, copied in full and in order} + + Look right? + ``` + + Never use a bare "Look right?" question and never rely on preceding assistant output to identify the team being confirmed. + + - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]` + +**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.** + +--- + +## Phase 2: Create the Team + +**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes"). + +> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. **Do NOT enter Phase 2 until the user confirms.** + +6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: `team.md`, `routing.md`, `ceremonies.md`, `decisions.md`, `decisions/inbox/`, `casting/`, `agents/`, `orchestration-log/`, `skills/`, `log/`, `rai/`). + +**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id). + +**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing. Rai's charter is seeded from the `Rai-charter.md` template, and `.squad/rai/policy.md` is seeded from `rai-policy.md`. Fact Checker's charter is seeded from `fact-checker-charter.md` and `.squad/fact-checker/policy.md` is seeded from `fact-checker-policy.md`. + +**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks. + +**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches: + +``` +.squad/decisions.md merge=union +.squad/agents/*/history.md merge=union +.squad/log/** merge=union +.squad/orchestration-log/** merge=union +.squad/rai/audit-trail.md merge=union +``` + +The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically. + +7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"* + +8. **Post-setup input sources** (optional — ask after team is created, not during casting): + - **PRD/spec:** *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow. + - **GitHub issues:** *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow. + - **Human members:** *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section. + - **Copilot agent:** *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment. + - These are additive. **Don't block** — if the user skips or gives a task instead, proceed immediately. diff --git a/templates/skills/coordinator-response-mode/SKILL.md b/templates/skills/coordinator-response-mode/SKILL.md new file mode 100644 index 000000000..4dff3b800 --- /dev/null +++ b/templates/skills/coordinator-response-mode/SKILL.md @@ -0,0 +1,97 @@ +--- +name: "coordinator-response-mode" +description: "Selecting WHO handles work is the Routing table; selecting HOW they handle it (Direct, Lightweight, Standard, Full) is Response Mode. This skill contains the complete decision table, exemplar prompts for each mode, the Lightweight spawn template, and the upgrade rules. Squad coordinator loads this on demand once routing has identified the agent — to pick the right ceremony level for the task." +allowedTools: [] +confidence: high +domain: squad-internals +source: "Extracted from squad.agent.md as part of the slimming effort (bradygaster/squad#1308). Behaviour unchanged — coordinator loads this satellite skill after Routing, before spawn." +--- + +> **Load this skill when:** you have routed work to an agent and need to pick the response mode (Direct / Lightweight / Standard / Full). The 1-line stub in `squad.agent.md` is for awareness; this skill is the full decision table + templates. + +## Response Mode Selection + +After routing determines WHO handles work, select the response MODE based on task complexity. **Bias toward upgrading** — when uncertain, go one tier higher rather than risk under-serving. + +| Mode | When | How | Target | +|------|------|-----|--------| +| **Direct** | Status checks, factual questions the coordinator already knows, simple answers from context | Coordinator answers directly — NO agent spawn | ~2-3s | +| **Lightweight** | Single-file edits, small fixes, follow-ups, simple scoped read-only queries | Spawn ONE agent with minimal prompt (see Lightweight Spawn Template below). Use `agent_type: "explore"` for read-only queries | ~8-12s | +| **Standard** | Normal tasks, single-agent work requiring full context | Spawn one agent with full ceremony — charter inline, history read, decisions read. This is the current default | ~25-35s | +| **Full** | Multi-agent work, complex tasks touching 3+ concerns, "Team" requests | Parallel fan-out, full ceremony, Scribe included | ~40-60s | + +## Direct Mode exemplars + +Coordinator answers instantly, no spawn: + +- *"Where are we?"* → Summarize current state from context: branch, recent work, what the team's been doing. A user favorite — make it instant. +- *"How many tests do we have?"* → Run a quick command, answer directly. +- *"What branch are we on?"* → `git branch --show-current`, answer directly. +- *"Who's on the team?"* → Answer from `team.md` already in context. +- *"What did we decide about X?"* → Answer from `decisions.md` already in context. + +## Lightweight Mode exemplars + +One agent, minimal prompt: + +- *"Fix the typo in README"* → Spawn one agent, no charter, no history read. +- *"Add a comment to line 42"* → Small scoped edit, minimal context needed. +- *"What does this function do?"* → `agent_type: "explore"` (Haiku model, fast). +- Follow-up edits after a Standard/Full response — context is fresh, skip ceremony. + +## Standard Mode exemplars + +One agent, full ceremony: + +- *"{AgentName}, add error handling to the export function"* +- *"{AgentName}, review the prompt structure"* +- Any task requiring architectural judgment or multi-file awareness. + +## Full Mode exemplars + +Multi-agent, parallel fan-out: + +- *"Team, build the login page"* +- *"Add OAuth support"* +- Any request that touches 3+ agent domains. + +## Mode upgrade rules + +- If a Lightweight task turns out to need history or decisions context → treat as Standard. +- If uncertain between Direct and Lightweight → choose Lightweight. +- If uncertain between Lightweight and Standard → choose Standard. +- **Never downgrade mid-task.** If you started Standard, finish Standard. + +## Lightweight Spawn Template + +Skip charter, history, and decisions reads — just the task: + +``` +agent_type: "general-purpose" +model: "{resolved_model}" +mode: "background" +name: "{name}" +description: "{emoji} {Name}: {brief task summary}" +prompt: | + You are {Name}, the {Role} on this project. + TEAM ROOT: {team_root} + CURRENT_DATETIME: + WORKTREE_PATH: {worktree_path} + WORKTREE_MODE: {true|false} + **Requested by:** {current user name} + + {% if WORKTREE_MODE %} + **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches. + {% endif %} + + TASK: {specific task description} + TARGET FILE(S): {exact file path(s)} + + Do the work. Keep it focused. + If you made a meaningful decision, persist it with `memory.write` (class: `decision`) when available, or fall back to `squad_decide` / `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`. Do not run git notes, switch branches, or write mutable `.squad/` state by hand. + + ⚠️ OUTPUT: Report outcomes in human terms. Never expose tool internals or SQL. + ⚠️ 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}. CURRENT_DATETIME: — {question} TEAM ROOT: {team_root}"` diff --git a/templates/skills/coordinator-source-of-truth/SKILL.md b/templates/skills/coordinator-source-of-truth/SKILL.md new file mode 100644 index 000000000..3a992ba0a --- /dev/null +++ b/templates/skills/coordinator-source-of-truth/SKILL.md @@ -0,0 +1,45 @@ +--- +name: "coordinator-source-of-truth" +description: "The complete file-by-file source-of-truth hierarchy for Squad: which files are authoritative, which are derived/append-only, who may write each one, who may read each one, and the precedence rules when they conflict. Squad coordinator loads this on demand when it needs to resolve a write conflict, decide where a piece of state belongs, or answer a 'who owns this file' question." +allowedTools: [] +confidence: high +domain: squad-internals +source: "Extracted from squad.agent.md as part of the slimming effort (bradygaster/squad#1308). Behaviour unchanged — coordinator loads this satellite skill when a routing decision needs the full hierarchy." +--- + +> **Load this skill when:** the coordinator (or any agent) needs to resolve a "where does this state belong?" or "who is allowed to write this file?" question — e.g., when about to write `.squad/decisions.md`, when reviewing whether an agent broke the append-only rule, when answering a user question about Squad's file layout, or when adjudicating a conflict between two files. The short summary in `squad.agent.md` is for routing; this skill is the full reference. + +## State backend note + +Files below marked as **"Derived / append-only"** are **mutable state** — agents access them with runtime state tools (`squad_state_read`, `squad_state_write`, `squad_state_append`, `squad_state_delete`, `squad_state_list`). The runtime decides whether the configured backend stores them on disk, git-native state, or an external provider. Files marked as **"Authoritative"** are **static config** and always live on disk regardless of backend. + +## File hierarchy + +| File | Status | Who May Write | Who May Read | +|------|--------|---------------|--------------| +| `.github/agents/squad.agent.md` | **Authoritative governance.** All roles, handoffs, gates, and enforcement rules. | Repo maintainer (human) | Squad (Coordinator) | +| `.squad/decisions.md` | **Authoritative decision ledger.** Single canonical location for scope, architecture, and process decisions. | Squad (Coordinator) — append only | All agents | +| `.squad/team.md` | **Authoritative roster.** Current team composition. | Squad (Coordinator) | All agents | +| `.squad/routing.md` | **Authoritative routing.** Work assignment rules. | Squad (Coordinator) | Squad (Coordinator) | +| `.squad/ceremonies.md` | **Authoritative ceremony config.** Definitions, triggers, and participants for team ceremonies. | Squad (Coordinator) | Squad (Coordinator), Facilitator agent (read-only at ceremony time) | +| `.squad/casting/policy.json` | **Authoritative casting config.** Universe allowlist and capacity. | Squad (Coordinator) | Squad (Coordinator) | +| `.squad/casting/registry.json` | **Authoritative name registry.** Persistent agent-to-name mappings. | Squad (Coordinator) | Squad (Coordinator) | +| `.squad/casting/history.json` | **Derived / append-only.** Universe usage history and assignment snapshots. | Squad (Coordinator) — append only | Squad (Coordinator) | +| `.squad/agents/{name}/charter.md` | **Authoritative agent identity.** Per-agent role and boundaries. | Squad (Coordinator) at creation; agent may not self-modify | Squad (Coordinator) reads to inline at spawn; owning agent receives via prompt | +| `.squad/agents/{name}/history.md` | **Derived / append-only.** Personal learnings. Never authoritative for enforcement. | Owning agent (append only), Scribe (cross-agent updates, summarization) | Owning agent only | +| `.squad/agents/{name}/history-archive.md` | **Derived / append-only.** Archived history entries. Preserved for reference. | Scribe | Owning agent (read-only) | +| `.squad/orchestration-log/` | **Derived / append-only.** Agent routing evidence. Never edited after write. | Scribe | All agents (read-only) | +| `.squad/log/` | **Derived / append-only.** Session logs. Diagnostic archive. Never edited after write. | Scribe | All agents (read-only) | +| `.squad/templates/` | **Reference.** Format guides for runtime files. Not authoritative for enforcement. | Squad (Coordinator) at init | Squad (Coordinator) | +| `.squad/rai/policy.md` | **Authoritative RAI policy.** Check categories, terminology standards, and opt-out rules. | Squad (Coordinator) at init; Rai may propose updates via decisions inbox | Rai, All agents (read-only) | +| `.squad/rai/audit-trail.md` | **Derived / append-only.** RAI review evidence log. Redacted — never contains raw secrets or harmful content. | Rai (append only) | Rai, Squad (Coordinator) | +| `.squad/fact-checker/policy.md` | **Authoritative verification + Devil's Advocate policy.** Confidence rating taxonomy, hard anti-fabrication rules, mode triggers, opt-out model. | Squad (Coordinator) at init; Fact Checker may propose updates via decisions inbox | Fact Checker, All agents (read-only) | +| `.squad/fact-checker/audit-trail.md` | **Derived / append-only.** Verification verdicts + DA brief evidence log. Succinct — verdict + citation, never raw source material. | Fact Checker (append only) | Fact Checker, Squad (Coordinator) | +| `.squad/plugins/marketplaces.json` | **Authoritative plugin config.** Registered marketplace sources. | Squad CLI (`squad plugin marketplace`) | Squad (Coordinator) | + +## Rules + +1. **If `squad.agent.md` and any other file conflict, `squad.agent.md` wins.** It is the only file with hard governance authority. +2. **Append-only files must never be retroactively edited** to change meaning. They are diagnostic and audit-trail material. Corrections go in a new entry that references the prior one. +3. **Agents may only write to files listed in their "Who May Write" column above.** Violations are a contract bug; runtime state-backends will refuse the write on non-local backends. +4. **Non-coordinator agents may propose decisions** in their responses, but only Squad (Coordinator) records accepted decisions in `.squad/decisions.md`. diff --git a/templates/skills/cross-machine-coordination/SKILL.md b/templates/skills/cross-machine-coordination/SKILL.md new file mode 100644 index 000000000..d9242c44b --- /dev/null +++ b/templates/skills/cross-machine-coordination/SKILL.md @@ -0,0 +1,442 @@ +--- +name: "cross-machine-coordination" +description: "Enables squad agents on different machines to share work via git-based task queuing" +domain: "orchestration" +confidence: "medium" +source: "manual" +--- + +# Skill: Cross-Machine Coordination Pattern + +**Skill ID:** `cross-machine-coordination` +**Owner:** Ralph (Work Monitor) +**Squad Integration:** All agents +**Status:** Specification (ready for implementation) + +--- + +## Overview + +Enables squad agents running on different machines (laptop, DevBox, Azure VM) to securely share work, coordinate execution, and pass results without manual intervention. + +**Pattern:** Git-based task queuing + GitHub Issues supplement + +--- + +## Usage + +### For Task Sources (Orchestrating Machine) + +**To assign work to DevBox:** + +```bash +# Create task file +cat > .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-voice-clone.yaml << 'EOF' +id: gpu-voice-clone-001 +source_machine: laptop-machine +target_machine: devbox +priority: high +created_at: 2026-03-14T15:30:00Z +task_type: gpu_workload +payload: + command: "python scripts/voice-clone.py --input voice.wav --output cloned.wav" + expected_duration_min: 15 + resources: + gpu: true + memory_gb: 8 +status: pending +EOF + +# Commit & push +git add .squad/cross-machine/tasks/ +git commit -m "Cross-machine task: GPU voice cloning [squad:machine-devbox]" +git push origin main +``` + +Ralph on DevBox will: +1. Pull the task on next cycle (5-10 min) +2. Validate schema & command whitelist +3. Execute the GPU workload +4. Write result to `.squad/cross-machine/results/gpu-voice-clone-001.yaml` +5. Commit & push the result + +--- + +### For Task Executors (DevBox, Azure VMs) + +Ralph automatically watches `.squad/cross-machine/tasks/` for work targeted at this machine. + +**On each cycle (5-10 min):** + +```python +# Pseudo-code (Ralph implementation) +1. git pull origin main +2. Load all .yaml files in .squad/cross-machine/tasks/ +3. Filter for status=pending AND target_machine=HOSTNAME +4. For each task: + a. Validate schema (must have: id, source_machine, target_machine, payload) + b. Validate command against whitelist + c. Execute task (with timeout) + d. Write result to .squad/cross-machine/results/{id}.yaml + e. Commit & push result +``` + +--- + +### For Urgent/Ad-Hoc Tasks + +**Use GitHub Issues with `squad:machine-{name}` label:** + +```bash +# Create issue +gh issue create \ + --title "GPU: Clone voice profile from sample.wav" \ + --body "Execute voice cloning on DevBox. Input: /path/to/voice-input.wav" \ + --label "squad:machine-devbox" \ + --label "urgent" +``` + +Ralph on DevBox will: +1. Detect issue with `squad:machine-devbox` label +2. Parse task from issue body +3. Execute task +4. Comment with result +5. Close issue + +--- + +## File Formats + +### Task File (YAML) + +**Location:** `.squad/cross-machine/tasks/{timestamp}-{machine}-{task-id}.yaml` + +**Required Fields:** +```yaml +id: {task-id} # Unique identifier (alphanumeric + dash) +source_machine: {hostname} # Where task was created +target_machine: {hostname} # Where task will execute +priority: high|normal|low # Execution priority +created_at: 2026-03-14T15:30:00Z # ISO 8601 timestamp +task_type: gpu_workload|script|... # Category +payload: + command: "..." # Shell command to execute + expected_duration_min: 15 # Timeout (minutes) + resources: + gpu: true|false + memory_gb: 8 + cpu_cores: 4 +status: pending|executing|completed|failed +``` + +**Optional Fields:** +```yaml +description: "Human-readable task description" +timeout_override_min: 120 # Override default timeout +retry_count: 3 # Retry failed tasks +``` + +### Result File (YAML) + +**Location:** `.squad/cross-machine/results/{task-id}.yaml` + +```yaml +id: {task-id} # Links back to task +target_machine: devbox # Executed on +completed_at: 2026-03-14T15:45:00Z # When it finished +status: completed|failed|timeout # Outcome +exit_code: 0 # Shell exit code +stdout: "..." # Captured output +stderr: "..." # Captured errors +duration_seconds: 900 # How long it took +artifacts: + - path: "/path/to/artifacts/..." # Location of results + type: audio|text|model|... + size_mb: 2.5 +``` + +--- + +## Security Model + +### Validation Pipeline + +All tasks go through: + +1. **Schema Validation** + - YAML structure matches spec + - Required fields present + - No unexpected fields (reject) + +2. **Command Whitelist** + - Only approved commands allowed + - Path validation (no `../../` escapes) + - Environment variable sanitization + - No inline shell operators (`&&`, `|`, `>`) + +3. **Resource Limits** + - Timeout enforced (default: 60 min) + - Memory cap: 16GB (adjustable) + - CPU threads: 4 (adjustable) + - Disk write: 100GB (adjustable) + +4. **Execution Isolation** + - Runs as unprivileged user + - Temp directory cleaned after execution + - Network access: read-only (no outbound writes) + +5. **Audit Trail** + - All executions logged to git + - Commit signed with Ralph's key + - Result stored immutably + +### Threat Mitigations + +| Threat | Mitigation | +|--------|-----------| +| **Malicious task injection** | Branch protection + PR review before merge | +| **Credential leakage** | Pre-commit secret scan + environment scrubbing | +| **Resource exhaustion** | Timeout + memory limits | +| **Code injection** | Command whitelist + no shell evaluation | +| **Result tampering** | Git commit history is immutable | + +--- + +## Configuration + +Ralph reads config from `.squad/config.json`: + +```json +{ + "cross_machine": { + "enabled": true, + "poll_interval_seconds": 300, + "this_machine": "devbox", + "max_concurrent_tasks": 2, + "task_timeout_minutes": 60, + "command_whitelist": [ + "python scripts/voice-clone.py", + "python scripts/data-process.py", + "bash scripts/cleanup.sh" + ], + "result_ttl_days": 30 + } +} +``` + +--- + +## Examples + +### Example 1: GPU Voice Cloning (Laptop → DevBox) + +**1. Laptop creates task:** + +```yaml +# .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-001.yaml +id: gpu-voice-clone-001 +source_machine: laptop-machine +target_machine: devbox +priority: high +created_at: 2026-03-14T15:30:00Z +task_type: gpu_workload +payload: + command: "python scripts/voice-clone.py --input voice.wav --output cloned.wav" + expected_duration_min: 15 + resources: + gpu: true + memory_gb: 8 +status: pending +``` + +**2. Laptop commits & pushes:** + +```bash +git add .squad/cross-machine/tasks/ +git commit -m "Task: GPU voice cloning [squad:machine-devbox]" +git push origin main +``` + +**3. DevBox Ralph (5 min later):** + +``` +[Ralph Watch Cycle] +- Pulled origin/main +- Detected: gpu-voice-clone-001 (status: pending, target: devbox) +- Validation: ✅ Schema OK, command whitelisted +- Executing: python scripts/voice-clone.py ... +- [15 minutes of processing] +- Completed: exit code 0 +- Writing result... +- Committing & pushing... +``` + +**4. Laptop Ralph (next cycle) sees result:** + +```yaml +# .squad/cross-machine/results/gpu-voice-clone-001.yaml +id: gpu-voice-clone-001 +target_machine: devbox +completed_at: 2026-03-14T15:45:00Z +status: completed +exit_code: 0 +stdout: "Voice cloning completed. Output written to /tmp/cloned.wav" +stderr: "" +duration_seconds: 900 +artifacts: + - path: "/path/to/artifacts/voice-clone-001/output.wav" + type: audio + size_mb: 2.5 +``` + +--- + +### Example 2: Urgent Debug Request (Human → DevBox via Issue) + +**Create issue:** + +```bash +gh issue create \ + --title "DevBox: Debug voice model failure" \ + --body "Error: Model failed to load on last run. Please check /tmp/model.log and report findings." \ + --label "squad:machine-devbox" \ + --label "urgent" +``` + +**DevBox Ralph detects → executes → comments:** + +``` +✅ Executed on devbox at 2026-03-14 15:47:00 +Command: python scripts/debug-model.py + +Result: +------ +Model file: /tmp/model-v2.bin (OK) +Checksum: a1b2c3d4e5f6 (matches expected) +Memory available: 12 GB (sufficient) + +ERROR FOUND: Config file permission issue + - File: ~/.config/voice/model.yaml + - Permissions: -rw------- (owner-only) + - Expected: -rw-r--r-- (world-readable for service) + +FIX: Run: chmod 644 ~/.config/voice/model.yaml +``` + +--- + +## Error Handling + +### Task Execution Failures + +If a task fails (exit code != 0): + +1. Result written with `status: failed` + exit code +2. stderr captured in result +3. Committed to git for audit +4. Source machine can retry by re-pushing task with `status: pending` + +### Stalled Tasks + +If a task doesn't complete within timeout: + +1. Process killed +2. Result written with `status: timeout` +3. stderr: "Execution exceeded X minutes" +4. Source can investigate or retry + +### Network Failures + +If git push/pull fails: + +- Ralph retries on next cycle +- Tasks queue locally until connectivity restored +- No tasks lost (stored in local repo) + +--- + +## Monitoring & Debugging + +### Check Task Queue + +```bash +ls -la .squad/cross-machine/tasks/ +cat .squad/cross-machine/tasks/*.yaml | grep -E "^(id|status|target_machine):" +``` + +### Check Results + +```bash +ls -la .squad/cross-machine/results/ +cat .squad/cross-machine/results/{task-id}.yaml +``` + +### View Execution History + +```bash +git log --oneline .squad/cross-machine/ | head -20 +``` + +### Monitor Ralph Cycles + +```bash +tail -f .squad/log/ralph-watch.log | grep "cross-machine" +``` + +--- + +## Integration with Ralph Watch + +Ralph automatically includes this pattern in its watch loop: + +``` +Ralph Watch Cycle (every 5-10 min): +1. Fetch GitHub issues with squad:machine-* labels +2. Poll .squad/cross-machine/tasks/ +3. For each matching task: + - Validate + - Execute + - Write result + - Commit & push +4. Update status in issue (if applicable) +5. Sleep until next cycle +``` + +No manual Ralph configuration needed — just create task files or issues with the right labels. + +--- + +## Migration from Manual Handoff + +**Before (today):** +- Laptop → user manually copies file to Teams chat +- user pastes into target terminal +- user copies output back +- user pastes result manually + +**After (with this pattern):** +- Laptop Ralph writes task file → git push +- DevBox Ralph auto-executes → git push result +- Laptop Ralph auto-reads result +- 0 human intervention needed + +--- + +## Future Enhancements + +Potential expansions (Phase 2+): + +1. **Task Priorities:** Execution order based on priority field +2. **Serial Pipelines:** Machine A → B → C task chains +3. **GPU Availability Polling:** Query DevBox before submitting work +4. **Cost Tracking:** Log resource usage per task +5. **Notification Webhooks:** Alert on task completion +6. **Web Dashboard:** Real-time task status visualization + +--- + +## Questions? + +Refer to research report: `research/active/cross-machine-agents/README.md` + +Contact: the research and documentation owner or Ralph (Work Monitor) diff --git a/templates/skills/cross-squad-communication/SKILL.md b/templates/skills/cross-squad-communication/SKILL.md new file mode 100644 index 000000000..9286d5fa2 --- /dev/null +++ b/templates/skills/cross-squad-communication/SKILL.md @@ -0,0 +1,399 @@ +--- +name: "cross-squad-communication" +description: "Protocol for sending queries, delegating tasks, and sharing context between independent Squad instances across different repositories" +domain: "multi-repo coordination" +confidence: "medium" +source: "Ported from tamirdresher/squad-skills (plugins/cross-squad-communication). Companion to the registry-aware cross-squad skill — this one teaches the actual communication protocols once a peer is discovered. Pattern 0 (synchronous CLI) is the only end-to-end-validated pattern; Patterns 1, 2, 3 are documented from design but require live validation against your own setup before relying on them in production. See the Validation Status section at the bottom of this skill." +--- + +## Context + +When multiple repositories each have their own Squad (AI team), they need to exchange information: knowledge queries, PR reviews, task delegation, and dependency analysis. Each squad has its own agents, MCP tools, and issue tracker — there is no shared runtime. + +> **Companion skill — read first:** `cross-squad/SKILL.md` covers **discovery** of peer squads via `squad registry add/list/remove`. This skill picks up after a peer is known and covers the **communication protocols** themselves — the four numbered patterns below: Pattern 0 (synchronous CLI), Pattern 1 (read-only knowledge query), Pattern 2 (git-based async), and Pattern 3 (GitHub-issue-based delegation). A separate non-numbered appendix (Cross-Repo Dependency Scan) is provided as a related analysis tool, not a communication pattern. The two skills are designed to be used together. + +**When this skill applies:** +- A squad agent needs information from another squad-enabled repo +- A task needs to be delegated to another squad +- Cross-repo dependency analysis is needed +- PR review requests span repo boundaries + +**Key constraint:** Each squad has its own runtime, MCP tools, and issue tracker. Cross-squad communication can be **synchronous** (via CLI session targeting the other repo) or **asynchronous** (file-based or issue-based). The coordinator decides which approach fits. + +--- + +## Patterns + +### Decision Tree: Choosing the Right Pattern + +``` +Is the target repo cloned locally? +├─ NO → Use Pattern 3 (Issue-Based) or Pattern 2 (Git-Based Async) +└─ YES + ├─ Is this a quick query / knowledge lookup? + │ └─ YES → Use Pattern 0 (Synchronous CLI) — fastest + ├─ Does the work need to persist as artifacts? + │ └─ YES → Use Pattern 2 (Git-Based Async) + ├─ Is it a long-running analysis or multi-cycle task? + │ └─ YES → Use Pattern 2 (Git-Based Async) + └─ Is the target squad's Ralph running? + ├─ YES → Pattern 2 or 3 (async processing available) + └─ NO → Pattern 0 (Synchronous CLI) or Pattern 1 (Read-Only) +``` + +--- + +## Universal rule: every `copilot` spawn into a peer squad MUST pass `--agent squad` + +The `copilot` CLI accepts `--agent ` to select a custom agent (see `copilot --help`). Squad installs ship `.github/agents/squad.agent.md`, which is loaded **only when `--agent squad` is specified**. Without it the spawned session runs as a generic Copilot CLI session that does NOT load the peer's `team.md`, routing, MCP tools, casting, or coordinator behaviour — so you get an off-the-shelf model answering, not the peer's Squad. **Every command example in this skill that spawns `copilot` into a peer repo includes `--agent squad`; do not strip it.** + +This rule also applies anywhere else you spawn `copilot` into a Squad-initialised repo (not just cross-squad protocols) — e.g., `squad init`'s post-init tip and any automation that invokes the CLI on a squadified folder. The only case where you may omit `--agent` is when resuming an existing session (`copilot --resume `) — the resumed session preserves its original agent context. + +--- + +### Pattern 0: Synchronous CLI Session (Fastest for Interactive Queries) + +For quick knowledge queries, decision lookups, or short analyses — spawn a Copilot CLI session with the working directory set to the target squad's repo. This lets you send a prompt and get a response within the same session, using the target repo's full context. + +This is the same technique used by `ralph-watch.ps1`: write the prompt to a temp file, then invoke the CLI with that file as input. The key insight is that setting the working directory to the target repo gives the CLI session access to that squad's `.squad/` metadata, codebase, and conventions. + +**Protocol:** +1. Write prompt to a temp file (avoids argument-splitting issues, as learned in `ralph-watch.ps1`) +2. Read the file into a string and invoke `copilot -p ` with `-C ` set to the target repo (`-p` takes prompt text, NOT a file path) AND `--agent squad` so the spawned session uses the peer squad's coordinator (without `--agent` you get a generic Copilot CLI session that doesn't load the peer's `team.md`, MCP tools, or skills) +3. Receive response in the same session + +**Invocation:** +```powershell +# Spawn a Copilot CLI session targeting another squad's repo +$targetRepo = "C:\repos\platform-squad-repo" +$promptFile = New-TemporaryFile +@" +You are working in a Squad-enabled repository. +Read .squad/team.md and .squad/decisions.md first. + +[CROSS-SQUAD REQUEST] +From: research-squad +Request Type: knowledge_query +Query: What is the current architecture of the platform? What services does it expose? +Response Format: Brief structured summary +"@ | Out-File $promptFile -Encoding utf8 + +# Option A: copilot with prompt file (read file into string; -p takes text, not a path) +# --agent squad is REQUIRED: the target is another Squad install, so the spawned +# session must use that squad's coordinator (not a generic Copilot CLI session). +copilot -C $targetRepo --agent squad -p (Get-Content $promptFile -Raw) --allow-all-tools + +# Option B: Start-Process for non-blocking (ralph-watch.ps1 style) +Start-Process pwsh -ArgumentList "-NoProfile -Command `"copilot -C '$targetRepo' --agent squad -p (Get-Content '$promptFile' -Raw) --allow-all-tools`"" -Wait + +# Option C: Pipe directly (stdin is the prompt text) +"What is the platform architecture?" | copilot -C $targetRepo --agent squad --allow-all-tools +``` + +**When to use synchronous vs async:** + +| Scenario | Pattern | Why | +|----------|---------|-----| +| Quick knowledge query | Synchronous CLI (Pattern 0) | Fast answer, no overhead | +| "What did you decide about X?" | Synchronous CLI (Pattern 0) | Read decisions.md via the target squad's context | +| PR review request | Either (Pattern 0 or 2/3) | Sync for quick feedback, async for thorough review | +| Task delegation (do work in their repo) | Async (Pattern 2 or 3) | Work needs to persist beyond the session | +| Long-running analysis | Async (Pattern 2) | May take multiple cycles | +| Target repo not locally cloned | Async (Pattern 3) | Can't set working directory to a remote repo | + +**The coordinator decides which pattern to use based on:** +1. Is the target repo cloned locally? → If yes, sync CLI is available +2. Is this a quick query or a long task? → Quick = sync, long = async +3. Does the work need to persist? → If yes, use async (creates artifacts) +4. Is the target squad's Ralph running? → Needed for async processing + +**Requirements:** +- Target repo must be cloned locally (for `copilot -C `) +- Target repo must be Squad-initialised (`.squad/config.json` + `.github/agents/squad.agent.md` present), so `--agent squad` resolves to the peer's coordinator +- Prompt file avoids argument-splitting bugs (see `ralph-watch.ps1` lines 2166-2184) + +**Response quality:** ⭐⭐⭐⭐⭐ — the CLI session has full context of the target repo, including code, squad metadata, and MCP tools. + +### Liveness Protocol for Pattern 0 + +The synchronous CLI session requires monitoring to avoid false timeouts. With 7+ MCP servers initializing and `.squad/` metadata being read, startup can take 30-60 seconds. A hard timeout kills valid sessions before they complete. Instead, monitor the agency session's activity log directory. + +**Health Check Approach:** + +Instead of a fixed wall-clock timeout, monitor the agency session log directory for activity: + +```powershell +# The Copilot CLI creates a session log directory at ~/.copilot/logs/. +# Older `agency` runtimes wrote to ~/.agency/logs/; fall back to that +# location if the new path doesn't exist yet on the user's machine. +# e.g., ~/.copilot/logs/session_20260325_071211_57824 +$copilotLogs = "$env:USERPROFILE\.copilot\logs" +$agencyLogs = "$env:USERPROFILE\.agency\logs" +$logRoot = if (Test-Path $copilotLogs) { $copilotLogs } elseif (Test-Path $agencyLogs) { $agencyLogs } else { $null } +if ($logRoot) { + $logDir = Get-ChildItem $logRoot -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 1 +} +$lastSize = 0 +$stallCount = 0 + +while ($proc -and -not $proc.HasExited) { + Start-Sleep -Seconds 15 + $currentSize = (Get-ChildItem $logDir -Recurse -File | Measure-Object -Property Length -Sum).Sum + + if ($currentSize -eq $lastSize) { + $stallCount++ + if ($stallCount -ge 4) { # 60s with no progress + Write-Warning "Session stalled — no log activity for 60s" + break + } + } else { + $stallCount = 0 + $lastSize = $currentSize + } +} +``` + +**Progress Indicators (What Counts as "Alive"):** + +- New files appearing in the session log directory (e.g., `transcript.log`, `mcp-server-logs/`) +- Log file size increasing (indicates active processing) +- New or modified `.squad/` files in the target repo (e.g., `decisions/inbox.md`, `identity/history.md`) +- Process still running and consuming non-idle CPU time + +**Stall Detection (When to Intervene):** + +- **No log activity for 60s** → Issue a warning; session may be slow but not hung +- **No log activity for 120s** → Likely stuck; consider terminating and checking logs +- **Process exited with non-zero exit code** → Failed; examine `transcript.log` and `stderr` for errors +- **MCP server connection timeout** → Session blocked waiting for an MCP server response + +**Recovery Actions When Stalled:** + +1. **Check for user input waiting:** Inspect logs for prompts or dialogs (shouldn't happen with `--autopilot`) +2. **Check MCP server health:** Review `mcp-server-logs/` for connection errors or timeouts +3. **Retry with `--disable-builtin-mcps` flag:** For lightweight queries that don't require MCP tools + ```powershell + # Retry without MCP servers — faster startup, limited capability + copilot -C $targetRepo --agent squad -p (Get-Content $promptFile -Raw) --disable-builtin-mcps --allow-all-tools + ``` +4. **Increase timeout threshold:** If MCP server initialization is consistently slow (>90s), raise threshold before declaring stall + +--- + +### Pattern 1: Read-Only Knowledge Query (No CLI Needed) + +For questions about another squad's architecture, decisions, or current state — read their `.squad/` metadata directly. + +**Protocol:** +1. Read target repo's `.squad/team.md` → get stack, members, issue source +2. Read `.squad/decisions.md` → get architectural decisions +3. Read `.squad/routing.md` → understand who handles what +4. Read `.squad/identity/now.md` → get current focus +5. Scan code structure if needed (csproj files, directory layout) + +**Requirements:** +- Target repo must be cloned locally or accessible via git +- No authentication needed beyond git read access + +**Example:** +```powershell +# Query another squad's architecture +$targetRepo = "C:\repos\platform-squad-repo" +Get-Content "$targetRepo\.squad\team.md" +Get-Content "$targetRepo\.squad\decisions.md" +Get-Content "$targetRepo\.squad\identity\now.md" +``` + +**Response quality:** ⭐⭐⭐⭐ — excellent for structural/architectural questions. + +--- + +### Pattern 2: Async Task Request (Git-Based) + +For work that needs the target squad to execute (PR reviews, issue analysis, code changes). + +**Protocol:** +1. Create request file in YOUR repo: `.squad/cross-squad/requests/{timestamp}-{target}-{id}.yaml` +2. Commit and push +3. Target squad's Ralph detects on next cycle +4. Target squad processes and writes response to their `.squad/cross-squad/responses/` +5. Your Ralph picks up the response + +**Request File Format:** +```yaml +id: req-2026-06-13-001 +source_squad: research-squad +source_repo: your-org/research-squad-repo +target_squad: platform-squad +target_repo: your-org/platform-squad-repo +request_type: knowledge_query | pr_review | task_delegation | dependency_check +priority: high | normal | low +created_at: 2026-06-13T10:00:00Z +query: "What is the current architecture of the platform?" +routing_hint: "lead" # optional — which agent should handle this +status: pending +``` + +**Response File Format:** +```yaml +id: req-2026-06-13-001 +responding_squad: platform-squad +responding_agent: lead +responded_at: 2026-06-13T10:15:00Z +status: completed | partial | rejected +response: | + The platform architecture consists of... +artifacts: [] # optional file paths +``` + +--- + +### Pattern 3: Issue-Based Delegation (For GitHub-Hosted Repos) + +For repos on GitHub, use issues with labels as the message bus. + +**Protocol:** +1. Create issue in target repo with label `squad:cross-squad` +2. Include source squad identifier and routing hint in issue body +3. Target squad's Ralph picks up and routes to appropriate agent +4. Response posted as issue comment +5. Issue closed when complete + +**Example:** +```bash +gh issue create \ + --repo your-org/platform-squad-repo \ + --title "[Cross-Squad] Architecture query from research-squad" \ + --body "Source: research-squad\nQuery: What services does the platform expose?\nRouting: lead" \ + --label "squad:cross-squad" +``` + +**Limitation:** Only works for repos on GitHub. Other platforms (Azure DevOps, GitLab, etc.) need different approach. + +--- + +### Appendix: Cross-Repo Dependency Scan (Related Analysis Tool — Not a Communication Pattern) + +> This section is intentionally listed as an appendix rather than "Pattern 4" — it is a one-off analysis utility for discovering how two repos relate, not a protocol the coordinator picks from the decision tree above. The four numbered communication patterns are 0–3. + +For discovering how two repos relate to each other. + +**Protocol:** +1. Search both repos for mutual references: + ```powershell + Select-String -Path (Get-ChildItem $repoA -Recurse -Include "*.md","*.cs","*.json","*.csproj") ` + -Pattern $repoB_name + Select-String -Path (Get-ChildItem $repoB -Recurse -Include "*.md","*.cs","*.json","*.csproj") ` + -Pattern $repoA_name + ``` +2. Check shared NuGet packages / npm packages +3. Check shared ADO project or GitHub org +4. Document relationship type: code dependency, operational coupling, shared infra + +--- + +## Discovery Protocol + +Before sending any cross-squad request, verify the target: + +``` +1. Does .squad/team.md exist? → Squad is installed +2. What is the issue_source? → GitHub Issues | ADO | Planner +3. What agents are active? → Check member status column +4. What is the routing table? → Read routing.md +5. What is the current focus? → Read identity/now.md +6. Is Ralph running? → Check for recent commits by Ralph +``` + +If `.squad/team.md` doesn't exist, the repo is not squad-enabled. Fall back to standard human communication. + +--- + +## Platform Compatibility Matrix + +| Source Issue Tracker | Target Issue Tracker | Mechanism | +|---------------------|---------------------|-----------| +| GitHub Issues | GitHub Issues | Issue-based (Pattern 3) | +| GitHub Issues | ADO Work Items | Git-based (Pattern 2) | +| GitHub Issues | Planner | Git-based (Pattern 2) | +| ADO Work Items | GitHub Issues | Issue-based (Pattern 3) via `gh` CLI | +| ADO Work Items | ADO Work Items | ADO cross-project work items | +| Any | Any | Git-based (Pattern 2) — universal fallback | + +--- + +## Examples + +### Example 1: research-squad queries platform-squad architecture + +```powershell +# Step 1: Read metadata (Pattern 1) +$target = "C:\repos\platform-squad-repo" +$team = Get-Content "$target\.squad\team.md" -Raw +$decisions = Get-Content "$target\.squad\decisions.md" -Raw + +# Step 2: Extract answer from metadata +# team.md reveals tech stack and member roles +# decisions.md reveals architectural choices + +# Step 3: If deeper analysis needed, create async request (Pattern 2) +``` + +### Example 2: Request PR review from another squad + +```yaml +# .squad/cross-squad/requests/2026-06-13-platform-squad-pr-review.yaml +id: pr-review-001 +source_squad: research-squad +target_squad: platform-squad +request_type: pr_review +priority: normal +query: "Review PR #54 — package version fix. Check for correctness." +routing_hint: "lead" +status: pending +``` + +--- + +## Anti-Patterns + +### ⚠️ Know when synchronous CLI is NOT the right choice +```powershell +# WRONG — don't use sync CLI for long-running tasks that need artifacts +copilot -C $targetRepo --agent squad -p (Get-Content $promptFile -Raw) --allow-all-tools +# If the task creates files, PRs, or takes multiple cycles → use async (Pattern 2 or 3) + +# WRONG — don't use sync CLI when the target repo isn't cloned locally +copilot -C "C:\not\cloned\yet" --agent squad --allow-all-tools +# If the repo isn't available locally → use issue-based delegation (Pattern 3) +``` +Synchronous CLI sessions (Pattern 0) are valid for quick queries and knowledge lookups. Use async patterns for work that needs to persist or where the target repo isn't available locally. + +### ❌ Don't assume shared MCP tools +Each squad has its own MCP server instances. You cannot invoke another squad's ADO tools or GitHub tools from your session. + +### ❌ Don't skip the discovery step +Always read `team.md` first. The target squad may use a different issue tracker, have different agents, or be in a different state than expected. + +### ❌ Don't send requests to squads without Ralph +If the target squad doesn't have Ralph (Work Monitor) running, async requests will never be processed. Check for recent Ralph activity first. + +### ❌ Don't mix up repo platforms +Different repos may use GitHub Issues vs Azure DevOps Work Items vs Jira. Check `team.md` / repository metadata for the right tooling before sending requests. + +--- + +## Validation Status + +This skill was originally drafted against two prototype squad setups (a GitHub-hosted platform squad with ~10 agents and an Azure DevOps-hosted automation squad with ~4 agents). The protocols are platform-agnostic; the examples in this document use generic names so you can substitute your own repos. Patterns 0 and 1 have been exercised end-to-end in those prototypes; Patterns 2 and 3 are documented from design but have not been end-to-end-validated against a live target repo. + +| Scenario | Result | +|----------|--------| +| Knowledge query (read-only) | ✅ Works via Pattern 1 | +| Step handler discovery | ✅ Works via file scan | +| PR review (basic) | ⚠️ Partial — git log only, no API | +| Backlog enumeration | ⚠️ Partial — depends on issue platform | +| Dependency analysis | ✅ Works via cross-reference scan | +| CLI invocation (sync) + Liveness Protocol | ✅ Works — session launches successfully; log monitoring prevents false timeouts | + +**Confidence: MEDIUM** — Synchronous CLI pattern (Pattern 0) validated end-to-end. Liveness protocol provides operational robustness against slow MCP initialization. Git-based async (Pattern 2) and issue-based (Pattern 3) untested end-to-end. Production readiness requires Ralph integration on both sides. diff --git a/templates/skills/cross-squad/SKILL.md b/templates/skills/cross-squad/SKILL.md new file mode 100644 index 000000000..d008e85b8 --- /dev/null +++ b/templates/skills/cross-squad/SKILL.md @@ -0,0 +1,174 @@ +--- +name: "cross-squad" +description: "Coordinating work across multiple Squad instances — discovery, delegation, and disambiguation when the user says 'squad' (the product) vs casual English 'group of agents'." +domain: "orchestration" +confidence: "medium" +source: "manual" +triggers: + - "spawn N squads" + - "spawn a squad" + - "another squad" + - "two squads of" + - "second squad" + - "fan out to squads" + - "delegate to a squad" + - "set up squads for" + - "create a squad to review" + - "ask the other squad" +tools: + - name: "squad-discover" + description: "List known squads and their capabilities" + when: "When you need to find which squad can handle a task" + - name: "squad-delegate" + description: "Create work in another squad's repository" + when: "When a task belongs to another squad's domain" +--- + +## Context + +> **Read this FIRST any time the user says "squad" as a thing to spawn, delegate to, address, or fan out to** — e.g., *"spawn two squads of designers and devs"*, *"ask the other squad"*, *"delegate to a squad"*. In Squad-PRODUCT vocabulary, "squad" is a **peer** (an independent installation with its own `.squad/`, `team.md`, MCP server, and agents) — NOT a generic English synonym for "team" or "group". Do not fan out raw `task` agents inside your own coordinator context when the user means "another squad". Use the discovery and communication patterns below (and the companion `cross-squad-communication` skill for the actual protocols). + +When an organization runs multiple Squad instances (e.g., platform-squad, frontend-squad, data-squad), those squads need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across squads without creating tight coupling. + +> **Companion skill — for protocol details:** `cross-squad-communication/SKILL.md` covers the four communication patterns (synchronous CLI, read-only knowledge query, git-based async, and GitHub-issue-based delegation) once a peer squad is discovered via the registry below. This skill answers "who?" — the companion answers "how?". + +Cross-squad orchestration applies when: +- A task requires capabilities owned by another squad +- An architectural decision affects multiple squads +- A feature spans multiple repositories with different squads +- A squad needs to request infrastructure, tooling, or support from another squad + +## Disambiguation: "squad" vs ad-hoc agents + +When the user uses the word **"squad" / "squads"** or asks to **"spawn a team"**, the coordinator MUST treat it as a literal reference to a Squad install (a `.squad/` directory with its own roster, casting, and coordinator) — NOT as a casual synonym for "a group of sub-agents". + +### Default behaviour (apply unless explicitly told otherwise) + +| User says | Coordinator does | +|---|---| +| *"spawn two squads of X and Y"* / *"set up squads for X, Y, Z"* | Bootstrap N **real** Squad installs — separate folder + `git init` + `squad init` per squad — then use the cross-squad patterns below (`.squad/manifest.json`, `squad registry add`, `squad delegate`) and the protocols in the `cross-squad-communication` skill | +| *"ask the other squad about X"* / *"delegate to the data squad"* | Discover the peer via `squad registry list` (or by reading a known `.squad/manifest.json`), then use `cross-squad-communication` Pattern 0 / 1 / 2 / 3 — never re-implement the protocol with `task` | +| *"spawn a few agents to do X"* / *"have some agents review X"* / *"in parallel, get sub-agents to..."* | Ad-hoc `task` fan-out is fine — no `.squad/` bootstrap needed. This is the only path where raw `task` is appropriate when the user mentioned a multi-agent activity | + +### Ambiguous? `ask_user`, never silently downgrade + +If the request **could** be either interpretation AND bootstrapping real squads is non-trivial (more than one or two `squad init` runs), you MUST use the `ask_user` tool with a 2-choice prompt before proceeding: + +``` +question: "Should I create separate Squad installs or just dispatch ad-hoc agents?" +choices: + - "Real squads — separate .squad/ per squad (heavier, persistent, can be re-engaged later)" + - "Ad-hoc agents — one-shot `task` dispatch (lighter, ephemeral, no .squad/ created)" +``` + +The cost of asking is one `ask_user`. The cost of getting it wrong is the user has to redo the work. **Never silently pick the cheaper option just because it feels disproportionate for the task size — surface the trade-off and let the user pick.** + +### Anti-patterns (every one of these is a real failure mode observed in production) + +- **Calling `task` sub-agents "squad-alpha" / "squad-beta"** and treating them as squads. Naming something a squad doesn't make it one — a squad has its own `.squad/`, `team.md`, MCP server, and coordinator. If those aren't there, it's not a squad. +- **Matching a prior session's ad-hoc pattern without re-checking current intent.** If you see existing `reviews/squad-alpha/` folders from a previous run, that's a hint, NOT a contract — the user may have meant something different this time. Re-evaluate from scratch. +- **Silently choosing the cheaper interpretation because "bootstrapping two real squads for a 30-line app feels disproportionate".** That's a judgment call for the USER to make, not the coordinator. Use `ask_user`. +- **Loading the `cross-squad` skill, reading it, then doing `task` fan-out anyway** because the eager-execution / parallel-fan-out doctrine pulled you back. The disambiguation rule on this page OVERRIDES the generic fan-out doctrine when "squad" was the trigger. + +## Patterns + +### Discovery via Manifest +Each squad publishes a `.squad/manifest.json` declaring its name, capabilities, and contact information. Squads discover each other through two mechanisms: + +1. **`.squad/squad-registry.json`** — **discovery-only.** Peer squads are findable via `squad discover` and addressable via `squad delegate`, but their skills/decisions/wisdom are NOT loaded into your coordinator. Manage with `squad registry add/list/remove`. +2. **`.squad/upstream.json`** — **discovery + inheritance.** Squads listed here are also discoverable, AND your coordinator inherits their skills/decisions/wisdom/routing at session start. Manage with `squad upstream add/list/remove/sync`. + +Both forms read the peer's manifest via the same code path. The `path` field is the **repository root** (e.g. `../friend-repo`), and Squad appends `.squad/manifest.json` internally. Pointing at the `.squad/` directory works too — Squad accepts both forms (`readManifest` strips a trailing `.squad` if present). + +```json +{ + "name": "platform-squad", + "version": "1.0.0", + "description": "Platform infrastructure team", + "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"], + "contact": { + "repo": "org/platform", + "labels": ["squad:platform"] + }, + "accepts": ["issues", "prs"], + "skills": ["helm-developer", "operator-developer", "pipeline-engineer"] +} +``` + +### Context Sharing +When delegating work, share only what the target squad needs: +- **Capability list**: What this squad can do (from manifest) +- **Relevant decisions**: Only decisions that affect the target squad +- **Handoff context**: A concise description of why this work is being delegated + +Do NOT share: +- Internal team state (casting history, session logs) +- Full decision archives (send only relevant excerpts) +- Authentication credentials or secrets + +### Work Handoff Protocol +1. **Check manifest**: Verify the target squad accepts the work type (issues, PRs) +2. **Create issue**: Use `gh issue create` in the target repo with: + - Title: `[cross-squad] ` + - Label: `squad:cross-squad` (or the squad's configured label) + - Body: Context, acceptance criteria, and link back to originating issue +3. **Track**: Record the cross-squad issue URL in the originating squad's orchestration log +4. **Poll**: Periodically check if the delegated issue is closed/completed + +### Feedback Loop +Track delegated work completion: +- Poll target issue status via `gh issue view` +- Update originating issue with status changes +- Close the feedback loop when delegated work merges + +## Examples + +### Registering a peer squad (no inheritance) +```bash +# Friend's repo is checked out at ../friend-platform/ +squad registry add platform-squad ../friend-platform + +# Verify +squad registry list +squad discover +``` + +### Discovering squads +```bash +# List all squads discoverable from registry + upstreams +squad discover + +# Output: +# platform-squad → org/platform (kubernetes, helm, monitoring) +# frontend-squad → org/frontend (react, nextjs, storybook) +# data-squad → org/data (spark, airflow, dbt) +``` + +### Delegating work +```bash +# Delegate a task to the platform squad +squad delegate platform-squad "Add Prometheus metrics endpoint for the auth service" + +# Creates issue in org/platform with cross-squad label and context +``` + +### Manifest in squad.config.ts +```typescript +export default defineSquad({ + manifest: { + name: 'platform-squad', + capabilities: ['kubernetes', 'helm'], + contact: { repo: 'org/platform', labels: ['squad:platform'] }, + accepts: ['issues', 'prs'], + skills: ['helm-developer', 'operator-developer'], + }, +}); +``` + +## Anti-Patterns +- **Direct file writes across repos** — Never modify another squad's `.squad/` directory. Use issues and PRs as the communication protocol. +- **Tight coupling** — Don't depend on another squad's internal structure. Use the manifest as the public API contract. +- **Unbounded delegation** — Always include acceptance criteria and a timeout. Don't create open-ended requests. +- **Skipping discovery** — Don't hardcode squad locations. Use manifests and the discovery protocol. +- **Sharing secrets** — Never include credentials, tokens, or internal URLs in cross-squad issues. +- **Circular delegation** — Track delegation chains. If squad A delegates to B which delegates back to A, something is wrong. diff --git a/templates/skills/distributed-mesh/SKILL.md b/templates/skills/distributed-mesh/SKILL.md new file mode 100644 index 000000000..624db9626 --- /dev/null +++ b/templates/skills/distributed-mesh/SKILL.md @@ -0,0 +1,287 @@ +--- +name: "distributed-mesh" +description: "How to coordinate with squads on different machines using git as transport" +domain: "distributed-coordination" +confidence: "high" +source: "multi-model-consensus (Opus 4.6, Sonnet 4.5, GPT-5.4)" +--- + +## SCOPE + +**✅ THIS SKILL PRODUCES (exactly these, nothing more):** + +1. **`mesh.json`** — Generated from user answers about zones and squads (which squads participate, what zone each is in, paths/URLs for each), using `mesh.json.example` in this skill's directory as the schema template +2. **`sync-mesh.sh` and `sync-mesh.ps1`** — Copied from this skill's directory into the project root (these are bundled resources, NOT generated code) +3. **Zone 2 state repo initialization** (if applicable) — If the user specified a Zone 2 shared state repo, run `sync-mesh.sh --init` to scaffold the state repo structure +4. **A decision entry** in `.squad/decisions/inbox/` documenting the mesh configuration for team awareness + +**❌ THIS SKILL DOES NOT PRODUCE:** + +- **No application code** — No validators, libraries, or modules of any kind +- **No test files** — No test suites, test cases, or test scaffolding +- **No GENERATING sync scripts** — They are bundled with this skill as pre-built resources. COPY them, don't generate them. +- **No daemons or services** — No background processes, servers, or persistent runtimes +- **No modifications to existing squad files** beyond the decision entry (no changes to team.md, routing.md, agent charters, etc.) + +**Your role:** Configure the mesh topology and install the bundled sync scripts. Nothing more. + +## Context + +When squads are on different machines (developer laptops, CI runners, cloud VMs, partner orgs), the local file-reading convention still works — but remote files need to arrive on your disk first. This skill teaches the pattern for distributed squad communication. + +**When this applies:** +- Squads span multiple machines, VMs, or CI runners +- Squads span organizations or companies +- An agent needs context from a squad whose files aren't on the local filesystem + +**When this does NOT apply:** +- All squads are on the same machine (just read the files directly) + +## Patterns + +### The Core Principle + +> "The filesystem is the mesh, and git is how the mesh crosses machine boundaries." + +The agent interface never changes. Agents always read local files. The distributed layer's only job is to make remote files appear locally before the agent reads them. + +### Three Zones of Communication + +**Zone 1 — Local:** Same filesystem. Read files directly. Zero transport. + +**Zone 2 — Remote-Trusted:** Different host, same org, shared git auth. Transport: `git pull` from a shared repo. This collapses Zone 2 into Zone 1 — files materialize on disk, agent reads them normally. + +**Zone 3 — Remote-Opaque:** Different org, no shared auth. Transport: `curl` to fetch published contracts (SUMMARY.md). One-way visibility — you see only what they publish. + +### Agent Lifecycle (Distributed) + +``` +1. SYNC: git pull (Zone 2) + curl (Zone 3) — materialize remote state +2. READ: cat .mesh/**/state.md — all files are local now +3. WORK: do their assigned work (the agent's normal task, NOT mesh-building) +4. WRITE: update own billboard, log, drops +5. PUBLISH: git add + commit + push — share state with remote peers +``` + +Steps 2–4 are identical to local-only. Steps 1 and 5 are the entire distributed extension. **Note:** "WORK" means the agent performs its normal squad duties — it does NOT mean "build mesh infrastructure." + +### The mesh.json Config + +```json +{ + "squads": { + "auth-squad": { "zone": "local", "path": "../auth-squad/.mesh" }, + "ci-squad": { + "zone": "remote-trusted", + "source": "git@github.com:our-org/ci-squad.git", + "ref": "main", + "sync_to": ".mesh/remotes/ci-squad" + }, + "partner-fraud": { + "zone": "remote-opaque", + "source": "https://partner.dev/squad-contracts/fraud/SUMMARY.md", + "sync_to": ".mesh/remotes/partner-fraud", + "auth": "bearer" + } + } +} +``` + +Three zone types, one file. Local squads need only a path. Remote-trusted need a git URL. Remote-opaque need an HTTP URL. + +### Write Partitioning + +Each squad writes only to its own directory (`boards/{self}.md`, `squads/{self}/*`, `drops/{date}-{self}-*.md`). No two squads write to the same file. Git push/pull never conflicts. If push fails ("branch is behind"), the fix is always `git pull --rebase && git push`. + +### Trust Boundaries + +Trust maps to git permissions: +- **Same repo access** = full mesh visibility +- **Read-only access** = can observe, can't write +- **No access** = invisible (correct behavior) + +For selective visibility, use separate repos per audience (internal, partner, public). Git permissions ARE the trust negotiation. + +### Phased Rollout + +- **Phase 0:** Convention only — document zones, agree on mesh.json fields, manually run `git pull`/`git push`. Zero new code. +- **Phase 1:** Sync script (~30 lines bash or PowerShell) when manual sync gets tedious. +- **Phase 2:** Published contracts + curl fetch when a Zone 3 partner appears. +- **Phase 3:** Never. No MCP federation, A2A, service discovery, message queues. + +**Important:** Phases are NOT auto-advanced. These are project-level decisions — you start at Phase 0 (manual sync) and only move forward when the team decides complexity is justified. + +### Mesh State Repo + +The shared mesh state repo is a plain git repository — NOT a Squad project. It holds: +- One directory per participating squad +- Each directory contains at minimum a SUMMARY.md with the squad's current state +- A root README explaining what the repo is and who participates + +No `.squad/` folder, no agents, no automation. Write partitioning means each squad only pushes to its own directory. The repo is a rendezvous point, not an intelligent system. + +If you want a squad that *observes* mesh health, that's a separate Squad project that lists the state repo as a Zone 2 remote in its `mesh.json` — it does NOT live inside the state repo. + +## Examples + +### Developer Laptop + CI Squad (Zone 2) + +Auth-squad agent wakes up. `git pull` brings ci-squad's latest results. Agent reads: "3 test failures in auth module." Adjusts work. Pushes results when done. **Overhead: one `git pull`, one `git push`.** + +### Two Orgs Collaborating (Zone 3) + +Payment-squad fetches partner's published SUMMARY.md via curl. Reads: "Risk scoring v3 API deprecated April 15. New field `device_fingerprint` required." The consuming agent (in payment-squad's team) reads this information and uses it to inform its work — for example, updating payment integration code to include the new field. Partner can't see payment-squad's internals. + +### Same Org, Shared Mesh Repo (Zone 2) + +Three squads on different machines. One shared git repo holds the mesh. Each squad: `git pull` before work, `git push` after. Write partitioning ensures zero merge conflicts. + +## AGENT WORKFLOW (Deterministic Setup) + +When a user invokes this skill to set up a distributed mesh, follow these steps **exactly, in order:** + +### Step 1: ASK the user for mesh topology + +Ask these questions (adapt phrasing naturally, but get these answers): + +1. **Which squads are participating?** (List of squad names) +2. **For each squad, which zone is it in?** + - `local` — same filesystem (just need a path) + - `remote-trusted` — different machine, same org, shared git access (need git URL + ref) + - `remote-opaque` — different org, no shared auth (need HTTPS URL to published contract) +3. **For each squad, what's the connection info?** + - Local: relative or absolute path to their `.mesh/` directory + - Remote-trusted: git URL (SSH or HTTPS), ref (branch/tag), and where to sync it to locally + - Remote-opaque: HTTPS URL to their SUMMARY.md, where to sync it, and auth type (none/bearer) +4. **Where should the shared state live?** (For Zone 2 squads: git repo URL for the mesh state, or confirm each squad syncs independently) + +### Step 2: GENERATE `mesh.json` + +Using the answers from Step 1, create a `mesh.json` file at the project root. Use `mesh.json.example` from THIS skill's directory (`.squad/skills/distributed-mesh/mesh.json.example`) as the schema template. + +Structure: + +```json +{ + "squads": { + "": { "zone": "local", "path": "" }, + "": { + "zone": "remote-trusted", + "source": "", + "ref": "", + "sync_to": ".mesh/remotes/" + }, + "": { + "zone": "remote-opaque", + "source": "", + "sync_to": ".mesh/remotes/", + "auth": "" + } + } +} +``` + +Write this file to the project root. Do NOT write any other code. + +### Step 3: COPY sync scripts + +Copy the bundled sync scripts from THIS skill's directory into the project root: + +- **Source:** `.squad/skills/distributed-mesh/sync-mesh.sh` +- **Destination:** `sync-mesh.sh` (project root) + +- **Source:** `.squad/skills/distributed-mesh/sync-mesh.ps1` +- **Destination:** `sync-mesh.ps1` (project root) + +These are bundled resources. Do NOT generate them — COPY them directly. + +### Step 4: RUN `--init` (if Zone 2 state repo exists) + +If the user specified a Zone 2 shared state repo in Step 1, run the initialization: + +**On Unix/Linux/macOS:** +```bash +bash sync-mesh.sh --init +``` + +**On Windows:** +```powershell +.\sync-mesh.ps1 -Init +``` + +This scaffolds the state repo structure (squad directories, placeholder SUMMARY.md files, root README). + +**Skip this step if:** +- No Zone 2 squads are configured (local/opaque only) +- The state repo already exists and is initialized + +### Step 5: WRITE a decision entry + +Create a decision file at `.squad/decisions/inbox/-mesh-setup.md` with this content: + +```markdown +### : Mesh configuration + +**By:** (via distributed-mesh skill) + +**What:** Configured distributed mesh with squads across zones + +**Squads:** +- `` — Zone — +- `` — Zone — +- ... + +**State repo:** + +**Why:** +``` + +Write this file. The Scribe will merge it into the main decisions file later. + +### Step 6: STOP + +**You are done.** Do not: +- Generate sync scripts (they're bundled with this skill — COPY them) +- Write validator code +- Write test files +- Create any other modules, libraries, or application code +- Modify existing squad files (team.md, routing.md, charters) +- Auto-advance to Phase 2 or Phase 3 + +Output a simple completion message: + +``` +✅ Mesh configured. Created: +- mesh.json ( squads) +- sync-mesh.sh and sync-mesh.ps1 (copied from skill bundle) +- Decision entry: .squad/decisions/inbox/ + +Run `bash sync-mesh.sh` (or `.\sync-mesh.ps1` on Windows) before agents start to materialize remote state. +``` + +--- + +## Anti-Patterns + +**❌ Code generation anti-patterns:** +- Writing `mesh-config-validator.js` or any validator module +- Writing test files for mesh configuration +- Generating sync scripts instead of copying the bundled ones from this skill's directory +- Creating library modules or utilities +- Building any code that "runs the mesh" — the mesh is read by agents, not executed + +**❌ Architectural anti-patterns:** +- Building a federation protocol — Git push/pull IS federation +- Running a sync daemon or server — Agents are not persistent. Sync at startup, publish at shutdown +- Real-time notifications — Agents don't need real-time. They need "recent enough." `git pull` is recent enough +- Schema validation for markdown — The LLM reads markdown. If the format changes, it adapts +- Service discovery protocol — mesh.json is a file with 10 entries. Not a "discovery problem" +- Auth framework — Git SSH keys and HTTPS tokens. Not a framework. Already configured +- Message queues / event buses — Agents wake, read, work, write, sleep. Nobody's home to receive events +- Any component requiring a running process — That's the line. Don't cross it + +**❌ Scope creep anti-patterns:** +- Auto-advancing phases without user decision +- Modifying agent charters or routing rules +- Setting up CI/CD pipelines for mesh sync +- Creating dashboards or monitoring tools diff --git a/templates/skills/distributed-mesh/mesh.json.example b/templates/skills/distributed-mesh/mesh.json.example new file mode 100644 index 000000000..7f5730a88 --- /dev/null +++ b/templates/skills/distributed-mesh/mesh.json.example @@ -0,0 +1,30 @@ +{ + "squads": { + "auth-squad": { + "zone": "local", + "path": "../auth-squad/.mesh" + }, + "api-squad": { + "zone": "local", + "path": "../api-squad/.mesh" + }, + "ci-squad": { + "zone": "remote-trusted", + "source": "git@github.com:our-org/ci-squad.git", + "ref": "main", + "sync_to": ".mesh/remotes/ci-squad" + }, + "data-squad": { + "zone": "remote-trusted", + "source": "git@github.com:our-org/data-pipeline.git", + "ref": "main", + "sync_to": ".mesh/remotes/data-squad" + }, + "partner-fraud": { + "zone": "remote-opaque", + "source": "https://partner.example.com/squad-contracts/fraud/SUMMARY.md", + "sync_to": ".mesh/remotes/partner-fraud", + "auth": "bearer" + } + } +} diff --git a/templates/skills/distributed-mesh/sync-mesh.ps1 b/templates/skills/distributed-mesh/sync-mesh.ps1 new file mode 100644 index 000000000..5f409ef37 --- /dev/null +++ b/templates/skills/distributed-mesh/sync-mesh.ps1 @@ -0,0 +1,111 @@ +# sync-mesh.ps1 — Materialize remote squad state locally +# +# Reads mesh.json, fetches remote squads into local directories. +# Run before agent reads. No daemon. No service. ~40 lines. +# +# Usage: .\sync-mesh.ps1 [path-to-mesh.json] +# .\sync-mesh.ps1 -Init [path-to-mesh.json] +# Requires: git +param( + [switch]$Init, + [string]$MeshJson = "mesh.json" +) +$ErrorActionPreference = "Stop" + +# Handle -Init mode +if ($Init) { + if (-not (Test-Path $MeshJson)) { + Write-Host "❌ $MeshJson not found" + exit 1 + } + + Write-Host "🚀 Initializing mesh state repository..." + $config = Get-Content $MeshJson -Raw | ConvertFrom-Json + $squads = $config.squads.PSObject.Properties.Name + + # Create squad directories with placeholder SUMMARY.md + foreach ($squad in $squads) { + if (-not (Test-Path $squad)) { + New-Item -ItemType Directory -Path $squad | Out-Null + Write-Host " ✓ Created $squad/" + } else { + Write-Host " • $squad/ exists (skipped)" + } + + $summaryPath = "$squad/SUMMARY.md" + if (-not (Test-Path $summaryPath)) { + "# $squad`n`n_No state published yet._" | Set-Content $summaryPath + Write-Host " ✓ Created $summaryPath" + } else { + Write-Host " • $summaryPath exists (skipped)" + } + } + + # Generate root README.md + if (-not (Test-Path "README.md")) { + $readme = @" +# Squad Mesh State Repository + +This repository tracks published state from participating squads. + +## Participating Squads + +"@ + foreach ($squad in $squads) { + $zone = $config.squads.$squad.zone + $readme += "- **$squad** (Zone: $zone)`n" + } + $readme += @" + +Each squad directory contains a ``SUMMARY.md`` with their latest published state. +State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``. +"@ + $readme | Set-Content "README.md" + Write-Host " ✓ Created README.md" + } else { + Write-Host " • README.md exists (skipped)" + } + + Write-Host "" + Write-Host "✅ Mesh state repository initialized" + exit 0 +} + +$config = Get-Content $MeshJson -Raw | ConvertFrom-Json + +# Zone 2: Remote-trusted — git clone/pull +foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-trusted" }) { + $squad = $entry.Name + $source = $entry.Value.source + $ref = if ($entry.Value.ref) { $entry.Value.ref } else { "main" } + $target = $entry.Value.sync_to + + if (Test-Path "$target/.git") { + git -C $target pull --rebase --quiet 2>$null + if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: pull failed (using stale)" } + } else { + New-Item -ItemType Directory -Force -Path (Split-Path $target -Parent) | Out-Null + git clone --quiet --depth 1 --branch $ref $source $target 2>$null + if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: clone failed (unavailable)" } + } +} + +# Zone 3: Remote-opaque — fetch published contracts +foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-opaque" }) { + $squad = $entry.Name + $source = $entry.Value.source + $target = $entry.Value.sync_to + $auth = $entry.Value.auth + + New-Item -ItemType Directory -Force -Path $target | Out-Null + $params = @{ Uri = $source; OutFile = "$target/SUMMARY.md"; UseBasicParsing = $true } + if ($auth -eq "bearer") { + $tokenVar = ($squad.ToUpper() -replace '-', '_') + "_TOKEN" + $token = [Environment]::GetEnvironmentVariable($tokenVar) + if ($token) { $params.Headers = @{ Authorization = "Bearer $token" } } + } + try { Invoke-WebRequest @params -ErrorAction Stop } + catch { "# ${squad} — unavailable ($(Get-Date))" | Set-Content "$target/SUMMARY.md" } +} + +Write-Host "✓ Mesh sync complete" diff --git a/templates/skills/distributed-mesh/sync-mesh.sh b/templates/skills/distributed-mesh/sync-mesh.sh new file mode 100644 index 000000000..802fd2d8d --- /dev/null +++ b/templates/skills/distributed-mesh/sync-mesh.sh @@ -0,0 +1,104 @@ +#!/bin/bash +# sync-mesh.sh — Materialize remote squad state locally +# +# Reads mesh.json, fetches remote squads into local directories. +# Run before agent reads. No daemon. No service. ~40 lines. +# +# Usage: ./sync-mesh.sh [path-to-mesh.json] +# ./sync-mesh.sh --init [path-to-mesh.json] +# Requires: jq (https://github.com/jqlang/jq), git, curl + +set -euo pipefail + +# Handle --init mode +if [ "${1:-}" = "--init" ]; then + MESH_JSON="${2:-mesh.json}" + + if [ ! -f "$MESH_JSON" ]; then + echo "❌ $MESH_JSON not found" + exit 1 + fi + + echo "🚀 Initializing mesh state repository..." + squads=$(jq -r '.squads | keys[]' "$MESH_JSON") + + # Create squad directories with placeholder SUMMARY.md + for squad in $squads; do + if [ ! -d "$squad" ]; then + mkdir -p "$squad" + echo " ✓ Created $squad/" + else + echo " • $squad/ exists (skipped)" + fi + + if [ ! -f "$squad/SUMMARY.md" ]; then + echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md" + echo " ✓ Created $squad/SUMMARY.md" + else + echo " • $squad/SUMMARY.md exists (skipped)" + fi + done + + # Generate root README.md + if [ ! -f "README.md" ]; then + { + echo "# Squad Mesh State Repository" + echo "" + echo "This repository tracks published state from participating squads." + echo "" + echo "## Participating Squads" + echo "" + for squad in $squads; do + zone=$(jq -r ".squads.\"$squad\".zone" "$MESH_JSON") + echo "- **$squad** (Zone: $zone)" + done + echo "" + echo "Each squad directory contains a \`SUMMARY.md\` with their latest published state." + echo "State is synchronized using \`sync-mesh.sh\` or \`sync-mesh.ps1\`." + } > README.md + echo " ✓ Created README.md" + else + echo " • README.md exists (skipped)" + fi + + echo "" + echo "✅ Mesh state repository initialized" + exit 0 +fi + +MESH_JSON="${1:-mesh.json}" + +# Zone 2: Remote-trusted — git clone/pull +for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-trusted") | .key' "$MESH_JSON"); do + source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON") + ref=$(jq -r ".squads.\"$squad\".ref // \"main\"" "$MESH_JSON") + target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON") + + if [ -d "$target/.git" ]; then + git -C "$target" pull --rebase --quiet 2>/dev/null \ + || echo "⚠ $squad: pull failed (using stale)" + else + mkdir -p "$(dirname "$target")" + git clone --quiet --depth 1 --branch "$ref" "$source" "$target" 2>/dev/null \ + || echo "⚠ $squad: clone failed (unavailable)" + fi +done + +# Zone 3: Remote-opaque — fetch published contracts +for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-opaque") | .key' "$MESH_JSON"); do + source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON") + target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON") + auth=$(jq -r ".squads.\"$squad\".auth // \"\"" "$MESH_JSON") + + mkdir -p "$target" + auth_flag="" + if [ "$auth" = "bearer" ]; then + token_var="$(echo "${squad}" | tr '[:lower:]-' '[:upper:]_')_TOKEN" + [ -n "${!token_var:-}" ] && auth_flag="--header \"Authorization: Bearer ${!token_var}\"" + fi + + eval curl --silent --fail $auth_flag "$source" -o "$target/SUMMARY.md" 2>/dev/null \ + || echo "# ${squad} — unavailable ($(date))" > "$target/SUMMARY.md" +done + +echo "✓ Mesh sync complete" diff --git a/templates/skills/docs-standards/SKILL.md b/templates/skills/docs-standards/SKILL.md new file mode 100644 index 000000000..09039a014 --- /dev/null +++ b/templates/skills/docs-standards/SKILL.md @@ -0,0 +1,71 @@ +--- +name: "docs-standards" +description: "Microsoft Style Guide + Squad-specific documentation patterns" +domain: "documentation" +confidence: "high" +source: "earned (documentation reviews)" +--- + +## Context + +Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability. + +## Patterns + +### Microsoft Style Guide Rules +- **Sentence-case headings:** "Getting started" not "Getting Started" +- **Active voice:** "Run the command" not "The command should be run" +- **Second person:** "You can configure..." not "Users can configure..." +- **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 +- **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 +- **Cross-references at bottom:** Related pages linked after main content + +### Structure +- **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)** + +### Test Sync Rule +- **Always update test assertions:** When adding docs pages to `features/`, `scenarios/`, `guides/`, update corresponding `EXPECTED_*` arrays in `test/docs-build.test.ts` in the same commit + +## Examples + +✓ **Correct:** +```markdown +# Getting started with Squad + +> ⚠️ **Experimental:** This feature is in preview. + +Try this: +\`\`\`bash +squad init +\`\`\` + +Squad helps you build AI teams... + +--- + +## Install Squad + +Run the following command... +``` + +✗ **Incorrect:** +```markdown +# Getting Started With Squad // Title case + +Squad is a tool which will help users... // Third person, future tense + +You can install Squad with npm & configure it... // Ampersand in prose +``` + +## Anti-Patterns + +- Title-casing headings because "it looks nicer" +- Writing in passive voice or third person +- Long paragraphs of dense text (breaks scannability) +- Adding doc pages without updating test assertions +- Using ampersands outside code blocks diff --git a/templates/skills/e2e-template-testing/SKILL.md b/templates/skills/e2e-template-testing/SKILL.md index 0523fd340..316d20868 100644 --- a/templates/skills/e2e-template-testing/SKILL.md +++ b/templates/skills/e2e-template-testing/SKILL.md @@ -137,13 +137,13 @@ tool calls (including file writes) prompt for confirmation and block. ```powershell # PowerShell (Windows) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." ` +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." ` 2>&1 | Tee-Object evidence/session-task.log ``` ```bash # Bash (macOS/Linux) -copilot --agent squad --allow-all-tools -p "Picard, decide what testing framework to use. Write your decision." \ +copilot --agent squad --allow-all-tools -p "Lead, decide what testing framework to use. Write your decision." \ 2>&1 | tee evidence/session-task.log ``` diff --git a/templates/skills/economy-mode/SKILL.md b/templates/skills/economy-mode/SKILL.md new file mode 100644 index 000000000..646038978 --- /dev/null +++ b/templates/skills/economy-mode/SKILL.md @@ -0,0 +1,115 @@ +--- +name: "economy-mode" +description: "Shifts Layer 3 model selection to cost-optimized alternatives when economy mode is active." +domain: "model-selection" +confidence: "low" +source: "manual" +--- + +## SCOPE + +✅ THIS SKILL PRODUCES: +- A modified Layer 3 model selection table applied when economy mode is active +- `economyMode: true` written to `.squad/config.json` when activated persistently +- Spawn acknowledgments with `💰` indicator when economy mode is active + +❌ THIS SKILL DOES NOT PRODUCE: +- Code, tests, or documentation +- Cost reports or billing artifacts +- Changes to Layer 0, Layer 1, or Layer 2 resolution (user intent always wins) + +## Context + +Economy mode shifts Layer 3 (Task-Aware Auto-Selection) to lower-cost alternatives. It does NOT override persistent config (`defaultModel`, `agentModelOverrides`) or per-agent charter preferences — those represent explicit user intent and always take priority. + +Use this skill when the user wants to reduce costs across an entire session or permanently, without manually specifying models for each agent. + +## Activation Methods + +| Method | How | +|--------|-----| +| Session phrase | "use economy mode", "save costs", "go cheap", "reduce costs" | +| Persistent config | `"economyMode": true` in `.squad/config.json` | +| CLI flag | `squad --economy` | + +**Deactivation:** "turn off economy mode", "disable economy mode", or remove `economyMode` from `config.json`. + +## Economy Model Selection Table + +When economy mode is **active**, Layer 3 auto-selection uses this table instead of the normal defaults: + +| Task Output | Normal Mode | Economy Mode | +|-------------|-------------|--------------| +| Writing code (implementation, refactoring, bug fixes) | `gpt-5.6-terra` | `gpt-5.6-luna` | +| Writing prompts or agent designs | `gpt-5.6-terra` | `gpt-5.6-luna` | +| Docs, planning, triage, changelogs, mechanical ops | `gpt-5.6-luna` | `gpt-5.6-luna` | +| Visual/design work requiring image analysis | `gpt-5.6-sol` | `gpt-5.6-terra` | +| Architecture, code review, security audits | `gpt-5.6-sol` | `gpt-5.6-terra` | +| Scribe / logger / mechanical file ops | `gpt-5.6-luna` | `gpt-5.6-luna` | + +**Prefer `gpt-5.6-luna`** for all economy-mode tasks where cost is the priority. + +## AGENT WORKFLOW + +### On Session Start + +1. READ `.squad/config.json` +2. CHECK for `economyMode: true` — if present, activate economy mode for the session +3. STORE economy mode state in session context + +### On User Phrase Trigger + +**Session-only (no config change):** "use economy mode", "save costs", "go cheap" + +1. SET economy mode active for this session +2. ACKNOWLEDGE: `✅ Economy mode active — using cost-optimized models this session. (Layer 0 and Layer 2 preferences still apply)` + +**Persistent:** "always use economy mode", "save economy mode" + +1. WRITE `economyMode: true` to `.squad/config.json` (merge, don't overwrite other fields) +2. ACKNOWLEDGE: `✅ Economy mode saved — cost-optimized models will be used until disabled.` + +### On Every Agent Spawn (Economy Mode Active) + +1. CHECK Layer 0a/0b first (agentModelOverrides, defaultModel) — if set, use that. Economy mode does NOT override Layer 0. +2. CHECK Layer 1 (session directive for a specific model) — if set, use that. Economy mode does NOT override explicit session directives. +3. CHECK Layer 2 (charter preference) — if set, use that. Economy mode does NOT override charter preferences. +4. APPLY economy table at Layer 3 instead of normal table. +5. INCLUDE `💰` in spawn acknowledgment: `🔧 {Name} ({model} · 💰 economy) — {task}` + +### On Deactivation + +**Trigger phrases:** "turn off economy mode", "disable economy mode", "use normal models" + +1. REMOVE `economyMode` from `.squad/config.json` (if it was persisted) +2. CLEAR session economy mode state +3. ACKNOWLEDGE: `✅ Economy mode disabled — returning to standard model selection.` + +### STOP + +After updating economy mode state and including the `💰` indicator in spawn acknowledgments, this skill is done. Do NOT: +- Change Layer 0, Layer 1, or Layer 2 model choices +- Override charter-specified models +- Generate cost reports or comparisons +- Fall back to premium models via economy mode (economy mode never bumps UP) + +## Config Schema + +`.squad/config.json` economy-related fields: + +```json +{ + "version": 1, + "economyMode": true +} +``` + +- `economyMode` — when `true`, Layer 3 uses the economy table. Optional; absent = economy mode off. +- Combines with `defaultModel` and `agentModelOverrides` — Layer 0 always wins. + +## Anti-Patterns + +- **Don't override Layer 0 in economy mode.** If the user set `defaultModel: "claude-opus-4.6"`, they want quality. Economy mode only affects Layer 3 auto-selection. +- **Don't silently apply economy mode.** Always acknowledge when activated or deactivated. +- **Don't treat economy mode as permanent by default.** Session phrases activate session-only; only "always" or `config.json` persist it. +- **Don't bump premium tasks down too far.** Visual, architecture, and security work shifts from Sol to Terra in economy mode — it does NOT go to fast/cheap models. diff --git a/templates/skills/error-recovery/SKILL.md b/templates/skills/error-recovery/SKILL.md new file mode 100644 index 000000000..ebf38825c --- /dev/null +++ b/templates/skills/error-recovery/SKILL.md @@ -0,0 +1,99 @@ +--- +name: "error-recovery" +description: "Standard recovery patterns for all squad agents. When something fails, adapt — don't just report the failure." +domain: "reliability, agent-coordination" +confidence: "high" +license: MIT +--- + +# Error Recovery Patterns + +Standard recovery patterns for all squad agents. When something fails, **adapt** — don't just report the failure. + +--- + +## 1. Retry with Backoff + +**When:** Transient failures — API timeouts, rate limits, network errors, temporary service unavailability. + +**Pattern:** +1. Wait briefly, then retry (start at 2s, double each attempt) +2. Maximum 3 retries before escalating +3. Log each attempt with the error received + +**Example:** API call returns 429 Too Many Requests → wait 2s → retry → wait 4s → retry → wait 8s → retry → escalate if still failing. + +--- + +## 2. Fallback Alternatives + +**When:** Primary tool or approach fails and an alternative exists. + +**Pattern:** +1. Attempt primary approach +2. On failure, identify alternative tool/method +3. Try the alternative with the same intent +4. Document which alternative was used and why + +**Example:** Primary CLI tool fails → fall back to direct API call for the same operation. + +--- + +## 3. Diagnose-and-Fix + +**When:** Build failures, test failures, linting errors — structured errors with actionable output. + +**Pattern:** +1. Read the full error output carefully +2. Identify the root cause from error messages +3. Attempt a targeted fix +4. Re-run to verify the fix +5. Maximum 3 fix-retry cycles before escalating + +**Example:** Build fails with a type error → check for missing import → add it → rebuild. + +--- + +## 4. Escalate with Context + +**When:** Recovery attempts have been exhausted, or the failure requires human judgment. + +**Pattern:** +1. Summarize what was attempted and what failed +2. Include the exact error messages +3. State what you believe the root cause is +4. Suggest next steps or who might be able to help +5. Hand off to the coordinator or the appropriate specialist + +**Example:** After 3 failed build attempts → "Build fails on line 42 with null reference. Tried X, Y, Z. Likely a design issue in the Foo module. Recommend the code owner review." + +--- + +## 5. Graceful Degradation + +**When:** A non-critical step fails but the overall task can still deliver value. + +**Pattern:** +1. Determine if the failed step is critical to the task outcome +2. If non-critical, log the failure and continue +3. Deliver partial results with a clear note of what was skipped +4. Offer to retry the skipped step separately + +**Example:** Generating a report with 5 sections — section 3 data source is unavailable → produce the report with 4 sections, note that section 3 was skipped and why. + +--- + +## Applying These Patterns + +Each agent should reference these patterns in their charter's `## Error Recovery` section, tailored to their domain. The charter should list the agent's most common failure modes and map each to the appropriate pattern above. + +**Selection guide:** + +| Failure Type | Primary Pattern | Fallback Pattern | +|---|---|---| +| Network/API transient | Retry with Backoff | Escalate with Context | +| Tool/dependency missing | Fallback Alternatives | Escalate with Context | +| Build/test error | Diagnose-and-Fix | Escalate with Context | +| Auth/permissions | Retry with Backoff | Escalate with Context | +| Non-critical data missing | Graceful Degradation | — | +| Unknown/novel error | Escalate with Context | — | diff --git a/templates/skills/external-comms/SKILL.md b/templates/skills/external-comms/SKILL.md new file mode 100644 index 000000000..9745028f2 --- /dev/null +++ b/templates/skills/external-comms/SKILL.md @@ -0,0 +1,329 @@ +--- +name: "external-comms" +description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" +domain: "community, communication, workflow" +confidence: "low" +source: "manual (external communications workflow)" +tools: + - name: "github-mcp-server-list_issues" + description: "List open issues for scan candidates and lightweight triage" + when: "Use for recent open issue scans before thread-level review" + - name: "github-mcp-server-issue_read" + description: "Read the full issue, comments, and labels before drafting" + when: "Use after selecting a candidate so the communications owner has complete thread context" + - name: "github-mcp-server-search_issues" + description: "Search for candidate issues or prior squad responses" + when: "Use when filtering by keywords, labels, or duplicate response checks" + - name: "gh CLI" + description: "Fallback for GitHub issue comments and discussions workflows" + when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete" +--- + +## Context + +Phase 1 is **draft-only mode**. + +- The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. +- **Human review gate is mandatory** — the communications owner never posts autonomously. +- Every action is logged to `.squad/comms/audit/`. +- This workflow is triggered manually only ("check community") — no automated activation in Phase 1. + +## Patterns + +### 1. Scan + +Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions. + +- Include **open** issues and discussions only. +- Filter for items with **no squad team response**. +- Limit to items created in the last 7 days. +- Exclude items labeled `squad:internal` or `wontfix`. +- Include discussions **and** issues in the same sweep. +- Phase 1 scope is **issues and discussions only** — do not draft PR replies. + +### Discussion Handling (Phase 1) + +Discussions use the GitHub Discussions API, which differs from issues: + +- **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions +- **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) +- **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. +- **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. + +### 2. Classify + +Determine the response type before drafting. + +- Welcome (new contributor) +- Troubleshooting (bug/help) +- Feature guidance (feature request/how-to) +- Redirect (wrong repo/scope) +- Acknowledgment (confirmed, no fix) +- Closing (resolved) +- Technical uncertainty (unknown cause) +- Empathetic disagreement (pushback on a decision or design) +- Information request (need more reproduction details or context) + +### Template Selection Guide + +| Signal in Issue/Discussion | → Response Type | Template | +|---------------------------|-----------------|----------| +| New contributor (0 prior issues) | Welcome | T1 | +| Error message, stack trace, "doesn't work" | Troubleshooting | T2 | +| "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 | +| Wrong repo, out of scope for Squad | Redirect | T4 | +| Confirmed bug, no fix available yet | Acknowledgment | T5 | +| Fix shipped, PR merged that resolves issue | Closing | T6 | +| Unclear cause, needs investigation | Technical Uncertainty | T7 | +| Author disagrees with a decision or design | Empathetic Disagreement | T8 | +| Need more reproduction info or context | Information Request | T9 | + +Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary. + +### Confidence Classification + +| Confidence | Criteria | Example | +|-----------|----------|---------| +| 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" | +| 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) | +| 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" | + +**Auto-escalation rules:** +- Any mention of competitors → 🔴 +- Any mention of pricing/licensing → 🔴 +- Author has >3 follow-up comments without resolution → 🔴 +- Question references a closed-wontfix issue → 🔴 + +### 3. Draft + +Use the humanizer skill for every draft. + +- Complete **Thread-Read Verification** before writing. +- Read the **full thread**, including all comments, before writing. +- Select the matching template from the **Template Selection Guide** and record the template ID in the review notes. +- Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it. +- Validate the draft against the humanizer anti-patterns. +- Flag long threads (`>10` comments) with `⚠️`. + +### Thread-Read Verification + +Before drafting, the communications owner MUST verify complete thread coverage: + +1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. +2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. +3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}" +4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary +5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column + +### 4. Present + +Show drafts for review in this exact format: + +```text +📝 Community Response Drafts +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +Each full draft must begin with the thread summary line: +`Thread: {N} comments, last activity {date}, {summary of key points}` + +### 5. Human Action + +Wait for explicit human direction before anything is posted. + +- `comms approve 1 3` — approve drafts 1 and 3 +- `comms edit 2` — edit draft 2 +- `comms skip` — skip all +- `banana` — freeze all pending (safe word) + +### Rollback — Bad Post Recovery + +If a posted response turns out to be wrong, inappropriate, or needs correction: + +1. **Delete the comment:** + - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` + - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` +2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content +3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle +4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case + +**Safe word — `banana`:** +- Immediately freezes all pending drafts in the review queue +- No new scans or drafts until `comms resume` is issued +- Audit entry logged with halter identity and reason + +### 6. Post + +After approval: + +- Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. +- The communications owner helps by preparing the CLI command. +- Write the audit entry after the posting action. + +### 7. Audit + +Log every action. + +- Location: `.squad/comms/audit/{timestamp}.md` +- Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table +- Universal required fields: `timestamp`, `action` +- All other fields are conditional on the action type + +## Examples + +These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it. + +### Example scan command + +```bash +gh issue list --state open --json number,title,author,labels,comments --limit 20 +``` + +### Example review table + +```text +📝 Community Response Drafts +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." | +| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." | +| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +### Example audit entry (post action) + +```markdown +--- +timestamp: "2026-03-16T21:30:00Z" +action: "post" +item_number: 426 +draft_id: 1 +reviewer: "@bradygaster" +--- + +## Context (draft, approve, edit, skip, post, delete actions) +- Thread depth: 3 +- Response type: welcome +- Confidence: 🟢 +- Long thread flag: false + +## Draft Content (draft, edit, post actions) +Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install. + +Hey @newdev! Welcome to Squad 👋 Thanks for opening this. +We reproduced the issue in preview builds and we're checking the regression point now. +Let us know if you can share the command you ran right before the failure. + +## Post Result (post, delete actions) +https://github.com/bradygaster/squad/issues/426#issuecomment-123456 +``` + +### T1 — Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{specific acknowledgment or first answer} +Let us know if you have questions — happy to help! +``` + +### T2 — Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### T3 — Feature Guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### T4 — Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### T5 — Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### T6 — Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### T7 — Technical Uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +### T8 — Empathetic Disagreement + +```text +We hear you, {author}. That's a fair concern. + +The current design choice was driven by {reason}. We know it's not ideal for every use case. + +{what alternatives exist or what trade-off was made} + +If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here! +``` + +### T9 — Information Request + +```text +Thanks for reporting this, {author}! + +To help us dig into this, could you share: +- {specific ask 1} +- {specific ask 2} +- {specific ask 3, if applicable} + +That context will help us narrow down what's happening. Appreciate it! +``` + +## Anti-Patterns + +- ❌ Posting without human review (NEVER — this is the cardinal rule) +- ❌ Drafting without reading full thread (context is everything) +- ❌ Ignoring confidence flags (🔴 items need Lead or human review) +- ❌ Scanning closed issues (only open items) +- ❌ Responding to issues labeled `squad:internal` or `wontfix` +- ❌ Skipping audit logging (every action must be recorded) +- ❌ Drafting for issues where a squad member already responded (avoid duplicates) +- ❌ Drafting pull request responses in Phase 1 (issues/discussions only) +- ❌ Treating templates like loose examples instead of reusable drafting assets +- ❌ Asking for more info without specific requests diff --git a/templates/skills/fact-checking/SKILL.md b/templates/skills/fact-checking/SKILL.md new file mode 100644 index 000000000..f7f7873e5 --- /dev/null +++ b/templates/skills/fact-checking/SKILL.md @@ -0,0 +1,61 @@ +--- +name: fact-checking +description: Review and validate claims using counter-hypothesis testing. Use when verifying technical content, checking references, validating API endpoints, or performing quality assurance on deliverables. +license: MIT +compatibility: Requires access to external references and APIs +metadata: + author: squad + version: "1.0.0" + domain: quality, verification + confidence: low + last_validated: "2026-03-01" +--- + +# Skill: Fact Checking + +## Context +Codifies the challenger agent review output format and methodology so any agent performing fact-checking or review produces consistent, structured output. + +## Pattern + +### Review Methodology + +For every claim or deliverable under review: +1. Ask: "What evidence supports this? What would disprove it?" +2. Generate counter-hypotheses and test them against available data +3. Verify URLs, package names, API endpoints, and external references actually exist +4. Flag confidence levels: ✅ Verified, ⚠️ Unverified, ❌ Contradicted + +### Review Output Format + +When reviewing another agent's work, use this template: + +``` +### Fact Check — {deliverable name} +**Claims verified:** {count} +**Issues found:** {count} + +| # | Claim | Status | Evidence/Notes | +|---|-------|--------|---------------| +| 1 | {claim} | ✅/⚠️/❌ | {supporting or contradicting evidence} | + +**Counter-hypotheses tested:** +- {alternative explanation + result} + +**Verdict:** {PASS / PASS WITH NOTES / NEEDS REVISION} +``` + +### Confidence Levels + +- ✅ **Verified** — evidence confirms the claim +- ⚠️ **Unverified** — cannot confirm or deny; suggest verification method +- ❌ **Contradicted** — evidence disproves the claim + +### Ceremony Integration + +Auto-trigger this skill before any architecture decision, or when an agent claim contains superlatives or percentage thresholds (e.g., "saves 75%", "always", "never"). The coordinator spawns the challenger agent with: + +``` +Challenger — fact-check {agent}'s claim: "{claim}" +Cite evidence for every verdict. Max 3 investigation cycles. +``` \ No newline at end of file diff --git a/templates/skills/gh-auth-isolation/SKILL.md b/templates/skills/gh-auth-isolation/SKILL.md new file mode 100644 index 000000000..e4ac1abda --- /dev/null +++ b/templates/skills/gh-auth-isolation/SKILL.md @@ -0,0 +1,183 @@ +--- +name: "gh-auth-isolation" +description: "Safely manage multiple GitHub identities (EMU + personal) in agent workflows" +domain: "security, github-integration, authentication, multi-account" +confidence: "high" +source: "earned (production usage across 50+ sessions with EMU corp + personal GitHub accounts)" +tools: + - name: "gh" + description: "GitHub CLI for authenticated operations" + when: "When accessing GitHub resources requiring authentication" +--- + +## Context + +Many developers use GitHub through an Enterprise Managed User (EMU) account at work while maintaining a personal GitHub account for open-source contributions. AI agents spawned by Squad inherit the shell's default `gh` authentication — which is usually the EMU account. This causes failures when agents try to push to personal repos, create PRs on forks, or interact with resources outside the enterprise org. + +This skill teaches agents how to detect the active identity, switch contexts safely, and avoid mixing credentials across operations. + +## Patterns + +### Detect Current Identity + +Before any GitHub operation, check which account is active: + +```bash +gh auth status +``` + +Look for: +- `Logged in to github.com as USERNAME` — the active account +- `Token scopes: ...` — what permissions are available +- Multiple accounts will show separate entries + +### Extract a Specific Account's Token + +When you need to operate as a specific user (not the default): + +```bash +# Get the personal account token (by username) +gh auth token --user personaluser + +# Get the EMU account token +gh auth token --user corpalias_enterprise +``` + +**Use case:** Push to a personal fork while the default `gh` auth is the EMU account. + +### Push to Personal Repos from EMU Shell + +The most common scenario: your shell defaults to the EMU account, but you need to push to a personal GitHub repo. + +```bash +# 1. Extract the personal token +$token = gh auth token --user personaluser + +# 2. Push using token-authenticated HTTPS +git push https://personaluser:$token@github.com/personaluser/repo.git branch-name +``` + +**Why this works:** `gh auth token --user` reads from `gh`'s credential store without switching the active account. The token is used inline for a single operation and never persisted. + +### Create PRs on Personal Forks + +When the default `gh` context is EMU but you need to create a PR from a personal fork: + +```bash +# Option 1: Use --repo flag (works if token has access) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." --body "..." + +# Option 2: Temporarily set GH_TOKEN for one command +$env:GH_TOKEN = $(gh auth token --user personaluser) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." +Remove-Item Env:\GH_TOKEN +``` + +### Config Directory Isolation (Advanced) + +For complete isolation between accounts, use separate `gh` config directories: + +```bash +# Personal account operations +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login # Login with personal account (one-time setup) +gh repo clone personaluser/repo + +# EMU account operations (default) +Remove-Item Env:\GH_CONFIG_DIR +gh auth status # Back to EMU account +``` + +**Setup (one-time):** +```bash +# Create isolated config for personal account +mkdir ~/.config/gh-public +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login --web --git-protocol https +``` + +### Shell Aliases for Quick Switching + +Add to your shell profile for convenience: + +```powershell +# PowerShell profile +function ghp { $env:GH_CONFIG_DIR = "$HOME/.config/gh-public"; gh @args; Remove-Item Env:\GH_CONFIG_DIR } +function ghe { gh @args } # Default EMU + +# Usage: +# ghp repo clone personaluser/repo # Uses personal account +# ghe issue list # Uses EMU account +``` + +```bash +# Bash/Zsh profile +alias ghp='GH_CONFIG_DIR=~/.config/gh-public gh' +alias ghe='gh' + +# Usage: +# ghp repo clone personaluser/repo +# ghe issue list +``` + +## Examples + +### ✓ Correct: Agent pushes blog post to personal GitHub Pages + +```powershell +# Agent needs to push to personaluser.github.io (personal repo) +# Default gh auth is corpalias_enterprise (EMU) + +$token = gh auth token --user personaluser +git remote set-url origin https://personaluser:$token@github.com/personaluser/personaluser.github.io.git +git push origin main + +# Clean up — don't leave token in remote URL +git remote set-url origin https://github.com/personaluser/personaluser.github.io.git +``` + +### ✓ Correct: Agent creates a PR from personal fork to upstream + +```powershell +# Fork: personaluser/squad, Upstream: bradygaster/squad +# Agent is on branch contrib/fix-docs in the fork clone + +git push origin contrib/fix-docs # Pushes to fork (may need token auth) + +# Create PR targeting upstream +gh pr create --repo bradygaster/squad --head personaluser:contrib/fix-docs ` + --title "docs: fix installation guide" ` + --body "Fixes #123" +``` + +### ✗ Incorrect: Blindly pushing with wrong account + +```bash +# BAD: Agent assumes default gh auth works for personal repos +git push origin main +# ERROR: Permission denied — EMU account has no access to personal repo + +# BAD: Hardcoding tokens in scripts +git push https://personaluser:ghp_xxxxxxxxxxxx@github.com/personaluser/repo.git main +# SECURITY RISK: Token exposed in command history and process list +``` + +### ✓ Correct: Check before you push + +```bash +# Always verify which account has access before operations +gh auth status +# If wrong account, use token extraction: +$token = gh auth token --user personaluser +git push https://personaluser:$token@github.com/personaluser/repo.git main +``` + +## Anti-Patterns + +- ❌ **Hardcoding tokens** in scripts, environment variables, or committed files. Use `gh auth token --user` to extract at runtime. +- ❌ **Assuming the default `gh` auth works** for all repos. EMU accounts can't access personal repos and vice versa. +- ❌ **Switching `gh auth login`** globally mid-session. This changes the default for ALL processes and can break parallel agents. +- ❌ **Storing personal tokens in `.env`** or `.squad/` files. These get committed by Scribe. Use `gh`'s credential store. +- ❌ **Ignoring token cleanup** after inline HTTPS pushes. Always reset the remote URL to avoid persisting tokens. +- ❌ **Using `gh auth switch`** in multi-agent sessions. One agent switching affects all others sharing the shell. +- ❌ **Mixing EMU and personal operations** in the same git clone. Use separate clones or explicit remote URLs per operation. diff --git a/templates/skills/gh-aw-enlistment/SKILL.md b/templates/skills/gh-aw-enlistment/SKILL.md new file mode 100644 index 000000000..7f1f0d4ba --- /dev/null +++ b/templates/skills/gh-aw-enlistment/SKILL.md @@ -0,0 +1,347 @@ +--- +name: "gh-aw-enlistment" +description: "Enlist a repository into Squad by installing the supported GitHub Agentic Workflows (gh-aw) bootstrap — with strict compilation, an explicit safe-update allowlist, and a human-reviewed bootstrap PR. Never auto-merges." +domain: "github-integration, agentic-workflows, ci-bootstrap, safety-gated-automation" +confidence: "high" +source: "Operationalized from the authoritative Squad gh-aw guide (docs/src/content/docs/guide/gh-aw.md) covering the supported install → compile → validate → bootstrap-PR path." +triggers: [set up Squad agentic workflows, enlist this repo in Squad, enlist my repository in Squad, install Squad gh-aw workflows, install Squad agentic workflows, add Squad gh aw workflows, bootstrap Squad in this repo, onboard this repo to Squad, set up /squad slash commands, gh aw add squad] +tools: + - name: "gh" + description: "GitHub CLI — repo identity, Actions permissions, PR creation, review request, and check watching." + when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR." + - name: "gh aw" + description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set." + when: "Installing the six @dev workflows and compiling them into deterministic .lock.yml files." +--- + +## Context + +Use this skill when a user wants to **enlist a repository into Squad** through +**GitHub Agentic Workflows (`gh aw`)** — e.g. "set up Squad agentic workflows", +"enlist this repo in Squad", or "install Squad gh-aw workflows". The end state is +the `/squad` slash command being live on the repo, delivered as a **human-reviewed +bootstrap pull request** — never an auto-merge. + +This skill **operationalizes** the supported bootstrap path. It does not summarize +it: each step below is a gate with explicit success evidence and **STOP conditions**. +The authoritative source is `docs/src/content/docs/guide/gh-aw.md` (mirrored at +`https://bradygaster.github.io/squad/docs/guide/gh-aw/`). If that guide and this +skill ever disagree, the guide wins — re-read it before proceeding. + +**Portability contract:** resolve every repository identifier (owner, repo, default +branch) **at runtime**. Never hardcode a placeholder like `{owner}/{repo}`. The only +fixed identifier is the Squad source itself — `bradygaster/squad/workflows/...@dev` — +because that is where the workflows are published. + +**Idempotency contract:** the bootstrap is re-runnable. Never clobber existing +workflows, prefer detecting prior state over duplicating it, and **stop clearly** on +any unsafe or ambiguous condition rather than guessing. + +## Patterns + +Run these steps in order. Treat every "STOP" as a hard halt: report the exact +condition and wait for a human decision — do not work around it. + +### 0. Preflight — verify before you touch anything + +```bash +# gh is authenticated +gh auth status + +# Capture repository identity and default branch AT RUNTIME +owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')" +default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')" +echo "Repo: ${owner_repo} Default branch: ${default_branch}" + +# The gh-aw extension must be installed (install once if missing) +gh extension list | grep -q 'github/gh-aw' || gh extension install github/gh-aw + +# Git state must be understood and clean enough to isolate the install +git status --short +``` + +> **Portability — extension check:** the `grep -q` above is bash/Git Bash. On Windows +> PowerShell use: +> `if (-not (gh extension list | Select-String -Quiet 'github/gh-aw')) { gh extension install github/gh-aw }` + +- **STOP** if `gh auth status` is not logged in, or is logged in as the wrong + identity for this repo (see the `gh-auth-isolation` skill to operate as a + specific account without switching the global default). +- **STOP** if `owner_repo` or `default_branch` cannot be resolved. +- **STOP** if the working tree has unrelated uncommitted changes you cannot + account for — the bootstrap must land as an isolated, reviewable change. +- Confirm Copilot is enabled for the repository where checkable; the activation + run and the requested `@copilot` review both depend on it. + +### 1. Allow Actions-created PRs while keeping the default token read-only + +Squad opens PRs through GitHub Actions. Enable that **without** widening the +default workflow token: + +```bash +gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \ + -f default_workflow_permissions=read \ + -F can_approve_pull_request_reviews=true +``` + +Without this, Squad still pushes the generated branch but falls back to an issue +with a manual PR link — and a self-authored PR cannot be self-approved. Keep +`default_workflow_permissions=read`; do not set it to `write`. + +### 2. Isolate the install on a bootstrap branch (preserve existing workflows) + +```bash +git switch -c chore/squad-gh-aw-bootstrap +``` + +- If the branch already exists (a re-run), switch to it instead of recreating it. +- **Never overwrite** an existing `.github/workflows/*.md` or `*.lock.yml` that is + not part of the Squad set. `gh aw add` is additive; if you see it about to + replace an unrelated workflow, **STOP**. + +### 3. Install the six supported workflows — in order, dispatcher first + +```bash +gh aw add \ + bradygaster/squad/workflows/squad.md@dev \ + bradygaster/squad/workflows/squad-implement-worker.md@dev \ + bradygaster/squad/workflows/squad-review.md@dev \ + bradygaster/squad/workflows/squad-deps-worker.md@dev \ + bradygaster/squad/workflows/squad-retro.md@dev \ + bradygaster/squad/workflows/squad-improvement-worker.md@dev +``` + +Keep `squad.md` first: `gh aw add` discovers its worker/reviewer dependencies +while compiling it, and the explicit entries confirm the full surface without +creating duplicates. The installed top-level set is exactly: + +- `squad.md` + `squad.lock.yml` +- `squad-implement-worker.md` + `squad-implement-worker.lock.yml` +- `squad-review.md` + `squad-review.lock.yml` +- `squad-deps-worker.md` + `squad-deps-worker.lock.yml` +- `squad-retro.md` + `squad-retro.lock.yml` +- `squad-improvement-worker.md` + `squad-improvement-worker.lock.yml` + +`squad-improvement-worker` is part of the standard, coherent install above — +not a separate opt-in add-on. It stays dormant until a maintainer approves a +governance-scoped retrospective proposal (see the gh-aw guide's retrospective +auto-implementation section); installing it alongside the other five keeps the +full stack consistent and avoids a second bootstrap pass later. + +Report/proposal-only is the default. Ordinary fixes require the explicit +`"squadRetroAutoImplement": "allow"` setting in `.squad/config.json`; +five action issues and three dispatches per wakeup remain separate caps. +An improvement requires `/squad approve-improvement`, `Approved-Revision:` +and exact `Approved-Path:` lines from a human with write/maintain/admin access. +The dispatcher sends nested issue and approval-comment IDs to the worker; +manual retries use those same IDs. `/squad revoke-improvement` is reserved +without dispatch and is rechecked before outputs. Draft PRs and human merge +remain mandatory; closed-unmerged PRs never cause automatic replacements. +See the guide for content-hash calculation and the one-retry recovery policy. + +`@dev` is intentional — it tracks the branch where new modes and fixes land first. + +### 4. Review the first-install safe-update report — approve ONLY the documented entries + +On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: + + +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Action: **`bradygaster/squad/.github/actions/squad-init`** + + +> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets +> the workflows *reference* so you can approve that surface — it is not asking you +> to supply them. Both secrets are optional, they need not exist, and neither is +> required to enlist a repository. Single-repo activation runs on the built-in +> `github.token`. Configure them only for cross-repo access or elevated +> permissions. Auth precedence: GitHub App token, then the PAT, then +> `github.token`. Never block an enlistment waiting for a credential. + +If — and only if — the report contains exactly those documented entries, complete +the one-time approval: + +```bash +gh aw compile --strict --approve # first install only, when the safe-update warning appears +``` + +- **STOP** if the report lists **any other secret** or **any other action**. Do not + approve. Report the unexpected entry verbatim and wait for a human. +- This `--approve` step is *only* the first-install unblock. It is **not** a + substitute for the final strict compile in the next step. + +### 5. Always run the final strict compile WITHOUT `--approve` + +```bash +gh aw compile --strict +``` + +This must run after any first-install approval and before committing. Success +criteria: + +- All six workflows compile successfully. +- The **only** permitted warning is the known `squad.md` bot-trigger warning: it + configures both slash-command and `github-actions[bot]` triggers, and the bot + trigger is required for controlled worker-continuation dispatches. +- **STOP** on any error, or on **any additional warning** beyond that single + documented one. + +### 6. Require all six source/lock pairs to exist + +```bash +for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker; do + test -f ".github/workflows/${workflow}.md" || { echo "MISSING ${workflow}.md"; exit 1; } + test -f ".github/workflows/${workflow}.lock.yml" || { echo "MISSING ${workflow}.lock.yml"; exit 1; } +done +``` + +- **STOP** and rerun `gh aw compile --strict` if any `.lock.yml` is missing. Do not + open or merge the bootstrap PR until all **twelve** files exist and strict + compilation passes. + +> On Windows PowerShell, the `for`/`test -f` loop above is POSIX. Use an +> equivalent guard (e.g. `Test-Path`) or run it under Git Bash; the *logic* — all +> twelve files must exist — is what matters. + +### 7. Inspect generated files, then stage only the documented surfaces + +Downloaded workflow audit data is local diagnostic output — **do not commit it**. +If `.github/aw/logs/` lacks a `.gitignore`, add one there: + +```gitignore +# Ignore all downloaded workflow logs +* + +# But keep this file +!.gitignore +``` + +`gh aw add` may also create `.vscode/settings.json` (enables Copilot for Markdown +workflow files). This is an **optional editor setting** — the stage command below +intentionally leaves it untracked. Delete it if unwanted, or stage it explicitly +if your team wants to share it. Decide deliberately; do not stage it by accident. + +Stage **only** the documented generated surfaces, then verify the staged set: + +```bash +git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/ +git diff --cached --stat +# No deletions should be staged: +test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: staged deletions"; exit 1; } +``` + +- **STOP** if the staged diff shows **unexpected deletions**, **unexpected secrets**, + edits to **unrelated files**, or committed **log/diagnostic output**. Re-scope with + explicit `git add -- ` — never `git add .`, `git add -A`, or `git commit -a`. + +### 8. Commit, push, and open the bootstrap PR to the captured default branch + +```bash +git commit -m "ci: add Squad agentic workflow" +git push -u origin HEAD +gh pr create \ + --base "${default_branch}" \ + --title "ci: add Squad agentic workflow" \ + --body "Installs and strictly compiles the supported Squad GH-AW workflows." +gh pr edit --add-reviewer @copilot +gh pr checks --watch +``` + +- Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded + `main`. +- Request Copilot review, address feedback, and wait for required checks. + +### 9. Never auto-merge — and explain what comes next + +- **Never** merge the bootstrap PR yourself. Merge happens **only** after human + approval. +- Make the two-PR flow explicit to the user: `/squad cast` runs **only after the + bootstrap PR merges**. Casting analyzes the codebase and opens a **separate, + human-reviewed Cast PR** containing the team, routing, charters, the Copilot + agent, and `meet-the-squad.md`. If a work command (`/squad implement`, + `/squad review`) is run before a team exists, it auto-opens that Cast PR first — + merge it and rerun the original command; do not start a second cast. + +## Examples + +### ✓ Correct: runtime-resolved identity, allowlist honored, human-reviewed + +```bash +owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')" +default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')" + +gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \ + -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true + +git switch -c chore/squad-gh-aw-bootstrap +gh aw add \ + bradygaster/squad/workflows/squad.md@dev \ + bradygaster/squad/workflows/squad-implement-worker.md@dev \ + bradygaster/squad/workflows/squad-review.md@dev \ + bradygaster/squad/workflows/squad-deps-worker.md@dev \ + bradygaster/squad/workflows/squad-retro.md@dev \ + bradygaster/squad/workflows/squad-improvement-worker.md@dev + +# Safe-update report shows ONLY the two documented secrets + squad-init → approve once +gh aw compile --strict --approve +gh aw compile --strict # final, no --approve; only the bot-trigger warning remains + +git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/ +git commit -m "ci: add Squad agentic workflow" +git push -u origin HEAD +gh pr create --base "${default_branch}" \ + --title "ci: add Squad agentic workflow" \ + --body "Installs and strictly compiles the supported Squad GH-AW workflows." +gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT merge +``` + +### ✓ Correct: STOP on an undocumented safe-update entry + +```text +gh aw add reports a third secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) + and is NOT the squad-init action. Do NOT run `--approve`. + Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. +``` + +### ✗ Incorrect: hardcoded target and blanket staging + +```bash +# BAD: hardcoded owner/repo and default branch +gh api --method PUT "repos/acme/widgets/actions/permissions/workflow" ... +gh pr create --base main ... # wrong if the default branch isn't `main` + +# BAD: stages logs, .vscode settings, and anything else that changed +git add -A +git commit -m "add squad" +``` + +### ✗ Incorrect: skipping the final strict compile or auto-merging + +```bash +gh aw compile --strict --approve # approved first install... +# ...then committed WITHOUT the final `gh aw compile --strict` (no --approve). WRONG. +gh pr merge --squash # auto-merge before human review. NEVER. +``` + +## Anti-Patterns + +- ❌ **Hardcoding repository identifiers.** Always resolve `owner/repo` and the + default branch at runtime with `gh repo view`. +- ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only + `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. +- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, + `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + else is a STOP. +- ❌ **Treating `--approve` as the final compile.** Always finish with a plain + `gh aw compile --strict` (no `--approve`). +- ❌ **Tolerating extra warnings.** Only the `squad.md` bot-trigger warning is + allowed; every other warning or error halts the run. +- ❌ **Committing diagnostics.** Never commit `.github/aw/logs/` output; add the + log `.gitignore` if missing. +- ❌ **Clobbering existing workflows.** The install is additive; preserve unrelated + `.github/workflows/` files. +- ❌ **Widening the default token.** Keep `default_workflow_permissions=read`. +- ❌ **Auto-merging.** The bootstrap PR and the later Cast PR are both + human-reviewed. `/squad cast` runs only after the bootstrap PR merges. +- ❌ **Opening the PR before all twelve files exist and strict compile passes.** diff --git a/templates/skills/git-workflow/SKILL.md b/templates/skills/git-workflow/SKILL.md new file mode 100644 index 000000000..bfa0b8596 --- /dev/null +++ b/templates/skills/git-workflow/SKILL.md @@ -0,0 +1,204 @@ +--- +name: "git-workflow" +description: "Squad branching model: dev-first workflow with insiders preview channel" +domain: "version-control" +confidence: "high" +source: "team-decision" +--- + +## Context + +Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.** + +| Branch | Purpose | Publishes | +|--------|---------|-----------| +| `main` | Released, tagged, in-npm code only | `npm publish` on tag | +| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge | +| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync | + +## Branch Naming Convention + +Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}` + +Examples: +- `squad/195-fix-version-stamp-bug` +- `squad/42-add-profile-api` + +## Workflow for Issue Work + +1. **Branch from dev:** + ```bash + git checkout dev + git pull origin dev + git checkout -b squad/{issue-number}-{slug} + ``` + +2. **Mark issue in-progress:** + ```bash + gh issue edit {number} --add-label "status:in-progress" + ``` + +3. **Create draft PR targeting dev:** + ```bash + gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft + ``` + +4. **Do the work.** Make changes, write tests, commit with issue reference. + +5. **Push and mark ready:** + ```bash + git push -u origin squad/{issue-number}-{slug} + gh pr ready + ``` + +6. **After merge to dev:** + ```bash + git checkout dev + git pull origin dev + git branch -d squad/{issue-number}-{slug} + git push origin --delete squad/{issue-number}-{slug} + ``` + +## Parallel Multi-Issue Work (Worktrees) + +When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead. + +### When to Use Worktrees vs Sequential + +| Scenario | Strategy | +|----------|----------| +| Single issue | Standard workflow above — no worktree needed | +| 2+ simultaneous issues in same repo | Worktrees — one per issue | +| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) | + +### Setup + +From the main clone (must be on dev or any branch): + +```bash +# Ensure dev is current +git fetch origin dev + +# Create a worktree per issue — siblings to the main clone +git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev +git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev +``` + +**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`). + +Each worktree: +- Has its own working directory and index +- Is on its own `squad/{issue-number}-{slug}` branch from dev +- Shares the same `.git` object store (disk-efficient) + +### Per-Worktree Agent Workflow + +Each agent operates inside its worktree exactly like the single-issue workflow: + +```bash +cd ../squad-195 + +# Work normally — commits, tests, pushes +git add -A && git commit -m "fix: stamp bug (#195)" +git push -u origin squad/195-fix-stamp-bug + +# Create PR targeting dev +gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft +``` + +All PRs target `dev` independently. Agents never interfere with each other's filesystem. + +### .squad/ State in Worktrees + +The `.squad/` directory 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 agent appends to its own section; union merge reconciles on PR merge to dev +- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only + +### Cleanup After Merge + +After a worktree's PR is merged to dev: + +```bash +# From the main clone +git worktree remove ../squad-195 +git worktree prune # clean stale metadata +git branch -d squad/195-fix-stamp-bug +git push origin --delete squad/195-fix-stamp-bug +``` + +If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state. + +--- + +## Multi-Repo Downstream Scenarios + +When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad): + +### Setup + +Clone downstream repos as siblings to the main repo: + +``` +~/work/ + squad-pr/ # main repo + squad-sdk/ # downstream dependency + user-app/ # consumer project +``` + +Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Squad conventions, use `squad/{issue-number}-{slug}`. + +### Coordinated PRs + +- Create PRs in each repo independently +- Link them in PR descriptions: + ``` + Closes #42 + + **Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature) + ``` +- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli) + +### Local Linking for Testing + +Before pushing, verify cross-repo changes work together: + +```bash +# Node.js / npm +cd ../squad-sdk && npm link +cd ../squad-pr && npm link squad-sdk + +# Go +# Use replace directive in go.mod: +# replace github.com/org/squad-sdk => ../squad-sdk + +# Python +cd ../squad-sdk && pip install -e . +``` + +**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs. + +### Worktrees + Multi-Repo + +These compose naturally. You can have: +- Multiple worktrees in the main repo (parallel issues) +- Separate clones for downstream repos +- Each combination operates independently + +--- + +## Anti-Patterns + +- ❌ Branching from main (branch from dev) +- ❌ PR targeting main directly (target dev) +- ❌ Non-conforming branch names (must be squad/{number}-{slug}) +- ❌ Committing directly to main or dev (use PRs) +- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead) +- ❌ Using worktrees for cross-repo work (use separate clones) +- ❌ Leaving stale worktrees after PR merge (clean up immediately) + +## Promotion Pipeline + +- dev → insiders: Automated sync on green build +- dev → main: Manual merge when ready for stable release, then tag +- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent diff --git a/templates/skills/github-multi-account/SKILL.md b/templates/skills/github-multi-account/SKILL.md new file mode 100644 index 000000000..0a2158f33 --- /dev/null +++ b/templates/skills/github-multi-account/SKILL.md @@ -0,0 +1,95 @@ +--- +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 +author: tamirdresher +--- + +# GitHub Multi-Account — AI-Driven Setup + +## When to Activate +When the user has multiple GitHub accounts (check with `gh auth status`). If you see 2+ accounts listed, this skill applies. + +## What to Do (as the AI agent) + +### Step 1: Detect accounts +Run: `gh auth status` +Look for multiple accounts. Note which usernames are listed. + +### Step 2: Ask the user +Ask: "I see you have multiple GitHub accounts: {list them}. Which one is your personal account and which is your work/EMU account?" + +### Step 3: Run the setup automatically +Once the user confirms, do ALL of this for them: + +```powershell +# 1. Define the functions +$personal = "THEIR_PERSONAL_USERNAME" +$work = "THEIR_WORK_USERNAME" + +# 2. Add to PowerShell profile +$profilePath = $PROFILE.CurrentUserAllHosts +if (!(Test-Path $profilePath)) { New-Item -Path $profilePath -Force | Out-Null } +$existing = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue +if ($existing -notmatch "gh-personal") { + $block = @" + +# === GitHub Multi-Account Aliases === +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 } +Set-Alias ghp gh-personal +Set-Alias ghw gh-work +"@ + Add-Content -Path $profilePath -Value $block +} + +# 3. Create CMD wrappers +$binDir = Join-Path $env:USERPROFILE ".squad\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 + +# 4. Add to PATH +$userPath = [Environment]::GetEnvironmentVariable("PATH", "User") +if ($userPath -notmatch [regex]::Escape($binDir)) { + [Environment]::SetEnvironmentVariable("PATH", "$binDir;$userPath", "User") + $env:PATH = "$binDir;$env:PATH" +} + +# 5. Load in current session +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 } +Set-Alias ghp gh-personal +Set-Alias ghw gh-work +``` + +### Step 4: Verify for the user +Run these and show the results: +```powershell +ghp api user --jq '.login' # should show personal username +ghw api user --jq '.login' # should show work username +``` + +### Step 5: Tell the user +"All set! From now on use `ghp` for personal repos and `ghw` for work repos. I'll use them too." + +## After Setup — Usage Rules + +1. **NEVER** use bare `gh` for repo operations — always `ghp` or `ghw` +2. **NEVER** manually `gh auth switch` — the aliases handle it +3. Determine alias by repo owner: + - Personal account repos → `ghp` / `gh-personal` + - Work/EMU account repos → `ghw` / `gh-work` + +## 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`. + +## 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 } +``` diff --git a/templates/skills/history-hygiene/SKILL.md b/templates/skills/history-hygiene/SKILL.md new file mode 100644 index 000000000..b0f61417c --- /dev/null +++ b/templates/skills/history-hygiene/SKILL.md @@ -0,0 +1,36 @@ +--- +name: history-hygiene +description: Record final outcomes to history.md, not intermediate requests or reversed decisions +domain: documentation, team-collaboration +confidence: high +source: earned (release-history correction incident) +--- + +## Context + +History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. A release incident proved this: history retained an obsolete v0.6.0 target after the user had changed it to v0.8.17. Future spawns read the wrong truth and repeated the mistake. + +## Patterns + +- **Record the final outcome**, not the initial request. +- **Wait for confirmation** before writing to history — don't log intermediate states. +- **If a decision reverses**, update the entry immediately — don't leave stale data. +- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened. + +## Examples + +✓ **Correct:** +- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by the user)" +- "Reverted to Node 18 per the user's explicit request on 2024-01-15" + +✗ **Incorrect:** +- "The user directed v0.6.0" (when later reversed) +- Recording what was *requested* instead of what *actually happened* +- Logging entries before outcome is confirmed + +## Anti-Patterns + +- Writing intermediate or "for now" states to disk +- Attributing decisions without confirming final direction +- Treating history like a draft — history is the source of truth +- Assuming readers will cross-reference or verify; they won't diff --git a/templates/skills/humanizer/SKILL.md b/templates/skills/humanizer/SKILL.md new file mode 100644 index 000000000..0932510c2 --- /dev/null +++ b/templates/skills/humanizer/SKILL.md @@ -0,0 +1,105 @@ +--- +name: "humanizer" +description: "Tone enforcement patterns for external-facing community responses" +domain: "communication, tone, community" +confidence: "low" +source: "manual (external communications workflow)" +--- + +## Context + +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. + +- Tone must be warm, helpful, and human-sounding — never robotic or corporate. +- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. + +## Patterns + +1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!") +2. **Active voice** — "We're looking into this" not "This is being investigated" +3. **Second person** — Address the person directly ("you" not "the user") +4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:" +5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues" +6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!" +7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required" +8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence +9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting +10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold) +11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning +12. **Information request** — Ask for specific details, not open-ended "can you provide more info?" +13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link + +## Examples + +### 1. Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{substantive response} +Let us know if you have questions — happy to help! +``` + +### 2. Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### 3. Feature guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### 4. Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### 5. Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### 6. Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### 7. Technical uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +## Anti-Patterns + +- ❌ Corporate speak: "We appreciate your patience as we investigate this matter" +- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..." +- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked" +- ❌ Dismissive: "This works as designed" without empathy +- ❌ Over-promising: "We'll ship this next week" without commitment from the team +- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" +- ❌ Excessive emoji: More than 1-2 emoji per response +- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead +- ❌ Link-dumping: Pasting URLs without context ("See: https://...") +- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information diff --git a/templates/skills/init-mode/SKILL.md b/templates/skills/init-mode/SKILL.md new file mode 100644 index 000000000..5f99e7dab --- /dev/null +++ b/templates/skills/init-mode/SKILL.md @@ -0,0 +1,104 @@ +--- +name: "init-mode" +description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)" +domain: "orchestration" +confidence: "high" +source: "extracted" +tools: + - name: "ask_user" + description: "Confirm team roster with selectable menu" + when: "Phase 1 proposal — requires explicit user confirmation" +--- + +## Context + +Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2). + +## Patterns + +### Phase 1: Propose the Team + +No team exists yet. Propose one — but **DO NOT create any files until the user confirms.** + +1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey {user}, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.** +2. Ask: *"What are you building? (language, stack, what it does)"* +3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section): + - Determine team size (typically 4–5 + Scribe). + - **Default to descriptive names** (Lead, Frontend, Backend, Tester, etc.) unless the user requests a themed universe. + - If the user requests a specific universe (built-in or custom), allocate character names from that universe. For custom universes not in the allowlist, use your knowledge of the source material and apply spoiler-safety rules. + - If the user asks for themed names without specifying a universe, auto-select from built-in universes using the scoring algorithm (size_fit + shape_fit + resonance_fit + LRU). + - Scribe is always "Scribe" — exempt from casting. + - Ralph is always "Ralph" — exempt from casting. +4. Propose the team with their cast names. Example (names will vary per cast): + +``` +🏗️ Lead — Lead Scope, decisions, code review +⚛️ Frontend — Frontend Dev React, UI, components +🔧 Backend — Backend Dev APIs, database, services +🧪 Tester — Tester Tests, quality, edge cases +📋 Scribe — (silent) Memory, decisions, session logs +🔄 Ralph — (monitor) Work queue, backlog, keep-alive +``` + +5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu: + - **question:** *"Look right?"* + - **choices:** `["Yes, cast this team", "Add someone", "Change a role"]` + +**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.** + +### Phase 2: Create the Team + +**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes"). + +> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms. + +6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/). + +**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id). + +**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing. + +**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks. + +**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches: +``` +.squad/decisions.md merge=union +.squad/agents/*/history.md merge=union +.squad/log/** merge=union +.squad/orchestration-log/** merge=union +``` +The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically. + +7. Say: *"✅ Team cast. Try: '{FirstCastName}, set up the project structure'"* + +8. **Post-setup input sources** (optional — ask after team is created, not during casting): + - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow + - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow + - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section + - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment + - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately. + +## Examples + +**Example flow:** +1. Coordinator detects no team.md → Init Mode +2. Runs `git config user.name` → "{user}" +3. Asks: *"Hey {user}, what are you building?"* +4. User: *"TypeScript CLI tool with GitHub API integration"* +5. Coordinator uses descriptive naming by default +6. Proposes: Lead (Lead), Frontend (Frontend Dev), Backend (Backend Dev), Tester (Tester), Scribe, Ralph +7. Uses `ask_user` with choices → user selects "Yes, cast this team" +8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents +9. Says: *"✅ Team cast. Try: 'Lead, set up the project structure'"* + +## Anti-Patterns + +- ❌ Creating files before user confirms Phase 1 +- ❌ Mixing agents from different universes in the same cast +- ❌ Skipping the `ask_user` tool and assuming confirmation +- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role" +- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows) +- ❌ Forgetting to initialize `.squad/casting/` state files +- ❌ Reading or storing `git config user.email` (PII violation) +- ❌ Rejecting a user's universe choice because it is not in the built-in allowlist +- ❌ Auto-selecting a themed universe when the user didn't ask for one (use descriptive names by default) diff --git a/templates/skills/iterative-retrieval/SKILL.md b/templates/skills/iterative-retrieval/SKILL.md new file mode 100644 index 000000000..4d8eea993 --- /dev/null +++ b/templates/skills/iterative-retrieval/SKILL.md @@ -0,0 +1,165 @@ +--- +name: "iterative-retrieval" +description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work." +domain: "agent-coordination" +confidence: "high" +license: MIT +--- + +# Iterative Retrieval Skill + +Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these +handoffs become vague, cycles multiply, and outputs land without being checked. The +**Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and +requires the coordinator to validate agent output before closing an issue. + +--- + +## Spawn Prompt Template + +Every agent spawn must include the following four sections. Copy and fill in the template: + +``` +## Task +{What you need done — concrete and bounded} + +## WHY this matters +{The motivation and context. What system or user goal does this serve? What breaks if skipped?} + +## Success criteria +{How you will know the output is correct. Be explicit — list acceptance criteria, not vibes.} +Example: +- [ ] File X exists and contains Y +- [ ] No regressions in existing tests +- [ ] PR is open targeting main with description matching the issue + +## Escalation path +{What the agent should do if uncertain or stuck. "Stop and ask me" is valid.} +Example: +- If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision +- If blocked by a dependency → label status:blocked, explain in a comment +- If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator +``` + +--- + +## 3-Cycle Protocol + +| Cycle | Description | Exit condition | +|-------|-------------|----------------| +| **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. | +| **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. | +| **3** | Final attempt with all context from cycles 1–2 | Done or escalate — no cycle 4. | + +### Rules + +1. **After each cycle**, the coordinator evaluates the output against the success criteria + before accepting it or spawning the next cycle. +2. **Objective context forward**: each subsequent spawn includes a summary of what was tried + and what is still missing — not just a repeat of the original task. +3. **Cycle 3 exhausted** → escalate: write a summary to `.squad/decisions/inbox/`, label the + issue `status:needs-decision`, and notify the user. + +--- + +## Coordinator Validation Checklist + +Before accepting agent output and closing an issue, the coordinator must check: + +- [ ] All success criteria from the spawn prompt are met +- [ ] PR exists and description matches the issue (if code work) +- [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes) +- [ ] Agent did not silently skip parts of the task +- [ ] If the agent reported uncertainty — was it resolved or escalated? + +If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas. + +--- + +## When to Escalate vs Retry + +**Retry (cycle N+1)** when: +- Output is structurally correct but missing specific items +- Agent misunderstood scope (provide more context and re-run) +- Partial success — clearly identified remaining delta + +**Escalate** when: +- Requirements are fundamentally unclear (decision needed) +- 3 cycles complete without convergence +- Agent returned conflicting results across cycles +- Task requires elevated permissions or external action +- The work depends on another issue that isn't done yet + +--- + +## Issue Dedup Check (Mandatory) + +Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid +duplicates. + +```bash +# Check for existing open issues before creating a new one +gh issue list --search "" --state open +``` + +- If an open issue already covers the same problem → **comment on it** instead of creating a new one. +- If no duplicate → proceed to create the issue. +- Use 2–3 representative keywords from the planned issue title as the search query. + +--- + +## Mandatory Output Requirement (Research-Then-Execute) + +Every research or analysis task completed under this protocol **MUST** end with at least one +concrete action before the cycle is closed. Acceptable follow-up actions: + +- GitHub issue created documenting the findings and next steps +- PR opened implementing a recommendation +- Decision recorded in `.squad/decisions/inbox/` +- Documented recommendation with a named assignee and due date + +**Pure analysis reports without actionable follow-up will be rejected during triage.** +If no action is warranted, the agent must explicitly state why and get coordinator sign-off. + +--- + +## Anti-Patterns + +- **Spawning without WHY** — agents can't prioritise trade-offs without motivation context. +- **Accepting output without validating** — one failed check avoids merging broken work. +- **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent. +- **Vague success criteria** — "looks good" is not a criterion. Use checkboxes. +- **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong. +- **Creating issues without dedup check** — always search before creating. +- **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work. + +--- + +## Examples + +### Good spawn prompt +``` +## Task +Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining +the 3-cycle rule, WHY format, and validation checklist. + +## WHY this matters +The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded +cycles and outputs go unvalidated — leading to stale issues and silent failures. + +## Success criteria +- [ ] Section "Iterative Retrieval Protocol" exists in charter.md +- [ ] Section documents max-3-cycles rule +- [ ] Section documents WHY format requirement +- [ ] Section contains validation checklist (at least 4 items) +- [ ] No other sections of charter.md are modified + +## Escalation path +If the charter.md format is unclear, check another agent charter as a reference. +If uncertain about content, stop and surface to coordinator. +``` + +### Bad spawn prompt (don't do this) +``` +Update the coordinator charter with the iterative retrieval stuff. +``` diff --git a/templates/skills/model-selection/SKILL.md b/templates/skills/model-selection/SKILL.md new file mode 100644 index 000000000..18dcebf47 --- /dev/null +++ b/templates/skills/model-selection/SKILL.md @@ -0,0 +1,125 @@ +--- +name: "model-selection" +description: "Determines which LLM model to use for each agent spawn" +domain: "orchestration" +confidence: "medium" +source: "extracted" +--- + +# Model Selection + +> Determines which LLM model to use for each agent spawn. + +## SCOPE + +✅ THIS SKILL PRODUCES: +- A resolved `model` parameter for every `task` tool call +- Persistent model preferences in `.squad/config.json` +- Spawn acknowledgments that include the resolved model + +❌ THIS SKILL DOES NOT PRODUCE: +- Code, tests, or documentation +- Model performance benchmarks +- Cost reports or billing artifacts + +## Context + +Squad supports a curated model catalog across three tiers (premium, standard, fast). The coordinator must select the right model for each agent spawn. Users can set persistent preferences that survive across sessions. + +## 5-Layer Model Resolution Hierarchy + +Resolution is **first-match-wins** — the highest layer with a value wins. + +| Layer | Name | Source | Persistence | +|-------|------|--------|-------------| +| **0a** | Per-Agent Config | `.squad/config.json` → `agentModelOverrides.{name}` | Persistent (survives sessions) | +| **0b** | Global Config | `.squad/config.json` → `defaultModel` | Persistent (survives sessions) | +| **1** | Session Directive | User said "use X" in current session | Session-only | +| **2** | Charter Preference | Agent's `charter.md` → `## Model` section | Persistent (in charter) | +| **3** | Task-Aware Auto | Code/prompts → Terra, docs → Luna, visual → Sol | Computed per-spawn | +| **4** | Default | `gpt-5.6-luna` | Hardcoded fallback | + +**Key principle:** Layer 0 (persistent config) beats everything. If the user said "always use opus" and it was saved to config.json, every agent gets opus regardless of role or task type. This is intentional — the user explicitly chose quality over cost. + +## AGENT WORKFLOW + +### On Session Start + +1. READ `.squad/config.json` +2. CHECK for `defaultModel` field — if present, this is the Layer 0 override for all spawns +3. CHECK for `agentModelOverrides` field — if present, these are per-agent Layer 0a overrides +4. STORE both values in session context for the duration + +### On Every Agent Spawn + +1. CHECK Layer 0a: Is there an `agentModelOverrides.{agentName}` in config.json? → Use it. +2. CHECK Layer 0b: Is there a `defaultModel` in config.json? → Use it. +3. CHECK Layer 1: Did the user give a session directive? → Use it. +4. CHECK Layer 2: Does the agent's charter have a `## Model` section? → Use it. +5. CHECK Layer 3: Determine task type: +- Code (implementation, tests, refactoring, bug fixes) → `gpt-5.6-terra` +- Prompts, agent designs → `gpt-5.6-terra` +- Visual/design with image analysis → `gpt-5.6-sol` +- Non-code (docs, planning, triage, changelogs) → `gpt-5.6-luna` +6. FALLBACK Layer 4: `gpt-5.6-luna` +7. INCLUDE model in spawn acknowledgment: `🔧 {Name} ({resolved_model}) — {task}` + +### When User Sets a Preference + +**Trigger phrases:** "always use X", "use X for everything", "switch to X", "default to X" + +1. VALIDATE the model ID against the catalog +2. WRITE `defaultModel` to `.squad/config.json` (merge, don't overwrite) +3. ACKNOWLEDGE: `✅ Model preference saved: {model} — all future sessions will use this until changed.` + +**Per-agent trigger:** "use X for {agent}" + +1. VALIDATE model ID +2. WRITE to `agentModelOverrides.{agent}` in `.squad/config.json` +3. ACKNOWLEDGE: `✅ {Agent} will always use {model} — saved to config.` + +### When User Clears a Preference + +**Trigger phrases:** "switch back to automatic", "clear model preference", "use default models" + +1. REMOVE `defaultModel` from `.squad/config.json` +2. ACKNOWLEDGE: `✅ Model preference cleared — returning to automatic selection.` + +### STOP + +After resolving the model and including it in the spawn template, this skill is done. Do NOT: +- Generate model comparison reports +- Run benchmarks or speed tests +- Create new config files (only modify existing `.squad/config.json`) +- Change the model after spawn (fallback chains handle runtime failures) + +## Config Schema + +`.squad/config.json` model-related fields: + +```json +{ + "version": 1, + "defaultModel": "claude-opus-4.6", + "agentModelOverrides": { + "fenster": "claude-sonnet-4.6", + "mcmanus": "claude-haiku-4.5" + } +} +``` + +- `defaultModel` — applies to ALL agents unless overridden by `agentModelOverrides` +- `agentModelOverrides` — per-agent overrides that take priority over `defaultModel` +- Both fields are optional. When absent, Layers 1-4 apply normally. + +## Fallback Chains + +If a model is unavailable (rate limit, plan restriction), retry within the same tier: + +``` +Premium: gpt-5.6-sol → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-4.6 → (omit model param) +Standard: gpt-5.6-terra → claude-sonnet-5 → claude-sonnet-4.6 → gpt-5.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4.5 → gemini-3.1-pro → (omit model param) +Fast: gpt-5.6-luna → claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini → (omit model param) +``` + +**Never fall UP in tier.** A fast task won't land on a premium model via fallback. diff --git a/templates/skills/notification-routing/SKILL.md b/templates/skills/notification-routing/SKILL.md new file mode 100644 index 000000000..42c5cb075 --- /dev/null +++ b/templates/skills/notification-routing/SKILL.md @@ -0,0 +1,105 @@ +--- +name: "notification-routing" +description: "Route agent notifications to specific channels by type — prevent alert fatigue from single-channel flooding" +domain: "communication" +confidence: "high" +source: "earned" +--- + +## Context + +When a Squad grows beyond a few agents, notifications flood a single channel — failure alerts drown in daily +briefings, tech news buries security findings, and everything gets ignored. This is the pub-sub problem: +a single message queue for everything is a recipe for missed alerts. + +The fix is **topic-based routing**: agents tag notifications with a channel type, and a routing function +sends them to the appropriate destination. + +**Trigger symptoms:** +- Important alerts missed because they're buried in routine notifications +- Team members turning off notifications entirely (signal overwhelm) +- Onboarding friction: "where do I look for X?" + +## Patterns + +### Channel Config Schema + +Define a `.squad/teams-channels.json` (or equivalent) mapping notification types to channel identifiers: + +```json +{ + "teamId": "your-team-id", + "channels": { + "notifications": "squad-alerts", + "tech-news": "tech-news", + "security": "security-findings", + "releases": "release-announcements", + "daily-digest": "daily-digest" + } +} +``` + +Place this in `.squad/` (git-tracked, shared across the team). For platforms that use channel IDs instead of +names (Teams, Slack), store the resolved ID alongside the name to avoid name-collision bugs: + +```json +{ + "channels": { + "notifications": { "name": "squad-alerts", "id": "channel-id-opaque-string" } + } +} +``` + +### CHANNEL: Tag Convention + +Agents prefix their output with `CHANNEL:` to signal where the notification should go: + +``` +CHANNEL:security +Security Reviewer found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5 +``` + +### Routing Dispatcher (shell pseudocode) + +```bash +dispatch_notification() { + local raw_output="$1" + local channel="notifications" # default + + if echo "$raw_output" | grep -qE '^CHANNEL:[a-z][a-z0-9-]*'; then + channel=$(echo "$raw_output" | head -1 | cut -d: -f2) + raw_output=$(echo "$raw_output" | tail -n +2) + fi + + send_notification --channel "$channel" --message "$raw_output" +} +``` + +### Provider-Agnostic Adapter + +The routing layer is provider-agnostic. Plug in your platform adapter: + +``` +.squad/notify-adapter.sh # Teams / Slack / Discord / webhook -- swappable +``` + +The routing config and CHANNEL: tags never change. Only the adapter changes per deployment. + +## Anti-Patterns + +**Never send all notification types to one channel:** +``` +send_notification --channel "general" --message "$anything" +``` + +**Never use display names as identifiers (name collision risk):** +``` +send_to_team --name "Squad" --channel "notifications" +``` + +Resolve channel IDs once at setup. Use IDs at runtime. + +## Distributed Systems Pattern + +This is **pub-sub with topic routing** -- the same principle as Kafka topics, RabbitMQ routing keys, and +AWS SNS topic filtering. Route by type. Each consumer subscribes to the topics it cares about. \ No newline at end of file diff --git a/templates/skills/personal-squad/SKILL.md b/templates/skills/personal-squad/SKILL.md new file mode 100644 index 000000000..958031e39 --- /dev/null +++ b/templates/skills/personal-squad/SKILL.md @@ -0,0 +1,66 @@ +--- +name: "personal-squad" +description: "User-level AI agents that travel with you across projects" +domain: "configuration" +confidence: "medium" +source: "manual" +--- + +# Personal Squad — Skill Document + +## What is a Personal Squad? + +A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session. + +## Directory Structure + +``` +~/Library/Application Support/squad/personal-squad/ # macOS +~/.config/squad/personal-squad/ # Linux +%APPDATA%/squad/personal-squad/ # Windows +├── agents/ +│ ├── {agent-name}/ +│ │ ├── charter.md +│ │ └── history.md +│ └── ... +└── config.json # Optional: personal squad config +``` + +## How It Works + +1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory +2. **Merge:** Personal agents are merged into the session cast alongside project agents +3. **Ghost Protocol:** Personal agents can read project state but not write to it +4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery + +## Commands + +- `squad personal init` — Bootstrap a personal squad directory +- `squad personal list` — List your personal agents +- `squad personal add {name} --role {role}` — Add a personal agent +- `squad personal remove {name}` — Remove a personal agent +- `squad cast` — Show the current session cast (project + personal) + +## Ghost Protocol + +See `templates/ghost-protocol.md` for the full rules. Key points: +- Personal agents advise; project agents execute +- No writes to project `.squad/` state +- Transparent origin tagging in logs +- Project agents take precedence on conflicts + +## Configuration + +Optional `config.json` in the personal squad directory: +```json +{ + "defaultModel": "auto", + "ghostProtocol": true, + "agents": {} +} +``` + +## Environment Variables + +- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery +- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path diff --git a/templates/skills/pr-review-response/SKILL.md b/templates/skills/pr-review-response/SKILL.md new file mode 100644 index 000000000..dfe290a56 --- /dev/null +++ b/templates/skills/pr-review-response/SKILL.md @@ -0,0 +1,268 @@ +--- +name: "pr-review-response" +description: "Teaches agents to reply to PR review comment threads after fixing issues, making resolutions traceable" +domain: "pull-requests, code-review, traceability" +confidence: "low" +source: "observed (agents fix review feedback silently — reviewers can't tell which comments were addressed)" +tools: + - name: "github-mcp-server-pull_request_read" + description: "Read PR review threads and comments" + when: "Step 1 — fetching review comments to understand what needs fixing" + - name: "gh api (REST)" + description: "Reply to review comment threads and resolve threads via GraphQL" + when: "Step 3 — posting reply to each comment thread after fixing" +--- + +## Context + +When an agent fixes code in response to PR review comments (from Copilot, a human reviewer, or any GitHub reviewer), the fix alone is not enough. The reviewer needs to see — on the PR thread itself — which comments were addressed and how. Without replies, comments stay visually unresolved, reviewers must re-read the entire diff to verify fixes, and there's no traceable link between feedback and resolution. + +Use this skill whenever: +- You are fixing code based on PR review feedback +- You are addressing Copilot review suggestions +- You are responding to reviewer-requested changes on a PR +- A squad member hands you review comments to resolve + +## SCOPE + +✅ THIS SKILL PRODUCES: +- Reply comments on each review thread explaining the fix +- Optionally resolved threads (via GraphQL when appropriate) +- Commit messages that reference the PR and review context + +❌ THIS SKILL DOES NOT PRODUCE: +- The code fixes themselves (that's the agent's domain work) +- New review comments or reviews +- PR descriptions or summaries + +## Patterns + +### Step 1: Read the review comments + +**Using MCP tools (preferred when available):** + +``` +github-mcp-server-pull_request_read + method: "get_review_comments" + owner: "{owner}" + repo: "{repo}" + pullNumber: {pr_number} +``` + +This returns review threads with metadata: `isResolved`, `isOutdated`, `isCollapsed`, and their associated comments. Each comment has an `id` you'll need for replies. + +**Using gh CLI (fallback):** + +```bash +gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate +``` + +Each comment object contains `id`, `body`, `path`, `line`, and `in_reply_to_id`. Top-level comments have no `in_reply_to_id` — those are the ones you reply to. + +### Step 2: Fix the code + +Make the actual code changes. This is your normal domain work — the skill doesn't prescribe how to fix, only how to communicate the fix. + +**Track what you changed.** For each review comment, note: +- The comment `id` (top-level, not a reply) +- The file and line referenced +- What you actually changed (brief description) +- The commit SHA after pushing (if available) + +### Step 3: Reply to each review thread + +After fixing and committing, reply to **each** review comment thread individually. + +**REST API call (via gh CLI):** + +```bash +gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \ + -f body="Fixed in {sha_short} — {brief description of what was changed}" +``` + +**Important:** `{comment_id}` must be the ID of the **top-level** comment in the thread. You cannot reply to a reply — only to the original review comment. + +**Example replies:** + +```bash +# Specific and traceable +gh api repos/bradygaster/squad/pulls/42/comments/18234/replies \ + -f body="Fixed in a1b2c3d — switched to path.dirname(squadDirInfo.path) for worktree consistency" + +# When applying a suggested code change +gh api repos/bradygaster/squad/pulls/42/comments/18235/replies \ + -f body="Applied suggestion — updated error message to include the file path for debuggability" + +# When pushing back on a suggestion +gh api repos/bradygaster/squad/pulls/42/comments/18236/replies \ + -f body="Considered but not applied — this path needs to stay absolute because worktree resolution depends on it. See detectSquadDir() in detect-squad-dir.ts." +``` + +### Step 4: Resolve threads (optional, GraphQL only) + +Thread resolution is only available via the GitHub GraphQL API. Use this when your fix fully addresses the comment and no further discussion is needed. + +**First, get the thread IDs** (they're different from comment IDs): + +```bash +gh api graphql -f query=' + query { + repository(owner: "{owner}", name: "{repo}") { + pullRequest(number: {pr_number}) { + reviewThreads(first: 100) { + nodes { + id + isResolved + comments(first: 1) { + nodes { body databaseId } + } + } + } + } + } + } +' +``` + +Match thread IDs to comment IDs using `databaseId`, then resolve: + +```bash +gh api graphql -f query=' + mutation { + resolveReviewThread(input: {threadId: "{thread_node_id}"}) { + thread { id isResolved } + } + } +' +``` + +**When to resolve vs. leave open:** +- ✅ Resolve: You fixed exactly what was requested, no ambiguity +- ❌ Don't resolve: You pushed back, applied a different fix, or the comment needs further discussion +- ❌ Don't resolve: The reviewer is a human — let them confirm and resolve themselves + +**Rule of thumb:** Agent-to-agent threads (e.g., Copilot review → agent fix) can be resolved by the fixer. Human reviewer threads should be left for the human to resolve. + +### Step 5: Commit message traceability + +Commit messages should reference the PR context: + +``` +fix: address review feedback on PR #{pr_number} + +- Switched to path.dirname() for worktree path resolution (comment #18234) +- Updated error message to include file path (comment #18235) + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> +``` + +For single-comment fixes, a shorter format works: + +``` +fix: use path.dirname() for worktree consistency (PR #{pr_number} review) + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> +``` + +## AGENT WORKFLOW (Summary) + +1. **READ** — Fetch review threads using MCP tool or `gh api` +2. **FIX** — Make code changes, tracking comment ID → change mapping +3. **COMMIT** — Push with traceable commit message referencing PR and comments +4. **REPLY** — Post individual reply to each thread via `gh api .../replies` +5. **RESOLVE** — (Optional) Resolve agent-to-agent threads via GraphQL +6. **STOP** — Do not batch-reply, do not skip threads, do not resolve human threads + +## Examples + +### Example: Copilot flags a potential null dereference + +**Review comment (id: 55123):** +> `squadDir` could be undefined here. Consider adding a null check. + +**Agent workflow:** +1. Read the comment via `get_review_comments` +2. Add the null check in `src/cli/core/detect-squad-dir.ts` +3. Commit: `fix: add null check for squadDir (PR #99 review)` +4. Reply: + ```bash + gh api repos/bradygaster/squad/pulls/99/comments/55123/replies \ + -f body="Fixed in f4e5d6c — added early return when squadDir is undefined, matching the pattern in loadConfig()" + ``` +5. Resolve the thread (Copilot → agent, safe to resolve) + +### Example: Multiple review comments on one PR + +**Comments:** +- id: 55123 — "Null check needed" on `detect-squad-dir.ts:42` +- id: 55124 — "Consider using path.join()" on `detect-squad-dir.ts:58` +- id: 55125 — "This log message is too verbose" on `output.ts:15` + +**Agent handles each individually:** +```bash +# Fix all three, commit +git add packages/squad-cli/src/cli/core/detect-squad-dir.ts packages/squad-cli/src/cli/core/output.ts +git commit -m "fix: address 3 review comments on PR #99 + +- Added null check for squadDir (comment #55123) +- Switched to path.join() for cross-platform paths (comment #55124) +- Reduced log verbosity to debug level (comment #55125)" + +git push + +# Reply to each thread individually +gh api repos/bradygaster/squad/pulls/99/comments/55123/replies \ + -f body="Fixed — added early return when squadDir is undefined" + +gh api repos/bradygaster/squad/pulls/99/comments/55124/replies \ + -f body="Fixed — switched to path.join(squadDir, 'config.json') for cross-platform consistency" + +gh api repos/bradygaster/squad/pulls/99/comments/55125/replies \ + -f body="Fixed — changed from console.log to debug() so it only shows with --verbose flag" +``` + +### Example: Handling Copilot suggestion blocks + +Copilot sometimes provides `suggestion` blocks with exact code to apply: + +**Review comment (id: 55130):** +```` +Consider using optional chaining: +```suggestion +const name = config?.agent?.name ?? 'default'; +``` +```` + +**Reply format when applying:** +```bash +gh api repos/bradygaster/squad/pulls/99/comments/55130/replies \ + -f body="Applied suggestion — using optional chaining with nullish coalescing" +``` + +**Reply format when not applying:** +```bash +gh api repos/bradygaster/squad/pulls/99/comments/55130/replies \ + -f body="Not applied — config is guaranteed non-null at this point (validated on line 12). Optional chaining would mask errors." +``` + +### Example: Pushing back on a review comment + +Not every review comment should be accepted. When a suggestion is incorrect or doesn't apply: + +```bash +gh api repos/bradygaster/squad/pulls/99/comments/55140/replies \ + -f body="Considered but not applied — this file is in the zero-dependency bootstrap set (see copilot-instructions.md § Protected Files). Adding path.join() would require importing from the SDK, which breaks the bootstrap constraint." +``` + +Do NOT resolve the thread when pushing back. Leave it open for the reviewer to confirm. + +## Anti-Patterns + +- ❌ **Fixing silently** — Making code changes without replying to the review thread. The reviewer has no way to know which comments were addressed. +- ❌ **Batch-replying "all fixed"** — A single comment saying "Addressed all review feedback" on the PR. Each thread needs its own reply so reviewers can verify individually. +- ❌ **Resolving without explaining** — Marking threads resolved without posting a reply first. The resolution gives no context on what was done. +- ❌ **Resolving human reviewer threads** — Only resolve threads from automated reviewers (Copilot, bots). Let human reviewers confirm and resolve their own threads. +- ❌ **Vague replies** — "Fixed" or "Done" without saying what was changed. The reply should be specific enough that the reviewer doesn't need to re-read the diff. +- ❌ **Replying before pushing** — Reply after your fix is committed and pushed, not before. The reply should reference actual committed code. +- ❌ **Ignoring comments you disagree with** — If you don't apply a suggestion, reply explaining why. Silence looks like you missed it. +- ❌ **Replying to replies** — The REST API only supports replying to top-level review comments. Attempting to reply to a reply will fail with a 404. diff --git a/templates/skills/pr-screenshots/SKILL.md b/templates/skills/pr-screenshots/SKILL.md new file mode 100644 index 000000000..fc93e8f77 --- /dev/null +++ b/templates/skills/pr-screenshots/SKILL.md @@ -0,0 +1,149 @@ +--- +name: "pr-screenshots" +description: "Capture Playwright screenshots and embed them in GitHub PR descriptions" +domain: "pull-requests, visual-review, docs, testing" +confidence: "high" +source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)" +--- + +## Context + +When a PR includes visual changes (docs sites, UI components, generated pages), reviewers +need to see what the PR delivers without checking out the branch. Screenshots belong in +the **PR description body**, not as committed files and not as text descriptions. + +Use this skill whenever: +- A PR touches docs site pages (Astro, Starlight, etc.) +- A PR adds or changes UI components +- A PR generates visual artifacts (TypeDoc, Storybook, diagrams) +- Playwright tests already capture screenshots as part of testing + +## Patterns + +### 1. Capture screenshots with Playwright + +If Playwright tests already exist and produce screenshots, reuse those. Otherwise, +write a minimal capture script: + +```javascript +// scripts/capture-pr-screenshots.mjs +import { chromium } from 'playwright'; + +const browser = await chromium.launch(); +const page = await browser.newPage({ viewport: { width: 1280, height: 720 } }); + +const screenshots = [ + { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' }, + { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' }, +]; + +for (const { url, name } of screenshots) { + await page.goto(url, { waitUntil: 'networkidle' }); + await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false }); +} + +await browser.close(); +``` + +### 2. Host screenshots on a temporary branch + +GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary +images directly. Use a temporary orphan branch to host the images: + +```powershell +# Save current branch +$currentBranch = git branch --show-current + +# Create orphan branch with only screenshot files +git checkout --orphan screenshots-temp +git reset +git add screenshots/*.png +git commit -m "screenshots for PR review" +git push origin screenshots-temp --force + +# Build raw URLs +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" +# Each image: $base/{name}.png + +# Return to working branch +git checkout -f $currentBranch +``` + +### 3. Embed in PR description + +Use `gh pr edit` with the raw URLs embedded as markdown images: + +```powershell +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" + +gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @" +## {PR Title} + +### What this PR delivers +- {bullet points of changes} + +--- + +### Screenshots + +#### {Page/Feature Name} +![{alt text}]($base/{name}.png) + +#### {Another Page} +![{alt text}]($base/{another-name}.png) + +--- + +### To verify locally +```bash +{commands to run locally} +``` +"@ +``` + +### 4. Cleanup after merge + +After the PR is merged, delete the temporary branch: + +```bash +git push origin --delete screenshots-temp +``` + +### 5. Gitignore screenshots locally + +Screenshots are build artifacts — never commit them to feature branches: + +```gitignore +# PR screenshots (hosted on temp branch, not committed to features) +screenshots/ +docs/tests/screenshots/ +``` + +## Examples + +### Example: Docs site PR with 3 pages + +1. Start dev server: `cd docs && npm run dev` +2. Run Playwright tests (they capture screenshots as a side effect) +3. Push screenshots to `screenshots-temp` branch +4. Update PR body with embedded `![...]()` image references +5. Reviewer sees the pages inline without checking out the branch + +### Example: Reusing existing Playwright test screenshots + +If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`: + +```powershell +cd docs && npx playwright test tests/api-reference.spec.mjs +# Screenshots now at docs/tests/screenshots/*.png +# Push those to screenshots-temp and embed in PR +``` + +## Anti-Patterns + +- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale +- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting +- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads +- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern +- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see +- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge diff --git a/templates/skills/project-conventions/SKILL.md b/templates/skills/project-conventions/SKILL.md new file mode 100644 index 000000000..48a1861da --- /dev/null +++ b/templates/skills/project-conventions/SKILL.md @@ -0,0 +1,56 @@ +--- +name: "project-conventions" +description: "Core conventions and patterns for this codebase" +domain: "project-conventions" +confidence: "medium" +source: "template" +--- + +## Context + +> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality. + +## Patterns + +### [Pattern Name] + +Describe a key convention or practice used in this codebase. Be specific about what to do and why. + +### Error Handling + + + + + + +### Testing + + + + + + +### Code Style + + + + + + +### File Structure + + + + + + +## Examples + +``` +// Add code examples that demonstrate your conventions +``` + +## Anti-Patterns + + +- **[Anti-pattern]** — Explanation of what not to do and why. diff --git a/templates/skills/ralph-two-pass-scan/SKILL.md b/templates/skills/ralph-two-pass-scan/SKILL.md new file mode 100644 index 000000000..dfe282a87 --- /dev/null +++ b/templates/skills/ralph-two-pass-scan/SKILL.md @@ -0,0 +1,43 @@ +--- +name: "ralph-two-pass-scan" +description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration" +domain: "work-monitoring" +confidence: "high" +source: "extracted" +--- + +# Skill: Ralph — Two-Pass Issue Scanning +**Confidence:** high +**Domain:** work-monitoring +**Last validated:** 2026-03-24 + +## Context +Cuts GitHub API calls from N+1 to ~7 per round (~72% reduction) by separating list scanning from full hydration. +Addresses the scanning inefficiency described in issue #596. + +## Pattern + +### Pass 1 — Lightweight Scan + +``` +gh issue list --state open --json number,title,labels,assignees --limit 100 +``` + +**Skip hydration if ANY of these match:** + +| Condition | Skip reason | +|-----------|-------------| +| `assignees` non-empty AND no `status:needs-review` | Already owned | +| Labels contain `status:blocked` or `status:waiting-external` | Externally gated | +| Labels contain `status:done` or `status:postponed` | Closed loop | +| Title matches stale/noisy pattern (`[chore]`, `[auto]`) | Low-signal | + +### Pass 2 — Selective Hydration + +For each issue surviving Pass 1: + +``` +gh issue view --json number,title,body,labels,assignees,comments,state +``` + +Then apply normal Ralph triage logic. Rule of thumb: hydrate ≤ 30% of scanned list. If more than 30% survive Pass 1, tighten filter rules. diff --git a/templates/skills/reflect/SKILL.md b/templates/skills/reflect/SKILL.md new file mode 100644 index 000000000..6a85b5190 --- /dev/null +++ b/templates/skills/reflect/SKILL.md @@ -0,0 +1,229 @@ +--- +name: reflect +description: Learning capture system that extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes. Use after user corrections ("no", "wrong"), praise ("perfect", "exactly"), or when discovering edge cases. Complements .squad/agents/{agent}/history.md and .squad/decisions.md. +license: MIT +version: 1.0.0-squad +domain: team-memory, learning +confidence: high +--- + +# Reflect Skill + +**Critical learning capture system** for Squad. Prevents repeating mistakes and preserves successful patterns across sessions. + +Analyze conversations and propose improvements to squad knowledge based on what worked, what didn't, and edge cases discovered. **Every correction is a learning opportunity.** + +--- + +## Integration with Squad Architecture + +**Reflect complements existing Squad knowledge systems:** + +1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates) +2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect +3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md + +**Workflow:** +- Use `reflect` during work to capture learnings +- At session end, review captured learnings +- Promote HIGH confidence patterns → lead agent for decision.md review +- Promote agent-specific patterns → `{agent}/history.md` updates + +--- + +## Triggers + +### 🔴 HIGH Priority (Invoke Immediately) + +| Trigger | Example | Why Critical | +|---------|---------|--------------| +| User correction | "no", "wrong", "not like that", "never do" | Captures mistakes to prevent repetition | +| Architectural insight | "you removed that without understanding why" | Documents design decisions (Chesterton's Fence) | +| Immediate fixes | "debug", "root cause", "fix all" | Learns from errors in real-time | + +### 🟡 MEDIUM Priority (Invoke After Multiple) + +| Trigger | Example | Why Important | +|---------|---------|---------------| +| User praise | "perfect", "exactly", "great" | Reinforces successful patterns | +| Tool preferences | "use X instead of Y", "prefer" | Builds workflow preferences | +| Edge cases | "what if X happens?", "don't forget", "ensure" | Captures scenarios to handle | + +### 🟢 LOW Priority (Invoke at Session End) + +| Trigger | Example | Why Useful | +|---------|---------|------------| +| Repeated patterns | Frequent use of specific commands/tools | Identifies workflow preferences | +| Session end | After complex work | Consolidates all session learnings | + +--- + +## Process + +### Phase 1: Identify Learning Target + +Determine what knowledge system should be updated: + +1. **Agent-specific learning** → `.squad/agents/{agent}/history.md` +2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md` +3. **Skill-specific improvement** → Document in session, recommend to skill owner + +### Phase 2: Analyze Conversation + +Scan for learning signals with confidence levels: + +#### HIGH Confidence: Corrections + +User actively steered or corrected output. + +**Detection patterns:** +- Explicit rejection: "no", "not like that", "that's wrong" +- Strong directives: "never do", "always do", "don't ever" +- User provided alternative implementation + +**Example:** +```text +User: "No, use the azure-devops MCP tool instead of raw API calls" +→ [HIGH] + Add constraint: "Prefer azure-devops MCP tools over REST API" +``` + +#### MEDIUM Confidence: Success Patterns + +Output was accepted or praised. + +**Detection patterns:** +- Explicit praise: "perfect", "great", "yes", "exactly" +- User built on output without modification +- Output was committed without changes + +**Example:** +```text +User: "Perfect, that's exactly what I needed" +→ [MED] + Add preference: "Include usage examples in documentation" +``` + +#### MEDIUM Confidence: Edge Cases + +Scenarios not anticipated. + +**Detection patterns:** +- Questions not answered +- Workarounds user had to apply +- Error handling gaps discovered + +#### LOW Confidence: Preferences + +Accumulated patterns over time. + +--- + +### Phase 3: Propose Learnings + +Present findings: + +```text +┌─────────────────────────────────────────────────────────────┐ +│ REFLECTION: {target (agent/decision/skill)} │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ [HIGH] + Add constraint: "{specific constraint}" │ +│ Source: "{quoted user correction}" │ +│ Target: .squad/decisions/inbox/{agent}-{topic}.md │ +│ │ +│ [MED] + Add preference: "{specific preference}" │ +│ Source: "{evidence from conversation}" │ +│ Target: .squad/agents/{agent}/history.md │ +│ │ +│ [LOW] ~ Note for review: "{observation}" │ +│ Source: "{pattern observed}" │ +│ Target: Session notes only │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ Apply changes? [Y/n/edit] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Confidence Threshold:** + +| Threshold | Action | +|-----------|--------| +| ≥1 HIGH signal | Always propose (user explicitly corrected) | +| ≥2 MED signals | Propose (sufficient pattern) | +| ≥3 LOW signals | Propose (accumulated evidence) | +| 1-2 LOW only | Skip (insufficient evidence) | + +### Phase 4: Persist Learnings + +**ALWAYS show changes before applying.** + +After user approval: + +1. **For Agent History:** + - Append to `.squad/agents/{agent}/history.md` under `## Learnings` section + - Format: Date, assignment context, key learning + +2. **For Team Decisions:** + - Create `.squad/decisions/inbox/{agent}-{topic}.md` + - Lead agent reviews and merges to `decisions.md` if appropriate + +3. **For Skills:** + - Document recommendation in session notes + - Squad lead reviews and routes to skill owner + +--- + +## Usage Examples + +### Example 1: User Correction + +**Conversation:** +``` +Agent: "I'll use grep to search the repository" +User: "No, use the code search tools first, grep is too slow" +``` + +**Reflection Output:** +``` +[HIGH] + Add constraint: "Use code intelligence tools before grep" + Source: "No, use the code search tools first, grep is too slow" + Target: .squad/agents/{agent}/history.md +``` + +### Example 2: Success Pattern + +**Conversation:** +``` +Agent: [Creates PR with detailed description and test plan] +User: "Perfect! This is exactly the format I want for all PRs" +``` + +**Reflection Output:** +``` +[MED] + Add preference: "Include test plan in PR descriptions" + Source: User praised detailed PR format + Target: .squad/decisions/inbox/pr-format.md (for team adoption) +``` + +--- + +## When to Use + +✅ **Use reflect when:** +- User says "no", "wrong", "not like that" (HIGH priority) +- User says "perfect", "exactly", "great" (MED priority) +- You discover edge cases or gaps +- Complex work session with multiple learnings +- At end of sprint/milestone to consolidate patterns + +❌ **Don't use reflect when:** +- Simple one-off questions with no pattern +- User is just exploring ideas (no concrete decisions) +- Learning is already captured in history.md/decisions.md + +--- + +## See Also + +- `.squad/decisions.md` — Team-wide decisions +- `.squad/agents/*/history.md` — Agent-specific learnings +- `.squad/routing.md` — Work assignment patterns diff --git a/templates/skills/release-process/SKILL.md b/templates/skills/release-process/SKILL.md new file mode 100644 index 000000000..868adb846 --- /dev/null +++ b/templates/skills/release-process/SKILL.md @@ -0,0 +1,237 @@ +--- +name: "release-process" +description: "Prepare, publish, recover, and verify Squad insider, preview, and stable releases" +domain: "release" +confidence: "high" +source: "earned" +--- + +# Release Process + +This is the canonical Squad release runbook. Squad has three release channels +and two long-lived branches: + +| Source | Version | GitHub | npm | Standalone | Homebrew/WinGet | +|--------|---------|--------|-----|------------|-----------------| +| Insider dispatch from `dev` | Generated `X.Y.Z-insider.N` | Prerelease | `insider` | Yes | Yes | +| Release dispatch from `dev` | `X.Y.Z-preview.N` | Prerelease | `preview` | Yes | Yes | +| Push to `main` by promotion workflow | `X.Y.Z` | Stable/latest | `latest` | Yes | Yes | + +The repository does not use a staging `preview` branch. Preview is a release +channel, not a branch. + +## Non-negotiable rules + +1. Never create release tags or GitHub Releases manually. `squad-release.yml` + creates both. +2. Never reuse a version. A preview such as `0.14.0-preview.1` and stable + `0.14.0` are separate immutable releases. +3. Keep the root, SDK, and CLI versions identical. +4. Set the CLI's SDK dependency floor to `>=VERSION`; prerelease workspaces do + not match an older stable range. +5. Add an exact `## [VERSION]` entry to `CHANGELOG.md`. +6. Merge release preparation to `dev` and wait for CI before dispatching. +7. Keep separate Homebrew casks and WinGet identifiers for each channel. + +## Required credentials + +Configure these GitHub Actions secrets: + +- `NPM_TOKEN`: an automation-capable npm publish token that does not require an + interactive OTP. +- `HOMEBREW_TAP_TOKEN`: a classic GitHub PAT with `public_repo`, owned by an + account that has write access to `bradygaster/homebrew-squad`. +- `WINGET_CREATE_GITHUB_TOKEN`: a classic GitHub PAT with `public_repo`, owned + by the account that maintains `tamirdresher/winget-pkgs`. + +## Prepare a release + +Verify `dev` and `main` share ancestry before changing versions: + +```bash +git fetch origin dev main +git merge-base origin/dev origin/main +``` + +If that command returns no commit, stop and repair ancestry in a separate PR. + +Choose a unique SemVer version and update all package manifests: + +```bash +VERSION=0.14.0-preview.1 +npm version "$VERSION" --workspaces --include-workspace-root --no-git-tag-version +npm pkg set "dependencies.@bradygaster/squad-sdk=>=$VERSION" \ + --workspace @bradygaster/squad-cli +npm install --package-lock-only +``` + +This updates the root package, both workspaces, and the lockfile. Confirm: + +```bash +node -p "require('semver').valid('$VERSION')" +grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json +grep -F "## [$VERSION]" CHANGELOG.md +npm run build +npx vitest run +``` + +Release preparation lands through a normal PR to `dev`. Do not push directly to +`main`. + +## Publish a preview release + +Preview versions must contain a prerelease suffix, for example +`0.14.0-preview.1`. + +After the release-preparation PR is merged and `dev` CI is green: + +```bash +VERSION=0.14.0-preview.1 +gh workflow run squad-release.yml \ + --ref dev \ + -f confirm_tag="v$VERSION" +gh run watch +``` + +The workflow: + +1. Requires the dispatch ref to be `dev`. +2. Rejects a stable `X.Y.Z` version. +3. Creates `v$VERSION` and a GitHub prerelease. +4. Publishes both npm packages with `--tag preview`. +5. Uploads six standalone archives and `SHA256SUMS.txt`. +6. Updates the `squad-preview` Homebrew cask and + `bradygaster.Squad.Preview` WinGet package. + +Install the resulting preview: + +```bash +npm install -g @bradygaster/squad-cli@preview +``` + +The same preview is available through `brew install --cask squad-preview` and +`winget install --id bradygaster.Squad.Preview --exact`. + +## Publish an insider release + +Start an on-demand snapshot from `dev`: + +```bash +gh workflow run squad-insider-publish.yml --ref dev -f dry_run=false +gh run watch +``` + +The workflow computes the next immutable `X.Y.Z-insider.N` version, publishes +npm `insider`, creates a GitHub prerelease, uploads standalone bundles, updates +the `squad-insider` Homebrew cask, and opens or reuses the +`bradygaster.Squad.Insider` WinGet PR. + +## Publish a stable release + +Stable versions must be exactly `X.Y.Z`. Prepare and merge the stable version +to `dev`, then optionally validate the sanitized merge without changing +`main`: + +```bash +gh workflow run squad-promote.yml --ref dev -f dry_run=true +gh run watch +``` + +Start the real promotion: + +```bash +gh workflow run squad-promote.yml --ref dev -f dry_run=false +gh run watch +``` + +`squad-promote.yml`: + +1. Merges `origin/dev` directly into `main`. +2. Removes `.ai-team/`, `.squad/`, `.ai-team-templates/`, `team-docs/`, and + `docs/proposals/` from the release tree. +3. Rejects unresolved conflicts, prerelease versions, mismatched package + versions, and missing changelog entries. +4. Installs dependencies, builds, and runs release tests. +5. Pushes `main` and explicitly dispatches `squad-release.yml`. + +The explicit dispatch is required because GitHub suppresses push-triggered +workflow runs for commits authenticated with `GITHUB_TOKEN`. The release +workflow creates the stable tag and GitHub Release, publishes npm `latest`, +uploads standalone archives, updates Homebrew, and opens or reuses the WinGet +PR. + +## Verify publication + +Use `insider`, `preview`, or `latest` for `DIST_TAG`: + +```bash +VERSION=0.14.0 +DIST_TAG=latest + +npm view @bradygaster/squad-sdk "dist-tags.$DIST_TAG" +npm view @bradygaster/squad-cli "dist-tags.$DIST_TAG" +gh release view "v$VERSION" +``` + +The npm values must equal `VERSION`. The GitHub Release must contain: + +```text +squad-linux-x64.tar.gz +squad-linux-arm64.tar.gz +squad-darwin-x64.tar.gz +squad-darwin-arm64.tar.gz +squad-win32-x64.zip +squad-win32-arm64.zip +SHA256SUMS.txt +``` + +For every release, also verify the channel's Homebrew cask (`squad`, +`squad-preview`, or `squad-insider`) and WinGet identifier +(`bradygaster.Squad`, `.Preview`, or `.Insider`) reference the new version. + +## Recovery + +The top-level release workflow intentionally does not republish after its tag +already exists. Rerun the failed child job, or dispatch the reusable workflow +from the branch that owns that release channel while building from the +immutable tag. + +Stable recovery: + +```bash +VERSION=0.14.0 +gh workflow run squad-npm-publish.yml --ref main \ + -f version="$VERSION" -f source_ref="v$VERSION" +gh workflow run squad-standalone-release.yml --ref main \ + -f upload=true -f release_tag="v$VERSION" -f source_ref="v$VERSION" +``` + +Preview recovery: + +```bash +VERSION=0.14.0-preview.1 +gh workflow run squad-npm-publish.yml --ref dev \ + -f version="$VERSION" -f source_ref="v$VERSION" +gh workflow run squad-standalone-release.yml --ref dev \ + -f upload=true -f release_tag="v$VERSION" -f source_ref="v$VERSION" +``` + +Publication is idempotent. Existing package versions and release assets are +verified rather than overwritten. npm publication fails instead of silently +moving `latest` or `preview` away from an existing version. + +## After a stable release + +Prepare the next development version in a normal PR to `dev`: + +```bash +NEXT_VERSION=0.15.0-preview.1 +npm version "$NEXT_VERSION" --workspaces --include-workspace-root --no-git-tag-version +npm pkg set "dependencies.@bradygaster/squad-sdk=>=$NEXT_VERSION" \ + --workspace @bradygaster/squad-cli +npm install --package-lock-only +``` + +Do not merge `main` back into `dev`; the promotion commit already has `dev` as +its parent, while the stripped internal state intentionally remains only on +`dev`. diff --git a/templates/skills/reskill/SKILL.md b/templates/skills/reskill/SKILL.md new file mode 100644 index 000000000..c9e6184de --- /dev/null +++ b/templates/skills/reskill/SKILL.md @@ -0,0 +1,92 @@ +--- +name: "reskill" +description: "Team-wide charter and history optimization through skill extraction" +domain: "team-optimization" +confidence: "high" +source: "manual — reduce per-agent context overhead" +--- + +## Context + +When the coordinator hears "team, reskill" (or similar: "optimize context", "slim down charters"), trigger a team-wide optimization pass. The goal: reduce per-agent context consumption by extracting shared patterns from charters and histories into reusable skills. + +This is a periodic maintenance activity. Run whenever charter/history bloat is suspected. + +## Process + +### Step 1: Audit +Read all agent charters and histories. Measure byte sizes. Identify: + +- **Boilerplate** — sections repeated across ≥3 charters with <10% variation (collaboration, model, boundaries template) +- **Shared knowledge** — domain knowledge duplicated in 2+ charters (incident postmortems, technical patterns) +- **Mature learnings** — history entries appearing 3+ times across agents that should be promoted to skills + +### Step 2: Extract +For each identified pattern: +1. Create or update a skill at `.squad/skills/{skill-name}/SKILL.md` +2. Follow the skill template format (frontmatter + Context + Patterns + Examples + Anti-Patterns) +3. Set confidence: low (first observation), medium (2+ agents), high (team-wide) + +### Step 3: Trim +**Charters** — target ≤1.5KB per agent: +- Remove Collaboration section entirely (spawn prompt + agent-collaboration skill covers it) +- Remove Voice section (tagline blockquote at top of charter already captures it) +- Trim Model section to single line: `Preferred: {model}` +- Remove "When I'm unsure" boilerplate from Boundaries +- Remove domain knowledge now covered by a skill — add skill reference comment if helpful +- Keep: Identity, What I Own, unique How I Work patterns, Boundaries (domain list only) + +**Histories** — target ≤8KB per agent: +- Apply history-hygiene skill to any history >12KB +- Promote recurring patterns (3+ occurrences across agents) to skills +- Summarize old entries into `## Core Context` section +- Remove session-specific metadata (dates, branch names, requester names) + +### Step 4: Report +Output a savings table: + +| Agent | Charter Before | Charter After | History Before | History After | Saved | +|-------|---------------|---------------|----------------|---------------|-------| + +Include totals and percentage reduction. + +## Patterns + +### Minimal Charter Template (target format after reskill) + +``` +# {Name} — {Role} + +> {Tagline — one sentence capturing voice and philosophy} + +## Identity +- **Name:** {Name} +- **Role:** {Role} +- **Expertise:** {comma-separated list} + +## What I Own +- {bullet list of owned artifacts/domains} + +## How I Work +- {unique patterns and principles — NOT boilerplate} + +## Boundaries +**I handle:** {domain list} +**I don't handle:** {explicit exclusions} + +## Model +Preferred: {model} +``` + +### Skill Extraction Threshold +- **1 charter** → leave in charter (unique to that agent) +- **2 charters** → consider extracting if >500 bytes of overlap +- **3+ charters** → always extract to a shared skill + +## Anti-Patterns +- Don't delete unique per-agent identity or domain-specific knowledge +- Don't create skills for content only one agent uses +- Don't merge unrelated patterns into a single mega-skill +- Don't remove Model preference line (coordinator needs it for model selection) +- Don't touch `.squad/decisions.md` during reskill +- Don't remove the tagline blockquote — it's the charter's soul in one line diff --git a/templates/skills/retro-enforcement/SKILL.md b/templates/skills/retro-enforcement/SKILL.md new file mode 100644 index 000000000..e7d319276 --- /dev/null +++ b/templates/skills/retro-enforcement/SKILL.md @@ -0,0 +1,148 @@ +# Skill: Retro Enforcement + +## Purpose + +Ensure retrospectives happen on schedule and that their action items are tracked in GitHub Issues — not markdown checklists. + +This skill addresses a specific, measured failure mode: **0% completion rate on markdown retro action items across 6 consecutive retrospectives**. GitHub Issues have an 85%+ completion rate in the same squad. The format was the problem, not the people. + +## Core Function: Test-RetroOverdue + +```powershell +function Test-RetroOverdue { + param( + [string]$LogDir = ".squad/log", + [int]$WindowDays = 7, + [string]$Pattern = "*retrospective*" + ) + + $cutoff = (Get-Date).AddDays(-$WindowDays) + + $retroLogs = Get-ChildItem -Path $LogDir -Filter $Pattern -ErrorAction SilentlyContinue | + Where-Object { $_.LastWriteTime -ge $cutoff } + + return ($retroLogs.Count -eq 0) +} +``` + +### Returns +- `$true` — No retro log found within the window. **Retro is overdue. Block other work.** +- `$false` — At least one retro log found within the window. Proceed normally. + +### Detection Logic + +The function checks `.squad/log/` for any file matching `*retrospective*` dated within the last `$WindowDays` days (default: 7). If none is found, the retro is overdue. + +**File naming convention:** `.squad/log/{ISO8601-timestamp}-retrospective.md` + +Example: `.squad/log/2026-03-24T14-45-00Z-retrospective.md` + +## Coordinator Integration + +Call `Test-RetroOverdue` **at the start of every round**, before building the work queue. + +```powershell +# At round start — before any work queue construction +if (Test-RetroOverdue -LogDir ".squad/log" -WindowDays 7) { + Write-Host "[RETROSPECTIVE] Retrospective overdue. Running before other work." + + # Spawn retro facilitator + Invoke-RetroSession -Mode "catch-up" + + # Wait for retro log to be written + # Then resume normal round +} + +# Proceed with normal work queue +$workQueue = Get-PendingIssues | Sort-Object -Property Priority +``` + +### Blocking Semantics + +When `Test-RetroOverdue` returns `$true`: + +1. **Do not start any other work** until the retro completes +2. **Spawn the facilitator agent** (Scribe or designated) with retro mode +3. **Wait for the log file** to be written to `.squad/log/` +4. **Verify action items** were created as GitHub Issues (not markdown) +5. **Resume normal round** after retro log confirmed + +## Action Item Enforcement + +Every retro action item MUST become a GitHub Issue. The facilitator agent is responsible for this. The coordinator verifies. + +### Verification Check + +```powershell +function Test-RetroActionItemsCreated { + param([string]$RetroLogPath) + + $content = Get-Content $RetroLogPath -Raw + + # Check for Issue references (e.g., #1478, https://github.com/.../issues/1478) + $issueRefs = [regex]::Matches($content, '(?:#\d{3,}|issues/\d{3,})') + + # Check for unclosed markdown checkboxes (bad pattern) + $openCheckboxes = [regex]::Matches($content, '- \[ \]') + + if ($openCheckboxes.Count -gt 0) { + Write-Warning "[RETROSPECTIVE] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues" + return $false + } + + return ($issueRefs.Count -gt 0) +} +``` + +### Why Not Markdown Checklists + +From production data in tamirdresher/tamresearch1: + +| Retro | Action Items Format | Completion | +|-------|---------------------|------------| +| 2025-12-05 | Markdown `- [ ]` | 0/4 = **0%** | +| 2025-12-19 | Markdown `- [ ]` | 0/3 = **0%** | +| 2026-01-09 | Markdown `- [ ]` | 0/5 = **0%** | +| 2026-01-23 | Markdown `- [ ]` | 0/4 = **0%** | +| 2026-02-07 | Markdown `- [ ]` | 0/3 = **0%** | +| 2026-02-21 | Markdown `- [ ]` | 0/4 = **0%** | +| 2026-03-24 | GitHub Issues | 4/4 = **100%** (after enforcement) | + +**Root cause:** Markdown checklists have no assignee, no notifications, no close event, and no query surface. They are invisible to every workflow that drives completion. + +## Cadence Enforcement + +### Recommended schedule +- Weekly squads: window = 7 days +- Bi-weekly squads: window = 14 days + +### Ralph integration example + +```powershell +# ralph-watch.ps1 — round start hook +function Invoke-RoundStart { + # 1. Always check retro first + if (Test-RetroOverdue -LogDir "$RepoRoot/.squad/log" -WindowDays 7) { + Write-Host "[RALPH] Retro overdue — enforcing before work queue" + Invoke-RetroSession + return # Re-enter round after retro completes + } + + # 2. Normal work queue + $issues = Get-ReadyIssues + foreach ($issue in $issues) { + Invoke-WorkItem -Issue $issue + } +} +``` + +## Skill Metadata + +| Field | Value | +|-------|-------| +| **Skill ID** | `retro-enforcement` | +| **Category** | Ceremonies / Process | +| **Trigger** | Coordinator round start | +| **Dependencies** | `.squad/log/` directory, GitHub Issues API | +| **Tested in** | tamirdresher/tamresearch1 (production, March 2026) | +| **Outcome** | Retro cadence restored; action item completion 0% → 100% | diff --git a/templates/skills/reviewer-protocol/SKILL.md b/templates/skills/reviewer-protocol/SKILL.md new file mode 100644 index 000000000..1f8e98430 --- /dev/null +++ b/templates/skills/reviewer-protocol/SKILL.md @@ -0,0 +1,79 @@ +--- +name: "reviewer-protocol" +description: "Reviewer rejection workflow and strict lockout semantics" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +When a team member has a **Reviewer** role (e.g., Tester, Code Reviewer, Lead), they may approve or reject work from other agents. On rejection, the coordinator enforces strict lockout rules to ensure the original author does NOT self-revise. This prevents defensive feedback loops and ensures independent review. + +## Patterns + +### Reviewer Rejection Protocol + +When a team member has a **Reviewer** role: + +- Reviewers may **approve** or **reject** work from other agents. +- On **rejection**, the Reviewer may choose ONE of: + 1. **Reassign:** Require a *different* agent to do the revision (not the original author). + 2. **Escalate:** Require a *new* agent be spawned with specific expertise. +- The Coordinator MUST enforce this. If the Reviewer says "someone else should fix this," the original agent does NOT get to self-revise. +- If the Reviewer approves, work proceeds normally. + +### Strict Lockout Semantics + +When an artifact is **rejected** by a Reviewer: + +1. **The original author is locked out.** They may NOT produce the next version of that artifact. No exceptions. +2. **A different agent MUST own the revision.** The Coordinator selects the revision author based on the Reviewer's recommendation (reassign or escalate). +3. **The Coordinator enforces this mechanically.** Before spawning a revision agent, the Coordinator MUST verify that the selected agent is NOT the original author. If the Reviewer names the original author as the fix agent, the Coordinator MUST refuse and ask the Reviewer to name a different agent. +4. **The locked-out author may NOT contribute to the revision** in any form — not as a co-author, advisor, or pair. The revision must be independently produced. +5. **Lockout scope:** The lockout applies to the specific artifact that was rejected. The original author may still work on other unrelated artifacts. +6. **Lockout duration:** The lockout persists for that revision cycle. If the revision is also rejected, the same rule applies again — the revision author is now also locked out, and a third agent must revise. +7. **Deadlock handling:** If all eligible agents have been locked out of an artifact, the Coordinator MUST escalate to the user rather than re-admitting a locked-out author. + +## Examples + +**Example 1: Reassign after rejection** +1. Runtime Engineer writes authentication module +2. Quality Engineer reviews → rejects: "Error handling is missing. Another engineer should fix this." +3. Coordinator: Runtime Engineer is now locked out of this artifact +4. Coordinator spawns a different engineer to revise the authentication module +5. The revision engineer produces v2 +6. Quality Engineer reviews v2 → approves +7. Lockout clears for next artifact + +**Example 2: Escalate for expertise** +1. Original Author writes TypeScript config +2. Lead reviews → rejects: "Need someone with deeper TS knowledge. Escalate." +3. Coordinator: Original Author is now locked out +4. Coordinator spawns new agent (or existing TS expert) to revise +5. New agent produces v2 +6. Lead reviews v2 + +**Example 3: Deadlock handling** +1. Original Author writes module → rejected +2. Revision Engineer revises → rejected +3. Quality Engineer revises → rejected +4. All 3 eligible agents are now locked out +5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]" + +**Example 4: Reviewer accidentally names original author** +1. Original Author writes module → rejected +2. Quality Engineer says: "The original author should fix the error handling" +3. Coordinator: "The original author is locked out. Please name a different agent." +4. Quality Engineer names a revision engineer +5. Coordinator spawns the revision engineer + +## Anti-Patterns + +- ❌ Allowing the original author to self-revise after rejection +- ❌ Treating the locked-out author as an "advisor" or "co-author" on the revision +- ❌ Re-admitting a locked-out author when deadlock occurs (must escalate to user) +- ❌ Applying lockout across unrelated artifacts (scope is per-artifact) +- ❌ Accepting the Reviewer's assignment when they name the original author (must refuse and ask for a different agent) +- ❌ Clearing lockout before the revision is approved (lockout persists through revision cycle) +- ❌ Skipping verification that the revision agent is not the original author diff --git a/templates/skills/rework-rate/SKILL.md b/templates/skills/rework-rate/SKILL.md deleted file mode 100644 index 2a80cf46e..000000000 --- a/templates/skills/rework-rate/SKILL.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -name: "rework-rate" -description: "Measure and interpret PR rework rate — the emerging 5th DORA metric" -domain: "metrics, code-review, quality" -confidence: "high" -source: "manual" -tools: - - name: "squad rework" - description: "Analyze PR rework rate from merged PRs" - when: "When measuring code quality, review efficiency, or team health metrics" ---- - -## Context - -Rework Rate measures the percentage of code changes that require revision after initial review submission. It is considered the emerging 5th DORA metric alongside Deployment Frequency, Lead Time for Changes, Mean Time to Recovery, and Change Failure Rate. - -Use this skill when: -- Measuring team code review efficiency -- Identifying patterns in PR revision cycles -- Coaching on PR quality and review practices -- Tracking AI-generated code retention rates -- Building engineering health dashboards - -## Patterns - -### Calculation - -``` -Rework Rate = (commits after first review) / (total commits) × 100 - -Sub-metrics: - Review Cycles = number of changes-requested → push → approval loops - Rejection Rate = PRs with ≥1 "changes requested" / total PRs × 100 - Rework Time = last approval timestamp - first changes-requested timestamp -``` - -### Healthy Ranges - -| Metric | 🟢 Healthy | 🟡 Moderate | 🔴 Needs Attention | -|--------|-----------|------------|-------------------| -| Rework Rate | ≤15% | 15–30% | >30% | -| Review Cycles | ≤1.0 | 1.0–2.0 | >2.0 | -| Rejection Rate | ≤20% | 20–40% | >40% | - -### Using the CLI - -```bash -# Analyze last 30 days (default) -npx github:bradygaster/squad rework - -# Custom period -npx github:bradygaster/squad rework --days 7 --limit 50 - -# Machine-readable output -npx github:bradygaster/squad rework --json -``` - -### Improvement Strategies - -When rework rate is high: -1. **Smaller PRs** — Break large changes into focused, reviewable units -2. **Clear specs** — Write acceptance criteria before coding -3. **Pre-review checklist** — Self-review before requesting reviews -4. **Pair reviews** — Complex changes benefit from synchronous review -5. **Draft PRs** — Use draft status for early feedback on direction - -## Examples - -```javascript -// Ralph can use rework metrics in watch cycles: -// "📊 Weekly Rework Rate: 12% (healthy) — 3/25 PRs had changes requested" - -// In squad ceremonies, rework trends inform retrospectives: -// "Rework rate dropped from 28% to 14% after adopting smaller PR sizes" -``` - -## Anti-Patterns - -- **Using rework rate to blame individuals** — Use it for team coaching, not performance reviews -- **Optimizing for zero rework** — Some rework is healthy; it means reviews are catching issues -- **Ignoring context** — Large refactors naturally have higher rework; compare like with like -- **Measuring without acting** — Metrics without follow-up actions are waste diff --git a/templates/skills/secret-handling/SKILL.md b/templates/skills/secret-handling/SKILL.md new file mode 100644 index 000000000..b0576f879 --- /dev/null +++ b/templates/skills/secret-handling/SKILL.md @@ -0,0 +1,200 @@ +--- +name: secret-handling +description: Never read .env files or write secrets to .squad/ committed files +domain: security, file-operations, team-collaboration +confidence: high +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. + +## Patterns + +### Prohibited File Reads + +**NEVER read these files:** +- `.env` (production secrets) +- `.env.local` (local dev secrets) +- `.env.production` (production environment) +- `.env.development` (development environment) +- `.env.staging` (staging environment) +- `.env.test` (test environment with real credentials) +- Any file matching `.env.*` UNLESS explicitly allowed (see below) + +**Allowed alternatives:** +- `.env.example` (safe — contains placeholder values, no real secrets) +- `.env.sample` (safe — documentation template) +- `.env.template` (safe — schema/structure reference) + +**If you need config info:** +1. **Ask the user directly** — "What's the database connection string?" +2. **Read `.env.example`** — shows structure without exposing secrets +3. **Read documentation** — check `README.md`, `docs/`, config guides + +**NEVER assume you can "just peek at .env to understand the schema."** Use `.env.example` or ask. + +### Prohibited Output Patterns + +**NEVER write these to `.squad/` files:** + +| Pattern Type | Examples | Regex Pattern (for scanning) | +|--------------|----------|-------------------------------| +| API Keys | `OPENAI_API_KEY=sk-proj-...`, `GITHUB_TOKEN=ghp_...` | `[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+` | +| Passwords | `DB_PASSWORD=super_secret_123`, `password: "..."` | `(?:PASSWORD|PASS|PWD)[:=]\s*["']?[^\s"']+` | +| Connection Strings | `postgres://user:pass@host:5432/db`, `Server=...;Password=...` | `(?:postgres|mysql|mongodb)://[^@]+@|(?:Server|Host)=.*(?:Password|Pwd)=` | +| JWT Tokens | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` | `eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+` | +| Private Keys | `-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` | `-----BEGIN [A-Z ]+PRIVATE KEY-----` | +| AWS Credentials | `AKIA...`, `aws_secret_access_key=...` | `AKIA[0-9A-Z]{16}|aws_secret_access_key=[^\s]+` | +| Email Addresses | `user@example.com` (PII violation per team decision) | `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` | + +**What to write instead:** +- Placeholder values: `DATABASE_URL=` +- Redacted references: `API key configured (see .env.example)` +- Architecture notes: "App uses JWT auth — token stored in session" +- Schema documentation: "Requires OPENAI_API_KEY, GITHUB_TOKEN (see .env.example for format)" + +### Scribe Pre-Commit Validation + +**Before committing `.squad/` changes, Scribe 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) +3. **If secrets detected:** + - STOP the commit (do NOT proceed) + - Remove the file from staging: `git reset HEAD ` + - Report to user: + ``` + 🚨 SECRET DETECTED — commit blocked + + File: .squad/decisions/inbox/river-db-config.md + Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod + + This file contains credentials and MUST NOT be committed. + Please remove the secret, replace with placeholder, and try again. + ``` + - Exit with error (never silently skip) + +4. **If no secrets detected:** + - Proceed with commit as normal + +**Implementation note for Scribe:** +- Run validation AFTER staging files, BEFORE calling `git commit` +- Use PowerShell `Select-String` or `git diff --cached` to scan staged content +- Fail loud — secret leaks are unacceptable, blocking the commit is correct behavior + +### Remediation — If a Secret Was Already Committed + +**If you discover a secret in git history:** + +1. **STOP immediately** — do not make more commits +2. **Alert the user:** + ``` + 🚨 CREDENTIAL LEAK DETECTED + + A secret was found in git history: + Commit: abc1234 + File: .squad/decisions/inbox/agent-config.md + Pattern: API_KEY=sk-proj-... + + This requires immediate remediation: + 1. Revoke the exposed credential (regenerate API key, rotate password) + 2. Remove from git history (git filter-repo or BFG) + 3. Force-push the cleaned history + + Do NOT proceed with new work until this is resolved. + ``` +3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools +4. **Wait for user confirmation** before resuming work + +## Examples + +### ✓ Correct: Reading Config Schema + +**Agent needs to know what environment variables are required:** + +``` +Agent: "What environment variables does this app need?" +→ Reads `.env.example`: + OPENAI_API_KEY=sk-... + DATABASE_URL=postgres://user:pass@localhost:5432/db + REDIS_URL=redis://localhost:6379 + +→ Writes to .squad/decisions/inbox/river-env-setup.md: + "App requires three environment variables: + - OPENAI_API_KEY (OpenAI API key, format: sk-...) + - DATABASE_URL (Postgres connection string) + - REDIS_URL (Redis connection string) + See .env.example for full schema." +``` + +### ✗ Incorrect: Reading Live Credentials + +**Agent needs to know database schema:** + +``` +Agent: (reads .env) + DATABASE_URL=postgres://admin:super_secret_pw@prod.example.com:5432/appdb + +→ Writes to .squad/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 +``` + +**Correct approach:** +``` +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: + "Database: Postgres (connection configured in .env). Schema defined in db/migrations/." +``` + +### ✓ Correct: Scribe Pre-Commit Validation + +**Scribe is about to commit:** + +```powershell +# Stage files +git add .squad/ + +# Scan staged content for secrets +$stagedContent = git diff --cached +$secretPatterns = @( + '[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+', + '(?:PASSWORD|PASS|PWD)[:=]\s*["'']?[^\s"'']+', + 'eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+' +) + +$detected = $false +foreach ($pattern in $secretPatterns) { + if ($stagedContent -match $pattern) { + $detected = $true + Write-Host "🚨 SECRET DETECTED: $($matches[0])" + break + } +} + +if ($detected) { + # Remove from staging, report, exit + git reset HEAD .squad/ + Write-Error "Commit blocked — secret detected in staged files" + exit 1 +} + +# Safe to commit +git commit -F $msgFile +``` + +## Anti-Patterns + +- ❌ Reading `.env` "just to check the schema" — use `.env.example` instead +- ❌ Writing "sanitized" connection strings that still contain credentials +- ❌ Assuming "it's just a dev environment" makes secrets safe to commit +- ❌ 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 +- ❌ Extracting "just the host" from a connection string — still leaks infrastructure topology diff --git a/templates/skills/session-recovery/SKILL.md b/templates/skills/session-recovery/SKILL.md new file mode 100644 index 000000000..05cfbae60 --- /dev/null +++ b/templates/skills/session-recovery/SKILL.md @@ -0,0 +1,155 @@ +--- +name: "session-recovery" +description: "Find and resume interrupted Copilot CLI sessions using session_store queries" +domain: "workflow-recovery" +confidence: "high" +source: "earned" +tools: + - name: "sql" + description: "Query session_store database for past session history" + when: "Always — session_store is the source of truth for session history" +--- + +## Context + +Squad agents run in Copilot CLI sessions that can be interrupted — terminal crashes, network drops, machine restarts, or accidental window closes. When this happens, in-progress work may be left in a partially-completed state: branches with uncommitted changes, issues marked in-progress with no active agent, or checkpoints that were never finalized. + +Copilot CLI stores session history in a SQLite database called `session_store` (read-only, accessed via the `sql` tool with `database: "session_store"`). This skill teaches agents how to query that store to detect interrupted sessions and resume work. + +## Patterns + +### 1. Find Recent Sessions + +Query the `sessions` table filtered by time window. Include the last checkpoint to understand where the session stopped: + +```sql +SELECT + s.id, + s.summary, + s.cwd, + s.branch, + s.updated_at, + (SELECT title FROM checkpoints + WHERE session_id = s.id + ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint +FROM sessions s +WHERE s.updated_at >= datetime('now', '-24 hours') +ORDER BY s.updated_at DESC; +``` + +### 2. Filter Out Automated Sessions + +Automated agents (monitors, keep-alive, heartbeat) create high-volume sessions that obscure human-initiated work. Exclude them: + +```sql +SELECT s.id, s.summary, s.cwd, s.updated_at, + (SELECT title FROM checkpoints + WHERE session_id = s.id + ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint +FROM sessions s +WHERE s.updated_at >= datetime('now', '-24 hours') + AND s.id NOT IN ( + SELECT DISTINCT t.session_id FROM turns t + WHERE t.turn_index = 0 + AND (LOWER(t.user_message) LIKE '%keep-alive%' + OR LOWER(t.user_message) LIKE '%heartbeat%') + ) +ORDER BY s.updated_at DESC; +``` + +### 3. Search by Topic (FTS5) + +Use the `search_index` FTS5 table for keyword search. Expand queries with synonyms since this is keyword-based, not semantic: + +```sql +SELECT DISTINCT s.id, s.summary, s.cwd, s.updated_at +FROM search_index si +JOIN sessions s ON si.session_id = s.id +WHERE search_index MATCH 'auth OR login OR token OR JWT' + AND s.updated_at >= datetime('now', '-48 hours') +ORDER BY s.updated_at DESC +LIMIT 10; +``` + +### 4. Search by Working Directory + +```sql +SELECT s.id, s.summary, s.updated_at, + (SELECT title FROM checkpoints + WHERE session_id = s.id + ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint +FROM sessions s +WHERE s.cwd LIKE '%my-project%' + AND s.updated_at >= datetime('now', '-48 hours') +ORDER BY s.updated_at DESC; +``` + +### 5. Get Full Session Context Before Resuming + +Before resuming, inspect what the session was doing: + +```sql +-- Conversation turns +SELECT turn_index, substr(user_message, 1, 200) AS ask, timestamp +FROM turns WHERE session_id = 'SESSION_ID' ORDER BY turn_index; + +-- Checkpoint progress +SELECT checkpoint_number, title, overview +FROM checkpoints WHERE session_id = 'SESSION_ID' ORDER BY checkpoint_number; + +-- Files touched +SELECT file_path, tool_name +FROM session_files WHERE session_id = 'SESSION_ID'; + +-- Linked PRs/issues/commits +SELECT ref_type, ref_value +FROM session_refs WHERE session_id = 'SESSION_ID'; +``` + +### 6. Detect Orphaned Issue Work + +Find sessions that were working on issues but may not have completed: + +```sql +SELECT DISTINCT s.id, s.branch, s.summary, s.updated_at, + sr.ref_type, sr.ref_value +FROM sessions s +JOIN session_refs sr ON s.id = sr.session_id +WHERE sr.ref_type = 'issue' + AND s.updated_at >= datetime('now', '-48 hours') +ORDER BY s.updated_at DESC; +``` + +Cross-reference with `gh issue list --label "status:in-progress"` to find issues that are marked in-progress but have no active session. + +### 7. Resume a Session + +Once you have the session ID: + +```bash +# Resume directly +copilot --resume SESSION_ID +``` + +## Examples + +**Recovering from a crash during PR creation:** +1. Query recent sessions filtered by branch name +2. Find the session that was working on the PR +3. Check its last checkpoint — was the code committed? Was the PR created? +4. Resume or manually complete the remaining steps + +**Finding yesterday's work on a feature:** +1. Use FTS5 search with feature keywords +2. Filter to the relevant working directory +3. Review checkpoint progress to see how far the session got +4. Resume if work remains, or start fresh with the context + +## Anti-Patterns + +- ❌ Searching by partial session IDs — always use full UUIDs +- ❌ Resuming sessions that completed successfully — they have no pending work +- ❌ Using `MATCH` with special characters without escaping — wrap paths in double quotes +- ❌ Skipping the automated-session filter — high-volume automated sessions will flood results +- ❌ Assuming FTS5 is semantic search — it's keyword-based; always expand queries with synonyms +- ❌ Ignoring checkpoint data — checkpoints show exactly where the session stopped diff --git a/templates/skills/squad-commands/SKILL.md b/templates/skills/squad-commands/SKILL.md new file mode 100644 index 000000000..652786a00 --- /dev/null +++ b/templates/skills/squad-commands/SKILL.md @@ -0,0 +1,303 @@ +--- +name: squad-commands +description: > + Categorized catalog of common Squad operations. Coordinator reads this + file and presents it as an interactive menu when the user asks for + available commands or help. +domain: squad-operations +confidence: high +source: first-party +triggers: ["squad commands", "what can squad do", "show me squad options", "slash commands"] +--- + +## Menu Presentation Rules + +When the user triggers this skill ("squad commands", "help", "what can squad do", etc.): + +1. **Category-level menu first.** Present category names as an `ask_user` choice list: + ``` + 📋 Squad Commands — pick a category: + 1. Install & Upgrade + 2. Team Management + 3. Issues & PRs + 4. Plugins & Skills + 5. Model & Cost + 6. Sessions & State + ``` +2. **Drill-down.** After selection, show operation titles in that category as a second `ask_user` list. +3. **Direct match skips the menu.** If the user says "how do I upgrade with state backend," match to the specific entry and go straight to argument collection. +4. **Compact fallback.** If `ask_user` is unavailable, render as a markdown table instead. +5. **Back / Cancel.** Include "← Back to categories" in sub-menus. Include "Cancel" in confirmation prompts. Respect "never mind" / "cancel" at any point. + +**Argument collection:** For entries with `args`, iterate the list sequentially. Use `ask_user` with choices when `choices` is provided; free-text prompt otherwise. If the user says "just do it" or "defaults are fine," skip remaining args and use their defaults. + +**Confirmation template:** +``` +⚠️ This will {action-description}. +{what will change} +Proceed? (yes / no) +``` + +--- + +## Install & Upgrade + +### Upgrade Squad CLI + +- **intent:** upgrade squad, update squad, install latest version, get new version +- **summary:** Upgrade Squad CLI to the latest version for your channel +- **action:** shell +- **command:** squad upgrade +- **args:** + - `state-backend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** false +- **platform_caveats:** Requires terminal. In VS Code, open the integrated terminal and run the command directly. + +### Initialize Squad + +- **intent:** set up squad, initialize squad, create team, start squad in this project +- **summary:** Scaffold Squad in the current directory (idempotent) +- **action:** shell +- **command:** squad init +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires terminal. Recommend a standalone terminal for best results. + +### Switch State Backend + +- **intent:** switch state backend, change state storage, use git-notes, use orphan branch +- **summary:** Change where Squad stores mutable state (config.json) +- **action:** file-edit +- **command:** .squad/config.json → stateBackend +- **args:** + - `stateBackend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** true +- **platform_caveats:** May require migration if switching away from worktree. Show current value and new value before confirming. + +--- + +## Team Management + +### Add Team Member + +- **intent:** add team member, hire agent, add agent, add developer, recruit +- **summary:** Add a new agent to the team roster +- **action:** coordinator +- **command:** Add Team Member flow (Init Mode / Team Mode) +- **args:** + - `role`: What role should this agent fill? (e.g., Frontend Dev, Backend Dev, QA Engineer) + - `name`: Preferred name or casting universe? | default: (auto-cast from active universe) +- **confirm:** false + +### Remove Team Member + +- **intent:** remove team member, fire agent, delete agent, remove developer +- **summary:** Remove an agent and delete their charter and history files +- **action:** coordinator +- **command:** Remove Team Member flow +- **args:** + - `member`: Which team member to remove? (name or role) +- **confirm:** true + +### Reassign Roles + +- **intent:** reassign role, change role, swap roles, update team member role +- **summary:** Update a team member's role in team.md and their charter +- **action:** coordinator +- **command:** Update team.md roster + charter.md +- **args:** + - `member`: Which team member? + - `newRole`: New role? +- **confirm:** false + +### Show Roster + +- **intent:** show roster, who is on the team, list team members, show team, capability profile +- **summary:** Display the current team roster and capability profile +- **action:** coordinator +- **command:** Direct Mode — read team.md, answer +- **args:** (none) +- **confirm:** false + +--- + +## Issues & PRs + +### Connect GitHub Repo + +- **intent:** connect github, enable issues, set up issues, link repository, github issues mode +- **summary:** Connect this project to GitHub Issues via gh auth +- **action:** coordinator +- **command:** GitHub Issues Mode (connection flow) +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires `gh auth login` to have been run in the terminal. + +### Triage Issues + +- **intent:** triage issues, review issues, assign issues, label issues +- **summary:** Run the Lead triage flow on open GitHub issues +- **action:** coordinator +- **command:** GitHub Issues Mode → Lead triage +- **args:** (none) +- **confirm:** false + +### Activate Ralph + +- **intent:** activate ralph, start ralph, ralph go, start work monitor, start auto-work +- **summary:** Activate Ralph — Work Monitor — to pick up and run queued issues +- **action:** coordinator +- **command:** Ralph — Work Monitor triggers +- **args:** (none) +- **confirm:** false + +### Set Ralph Polling Interval + +- **intent:** set ralph interval, change ralph timing, how often does ralph check, ralph every N minutes +- **summary:** Tell Ralph how frequently to poll for new work +- **action:** coordinator +- **command:** Ralph trigger: "Ralph, check every N minutes" +- **args:** + - `interval`: How often should Ralph poll? (in minutes) | default: 10 +- **confirm:** false + +### Start Squad Watch + +- **intent:** start watch, squad watch, monitor issues, watch for issues, auto-triage +- **summary:** Start squad watch to continuously poll and triage issues +- **action:** shell +- **command:** squad watch +- **args:** + - `interval`: Poll interval in minutes | default: 10 +- **confirm:** false +- **platform_caveats:** CLI-only — long-running foreground process. Not viable in VS Code without an integrated terminal. Run: `squad watch --interval {n}` in your terminal. + +--- + +## Plugins & Skills + +### Browse Plugin Marketplace + +- **intent:** browse plugins, explore plugins, what plugins are available, plugin marketplace +- **summary:** Browse available plugins in the Squad marketplace +- **action:** shell +- **command:** squad plugin marketplace browse +- **args:** + - `name`: Plugin name to search for | default: (browse all) +- **confirm:** false + +### Add Marketplace Plugin + +- **intent:** add plugin, install plugin, get plugin from marketplace +- **summary:** Add a plugin from the marketplace to this Squad +- **action:** shell +- **command:** squad plugin marketplace add +- **args:** + - `plugin`: Plugin owner/repo (e.g., owner/plugin-name) +- **confirm:** false + +### Remove Marketplace Plugin + +- **intent:** remove plugin, uninstall plugin, delete plugin +- **summary:** Remove an installed marketplace plugin +- **action:** shell +- **command:** squad plugin marketplace remove +- **args:** + - `name`: Plugin name to remove +- **confirm:** true + +### List Marketplace Plugins + +- **intent:** list plugins, show installed plugins, what plugins do I have +- **summary:** List all plugins registered in this Squad +- **action:** shell +- **command:** squad plugin marketplace list +- **args:** (none) +- **confirm:** false + +### List Installed Skills + +- **intent:** list skills, show skills, what skills are installed, skill catalog +- **summary:** List all skills installed in .squad/skills/ and .copilot/skills/ +- **action:** coordinator +- **command:** Direct Mode — list .squad/skills/ and .copilot/skills/ directories +- **args:** (none) +- **confirm:** false + +--- + +## Model & Cost + +### Set Default Model + +- **intent:** set default model, change model, use gpt, use claude, switch model +- **summary:** Set the default model for all agents in config.json +- **action:** file-edit +- **command:** .squad/config.json → defaultModel +- **args:** + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5, gpt-5.3-codex) +- **confirm:** false + +### Override Per-Agent Model + +- **intent:** set model for agent, agent model override, use different model for one agent +- **summary:** Set a model override for a specific agent in config.json +- **action:** file-edit +- **command:** .squad/config.json → agentModelOverrides.{agentName} +- **args:** + - `agent`: Agent name (must match name in team.md) + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5) +- **confirm:** false + +### Clear Model Preference + +- **intent:** clear model, reset model, remove model preference, use default model +- **summary:** Remove a model override from config.json (reverts to system default) +- **action:** file-edit +- **command:** .squad/config.json → remove defaultModel or agentModelOverrides.{agentName} +- **args:** + - `scope`: Clear default or a specific agent? | choices: {default model, specific agent} | default: default model + - `agent`: Agent name (only if scope = specific agent) +- **confirm:** false + +--- + +## Sessions & State + +### Catch-Up Summary + +- **intent:** catch me up, what happened, status, what did the team do, session summary +- **summary:** Summarize recent agent activity and key decisions +- **action:** coordinator +- **command:** Session catch-up flow (lazy scan) +- **args:** (none) +- **confirm:** false + +### Show Recent Decisions + +- **intent:** show decisions, recent decisions, what decisions were made, decision log +- **summary:** Display recent entries from .squad/decisions.md +- **action:** coordinator +- **command:** Direct Mode — read decisions.md, answer +- **args:** (none) +- **confirm:** false + +### Archive Old Decisions + +- **intent:** archive decisions, clean up decisions, move old decisions, compact decisions +- **summary:** Move old decisions from decisions.md to decisions-archive.md +- **action:** coordinator +- **command:** Move entries older than threshold from .squad/decisions.md → .squad/decisions-archive.md +- **args:** + - `olderThan`: Archive decisions older than how many days? | default: 30 +- **confirm:** true + +### Summarize Agent History + +- **intent:** summarize history, what did agent do, agent history, compress history +- **summary:** Spawn an agent to summarize and compress a team member's history file +- **action:** coordinator +- **command:** Spawn agent with history.md summarization task +- **args:** + - `member`: Which team member's history to summarize? +- **confirm:** false diff --git a/templates/skills/squad-help/SKILL.md b/templates/skills/squad-help/SKILL.md new file mode 100644 index 000000000..81bc4ae2a --- /dev/null +++ b/templates/skills/squad-help/SKILL.md @@ -0,0 +1,97 @@ +--- +name: "squad-help" +description: "How to actually use Squad — Squad is a custom Copilot agent (invoked via the task tool with agent_type='Squad'), not a skill. This file explains the right invocation paths for setting up a team, listing squad commands, and initializing Squad in a new project." +allowedTools: [] +confidence: high +domain: squad-onboarding +--- + +# Skill: squad-help + +> **Quick reference.** If you're reading this because a user said "use squad" or "squad" or "set up a squad", you're in the right place — read on for the correct invocation paths. + +--- + +## Squad is a custom agent, not a skill + +The Squad framework registers a **custom Copilot CLI agent** at `.github/agents/squad.agent.md`. The agent is named **`Squad`** and its description is *"Your AI team. Describe what you're building, get a team of specialists that live in your repo."* + +Copilot CLI agents and skills are different things: + +| Thing | How to invoke | Example | +|---|---|---| +| **Skill** | `skill(name)` tool call or natural-language match | `skill(squad-commands)` | +| **Agent** | `task` tool with `agent_type=` | `task(name="...", agent_type="Squad", prompt="...")` | +| **Slash command** | Built-in CLI keyword | `/agent`, `/skills`, `/mcp` | + +Calling `skill(Squad)` will fail with *"Skill not found: Squad"* because Squad is the agent, not a skill. (`/squad` as a slash command also does not exist — only built-in CLI keywords like `/agent`, `/skills`, `/mcp` are slash commands. There's no way to map a skill name to a slash command without a Copilot CLI feature change.) + +--- + +## How to actually use Squad + +Pick the path that matches the user's intent: + +### A) Invoke the Squad coordinator agent (most common) + +The Squad coordinator orchestrates a team of specialists. It routes work to the right agent, scaffolds a team if none exists, and enforces handoffs. + +```text +task( + name="", + agent_type="Squad", + prompt="" +) +``` + +Use this when the user says things like: +- *"Use Squad to build X"* +- *"Set up an AI team for this project"* +- *"Have the Squad coordinator design Y"* +- *"Spawn Squad"* / *"Squad, help me with ..."* + +### B) See what Squad commands exist + +The `squad-commands` skill is a categorized catalog of common Squad operations. The coordinator presents it as an interactive menu. + +Trigger by natural-language match: `"squad commands"`, `"what can squad do"`, `"show me squad options"`, `"slash commands"`, `"what commands are available"`. + +Use this when the user says things like: +- *"What can Squad do?"* +- *"Show me the squad commands"* +- *"squad help"* + +### C) Initialize Squad in a fresh project + +`squad init` is a **shell command**, not a tool call. The user runs it in their terminal in a project that has no `.squad/` directory yet. + +```bash +squad init +``` + +Do **not** try to invoke this from inside an existing Copilot session — `.squad/` is already initialized if you're reading this file. + +--- + +## What NOT to do + +- ❌ Do not call `skill(Squad)`, `skill(squad)`, or `skill(squad-coordinator)` — Squad is not a skill. +- ❌ Do not type `/squad` expecting a slash command — slash commands are CLI keywords, not skill names. Use `/agent` (browse) or invoke the `Squad` agent via the `task` tool. +- ❌ Do not call `task(agent_type="Squad", …)` for tiny tasks the current agent can handle directly. Squad is for work that needs orchestration; trivial edits do not. + +--- + +## How this skill was discovered + +This skill ships from the Squad SDK templates and is wired into `MANIFEST_SKILL_NAMES`. It lives at `.copilot/skills/squad-help/SKILL.md` so the Copilot CLI's `/skills` loader picks it up alongside the other bundled Squad skills. + +If you removed this skill on purpose, the model will fall back to its own reasoning and may make the lookup mistakes described above. + +--- + +## See also + +- `.github/agents/squad.agent.md` — the actual Squad coordinator agent +- `.copilot/skills/squad-commands/SKILL.md` — the command catalog +- `.copilot/skills/squad-conventions/SKILL.md` — conventions for working on the Squad codebase itself +- `.copilot/skills/squad-version-check/SKILL.md` — version-stamping mechanics diff --git a/templates/skills/squad-version-check/SKILL.md b/templates/skills/squad-version-check/SKILL.md new file mode 100644 index 000000000..5f3fd785d --- /dev/null +++ b/templates/skills/squad-version-check/SKILL.md @@ -0,0 +1,169 @@ +--- +name: "squad-version-check" +description: "Internals of how @bradygaster/squad-cli stamps its version, how `squad upgrade` works (what it preserves vs overwrites), and how to probe the npm registry for the latest version from a coordinator prompt." +allowedTools: [] +confidence: medium +domain: squad-internals +source: "validated in bradygaster/squad#1173 recon (2026-05-26)." +--- + +# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics + +**Confidence:** medium +**Discovered by:** repository investigation +**Date:** 2026-05-26 +**Validated in:** Issue #1173 recon (bradygaster/squad) + +--- + +## What This Skill Covers + +Reusable knowledge about how `@bradygaster/squad-cli` stamps its version into `squad.agent.md`, how `squad upgrade` works, what it preserves vs. overwrites, and how to probe the npm registry for the latest version from a coordinator prompt. + +--- + +## Package & Registry Facts + +- **Package name:** `@bradygaster/squad-cli` +- **Registry:** npm (public) +- **CLI binary:** `squad` (registered via `package.json#bin.squad`) +- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase) + +--- + +## Version Stamping Mechanism + +**Source file:** `dist/cli/core/version.js` + +Three functions: + +### `getPackageVersion()` +Walks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist/cli/core/version.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found. + +### `stampVersion(filePath, version)` +Mutates `squad.agent.md` in three places: +1. HTML comment: `` (must be on the line immediately after frontmatter `---`) +2. Identity line: `- **Version:** {version}` +3. Greeting instruction: backtick-quoted `` `Squad v{version}` `` + +**Called by:** both `init` and `upgrade` — after copying the template to the destination. + +### `readInstalledVersion(filePath)` +Reads the stamped version back from `squad.agent.md`: +1. First tries HTML comment format: `//` +2. Falls back to old frontmatter format: `/^version:\s*"([^"]+)"/m` +3. Returns `'0.0.0'` on any error + +--- + +## `squad upgrade` Behavior + +**Source file:** `dist/cli/core/upgrade.js` + +### What gets overwritten: +- `squad.agent.md` — full overwrite from template, then `stampVersion()` +- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled) +- GitHub Actions workflows — from `templates/workflows/`; non-npm projects get type-aware stubs +- Runs `runMigrations()` after file copy + +### What is PRESERVED: +- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned) +- `agents/*/history.md` (individual agent memory) +- `.squad/config.json` — **never touched**; `stateBackend` survives intact +- User-added files not in TEMPLATE_MANIFEST + +### Self-upgrade path (`selfUpgradeCli()`): +Detects npm/pnpm/yarn via `npm_execpath` and `npm_config_user_agent`. Runs: +- npm: `npm install -g @bradygaster/squad-cli@latest` +- pnpm: `pnpm add -g @bradygaster/squad-cli@latest` +- yarn: `yarn global add @bradygaster/squad-cli@latest` +Use `@insider` tag for insider builds. + +### `compareSemver(a, b)` utility (in upgrade.js): +Returns -1/0/1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` < `0.9.5`). Can be ported directly if needed in prompt logic. + +--- + +## `.squad/config.json` — What It Holds + +```json +{ + "version": 1, + "stateBackend": "worktree" +} +``` + +Other optional fields added by the coordinator at runtime: +- `defaultModel` — global model override for all agent spawns +- `agentModelOverrides.{agentName}` — per-agent model override + +The file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences). + +--- + +## Version-Check Probe (npm Registry) + +Use this one-liner from inside a coordinator prompt to fetch dist-tags: + +``` +npm view @bradygaster/squad-cli dist-tags --json +``` + +- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting. +- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`). +- On any error (network failure, registry unreachable, parse error): show normal greeting. + +--- + +## Upstream OS-Specific Cache + +The CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL. + +**One-liner to read the upstream cache:** +``` +node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}" +``` + +Output semantics: +- Valid JSON `{"latestVersion":"X.Y.Z","checkedAt":N}` → cache hit; use `latestVersion` +- `STALE` → cache expired (older than 24h); treat as no data +- `MISS` → cache missing or corrupt; treat as no data + +**OS-specific cache path:** +- Windows: `%APPDATA%\squad-cli\update-check.json` +- Linux: `~/.config/squad-cli/update-check.json` +- macOS: `~/Library/Application Support/squad-cli/update-check.json` + +--- + +## Repo-Local Cache Convention: `.squad/.cache/version-check.json` + +Used by coordinator for `insider`/`preview` channels (the upstream cache only stores `latest`). + +**Schema:** +```json +{ + "checkedAt": "2026-05-26T14:13:28.492Z", + "currentVersion": "0.9.6-insider.2", + "channel": "insider", + "channelVersion": "0.9.7-insider.1" +} +``` + +**TTL:** 24 hours from `checkedAt`. +**Gitignore:** `.squad/.cache/` is listed in `.gitignore` — cache files are never committed. + +--- + +## Key File Paths (installed CLI) + +| Purpose | Path | +|---|---| +| Version utilities | `dist/cli/core/version.js` | +| Upgrade logic | `dist/cli/core/upgrade.js` | +| Init logic | `dist/cli/core/init.js` | +| Template manifest | `dist/cli/core/templates.js` | +| Copilot install helper | `dist/cli/copilot-install.js` | +| squad.agent.md template | `templates/squad.agent.md.template` | +| Session init reference | `templates/session-init-reference.md` | +| All templates | `templates/` | diff --git a/templates/skills/squad/SKILL.md b/templates/skills/squad/SKILL.md new file mode 100644 index 000000000..5feadf4c4 --- /dev/null +++ b/templates/skills/squad/SKILL.md @@ -0,0 +1,299 @@ +--- +name: squad +description: >- + Squad's command catalog and interactive menu. Invoke via /squad (slash command) or natural language ("squad commands", "what can squad do", "show me squad options"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent. +user-invocable: true +allowedTools: [] +--- + +## Menu Presentation Rules + +When the user triggers this skill (via `/squad` slash command, "squad commands", "help", "what can squad do", etc.): + +1. **Category-level menu first.** Present category names as an `ask_user` choice list: + ``` + 📋 Squad Commands — pick a category: + 1. Install & Upgrade + 2. Team Management + 3. Issues & PRs + 4. Plugins & Skills + 5. Model & Cost + 6. Sessions & State + ``` +2. **Drill-down.** After selection, show operation titles in that category as a second `ask_user` list. +3. **Direct match skips the menu.** If the user says "how do I upgrade with state backend," match to the specific entry and go straight to argument collection. +4. **Compact fallback.** If `ask_user` is unavailable, render as a markdown table instead. +5. **Back / Cancel.** Include "← Back to categories" in sub-menus. Include "Cancel" in confirmation prompts. Respect "never mind" / "cancel" at any point. + +**Argument collection:** For entries with `args`, iterate the list sequentially. Use `ask_user` with choices when `choices` is provided; free-text prompt otherwise. If the user says "just do it" or "defaults are fine," skip remaining args and use their defaults. + +**Confirmation template:** +``` +⚠️ This will {action-description}. +{what will change} +Proceed? (yes / no) +``` + +--- + +## Install & Upgrade + +### Upgrade Squad CLI + +- **intent:** upgrade squad, update squad, install latest version, get new version +- **summary:** Upgrade Squad CLI to the latest version for your channel +- **action:** shell +- **command:** squad upgrade +- **args:** + - `state-backend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** false +- **platform_caveats:** Requires terminal. In VS Code, open the integrated terminal and run the command directly. + +### Initialize Squad + +- **intent:** set up squad, initialize squad, create team, start squad in this project +- **summary:** Scaffold Squad in the current directory (idempotent) +- **action:** shell +- **command:** squad init +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires terminal. Recommend a standalone terminal for best results. + +### Switch State Backend + +- **intent:** switch state backend, change state storage, use git-notes, use orphan branch +- **summary:** Change where Squad stores mutable state (config.json) +- **action:** file-edit +- **command:** .squad/config.json → stateBackend +- **args:** + - `stateBackend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current) +- **confirm:** true +- **platform_caveats:** May require migration if switching away from worktree. Show current value and new value before confirming. + +--- + +## Team Management + +### Add Team Member + +- **intent:** add team member, hire agent, add agent, add developer, recruit +- **summary:** Add a new agent to the team roster +- **action:** coordinator +- **command:** Add Team Member flow (Init Mode / Team Mode) +- **args:** + - `role`: What role should this agent fill? (e.g., Frontend Dev, Backend Dev, QA Engineer) + - `name`: Preferred name or casting universe? | default: (auto-cast from active universe) +- **confirm:** false + +### Remove Team Member + +- **intent:** remove team member, fire agent, delete agent, remove developer +- **summary:** Remove an agent and delete their charter and history files +- **action:** coordinator +- **command:** Remove Team Member flow +- **args:** + - `member`: Which team member to remove? (name or role) +- **confirm:** true + +### Reassign Roles + +- **intent:** reassign role, change role, swap roles, update team member role +- **summary:** Update a team member's role in team.md and their charter +- **action:** coordinator +- **command:** Update team.md roster + charter.md +- **args:** + - `member`: Which team member? + - `newRole`: New role? +- **confirm:** false + +### Show Roster + +- **intent:** show roster, who is on the team, list team members, show team, capability profile +- **summary:** Display the current team roster and capability profile +- **action:** coordinator +- **command:** Direct Mode — read team.md, answer +- **args:** (none) +- **confirm:** false + +--- + +## Issues & PRs + +### Connect GitHub Repo + +- **intent:** connect github, enable issues, set up issues, link repository, github issues mode +- **summary:** Connect this project to GitHub Issues via gh auth +- **action:** coordinator +- **command:** GitHub Issues Mode (connection flow) +- **args:** (none) +- **confirm:** false +- **platform_caveats:** Requires `gh auth login` to have been run in the terminal. + +### Triage Issues + +- **intent:** triage issues, review issues, assign issues, label issues +- **summary:** Run the Lead triage flow on open GitHub issues +- **action:** coordinator +- **command:** GitHub Issues Mode → Lead triage +- **args:** (none) +- **confirm:** false + +### Activate Ralph + +- **intent:** activate ralph, start ralph, ralph go, start work monitor, start auto-work +- **summary:** Activate Ralph — Work Monitor — to pick up and run queued issues +- **action:** coordinator +- **command:** Ralph — Work Monitor triggers +- **args:** (none) +- **confirm:** false + +### Set Ralph Polling Interval + +- **intent:** set ralph interval, change ralph timing, how often does ralph check, ralph every N minutes +- **summary:** Tell Ralph how frequently to poll for new work +- **action:** coordinator +- **command:** Ralph trigger: "Ralph, check every N minutes" +- **args:** + - `interval`: How often should Ralph poll? (in minutes) | default: 10 +- **confirm:** false + +### Start Squad Watch + +- **intent:** start watch, squad watch, monitor issues, watch for issues, auto-triage +- **summary:** Start squad watch to continuously poll and triage issues +- **action:** shell +- **command:** squad watch +- **args:** + - `interval`: Poll interval in minutes | default: 10 +- **confirm:** false +- **platform_caveats:** CLI-only — long-running foreground process. Not viable in VS Code without an integrated terminal. Run: `squad watch --interval {n}` in your terminal. + +--- + +## Plugins & Skills + +### Browse Plugin Marketplace + +- **intent:** browse plugins, explore plugins, what plugins are available, plugin marketplace +- **summary:** Browse available plugins in the Squad marketplace +- **action:** shell +- **command:** squad plugin marketplace browse +- **args:** + - `name`: Plugin name to search for | default: (browse all) +- **confirm:** false + +### Add Marketplace Plugin + +- **intent:** add plugin, install plugin, get plugin from marketplace +- **summary:** Add a plugin from the marketplace to this Squad +- **action:** shell +- **command:** squad plugin marketplace add +- **args:** + - `plugin`: Plugin owner/repo (e.g., owner/plugin-name) +- **confirm:** false + +### Remove Marketplace Plugin + +- **intent:** remove plugin, uninstall plugin, delete plugin +- **summary:** Remove an installed marketplace plugin +- **action:** shell +- **command:** squad plugin marketplace remove +- **args:** + - `name`: Plugin name to remove +- **confirm:** true + +### List Marketplace Plugins + +- **intent:** list plugins, show installed plugins, what plugins do I have +- **summary:** List all plugins registered in this Squad +- **action:** shell +- **command:** squad plugin marketplace list +- **args:** (none) +- **confirm:** false + +### List Installed Skills + +- **intent:** list skills, show skills, what skills are installed, skill catalog +- **summary:** List all skills installed in .squad/skills/ and .github/skills/ +- **action:** coordinator +- **command:** Direct Mode — list .squad/skills/ and .github/skills/ directories +- **args:** (none) +- **confirm:** false + +--- + +## Model & Cost + +### Set Default Model + +- **intent:** set default model, change model, use gpt, use claude, switch model +- **summary:** Set the default model for all agents in config.json +- **action:** file-edit +- **command:** .squad/config.json → defaultModel +- **args:** + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5, gpt-5.3-codex) +- **confirm:** false + +### Override Per-Agent Model + +- **intent:** set model for agent, agent model override, use different model for one agent +- **summary:** Set a model override for a specific agent in config.json +- **action:** file-edit +- **command:** .squad/config.json → agentModelOverrides.{agentName} +- **args:** + - `agent`: Agent name (must match name in team.md) + - `model`: Model name (e.g., gpt-5.6-luna, claude-sonnet-4.5) +- **confirm:** false + +### Clear Model Preference + +- **intent:** clear model, reset model, remove model preference, use default model +- **summary:** Remove a model override from config.json (reverts to system default) +- **action:** file-edit +- **command:** .squad/config.json → remove defaultModel or agentModelOverrides.{agentName} +- **args:** + - `scope`: Clear default or a specific agent? | choices: {default model, specific agent} | default: default model + - `agent`: Agent name (only if scope = specific agent) +- **confirm:** false + +--- + +## Sessions & State + +### Catch-Up Summary + +- **intent:** catch me up, what happened, status, what did the team do, session summary +- **summary:** Summarize recent agent activity and key decisions +- **action:** coordinator +- **command:** Session catch-up flow (lazy scan) +- **args:** (none) +- **confirm:** false + +### Show Recent Decisions + +- **intent:** show decisions, recent decisions, what decisions were made, decision log +- **summary:** Display recent entries from .squad/decisions.md +- **action:** coordinator +- **command:** Direct Mode — read decisions.md, answer +- **args:** (none) +- **confirm:** false + +### Archive Old Decisions + +- **intent:** archive decisions, clean up decisions, move old decisions, compact decisions +- **summary:** Move old decisions from decisions.md to decisions-archive.md +- **action:** coordinator +- **command:** Move entries older than threshold from .squad/decisions.md → .squad/decisions-archive.md +- **args:** + - `olderThan`: Archive decisions older than how many days? | default: 30 +- **confirm:** true + +### Summarize Agent History + +- **intent:** summarize history, what did agent do, agent history, compress history +- **summary:** Spawn an agent to summarize and compress a team member's history file +- **action:** coordinator +- **command:** Spawn agent with history.md summarization task +- **args:** + - `member`: Which team member's history to summarize? +- **confirm:** false diff --git a/templates/skills/test-discipline/SKILL.md b/templates/skills/test-discipline/SKILL.md new file mode 100644 index 000000000..9f85fba96 --- /dev/null +++ b/templates/skills/test-discipline/SKILL.md @@ -0,0 +1,37 @@ +--- +name: "test-discipline" +description: "Update tests when changing APIs — no exceptions" +domain: "quality" +confidence: "high" +source: "earned (test assertion sync violations)" +--- + +## Context + +When APIs or public interfaces change, tests must be updated in the same commit. When test assertions reference file counts or expected arrays, they must be kept in sync with disk reality. Stale tests block CI for other contributors. + +## Patterns + +- **API changes → test updates (same commit):** If you change a function signature, public interface, or exported API, update the corresponding tests before committing +- **Test assertions → disk reality:** When test files contain expected counts (e.g., `EXPECTED_FEATURES`, `EXPECTED_SCENARIOS`), they must match the actual files on disk +- **Add files → update assertions:** When adding docs pages, features, or any counted resource, update the test assertion array in the same commit +- **CI failures → check assertions first:** Before debugging complex failures, verify test assertion arrays match filesystem state + +## Examples + +✓ **Correct:** +- Changed auth API signature → updated auth.test.ts in same commit +- Added `distributed-mesh.md` to features/ → added `'distributed-mesh'` to EXPECTED_FEATURES array +- Deleted two scenario files → removed entries from EXPECTED_SCENARIOS + +✗ **Incorrect:** +- Changed spawn parameters → committed without updating casting.test.ts (CI breaks for next person) +- Added `built-in-roles.md` → left EXPECTED_FEATURES at old count (PR blocked) +- Test says "expected 7 files" but disk has 25 (assertion staleness) + +## Anti-Patterns + +- Committing API changes without test updates ("I'll fix tests later") +- Treating test assertion arrays as static (they evolve with content) +- Assuming CI passing means coverage is correct (stale assertions can pass while being wrong) +- Leaving gaps for other agents to discover diff --git a/templates/skills/tiered-memory/SKILL.md b/templates/skills/tiered-memory/SKILL.md new file mode 100644 index 000000000..badc64671 --- /dev/null +++ b/templates/skills/tiered-memory/SKILL.md @@ -0,0 +1,220 @@ +--- +name: tiered-memory +description: Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn +domain: memory-management, performance +confidence: design (runtime not yet implemented) +source: design proposal +--- + +# Skill: Tiered Agent Memory + +> **Status (v0.10.0):** This skill describes a **design proposal**, not a shipped runtime. Skill files install via `squad init`/`upgrade`, but the underlying tier scaffolding (`.squad/memory/hot/`, `cold/`, `wiki/`), Scribe promotion logic, and spawn-template tier-aware reads are tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264). Until those land, agents continue to load full `history.md` + `decisions.md` on every spawn. + +## Overview + +Squad agents today load their full context history on every spawn, which grows unboundedly across sessions. The Tiered Agent Memory model proposes a three-tier separation so agents only load the bytes that are actually relevant to the current task, with older context kept available on demand. + +--- + +## Memory Tiers + +### 🔥 Hot Tier — Current Session Context +- **Size target:** keep small (~2–4KB typical) +- **Load policy:** Always loaded. Every spawn includes hot memory by default. +- **Contents:** Current task description, active decisions made this session, immediate blockers, last 3–5 actions taken, who you are talking to right now. +- **Lifetime:** Current session only. Discarded after session ends (Scribe promotes relevant parts to Cold). +- **Purpose:** Provide immediate task context without any latency or load decision. + +### ❄️ Cold Tier — Summarized Cross-Session History +- **Size target:** larger summary, not full transcript (~8–12KB typical) +- **Load policy:** Load on demand. Include only when the task explicitly needs history. +- **Contents:** Summarized past sessions (compressed by Scribe), cross-session decisions, recurring patterns, unresolved issues from prior work. +- **Lifetime:** Rolling window (default proposal: 30 days). Eligible entries are then promoted to Wiki. +- **Purpose:** Answer "what have we tried before?" and "what was decided?" without replaying full transcripts. +- **How to include:** Pass `--include-cold` in spawn template or add `## Cold Memory` section. + +### 📚 Wiki Tier — Durable Structured Knowledge +- **Size target:** variable, structured reference docs +- **Load policy:** Async write, selective read. Load only when task requires domain knowledge. +- **Contents:** Architecture decisions (ADRs), agent charters, routing rules, stable conventions, external API contracts, known platform constraints. +- **Lifetime:** Permanent until explicitly deprecated. +- **Purpose:** Authoritative reference. Not history — structured facts. +- **How to include:** Pass `--include-wiki` or reference specific wiki doc paths in spawn template. + +--- + +## When to Load Each Tier + +| Situation | Hot | Cold | Wiki | +|-----------|-----|------|------| +| New task, no prior context needed | ✅ | ❌ | ❌ | +| Resuming interrupted work | ✅ | ✅ | ❌ | +| Debugging a recurring issue | ✅ | ✅ | ❌ | +| Implementing against a spec/ADR | ✅ | ❌ | ✅ | +| Onboarding to unfamiliar subsystem | ✅ | ❌ | ✅ | +| Post-incident review | ✅ | ✅ | ✅ | + +--- + +## Spawn Template Pattern + +The default spawn prompt should include **Hot tier only**: + +``` +## Memory Context + +### Hot (current session) +{hot_context} +``` + +Add `--include-cold` when the task needs history: +``` +## Memory Context + +### Hot (current session) +{hot_context} + +### Cold (summarized history — load on demand) +See: .squad/memory/cold/{agent-name}.md +``` + +Add `--include-wiki` when the task needs domain knowledge: +``` +## Memory Context + +### Hot (current session) +{hot_context} + +### Wiki (durable reference) +See: .squad/memory/wiki/{topic}.md +``` + +--- + +## Integration with Scribe Agent (design — not yet implemented) + +Scribe is the proposed memory coordinator for this system. Once the runtime lands, Scribe will: + +1. **End of session:** Compress Hot → Cold summary (target: ~10% of session verbosity) +2. **Aged cold entries:** Promote Cold → Wiki for decisions/facts that aged into stable knowledge +3. **On-demand wiki writes:** Any agent can request Scribe to write a wiki entry mid-session + +Until then, see the Scribe charter for current behavior: `.squad/agents/scribe/charter.md` + +--- + +## Implementation Checklist (tracked in #1264) + +- [ ] Scribe writes Hot context file at session start (`.squad/memory/hot/{agent}.md`) +- [ ] Scribe compresses and writes Cold summary at session end +- [ ] Spawn templates default to Hot-only +- [ ] Coordinators add `--include-cold` / `--include-wiki` flags as needed +- [ ] Wiki entries stored in `.squad/memory/wiki/` +- [ ] Cold entries stored in `.squad/memory/cold/` with rolling TTL + +--- + +## References + +- Tracking issue: [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — installation gap + runtime status +- Original design spike: [bradygaster/squad#686](https://github.com/bradygaster/squad/issues/686) — tiered memory implementation plan +- Related: [bradygaster/squad#600](https://github.com/bradygaster/squad/issues/600) — context payload growth + +--- + +## Spawn Template + +# Spawn Template: Agent with Tiered Memory + +Use this template when spawning any Squad agent. By default it loads **Hot tier only**. Add optional sections as needed. + +--- + +## Task + +{task_description} + +## WHY + +{why_this_matters} + +## Success Criteria + +- [ ] {criterion_1} +- [ ] {criterion_2} + +--- + +## Memory Context + +### 🔥 Hot (always included) + +> Paste current session context here (~2–4KB target): + +``` +Current task: {task_description} +Active decisions: {decisions_this_session} +Last actions: {last_3_to_5_actions} +Blockers: {current_blockers_or_none} +Talking to: {current_interlocutor} +``` + +--- + +### ❄️ Cold (include when task needs history — add `--include-cold`) + +> Load on demand. Do not inline unless specifically needed. + +Summarized cross-session history is at: +`.squad/memory/cold/{agent-name}.md` + +Include when: +- Resuming interrupted work +- Debugging a recurring issue +- "What have we tried before?" + +**To load cold memory, add this section and fetch the file before spawning:** + +``` +## Cold Memory Summary +{contents_of_.squad/memory/cold/{agent-name}.md} +``` + +--- + +### 📚 Wiki (include when task needs domain knowledge — add `--include-wiki`) + +> Load on demand. Reference specific wiki docs by path. + +Wiki entries are at: `.squad/memory/wiki/` + +Include when: +- Implementing against an ADR or spec +- Onboarding to unfamiliar subsystem +- Need stable conventions or API contracts + +**To load wiki, add this section and reference the specific doc:** + +``` +## Wiki Reference +{contents_of_.squad/memory/wiki/{topic}.md} +``` + +--- + +## Escalation + +If blocked or uncertain: +- Architecture questions → current architecture owner from `routing.md` +- Security concerns → current security owner from `routing.md` +- Infrastructure/deployment → current delivery owner from `routing.md` +- Memory/history questions → current memory owner from `routing.md` + +--- + +## Notes + +- Hot tier is always included; keep it focused +- Cold adds a summary; only include when history is relevant +- Wiki adds variable size; only include specific relevant docs +- Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn diff --git a/templates/skills/versioning-policy/SKILL.md b/templates/skills/versioning-policy/SKILL.md new file mode 100644 index 000000000..59de6f54b --- /dev/null +++ b/templates/skills/versioning-policy/SKILL.md @@ -0,0 +1,123 @@ +--- +name: "versioning-policy" +description: "SemVer rules for Squad's stable, preview, insider, and local package versions" +domain: "release, versioning, npm, CI" +confidence: "high" +source: "earned (PR #640 workspace resolution incident and automated release channels)" +--- + +## Context + +Squad publishes `@bradygaster/squad-sdk` and +`@bradygaster/squad-cli` from one npm workspace. Their versions and the root +version move together. A mismatched prerelease dependency can make npm silently +resolve an older registry SDK instead of the local workspace. + +## 1. Supported versions + +| Use | Version | Committed branch | +|---|---|---| +| Stable release | `MAJOR.MINOR.PATCH` | `main`, and briefly `dev` during promotion | +| Preview release | `MAJOR.MINOR.PATCH-preview.N` | `dev` | +| Insider snapshot | `MAJOR.MINOR.PATCH-insider.N` | Generated by the insider workflow | +| Local build | `MAJOR.MINOR.PATCH-build.N` | Never committed | + +`preview` is a release channel, not a branch. Stable promotion merges a +sanitized release tree directly from `dev` to `main`. + +## 2. Package versions stay in lockstep + +These versions must always be identical: + +- `package.json` +- `packages/squad-sdk/package.json` +- `packages/squad-cli/package.json` +- the corresponding workspace entries in `package-lock.json` + +Use the workspace-aware version command: + +```bash +npm version "$VERSION" --workspaces --include-workspace-root --no-git-tag-version +``` + +Never edit only one package version. + +## 3. Prerelease workspace dependency rule + +The CLI depends on the SDK through a SemVer range. SemVer deliberately excludes +prereleases unless the comparator names a prerelease with the same base version. +For example, `>=0.13.0` does not match `0.14.0-preview.1`. + +For every committed preview version, set both the CLI manifest and lockfile +dependency floor to that exact preview: + +```bash +npm pkg set "dependencies.@bradygaster/squad-sdk=>=$VERSION" \ + --workspace @bradygaster/squad-cli +npm install --package-lock-only +``` + +For `VERSION=0.14.0-preview.1`, the required range is +`>=0.14.0-preview.1`. Before stable promotion, change the version and floor to +`0.14.0` / `>=0.14.0`; never leave a prerelease floor in a stable release. + +This rule prevents the PR #640 failure mode, where the build succeeded against +a stale published SDK rather than the workspace SDK. + +## 4. Local build versions are ephemeral + +`scripts/bump-build.mjs` may create `-build.N` versions for local development. + +- Never commit a `-build.N` version. +- The script skips itself when `CI=true` or `SKIP_BUILD_BUMP=1`. +- If a build changes manifests locally, restore the intended release source + versions before committing. + +## 5. Release lifecycle + +1. On a release-preparation branch from `dev`, set the next + `X.Y.Z-preview.N` version and matching SDK dependency floor. +2. Merge to `dev`, wait for CI, and dispatch `squad-release.yml` from `dev`. +3. Repeat with a new immutable preview version when another candidate is needed. +4. Dispatch `squad-insider-publish.yml` whenever an on-demand development + snapshot is needed; it computes the next immutable `X.Y.Z-insider.N`. +5. Prepare stable `X.Y.Z` and its stable SDK dependency floor on `dev`. +6. Dispatch `squad-promote.yml`; it sanitizes `dev`, pushes `main`, and + explicitly dispatches the stable release. +7. Open the next preview-version PR for continued development. + +A preview such as `0.14.0-preview.1` is never renamed or converted in place. +Stable `0.14.0` is a separate immutable package version and GitHub tag. + +## 6. Ownership + +The current Release Manager owns release version changes. Other agents may update +versions only when explicitly assigned release work or when reverting an +accidentally committed local `-build.N` version. + +## 7. CI enforcement + +CI verifies: + +- root, SDK, and CLI versions match; +- package-lock workspace versions match; +- committed prereleases use approved `preview` or `insider` identifiers; +- a preview CLI dependency and lockfile entry equal `>=VERSION`; +- stable source does not retain a prerelease dependency floor; and +- workspace packages resolve through local links rather than stale registry + packages. + +Release workflows repeat the dependency checks before creating a tag or +publishing. + +## Quick reference + +| Rule | Summary | +|---|---| +| Insider | The workflow generates `X.Y.Z-insider.N` from the stable base version | +| Preview | Commit `X.Y.Z-preview.N` to `dev` for an on-demand prerelease | +| Stable | Only `X.Y.Z` may release from `main` | +| Sync | Root, SDK, CLI, and lockfile workspace versions must match | +| Dependency | Preview CLI range and lockfile entry must be `>=VERSION` | +| Local build | `-build.N` is local-only and never committed | +| Ownership | The current Release Manager owns planned release version changes | diff --git a/templates/skills/windows-compatibility/SKILL.md b/templates/skills/windows-compatibility/SKILL.md new file mode 100644 index 000000000..6242b88c4 --- /dev/null +++ b/templates/skills/windows-compatibility/SKILL.md @@ -0,0 +1,98 @@ +--- +name: "windows-compatibility" +description: "Cross-platform path handling and command patterns" +domain: "platform" +confidence: "high" +source: "earned (multiple Windows-specific bugs: colons in filenames, git -C failures, path separators)" +--- + +## Context + +Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platform-specific assumptions: ISO timestamps with colons (illegal on Windows), `git -C` with Windows paths (unreliable), forward-slash paths in Node.js on Windows. + +## Patterns + +### Filenames & Timestamps +- **Never use colons in filenames:** ISO 8601 format `2026-03-15T05:30:00Z` is illegal on Windows +- **Use `safeTimestamp()` utility:** Replaces colons with hyphens → `2026-03-15T05-30-00Z` +- **Centralize formatting:** Don't inline `.toISOString().replace(/:/g, '-')` — use the utility + +### Git Commands +- **Never use `git -C {path}`:** Unreliable with Windows paths (backslashes, spaces, drive letters) +- **Always `cd` first:** Change directory, then run git commands +- **Check for changes before commit:** `git diff --cached --quiet` (exit 0 = no changes) + +### Commit Messages +- **Never embed newlines in `-m` flag:** Backtick-n (`\n`) fails silently in PowerShell +- **Use temp file + `-F` flag:** Write message to file, commit with `git commit -F $msgFile` + +### Paths +- **Never assume CWD is repo root:** Always use `TEAM ROOT` from spawn prompt or run `git rev-parse --show-toplevel` +- **Use path.join() or path.resolve():** Don't manually concatenate with `/` or `\` + +### Path Comparison (Case Sensitivity) +- **Never use case-sensitive `startsWith` or `===` for path comparison on Windows or macOS:** These filesystems are case-insensitive — `C:\Users\` and `c:\users\` refer to the same location +- **Use platform-aware comparison:** Check `process.platform === 'win32' || process.platform === 'darwin'` and lowercase both sides before comparing +- **Pattern:** + ```typescript + const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin'; + + function pathStartsWith(fullPath: string, prefix: string): boolean { + if (CASE_INSENSITIVE) { + return fullPath.toLowerCase().startsWith(prefix.toLowerCase()); + } + return fullPath.startsWith(prefix); + } + ``` +- **Where it matters:** Security checks (path traversal prevention), rootDir confinement, any path-contains-path validation +- **Linux is case-sensitive:** Do NOT lowercase on Linux — `/Home/` and `/home/` are different directories + +## Examples + +✓ **Correct:** +```javascript +// Timestamp utility +const safeTimestamp = () => new Date().toISOString().replace(/:/g, '-').split('.')[0] + 'Z'; + +// Git workflow (PowerShell) +cd $teamRoot +git add .squad/ +if ($LASTEXITCODE -eq 0) { + $msg = @" +docs(ai-team): session log + +Changes: +- Added decisions +"@ + $msgFile = [System.IO.Path]::GetTempFileName() + Set-Content -Path $msgFile -Value $msg -Encoding utf8 + git commit -F $msgFile + Remove-Item $msgFile +} +``` + +✗ **Incorrect:** +```javascript +// Colon in filename +const logPath = `.squad/log/${new Date().toISOString()}.md`; // ILLEGAL on Windows + +// git -C with Windows path +exec('git -C C:\\src\\squad add .squad/'); // UNRELIABLE + +// Inline newlines in commit message +exec('git commit -m "First line\nSecond line"'); // FAILS silently in PowerShell +``` + +## Anti-Patterns + +- Testing only on one platform (bugs ship to other platforms) +- Assuming Unix-style paths work everywhere +- Using `git -C` because it "looks cleaner" (it doesn't work) +- Skipping `git diff --cached --quiet` check (creates empty commits) +- **Wrong — case-sensitive path check on Windows and macOS:** + ```typescript + if (!resolved.startsWith(rootDir + path.sep)) { + throw new Error('Path traversal blocked'); + } + // Fails: 'c:\\Users\\temp\\file'.startsWith('C:\\Users\\temp\\') → false + ``` diff --git a/templates/spawn-reference.md b/templates/spawn-reference.md index b5e1748bc..a89c2dbb1 100644 --- a/templates/spawn-reference.md +++ b/templates/spawn-reference.md @@ -61,7 +61,7 @@ Standard spawn via `task` tool — used in CLI, or as fallback when `create_sess - **`agent_type`**: `"general-purpose"` (always — this gives agents full tool access) - **`mode`**: `"background"` (default) or `"sync"` — use `"background"` for all parallelizable work; use `"sync"` only when the result is needed before the next step can proceed -- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Ripley: Design REST API endpoints"`, `"Dallas: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing +- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Runtime Engineer: Design REST API endpoints"`, `"Experience Engineer: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing - **`prompt`**: The full agent prompt (see below) **⚡ Inline the charter.** Before spawning, read the agent's `charter.md` (resolve from team root: `{team_root}/.squad/agents/{name}/charter.md`) and paste its contents directly into the spawn prompt. This eliminates a tool call from the agent's critical path. The agent still reads its own `history.md` and `decisions.md`. diff --git a/templates/squad.agent.md.template b/templates/squad.agent.md.template index a2bf7384c..708edca2b 100644 --- a/templates/squad.agent.md.template +++ b/templates/squad.agent.md.template @@ -176,11 +176,11 @@ For each squad member with assigned issues, note them in the session context. Wh **The user should never see a blank screen while agents work.** Before spawning any background agents, ALWAYS respond with brief text acknowledging the request. Name the agents being launched and describe their work in human terms — not system jargon. This acknowledgment is REQUIRED, not optional. -- **Single agent:** `"Fenster's on it — looking at the error handling now."` +- **Single agent:** `"Runtime Engineer is on it — looking at the error handling now."` - **Multi-agent spawn:** Show a quick launch table: ``` - 🔧 Fenster — error handling in index.js - 🧪 Hockney — writing test cases + 🔧 Runtime Engineer — error handling in index.js + 🧪 Quality Engineer — writing test cases 📋 Scribe — logging session ``` @@ -214,9 +214,9 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use 👤 as fallback **Examples:** -- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"` -- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"` -- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` +- `name: "lead"`, `description: "🏗️ Lead: Reviewing architecture proposal"` +- `name: "runtime-engineer"`, `description: "🔧 Runtime Engineer: Refactoring auth module"` +- `name: "quality-engineer"`, `description: "🧪 Quality Engineer: Writing test cases"` - `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. @@ -234,7 +234,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa **NOT directives** (route normally): - Work requests ("build X", "fix Y", "test Z", "add a feature") - Questions ("how does X work?", "what did the team do?") -- Agent-directed tasks ("Ripley, refactor the API") +- Agent-directed tasks ("Runtime Engineer, refactor the API") **When you detect a directive:** @@ -288,7 +288,7 @@ The routing table determines **WHO** handles work. After routing, use Response M | Signal | Action | |--------|--------| -| Names someone ("Ripley, fix the button") | Spawn that agent | +| Names someone ("Experience Engineer, fix the button") | Spawn that agent | | Personal agent by name (user addresses a personal agent) | Route to personal agent in consult mode — they advise, project agent executes changes | | "Team" or multi-domain question | Spawn 2-3+ relevant agents in parallel, synthesize | | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) | @@ -654,7 +654,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without dispatching via the platform's tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Dispatch to the real agent and let it respond. 3. **Never skip dispatching (via `task` or `runSubagent`) for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "experience-engineer"` is right. `"General purpose task"` is wrong — `"Experience Engineer: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict. ### After Agent Work diff --git a/templates/workflows/squad-triage.yml b/templates/workflows/squad-triage.yml index 627626aaf..579f74d29 100644 --- a/templates/workflows/squad-triage.yml +++ b/templates/workflows/squad-triage.yml @@ -91,10 +91,12 @@ jobs: } function findLead(teamMembers) { - return teamMembers.find(member => { + const hasRoleToken = (member, token) => { const roleWords = member.role.toLowerCase().match(/[a-z0-9]+/g) || []; - return roleWords.includes('lead'); - }); + return roleWords.includes(token); + }; + return teamMembers.find(member => hasRoleToken(member, 'lead')) || + teamMembers.find(member => hasRoleToken(member, 'architect')); } function slugify(t) { return t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); } @@ -127,7 +129,12 @@ jobs: const headers = tableCells(line).map(cell => cell.toLowerCase()); const workTypeIndex = headers.indexOf('work type'); - const routeIndex = headers.findIndex(header => header === 'route to' || header === 'agent'); + const routeIndex = headers.findIndex(header => + header === 'route to' || + header === 'agent' || + header === 'primary' || + header === 'primary agent' + ); const examplesIndex = headers.indexOf('examples'); if (workTypeIndex < 0 || routeIndex < 0) continue; @@ -140,16 +147,11 @@ jobs: const examples = examplesIndex >= 0 ? (cells[examplesIndex] || '') : ''; if (!workType || !routeCell) continue; - const destinationNames = routeCell - .split(/\s*(?:,|\/|&|\+|\band\b)\s*/i) - .map(normalizeRouteDestination) - .filter(Boolean); - const destinations = teamMembers.filter(member => - destinationNames.includes(normalizeRouteDestination(member.name)) + const destinationName = normalizeRouteDestination(routeCell); + const member = teamMembers.find(candidate => + normalizeRouteDestination(candidate.name) === destinationName ); - for (const member of destinations) { - rules.push({ member, workType, examples }); - } + if (member) rules.push({ member, workType, examples }); } break; } @@ -158,28 +160,34 @@ jobs: } function routeScore(issueText, rule) { - const stopWords = new Set([ - 'and', 'the', 'for', 'with', 'from', 'into', 'module', 'system', - 'work', 'owner', 'agent', 'support', 'management', + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', ]); - const phrases = rule.workType - .toLowerCase() - .split(/[,/&]+/) - .map(value => value.trim()) - .filter(value => value.length >= 4); - const keywords = `${rule.workType} ${rule.examples}` - .toLowerCase() - .match(/[a-z0-9@.+#-]+/g) || []; - - let score = phrases.reduce( - (total, phrase) => total + (issueText.includes(phrase) ? 8 : 0), - 0 - ); - for (const keyword of new Set(keywords)) { - if (keyword.length < 3 || stopWords.has(keyword)) continue; - if (issueText.includes(keyword)) score++; + + function tokens(value) { + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + } + + function containsPhrase(haystack, needle) { + if (needle.length === 0 || needle.length > haystack.length) return false; + return haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); } - return score; + + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter(token => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.examples.split(/[,;]+/)] + .flatMap(phrase => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + + return rawPhrases.reduce((best, phrase) => { + const phraseTokens = tokens(phrase); + if (!containsPhrase(issueTokens, phraseTokens)) return best; + const specificity = phraseTokens.length * 100; + return Math.max(best, specificity); + }, 0); } function selectRoutingAssignment(issueText, routingContent, teamMembers, lead) { @@ -192,7 +200,16 @@ jobs: return { member: lead, workType: null }; } - const best = scoredRoutes[0]; + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter(candidate => candidate.score === bestScore); + const bestMembers = new Set(bestRoutes.map(candidate => + normalizeRouteDestination(candidate.rule.member.name) + )); + if (bestMembers.size !== 1) { + return { member: lead, workType: null }; + } + + const best = bestRoutes[0]; return { member: best.rule.member, workType: best.rule.workType }; } diff --git a/test/catalog-refresh.test.ts b/test/catalog-refresh.test.ts index f37145742..407756c1a 100644 --- a/test/catalog-refresh.test.ts +++ b/test/catalog-refresh.test.ts @@ -173,7 +173,6 @@ describe('template asset catalog invariants (#1080/#1183)', () => { // the same bug across squad-cli/templates, squad-sdk/templates, .squad-templates. const TEMPLATE_GLOBS = [ '.squad-templates/**/*.md', - '.squad/skills/**/*.md', '.copilot/skills/**/*.md', ]; diff --git a/test/ci/changelog-gate.test.ts b/test/ci/changelog-gate.test.ts index 59d96e559..cd6eb0b49 100644 --- a/test/ci/changelog-gate.test.ts +++ b/test/ci/changelog-gate.test.ts @@ -33,7 +33,6 @@ const governedPaths = [ '.squad-templates/scribe-charter.md', 'templates/skills/release-process/SKILL.md', 'templates/casting/policy.json', - '.squad/agents/troi/charter.md', ]; const unrelatedPaths = [ @@ -44,8 +43,11 @@ const unrelatedPaths = [ 'packages/squad-cli/package.json', 'scripts/bump-build.mjs', 'test/ci/changelog-gate.test.ts', + '.squad/team.md', '.squad/agents/troi/notes.md', + '.squad/agents/troi/charter.md', '.squad/routing.md', + '.squad/casting/registry.json', ]; describe('changelog gate path matching', () => { diff --git a/test/cross-squad.test.ts b/test/cross-squad.test.ts index 2f47c49db..f4471a29b 100644 --- a/test/cross-squad.test.ts +++ b/test/cross-squad.test.ts @@ -520,7 +520,7 @@ const __dirname_ccc = dirname(fileURLToPath(import.meta.url)); const REPO_ROOT_CCC = resolve(__dirname_ccc, '..'); const CROSS_SQUAD_COMM_LOCATIONS = [ - '.squad/skills/cross-squad-communication/SKILL.md', + '.squad-templates/skills/cross-squad-communication/SKILL.md', 'packages/squad-cli/templates/skills/cross-squad-communication/SKILL.md', 'packages/squad-sdk/templates/skills/cross-squad-communication/SKILL.md', ] as const; diff --git a/test/e2e-runbook-hygiene.test.ts b/test/e2e-runbook-hygiene.test.ts deleted file mode 100644 index 13f7e29af..000000000 --- a/test/e2e-runbook-hygiene.test.ts +++ /dev/null @@ -1,197 +0,0 @@ -/** - * E2E Runbook Hygiene - * - * E-scenario runbooks in `.squad/e2e/` ship as documented shell commands that a - * human operator pastes into a terminal. Nothing executes them in CI, so a - * command that cannot run at all can sit in a runbook indefinitely. - * - * That is only a documentation bug until it meets a gate whose pass condition is - * universally quantified ("every X in the result set must be Y"). Such a - * condition is **vacuously true over the empty set**, so a command that fails and - * returns nothing does not merely fail to inform the verdict — it writes the - * *passing* answer into it. - * - * That is exactly what happened in E4 Phase 3b (#1822): `gh` was invoked with a - * `--arg` flag it does not have, `--jq` swallowed `--arg` as its expression, `gh` - * exited 1 with empty stdout on every run, and `2>$null` hid the error. The two - * verdict fields marked `# dispositive` — where `true` is the FAIL evidence — - * were handed their `false` by an infrastructure failure. - * - * PR #1821 fixed that instance. This suite exists so the *class* cannot recur: - * it executes no commands and needs no fixture, network, or Actions minutes, yet - * it fails the build the moment a runbook regains either property that made the - * silent pass possible. - * - * Measured at introduction: 16 of 17 stderr-suppression sites already paired with - * an exit-code check, so this codifies discipline the runbooks already practice - * rather than imposing a new one. - * - * See `.squad/e2e/README.md` § Runbook conventions for the companion rule that - * cannot be mechanized: a universally-quantified gate must assert its input set - * is non-empty before evaluating. - */ - -import { describe, it, expect } from 'vitest'; -import { readFileSync, readdirSync } from 'node:fs'; -import { join } from 'node:path'; - -const E2E_DIR = join(process.cwd(), '.squad', 'e2e'); - -/** How many lines after a suppression may carry its exit-code check. */ -const EXIT_CHECK_WINDOW = 6; - -/** - * Read a text file with line endings normalized to LF. - * - * Markdown in this repo is not pinned to LF in .gitattributes, so Windows - * checkouts materialize CRLF. Normalize on read rather than making each regex - * CRLF-aware. - */ -function readText(filePath: string): string { - return readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n'); -} - -interface CodeLine { - /** 1-based line number in the source markdown. */ - line: number; - text: string; -} - -/** - * Return the executable lines of every fenced code block in a markdown file. - * - * Prose is excluded because runbooks legitimately *describe* these hazards in - * comments — E4 documents the `--jq --arg` defect verbatim so the next reader - * understands why the guard exists. A linter that flagged its own postmortem - * would punish the documentation that prevents recurrence. - * - * Comment lines are excluded for the same reason. - */ -function executableLines(markdown: string): CodeLine[] { - const out: CodeLine[] = []; - let inFence = false; - - markdown.split('\n').forEach((raw, idx) => { - if (raw.trimStart().startsWith('```')) { - inFence = !inFence; - return; - } - if (!inFence) return; - - const trimmed = raw.trim(); - if (trimmed === '' || trimmed.startsWith('#')) return; - - out.push({ line: idx + 1, text: raw }); - }); - - return out; -} - -/** - * Join shell line-continuations into single logical commands. - * - * A `gh` invocation is routinely split across physical lines with a trailing - * PowerShell backtick or POSIX backslash. Flag misuse must be judged against the - * whole command, not one fragment of it. The reported line number stays that of - * the first physical line so the failure points at the start of the command. - */ -function logicalCommands(lines: CodeLine[]): CodeLine[] { - const out: CodeLine[] = []; - let pending: CodeLine | null = null; - - for (const cur of lines) { - const continues = /[`\\]\s*$/.test(cur.text); - const body = cur.text.replace(/[`\\]\s*$/, ' '); - - if (pending) { - pending = { line: pending.line, text: `${pending.text}${body}` }; - } else { - pending = { line: cur.line, text: body }; - } - - if (!continues) { - out.push(pending); - pending = null; - } - } - - if (pending) out.push(pending); - return out; -} - -function runbooks(): string[] { - return readdirSync(E2E_DIR) - .filter((f) => f.endsWith('.md')) - .map((f) => join(E2E_DIR, f)); -} - -describe('E2E runbook hygiene', () => { - it('finds runbooks to lint', () => { - // Guards this suite against the failure mode it exists to prevent: if the - // glob silently matched nothing, every assertion below would pass over an - // empty set and prove nothing. - expect(runbooks().length).toBeGreaterThan(0); - }); - - /** - * `--arg` is a jq flag, not a gh flag. `gh` rejects it, and because `--jq` - * consumes the next token as its expression the remainder degrade into stray - * positionals — producing exit 1 and empty stdout rather than an obvious - * parse error. Interpolate the value into the jq expression in the host shell - * instead. - */ - it('never passes --arg to gh', () => { - const offenders: string[] = []; - - for (const file of runbooks()) { - for (const cmd of logicalCommands(executableLines(readText(file)))) { - if (/\bgh\s/.test(cmd.text) && /\s--arg\b/.test(cmd.text)) { - offenders.push(`${file}:${cmd.line} — ${cmd.text.trim()}`); - } - } - } - - expect( - offenders, - `gh has no --arg flag. It exits 1 with empty stdout, which a ` + - `universally-quantified gate reads as a pass. Build the jq expression ` + - `in the shell and pass it as a single --jq argument:\n${offenders.join('\n')}`, - ).toEqual([]); - }); - - /** - * Suppressing stderr is legitimate — runbooks do it to keep transcripts - * readable — but only when the command's success is established some other - * way. Unpaired, it converts a hard failure into an empty result that reads - * as a pass. - */ - it('pairs every stderr suppression with an exit-code check', () => { - const offenders: string[] = []; - - for (const file of runbooks()) { - const lines = executableLines(readText(file)); - - lines.forEach((cur, idx) => { - if (!/2>\s*(\$null|\/dev\/null)/.test(cur.text)) return; - - const window = lines - .slice(idx, idx + EXIT_CHECK_WINDOW) - .map((l) => l.text) - .join('\n'); - - const checksExit = /\$LASTEXITCODE|\$\?|\bexit\s+code\b/i.test(window); - if (!checksExit) { - offenders.push(`${file}:${cur.line} — ${cur.text.trim()}`); - } - }); - } - - expect( - offenders, - `Suppressed stderr without a nearby exit-code check. A failed command ` + - `then yields an empty result set, and a gate phrased "every X must be ` + - `Y" passes vacuously on it. Capture $LASTEXITCODE and report ` + - `INCONCLUSIVE — never a verdict value — when it is non-zero:\n${offenders.join('\n')}`, - ).toEqual([]); - }); -}); diff --git a/test/gh-aw-enlistment-skill.test.ts b/test/gh-aw-enlistment-skill.test.ts index e3fe92256..d488ece35 100644 --- a/test/gh-aw-enlistment-skill.test.ts +++ b/test/gh-aw-enlistment-skill.test.ts @@ -24,7 +24,7 @@ const ROOT = resolve(__dirname, '..'); const SKILL_ID = 'gh-aw-enlistment'; -const CANONICAL = `.squad/skills/${SKILL_ID}/SKILL.md`; +const CANONICAL = `.squad-templates/skills/${SKILL_ID}/SKILL.md`; const MIRRORS = [ `packages/squad-cli/templates/skills/${SKILL_ID}/SKILL.md`, `packages/squad-sdk/templates/skills/${SKILL_ID}/SKILL.md`, diff --git a/test/gh-aw-plan-lifecycle.test.ts b/test/gh-aw-plan-lifecycle.test.ts index 694eaae79..0ea79de93 100644 --- a/test/gh-aw-plan-lifecycle.test.ts +++ b/test/gh-aw-plan-lifecycle.test.ts @@ -18,7 +18,6 @@ import { join } from 'node:path'; const WORKFLOWS_DIR = join(process.cwd(), 'workflows'); const SQUAD_WORKFLOW = join(WORKFLOWS_DIR, 'squad.md'); const ONTOLOGY = join(WORKFLOWS_DIR, 'shared', 'squad-planning-ontology.md'); -const TEAM = join(process.cwd(), '.squad', 'team.md'); const GH_AW_GUIDE = join(process.cwd(), 'docs', 'src', 'content', 'docs', 'guide', 'gh-aw.md'); function readText(filePath: string): string { @@ -96,7 +95,19 @@ function agentBlock(markdown: string, name: string): string { const squad = readText(SQUAD_WORKFLOW); const ontology = readText(ONTOLOGY); -const team = readText(TEAM); +const team = [ + '# Synthetic Team Fixture', + '', + '## Members', + '', + '| Name | Role |', + '|------|------|', + '| Architect | Lead |', + '| Builder | Runtime Engineer |', + '| Writer | Documentation |', + '', + '## End', +].join('\n'); const guide = readText(GH_AW_GUIDE); // --------------------------------------------------------------------------- @@ -175,8 +186,8 @@ function leakedRoleTokens(text: string): string[] { describe('#1759: Owner/Agent bind to the cast Name column', () => { it('team.md exposes distinct Name and Role columns to bind against', () => { - expect(NAMES).toContain('Procedures'); - expect(NAMES).toContain('Flight'); + expect(NAMES).toContain('Architect'); + expect(NAMES).toContain('Builder'); expect(ROLES_LC.has('lead')).toBe(true); // "Lead" is a Role, not a Name expect(NAMES_LC.has('lead')).toBe(false); // and it is not a valid Owner }); @@ -186,8 +197,8 @@ describe('#1759: Owner/Agent bind to the cast Name column', () => { const goodPlan = [ '| # | Title | Owner | Size | Depends On |', '|---|-------|-------|------|-----------|', - '| 1 | Wire adapter | EECOM | M | - |', - '| 2 | Prompt refactor | Procedures | S | 1 |', + '| 1 | Wire adapter | Builder | M | - |', + '| 2 | Prompt refactor | Architect | S | 1 |', ].join('\n'); // A plan table that leaked Role strings into the Owner column. @@ -203,9 +214,9 @@ describe('#1759: Owner/Agent bind to the cast Name column', () => { expect(owners(goodPlan).some(isRoleStringLeak)).toBe(false); expect(owners(badPlan).every(isRoleStringLeak)).toBe(true); - // The specific failure mode: "lead" is a Role, "Procedures"/"EECOM" are Names. + // The specific failure mode: "lead" is a Role, while the fixture values are Names. expect(isRoleStringLeak('lead')).toBe(true); - expect(isRoleStringLeak('Procedures')).toBe(false); + expect(isRoleStringLeak('Architect')).toBe(false); }); it('squad-plan binds the Owner column to a certified team.md Name cell', () => { diff --git a/test/gh-aw-research-online.test.ts b/test/gh-aw-research-online.test.ts index c845ead97..21d4c4253 100644 --- a/test/gh-aw-research-online.test.ts +++ b/test/gh-aw-research-online.test.ts @@ -181,12 +181,6 @@ describe('gh-aw: /squad research online-documentation capability', () => { it('introduces no bespoke source-config / allowlist artifact files', () => { const forbidden = [ - join(process.cwd(), '.squad', 'research-sources.md'), - join(process.cwd(), '.squad', 'research-sources.yml'), - join(process.cwd(), '.squad', 'research-sources.yaml'), - join(process.cwd(), '.squad', 'research-sources.json'), - join(process.cwd(), '.squad', 'sources.md'), - join(process.cwd(), '.squad', 'sources.yml'), join(WORKFLOWS_DIR, 'research-allowlist.md'), join(WORKFLOWS_DIR, 'shared', 'squad-research-sources.md'), ]; diff --git a/test/ralph-triage.test.ts b/test/ralph-triage.test.ts index 7d0062f7a..98d50a1e4 100644 --- a/test/ralph-triage.test.ts +++ b/test/ralph-triage.test.ts @@ -1,5 +1,3 @@ -import { readFileSync } from 'node:fs'; -import { join } from 'node:path'; import { createRequire } from 'node:module'; import { describe, it, expect, expectTypeOf, afterEach } from 'vitest'; import { @@ -14,8 +12,39 @@ import { } from '../packages/squad-sdk/src/ralph/triage.js'; import type { GhIssue, GhPullRequest } from '../packages/squad-cli/src/cli/core/gh-cli.js'; -const ROUTING_MD = readFileSync(join(process.cwd(), '.squad', 'routing.md'), 'utf-8'); -const TEAM_MD = readFileSync(join(process.cwd(), '.squad', 'team.md'), 'utf-8'); +const TEAM_MD = [ + '# Team', + '', + '## Members', + '', + '| Name | Role |', + '|------|------|', + '| Team Lead | Lead |', + '| Runtime Engineer | Backend Runtime |', + '| Quality Engineer | Test Engineer |', + '| Experience Engineer | Frontend UX |', + '| Scribe | Session Memory |', + '| Ralph | Work Monitor |', +].join('\n'); + +const ROUTING_MD = [ + '# Routing', + '', + '## Routing Table', + '', + '| Work Type | Route To | Examples |', + '|-----------|-------|----------|', + '| Core runtime | Runtime Engineer 🔧 | adapter, session pool, API |', + '| Tests & quality | Quality Engineer 🧪 | Test coverage, Vitest, edge cases, CI/CD |', + '| Experience | Experience Engineer 🎨 | UI, UX, CSS |', + '', + '## Module Ownership', + '', + '| Module | Primary | Secondary |', + '|--------|---------|-----------|', + '| `src/ralph/` | Runtime Engineer | Team Lead |', + '| `src/` | Team Lead | Runtime Engineer |', +].join('\n'); function issue(title: string, body = ''): TriageIssue { return { @@ -31,7 +60,7 @@ describe('ralph triage parser helpers', () => { it('parses a standard team.md with ## Members table', () => { const roster = parseRoster(TEAM_MD); expect(roster.length).toBeGreaterThan(0); - // Verify structure, not specific names — names change during team rebirths + // Verify structure without reading the repository's live team state. expect(roster[0]).toHaveProperty('name'); expect(roster[0]).toHaveProperty('role'); expect(roster[0]).toHaveProperty('label'); @@ -132,10 +161,10 @@ describe('ralph triage parser helpers', () => { }); describe('parseRoutingRules()', () => { - it('parses standard routing.md with Work Type → Agent table', () => { + it('parses the canonical Routing Table with Route To column', () => { const rules = parseRoutingRules(ROUTING_MD); expect(rules.length).toBeGreaterThan(0); - // Verify structure — agent names change during team rebirths + // Verify structure using the synthetic roster. expect(rules[0]).toHaveProperty('workType'); expect(rules[0]).toHaveProperty('agentName'); expect(rules[0]).toHaveProperty('keywords'); @@ -162,6 +191,20 @@ describe('ralph triage parser helpers', () => { ]); }); + it('accepts generated preset routing with a Primary column', () => { + const markdown = [ + '## Routing Table', + '', + '| Work Type | Primary | Secondary |', + '|-----------|---------|-----------|', + '| Runtime | Runtime Engineer | Quality Engineer |', + ].join('\n'); + + expect(parseRoutingRules(markdown)).toEqual([ + { workType: 'Runtime', agentName: 'Runtime Engineer', keywords: [] }, + ]); + }); + it('returns empty array for empty/missing section', () => { expect(parseRoutingRules('# No routing section')).toEqual([]); expect(parseRoutingRules('## Work Type → Agent')).toEqual([]); @@ -214,7 +257,7 @@ describe('triageIssue()', () => { const modules = parseModuleOwnership(ROUTING_MD); it('module path match returns module-ownership source with high confidence', () => { - // Find a module path from the live routing to test with + // Find a module path from the synthetic routing fixture. const firstModule = modules[0]; expect(firstModule).toBeDefined(); const decision = triageIssue( @@ -226,8 +269,7 @@ describe('triageIssue()', () => { expect(decision?.source).toBe('module-ownership'); expect(decision?.confidence).toBe('high'); - // Agent name comes from live routing — don't hardcode it - expect(decision?.agent.name).toBeTruthy(); + expect(decision?.agent.name).toBe('Runtime Engineer'); }); it('routing keyword match returns routing-rule source', () => { @@ -239,8 +281,7 @@ describe('triageIssue()', () => { ); expect(decision?.source).toBe('routing-rule'); - // Agent name comes from live routing — don't hardcode it - expect(decision?.agent.name).toBeTruthy(); + expect(decision?.agent.name).toBe('Quality Engineer'); }); it('multiple keyword matches get higher confidence', () => { @@ -277,8 +318,7 @@ describe('triageIssue()', () => { it('lead fallback when no match', () => { const decision = triageIssue(issue('Unclear request', 'No obvious signal here'), rules, modules, roster); expect(decision?.source).toBe('lead-fallback'); - // Should find *some* lead — don't hardcode the name - expect(decision?.agent.name).toBeTruthy(); + expect(decision?.agent.name).toBe('Team Lead'); expect(decision?.confidence).toBe('low'); }); @@ -289,39 +329,43 @@ describe('triageIssue()', () => { it('combines title + body for matching', () => { const onlyBodyRule: RoutingRule[] = [ - { workType: 'Testing', agentName: 'Hockney', keywords: ['vitest'] }, + { workType: 'Testing', agentName: 'Quality Engineer', keywords: ['vitest'] }, + ]; + const qualityOnly: TeamMember[] = [ + { name: 'Quality Engineer', role: 'Tester', label: 'squad:quality-engineer' }, ]; - const hockneyOnly: TeamMember[] = [{ name: 'Hockney', role: 'Tester', label: 'squad:hockney' }]; const decision = triageIssue( issue('Please investigate', 'This appears only in body: vitest'), onlyBodyRule, [], - hockneyOnly, + qualityOnly, ); expect(decision?.source).toBe('routing-rule'); - expect(decision?.agent.name).toBe('Hockney'); + expect(decision?.agent.name).toBe('Quality Engineer'); }); it('case insensitive matching', () => { const onlyBodyRule: RoutingRule[] = [ - { workType: 'Testing', agentName: 'Hockney', keywords: ['vitest'] }, + { workType: 'Testing', agentName: 'Quality Engineer', keywords: ['vitest'] }, + ]; + const qualityOnly: TeamMember[] = [ + { name: 'Quality Engineer', role: 'Tester', label: 'squad:quality-engineer' }, ]; - const hockneyOnly: TeamMember[] = [{ name: 'Hockney', role: 'Tester', label: 'squad:hockney' }]; - const decision = triageIssue(issue('Need VITEST coverage now'), onlyBodyRule, [], hockneyOnly); + const decision = triageIssue(issue('Need VITEST coverage now'), onlyBodyRule, [], qualityOnly); expect(decision?.source).toBe('routing-rule'); }); it('prefers longer module path match (src/ralph/ over src/)', () => { const customModules: ModuleOwnership[] = [ - { modulePath: 'src/', primary: 'Keaton', secondary: null }, - { modulePath: 'src/ralph/', primary: 'Fenster', secondary: null }, + { modulePath: 'src/', primary: 'Team Lead', secondary: null }, + { modulePath: 'src/ralph/', primary: 'Runtime Engineer', secondary: null }, ]; const customRoster: TeamMember[] = [ - { name: 'Keaton', role: 'Lead', label: 'squad:keaton' }, - { name: 'Fenster', role: 'Core Dev', label: 'squad:fenster' }, + { name: 'Team Lead', role: 'Lead', label: 'squad:team-lead' }, + { name: 'Runtime Engineer', role: 'Core Dev', label: 'squad:runtime-engineer' }, ]; const decision = triageIssue( @@ -332,7 +376,7 @@ describe('triageIssue()', () => { ); expect(decision?.source).toBe('module-ownership'); - expect(decision?.agent.name).toBe('Fenster'); + expect(decision?.agent.name).toBe('Runtime Engineer'); }); }); diff --git a/test/recast-identity-neutrality.test.ts b/test/recast-identity-neutrality.test.ts index d141f9000..91343c990 100644 --- a/test/recast-identity-neutrality.test.ts +++ b/test/recast-identity-neutrality.test.ts @@ -1,51 +1,14 @@ import { readdirSync, readFileSync } from 'node:fs'; -import { join } from 'node:path'; +import { join, relative } from 'node:path'; import { runInNewContext } from 'node:vm'; import { describe, expect, it } from 'vitest'; -const retiredNames = [ - 'Flight', - 'EECOM', - 'FIDO', - 'PAO', - 'CAPCOM', - 'CONTROL', - 'Booster', - 'Surgeon', - 'Belanna', - 'GNC', - 'RETRO', - 'INCO', - 'GUIDO', - 'VOX', - 'DSKY', - 'Sims', - 'Handbook', -]; - -const identityNeutralFiles = [ - '.github/instructions/squad-routing-guard.instructions.md', - '.github/PR_REQUIREMENTS.md', - '.github/PULL_REQUEST_TEMPLATE.md', - '.github/dependabot.yml', -]; - -const templateRoots = [ - '.squad/skills', - '.squad-templates', - 'templates', - 'packages/squad-cli/templates', - 'packages/squad-sdk/templates', -]; - -const broadlyScannableTemplateNames = retiredNames.filter( - name => !['Flight', 'CONTROL', 'RETRO'].includes(name) -); - -const contextualTemplateNameChecks = [ - { name: 'Flight', pattern: /(? RoutingAssignment; }; +function manifestSkillNames(): string[] { + const source = readFileSync('packages/squad-sdk/src/config/init.ts', 'utf8'); + const block = source.match(/export const MANIFEST_SKILL_NAMES = \[([\s\S]*?)\] as const;/); + expect(block).not.toBeNull(); + return [...block![1].matchAll(/'([^']+)'/g)].map(match => match[1]); +} + function filesUnder(directory: string): string[] { return readdirSync(directory, { withFileTypes: true }).flatMap(entry => { const path = join(directory, entry.name); @@ -85,32 +55,74 @@ function triageHelpers(workflow: string): TriageHelpers { return context.result; } -describe('re-cast identity neutrality', () => { - it.each(identityNeutralFiles)('%s does not bind policy to a cast name', file => { - const content = readFileSync(file, 'utf8'); - for (const name of retiredNames) { - expect(content).not.toMatch(new RegExp(`\\b${name}\\b`, 'i')); +describe('product and team isolation', () => { + it('keeps build and template synchronization independent of live .squad state', () => { + const packageJson = JSON.parse(readFileSync('package.json', 'utf8')) as { + scripts: Record; + }; + const buildInputs = [ + packageJson.scripts.prebuild, + readFileSync('scripts/sync-templates.mjs', 'utf8'), + readFileSync('scripts/sync-skill-templates.mjs', 'utf8'), + readFileSync('scripts/size-regression-guard.mjs', 'utf8'), + readFileSync('packages/squad-sdk/src/config/init.ts', 'utf8'), + ]; + + expect(packageJson.scripts.prebuild).not.toContain('sync-skill-templates'); + expect(packageJson.scripts.prebuild).not.toContain('sync-templates'); + for (const input of buildInputs) { + expect(input).not.toContain("join(rootDir, '.squad',"); + expect(input).not.toContain('.squad/skills'); } + + const ciWorkflow = readFileSync('.github/workflows/squad-ci.yml', 'utf8'); + expect(ciWorkflow).not.toMatch(/SDK_CLI_PATH_REGEX=.*\\\.squad\/agents/); + + const testFiles = filesUnder('test').filter(file => file.endsWith('.ts')); + for (const file of testFiles) { + expect(readFileSync(file, 'utf8'), `${file} reads live team state`).not.toMatch( + /join\(process\.cwd\(\), ['"]\.squad['"]/ + ); + } + + expect(readFileSync('.dockerignore', 'utf8')).toMatch(/^\.squad$/m); + const heartbeat = readFileSync('.github/workflows/squad-heartbeat.yml', 'utf8'); + expect(heartbeat).toContain('node templates/ralph-triage.js'); + expect(heartbeat).not.toContain('node .squad/templates/ralph-triage.js'); }); - it('shipped templates do not contain cast-specific agent names', () => { - const templateFiles = templateRoots.flatMap(filesUnder); + it('ships every manifest skill from product-owned canonical templates', () => { + const mirrorRoots = [ + 'templates/skills', + 'packages/squad-cli/templates/skills', + 'packages/squad-sdk/templates/skills', + ]; - for (const file of templateFiles) { - const content = readFileSync(file, 'utf8'); - for (const name of broadlyScannableTemplateNames) { - expect(content, `${file} contains ${name}`).not.toMatch( - new RegExp(`\\b${name}\\b`, 'i') - ); - } - for (const check of contextualTemplateNameChecks) { - expect(content, `${file} contains ${check.name}`).not.toMatch(check.pattern); + const canonicalRoot = '.squad-templates/skills'; + const canonicalFiles = filesUnder(canonicalRoot) + .map(file => relative(canonicalRoot, file)) + .sort(); + + for (const skill of manifestSkillNames()) { + expect(canonicalFiles).toContain(join(skill, 'SKILL.md')); + } + + for (const root of mirrorRoots) { + const mirrorFiles = filesUnder(root) + .map(file => relative(root, file)) + .sort(); + expect(mirrorFiles, `${root} must exactly mirror canonical skills`).toEqual(canonicalFiles); + for (const file of canonicalFiles) { + expect( + readFileSync(join(root, file), 'utf8').replace(/\r\n/g, '\n'), + `${root}/${file} drifted from the product-owned canonical template` + ).toEqual(readFileSync(join(canonicalRoot, file), 'utf8').replace(/\r\n/g, '\n')); } } }); - it('triage derives ownership from routing.md instead of role-name heuristics', () => { - const workflow = readFileSync('.github/workflows/squad-triage.yml', 'utf8'); + it.each(workflowCopies)('%s derives ownership from routing.md instead of role-name heuristics', file => { + const workflow = readFileSync(file, 'utf8'); expect(workflow).toContain('function routingRules(markdown, teamMembers)'); expect(workflow).toContain('Matched routing rule'); @@ -119,23 +131,30 @@ describe('re-cast identity neutrality', () => { expect(workflow).not.toContain("role.includes('devops')"); }); - it('executes routing matches, exact destinations, and Lead fallback', () => { - const workflow = readFileSync('.github/workflows/squad-triage.yml', 'utf8'); + it.each(workflowCopies)('%s executes boundary-safe, ambiguity-aware routing', file => { + const workflow = readFileSync(file, 'utf8'); const helpers = triageHelpers(workflow); const architect = { name: 'Architect', role: 'Architect' }; const lead = { name: 'Team Lead', role: 'Technical Lead' }; const runtime = { name: 'Runtime Engineer', role: 'Runtime' }; + const quality = { name: 'Quality Engineer', role: 'Quality' }; + const experience = { name: 'Experience Engineer', role: 'UX' }; + const types = { name: 'Type Engineer', role: 'Type system' }; const ann = { name: 'Ann', role: 'Documentation' }; const anna = { name: 'Anna', role: 'Documentation' }; - const members = [architect, lead, runtime, ann, anna]; + const members = [architect, lead, runtime, quality, experience, types, ann, anna]; const routing = [ '| Work Type | Agent | Examples', '| --- | --- | ---', - '| Core runtime | Runtime Engineer 🔧 | adapter, session pool', + '| Core runtime | Runtime Engineer 🔧 | adapter, session pool, API', + '| Tests & quality | Quality Engineer | CI/CD, API failure', + '| Experience | Experience Engineer | UI, UX', + '| Type system | Type Engineer | C#, generics', '| Docs | Anna 📚 | readme, documentation', ].join('\n'); expect(helpers.findLead(members)).toEqual(lead); + expect(helpers.findLead([architect])).toEqual(architect); expect( helpers.selectRoutingAssignment( 'adapter session pool regression', @@ -144,6 +163,30 @@ describe('re-cast identity neutrality', () => { lead ) ).toEqual({ member: runtime, workType: 'Core runtime' }); + expect( + helpers.selectRoutingAssignment( + 'CI failure in the release workflow', + routing, + members, + lead + ) + ).toEqual({ member: quality, workType: 'Tests & quality' }); + expect( + helpers.selectRoutingAssignment( + 'UI polish and UX review', + routing, + members, + lead + ) + ).toEqual({ member: experience, workType: 'Experience' }); + expect( + helpers.selectRoutingAssignment( + 'C# generic constraint regression', + routing, + members, + lead + ) + ).toEqual({ member: types, workType: 'Type system' }); expect( helpers.selectRoutingAssignment( 'readme documentation update', @@ -160,5 +203,72 @@ describe('re-cast identity neutrality', () => { lead ) ).toEqual({ member: lead, workType: null }); + expect( + helpers.selectRoutingAssignment( + 'rapid response required', + routing, + members, + lead + ) + ).toEqual({ member: lead, workType: null }); + expect( + helpers.selectRoutingAssignment( + 'engineer needed', + routing, + members, + lead + ) + ).toEqual({ member: lead, workType: null }); + expect( + helpers.selectRoutingAssignment( + 'API failure', + routing, + members, + lead + ) + ).toEqual({ member: quality, workType: 'Tests & quality' }); + + const ambiguousRouting = [ + '| Work Type | Agent | Examples', + '| --- | --- | ---', + '| Runtime | Runtime Engineer | API', + '| Quality | Quality Engineer | failure', + ].join('\n'); + expect( + helpers.selectRoutingAssignment( + 'API failure', + ambiguousRouting, + members, + lead + ) + ).toEqual({ member: lead, workType: null }); + + const invalidDestinationRouting = [ + '| Work Type | Agent | Examples', + '| --- | --- | ---', + '| Runtime | Runtime Engineer / Quality Engineer | adapter', + ].join('\n'); + expect( + helpers.selectRoutingAssignment( + 'adapter regression', + invalidDestinationRouting, + members, + lead + ) + ).toEqual({ member: lead, workType: null }); + + const presetRouting = [ + '| Work Type | Primary | Secondary |', + '| --- | --- | --- |', + '| Backend Engineer | Runtime Engineer | Quality Engineer |', + ].join('\n'); + expect( + helpers.selectRoutingAssignment( + 'backend regression', + presetRouting, + members, + lead + ) + ).toEqual({ member: runtime, workType: 'Backend Engineer' }); }); }); diff --git a/test/squad-agent-roster.test.ts b/test/squad-agent-roster.test.ts index 9bfd3ae25..ed68368a6 100644 --- a/test/squad-agent-roster.test.ts +++ b/test/squad-agent-roster.test.ts @@ -30,7 +30,7 @@ const TEMPLATE_TARGETS = [ // After #1308 phase 1, the Determine-team-size / always-on-roster text // lives in this satellite skill (canonical source + 2 template mirrors). const INIT_MODE_SKILL_TARGETS = [ - '.squad/skills/coordinator-init-mode/SKILL.md', + '.squad-templates/skills/coordinator-init-mode/SKILL.md', 'packages/squad-cli/templates/skills/coordinator-init-mode/SKILL.md', 'packages/squad-sdk/templates/skills/coordinator-init-mode/SKILL.md', ]; diff --git a/test/state/archival.test.ts b/test/state/archival.test.ts index e7836fb98..32752dca6 100644 --- a/test/state/archival.test.ts +++ b/test/state/archival.test.ts @@ -474,13 +474,5 @@ describe('archival integrity', () => { expect(entries[1]?.text).toContain('tail that must stay with Second'); }); - it('round-trips the real .squad/decisions.md byte-for-byte', () => { - const real = path.join(process.cwd(), '.squad', 'decisions.md'); - if (!existsSync(real)) return; // not present in a consumer checkout - const md = readFileSync(real, 'utf8'); - - expect(countEntries(md)).toBeGreaterThan(0); - expect(roundTrip(md)).toBe(md); - }); }); }); diff --git a/test/template-sync.test.ts b/test/template-sync.test.ts index c7cf8af7b..06efd8ad0 100644 --- a/test/template-sync.test.ts +++ b/test/template-sync.test.ts @@ -6,14 +6,14 @@ * Special target: .github/agents/ (squad.agent.md only) * * Coverage strategy: - * 1. Dynamic enumeration — every file in .squad-templates/ must be byte-for-byte - * identical across all mirror targets (and .github/agents/ for squad.agent.md). - * 2. Script execution — `node scripts/sync-templates.mjs` must exit 0. + * 1. Dynamic enumeration — every file in .squad-templates/ must be content-equivalent + * across all mirror targets (and .github/agents/ for squad.agent.md). + * 2. Script validation — the maintenance command parses without mutating files. * 3. Negative guard — .github/agents/ must not contain stray synced files. * 4. Semantic checks — universe counts, casting-policy internal consistency. */ -import { describe, it, expect, beforeAll } from 'vitest'; +import { describe, it, expect } from 'vitest'; import { readFileSync, existsSync, readdirSync } from 'node:fs'; import { resolve, dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -22,23 +22,6 @@ import { execSync } from 'node:child_process'; const __dirname = dirname(fileURLToPath(import.meta.url)); const ROOT = resolve(__dirname, '..'); -// Re-sync templates before any byte-comparison checks. -// -// Historically this existed because test/init-scaffolding.test.ts sandboxed -// itself *inside* the repo, so init() walked up to the real git root and -// stampVersion() rewrote .github/agents/squad.agent.md mid-run (#1796). That -// sandbox now lives in the OS temp dir and can no longer reach the repository, -// so this sync is defence-in-depth rather than active repair — it is kept so a -// future suite that reintroduces the escape fails loudly here instead of -// leaving a silently mutated working tree. -beforeAll(() => { - execSync('node scripts/sync-templates.mjs', { - cwd: ROOT, - encoding: 'utf-8', - timeout: 60_000, - }); -}); - // --------------------------------------------------------------------------- // Helpers // --------------------------------------------------------------------------- @@ -47,10 +30,6 @@ function readFile(relPath: string): string { return readFileSync(resolve(ROOT, relPath), 'utf-8'); } -function readFileBytes(relPath: string): Buffer { - return readFileSync(resolve(ROOT, relPath)); -} - function fileExists(relPath: string): boolean { return existsSync(resolve(ROOT, relPath)); } @@ -119,24 +98,10 @@ const CASTING_POLICY_LOCATIONS = [ ] as const; // --------------------------------------------------------------------------- -// 1. Dynamic enumeration — byte-for-byte parity for ALL synced files +// 1. Dynamic enumeration — content parity for ALL synced files // --------------------------------------------------------------------------- describe('dynamic template enumeration (all synced files)', () => { - // Re-sync immediately before byte comparisons as a second layer of defence. - // The original race — test/init-scaffolding.test.ts running runInit() against - // a sandbox under the repo root, so monorepo resolution stamped the real - // .github/agents/squad.agent.md — was fixed in #1796 by moving that sandbox - // to the OS temp dir. This describe-scoped beforeAll is retained to keep the - // window closed if any future suite reintroduces an in-repo sandbox. - beforeAll(() => { - execSync('node scripts/sync-templates.mjs', { - cwd: ROOT, - encoding: 'utf-8', - timeout: 60_000, - }); - }); - const sourceFiles = collectFiles(SOURCE_DIR); it('.squad-templates/ contains files to sync', () => { @@ -152,11 +117,11 @@ describe('dynamic template enumeration (all synced files)', () => { const destName = relFile === AGENT_MD_FILE ? `${AGENT_MD_FILE}.template` : relFile; const targetPath = `${target}/${destName}`; - it(`${targetPath} is byte-for-byte identical to ${canonicalPath}`, () => { + it(`${targetPath} is content-equivalent to ${canonicalPath}`, () => { expect(fileExists(targetPath), `${targetPath} should exist`).toBe(true); - const src = readFileBytes(canonicalPath); - const dst = readFileBytes(targetPath); - expect(Buffer.compare(src, dst), `${targetPath} content mismatch`).toBe(0); + const src = readFile(canonicalPath).replace(/\r\n/g, '\n'); + const dst = readFile(targetPath).replace(/\r\n/g, '\n'); + expect(dst, `${targetPath} content mismatch`).toBe(src); }); } @@ -164,29 +129,37 @@ describe('dynamic template enumeration (all synced files)', () => { if (relFile === AGENT_MD_FILE) { const agentPath = `${AGENT_MD_EXTRA_TARGET}/${AGENT_MD_FILE}`; - it(`${agentPath} is byte-for-byte identical to ${canonicalPath}`, () => { + it(`${agentPath} is content-equivalent to ${canonicalPath}`, () => { expect(fileExists(agentPath), `${agentPath} should exist`).toBe(true); - const src = readFileBytes(canonicalPath); - const dst = readFileBytes(agentPath); - expect(Buffer.compare(src, dst), `${agentPath} content mismatch`).toBe(0); + const src = readFile(canonicalPath).replace(/\r\n/g, '\n'); + const dst = readFile(agentPath).replace(/\r\n/g, '\n'); + expect(dst, `${agentPath} content mismatch`).toBe(src); }); } } }); // --------------------------------------------------------------------------- -// 2. Script execution — sync-templates.mjs must exit cleanly +// 2. Script validation — sync-templates.mjs must be explicit and parse cleanly // --------------------------------------------------------------------------- -describe('sync-templates.mjs script execution', () => { - it('exits with code 0 (no syntax errors, no crashes)', () => { - // execSync throws on non-zero exit codes +describe('sync-templates.mjs maintenance command', () => { + it('parses without mutating repository files', () => { + execSync('node --check scripts/sync-templates.mjs', { + cwd: ROOT, + encoding: 'utf-8', + timeout: 60_000, + }); + }); + + it('requires explicit opt-in before synchronization', () => { const output = execSync('node scripts/sync-templates.mjs', { cwd: ROOT, encoding: 'utf-8', timeout: 60_000, }); - expect(output).toContain('Synced'); + expect(output).toContain('requires explicit invocation'); + expect(output).not.toContain('Synced'); }); }); @@ -359,7 +332,7 @@ describe('squad.agent.md squad-spawning guidance', () => { // --------------------------------------------------------------------------- const CROSS_SQUAD_SKILL_LOCATIONS = [ - '.squad/skills/cross-squad/SKILL.md', + '.squad-templates/skills/cross-squad/SKILL.md', 'packages/squad-cli/templates/skills/cross-squad/SKILL.md', 'packages/squad-sdk/templates/skills/cross-squad/SKILL.md', ] as const; diff --git a/workflows/shared/squad-planning-ontology.md b/workflows/shared/squad-planning-ontology.md index 41d169253..55e5f754c 100644 --- a/workflows/shared/squad-planning-ontology.md +++ b/workflows/shared/squad-planning-ontology.md @@ -4,7 +4,7 @@ description: Squad planning ontology — artifact schemas, lifecycle state machi --- # Planning Ontology & Artifact Schemas -> **Version:** 2.0 · **Owner:** Procedures · **Status:** Active +> **Version:** 2.0 · **Owner:** Agent systems role · **Status:** Active > > **Decision Ratifications:** > - `copilot-plan-workflow-ux.md` → **Ratified Option A + Option 3**: Explicit commands (`/squad plan accept`) under the `/squad` namespace; planning logic lives in `shared/` components imported by `squad.md`. This file IS the shared component. diff --git a/workflows/squad-deps-worker.md b/workflows/squad-deps-worker.md index ca8ff45cd..d719919d2 100644 --- a/workflows/squad-deps-worker.md +++ b/workflows/squad-deps-worker.md @@ -76,7 +76,7 @@ safe-outputs: - "**/go.mod" - "go.sum" - "**/go.sum" - # Wave 1 protected-files exclusions (S2, issue #1748 Flight Decision comment, + # Wave 1 protected-files exclusions (S2, issue #1748 architecture decision, # APPROVED -- IMPLEMENTATION-READY, 2026-08-25). Excluding a basename from # `protected-files` allows the agent to produce a signed PR for that file; # the exclusion is compiled into `.lock.yml` at `gh aw compile` time and @@ -87,7 +87,7 @@ safe-outputs: # docs (`CODEOWNERS`, `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, # `CODE_OF_CONDUCT.md`, `DESIGN.md`, `AGENTS.md`) stay protected in every # wave -- see "bunfig.toml ruling" and "Always-protected" list in that - # Flight Decision comment. + # architecture decision. protected-files: policy: fallback-to-issue exclude: @@ -108,7 +108,7 @@ safe-outputs: # manifest basename above is excluded from protection in a later slice. # `excluded-files` strips these paths from the patch structurally, before # protected-files evaluation -- the correct mechanism per issue #1748's - # Flight Decision comment (APPROVED -- IMPLEMENTATION-READY, 2026-08-25), + # architecture decision (APPROVED -- IMPLEMENTATION-READY, 2026-08-25), # "Vendored/generated dependency content" threat-model row. - "node_modules/**" - "**/node_modules/**" diff --git a/workflows/squad.md b/workflows/squad.md index ab4c9e1db..1d6ba9b9c 100644 --- a/workflows/squad.md +++ b/workflows/squad.md @@ -403,7 +403,7 @@ failures, not commands to reinterpret as Cast. `workflow_dispatch` inputs `command` and `issue_number` are both `required: false`, so an empty activation probe can reach this workflow — the -`squad-implement-worker` relay fires one before its real dispatch (EECOM's +`squad-implement-worker` relay fires one before its real dispatch (the `dispatch-workflow` `max` fix, PR #1777). It is NOT a command. Guard against it as the FIRST action of the run, before resolving any command or entering any skill: From 9b44a2398f826888cd018e5dc416ba5ff72d3ecc Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 15:22:14 -0700 Subject: [PATCH 05/12] chore: normalize canonical skill assets Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../skills/architectural-proposals/SKILL.md | 8 +- .../skills/coordinator-response-mode/SKILL.md | 2 +- .../cross-machine-coordination/SKILL.md | 8 +- .../skills/cross-squad-communication/SKILL.md | 2 +- .../skills/distributed-mesh/sync-mesh.ps1 | 10 +- .../skills/distributed-mesh/sync-mesh.sh | 12 +- .../skills/external-comms/SKILL.md | 624 +++++++++--------- .../skills/gh-auth-isolation/SKILL.md | 366 +++++----- .squad-templates/skills/humanizer/SKILL.md | 210 +++--- .../skills/pr-screenshots/SKILL.md | 298 ++++----- .../skills/secret-handling/SKILL.md | 12 +- .../skills/windows-compatibility/SKILL.md | 2 +- .../skills/architectural-proposals/SKILL.md | 8 +- .../skills/coordinator-response-mode/SKILL.md | 2 +- .../cross-machine-coordination/SKILL.md | 8 +- .../skills/cross-squad-communication/SKILL.md | 2 +- .../skills/distributed-mesh/sync-mesh.ps1 | 10 +- .../skills/distributed-mesh/sync-mesh.sh | 12 +- .../templates/skills/secret-handling/SKILL.md | 12 +- .../skills/windows-compatibility/SKILL.md | 2 +- .../skills/architectural-proposals/SKILL.md | 8 +- .../skills/coordinator-response-mode/SKILL.md | 2 +- .../cross-machine-coordination/SKILL.md | 8 +- .../skills/cross-squad-communication/SKILL.md | 2 +- .../skills/distributed-mesh/sync-mesh.ps1 | 10 +- .../skills/distributed-mesh/sync-mesh.sh | 12 +- .../templates/skills/secret-handling/SKILL.md | 12 +- .../skills/windows-compatibility/SKILL.md | 2 +- .../skills/architectural-proposals/SKILL.md | 8 +- .../skills/coordinator-response-mode/SKILL.md | 2 +- .../cross-machine-coordination/SKILL.md | 8 +- .../skills/cross-squad-communication/SKILL.md | 2 +- .../skills/distributed-mesh/sync-mesh.ps1 | 10 +- .../skills/distributed-mesh/sync-mesh.sh | 12 +- templates/skills/external-comms/SKILL.md | 624 +++++++++--------- templates/skills/gh-auth-isolation/SKILL.md | 366 +++++----- templates/skills/humanizer/SKILL.md | 210 +++--- templates/skills/pr-screenshots/SKILL.md | 298 ++++----- templates/skills/secret-handling/SKILL.md | 12 +- .../skills/windows-compatibility/SKILL.md | 2 +- 40 files changed, 1610 insertions(+), 1610 deletions(-) diff --git a/.squad-templates/skills/architectural-proposals/SKILL.md b/.squad-templates/skills/architectural-proposals/SKILL.md index 4128ff096..3c3cb2533 100644 --- a/.squad-templates/skills/architectural-proposals/SKILL.md +++ b/.squad-templates/skills/architectural-proposals/SKILL.md @@ -82,8 +82,8 @@ When a proposal invalidates existing wave structure: ``` ### 1. Terminal UI Library: `ink` (recommended) or alternatives? -**Recommendation:** `ink` -**Alternatives:** `blessed`, raw readline +**Recommendation:** `ink` +**Alternatives:** `blessed`, raw readline **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. **Needs sign-off from:** Product Lead (product direction), Runtime Engineer (runtime performance) @@ -101,8 +101,8 @@ When a proposal invalidates existing wave structure: ``` ### Risk 2: SDK Streaming Reliability -**Risk:** SDK streaming events might drop messages or arrive out of order. -**Likelihood:** Low (SDK is production-grade). +**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:** diff --git a/.squad-templates/skills/coordinator-response-mode/SKILL.md b/.squad-templates/skills/coordinator-response-mode/SKILL.md index 4dff3b800..a88829f4d 100644 --- a/.squad-templates/skills/coordinator-response-mode/SKILL.md +++ b/.squad-templates/skills/coordinator-response-mode/SKILL.md @@ -79,7 +79,7 @@ prompt: | WORKTREE_PATH: {worktree_path} WORKTREE_MODE: {true|false} **Requested by:** {current user name} - + {% if WORKTREE_MODE %} **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches. {% endif %} diff --git a/.squad-templates/skills/cross-machine-coordination/SKILL.md b/.squad-templates/skills/cross-machine-coordination/SKILL.md index d9242c44b..87f559659 100644 --- a/.squad-templates/skills/cross-machine-coordination/SKILL.md +++ b/.squad-templates/skills/cross-machine-coordination/SKILL.md @@ -8,10 +8,10 @@ source: "manual" # Skill: Cross-Machine Coordination Pattern -**Skill ID:** `cross-machine-coordination` -**Owner:** Ralph (Work Monitor) -**Squad Integration:** All agents -**Status:** Specification (ready for implementation) +**Skill ID:** `cross-machine-coordination` +**Owner:** Ralph (Work Monitor) +**Squad Integration:** All agents +**Status:** Specification (ready for implementation) --- diff --git a/.squad-templates/skills/cross-squad-communication/SKILL.md b/.squad-templates/skills/cross-squad-communication/SKILL.md index 9286d5fa2..0088d8308 100644 --- a/.squad-templates/skills/cross-squad-communication/SKILL.md +++ b/.squad-templates/skills/cross-squad-communication/SKILL.md @@ -139,7 +139,7 @@ $stallCount = 0 while ($proc -and -not $proc.HasExited) { Start-Sleep -Seconds 15 $currentSize = (Get-ChildItem $logDir -Recurse -File | Measure-Object -Property Length -Sum).Sum - + if ($currentSize -eq $lastSize) { $stallCount++ if ($stallCount -ge 4) { # 60s with no progress diff --git a/.squad-templates/skills/distributed-mesh/sync-mesh.ps1 b/.squad-templates/skills/distributed-mesh/sync-mesh.ps1 index 5f409ef37..0b6bc1980 100644 --- a/.squad-templates/skills/distributed-mesh/sync-mesh.ps1 +++ b/.squad-templates/skills/distributed-mesh/sync-mesh.ps1 @@ -18,11 +18,11 @@ if ($Init) { Write-Host "❌ $MeshJson not found" exit 1 } - + Write-Host "🚀 Initializing mesh state repository..." $config = Get-Content $MeshJson -Raw | ConvertFrom-Json $squads = $config.squads.PSObject.Properties.Name - + # Create squad directories with placeholder SUMMARY.md foreach ($squad in $squads) { if (-not (Test-Path $squad)) { @@ -31,7 +31,7 @@ if ($Init) { } else { Write-Host " • $squad/ exists (skipped)" } - + $summaryPath = "$squad/SUMMARY.md" if (-not (Test-Path $summaryPath)) { "# $squad`n`n_No state published yet._" | Set-Content $summaryPath @@ -40,7 +40,7 @@ if ($Init) { Write-Host " • $summaryPath exists (skipped)" } } - + # Generate root README.md if (-not (Test-Path "README.md")) { $readme = @" @@ -65,7 +65,7 @@ State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``. } else { Write-Host " • README.md exists (skipped)" } - + Write-Host "" Write-Host "✅ Mesh state repository initialized" exit 0 diff --git a/.squad-templates/skills/distributed-mesh/sync-mesh.sh b/.squad-templates/skills/distributed-mesh/sync-mesh.sh index 802fd2d8d..e484e1a90 100644 --- a/.squad-templates/skills/distributed-mesh/sync-mesh.sh +++ b/.squad-templates/skills/distributed-mesh/sync-mesh.sh @@ -13,15 +13,15 @@ set -euo pipefail # Handle --init mode if [ "${1:-}" = "--init" ]; then MESH_JSON="${2:-mesh.json}" - + if [ ! -f "$MESH_JSON" ]; then echo "❌ $MESH_JSON not found" exit 1 fi - + echo "🚀 Initializing mesh state repository..." squads=$(jq -r '.squads | keys[]' "$MESH_JSON") - + # Create squad directories with placeholder SUMMARY.md for squad in $squads; do if [ ! -d "$squad" ]; then @@ -30,7 +30,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • $squad/ exists (skipped)" fi - + if [ ! -f "$squad/SUMMARY.md" ]; then echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md" echo " ✓ Created $squad/SUMMARY.md" @@ -38,7 +38,7 @@ if [ "${1:-}" = "--init" ]; then echo " • $squad/SUMMARY.md exists (skipped)" fi done - + # Generate root README.md if [ ! -f "README.md" ]; then { @@ -60,7 +60,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • README.md exists (skipped)" fi - + echo "" echo "✅ Mesh state repository initialized" exit 0 diff --git a/.squad-templates/skills/external-comms/SKILL.md b/.squad-templates/skills/external-comms/SKILL.md index 9745028f2..f1f0c4848 100644 --- a/.squad-templates/skills/external-comms/SKILL.md +++ b/.squad-templates/skills/external-comms/SKILL.md @@ -1,329 +1,329 @@ ---- -name: "external-comms" +--- +name: "external-comms" description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" -domain: "community, communication, workflow" -confidence: "low" +domain: "community, communication, workflow" +confidence: "low" source: "manual (external communications workflow)" -tools: - - name: "github-mcp-server-list_issues" - description: "List open issues for scan candidates and lightweight triage" - when: "Use for recent open issue scans before thread-level review" - - name: "github-mcp-server-issue_read" - description: "Read the full issue, comments, and labels before drafting" +tools: + - name: "github-mcp-server-list_issues" + description: "List open issues for scan candidates and lightweight triage" + when: "Use for recent open issue scans before thread-level review" + - name: "github-mcp-server-issue_read" + description: "Read the full issue, comments, and labels before drafting" when: "Use after selecting a candidate so the communications owner has complete thread context" - - name: "github-mcp-server-search_issues" - description: "Search for candidate issues or prior squad responses" - when: "Use when filtering by keywords, labels, or duplicate response checks" - - name: "gh CLI" - description: "Fallback for GitHub issue comments and discussions workflows" - when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete" ---- - -## Context - -Phase 1 is **draft-only mode**. - + - name: "github-mcp-server-search_issues" + description: "Search for candidate issues or prior squad responses" + when: "Use when filtering by keywords, labels, or duplicate response checks" + - name: "gh CLI" + description: "Fallback for GitHub issue comments and discussions workflows" + when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete" +--- + +## Context + +Phase 1 is **draft-only mode**. + - The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. - **Human review gate is mandatory** — the communications owner never posts autonomously. -- Every action is logged to `.squad/comms/audit/`. +- Every action is logged to `.squad/comms/audit/`. - This workflow is triggered manually only ("check community") — no automated activation in Phase 1. - -## Patterns - -### 1. Scan - -Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions. - -- Include **open** issues and discussions only. -- Filter for items with **no squad team response**. -- Limit to items created in the last 7 days. -- Exclude items labeled `squad:internal` or `wontfix`. -- Include discussions **and** issues in the same sweep. -- Phase 1 scope is **issues and discussions only** — do not draft PR replies. - -### Discussion Handling (Phase 1) - -Discussions use the GitHub Discussions API, which differs from issues: - -- **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions -- **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) + +## Patterns + +### 1. Scan + +Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions. + +- Include **open** issues and discussions only. +- Filter for items with **no squad team response**. +- Limit to items created in the last 7 days. +- Exclude items labeled `squad:internal` or `wontfix`. +- Include discussions **and** issues in the same sweep. +- Phase 1 scope is **issues and discussions only** — do not draft PR replies. + +### Discussion Handling (Phase 1) + +Discussions use the GitHub Discussions API, which differs from issues: + +- **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions +- **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) - **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. -- **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. - -### 2. Classify - -Determine the response type before drafting. - -- Welcome (new contributor) -- Troubleshooting (bug/help) -- Feature guidance (feature request/how-to) -- Redirect (wrong repo/scope) -- Acknowledgment (confirmed, no fix) -- Closing (resolved) -- Technical uncertainty (unknown cause) -- Empathetic disagreement (pushback on a decision or design) -- Information request (need more reproduction details or context) - -### Template Selection Guide - -| Signal in Issue/Discussion | → Response Type | Template | -|---------------------------|-----------------|----------| -| New contributor (0 prior issues) | Welcome | T1 | -| Error message, stack trace, "doesn't work" | Troubleshooting | T2 | -| "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 | -| Wrong repo, out of scope for Squad | Redirect | T4 | -| Confirmed bug, no fix available yet | Acknowledgment | T5 | -| Fix shipped, PR merged that resolves issue | Closing | T6 | -| Unclear cause, needs investigation | Technical Uncertainty | T7 | -| Author disagrees with a decision or design | Empathetic Disagreement | T8 | -| Need more reproduction info or context | Information Request | T9 | - -Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary. - -### Confidence Classification - -| Confidence | Criteria | Example | -|-----------|----------|---------| -| 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" | -| 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) | -| 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" | - -**Auto-escalation rules:** -- Any mention of competitors → 🔴 -- Any mention of pricing/licensing → 🔴 -- Author has >3 follow-up comments without resolution → 🔴 -- Question references a closed-wontfix issue → 🔴 - -### 3. Draft - -Use the humanizer skill for every draft. - -- Complete **Thread-Read Verification** before writing. -- Read the **full thread**, including all comments, before writing. -- Select the matching template from the **Template Selection Guide** and record the template ID in the review notes. -- Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it. -- Validate the draft against the humanizer anti-patterns. -- Flag long threads (`>10` comments) with `⚠️`. - -### Thread-Read Verification - +- **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. + +### 2. Classify + +Determine the response type before drafting. + +- Welcome (new contributor) +- Troubleshooting (bug/help) +- Feature guidance (feature request/how-to) +- Redirect (wrong repo/scope) +- Acknowledgment (confirmed, no fix) +- Closing (resolved) +- Technical uncertainty (unknown cause) +- Empathetic disagreement (pushback on a decision or design) +- Information request (need more reproduction details or context) + +### Template Selection Guide + +| Signal in Issue/Discussion | → Response Type | Template | +|---------------------------|-----------------|----------| +| New contributor (0 prior issues) | Welcome | T1 | +| Error message, stack trace, "doesn't work" | Troubleshooting | T2 | +| "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 | +| Wrong repo, out of scope for Squad | Redirect | T4 | +| Confirmed bug, no fix available yet | Acknowledgment | T5 | +| Fix shipped, PR merged that resolves issue | Closing | T6 | +| Unclear cause, needs investigation | Technical Uncertainty | T7 | +| Author disagrees with a decision or design | Empathetic Disagreement | T8 | +| Need more reproduction info or context | Information Request | T9 | + +Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary. + +### Confidence Classification + +| Confidence | Criteria | Example | +|-----------|----------|---------| +| 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" | +| 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) | +| 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" | + +**Auto-escalation rules:** +- Any mention of competitors → 🔴 +- Any mention of pricing/licensing → 🔴 +- Author has >3 follow-up comments without resolution → 🔴 +- Question references a closed-wontfix issue → 🔴 + +### 3. Draft + +Use the humanizer skill for every draft. + +- Complete **Thread-Read Verification** before writing. +- Read the **full thread**, including all comments, before writing. +- Select the matching template from the **Template Selection Guide** and record the template ID in the review notes. +- Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it. +- Validate the draft against the humanizer anti-patterns. +- Flag long threads (`>10` comments) with `⚠️`. + +### Thread-Read Verification + Before drafting, the communications owner MUST verify complete thread coverage: - -1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. -2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. -3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}" -4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary -5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column - -### 4. Present - -Show drafts for review in this exact format: - -```text + +1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. +2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. +3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}" +4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary +5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column + +### 4. Present + +Show drafts for review in this exact format: + +```text 📝 Community Response Drafts -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -| # | Item | Author | Type | Confidence | Read | Preview | -|---|------|--------|------|------------|------|---------| -| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." | - -Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review - -Full drafts below ▼ -``` - -Each full draft must begin with the thread summary line: -`Thread: {N} comments, last activity {date}, {summary of key points}` - -### 5. Human Action - -Wait for explicit human direction before anything is posted. - +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +Each full draft must begin with the thread summary line: +`Thread: {N} comments, last activity {date}, {summary of key points}` + +### 5. Human Action + +Wait for explicit human direction before anything is posted. + - `comms approve 1 3` — approve drafts 1 and 3 - `comms edit 2` — edit draft 2 - `comms skip` — skip all -- `banana` — freeze all pending (safe word) - -### Rollback — Bad Post Recovery - -If a posted response turns out to be wrong, inappropriate, or needs correction: - -1. **Delete the comment:** - - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` -2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content +- `banana` — freeze all pending (safe word) + +### Rollback — Bad Post Recovery + +If a posted response turns out to be wrong, inappropriate, or needs correction: + +1. **Delete the comment:** + - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` + - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` +2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content 3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle -4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case - -**Safe word — `banana`:** -- Immediately freezes all pending drafts in the review queue +4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case + +**Safe word — `banana`:** +- Immediately freezes all pending drafts in the review queue - No new scans or drafts until `comms resume` is issued -- Audit entry logged with halter identity and reason - -### 6. Post - -After approval: - -- Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. +- Audit entry logged with halter identity and reason + +### 6. Post + +After approval: + +- Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. - The communications owner helps by preparing the CLI command. -- Write the audit entry after the posting action. - -### 7. Audit - -Log every action. - -- Location: `.squad/comms/audit/{timestamp}.md` -- Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table -- Universal required fields: `timestamp`, `action` -- All other fields are conditional on the action type - -## Examples - -These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it. - -### Example scan command - -```bash -gh issue list --state open --json number,title,author,labels,comments --limit 20 -``` - -### Example review table - -```text +- Write the audit entry after the posting action. + +### 7. Audit + +Log every action. + +- Location: `.squad/comms/audit/{timestamp}.md` +- Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table +- Universal required fields: `timestamp`, `action` +- All other fields are conditional on the action type + +## Examples + +These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it. + +### Example scan command + +```bash +gh issue list --state open --json number,title,author,labels,comments --limit 20 +``` + +### Example review table + +```text 📝 Community Response Drafts -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -| # | Item | Author | Type | Confidence | Read | Preview | -|---|------|--------|------|------------|------|---------| -| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." | -| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." | -| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." | - -Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review - -Full drafts below ▼ -``` - -### Example audit entry (post action) - -```markdown ---- -timestamp: "2026-03-16T21:30:00Z" -action: "post" -item_number: 426 -draft_id: 1 -reviewer: "@bradygaster" ---- - -## Context (draft, approve, edit, skip, post, delete actions) -- Thread depth: 3 -- Response type: welcome -- Confidence: 🟢 -- Long thread flag: false - -## Draft Content (draft, edit, post actions) -Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install. - -Hey @newdev! Welcome to Squad 👋 Thanks for opening this. -We reproduced the issue in preview builds and we're checking the regression point now. -Let us know if you can share the command you ran right before the failure. - -## Post Result (post, delete actions) -https://github.com/bradygaster/squad/issues/426#issuecomment-123456 -``` - -### T1 — Welcome - -```text -Hey {author}! Welcome to Squad 👋 Thanks for opening this. -{specific acknowledgment or first answer} -Let us know if you have questions — happy to help! -``` - -### T2 — Troubleshooting - -```text -Thanks for the detailed report, {author}! -Here's what we think is happening: {explanation} -{steps or workaround} -Let us know if that helps, or if you're seeing something different. -``` - -### T3 — Feature Guidance - -```text -Great question! {context on current state} -{guidance or workaround} -We've noted this as a potential improvement — {tracking info if applicable}. -``` - -### T4 — Redirect - -```text -Thanks for reaching out! This one is actually better suited for {correct location}. -{brief explanation of why} -Feel free to open it there — they'll be able to help! -``` - -### T5 — Acknowledgment - -```text -Good catch, {author}. We've confirmed this is a real issue. -{what we know so far} -We'll update this thread when we have a fix. Thanks for flagging it! -``` - -### T6 — Closing - -```text -This should be resolved in {version/PR}! 🎉 -{brief summary of what changed} -Thanks for reporting this, {author} — it made Squad better. -``` - -### T7 — Technical Uncertainty - -```text -Interesting find, {author}. We're not 100% sure what's causing this yet. -Here's what we've ruled out: {list} -We'd love more context if you have it — {specific ask}. -We'll dig deeper and update this thread. -``` - -### T8 — Empathetic Disagreement - -```text -We hear you, {author}. That's a fair concern. - -The current design choice was driven by {reason}. We know it's not ideal for every use case. - -{what alternatives exist or what trade-off was made} - -If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here! -``` - -### T9 — Information Request - -```text -Thanks for reporting this, {author}! - -To help us dig into this, could you share: -- {specific ask 1} -- {specific ask 2} -- {specific ask 3, if applicable} - -That context will help us narrow down what's happening. Appreciate it! -``` - -## Anti-Patterns - -- ❌ Posting without human review (NEVER — this is the cardinal rule) -- ❌ Drafting without reading full thread (context is everything) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." | +| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." | +| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +### Example audit entry (post action) + +```markdown +--- +timestamp: "2026-03-16T21:30:00Z" +action: "post" +item_number: 426 +draft_id: 1 +reviewer: "@bradygaster" +--- + +## Context (draft, approve, edit, skip, post, delete actions) +- Thread depth: 3 +- Response type: welcome +- Confidence: 🟢 +- Long thread flag: false + +## Draft Content (draft, edit, post actions) +Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install. + +Hey @newdev! Welcome to Squad 👋 Thanks for opening this. +We reproduced the issue in preview builds and we're checking the regression point now. +Let us know if you can share the command you ran right before the failure. + +## Post Result (post, delete actions) +https://github.com/bradygaster/squad/issues/426#issuecomment-123456 +``` + +### T1 — Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{specific acknowledgment or first answer} +Let us know if you have questions — happy to help! +``` + +### T2 — Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### T3 — Feature Guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### T4 — Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### T5 — Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### T6 — Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### T7 — Technical Uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +### T8 — Empathetic Disagreement + +```text +We hear you, {author}. That's a fair concern. + +The current design choice was driven by {reason}. We know it's not ideal for every use case. + +{what alternatives exist or what trade-off was made} + +If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here! +``` + +### T9 — Information Request + +```text +Thanks for reporting this, {author}! + +To help us dig into this, could you share: +- {specific ask 1} +- {specific ask 2} +- {specific ask 3, if applicable} + +That context will help us narrow down what's happening. Appreciate it! +``` + +## Anti-Patterns + +- ❌ Posting without human review (NEVER — this is the cardinal rule) +- ❌ Drafting without reading full thread (context is everything) - ❌ Ignoring confidence flags (🔴 items need Lead or human review) -- ❌ Scanning closed issues (only open items) -- ❌ Responding to issues labeled `squad:internal` or `wontfix` -- ❌ Skipping audit logging (every action must be recorded) -- ❌ Drafting for issues where a squad member already responded (avoid duplicates) -- ❌ Drafting pull request responses in Phase 1 (issues/discussions only) -- ❌ Treating templates like loose examples instead of reusable drafting assets -- ❌ Asking for more info without specific requests +- ❌ Scanning closed issues (only open items) +- ❌ Responding to issues labeled `squad:internal` or `wontfix` +- ❌ Skipping audit logging (every action must be recorded) +- ❌ Drafting for issues where a squad member already responded (avoid duplicates) +- ❌ Drafting pull request responses in Phase 1 (issues/discussions only) +- ❌ Treating templates like loose examples instead of reusable drafting assets +- ❌ Asking for more info without specific requests diff --git a/.squad-templates/skills/gh-auth-isolation/SKILL.md b/.squad-templates/skills/gh-auth-isolation/SKILL.md index e4ac1abda..a639835b1 100644 --- a/.squad-templates/skills/gh-auth-isolation/SKILL.md +++ b/.squad-templates/skills/gh-auth-isolation/SKILL.md @@ -1,183 +1,183 @@ ---- -name: "gh-auth-isolation" -description: "Safely manage multiple GitHub identities (EMU + personal) in agent workflows" -domain: "security, github-integration, authentication, multi-account" -confidence: "high" -source: "earned (production usage across 50+ sessions with EMU corp + personal GitHub accounts)" -tools: - - name: "gh" - description: "GitHub CLI for authenticated operations" - when: "When accessing GitHub resources requiring authentication" ---- - -## Context - -Many developers use GitHub through an Enterprise Managed User (EMU) account at work while maintaining a personal GitHub account for open-source contributions. AI agents spawned by Squad inherit the shell's default `gh` authentication — which is usually the EMU account. This causes failures when agents try to push to personal repos, create PRs on forks, or interact with resources outside the enterprise org. - -This skill teaches agents how to detect the active identity, switch contexts safely, and avoid mixing credentials across operations. - -## Patterns - -### Detect Current Identity - -Before any GitHub operation, check which account is active: - -```bash -gh auth status -``` - -Look for: -- `Logged in to github.com as USERNAME` — the active account -- `Token scopes: ...` — what permissions are available -- Multiple accounts will show separate entries - -### Extract a Specific Account's Token - -When you need to operate as a specific user (not the default): - -```bash -# Get the personal account token (by username) -gh auth token --user personaluser - -# Get the EMU account token -gh auth token --user corpalias_enterprise -``` - -**Use case:** Push to a personal fork while the default `gh` auth is the EMU account. - -### Push to Personal Repos from EMU Shell - -The most common scenario: your shell defaults to the EMU account, but you need to push to a personal GitHub repo. - -```bash -# 1. Extract the personal token -$token = gh auth token --user personaluser - -# 2. Push using token-authenticated HTTPS -git push https://personaluser:$token@github.com/personaluser/repo.git branch-name -``` - -**Why this works:** `gh auth token --user` reads from `gh`'s credential store without switching the active account. The token is used inline for a single operation and never persisted. - -### Create PRs on Personal Forks - -When the default `gh` context is EMU but you need to create a PR from a personal fork: - -```bash -# Option 1: Use --repo flag (works if token has access) -gh pr create --repo upstream/repo --head personaluser:branch --title "..." --body "..." - -# Option 2: Temporarily set GH_TOKEN for one command -$env:GH_TOKEN = $(gh auth token --user personaluser) -gh pr create --repo upstream/repo --head personaluser:branch --title "..." -Remove-Item Env:\GH_TOKEN -``` - -### Config Directory Isolation (Advanced) - -For complete isolation between accounts, use separate `gh` config directories: - -```bash -# Personal account operations -$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" -gh auth login # Login with personal account (one-time setup) -gh repo clone personaluser/repo - -# EMU account operations (default) -Remove-Item Env:\GH_CONFIG_DIR -gh auth status # Back to EMU account -``` - -**Setup (one-time):** -```bash -# Create isolated config for personal account -mkdir ~/.config/gh-public -$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" -gh auth login --web --git-protocol https -``` - -### Shell Aliases for Quick Switching - -Add to your shell profile for convenience: - -```powershell -# PowerShell profile -function ghp { $env:GH_CONFIG_DIR = "$HOME/.config/gh-public"; gh @args; Remove-Item Env:\GH_CONFIG_DIR } -function ghe { gh @args } # Default EMU - -# Usage: -# ghp repo clone personaluser/repo # Uses personal account -# ghe issue list # Uses EMU account -``` - -```bash -# Bash/Zsh profile -alias ghp='GH_CONFIG_DIR=~/.config/gh-public gh' -alias ghe='gh' - -# Usage: -# ghp repo clone personaluser/repo -# ghe issue list -``` - -## Examples - -### ✓ Correct: Agent pushes blog post to personal GitHub Pages - -```powershell -# Agent needs to push to personaluser.github.io (personal repo) -# Default gh auth is corpalias_enterprise (EMU) - -$token = gh auth token --user personaluser -git remote set-url origin https://personaluser:$token@github.com/personaluser/personaluser.github.io.git -git push origin main - -# Clean up — don't leave token in remote URL -git remote set-url origin https://github.com/personaluser/personaluser.github.io.git -``` - -### ✓ Correct: Agent creates a PR from personal fork to upstream - -```powershell -# Fork: personaluser/squad, Upstream: bradygaster/squad -# Agent is on branch contrib/fix-docs in the fork clone - -git push origin contrib/fix-docs # Pushes to fork (may need token auth) - -# Create PR targeting upstream -gh pr create --repo bradygaster/squad --head personaluser:contrib/fix-docs ` - --title "docs: fix installation guide" ` - --body "Fixes #123" -``` - -### ✗ Incorrect: Blindly pushing with wrong account - -```bash -# BAD: Agent assumes default gh auth works for personal repos -git push origin main -# ERROR: Permission denied — EMU account has no access to personal repo - -# BAD: Hardcoding tokens in scripts -git push https://personaluser:ghp_xxxxxxxxxxxx@github.com/personaluser/repo.git main -# SECURITY RISK: Token exposed in command history and process list -``` - -### ✓ Correct: Check before you push - -```bash -# Always verify which account has access before operations -gh auth status -# If wrong account, use token extraction: -$token = gh auth token --user personaluser -git push https://personaluser:$token@github.com/personaluser/repo.git main -``` - -## Anti-Patterns - -- ❌ **Hardcoding tokens** in scripts, environment variables, or committed files. Use `gh auth token --user` to extract at runtime. -- ❌ **Assuming the default `gh` auth works** for all repos. EMU accounts can't access personal repos and vice versa. -- ❌ **Switching `gh auth login`** globally mid-session. This changes the default for ALL processes and can break parallel agents. -- ❌ **Storing personal tokens in `.env`** or `.squad/` files. These get committed by Scribe. Use `gh`'s credential store. -- ❌ **Ignoring token cleanup** after inline HTTPS pushes. Always reset the remote URL to avoid persisting tokens. -- ❌ **Using `gh auth switch`** in multi-agent sessions. One agent switching affects all others sharing the shell. -- ❌ **Mixing EMU and personal operations** in the same git clone. Use separate clones or explicit remote URLs per operation. +--- +name: "gh-auth-isolation" +description: "Safely manage multiple GitHub identities (EMU + personal) in agent workflows" +domain: "security, github-integration, authentication, multi-account" +confidence: "high" +source: "earned (production usage across 50+ sessions with EMU corp + personal GitHub accounts)" +tools: + - name: "gh" + description: "GitHub CLI for authenticated operations" + when: "When accessing GitHub resources requiring authentication" +--- + +## Context + +Many developers use GitHub through an Enterprise Managed User (EMU) account at work while maintaining a personal GitHub account for open-source contributions. AI agents spawned by Squad inherit the shell's default `gh` authentication — which is usually the EMU account. This causes failures when agents try to push to personal repos, create PRs on forks, or interact with resources outside the enterprise org. + +This skill teaches agents how to detect the active identity, switch contexts safely, and avoid mixing credentials across operations. + +## Patterns + +### Detect Current Identity + +Before any GitHub operation, check which account is active: + +```bash +gh auth status +``` + +Look for: +- `Logged in to github.com as USERNAME` — the active account +- `Token scopes: ...` — what permissions are available +- Multiple accounts will show separate entries + +### Extract a Specific Account's Token + +When you need to operate as a specific user (not the default): + +```bash +# Get the personal account token (by username) +gh auth token --user personaluser + +# Get the EMU account token +gh auth token --user corpalias_enterprise +``` + +**Use case:** Push to a personal fork while the default `gh` auth is the EMU account. + +### Push to Personal Repos from EMU Shell + +The most common scenario: your shell defaults to the EMU account, but you need to push to a personal GitHub repo. + +```bash +# 1. Extract the personal token +$token = gh auth token --user personaluser + +# 2. Push using token-authenticated HTTPS +git push https://personaluser:$token@github.com/personaluser/repo.git branch-name +``` + +**Why this works:** `gh auth token --user` reads from `gh`'s credential store without switching the active account. The token is used inline for a single operation and never persisted. + +### Create PRs on Personal Forks + +When the default `gh` context is EMU but you need to create a PR from a personal fork: + +```bash +# Option 1: Use --repo flag (works if token has access) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." --body "..." + +# Option 2: Temporarily set GH_TOKEN for one command +$env:GH_TOKEN = $(gh auth token --user personaluser) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." +Remove-Item Env:\GH_TOKEN +``` + +### Config Directory Isolation (Advanced) + +For complete isolation between accounts, use separate `gh` config directories: + +```bash +# Personal account operations +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login # Login with personal account (one-time setup) +gh repo clone personaluser/repo + +# EMU account operations (default) +Remove-Item Env:\GH_CONFIG_DIR +gh auth status # Back to EMU account +``` + +**Setup (one-time):** +```bash +# Create isolated config for personal account +mkdir ~/.config/gh-public +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login --web --git-protocol https +``` + +### Shell Aliases for Quick Switching + +Add to your shell profile for convenience: + +```powershell +# PowerShell profile +function ghp { $env:GH_CONFIG_DIR = "$HOME/.config/gh-public"; gh @args; Remove-Item Env:\GH_CONFIG_DIR } +function ghe { gh @args } # Default EMU + +# Usage: +# ghp repo clone personaluser/repo # Uses personal account +# ghe issue list # Uses EMU account +``` + +```bash +# Bash/Zsh profile +alias ghp='GH_CONFIG_DIR=~/.config/gh-public gh' +alias ghe='gh' + +# Usage: +# ghp repo clone personaluser/repo +# ghe issue list +``` + +## Examples + +### ✓ Correct: Agent pushes blog post to personal GitHub Pages + +```powershell +# Agent needs to push to personaluser.github.io (personal repo) +# Default gh auth is corpalias_enterprise (EMU) + +$token = gh auth token --user personaluser +git remote set-url origin https://personaluser:$token@github.com/personaluser/personaluser.github.io.git +git push origin main + +# Clean up — don't leave token in remote URL +git remote set-url origin https://github.com/personaluser/personaluser.github.io.git +``` + +### ✓ Correct: Agent creates a PR from personal fork to upstream + +```powershell +# Fork: personaluser/squad, Upstream: bradygaster/squad +# Agent is on branch contrib/fix-docs in the fork clone + +git push origin contrib/fix-docs # Pushes to fork (may need token auth) + +# Create PR targeting upstream +gh pr create --repo bradygaster/squad --head personaluser:contrib/fix-docs ` + --title "docs: fix installation guide" ` + --body "Fixes #123" +``` + +### ✗ Incorrect: Blindly pushing with wrong account + +```bash +# BAD: Agent assumes default gh auth works for personal repos +git push origin main +# ERROR: Permission denied — EMU account has no access to personal repo + +# BAD: Hardcoding tokens in scripts +git push https://personaluser:ghp_xxxxxxxxxxxx@github.com/personaluser/repo.git main +# SECURITY RISK: Token exposed in command history and process list +``` + +### ✓ Correct: Check before you push + +```bash +# Always verify which account has access before operations +gh auth status +# If wrong account, use token extraction: +$token = gh auth token --user personaluser +git push https://personaluser:$token@github.com/personaluser/repo.git main +``` + +## Anti-Patterns + +- ❌ **Hardcoding tokens** in scripts, environment variables, or committed files. Use `gh auth token --user` to extract at runtime. +- ❌ **Assuming the default `gh` auth works** for all repos. EMU accounts can't access personal repos and vice versa. +- ❌ **Switching `gh auth login`** globally mid-session. This changes the default for ALL processes and can break parallel agents. +- ❌ **Storing personal tokens in `.env`** or `.squad/` files. These get committed by Scribe. Use `gh`'s credential store. +- ❌ **Ignoring token cleanup** after inline HTTPS pushes. Always reset the remote URL to avoid persisting tokens. +- ❌ **Using `gh auth switch`** in multi-agent sessions. One agent switching affects all others sharing the shell. +- ❌ **Mixing EMU and personal operations** in the same git clone. Use separate clones or explicit remote URLs per operation. diff --git a/.squad-templates/skills/humanizer/SKILL.md b/.squad-templates/skills/humanizer/SKILL.md index 0932510c2..8d9be269b 100644 --- a/.squad-templates/skills/humanizer/SKILL.md +++ b/.squad-templates/skills/humanizer/SKILL.md @@ -1,105 +1,105 @@ ---- -name: "humanizer" -description: "Tone enforcement patterns for external-facing community responses" -domain: "communication, tone, community" -confidence: "low" -source: "manual (external communications workflow)" ---- - -## Context - -Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. - -- Tone must be warm, helpful, and human-sounding — never robotic or corporate. -- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. - -## Patterns - -1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!") -2. **Active voice** — "We're looking into this" not "This is being investigated" -3. **Second person** — Address the person directly ("you" not "the user") -4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:" -5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues" -6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!" -7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required" -8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence -9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting -10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold) -11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning -12. **Information request** — Ask for specific details, not open-ended "can you provide more info?" -13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link - -## Examples - -### 1. Welcome - -```text -Hey {author}! Welcome to Squad 👋 Thanks for opening this. -{substantive response} -Let us know if you have questions — happy to help! -``` - -### 2. Troubleshooting - -```text -Thanks for the detailed report, {author}! -Here's what we think is happening: {explanation} -{steps or workaround} -Let us know if that helps, or if you're seeing something different. -``` - -### 3. Feature guidance - -```text -Great question! {context on current state} -{guidance or workaround} -We've noted this as a potential improvement — {tracking info if applicable}. -``` - -### 4. Redirect - -```text -Thanks for reaching out! This one is actually better suited for {correct location}. -{brief explanation of why} -Feel free to open it there — they'll be able to help! -``` - -### 5. Acknowledgment - -```text -Good catch, {author}. We've confirmed this is a real issue. -{what we know so far} -We'll update this thread when we have a fix. Thanks for flagging it! -``` - -### 6. Closing - -```text -This should be resolved in {version/PR}! 🎉 -{brief summary of what changed} -Thanks for reporting this, {author} — it made Squad better. -``` - -### 7. Technical uncertainty - -```text -Interesting find, {author}. We're not 100% sure what's causing this yet. -Here's what we've ruled out: {list} -We'd love more context if you have it — {specific ask}. -We'll dig deeper and update this thread. -``` - -## Anti-Patterns - -- ❌ Corporate speak: "We appreciate your patience as we investigate this matter" -- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..." -- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked" -- ❌ Dismissive: "This works as designed" without empathy -- ❌ Over-promising: "We'll ship this next week" without commitment from the team -- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" -- ❌ Excessive emoji: More than 1-2 emoji per response -- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead -- ❌ Link-dumping: Pasting URLs without context ("See: https://...") -- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information +--- +name: "humanizer" +description: "Tone enforcement patterns for external-facing community responses" +domain: "communication, tone, community" +confidence: "low" +source: "manual (external communications workflow)" +--- + +## Context + +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. + +- Tone must be warm, helpful, and human-sounding — never robotic or corporate. +- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. + +## Patterns + +1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!") +2. **Active voice** — "We're looking into this" not "This is being investigated" +3. **Second person** — Address the person directly ("you" not "the user") +4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:" +5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues" +6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!" +7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required" +8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence +9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting +10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold) +11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning +12. **Information request** — Ask for specific details, not open-ended "can you provide more info?" +13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link + +## Examples + +### 1. Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{substantive response} +Let us know if you have questions — happy to help! +``` + +### 2. Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### 3. Feature guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### 4. Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### 5. Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### 6. Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### 7. Technical uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +## Anti-Patterns + +- ❌ Corporate speak: "We appreciate your patience as we investigate this matter" +- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..." +- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked" +- ❌ Dismissive: "This works as designed" without empathy +- ❌ Over-promising: "We'll ship this next week" without commitment from the team +- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" +- ❌ Excessive emoji: More than 1-2 emoji per response +- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead +- ❌ Link-dumping: Pasting URLs without context ("See: https://...") +- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information diff --git a/.squad-templates/skills/pr-screenshots/SKILL.md b/.squad-templates/skills/pr-screenshots/SKILL.md index fc93e8f77..7425ecf9e 100644 --- a/.squad-templates/skills/pr-screenshots/SKILL.md +++ b/.squad-templates/skills/pr-screenshots/SKILL.md @@ -1,149 +1,149 @@ ---- -name: "pr-screenshots" -description: "Capture Playwright screenshots and embed them in GitHub PR descriptions" -domain: "pull-requests, visual-review, docs, testing" -confidence: "high" -source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)" ---- - -## Context - -When a PR includes visual changes (docs sites, UI components, generated pages), reviewers -need to see what the PR delivers without checking out the branch. Screenshots belong in -the **PR description body**, not as committed files and not as text descriptions. - -Use this skill whenever: -- A PR touches docs site pages (Astro, Starlight, etc.) -- A PR adds or changes UI components -- A PR generates visual artifacts (TypeDoc, Storybook, diagrams) -- Playwright tests already capture screenshots as part of testing - -## Patterns - -### 1. Capture screenshots with Playwright - -If Playwright tests already exist and produce screenshots, reuse those. Otherwise, -write a minimal capture script: - -```javascript -// scripts/capture-pr-screenshots.mjs -import { chromium } from 'playwright'; - -const browser = await chromium.launch(); -const page = await browser.newPage({ viewport: { width: 1280, height: 720 } }); - -const screenshots = [ - { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' }, - { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' }, -]; - -for (const { url, name } of screenshots) { - await page.goto(url, { waitUntil: 'networkidle' }); - await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false }); -} - -await browser.close(); -``` - -### 2. Host screenshots on a temporary branch - -GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary -images directly. Use a temporary orphan branch to host the images: - -```powershell -# Save current branch -$currentBranch = git branch --show-current - -# Create orphan branch with only screenshot files -git checkout --orphan screenshots-temp -git reset -git add screenshots/*.png -git commit -m "screenshots for PR review" -git push origin screenshots-temp --force - -# Build raw URLs -$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" -# Each image: $base/{name}.png - -# Return to working branch -git checkout -f $currentBranch -``` - -### 3. Embed in PR description - -Use `gh pr edit` with the raw URLs embedded as markdown images: - -```powershell -$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" - -gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @" -## {PR Title} - -### What this PR delivers -- {bullet points of changes} - ---- - -### Screenshots - -#### {Page/Feature Name} -![{alt text}]($base/{name}.png) - -#### {Another Page} -![{alt text}]($base/{another-name}.png) - ---- - -### To verify locally -```bash -{commands to run locally} -``` -"@ -``` - -### 4. Cleanup after merge - -After the PR is merged, delete the temporary branch: - -```bash -git push origin --delete screenshots-temp -``` - -### 5. Gitignore screenshots locally - -Screenshots are build artifacts — never commit them to feature branches: - -```gitignore -# PR screenshots (hosted on temp branch, not committed to features) -screenshots/ -docs/tests/screenshots/ -``` - -## Examples - -### Example: Docs site PR with 3 pages - -1. Start dev server: `cd docs && npm run dev` -2. Run Playwright tests (they capture screenshots as a side effect) -3. Push screenshots to `screenshots-temp` branch -4. Update PR body with embedded `![...]()` image references -5. Reviewer sees the pages inline without checking out the branch - -### Example: Reusing existing Playwright test screenshots - -If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`: - -```powershell -cd docs && npx playwright test tests/api-reference.spec.mjs -# Screenshots now at docs/tests/screenshots/*.png -# Push those to screenshots-temp and embed in PR -``` - -## Anti-Patterns - -- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale -- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting -- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads -- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern -- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see -- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge +--- +name: "pr-screenshots" +description: "Capture Playwright screenshots and embed them in GitHub PR descriptions" +domain: "pull-requests, visual-review, docs, testing" +confidence: "high" +source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)" +--- + +## Context + +When a PR includes visual changes (docs sites, UI components, generated pages), reviewers +need to see what the PR delivers without checking out the branch. Screenshots belong in +the **PR description body**, not as committed files and not as text descriptions. + +Use this skill whenever: +- A PR touches docs site pages (Astro, Starlight, etc.) +- A PR adds or changes UI components +- A PR generates visual artifacts (TypeDoc, Storybook, diagrams) +- Playwright tests already capture screenshots as part of testing + +## Patterns + +### 1. Capture screenshots with Playwright + +If Playwright tests already exist and produce screenshots, reuse those. Otherwise, +write a minimal capture script: + +```javascript +// scripts/capture-pr-screenshots.mjs +import { chromium } from 'playwright'; + +const browser = await chromium.launch(); +const page = await browser.newPage({ viewport: { width: 1280, height: 720 } }); + +const screenshots = [ + { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' }, + { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' }, +]; + +for (const { url, name } of screenshots) { + await page.goto(url, { waitUntil: 'networkidle' }); + await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false }); +} + +await browser.close(); +``` + +### 2. Host screenshots on a temporary branch + +GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary +images directly. Use a temporary orphan branch to host the images: + +```powershell +# Save current branch +$currentBranch = git branch --show-current + +# Create orphan branch with only screenshot files +git checkout --orphan screenshots-temp +git reset +git add screenshots/*.png +git commit -m "screenshots for PR review" +git push origin screenshots-temp --force + +# Build raw URLs +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" +# Each image: $base/{name}.png + +# Return to working branch +git checkout -f $currentBranch +``` + +### 3. Embed in PR description + +Use `gh pr edit` with the raw URLs embedded as markdown images: + +```powershell +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" + +gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @" +## {PR Title} + +### What this PR delivers +- {bullet points of changes} + +--- + +### Screenshots + +#### {Page/Feature Name} +![{alt text}]($base/{name}.png) + +#### {Another Page} +![{alt text}]($base/{another-name}.png) + +--- + +### To verify locally +```bash +{commands to run locally} +``` +"@ +``` + +### 4. Cleanup after merge + +After the PR is merged, delete the temporary branch: + +```bash +git push origin --delete screenshots-temp +``` + +### 5. Gitignore screenshots locally + +Screenshots are build artifacts — never commit them to feature branches: + +```gitignore +# PR screenshots (hosted on temp branch, not committed to features) +screenshots/ +docs/tests/screenshots/ +``` + +## Examples + +### Example: Docs site PR with 3 pages + +1. Start dev server: `cd docs && npm run dev` +2. Run Playwright tests (they capture screenshots as a side effect) +3. Push screenshots to `screenshots-temp` branch +4. Update PR body with embedded `![...]()` image references +5. Reviewer sees the pages inline without checking out the branch + +### Example: Reusing existing Playwright test screenshots + +If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`: + +```powershell +cd docs && npx playwright test tests/api-reference.spec.mjs +# Screenshots now at docs/tests/screenshots/*.png +# Push those to screenshots-temp and embed in PR +``` + +## Anti-Patterns + +- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale +- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting +- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads +- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern +- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see +- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge diff --git a/.squad-templates/skills/secret-handling/SKILL.md b/.squad-templates/skills/secret-handling/SKILL.md index b0576f879..b6c6b31b6 100644 --- a/.squad-templates/skills/secret-handling/SKILL.md +++ b/.squad-templates/skills/secret-handling/SKILL.md @@ -67,10 +67,10 @@ Spawned agents have read access to the entire repository, including `.env` files - Report to user: ``` 🚨 SECRET DETECTED — commit blocked - + File: .squad/decisions/inbox/river-db-config.md Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod - + This file contains credentials and MUST NOT be committed. Please remove the secret, replace with placeholder, and try again. ``` @@ -92,17 +92,17 @@ Spawned agents have read access to the entire repository, including `.env` files 2. **Alert the user:** ``` 🚨 CREDENTIAL LEAK DETECTED - + A secret was found in git history: Commit: abc1234 File: .squad/decisions/inbox/agent-config.md Pattern: API_KEY=sk-proj-... - + This requires immediate remediation: 1. Revoke the exposed credential (regenerate API key, rotate password) 2. Remove from git history (git filter-repo or BFG) 3. Force-push the cleaned history - + Do NOT proceed with new work until this is resolved. ``` 3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools @@ -139,7 +139,7 @@ Agent: (reads .env) → Writes to .squad/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 ``` diff --git a/.squad-templates/skills/windows-compatibility/SKILL.md b/.squad-templates/skills/windows-compatibility/SKILL.md index 6242b88c4..98fa750b3 100644 --- a/.squad-templates/skills/windows-compatibility/SKILL.md +++ b/.squad-templates/skills/windows-compatibility/SKILL.md @@ -36,7 +36,7 @@ Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platfo - **Pattern:** ```typescript const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin'; - + function pathStartsWith(fullPath: string, prefix: string): boolean { if (CASE_INSENSITIVE) { return fullPath.toLowerCase().startsWith(prefix.toLowerCase()); diff --git a/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md b/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md index 4128ff096..3c3cb2533 100644 --- a/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md +++ b/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md @@ -82,8 +82,8 @@ When a proposal invalidates existing wave structure: ``` ### 1. Terminal UI Library: `ink` (recommended) or alternatives? -**Recommendation:** `ink` -**Alternatives:** `blessed`, raw readline +**Recommendation:** `ink` +**Alternatives:** `blessed`, raw readline **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. **Needs sign-off from:** Product Lead (product direction), Runtime Engineer (runtime performance) @@ -101,8 +101,8 @@ When a proposal invalidates existing wave structure: ``` ### Risk 2: SDK Streaming Reliability -**Risk:** SDK streaming events might drop messages or arrive out of order. -**Likelihood:** Low (SDK is production-grade). +**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:** diff --git a/packages/squad-cli/templates/skills/coordinator-response-mode/SKILL.md b/packages/squad-cli/templates/skills/coordinator-response-mode/SKILL.md index 4dff3b800..a88829f4d 100644 --- a/packages/squad-cli/templates/skills/coordinator-response-mode/SKILL.md +++ b/packages/squad-cli/templates/skills/coordinator-response-mode/SKILL.md @@ -79,7 +79,7 @@ prompt: | WORKTREE_PATH: {worktree_path} WORKTREE_MODE: {true|false} **Requested by:** {current user name} - + {% if WORKTREE_MODE %} **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches. {% endif %} diff --git a/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md b/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md index d9242c44b..87f559659 100644 --- a/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md +++ b/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md @@ -8,10 +8,10 @@ source: "manual" # Skill: Cross-Machine Coordination Pattern -**Skill ID:** `cross-machine-coordination` -**Owner:** Ralph (Work Monitor) -**Squad Integration:** All agents -**Status:** Specification (ready for implementation) +**Skill ID:** `cross-machine-coordination` +**Owner:** Ralph (Work Monitor) +**Squad Integration:** All agents +**Status:** Specification (ready for implementation) --- diff --git a/packages/squad-cli/templates/skills/cross-squad-communication/SKILL.md b/packages/squad-cli/templates/skills/cross-squad-communication/SKILL.md index 9286d5fa2..0088d8308 100644 --- a/packages/squad-cli/templates/skills/cross-squad-communication/SKILL.md +++ b/packages/squad-cli/templates/skills/cross-squad-communication/SKILL.md @@ -139,7 +139,7 @@ $stallCount = 0 while ($proc -and -not $proc.HasExited) { Start-Sleep -Seconds 15 $currentSize = (Get-ChildItem $logDir -Recurse -File | Measure-Object -Property Length -Sum).Sum - + if ($currentSize -eq $lastSize) { $stallCount++ if ($stallCount -ge 4) { # 60s with no progress diff --git a/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.ps1 b/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.ps1 index 5f409ef37..0b6bc1980 100644 --- a/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.ps1 +++ b/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.ps1 @@ -18,11 +18,11 @@ if ($Init) { Write-Host "❌ $MeshJson not found" exit 1 } - + Write-Host "🚀 Initializing mesh state repository..." $config = Get-Content $MeshJson -Raw | ConvertFrom-Json $squads = $config.squads.PSObject.Properties.Name - + # Create squad directories with placeholder SUMMARY.md foreach ($squad in $squads) { if (-not (Test-Path $squad)) { @@ -31,7 +31,7 @@ if ($Init) { } else { Write-Host " • $squad/ exists (skipped)" } - + $summaryPath = "$squad/SUMMARY.md" if (-not (Test-Path $summaryPath)) { "# $squad`n`n_No state published yet._" | Set-Content $summaryPath @@ -40,7 +40,7 @@ if ($Init) { Write-Host " • $summaryPath exists (skipped)" } } - + # Generate root README.md if (-not (Test-Path "README.md")) { $readme = @" @@ -65,7 +65,7 @@ State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``. } else { Write-Host " • README.md exists (skipped)" } - + Write-Host "" Write-Host "✅ Mesh state repository initialized" exit 0 diff --git a/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.sh b/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.sh index 802fd2d8d..e484e1a90 100644 --- a/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.sh +++ b/packages/squad-cli/templates/skills/distributed-mesh/sync-mesh.sh @@ -13,15 +13,15 @@ set -euo pipefail # Handle --init mode if [ "${1:-}" = "--init" ]; then MESH_JSON="${2:-mesh.json}" - + if [ ! -f "$MESH_JSON" ]; then echo "❌ $MESH_JSON not found" exit 1 fi - + echo "🚀 Initializing mesh state repository..." squads=$(jq -r '.squads | keys[]' "$MESH_JSON") - + # Create squad directories with placeholder SUMMARY.md for squad in $squads; do if [ ! -d "$squad" ]; then @@ -30,7 +30,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • $squad/ exists (skipped)" fi - + if [ ! -f "$squad/SUMMARY.md" ]; then echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md" echo " ✓ Created $squad/SUMMARY.md" @@ -38,7 +38,7 @@ if [ "${1:-}" = "--init" ]; then echo " • $squad/SUMMARY.md exists (skipped)" fi done - + # Generate root README.md if [ ! -f "README.md" ]; then { @@ -60,7 +60,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • README.md exists (skipped)" fi - + echo "" echo "✅ Mesh state repository initialized" exit 0 diff --git a/packages/squad-cli/templates/skills/secret-handling/SKILL.md b/packages/squad-cli/templates/skills/secret-handling/SKILL.md index b0576f879..b6c6b31b6 100644 --- a/packages/squad-cli/templates/skills/secret-handling/SKILL.md +++ b/packages/squad-cli/templates/skills/secret-handling/SKILL.md @@ -67,10 +67,10 @@ Spawned agents have read access to the entire repository, including `.env` files - Report to user: ``` 🚨 SECRET DETECTED — commit blocked - + File: .squad/decisions/inbox/river-db-config.md Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod - + This file contains credentials and MUST NOT be committed. Please remove the secret, replace with placeholder, and try again. ``` @@ -92,17 +92,17 @@ Spawned agents have read access to the entire repository, including `.env` files 2. **Alert the user:** ``` 🚨 CREDENTIAL LEAK DETECTED - + A secret was found in git history: Commit: abc1234 File: .squad/decisions/inbox/agent-config.md Pattern: API_KEY=sk-proj-... - + This requires immediate remediation: 1. Revoke the exposed credential (regenerate API key, rotate password) 2. Remove from git history (git filter-repo or BFG) 3. Force-push the cleaned history - + Do NOT proceed with new work until this is resolved. ``` 3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools @@ -139,7 +139,7 @@ Agent: (reads .env) → Writes to .squad/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 ``` diff --git a/packages/squad-cli/templates/skills/windows-compatibility/SKILL.md b/packages/squad-cli/templates/skills/windows-compatibility/SKILL.md index 6242b88c4..98fa750b3 100644 --- a/packages/squad-cli/templates/skills/windows-compatibility/SKILL.md +++ b/packages/squad-cli/templates/skills/windows-compatibility/SKILL.md @@ -36,7 +36,7 @@ Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platfo - **Pattern:** ```typescript const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin'; - + function pathStartsWith(fullPath: string, prefix: string): boolean { if (CASE_INSENSITIVE) { return fullPath.toLowerCase().startsWith(prefix.toLowerCase()); diff --git a/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md b/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md index 4128ff096..3c3cb2533 100644 --- a/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md +++ b/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md @@ -82,8 +82,8 @@ When a proposal invalidates existing wave structure: ``` ### 1. Terminal UI Library: `ink` (recommended) or alternatives? -**Recommendation:** `ink` -**Alternatives:** `blessed`, raw readline +**Recommendation:** `ink` +**Alternatives:** `blessed`, raw readline **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. **Needs sign-off from:** Product Lead (product direction), Runtime Engineer (runtime performance) @@ -101,8 +101,8 @@ When a proposal invalidates existing wave structure: ``` ### Risk 2: SDK Streaming Reliability -**Risk:** SDK streaming events might drop messages or arrive out of order. -**Likelihood:** Low (SDK is production-grade). +**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:** diff --git a/packages/squad-sdk/templates/skills/coordinator-response-mode/SKILL.md b/packages/squad-sdk/templates/skills/coordinator-response-mode/SKILL.md index 4dff3b800..a88829f4d 100644 --- a/packages/squad-sdk/templates/skills/coordinator-response-mode/SKILL.md +++ b/packages/squad-sdk/templates/skills/coordinator-response-mode/SKILL.md @@ -79,7 +79,7 @@ prompt: | WORKTREE_PATH: {worktree_path} WORKTREE_MODE: {true|false} **Requested by:** {current user name} - + {% if WORKTREE_MODE %} **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches. {% endif %} diff --git a/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md b/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md index d9242c44b..87f559659 100644 --- a/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md +++ b/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md @@ -8,10 +8,10 @@ source: "manual" # Skill: Cross-Machine Coordination Pattern -**Skill ID:** `cross-machine-coordination` -**Owner:** Ralph (Work Monitor) -**Squad Integration:** All agents -**Status:** Specification (ready for implementation) +**Skill ID:** `cross-machine-coordination` +**Owner:** Ralph (Work Monitor) +**Squad Integration:** All agents +**Status:** Specification (ready for implementation) --- diff --git a/packages/squad-sdk/templates/skills/cross-squad-communication/SKILL.md b/packages/squad-sdk/templates/skills/cross-squad-communication/SKILL.md index 9286d5fa2..0088d8308 100644 --- a/packages/squad-sdk/templates/skills/cross-squad-communication/SKILL.md +++ b/packages/squad-sdk/templates/skills/cross-squad-communication/SKILL.md @@ -139,7 +139,7 @@ $stallCount = 0 while ($proc -and -not $proc.HasExited) { Start-Sleep -Seconds 15 $currentSize = (Get-ChildItem $logDir -Recurse -File | Measure-Object -Property Length -Sum).Sum - + if ($currentSize -eq $lastSize) { $stallCount++ if ($stallCount -ge 4) { # 60s with no progress diff --git a/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.ps1 b/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.ps1 index 5f409ef37..0b6bc1980 100644 --- a/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.ps1 +++ b/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.ps1 @@ -18,11 +18,11 @@ if ($Init) { Write-Host "❌ $MeshJson not found" exit 1 } - + Write-Host "🚀 Initializing mesh state repository..." $config = Get-Content $MeshJson -Raw | ConvertFrom-Json $squads = $config.squads.PSObject.Properties.Name - + # Create squad directories with placeholder SUMMARY.md foreach ($squad in $squads) { if (-not (Test-Path $squad)) { @@ -31,7 +31,7 @@ if ($Init) { } else { Write-Host " • $squad/ exists (skipped)" } - + $summaryPath = "$squad/SUMMARY.md" if (-not (Test-Path $summaryPath)) { "# $squad`n`n_No state published yet._" | Set-Content $summaryPath @@ -40,7 +40,7 @@ if ($Init) { Write-Host " • $summaryPath exists (skipped)" } } - + # Generate root README.md if (-not (Test-Path "README.md")) { $readme = @" @@ -65,7 +65,7 @@ State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``. } else { Write-Host " • README.md exists (skipped)" } - + Write-Host "" Write-Host "✅ Mesh state repository initialized" exit 0 diff --git a/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.sh b/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.sh index 802fd2d8d..e484e1a90 100644 --- a/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.sh +++ b/packages/squad-sdk/templates/skills/distributed-mesh/sync-mesh.sh @@ -13,15 +13,15 @@ set -euo pipefail # Handle --init mode if [ "${1:-}" = "--init" ]; then MESH_JSON="${2:-mesh.json}" - + if [ ! -f "$MESH_JSON" ]; then echo "❌ $MESH_JSON not found" exit 1 fi - + echo "🚀 Initializing mesh state repository..." squads=$(jq -r '.squads | keys[]' "$MESH_JSON") - + # Create squad directories with placeholder SUMMARY.md for squad in $squads; do if [ ! -d "$squad" ]; then @@ -30,7 +30,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • $squad/ exists (skipped)" fi - + if [ ! -f "$squad/SUMMARY.md" ]; then echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md" echo " ✓ Created $squad/SUMMARY.md" @@ -38,7 +38,7 @@ if [ "${1:-}" = "--init" ]; then echo " • $squad/SUMMARY.md exists (skipped)" fi done - + # Generate root README.md if [ ! -f "README.md" ]; then { @@ -60,7 +60,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • README.md exists (skipped)" fi - + echo "" echo "✅ Mesh state repository initialized" exit 0 diff --git a/packages/squad-sdk/templates/skills/secret-handling/SKILL.md b/packages/squad-sdk/templates/skills/secret-handling/SKILL.md index b0576f879..b6c6b31b6 100644 --- a/packages/squad-sdk/templates/skills/secret-handling/SKILL.md +++ b/packages/squad-sdk/templates/skills/secret-handling/SKILL.md @@ -67,10 +67,10 @@ Spawned agents have read access to the entire repository, including `.env` files - Report to user: ``` 🚨 SECRET DETECTED — commit blocked - + File: .squad/decisions/inbox/river-db-config.md Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod - + This file contains credentials and MUST NOT be committed. Please remove the secret, replace with placeholder, and try again. ``` @@ -92,17 +92,17 @@ Spawned agents have read access to the entire repository, including `.env` files 2. **Alert the user:** ``` 🚨 CREDENTIAL LEAK DETECTED - + A secret was found in git history: Commit: abc1234 File: .squad/decisions/inbox/agent-config.md Pattern: API_KEY=sk-proj-... - + This requires immediate remediation: 1. Revoke the exposed credential (regenerate API key, rotate password) 2. Remove from git history (git filter-repo or BFG) 3. Force-push the cleaned history - + Do NOT proceed with new work until this is resolved. ``` 3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools @@ -139,7 +139,7 @@ Agent: (reads .env) → Writes to .squad/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 ``` diff --git a/packages/squad-sdk/templates/skills/windows-compatibility/SKILL.md b/packages/squad-sdk/templates/skills/windows-compatibility/SKILL.md index 6242b88c4..98fa750b3 100644 --- a/packages/squad-sdk/templates/skills/windows-compatibility/SKILL.md +++ b/packages/squad-sdk/templates/skills/windows-compatibility/SKILL.md @@ -36,7 +36,7 @@ Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platfo - **Pattern:** ```typescript const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin'; - + function pathStartsWith(fullPath: string, prefix: string): boolean { if (CASE_INSENSITIVE) { return fullPath.toLowerCase().startsWith(prefix.toLowerCase()); diff --git a/templates/skills/architectural-proposals/SKILL.md b/templates/skills/architectural-proposals/SKILL.md index 4128ff096..3c3cb2533 100644 --- a/templates/skills/architectural-proposals/SKILL.md +++ b/templates/skills/architectural-proposals/SKILL.md @@ -82,8 +82,8 @@ When a proposal invalidates existing wave structure: ``` ### 1. Terminal UI Library: `ink` (recommended) or alternatives? -**Recommendation:** `ink` -**Alternatives:** `blessed`, raw readline +**Recommendation:** `ink` +**Alternatives:** `blessed`, raw readline **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. **Needs sign-off from:** Product Lead (product direction), Runtime Engineer (runtime performance) @@ -101,8 +101,8 @@ When a proposal invalidates existing wave structure: ``` ### Risk 2: SDK Streaming Reliability -**Risk:** SDK streaming events might drop messages or arrive out of order. -**Likelihood:** Low (SDK is production-grade). +**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:** diff --git a/templates/skills/coordinator-response-mode/SKILL.md b/templates/skills/coordinator-response-mode/SKILL.md index 4dff3b800..a88829f4d 100644 --- a/templates/skills/coordinator-response-mode/SKILL.md +++ b/templates/skills/coordinator-response-mode/SKILL.md @@ -79,7 +79,7 @@ prompt: | WORKTREE_PATH: {worktree_path} WORKTREE_MODE: {true|false} **Requested by:** {current user name} - + {% if WORKTREE_MODE %} **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches. {% endif %} diff --git a/templates/skills/cross-machine-coordination/SKILL.md b/templates/skills/cross-machine-coordination/SKILL.md index d9242c44b..87f559659 100644 --- a/templates/skills/cross-machine-coordination/SKILL.md +++ b/templates/skills/cross-machine-coordination/SKILL.md @@ -8,10 +8,10 @@ source: "manual" # Skill: Cross-Machine Coordination Pattern -**Skill ID:** `cross-machine-coordination` -**Owner:** Ralph (Work Monitor) -**Squad Integration:** All agents -**Status:** Specification (ready for implementation) +**Skill ID:** `cross-machine-coordination` +**Owner:** Ralph (Work Monitor) +**Squad Integration:** All agents +**Status:** Specification (ready for implementation) --- diff --git a/templates/skills/cross-squad-communication/SKILL.md b/templates/skills/cross-squad-communication/SKILL.md index 9286d5fa2..0088d8308 100644 --- a/templates/skills/cross-squad-communication/SKILL.md +++ b/templates/skills/cross-squad-communication/SKILL.md @@ -139,7 +139,7 @@ $stallCount = 0 while ($proc -and -not $proc.HasExited) { Start-Sleep -Seconds 15 $currentSize = (Get-ChildItem $logDir -Recurse -File | Measure-Object -Property Length -Sum).Sum - + if ($currentSize -eq $lastSize) { $stallCount++ if ($stallCount -ge 4) { # 60s with no progress diff --git a/templates/skills/distributed-mesh/sync-mesh.ps1 b/templates/skills/distributed-mesh/sync-mesh.ps1 index 5f409ef37..0b6bc1980 100644 --- a/templates/skills/distributed-mesh/sync-mesh.ps1 +++ b/templates/skills/distributed-mesh/sync-mesh.ps1 @@ -18,11 +18,11 @@ if ($Init) { Write-Host "❌ $MeshJson not found" exit 1 } - + Write-Host "🚀 Initializing mesh state repository..." $config = Get-Content $MeshJson -Raw | ConvertFrom-Json $squads = $config.squads.PSObject.Properties.Name - + # Create squad directories with placeholder SUMMARY.md foreach ($squad in $squads) { if (-not (Test-Path $squad)) { @@ -31,7 +31,7 @@ if ($Init) { } else { Write-Host " • $squad/ exists (skipped)" } - + $summaryPath = "$squad/SUMMARY.md" if (-not (Test-Path $summaryPath)) { "# $squad`n`n_No state published yet._" | Set-Content $summaryPath @@ -40,7 +40,7 @@ if ($Init) { Write-Host " • $summaryPath exists (skipped)" } } - + # Generate root README.md if (-not (Test-Path "README.md")) { $readme = @" @@ -65,7 +65,7 @@ State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``. } else { Write-Host " • README.md exists (skipped)" } - + Write-Host "" Write-Host "✅ Mesh state repository initialized" exit 0 diff --git a/templates/skills/distributed-mesh/sync-mesh.sh b/templates/skills/distributed-mesh/sync-mesh.sh index 802fd2d8d..e484e1a90 100644 --- a/templates/skills/distributed-mesh/sync-mesh.sh +++ b/templates/skills/distributed-mesh/sync-mesh.sh @@ -13,15 +13,15 @@ set -euo pipefail # Handle --init mode if [ "${1:-}" = "--init" ]; then MESH_JSON="${2:-mesh.json}" - + if [ ! -f "$MESH_JSON" ]; then echo "❌ $MESH_JSON not found" exit 1 fi - + echo "🚀 Initializing mesh state repository..." squads=$(jq -r '.squads | keys[]' "$MESH_JSON") - + # Create squad directories with placeholder SUMMARY.md for squad in $squads; do if [ ! -d "$squad" ]; then @@ -30,7 +30,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • $squad/ exists (skipped)" fi - + if [ ! -f "$squad/SUMMARY.md" ]; then echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md" echo " ✓ Created $squad/SUMMARY.md" @@ -38,7 +38,7 @@ if [ "${1:-}" = "--init" ]; then echo " • $squad/SUMMARY.md exists (skipped)" fi done - + # Generate root README.md if [ ! -f "README.md" ]; then { @@ -60,7 +60,7 @@ if [ "${1:-}" = "--init" ]; then else echo " • README.md exists (skipped)" fi - + echo "" echo "✅ Mesh state repository initialized" exit 0 diff --git a/templates/skills/external-comms/SKILL.md b/templates/skills/external-comms/SKILL.md index 9745028f2..f1f0c4848 100644 --- a/templates/skills/external-comms/SKILL.md +++ b/templates/skills/external-comms/SKILL.md @@ -1,329 +1,329 @@ ---- -name: "external-comms" +--- +name: "external-comms" description: "Workflow for scanning, drafting, and presenting community responses with a human review gate" -domain: "community, communication, workflow" -confidence: "low" +domain: "community, communication, workflow" +confidence: "low" source: "manual (external communications workflow)" -tools: - - name: "github-mcp-server-list_issues" - description: "List open issues for scan candidates and lightweight triage" - when: "Use for recent open issue scans before thread-level review" - - name: "github-mcp-server-issue_read" - description: "Read the full issue, comments, and labels before drafting" +tools: + - name: "github-mcp-server-list_issues" + description: "List open issues for scan candidates and lightweight triage" + when: "Use for recent open issue scans before thread-level review" + - name: "github-mcp-server-issue_read" + description: "Read the full issue, comments, and labels before drafting" when: "Use after selecting a candidate so the communications owner has complete thread context" - - name: "github-mcp-server-search_issues" - description: "Search for candidate issues or prior squad responses" - when: "Use when filtering by keywords, labels, or duplicate response checks" - - name: "gh CLI" - description: "Fallback for GitHub issue comments and discussions workflows" - when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete" ---- - -## Context - -Phase 1 is **draft-only mode**. - + - name: "github-mcp-server-search_issues" + description: "Search for candidate issues or prior squad responses" + when: "Use when filtering by keywords, labels, or duplicate response checks" + - name: "gh CLI" + description: "Fallback for GitHub issue comments and discussions workflows" + when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete" +--- + +## Context + +Phase 1 is **draft-only mode**. + - The communications owner scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. - **Human review gate is mandatory** — the communications owner never posts autonomously. -- Every action is logged to `.squad/comms/audit/`. +- Every action is logged to `.squad/comms/audit/`. - This workflow is triggered manually only ("check community") — no automated activation in Phase 1. - -## Patterns - -### 1. Scan - -Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions. - -- Include **open** issues and discussions only. -- Filter for items with **no squad team response**. -- Limit to items created in the last 7 days. -- Exclude items labeled `squad:internal` or `wontfix`. -- Include discussions **and** issues in the same sweep. -- Phase 1 scope is **issues and discussions only** — do not draft PR replies. - -### Discussion Handling (Phase 1) - -Discussions use the GitHub Discussions API, which differs from issues: - -- **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions -- **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) + +## Patterns + +### 1. Scan + +Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions. + +- Include **open** issues and discussions only. +- Filter for items with **no squad team response**. +- Limit to items created in the last 7 days. +- Exclude items labeled `squad:internal` or `wontfix`. +- Include discussions **and** issues in the same sweep. +- Phase 1 scope is **issues and discussions only** — do not draft PR replies. + +### Discussion Handling (Phase 1) + +Discussions use the GitHub Discussions API, which differs from issues: + +- **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions +- **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) - **Answers vs comments:** In Q&A discussions, the communications owner drafts an "answer" (not a comment). The human marks it as accepted answer after posting. -- **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. - -### 2. Classify - -Determine the response type before drafting. - -- Welcome (new contributor) -- Troubleshooting (bug/help) -- Feature guidance (feature request/how-to) -- Redirect (wrong repo/scope) -- Acknowledgment (confirmed, no fix) -- Closing (resolved) -- Technical uncertainty (unknown cause) -- Empathetic disagreement (pushback on a decision or design) -- Information request (need more reproduction details or context) - -### Template Selection Guide - -| Signal in Issue/Discussion | → Response Type | Template | -|---------------------------|-----------------|----------| -| New contributor (0 prior issues) | Welcome | T1 | -| Error message, stack trace, "doesn't work" | Troubleshooting | T2 | -| "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 | -| Wrong repo, out of scope for Squad | Redirect | T4 | -| Confirmed bug, no fix available yet | Acknowledgment | T5 | -| Fix shipped, PR merged that resolves issue | Closing | T6 | -| Unclear cause, needs investigation | Technical Uncertainty | T7 | -| Author disagrees with a decision or design | Empathetic Disagreement | T8 | -| Need more reproduction info or context | Information Request | T9 | - -Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary. - -### Confidence Classification - -| Confidence | Criteria | Example | -|-----------|----------|---------| -| 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" | -| 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) | -| 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" | - -**Auto-escalation rules:** -- Any mention of competitors → 🔴 -- Any mention of pricing/licensing → 🔴 -- Author has >3 follow-up comments without resolution → 🔴 -- Question references a closed-wontfix issue → 🔴 - -### 3. Draft - -Use the humanizer skill for every draft. - -- Complete **Thread-Read Verification** before writing. -- Read the **full thread**, including all comments, before writing. -- Select the matching template from the **Template Selection Guide** and record the template ID in the review notes. -- Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it. -- Validate the draft against the humanizer anti-patterns. -- Flag long threads (`>10` comments) with `⚠️`. - -### Thread-Read Verification - +- **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. + +### 2. Classify + +Determine the response type before drafting. + +- Welcome (new contributor) +- Troubleshooting (bug/help) +- Feature guidance (feature request/how-to) +- Redirect (wrong repo/scope) +- Acknowledgment (confirmed, no fix) +- Closing (resolved) +- Technical uncertainty (unknown cause) +- Empathetic disagreement (pushback on a decision or design) +- Information request (need more reproduction details or context) + +### Template Selection Guide + +| Signal in Issue/Discussion | → Response Type | Template | +|---------------------------|-----------------|----------| +| New contributor (0 prior issues) | Welcome | T1 | +| Error message, stack trace, "doesn't work" | Troubleshooting | T2 | +| "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 | +| Wrong repo, out of scope for Squad | Redirect | T4 | +| Confirmed bug, no fix available yet | Acknowledgment | T5 | +| Fix shipped, PR merged that resolves issue | Closing | T6 | +| Unclear cause, needs investigation | Technical Uncertainty | T7 | +| Author disagrees with a decision or design | Empathetic Disagreement | T8 | +| Need more reproduction info or context | Information Request | T9 | + +Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary. + +### Confidence Classification + +| Confidence | Criteria | Example | +|-----------|----------|---------| +| 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" | +| 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) | +| 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" | + +**Auto-escalation rules:** +- Any mention of competitors → 🔴 +- Any mention of pricing/licensing → 🔴 +- Author has >3 follow-up comments without resolution → 🔴 +- Question references a closed-wontfix issue → 🔴 + +### 3. Draft + +Use the humanizer skill for every draft. + +- Complete **Thread-Read Verification** before writing. +- Read the **full thread**, including all comments, before writing. +- Select the matching template from the **Template Selection Guide** and record the template ID in the review notes. +- Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it. +- Validate the draft against the humanizer anti-patterns. +- Flag long threads (`>10` comments) with `⚠️`. + +### Thread-Read Verification + Before drafting, the communications owner MUST verify complete thread coverage: - -1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. -2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. -3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}" -4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary -5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column - -### 4. Present - -Show drafts for review in this exact format: - -```text + +1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. +2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. +3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}" +4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary +5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column + +### 4. Present + +Show drafts for review in this exact format: + +```text 📝 Community Response Drafts -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -| # | Item | Author | Type | Confidence | Read | Preview | -|---|------|--------|------|------------|------|---------| -| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." | - -Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review - -Full drafts below ▼ -``` - -Each full draft must begin with the thread summary line: -`Thread: {N} comments, last activity {date}, {summary of key points}` - -### 5. Human Action - -Wait for explicit human direction before anything is posted. - +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +Each full draft must begin with the thread summary line: +`Thread: {N} comments, last activity {date}, {summary of key points}` + +### 5. Human Action + +Wait for explicit human direction before anything is posted. + - `comms approve 1 3` — approve drafts 1 and 3 - `comms edit 2` — edit draft 2 - `comms skip` — skip all -- `banana` — freeze all pending (safe word) - -### Rollback — Bad Post Recovery - -If a posted response turns out to be wrong, inappropriate, or needs correction: - -1. **Delete the comment:** - - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` - - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` -2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content +- `banana` — freeze all pending (safe word) + +### Rollback — Bad Post Recovery + +If a posted response turns out to be wrong, inappropriate, or needs correction: + +1. **Delete the comment:** + - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` + - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` +2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content 3. **Draft replacement** (if needed): The communications owner drafts a corrected response and repeats the normal review cycle -4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case - -**Safe word — `banana`:** -- Immediately freezes all pending drafts in the review queue +4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case + +**Safe word — `banana`:** +- Immediately freezes all pending drafts in the review queue - No new scans or drafts until `comms resume` is issued -- Audit entry logged with halter identity and reason - -### 6. Post - -After approval: - -- Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. +- Audit entry logged with halter identity and reason + +### 6. Post + +After approval: + +- Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. - The communications owner helps by preparing the CLI command. -- Write the audit entry after the posting action. - -### 7. Audit - -Log every action. - -- Location: `.squad/comms/audit/{timestamp}.md` -- Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table -- Universal required fields: `timestamp`, `action` -- All other fields are conditional on the action type - -## Examples - -These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it. - -### Example scan command - -```bash -gh issue list --state open --json number,title,author,labels,comments --limit 20 -``` - -### Example review table - -```text +- Write the audit entry after the posting action. + +### 7. Audit + +Log every action. + +- Location: `.squad/comms/audit/{timestamp}.md` +- Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table +- Universal required fields: `timestamp`, `action` +- All other fields are conditional on the action type + +## Examples + +These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it. + +### Example scan command + +```bash +gh issue list --state open --json number,title,author,labels,comments --limit 20 +``` + +### Example review table + +```text 📝 Community Response Drafts -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -| # | Item | Author | Type | Confidence | Read | Preview | -|---|------|--------|------|------------|------|---------| -| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." | -| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." | -| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." | - -Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review - -Full drafts below ▼ -``` - -### Example audit entry (post action) - -```markdown ---- -timestamp: "2026-03-16T21:30:00Z" -action: "post" -item_number: 426 -draft_id: 1 -reviewer: "@bradygaster" ---- - -## Context (draft, approve, edit, skip, post, delete actions) -- Thread depth: 3 -- Response type: welcome -- Confidence: 🟢 -- Long thread flag: false - -## Draft Content (draft, edit, post actions) -Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install. - -Hey @newdev! Welcome to Squad 👋 Thanks for opening this. -We reproduced the issue in preview builds and we're checking the regression point now. -Let us know if you can share the command you ran right before the failure. - -## Post Result (post, delete actions) -https://github.com/bradygaster/squad/issues/426#issuecomment-123456 -``` - -### T1 — Welcome - -```text -Hey {author}! Welcome to Squad 👋 Thanks for opening this. -{specific acknowledgment or first answer} -Let us know if you have questions — happy to help! -``` - -### T2 — Troubleshooting - -```text -Thanks for the detailed report, {author}! -Here's what we think is happening: {explanation} -{steps or workaround} -Let us know if that helps, or if you're seeing something different. -``` - -### T3 — Feature Guidance - -```text -Great question! {context on current state} -{guidance or workaround} -We've noted this as a potential improvement — {tracking info if applicable}. -``` - -### T4 — Redirect - -```text -Thanks for reaching out! This one is actually better suited for {correct location}. -{brief explanation of why} -Feel free to open it there — they'll be able to help! -``` - -### T5 — Acknowledgment - -```text -Good catch, {author}. We've confirmed this is a real issue. -{what we know so far} -We'll update this thread when we have a fix. Thanks for flagging it! -``` - -### T6 — Closing - -```text -This should be resolved in {version/PR}! 🎉 -{brief summary of what changed} -Thanks for reporting this, {author} — it made Squad better. -``` - -### T7 — Technical Uncertainty - -```text -Interesting find, {author}. We're not 100% sure what's causing this yet. -Here's what we've ruled out: {list} -We'd love more context if you have it — {specific ask}. -We'll dig deeper and update this thread. -``` - -### T8 — Empathetic Disagreement - -```text -We hear you, {author}. That's a fair concern. - -The current design choice was driven by {reason}. We know it's not ideal for every use case. - -{what alternatives exist or what trade-off was made} - -If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here! -``` - -### T9 — Information Request - -```text -Thanks for reporting this, {author}! - -To help us dig into this, could you share: -- {specific ask 1} -- {specific ask 2} -- {specific ask 3, if applicable} - -That context will help us narrow down what's happening. Appreciate it! -``` - -## Anti-Patterns - -- ❌ Posting without human review (NEVER — this is the cardinal rule) -- ❌ Drafting without reading full thread (context is everything) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Item | Author | Type | Confidence | Read | Preview | +|---|------|--------|------|------------|------|---------| +| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." | +| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." | +| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." | + +Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review + +Full drafts below ▼ +``` + +### Example audit entry (post action) + +```markdown +--- +timestamp: "2026-03-16T21:30:00Z" +action: "post" +item_number: 426 +draft_id: 1 +reviewer: "@bradygaster" +--- + +## Context (draft, approve, edit, skip, post, delete actions) +- Thread depth: 3 +- Response type: welcome +- Confidence: 🟢 +- Long thread flag: false + +## Draft Content (draft, edit, post actions) +Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install. + +Hey @newdev! Welcome to Squad 👋 Thanks for opening this. +We reproduced the issue in preview builds and we're checking the regression point now. +Let us know if you can share the command you ran right before the failure. + +## Post Result (post, delete actions) +https://github.com/bradygaster/squad/issues/426#issuecomment-123456 +``` + +### T1 — Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{specific acknowledgment or first answer} +Let us know if you have questions — happy to help! +``` + +### T2 — Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### T3 — Feature Guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### T4 — Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### T5 — Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### T6 — Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### T7 — Technical Uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +### T8 — Empathetic Disagreement + +```text +We hear you, {author}. That's a fair concern. + +The current design choice was driven by {reason}. We know it's not ideal for every use case. + +{what alternatives exist or what trade-off was made} + +If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here! +``` + +### T9 — Information Request + +```text +Thanks for reporting this, {author}! + +To help us dig into this, could you share: +- {specific ask 1} +- {specific ask 2} +- {specific ask 3, if applicable} + +That context will help us narrow down what's happening. Appreciate it! +``` + +## Anti-Patterns + +- ❌ Posting without human review (NEVER — this is the cardinal rule) +- ❌ Drafting without reading full thread (context is everything) - ❌ Ignoring confidence flags (🔴 items need Lead or human review) -- ❌ Scanning closed issues (only open items) -- ❌ Responding to issues labeled `squad:internal` or `wontfix` -- ❌ Skipping audit logging (every action must be recorded) -- ❌ Drafting for issues where a squad member already responded (avoid duplicates) -- ❌ Drafting pull request responses in Phase 1 (issues/discussions only) -- ❌ Treating templates like loose examples instead of reusable drafting assets -- ❌ Asking for more info without specific requests +- ❌ Scanning closed issues (only open items) +- ❌ Responding to issues labeled `squad:internal` or `wontfix` +- ❌ Skipping audit logging (every action must be recorded) +- ❌ Drafting for issues where a squad member already responded (avoid duplicates) +- ❌ Drafting pull request responses in Phase 1 (issues/discussions only) +- ❌ Treating templates like loose examples instead of reusable drafting assets +- ❌ Asking for more info without specific requests diff --git a/templates/skills/gh-auth-isolation/SKILL.md b/templates/skills/gh-auth-isolation/SKILL.md index e4ac1abda..a639835b1 100644 --- a/templates/skills/gh-auth-isolation/SKILL.md +++ b/templates/skills/gh-auth-isolation/SKILL.md @@ -1,183 +1,183 @@ ---- -name: "gh-auth-isolation" -description: "Safely manage multiple GitHub identities (EMU + personal) in agent workflows" -domain: "security, github-integration, authentication, multi-account" -confidence: "high" -source: "earned (production usage across 50+ sessions with EMU corp + personal GitHub accounts)" -tools: - - name: "gh" - description: "GitHub CLI for authenticated operations" - when: "When accessing GitHub resources requiring authentication" ---- - -## Context - -Many developers use GitHub through an Enterprise Managed User (EMU) account at work while maintaining a personal GitHub account for open-source contributions. AI agents spawned by Squad inherit the shell's default `gh` authentication — which is usually the EMU account. This causes failures when agents try to push to personal repos, create PRs on forks, or interact with resources outside the enterprise org. - -This skill teaches agents how to detect the active identity, switch contexts safely, and avoid mixing credentials across operations. - -## Patterns - -### Detect Current Identity - -Before any GitHub operation, check which account is active: - -```bash -gh auth status -``` - -Look for: -- `Logged in to github.com as USERNAME` — the active account -- `Token scopes: ...` — what permissions are available -- Multiple accounts will show separate entries - -### Extract a Specific Account's Token - -When you need to operate as a specific user (not the default): - -```bash -# Get the personal account token (by username) -gh auth token --user personaluser - -# Get the EMU account token -gh auth token --user corpalias_enterprise -``` - -**Use case:** Push to a personal fork while the default `gh` auth is the EMU account. - -### Push to Personal Repos from EMU Shell - -The most common scenario: your shell defaults to the EMU account, but you need to push to a personal GitHub repo. - -```bash -# 1. Extract the personal token -$token = gh auth token --user personaluser - -# 2. Push using token-authenticated HTTPS -git push https://personaluser:$token@github.com/personaluser/repo.git branch-name -``` - -**Why this works:** `gh auth token --user` reads from `gh`'s credential store without switching the active account. The token is used inline for a single operation and never persisted. - -### Create PRs on Personal Forks - -When the default `gh` context is EMU but you need to create a PR from a personal fork: - -```bash -# Option 1: Use --repo flag (works if token has access) -gh pr create --repo upstream/repo --head personaluser:branch --title "..." --body "..." - -# Option 2: Temporarily set GH_TOKEN for one command -$env:GH_TOKEN = $(gh auth token --user personaluser) -gh pr create --repo upstream/repo --head personaluser:branch --title "..." -Remove-Item Env:\GH_TOKEN -``` - -### Config Directory Isolation (Advanced) - -For complete isolation between accounts, use separate `gh` config directories: - -```bash -# Personal account operations -$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" -gh auth login # Login with personal account (one-time setup) -gh repo clone personaluser/repo - -# EMU account operations (default) -Remove-Item Env:\GH_CONFIG_DIR -gh auth status # Back to EMU account -``` - -**Setup (one-time):** -```bash -# Create isolated config for personal account -mkdir ~/.config/gh-public -$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" -gh auth login --web --git-protocol https -``` - -### Shell Aliases for Quick Switching - -Add to your shell profile for convenience: - -```powershell -# PowerShell profile -function ghp { $env:GH_CONFIG_DIR = "$HOME/.config/gh-public"; gh @args; Remove-Item Env:\GH_CONFIG_DIR } -function ghe { gh @args } # Default EMU - -# Usage: -# ghp repo clone personaluser/repo # Uses personal account -# ghe issue list # Uses EMU account -``` - -```bash -# Bash/Zsh profile -alias ghp='GH_CONFIG_DIR=~/.config/gh-public gh' -alias ghe='gh' - -# Usage: -# ghp repo clone personaluser/repo -# ghe issue list -``` - -## Examples - -### ✓ Correct: Agent pushes blog post to personal GitHub Pages - -```powershell -# Agent needs to push to personaluser.github.io (personal repo) -# Default gh auth is corpalias_enterprise (EMU) - -$token = gh auth token --user personaluser -git remote set-url origin https://personaluser:$token@github.com/personaluser/personaluser.github.io.git -git push origin main - -# Clean up — don't leave token in remote URL -git remote set-url origin https://github.com/personaluser/personaluser.github.io.git -``` - -### ✓ Correct: Agent creates a PR from personal fork to upstream - -```powershell -# Fork: personaluser/squad, Upstream: bradygaster/squad -# Agent is on branch contrib/fix-docs in the fork clone - -git push origin contrib/fix-docs # Pushes to fork (may need token auth) - -# Create PR targeting upstream -gh pr create --repo bradygaster/squad --head personaluser:contrib/fix-docs ` - --title "docs: fix installation guide" ` - --body "Fixes #123" -``` - -### ✗ Incorrect: Blindly pushing with wrong account - -```bash -# BAD: Agent assumes default gh auth works for personal repos -git push origin main -# ERROR: Permission denied — EMU account has no access to personal repo - -# BAD: Hardcoding tokens in scripts -git push https://personaluser:ghp_xxxxxxxxxxxx@github.com/personaluser/repo.git main -# SECURITY RISK: Token exposed in command history and process list -``` - -### ✓ Correct: Check before you push - -```bash -# Always verify which account has access before operations -gh auth status -# If wrong account, use token extraction: -$token = gh auth token --user personaluser -git push https://personaluser:$token@github.com/personaluser/repo.git main -``` - -## Anti-Patterns - -- ❌ **Hardcoding tokens** in scripts, environment variables, or committed files. Use `gh auth token --user` to extract at runtime. -- ❌ **Assuming the default `gh` auth works** for all repos. EMU accounts can't access personal repos and vice versa. -- ❌ **Switching `gh auth login`** globally mid-session. This changes the default for ALL processes and can break parallel agents. -- ❌ **Storing personal tokens in `.env`** or `.squad/` files. These get committed by Scribe. Use `gh`'s credential store. -- ❌ **Ignoring token cleanup** after inline HTTPS pushes. Always reset the remote URL to avoid persisting tokens. -- ❌ **Using `gh auth switch`** in multi-agent sessions. One agent switching affects all others sharing the shell. -- ❌ **Mixing EMU and personal operations** in the same git clone. Use separate clones or explicit remote URLs per operation. +--- +name: "gh-auth-isolation" +description: "Safely manage multiple GitHub identities (EMU + personal) in agent workflows" +domain: "security, github-integration, authentication, multi-account" +confidence: "high" +source: "earned (production usage across 50+ sessions with EMU corp + personal GitHub accounts)" +tools: + - name: "gh" + description: "GitHub CLI for authenticated operations" + when: "When accessing GitHub resources requiring authentication" +--- + +## Context + +Many developers use GitHub through an Enterprise Managed User (EMU) account at work while maintaining a personal GitHub account for open-source contributions. AI agents spawned by Squad inherit the shell's default `gh` authentication — which is usually the EMU account. This causes failures when agents try to push to personal repos, create PRs on forks, or interact with resources outside the enterprise org. + +This skill teaches agents how to detect the active identity, switch contexts safely, and avoid mixing credentials across operations. + +## Patterns + +### Detect Current Identity + +Before any GitHub operation, check which account is active: + +```bash +gh auth status +``` + +Look for: +- `Logged in to github.com as USERNAME` — the active account +- `Token scopes: ...` — what permissions are available +- Multiple accounts will show separate entries + +### Extract a Specific Account's Token + +When you need to operate as a specific user (not the default): + +```bash +# Get the personal account token (by username) +gh auth token --user personaluser + +# Get the EMU account token +gh auth token --user corpalias_enterprise +``` + +**Use case:** Push to a personal fork while the default `gh` auth is the EMU account. + +### Push to Personal Repos from EMU Shell + +The most common scenario: your shell defaults to the EMU account, but you need to push to a personal GitHub repo. + +```bash +# 1. Extract the personal token +$token = gh auth token --user personaluser + +# 2. Push using token-authenticated HTTPS +git push https://personaluser:$token@github.com/personaluser/repo.git branch-name +``` + +**Why this works:** `gh auth token --user` reads from `gh`'s credential store without switching the active account. The token is used inline for a single operation and never persisted. + +### Create PRs on Personal Forks + +When the default `gh` context is EMU but you need to create a PR from a personal fork: + +```bash +# Option 1: Use --repo flag (works if token has access) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." --body "..." + +# Option 2: Temporarily set GH_TOKEN for one command +$env:GH_TOKEN = $(gh auth token --user personaluser) +gh pr create --repo upstream/repo --head personaluser:branch --title "..." +Remove-Item Env:\GH_TOKEN +``` + +### Config Directory Isolation (Advanced) + +For complete isolation between accounts, use separate `gh` config directories: + +```bash +# Personal account operations +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login # Login with personal account (one-time setup) +gh repo clone personaluser/repo + +# EMU account operations (default) +Remove-Item Env:\GH_CONFIG_DIR +gh auth status # Back to EMU account +``` + +**Setup (one-time):** +```bash +# Create isolated config for personal account +mkdir ~/.config/gh-public +$env:GH_CONFIG_DIR = "$HOME/.config/gh-public" +gh auth login --web --git-protocol https +``` + +### Shell Aliases for Quick Switching + +Add to your shell profile for convenience: + +```powershell +# PowerShell profile +function ghp { $env:GH_CONFIG_DIR = "$HOME/.config/gh-public"; gh @args; Remove-Item Env:\GH_CONFIG_DIR } +function ghe { gh @args } # Default EMU + +# Usage: +# ghp repo clone personaluser/repo # Uses personal account +# ghe issue list # Uses EMU account +``` + +```bash +# Bash/Zsh profile +alias ghp='GH_CONFIG_DIR=~/.config/gh-public gh' +alias ghe='gh' + +# Usage: +# ghp repo clone personaluser/repo +# ghe issue list +``` + +## Examples + +### ✓ Correct: Agent pushes blog post to personal GitHub Pages + +```powershell +# Agent needs to push to personaluser.github.io (personal repo) +# Default gh auth is corpalias_enterprise (EMU) + +$token = gh auth token --user personaluser +git remote set-url origin https://personaluser:$token@github.com/personaluser/personaluser.github.io.git +git push origin main + +# Clean up — don't leave token in remote URL +git remote set-url origin https://github.com/personaluser/personaluser.github.io.git +``` + +### ✓ Correct: Agent creates a PR from personal fork to upstream + +```powershell +# Fork: personaluser/squad, Upstream: bradygaster/squad +# Agent is on branch contrib/fix-docs in the fork clone + +git push origin contrib/fix-docs # Pushes to fork (may need token auth) + +# Create PR targeting upstream +gh pr create --repo bradygaster/squad --head personaluser:contrib/fix-docs ` + --title "docs: fix installation guide" ` + --body "Fixes #123" +``` + +### ✗ Incorrect: Blindly pushing with wrong account + +```bash +# BAD: Agent assumes default gh auth works for personal repos +git push origin main +# ERROR: Permission denied — EMU account has no access to personal repo + +# BAD: Hardcoding tokens in scripts +git push https://personaluser:ghp_xxxxxxxxxxxx@github.com/personaluser/repo.git main +# SECURITY RISK: Token exposed in command history and process list +``` + +### ✓ Correct: Check before you push + +```bash +# Always verify which account has access before operations +gh auth status +# If wrong account, use token extraction: +$token = gh auth token --user personaluser +git push https://personaluser:$token@github.com/personaluser/repo.git main +``` + +## Anti-Patterns + +- ❌ **Hardcoding tokens** in scripts, environment variables, or committed files. Use `gh auth token --user` to extract at runtime. +- ❌ **Assuming the default `gh` auth works** for all repos. EMU accounts can't access personal repos and vice versa. +- ❌ **Switching `gh auth login`** globally mid-session. This changes the default for ALL processes and can break parallel agents. +- ❌ **Storing personal tokens in `.env`** or `.squad/` files. These get committed by Scribe. Use `gh`'s credential store. +- ❌ **Ignoring token cleanup** after inline HTTPS pushes. Always reset the remote URL to avoid persisting tokens. +- ❌ **Using `gh auth switch`** in multi-agent sessions. One agent switching affects all others sharing the shell. +- ❌ **Mixing EMU and personal operations** in the same git clone. Use separate clones or explicit remote URLs per operation. diff --git a/templates/skills/humanizer/SKILL.md b/templates/skills/humanizer/SKILL.md index 0932510c2..8d9be269b 100644 --- a/templates/skills/humanizer/SKILL.md +++ b/templates/skills/humanizer/SKILL.md @@ -1,105 +1,105 @@ ---- -name: "humanizer" -description: "Tone enforcement patterns for external-facing community responses" -domain: "communication, tone, community" -confidence: "low" -source: "manual (external communications workflow)" ---- - -## Context - -Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. - -- Tone must be warm, helpful, and human-sounding — never robotic or corporate. -- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. -- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. - -## Patterns - -1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!") -2. **Active voice** — "We're looking into this" not "This is being investigated" -3. **Second person** — Address the person directly ("you" not "the user") -4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:" -5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues" -6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!" -7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required" -8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence -9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting -10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold) -11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning -12. **Information request** — Ask for specific details, not open-ended "can you provide more info?" -13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link - -## Examples - -### 1. Welcome - -```text -Hey {author}! Welcome to Squad 👋 Thanks for opening this. -{substantive response} -Let us know if you have questions — happy to help! -``` - -### 2. Troubleshooting - -```text -Thanks for the detailed report, {author}! -Here's what we think is happening: {explanation} -{steps or workaround} -Let us know if that helps, or if you're seeing something different. -``` - -### 3. Feature guidance - -```text -Great question! {context on current state} -{guidance or workaround} -We've noted this as a potential improvement — {tracking info if applicable}. -``` - -### 4. Redirect - -```text -Thanks for reaching out! This one is actually better suited for {correct location}. -{brief explanation of why} -Feel free to open it there — they'll be able to help! -``` - -### 5. Acknowledgment - -```text -Good catch, {author}. We've confirmed this is a real issue. -{what we know so far} -We'll update this thread when we have a fix. Thanks for flagging it! -``` - -### 6. Closing - -```text -This should be resolved in {version/PR}! 🎉 -{brief summary of what changed} -Thanks for reporting this, {author} — it made Squad better. -``` - -### 7. Technical uncertainty - -```text -Interesting find, {author}. We're not 100% sure what's causing this yet. -Here's what we've ruled out: {list} -We'd love more context if you have it — {specific ask}. -We'll dig deeper and update this thread. -``` - -## Anti-Patterns - -- ❌ Corporate speak: "We appreciate your patience as we investigate this matter" -- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..." -- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked" -- ❌ Dismissive: "This works as designed" without empathy -- ❌ Over-promising: "We'll ship this next week" without commitment from the team -- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance -- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" -- ❌ Excessive emoji: More than 1-2 emoji per response -- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead -- ❌ Link-dumping: Pasting URLs without context ("See: https://...") -- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information +--- +name: "humanizer" +description: "Tone enforcement patterns for external-facing community responses" +domain: "communication, tone, community" +confidence: "low" +source: "manual (external communications workflow)" +--- + +## Context + +Use this skill whenever the communications owner drafts external-facing responses for issues or discussions. + +- Tone must be warm, helpful, and human-sounding — never robotic or corporate. +- The repository's communication policy applies everywhere: **Humanized tone is mandatory**. +- This applies to **all external-facing content** drafted by the communications owner in Phase 1 issues/discussions workflows. + +## Patterns + +1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!") +2. **Active voice** — "We're looking into this" not "This is being investigated" +3. **Second person** — Address the person directly ("you" not "the user") +4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:" +5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues" +6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!" +7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required" +8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence +9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting +10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold) +11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning +12. **Information request** — Ask for specific details, not open-ended "can you provide more info?" +13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link + +## Examples + +### 1. Welcome + +```text +Hey {author}! Welcome to Squad 👋 Thanks for opening this. +{substantive response} +Let us know if you have questions — happy to help! +``` + +### 2. Troubleshooting + +```text +Thanks for the detailed report, {author}! +Here's what we think is happening: {explanation} +{steps or workaround} +Let us know if that helps, or if you're seeing something different. +``` + +### 3. Feature guidance + +```text +Great question! {context on current state} +{guidance or workaround} +We've noted this as a potential improvement — {tracking info if applicable}. +``` + +### 4. Redirect + +```text +Thanks for reaching out! This one is actually better suited for {correct location}. +{brief explanation of why} +Feel free to open it there — they'll be able to help! +``` + +### 5. Acknowledgment + +```text +Good catch, {author}. We've confirmed this is a real issue. +{what we know so far} +We'll update this thread when we have a fix. Thanks for flagging it! +``` + +### 6. Closing + +```text +This should be resolved in {version/PR}! 🎉 +{brief summary of what changed} +Thanks for reporting this, {author} — it made Squad better. +``` + +### 7. Technical uncertainty + +```text +Interesting find, {author}. We're not 100% sure what's causing this yet. +Here's what we've ruled out: {list} +We'd love more context if you have it — {specific ask}. +We'll dig deeper and update this thread. +``` + +## Anti-Patterns + +- ❌ Corporate speak: "We appreciate your patience as we investigate this matter" +- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..." +- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked" +- ❌ Dismissive: "This works as designed" without empathy +- ❌ Over-promising: "We'll ship this next week" without commitment from the team +- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance +- ❌ Robot signatures: "Best regards, Communications Team" or "Sincerely, The Squad Team" +- ❌ Excessive emoji: More than 1-2 emoji per response +- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead +- ❌ Link-dumping: Pasting URLs without context ("See: https://...") +- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information diff --git a/templates/skills/pr-screenshots/SKILL.md b/templates/skills/pr-screenshots/SKILL.md index fc93e8f77..7425ecf9e 100644 --- a/templates/skills/pr-screenshots/SKILL.md +++ b/templates/skills/pr-screenshots/SKILL.md @@ -1,149 +1,149 @@ ---- -name: "pr-screenshots" -description: "Capture Playwright screenshots and embed them in GitHub PR descriptions" -domain: "pull-requests, visual-review, docs, testing" -confidence: "high" -source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)" ---- - -## Context - -When a PR includes visual changes (docs sites, UI components, generated pages), reviewers -need to see what the PR delivers without checking out the branch. Screenshots belong in -the **PR description body**, not as committed files and not as text descriptions. - -Use this skill whenever: -- A PR touches docs site pages (Astro, Starlight, etc.) -- A PR adds or changes UI components -- A PR generates visual artifacts (TypeDoc, Storybook, diagrams) -- Playwright tests already capture screenshots as part of testing - -## Patterns - -### 1. Capture screenshots with Playwright - -If Playwright tests already exist and produce screenshots, reuse those. Otherwise, -write a minimal capture script: - -```javascript -// scripts/capture-pr-screenshots.mjs -import { chromium } from 'playwright'; - -const browser = await chromium.launch(); -const page = await browser.newPage({ viewport: { width: 1280, height: 720 } }); - -const screenshots = [ - { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' }, - { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' }, -]; - -for (const { url, name } of screenshots) { - await page.goto(url, { waitUntil: 'networkidle' }); - await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false }); -} - -await browser.close(); -``` - -### 2. Host screenshots on a temporary branch - -GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary -images directly. Use a temporary orphan branch to host the images: - -```powershell -# Save current branch -$currentBranch = git branch --show-current - -# Create orphan branch with only screenshot files -git checkout --orphan screenshots-temp -git reset -git add screenshots/*.png -git commit -m "screenshots for PR review" -git push origin screenshots-temp --force - -# Build raw URLs -$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" -# Each image: $base/{name}.png - -# Return to working branch -git checkout -f $currentBranch -``` - -### 3. Embed in PR description - -Use `gh pr edit` with the raw URLs embedded as markdown images: - -```powershell -$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" - -gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @" -## {PR Title} - -### What this PR delivers -- {bullet points of changes} - ---- - -### Screenshots - -#### {Page/Feature Name} -![{alt text}]($base/{name}.png) - -#### {Another Page} -![{alt text}]($base/{another-name}.png) - ---- - -### To verify locally -```bash -{commands to run locally} -``` -"@ -``` - -### 4. Cleanup after merge - -After the PR is merged, delete the temporary branch: - -```bash -git push origin --delete screenshots-temp -``` - -### 5. Gitignore screenshots locally - -Screenshots are build artifacts — never commit them to feature branches: - -```gitignore -# PR screenshots (hosted on temp branch, not committed to features) -screenshots/ -docs/tests/screenshots/ -``` - -## Examples - -### Example: Docs site PR with 3 pages - -1. Start dev server: `cd docs && npm run dev` -2. Run Playwright tests (they capture screenshots as a side effect) -3. Push screenshots to `screenshots-temp` branch -4. Update PR body with embedded `![...]()` image references -5. Reviewer sees the pages inline without checking out the branch - -### Example: Reusing existing Playwright test screenshots - -If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`: - -```powershell -cd docs && npx playwright test tests/api-reference.spec.mjs -# Screenshots now at docs/tests/screenshots/*.png -# Push those to screenshots-temp and embed in PR -``` - -## Anti-Patterns - -- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale -- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting -- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads -- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern -- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see -- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge +--- +name: "pr-screenshots" +description: "Capture Playwright screenshots and embed them in GitHub PR descriptions" +domain: "pull-requests, visual-review, docs, testing" +confidence: "high" +source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)" +--- + +## Context + +When a PR includes visual changes (docs sites, UI components, generated pages), reviewers +need to see what the PR delivers without checking out the branch. Screenshots belong in +the **PR description body**, not as committed files and not as text descriptions. + +Use this skill whenever: +- A PR touches docs site pages (Astro, Starlight, etc.) +- A PR adds or changes UI components +- A PR generates visual artifacts (TypeDoc, Storybook, diagrams) +- Playwright tests already capture screenshots as part of testing + +## Patterns + +### 1. Capture screenshots with Playwright + +If Playwright tests already exist and produce screenshots, reuse those. Otherwise, +write a minimal capture script: + +```javascript +// scripts/capture-pr-screenshots.mjs +import { chromium } from 'playwright'; + +const browser = await chromium.launch(); +const page = await browser.newPage({ viewport: { width: 1280, height: 720 } }); + +const screenshots = [ + { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' }, + { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' }, +]; + +for (const { url, name } of screenshots) { + await page.goto(url, { waitUntil: 'networkidle' }); + await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false }); +} + +await browser.close(); +``` + +### 2. Host screenshots on a temporary branch + +GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary +images directly. Use a temporary orphan branch to host the images: + +```powershell +# Save current branch +$currentBranch = git branch --show-current + +# Create orphan branch with only screenshot files +git checkout --orphan screenshots-temp +git reset +git add screenshots/*.png +git commit -m "screenshots for PR review" +git push origin screenshots-temp --force + +# Build raw URLs +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" +# Each image: $base/{name}.png + +# Return to working branch +git checkout -f $currentBranch +``` + +### 3. Embed in PR description + +Use `gh pr edit` with the raw URLs embedded as markdown images: + +```powershell +$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots" + +gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @" +## {PR Title} + +### What this PR delivers +- {bullet points of changes} + +--- + +### Screenshots + +#### {Page/Feature Name} +![{alt text}]($base/{name}.png) + +#### {Another Page} +![{alt text}]($base/{another-name}.png) + +--- + +### To verify locally +```bash +{commands to run locally} +``` +"@ +``` + +### 4. Cleanup after merge + +After the PR is merged, delete the temporary branch: + +```bash +git push origin --delete screenshots-temp +``` + +### 5. Gitignore screenshots locally + +Screenshots are build artifacts — never commit them to feature branches: + +```gitignore +# PR screenshots (hosted on temp branch, not committed to features) +screenshots/ +docs/tests/screenshots/ +``` + +## Examples + +### Example: Docs site PR with 3 pages + +1. Start dev server: `cd docs && npm run dev` +2. Run Playwright tests (they capture screenshots as a side effect) +3. Push screenshots to `screenshots-temp` branch +4. Update PR body with embedded `![...]()` image references +5. Reviewer sees the pages inline without checking out the branch + +### Example: Reusing existing Playwright test screenshots + +If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`: + +```powershell +cd docs && npx playwright test tests/api-reference.spec.mjs +# Screenshots now at docs/tests/screenshots/*.png +# Push those to screenshots-temp and embed in PR +``` + +## Anti-Patterns + +- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale +- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting +- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads +- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern +- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see +- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge diff --git a/templates/skills/secret-handling/SKILL.md b/templates/skills/secret-handling/SKILL.md index b0576f879..b6c6b31b6 100644 --- a/templates/skills/secret-handling/SKILL.md +++ b/templates/skills/secret-handling/SKILL.md @@ -67,10 +67,10 @@ Spawned agents have read access to the entire repository, including `.env` files - Report to user: ``` 🚨 SECRET DETECTED — commit blocked - + File: .squad/decisions/inbox/river-db-config.md Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod - + This file contains credentials and MUST NOT be committed. Please remove the secret, replace with placeholder, and try again. ``` @@ -92,17 +92,17 @@ Spawned agents have read access to the entire repository, including `.env` files 2. **Alert the user:** ``` 🚨 CREDENTIAL LEAK DETECTED - + A secret was found in git history: Commit: abc1234 File: .squad/decisions/inbox/agent-config.md Pattern: API_KEY=sk-proj-... - + This requires immediate remediation: 1. Revoke the exposed credential (regenerate API key, rotate password) 2. Remove from git history (git filter-repo or BFG) 3. Force-push the cleaned history - + Do NOT proceed with new work until this is resolved. ``` 3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools @@ -139,7 +139,7 @@ Agent: (reads .env) → Writes to .squad/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 ``` diff --git a/templates/skills/windows-compatibility/SKILL.md b/templates/skills/windows-compatibility/SKILL.md index 6242b88c4..98fa750b3 100644 --- a/templates/skills/windows-compatibility/SKILL.md +++ b/templates/skills/windows-compatibility/SKILL.md @@ -36,7 +36,7 @@ Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platfo - **Pattern:** ```typescript const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin'; - + function pathStartsWith(fullPath: string, prefix: string): boolean { if (CASE_INSENSITIVE) { return fullPath.toLowerCase().startsWith(prefix.toLowerCase()); From 2ba29c29a6763a04e7b48e1e077fbe0e5fef0537 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 15:31:47 -0700 Subject: [PATCH 06/12] test: use explicit empty secondary fixture Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/ralph-triage.test.ts | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/test/ralph-triage.test.ts b/test/ralph-triage.test.ts index 98d50a1e4..79fa24628 100644 --- a/test/ralph-triage.test.ts +++ b/test/ralph-triage.test.ts @@ -227,8 +227,17 @@ describe('ralph triage parser helpers', () => { }); it('handles "—" as secondary (should be null)', () => { - const modules = parseModuleOwnership(ROUTING_MD); - expect(modules.find((module) => module.modulePath === 'src/ralph/')?.secondary).toBeNull(); + const markdown = [ + '## Module Ownership', + '', + '| Module | Primary | Secondary |', + '|--------|---------|-----------|', + '| `src/ralph/` | Runtime Engineer | — |', + ].join('\n'); + + expect(parseModuleOwnership(markdown)).toEqual([ + { modulePath: 'src/ralph/', primary: 'Runtime Engineer', secondary: null }, + ]); }); it('returns empty array for missing section', () => { From 1d4ca994f70b6b162a92f26d87bde9f5d8577377 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 15:37:22 -0700 Subject: [PATCH 07/12] fix: prevent unsafe blanket staging guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../skills/e2e-template-testing/SKILL.md | 3 ++- .../skills/gh-aw-enlistment/SKILL.md | 5 ++-- .squad-templates/skills/git-workflow/SKILL.md | 7 ++++-- .../skills/e2e-template-testing/SKILL.md | 3 ++- .../skills/gh-aw-enlistment/SKILL.md | 5 ++-- .../templates/skills/git-workflow/SKILL.md | 7 ++++-- .../skills/e2e-template-testing/SKILL.md | 3 ++- .../skills/gh-aw-enlistment/SKILL.md | 5 ++-- .../templates/skills/git-workflow/SKILL.md | 7 ++++-- scripts/security-review.mjs | 10 ++++---- .../skills/e2e-template-testing/SKILL.md | 3 ++- templates/skills/gh-aw-enlistment/SKILL.md | 5 ++-- templates/skills/git-workflow/SKILL.md | 7 ++++-- test/scripts/security-review.test.ts | 24 +++++++++++++++++++ 14 files changed, 66 insertions(+), 28 deletions(-) diff --git a/.squad-templates/skills/e2e-template-testing/SKILL.md b/.squad-templates/skills/e2e-template-testing/SKILL.md index 316d20868..d1b38d94e 100644 --- a/.squad-templates/skills/e2e-template-testing/SKILL.md +++ b/.squad-templates/skills/e2e-template-testing/SKILL.md @@ -108,7 +108,8 @@ echo "# Test Project" > README.md echo '{"name":"test-project","version":"1.0.0"}' > package.json mkdir src echo "export function hello() { return 'world' }" > src/index.ts -git add -A && git commit -m "init: test project" +git add -- README.md package.json src/index.ts +git commit -m "init: test project" ``` Keep the project small — you only need enough for the coordinator to recognize a diff --git a/.squad-templates/skills/gh-aw-enlistment/SKILL.md b/.squad-templates/skills/gh-aw-enlistment/SKILL.md index 7f1f0d4ba..63477b185 100644 --- a/.squad-templates/skills/gh-aw-enlistment/SKILL.md +++ b/.squad-templates/skills/gh-aw-enlistment/SKILL.md @@ -311,9 +311,8 @@ gh aw add reports a third secret: `ACME_DEPLOY_KEY`. gh api --method PUT "repos/acme/widgets/actions/permissions/workflow" ... gh pr create --base main ... # wrong if the default branch isn't `main` -# BAD: stages logs, .vscode settings, and anything else that changed -git add -A -git commit -m "add squad" +# BAD: blanket staging captures logs, editor settings, and unrelated changes +# Stage only the generated bootstrap paths listed above. ``` ### ✗ Incorrect: skipping the final strict compile or auto-merging diff --git a/.squad-templates/skills/git-workflow/SKILL.md b/.squad-templates/skills/git-workflow/SKILL.md index bfa0b8596..b244fed5e 100644 --- a/.squad-templates/skills/git-workflow/SKILL.md +++ b/.squad-templates/skills/git-workflow/SKILL.md @@ -98,8 +98,11 @@ Each agent operates inside its worktree exactly like the single-issue workflow: ```bash cd ../squad-195 -# Work normally — commits, tests, pushes -git add -A && git commit -m "fix: stamp bug (#195)" +# Stage only the files changed for this issue, then inspect the commit contents +git add -- path/to/intentionally-changed-file +git diff --cached --stat +git diff --cached +git commit -m "fix: stamp bug (#195)" git push -u origin squad/195-fix-stamp-bug # Create PR targeting dev diff --git a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md index 316d20868..d1b38d94e 100644 --- a/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md @@ -108,7 +108,8 @@ echo "# Test Project" > README.md echo '{"name":"test-project","version":"1.0.0"}' > package.json mkdir src echo "export function hello() { return 'world' }" > src/index.ts -git add -A && git commit -m "init: test project" +git add -- README.md package.json src/index.ts +git commit -m "init: test project" ``` Keep the project small — you only need enough for the coordinator to recognize a diff --git a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md index 7f1f0d4ba..63477b185 100644 --- a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md @@ -311,9 +311,8 @@ gh aw add reports a third secret: `ACME_DEPLOY_KEY`. gh api --method PUT "repos/acme/widgets/actions/permissions/workflow" ... gh pr create --base main ... # wrong if the default branch isn't `main` -# BAD: stages logs, .vscode settings, and anything else that changed -git add -A -git commit -m "add squad" +# BAD: blanket staging captures logs, editor settings, and unrelated changes +# Stage only the generated bootstrap paths listed above. ``` ### ✗ Incorrect: skipping the final strict compile or auto-merging diff --git a/packages/squad-cli/templates/skills/git-workflow/SKILL.md b/packages/squad-cli/templates/skills/git-workflow/SKILL.md index bfa0b8596..b244fed5e 100644 --- a/packages/squad-cli/templates/skills/git-workflow/SKILL.md +++ b/packages/squad-cli/templates/skills/git-workflow/SKILL.md @@ -98,8 +98,11 @@ Each agent operates inside its worktree exactly like the single-issue workflow: ```bash cd ../squad-195 -# Work normally — commits, tests, pushes -git add -A && git commit -m "fix: stamp bug (#195)" +# Stage only the files changed for this issue, then inspect the commit contents +git add -- path/to/intentionally-changed-file +git diff --cached --stat +git diff --cached +git commit -m "fix: stamp bug (#195)" git push -u origin squad/195-fix-stamp-bug # Create PR targeting dev diff --git a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md index 316d20868..d1b38d94e 100644 --- a/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md +++ b/packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md @@ -108,7 +108,8 @@ echo "# Test Project" > README.md echo '{"name":"test-project","version":"1.0.0"}' > package.json mkdir src echo "export function hello() { return 'world' }" > src/index.ts -git add -A && git commit -m "init: test project" +git add -- README.md package.json src/index.ts +git commit -m "init: test project" ``` Keep the project small — you only need enough for the coordinator to recognize a diff --git a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md index 7f1f0d4ba..63477b185 100644 --- a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md @@ -311,9 +311,8 @@ gh aw add reports a third secret: `ACME_DEPLOY_KEY`. gh api --method PUT "repos/acme/widgets/actions/permissions/workflow" ... gh pr create --base main ... # wrong if the default branch isn't `main` -# BAD: stages logs, .vscode settings, and anything else that changed -git add -A -git commit -m "add squad" +# BAD: blanket staging captures logs, editor settings, and unrelated changes +# Stage only the generated bootstrap paths listed above. ``` ### ✗ Incorrect: skipping the final strict compile or auto-merging diff --git a/packages/squad-sdk/templates/skills/git-workflow/SKILL.md b/packages/squad-sdk/templates/skills/git-workflow/SKILL.md index bfa0b8596..b244fed5e 100644 --- a/packages/squad-sdk/templates/skills/git-workflow/SKILL.md +++ b/packages/squad-sdk/templates/skills/git-workflow/SKILL.md @@ -98,8 +98,11 @@ Each agent operates inside its worktree exactly like the single-issue workflow: ```bash cd ../squad-195 -# Work normally — commits, tests, pushes -git add -A && git commit -m "fix: stamp bug (#195)" +# Stage only the files changed for this issue, then inspect the commit contents +git add -- path/to/intentionally-changed-file +git diff --cached --stat +git diff --cached +git commit -m "fix: stamp bug (#195)" git push -u origin squad/195-fix-stamp-bug # Create PR targeting dev diff --git a/scripts/security-review.mjs b/scripts/security-review.mjs index 6edc328b1..64bab0509 100644 --- a/scripts/security-review.mjs +++ b/scripts/security-review.mjs @@ -193,17 +193,19 @@ const UNSAFE_GIT_EXCLUDED_PATHS = [ ]; const GIT_UNSAFE_PATTERNS = [ - { pattern: /git\s+add\s+\./, label: 'git add .' }, - { pattern: /git\s+add\s+-A/, label: 'git add -A' }, - { pattern: /git\s+commit\s+-a/, label: 'git commit -a' }, - { pattern: /git\s+push\s+--force/, label: 'git push --force' }, + { pattern: /git\s+add\s+\.(?=\s|$|[;&|])/, label: 'git add .' }, + { pattern: /git\s+add\s+-A(?=\s|$|[;&|])/, label: 'git add -A' }, + { pattern: /git\s+commit\s+-a(?=\s|$|[;&|])/, label: 'git commit -a' }, + { pattern: /git\s+push\s+--force(?!-with-lease)(?=\s|$|[;&|])/, label: 'git push --force' }, { pattern: /--force-with-lease/, label: 'git push --force-with-lease' }, ]; +const UNSAFE_GIT_PROHIBITION = /\b(?:never|do not|don't|avoid)\b|❌/i; for (const file of changedFiles) { if (UNSAFE_GIT_EXCLUDED_PATHS.some((p) => p.test(file))) continue; const added = addedByFile.get(file) || []; for (const { line, text } of added) { + if (UNSAFE_GIT_PROHIBITION.test(text)) continue; for (const { pattern, label } of GIT_UNSAFE_PATTERNS) { if (pattern.test(text)) { findings.push({ diff --git a/templates/skills/e2e-template-testing/SKILL.md b/templates/skills/e2e-template-testing/SKILL.md index 316d20868..d1b38d94e 100644 --- a/templates/skills/e2e-template-testing/SKILL.md +++ b/templates/skills/e2e-template-testing/SKILL.md @@ -108,7 +108,8 @@ echo "# Test Project" > README.md echo '{"name":"test-project","version":"1.0.0"}' > package.json mkdir src echo "export function hello() { return 'world' }" > src/index.ts -git add -A && git commit -m "init: test project" +git add -- README.md package.json src/index.ts +git commit -m "init: test project" ``` Keep the project small — you only need enough for the coordinator to recognize a diff --git a/templates/skills/gh-aw-enlistment/SKILL.md b/templates/skills/gh-aw-enlistment/SKILL.md index 7f1f0d4ba..63477b185 100644 --- a/templates/skills/gh-aw-enlistment/SKILL.md +++ b/templates/skills/gh-aw-enlistment/SKILL.md @@ -311,9 +311,8 @@ gh aw add reports a third secret: `ACME_DEPLOY_KEY`. gh api --method PUT "repos/acme/widgets/actions/permissions/workflow" ... gh pr create --base main ... # wrong if the default branch isn't `main` -# BAD: stages logs, .vscode settings, and anything else that changed -git add -A -git commit -m "add squad" +# BAD: blanket staging captures logs, editor settings, and unrelated changes +# Stage only the generated bootstrap paths listed above. ``` ### ✗ Incorrect: skipping the final strict compile or auto-merging diff --git a/templates/skills/git-workflow/SKILL.md b/templates/skills/git-workflow/SKILL.md index bfa0b8596..b244fed5e 100644 --- a/templates/skills/git-workflow/SKILL.md +++ b/templates/skills/git-workflow/SKILL.md @@ -98,8 +98,11 @@ Each agent operates inside its worktree exactly like the single-issue workflow: ```bash cd ../squad-195 -# Work normally — commits, tests, pushes -git add -A && git commit -m "fix: stamp bug (#195)" +# Stage only the files changed for this issue, then inspect the commit contents +git add -- path/to/intentionally-changed-file +git diff --cached --stat +git diff --cached +git commit -m "fix: stamp bug (#195)" git push -u origin squad/195-fix-stamp-bug # Create PR targeting dev diff --git a/test/scripts/security-review.test.ts b/test/scripts/security-review.test.ts index 412419ba8..b71886055 100644 --- a/test/scripts/security-review.test.ts +++ b/test/scripts/security-review.test.ts @@ -78,4 +78,28 @@ describe('security review unsafe git exclusions', () => { ), ).toBe(true); }); + + it('does not treat path-scoped staging as git add dot', () => { + const result = runSecurityReview( + '.github/agents/example.agent.md', + 'git add .squad/cross-machine/tasks/\n', + ); + + expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(false); + }); + + it('does not report explicit prohibitions as unsafe instructions', () => { + const result = runSecurityReview( + '.github/agents/example.agent.md', + 'Never use `git add -A`; stage explicit paths instead.\n', + ); + + expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(false); + }); + + it('reports executable blanket staging commands', () => { + const result = runSecurityReview('.github/agents/example.agent.md', 'git add -A\n'); + + expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(true); + }); }); From 7a8f687896346264e85bede362f1ad573e72dc0b Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 16:03:02 -0700 Subject: [PATCH 08/12] fix: keep unsafe git detection command-aware Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- scripts/security-review.mjs | 5 +++-- test/scripts/security-review.test.ts | 9 +++++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/scripts/security-review.mjs b/scripts/security-review.mjs index 64bab0509..ad495df13 100644 --- a/scripts/security-review.mjs +++ b/scripts/security-review.mjs @@ -205,9 +205,10 @@ for (const file of changedFiles) { if (UNSAFE_GIT_EXCLUDED_PATHS.some((p) => p.test(file))) continue; const added = addedByFile.get(file) || []; for (const { line, text } of added) { - if (UNSAFE_GIT_PROHIBITION.test(text)) continue; for (const { pattern, label } of GIT_UNSAFE_PATTERNS) { - if (pattern.test(text)) { + const match = pattern.exec(text); + const textBeforeCommand = match ? text.slice(0, match.index) : ''; + if (match && !UNSAFE_GIT_PROHIBITION.test(textBeforeCommand)) { findings.push({ category: 'unsafe-git', severity: 'error', diff --git a/test/scripts/security-review.test.ts b/test/scripts/security-review.test.ts index b71886055..817382b43 100644 --- a/test/scripts/security-review.test.ts +++ b/test/scripts/security-review.test.ts @@ -102,4 +102,13 @@ describe('security review unsafe git exclusions', () => { expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(true); }); + + it('does not let a trailing comment suppress an unsafe command', () => { + const result = runSecurityReview( + '.github/agents/example.agent.md', + 'git add -A # avoid orphaned files\n', + ); + + expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(true); + }); }); From 0f69801e3a0009312e06a74d1d30377a5f900d13 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 16:04:04 -0700 Subject: [PATCH 09/12] test: avoid scanner self-reporting fixtures Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/scripts/security-review.test.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/test/scripts/security-review.test.ts b/test/scripts/security-review.test.ts index 817382b43..e8c5f09c0 100644 --- a/test/scripts/security-review.test.ts +++ b/test/scripts/security-review.test.ts @@ -98,15 +98,17 @@ describe('security review unsafe git exclusions', () => { }); it('reports executable blanket staging commands', () => { - const result = runSecurityReview('.github/agents/example.agent.md', 'git add -A\n'); + const command = ['git add ', '-A\n'].join(''); + const result = runSecurityReview('.github/agents/example.agent.md', command); expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(true); }); it('does not let a trailing comment suppress an unsafe command', () => { + const command = ['git add ', '-A # avoid orphaned files\n'].join(''); const result = runSecurityReview( '.github/agents/example.agent.md', - 'git add -A # avoid orphaned files\n', + command, ); expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(true); From 8ca08ebe179862f2b48a9189ffc1faaf8f2ab987 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 18:01:46 -0700 Subject: [PATCH 10/12] ci: run typecheck and eslint in test job Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/squad-ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/squad-ci.yml b/.github/workflows/squad-ci.yml index c99abf2fb..1e278a376 100644 --- a/.github/workflows/squad-ci.yml +++ b/.github/workflows/squad-ci.yml @@ -178,6 +178,10 @@ jobs: GH_TOKEN: ${{ github.token }} - name: Build run: npm run build + - name: Type-check + run: npm run lint + - name: Lint source and tests + run: npm run lint:eslint - name: Run tests run: npm test From e2c1f3cb9c31203b07c983ecb8afae6c1d39f253 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 23:47:46 -0700 Subject: [PATCH 11/12] fix: align routing and security review parity Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/squad-triage.yml | 2 +- .squad-templates/ralph-triage.js | 160 ++++++--------- .squad-templates/workflows/squad-triage.yml | 2 +- packages/squad-cli/templates/ralph-triage.js | 160 ++++++--------- .../templates/workflows/squad-triage.yml | 2 +- packages/squad-sdk/src/ralph/triage.ts | 191 ++++++++---------- packages/squad-sdk/templates/ralph-triage.js | 160 ++++++--------- .../templates/workflows/squad-triage.yml | 2 +- scripts/security-review.mjs | 27 ++- templates/ralph-triage.js | 160 ++++++--------- templates/workflows/squad-triage.yml | 2 +- test/ralph-triage.test.ts | 121 +++++++++-- test/scripts/security-review.test.ts | 44 +++- 13 files changed, 504 insertions(+), 529 deletions(-) diff --git a/.github/workflows/squad-triage.yml b/.github/workflows/squad-triage.yml index c3c88f3cb..beb97805c 100644 --- a/.github/workflows/squad-triage.yml +++ b/.github/workflows/squad-triage.yml @@ -199,7 +199,7 @@ jobs: ]); function tokens(value) { - return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(?= 2 ? 'high' : 'medium', - }; - } - } - - const roleMatch = findRoleKeywordMatch(issueText, roster); - if (roleMatch) { return { - agent: roleMatch.agent, - reason: roleMatch.reason, - source: 'role-keyword', - confidence: 'medium', + agent: bestRule.agent, + reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, + source: 'routing-rule', + confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', }; } @@ -268,7 +255,7 @@ function cleanCell(value) { function splitKeywords(examplesCell) { if (!examplesCell) return []; return examplesCell - .split(',') + .split(/[,;]+/) .map((keyword) => cleanCell(keyword)) .filter((keyword) => keyword.length > 0); } @@ -295,33 +282,24 @@ function normalizeName(value) { .trim(); } +function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); +} + function findMember(target, roster) { - const normalizedTarget = normalizeName(target); + const normalizedTarget = normalizeRouteDestination(target); if (!normalizedTarget) return null; - for (const member of roster) { - if (normalizeName(member.name) === normalizedTarget) return member; - } - - for (const member of roster) { - if (normalizeName(member.role) === normalizedTarget) return member; - } - - for (const member of roster) { - const memberName = normalizeName(member.name); - if (normalizedTarget.includes(memberName) || memberName.includes(normalizedTarget)) { - return member; - } - } - - for (const member of roster) { - const memberRole = normalizeName(member.role); - if (normalizedTarget.includes(memberRole) || memberRole.includes(normalizedTarget)) { - return member; - } - } - - return null; + return roster.find((member) => + normalizeRouteDestination(member.name) === normalizedTarget + ) || null; } function findBestModuleMatch(issueText, modules) { @@ -342,64 +320,58 @@ function findBestModuleMatch(issueText, modules) { return best; } -function findBestRuleMatch(issueText, rules) { - let best = null; - let bestScore = 0; - - for (const rule of rules) { - const matchedKeywords = rule.keywords - .map((keyword) => keyword.toLowerCase()) - .filter((keyword) => keyword.length > 0 && issueText.includes(keyword)); - - if (matchedKeywords.length === 0) continue; - - const score = - matchedKeywords.length * 100 + matchedKeywords.reduce((sum, keyword) => sum + keyword.length, 0); - if (score > bestScore) { - best = { rule, matchedKeywords }; - bestScore = score; - } - } - - return best; +function findBestRuleMatch(issueText, rules, roster) { + const scoredRoutes = rules.flatMap((rule) => { + const agent = findMember(rule.agentName, roster); + if (!agent) return []; + const match = routeMatch(issueText, rule); + return match.score > 0 ? [{ rule, agent, ...match }] : []; + }).sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) return null; + + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter((candidate) => candidate.score === bestScore); + const bestAgents = new Set(bestRoutes.map((candidate) => + normalizeRouteDestination(candidate.agent.name) + )); + return bestAgents.size === 1 ? bestRoutes[0] : null; } -function findRoleKeywordMatch(issueText, roster) { - for (const member of roster) { - const role = member.role.toLowerCase(); - - if ( - (role.includes('frontend') || role.includes('ui')) && - (issueText.includes('ui') || issueText.includes('frontend') || issueText.includes('css')) - ) { - return { agent: member, reason: 'Matched frontend/UI role keywords' }; - } - - if ( - (role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || issueText.includes('database')) - ) { - return { agent: member, reason: 'Matched backend/API role keywords' }; - } +function routeMatch(issueText, rule) { + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', + ]); + const tokens = (value) => + value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(? + needle.length > 0 && + needle.length <= haystack.length && + haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); - if ( - (role.includes('test') || role.includes('qa')) && - (issueText.includes('test') || issueText.includes('bug') || issueText.includes('fix')) - ) { - return { agent: member, reason: 'Matched testing/QA role keywords' }; - } - } + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter((token) => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.keywords] + .flatMap((phrase) => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + const matchedKeywords = rawPhrases.filter((phrase) => + containsPhrase(issueTokens, tokens(phrase)) + ); + const score = matchedKeywords.reduce((best, phrase) => + Math.max(best, tokens(phrase).length * 100), 0); - return null; + return { score, matchedKeywords }; } function findLeadFallback(roster) { - return ( - roster.find((member) => { - const role = member.role.toLowerCase(); - return role.includes('lead') || role.includes('architect'); - }) || null - ); + const hasRoleToken = (member, token) => + (member.role.toLowerCase().match(/[a-z0-9]+/g) || []).includes(token); + return roster.find((member) => hasRoleToken(member, 'lead')) || + roster.find((member) => hasRoleToken(member, 'architect')) || + null; } function parseOwnerRepoFromRemote(remoteUrl) { diff --git a/.squad-templates/workflows/squad-triage.yml b/.squad-templates/workflows/squad-triage.yml index 579f74d29..21e67f70c 100644 --- a/.squad-templates/workflows/squad-triage.yml +++ b/.squad-templates/workflows/squad-triage.yml @@ -166,7 +166,7 @@ jobs: ]); function tokens(value) { - return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(?= 2 ? 'high' : 'medium', - }; - } - } - - const roleMatch = findRoleKeywordMatch(issueText, roster); - if (roleMatch) { return { - agent: roleMatch.agent, - reason: roleMatch.reason, - source: 'role-keyword', - confidence: 'medium', + agent: bestRule.agent, + reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, + source: 'routing-rule', + confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', }; } @@ -268,7 +255,7 @@ function cleanCell(value) { function splitKeywords(examplesCell) { if (!examplesCell) return []; return examplesCell - .split(',') + .split(/[,;]+/) .map((keyword) => cleanCell(keyword)) .filter((keyword) => keyword.length > 0); } @@ -295,33 +282,24 @@ function normalizeName(value) { .trim(); } +function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); +} + function findMember(target, roster) { - const normalizedTarget = normalizeName(target); + const normalizedTarget = normalizeRouteDestination(target); if (!normalizedTarget) return null; - for (const member of roster) { - if (normalizeName(member.name) === normalizedTarget) return member; - } - - for (const member of roster) { - if (normalizeName(member.role) === normalizedTarget) return member; - } - - for (const member of roster) { - const memberName = normalizeName(member.name); - if (normalizedTarget.includes(memberName) || memberName.includes(normalizedTarget)) { - return member; - } - } - - for (const member of roster) { - const memberRole = normalizeName(member.role); - if (normalizedTarget.includes(memberRole) || memberRole.includes(normalizedTarget)) { - return member; - } - } - - return null; + return roster.find((member) => + normalizeRouteDestination(member.name) === normalizedTarget + ) || null; } function findBestModuleMatch(issueText, modules) { @@ -342,64 +320,58 @@ function findBestModuleMatch(issueText, modules) { return best; } -function findBestRuleMatch(issueText, rules) { - let best = null; - let bestScore = 0; - - for (const rule of rules) { - const matchedKeywords = rule.keywords - .map((keyword) => keyword.toLowerCase()) - .filter((keyword) => keyword.length > 0 && issueText.includes(keyword)); - - if (matchedKeywords.length === 0) continue; - - const score = - matchedKeywords.length * 100 + matchedKeywords.reduce((sum, keyword) => sum + keyword.length, 0); - if (score > bestScore) { - best = { rule, matchedKeywords }; - bestScore = score; - } - } - - return best; +function findBestRuleMatch(issueText, rules, roster) { + const scoredRoutes = rules.flatMap((rule) => { + const agent = findMember(rule.agentName, roster); + if (!agent) return []; + const match = routeMatch(issueText, rule); + return match.score > 0 ? [{ rule, agent, ...match }] : []; + }).sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) return null; + + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter((candidate) => candidate.score === bestScore); + const bestAgents = new Set(bestRoutes.map((candidate) => + normalizeRouteDestination(candidate.agent.name) + )); + return bestAgents.size === 1 ? bestRoutes[0] : null; } -function findRoleKeywordMatch(issueText, roster) { - for (const member of roster) { - const role = member.role.toLowerCase(); - - if ( - (role.includes('frontend') || role.includes('ui')) && - (issueText.includes('ui') || issueText.includes('frontend') || issueText.includes('css')) - ) { - return { agent: member, reason: 'Matched frontend/UI role keywords' }; - } - - if ( - (role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || issueText.includes('database')) - ) { - return { agent: member, reason: 'Matched backend/API role keywords' }; - } +function routeMatch(issueText, rule) { + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', + ]); + const tokens = (value) => + value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(? + needle.length > 0 && + needle.length <= haystack.length && + haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); - if ( - (role.includes('test') || role.includes('qa')) && - (issueText.includes('test') || issueText.includes('bug') || issueText.includes('fix')) - ) { - return { agent: member, reason: 'Matched testing/QA role keywords' }; - } - } + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter((token) => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.keywords] + .flatMap((phrase) => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + const matchedKeywords = rawPhrases.filter((phrase) => + containsPhrase(issueTokens, tokens(phrase)) + ); + const score = matchedKeywords.reduce((best, phrase) => + Math.max(best, tokens(phrase).length * 100), 0); - return null; + return { score, matchedKeywords }; } function findLeadFallback(roster) { - return ( - roster.find((member) => { - const role = member.role.toLowerCase(); - return role.includes('lead') || role.includes('architect'); - }) || null - ); + const hasRoleToken = (member, token) => + (member.role.toLowerCase().match(/[a-z0-9]+/g) || []).includes(token); + return roster.find((member) => hasRoleToken(member, 'lead')) || + roster.find((member) => hasRoleToken(member, 'architect')) || + null; } function parseOwnerRepoFromRemote(remoteUrl) { diff --git a/packages/squad-cli/templates/workflows/squad-triage.yml b/packages/squad-cli/templates/workflows/squad-triage.yml index 579f74d29..21e67f70c 100644 --- a/packages/squad-cli/templates/workflows/squad-triage.yml +++ b/packages/squad-cli/templates/workflows/squad-triage.yml @@ -166,7 +166,7 @@ jobs: ]); function tokens(value) { - return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(?)\s*agent\b/i) ?? + parseTableSection(routingMd, /^##\s*work\s*type\s*(?:|->)\s*agent\b/i) ?? parseTableSection(routingMd, /^##\s*routing\s*table\b/i); if (!table) return []; @@ -134,8 +134,8 @@ export function parseRoster(teamMd: string): TeamMember[] { } /** - * Normalize an agent/role reference for comparison — strips markdown, emoji, - * and casing so `EECOM 🔧` and `eecom` compare equal. + * Normalize an agent/role reference for comparison  strips markdown, emoji, + * and casing so `EECOM ='` and `eecom` compare equal. * * Exported so other modules (e.g. capability advertisement) reuse the exact * matching semantics triage uses, instead of re-implementing them. @@ -161,10 +161,9 @@ export function findRosterMember(target: string, roster: TeamMember[]): TeamMemb /** * Triage an issue using routing rules, module ownership, and roster. * Priority order: - * 1. Module path match — issue mentions a file path matching module ownership - * 2. Work type keyword — issue content matches routing rule keywords - * 3. Role keyword — fallback to generic role-based matching (frontend/backend/test) - * 4. Lead fallback — assign to Lead/Architect if no match + * 1. Module path match  issue mentions a file path matching module ownership + * 2. Work type keyword  issue content matches routing rule keywords + * 3. Lead fallback  assign to Lead/Architect if no match */ export function triageIssue( issue: TriageIssue, @@ -200,26 +199,13 @@ export function triageIssue( } } - const bestRule = findBestRuleMatch(issueText, rules); + const bestRule = findBestRuleMatch(issueText, rules, roster); if (bestRule) { - const agent = findMember(bestRule.rule.agentName, roster); - if (agent) { - return { - agent, - reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, - source: 'routing-rule', - confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', - }; - } - } - - const roleMatch = findRoleKeywordMatch(issueText, roster); - if (roleMatch) { return { - agent: roleMatch.agent, - reason: roleMatch.reason, - source: 'role-keyword', - confidence: 'medium', + agent: bestRule.agent, + reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, + source: 'routing-rule', + confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', }; } @@ -228,7 +214,7 @@ export function triageIssue( return { agent: lead, - reason: 'No module, routing, or role keyword match — routed to Lead/Architect', + reason: 'No module, routing, or role keyword match  routed to Lead/Architect', source: 'lead-fallback', confidence: 'low', }; @@ -305,14 +291,14 @@ function cleanCell(value: string): string { function splitKeywords(examplesCell: string | undefined): string[] { if (!examplesCell) return []; return examplesCell - .split(',') + .split(/[,;]+/) .map((keyword) => cleanCell(keyword)) .filter((keyword) => keyword.length > 0); } function normalizeOptionalOwner(owner: string): string | null { if (!owner) return null; - if (/^[-—–]+$/.test(owner)) return null; + if (/^[-]+$/.test(owner)) return null; return owner; } @@ -332,33 +318,24 @@ function normalizeName(value: string): string { .trim(); } +function normalizeRouteDestination(value: string): string { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); +} + function findMember(target: string, roster: TeamMember[]): TeamMember | null { - const normalizedTarget = normalizeName(target); + const normalizedTarget = normalizeRouteDestination(target); if (!normalizedTarget) return null; - for (const member of roster) { - if (normalizeName(member.name) === normalizedTarget) return member; - } - - for (const member of roster) { - if (normalizeName(member.role) === normalizedTarget) return member; - } - - for (const member of roster) { - const memberName = normalizeName(member.name); - if (normalizedTarget.includes(memberName) || memberName.includes(normalizedTarget)) { - return member; - } - } - - for (const member of roster) { - const memberRole = normalizeName(member.role); - if (normalizedTarget.includes(memberRole) || memberRole.includes(normalizedTarget)) { - return member; - } - } - - return null; + return roster.find((member) => + normalizeRouteDestination(member.name) === normalizedTarget + ) ?? null; } function findBestModuleMatch(issueText: string, modules: ModuleOwnership[]): ModuleOwnership | null { @@ -382,68 +359,60 @@ function findBestModuleMatch(issueText: string, modules: ModuleOwnership[]): Mod function findBestRuleMatch( issueText: string, rules: RoutingRule[], -): { rule: RoutingRule; matchedKeywords: string[] } | null { - let best: { rule: RoutingRule; matchedKeywords: string[] } | null = null; - let bestScore = 0; - - for (const rule of rules) { - const matchedKeywords = rule.keywords - .map((keyword) => keyword.toLowerCase()) - .filter((keyword) => keyword.length > 0 && issueText.includes(keyword)); - - if (matchedKeywords.length === 0) continue; - - const score = - matchedKeywords.length * 100 + matchedKeywords.reduce((sum, keyword) => sum + keyword.length, 0); - if (score > bestScore) { - best = { - rule, - matchedKeywords, - }; - bestScore = score; - } - } - - return best; + roster: TeamMember[], +): { rule: RoutingRule; agent: TeamMember; matchedKeywords: string[] } | null { + const scoredRoutes = rules.flatMap((rule) => { + const agent = findMember(rule.agentName, roster); + if (!agent) return []; + const match = routeMatch(issueText, rule); + return match.score > 0 ? [{ rule, agent, ...match }] : []; + }).sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) return null; + + const bestScore = scoredRoutes[0]!.score; + const bestRoutes = scoredRoutes.filter((candidate) => candidate.score === bestScore); + const bestAgents = new Set(bestRoutes.map((candidate) => + normalizeRouteDestination(candidate.agent.name) + )); + return bestAgents.size === 1 ? bestRoutes[0]! : null; } -function findRoleKeywordMatch( +function routeMatch( issueText: string, - roster: TeamMember[], -): { agent: TeamMember; reason: string } | null { - for (const member of roster) { - const role = member.role.toLowerCase(); - - if ( - (role.includes('frontend') || role.includes('ui')) && - (issueText.includes('ui') || issueText.includes('frontend') || issueText.includes('css')) - ) { - return { agent: member, reason: 'Matched frontend/UI role keywords' }; - } - - if ( - (role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || issueText.includes('database')) - ) { - return { agent: member, reason: 'Matched backend/API role keywords' }; - } - - if ( - (role.includes('test') || role.includes('qa')) && - (issueText.includes('test') || issueText.includes('bug') || issueText.includes('fix')) - ) { - return { agent: member, reason: 'Matched testing/QA role keywords' }; - } - } - - return null; + rule: RoutingRule, +): { score: number; matchedKeywords: string[] } { + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', + ]); + const tokens = (value: string): string[] => + value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(? + needle.length > 0 && + needle.length <= haystack.length && + haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); + + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter((token) => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.keywords] + .flatMap((phrase) => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + const matchedKeywords = rawPhrases.filter((phrase) => + containsPhrase(issueTokens, tokens(phrase)) + ); + const score = matchedKeywords.reduce((best, phrase) => + Math.max(best, tokens(phrase).length * 100), 0); + + return { score, matchedKeywords }; } function findLeadFallback(roster: TeamMember[]): TeamMember | null { - return ( - roster.find((member) => { - const role = member.role.toLowerCase(); - return role.includes('lead') || role.includes('architect'); - }) ?? null - ); + const hasRoleToken = (member: TeamMember, token: string): boolean => + (member.role.toLowerCase().match(/[a-z0-9]+/g) ?? []).includes(token); + return roster.find((member) => hasRoleToken(member, 'lead')) ?? + roster.find((member) => hasRoleToken(member, 'architect')) ?? + null; } diff --git a/packages/squad-sdk/templates/ralph-triage.js b/packages/squad-sdk/templates/ralph-triage.js index 2e05eb971..792cb3566 100644 --- a/packages/squad-sdk/templates/ralph-triage.js +++ b/packages/squad-sdk/templates/ralph-triage.js @@ -170,26 +170,13 @@ function triageIssue(issue, rules, modules, roster) { } } - const bestRule = findBestRuleMatch(issueText, rules); + const bestRule = findBestRuleMatch(issueText, rules, roster); if (bestRule) { - const agent = findMember(bestRule.rule.agentName, roster); - if (agent) { - return { - agent, - reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, - source: 'routing-rule', - confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', - }; - } - } - - const roleMatch = findRoleKeywordMatch(issueText, roster); - if (roleMatch) { return { - agent: roleMatch.agent, - reason: roleMatch.reason, - source: 'role-keyword', - confidence: 'medium', + agent: bestRule.agent, + reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, + source: 'routing-rule', + confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', }; } @@ -268,7 +255,7 @@ function cleanCell(value) { function splitKeywords(examplesCell) { if (!examplesCell) return []; return examplesCell - .split(',') + .split(/[,;]+/) .map((keyword) => cleanCell(keyword)) .filter((keyword) => keyword.length > 0); } @@ -295,33 +282,24 @@ function normalizeName(value) { .trim(); } +function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); +} + function findMember(target, roster) { - const normalizedTarget = normalizeName(target); + const normalizedTarget = normalizeRouteDestination(target); if (!normalizedTarget) return null; - for (const member of roster) { - if (normalizeName(member.name) === normalizedTarget) return member; - } - - for (const member of roster) { - if (normalizeName(member.role) === normalizedTarget) return member; - } - - for (const member of roster) { - const memberName = normalizeName(member.name); - if (normalizedTarget.includes(memberName) || memberName.includes(normalizedTarget)) { - return member; - } - } - - for (const member of roster) { - const memberRole = normalizeName(member.role); - if (normalizedTarget.includes(memberRole) || memberRole.includes(normalizedTarget)) { - return member; - } - } - - return null; + return roster.find((member) => + normalizeRouteDestination(member.name) === normalizedTarget + ) || null; } function findBestModuleMatch(issueText, modules) { @@ -342,64 +320,58 @@ function findBestModuleMatch(issueText, modules) { return best; } -function findBestRuleMatch(issueText, rules) { - let best = null; - let bestScore = 0; - - for (const rule of rules) { - const matchedKeywords = rule.keywords - .map((keyword) => keyword.toLowerCase()) - .filter((keyword) => keyword.length > 0 && issueText.includes(keyword)); - - if (matchedKeywords.length === 0) continue; - - const score = - matchedKeywords.length * 100 + matchedKeywords.reduce((sum, keyword) => sum + keyword.length, 0); - if (score > bestScore) { - best = { rule, matchedKeywords }; - bestScore = score; - } - } - - return best; +function findBestRuleMatch(issueText, rules, roster) { + const scoredRoutes = rules.flatMap((rule) => { + const agent = findMember(rule.agentName, roster); + if (!agent) return []; + const match = routeMatch(issueText, rule); + return match.score > 0 ? [{ rule, agent, ...match }] : []; + }).sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) return null; + + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter((candidate) => candidate.score === bestScore); + const bestAgents = new Set(bestRoutes.map((candidate) => + normalizeRouteDestination(candidate.agent.name) + )); + return bestAgents.size === 1 ? bestRoutes[0] : null; } -function findRoleKeywordMatch(issueText, roster) { - for (const member of roster) { - const role = member.role.toLowerCase(); - - if ( - (role.includes('frontend') || role.includes('ui')) && - (issueText.includes('ui') || issueText.includes('frontend') || issueText.includes('css')) - ) { - return { agent: member, reason: 'Matched frontend/UI role keywords' }; - } - - if ( - (role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || issueText.includes('database')) - ) { - return { agent: member, reason: 'Matched backend/API role keywords' }; - } +function routeMatch(issueText, rule) { + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', + ]); + const tokens = (value) => + value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(? + needle.length > 0 && + needle.length <= haystack.length && + haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); - if ( - (role.includes('test') || role.includes('qa')) && - (issueText.includes('test') || issueText.includes('bug') || issueText.includes('fix')) - ) { - return { agent: member, reason: 'Matched testing/QA role keywords' }; - } - } + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter((token) => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.keywords] + .flatMap((phrase) => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + const matchedKeywords = rawPhrases.filter((phrase) => + containsPhrase(issueTokens, tokens(phrase)) + ); + const score = matchedKeywords.reduce((best, phrase) => + Math.max(best, tokens(phrase).length * 100), 0); - return null; + return { score, matchedKeywords }; } function findLeadFallback(roster) { - return ( - roster.find((member) => { - const role = member.role.toLowerCase(); - return role.includes('lead') || role.includes('architect'); - }) || null - ); + const hasRoleToken = (member, token) => + (member.role.toLowerCase().match(/[a-z0-9]+/g) || []).includes(token); + return roster.find((member) => hasRoleToken(member, 'lead')) || + roster.find((member) => hasRoleToken(member, 'architect')) || + null; } function parseOwnerRepoFromRemote(remoteUrl) { diff --git a/packages/squad-sdk/templates/workflows/squad-triage.yml b/packages/squad-sdk/templates/workflows/squad-triage.yml index 579f74d29..21e67f70c 100644 --- a/packages/squad-sdk/templates/workflows/squad-triage.yml +++ b/packages/squad-sdk/templates/workflows/squad-triage.yml @@ -166,7 +166,7 @@ jobs: ]); function tokens(value) { - return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(? p.test(file))) continue; const added = addedByFile.get(file) || []; for (const { line, text } of added) { for (const { pattern, label } of GIT_UNSAFE_PATTERNS) { - const match = pattern.exec(text); - const textBeforeCommand = match ? text.slice(0, match.index) : ''; - if (match && !UNSAFE_GIT_PROHIBITION.test(textBeforeCommand)) { + for (const match of text.matchAll(pattern)) { + const textBeforeCommand = text.slice(0, match.index); + if (isUnsafeGitProhibition(textBeforeCommand)) continue; findings.push({ category: 'unsafe-git', severity: 'error', diff --git a/templates/ralph-triage.js b/templates/ralph-triage.js index 2e05eb971..792cb3566 100644 --- a/templates/ralph-triage.js +++ b/templates/ralph-triage.js @@ -170,26 +170,13 @@ function triageIssue(issue, rules, modules, roster) { } } - const bestRule = findBestRuleMatch(issueText, rules); + const bestRule = findBestRuleMatch(issueText, rules, roster); if (bestRule) { - const agent = findMember(bestRule.rule.agentName, roster); - if (agent) { - return { - agent, - reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, - source: 'routing-rule', - confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', - }; - } - } - - const roleMatch = findRoleKeywordMatch(issueText, roster); - if (roleMatch) { return { - agent: roleMatch.agent, - reason: roleMatch.reason, - source: 'role-keyword', - confidence: 'medium', + agent: bestRule.agent, + reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`, + source: 'routing-rule', + confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium', }; } @@ -268,7 +255,7 @@ function cleanCell(value) { function splitKeywords(examplesCell) { if (!examplesCell) return []; return examplesCell - .split(',') + .split(/[,;]+/) .map((keyword) => cleanCell(keyword)) .filter((keyword) => keyword.length > 0); } @@ -295,33 +282,24 @@ function normalizeName(value) { .trim(); } +function normalizeRouteDestination(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[*_`]/g, '') + .replace(/\p{Extended_Pictographic}/gu, '') + .replace(/[\u200d\ufe0f]/g, '') + .trim() + .toLowerCase() + .replace(/\s+/g, ' '); +} + function findMember(target, roster) { - const normalizedTarget = normalizeName(target); + const normalizedTarget = normalizeRouteDestination(target); if (!normalizedTarget) return null; - for (const member of roster) { - if (normalizeName(member.name) === normalizedTarget) return member; - } - - for (const member of roster) { - if (normalizeName(member.role) === normalizedTarget) return member; - } - - for (const member of roster) { - const memberName = normalizeName(member.name); - if (normalizedTarget.includes(memberName) || memberName.includes(normalizedTarget)) { - return member; - } - } - - for (const member of roster) { - const memberRole = normalizeName(member.role); - if (normalizedTarget.includes(memberRole) || memberRole.includes(normalizedTarget)) { - return member; - } - } - - return null; + return roster.find((member) => + normalizeRouteDestination(member.name) === normalizedTarget + ) || null; } function findBestModuleMatch(issueText, modules) { @@ -342,64 +320,58 @@ function findBestModuleMatch(issueText, modules) { return best; } -function findBestRuleMatch(issueText, rules) { - let best = null; - let bestScore = 0; - - for (const rule of rules) { - const matchedKeywords = rule.keywords - .map((keyword) => keyword.toLowerCase()) - .filter((keyword) => keyword.length > 0 && issueText.includes(keyword)); - - if (matchedKeywords.length === 0) continue; - - const score = - matchedKeywords.length * 100 + matchedKeywords.reduce((sum, keyword) => sum + keyword.length, 0); - if (score > bestScore) { - best = { rule, matchedKeywords }; - bestScore = score; - } - } - - return best; +function findBestRuleMatch(issueText, rules, roster) { + const scoredRoutes = rules.flatMap((rule) => { + const agent = findMember(rule.agentName, roster); + if (!agent) return []; + const match = routeMatch(issueText, rule); + return match.score > 0 ? [{ rule, agent, ...match }] : []; + }).sort((left, right) => right.score - left.score); + + if (scoredRoutes.length === 0) return null; + + const bestScore = scoredRoutes[0].score; + const bestRoutes = scoredRoutes.filter((candidate) => candidate.score === bestScore); + const bestAgents = new Set(bestRoutes.map((candidate) => + normalizeRouteDestination(candidate.agent.name) + )); + return bestAgents.size === 1 ? bestRoutes[0] : null; } -function findRoleKeywordMatch(issueText, roster) { - for (const member of roster) { - const role = member.role.toLowerCase(); - - if ( - (role.includes('frontend') || role.includes('ui')) && - (issueText.includes('ui') || issueText.includes('frontend') || issueText.includes('css')) - ) { - return { agent: member, reason: 'Matched frontend/UI role keywords' }; - } - - if ( - (role.includes('backend') || role.includes('api') || role.includes('server')) && - (issueText.includes('api') || issueText.includes('backend') || issueText.includes('database')) - ) { - return { agent: member, reason: 'Matched backend/API role keywords' }; - } +function routeMatch(issueText, rule) { + const genericWorkTypeTokens = new Set([ + 'agent', 'engineer', 'engineering', 'management', 'owner', + 'specialist', 'system', 'work', + ]); + const tokens = (value) => + value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(? + needle.length > 0 && + needle.length <= haystack.length && + haystack.some((_, index) => + needle.every((token, offset) => haystack[index + offset] === token) + ); - if ( - (role.includes('test') || role.includes('qa')) && - (issueText.includes('test') || issueText.includes('bug') || issueText.includes('fix')) - ) { - return { agent: member, reason: 'Matched testing/QA role keywords' }; - } - } + const issueTokens = tokens(issueText); + const workTypeTokens = tokens(rule.workType) + .filter((token) => !genericWorkTypeTokens.has(token)); + const rawPhrases = [rule.workType, ...workTypeTokens, ...rule.keywords] + .flatMap((phrase) => phrase.includes('/') ? [phrase, ...phrase.split('/')] : [phrase]); + const matchedKeywords = rawPhrases.filter((phrase) => + containsPhrase(issueTokens, tokens(phrase)) + ); + const score = matchedKeywords.reduce((best, phrase) => + Math.max(best, tokens(phrase).length * 100), 0); - return null; + return { score, matchedKeywords }; } function findLeadFallback(roster) { - return ( - roster.find((member) => { - const role = member.role.toLowerCase(); - return role.includes('lead') || role.includes('architect'); - }) || null - ); + const hasRoleToken = (member, token) => + (member.role.toLowerCase().match(/[a-z0-9]+/g) || []).includes(token); + return roster.find((member) => hasRoleToken(member, 'lead')) || + roster.find((member) => hasRoleToken(member, 'architect')) || + null; } function parseOwnerRepoFromRemote(remoteUrl) { diff --git a/templates/workflows/squad-triage.yml b/templates/workflows/squad-triage.yml index 579f74d29..21e67f70c 100644 --- a/templates/workflows/squad-triage.yml +++ b/templates/workflows/squad-triage.yml @@ -166,7 +166,7 @@ jobs: ]); function tokens(value) { - return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?/g) || []; + return value.toLowerCase().match(/[a-z0-9]+(?:[+#.][a-z0-9+#.]*)?(? | Test coverage, Vitest, edge cases, CI/CD |', + '| Experience | Experience Engineer < | UI, UX, CSS |', '', '## Module Ownership', '', @@ -152,11 +152,11 @@ describe('ralph triage parser helpers', () => { '', '| Name | Role |', '|------|------|', - '| Quinn | QA 🧪 |', + '| Quinn | QA > |', ].join('\n'); const roster = parseRoster(withRoleEmoji); - expect(roster).toEqual([{ name: 'Quinn', role: 'QA 🧪', label: 'squad:quinn' }]); + expect(roster).toEqual([{ name: 'Quinn', role: 'QA >', label: 'squad:quinn' }]); }); }); @@ -179,7 +179,7 @@ describe('ralph triage parser helpers', () => { it('handles missing Examples column gracefully', () => { const markdown = [ - '## Work Type → Agent', + '## Work Type Agent', '', '| Work Type | Agent |', '|-----------|-------|', @@ -207,7 +207,7 @@ describe('ralph triage parser helpers', () => { it('returns empty array for empty/missing section', () => { expect(parseRoutingRules('# No routing section')).toEqual([]); - expect(parseRoutingRules('## Work Type → Agent')).toEqual([]); + expect(parseRoutingRules('## Work Type Agent')).toEqual([]); }); it('handles emoji in agent name column', () => { @@ -221,18 +221,18 @@ describe('ralph triage parser helpers', () => { it('parses Module Ownership table', () => { const modules = parseModuleOwnership(ROUTING_MD); expect(modules.length).toBeGreaterThan(0); - // Verify structure — agent names change during team rebirths + // Verify structure  agent names change during team rebirths expect(modules[0]).toHaveProperty('modulePath'); expect(modules[0]).toHaveProperty('primary'); }); - it('handles "—" as secondary (should be null)', () => { + it('handles "" as secondary (should be null)', () => { const markdown = [ '## Module Ownership', '', '| Module | Primary | Secondary |', '|--------|---------|-----------|', - '| `src/ralph/` | Runtime Engineer | — |', + '| `src/ralph/` | Runtime Engineer |  |', ].join('\n'); expect(parseModuleOwnership(markdown)).toEqual([ @@ -250,7 +250,7 @@ describe('ralph triage parser helpers', () => { '', '| Module | Primary | Secondary |', '|--------|---------|-----------|', - '| `SRC\\CLI\\` | Fenster | — |', + '| `SRC\\CLI\\` | Fenster |  |', ].join('\n'); expect(parseModuleOwnership(markdown)).toEqual([ @@ -305,8 +305,9 @@ describe('triageIssue()', () => { expect(decision?.confidence).toBe('high'); }); - it('role keyword fallback works for frontend/backend/test', () => { + it('does not infer ownership from role-name keywords', () => { const roleRoster: TeamMember[] = [ + { name: 'Lead', role: 'Technical Lead', label: 'squad:lead' }, { name: 'Front', role: 'Frontend UI Engineer', label: 'squad:front' }, { name: 'Back', role: 'Backend API Engineer', label: 'squad:back' }, { name: 'QA', role: 'Test Engineer', label: 'squad:qa' }, @@ -316,12 +317,12 @@ describe('triageIssue()', () => { const backend = triageIssue(issue('Database timeout on API endpoint'), [], [], roleRoster); const testing = triageIssue(issue('Flaky test bug fix needed'), [], [], roleRoster); - expect(frontend?.agent.name).toBe('Front'); - expect(backend?.agent.name).toBe('Back'); - expect(testing?.agent.name).toBe('QA'); - expect(frontend?.source).toBe('role-keyword'); - expect(backend?.source).toBe('role-keyword'); - expect(testing?.source).toBe('role-keyword'); + expect(frontend?.agent.name).toBe('Lead'); + expect(backend?.agent.name).toBe('Lead'); + expect(testing?.agent.name).toBe('Lead'); + expect(frontend?.source).toBe('lead-fallback'); + expect(backend?.source).toBe('lead-fallback'); + expect(testing?.source).toBe('lead-fallback'); }); it('lead fallback when no match', () => { @@ -390,6 +391,27 @@ describe('triageIssue()', () => { }); describe('triage parity', () => { + const require = createRequire(import.meta.url); + const standalone = require('../templates/ralph-triage.js') as { + parseRoster: typeof parseRoster; + parseRoutingRules: typeof parseRoutingRules; + triageIssue: typeof triageIssue; + }; + const implementations: Array<{ + name: string; + parseTeam: typeof parseRoster; + parseRules: typeof parseRoutingRules; + triage: typeof triageIssue; + }> = [ + { name: 'SDK', parseTeam: parseRoster, parseRules: parseRoutingRules, triage: triageIssue }, + { + name: 'standalone script', + parseTeam: standalone.parseRoster, + parseRules: standalone.parseRoutingRules, + triage: standalone.triageIssue, + }, + ]; + it('ralph-triage.js is valid JavaScript', async () => { const { execFile } = await import('node:child_process'); const { promisify } = await import('node:util'); @@ -401,15 +423,15 @@ describe('triage parity', () => { it('SDK and script use same routing priority order', () => { // Verify the SDK triage priority is: module-ownership > routing-rule > role-keyword > lead-fallback // This is the documented contract both implementations must follow - const routingMd = `## Work Type → Agent + const routingMd = `## Work Type Agent | Work Type | Agent | Examples | |---|---|---| -| Runtime | Fenster 🔧 | streaming, event loop | +| Runtime | Fenster =' | streaming, event loop | ## Module Ownership | Module | Primary | Secondary | |---|---|---| -| src/runtime/ | Fenster 🔧 | — |`; +| src/runtime/ | Fenster =' |  |`; const teamMd = `## Members | Name | Role | |---|---| @@ -430,9 +452,64 @@ describe('triage parity', () => { const result2 = triageIssue(ruleIssue, rules, modules, roster); expect(result2?.source).toBe('routing-rule'); }); + + it.each(implementations)('$name uses workflow-compatible route boundaries and destinations', ({ + parseTeam, + parseRules, + triage, + }) => { + const teamMd = [ + '## Members', + '| Name | Role |', + '|---|---|', + '| Team Lead | Technical Lead |', + '| Runtime Engineer | Runtime |', + '| Quality Engineer | Quality |', + '| Anna | Documentation |', + '| A.B | Specialist |', + ].join('\n'); + const routingMd = [ + '## Routing Table', + '| Work Type | Agent | Examples |', + '|---|---|---|', + '| Runtime | Runtime Engineer | API |', + '| Quality | Quality Engineer | failure |', + '| Docs | Ann | readme |', + '| Punctuation | AB | punctuation |', + '| Decorated | **Anna** = | handbook |', + ].join('\n'); + const parsedRoster = parseTeam(teamMd); + const parsedRules = parseRules(routingMd); + const decide = (title: string) => + triage({ number: 1, title, body: '', labels: [] }, parsedRules, [], parsedRoster); + + expect(decide('API regression')?.agent.name).toBe('Runtime Engineer'); + expect(decide('API.')?.agent.name).toBe('Runtime Engineer'); + expect(decide('rapid response required')?.agent.name).toBe('Team Lead'); + expect(decide('API failure')?.agent.name).toBe('Team Lead'); + expect(decide('readme update')?.agent.name).toBe('Team Lead'); + expect(decide('punctuation update')?.agent.name).toBe('Team Lead'); + expect(decide('handbook update')?.agent.name).toBe('Anna'); + + const semicolonRules = parseRules([ + '## Routing Table', + '| Work Type | Agent | Examples |', + '|---|---|---|', + '| Runtime | Runtime Engineer | API; server |', + '| Quality | Quality Engineer | failure |', + ].join('\n')); + const semicolonDecision = triage( + { number: 2, title: 'API failure', body: '', labels: [] }, + semicolonRules, + [], + parsedRoster, + ); + expect(semicolonDecision?.agent.name).toBe('Team Lead'); + expect(decide('failure.')?.agent.name).toBe('Quality Engineer'); + }); }); -describe('resolveGithubApiBase() — GitHub Enterprise support', () => { +describe('resolveGithubApiBase()  GitHub Enterprise support', () => { const require = createRequire(import.meta.url); const { resolveGithubApiBase } = require('../templates/ralph-triage.js'); diff --git a/test/scripts/security-review.test.ts b/test/scripts/security-review.test.ts index e8c5f09c0..923cf5261 100644 --- a/test/scripts/security-review.test.ts +++ b/test/scripts/security-review.test.ts @@ -89,21 +89,53 @@ describe('security review unsafe git exclusions', () => { }); it('does not report explicit prohibitions as unsafe instructions', () => { - const result = runSecurityReview( - '.github/agents/example.agent.md', - 'Never use `git add -A`; stage explicit paths instead.\n', - ); + const command = ['git add ', '-A'].join(''); + const result = runSecurityReview('.github/agents/example.agent.md', [ + `Never use \`${command}\`; stage explicit paths instead.`, + `Do not run ${command}; stage explicit paths instead.`, + `Avoid ${command}; stage explicit paths instead.`, + `Never \`git add .\`, ${command}, or \`git commit -a\`.`, + `- ❌ Blanket staging (${command}) is forbidden.`, + ].join('\n')); expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(false); }); - it('reports executable blanket staging commands', () => { - const command = ['git add ', '-A\n'].join(''); + it.each([ + ['blanket staging', ['git add ', '-A\n'].join('')], + ['inline Markdown', ['Run `git add ', '.` before committing.\n'].join('')], + ['dot slash staging', ['git add ', './\n'].join('')], + ['combined commit flags', ['git commit ', '-am update\n'].join('')], + ['do not forget instruction', ['Do not forget to run git add ', '-A\n'].join('')], + ['avoid-loss instruction', ['Avoid losing changes; run git add ', '-A\n'].join('')], + ['mixed prohibition and instruction', [ + 'Never use git add ', + '-A; instead run git add ', + '-A\n', + ].join('')], + ['sentence-separated prohibition and instruction', [ + 'Never use git add ', + '-A. Instead run git add ', + '.\n', + ].join('')], + ['comma-separated prohibition and instruction', [ + 'Do not run git add ', + '-A, instead run git add ', + '.\n', + ].join('')], + ])('reports executable unsafe git commands in %s', (_name, command) => { const result = runSecurityReview('.github/agents/example.agent.md', command); expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(true); }); + it('recognizes descriptive avoid prohibitions', () => { + const command = ['Avoid blanket staging with git add ', '-A\n'].join(''); + const result = runSecurityReview('.github/agents/example.agent.md', command); + + expect(result.findings.some((finding) => finding.category === 'unsafe-git')).toBe(false); + }); + it('does not let a trailing comment suppress an unsafe command', () => { const command = ['git add ', '-A # avoid orphaned files\n'].join(''); const result = runSecurityReview( From 3fcdac79ba498ea982df6df706146ee09c9d714c Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 9 Sep 2026 23:51:13 -0700 Subject: [PATCH 12/12] fix: preserve routing fixture integrity Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- packages/squad-sdk/src/ralph/triage.ts | 22 ++++++++++-------- scripts/security-review.mjs | 1 + test/ralph-triage.test.ts | 32 +++++++++++++------------- 3 files changed, 29 insertions(+), 26 deletions(-) diff --git a/packages/squad-sdk/src/ralph/triage.ts b/packages/squad-sdk/src/ralph/triage.ts index a4e81d38b..30d5aec00 100644 --- a/packages/squad-sdk/src/ralph/triage.ts +++ b/packages/squad-sdk/src/ralph/triage.ts @@ -48,7 +48,7 @@ interface ParsedTable { /** Parse routing rules from routing.md content */ export function parseRoutingRules(routingMd: string): RoutingRule[] { const table = - parseTableSection(routingMd, /^##\s*work\s*type\s*(?:|->)\s*agent\b/i) ?? + parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i) ?? parseTableSection(routingMd, /^##\s*routing\s*table\b/i); if (!table) return []; @@ -134,8 +134,8 @@ export function parseRoster(teamMd: string): TeamMember[] { } /** - * Normalize an agent/role reference for comparison  strips markdown, emoji, - * and casing so `EECOM ='` and `eecom` compare equal. + * Normalize an agent/role reference for comparison — strips markdown, emoji, + * and casing so `EECOM 🔧` and `eecom` compare equal. * * Exported so other modules (e.g. capability advertisement) reuse the exact * matching semantics triage uses, instead of re-implementing them. @@ -161,9 +161,9 @@ export function findRosterMember(target: string, roster: TeamMember[]): TeamMemb /** * Triage an issue using routing rules, module ownership, and roster. * Priority order: - * 1. Module path match  issue mentions a file path matching module ownership - * 2. Work type keyword  issue content matches routing rule keywords - * 3. Lead fallback  assign to Lead/Architect if no match + * 1. Module path match — issue mentions a file path matching module ownership + * 2. Work type keyword — issue content matches routing rule keywords + * 3. Lead fallback — assign to Lead/Architect if no match */ export function triageIssue( issue: TriageIssue, @@ -214,7 +214,7 @@ export function triageIssue( return { agent: lead, - reason: 'No module, routing, or role keyword match  routed to Lead/Architect', + reason: 'No module, routing, or role keyword match — routed to Lead/Architect', source: 'lead-fallback', confidence: 'low', }; @@ -298,7 +298,7 @@ function splitKeywords(examplesCell: string | undefined): string[] { function normalizeOptionalOwner(owner: string): string | null { if (!owner) return null; - if (/^[-]+$/.test(owner)) return null; + if (/^[-—–]+$/.test(owner)) return null; return owner; } @@ -410,8 +410,10 @@ function routeMatch( } function findLeadFallback(roster: TeamMember[]): TeamMember | null { - const hasRoleToken = (member: TeamMember, token: string): boolean => - (member.role.toLowerCase().match(/[a-z0-9]+/g) ?? []).includes(token); + const hasRoleToken = (member: TeamMember, token: string): boolean => { + const roleTokens: string[] = member.role.toLowerCase().match(/[a-z0-9]+/g) ?? []; + return roleTokens.includes(token); + }; return roster.find((member) => hasRoleToken(member, 'lead')) ?? roster.find((member) => hasRoleToken(member, 'architect')) ?? null; diff --git a/scripts/security-review.mjs b/scripts/security-review.mjs index 00ffe604f..5382447ab 100644 --- a/scripts/security-review.mjs +++ b/scripts/security-review.mjs @@ -185,6 +185,7 @@ for (const file of jstsFiles) { // .squad/log/ and .squad/orchestration-log/ are gitignored (never in PR diffs) but // listed here for documentation completeness. const UNSAFE_GIT_EXCLUDED_PATHS = [ + /^scripts\/security-review\.mjs$/, /^\.squad\/decisions\.md$/, /^\.squad\/agents\/.+\/history\.md$/, /^\.squad\/agents\/[^/]+\/history-archive-.+\.md$/, diff --git a/test/ralph-triage.test.ts b/test/ralph-triage.test.ts index a6d01022a..c7efb3f76 100644 --- a/test/ralph-triage.test.ts +++ b/test/ralph-triage.test.ts @@ -34,9 +34,9 @@ const ROUTING_MD = [ '', '| Work Type | Route To | Examples |', '|-----------|-------|----------|', - '| Core runtime | Runtime Engineer =' | adapter, session pool, API |', - '| Tests & quality | Quality Engineer > | Test coverage, Vitest, edge cases, CI/CD |', - '| Experience | Experience Engineer < | UI, UX, CSS |', + '| Core runtime | Runtime Engineer 🔧 | adapter, session pool, API |', + '| Tests & quality | Quality Engineer 🧪 | Test coverage, Vitest, edge cases, CI/CD |', + '| Experience | Experience Engineer 🎨 | UI, UX, CSS |', '', '## Module Ownership', '', @@ -152,11 +152,11 @@ describe('ralph triage parser helpers', () => { '', '| Name | Role |', '|------|------|', - '| Quinn | QA > |', + '| Quinn | QA 🧪 |', ].join('\n'); const roster = parseRoster(withRoleEmoji); - expect(roster).toEqual([{ name: 'Quinn', role: 'QA >', label: 'squad:quinn' }]); + expect(roster).toEqual([{ name: 'Quinn', role: 'QA 🧪', label: 'squad:quinn' }]); }); }); @@ -179,7 +179,7 @@ describe('ralph triage parser helpers', () => { it('handles missing Examples column gracefully', () => { const markdown = [ - '## Work Type Agent', + '## Work Type → Agent', '', '| Work Type | Agent |', '|-----------|-------|', @@ -207,7 +207,7 @@ describe('ralph triage parser helpers', () => { it('returns empty array for empty/missing section', () => { expect(parseRoutingRules('# No routing section')).toEqual([]); - expect(parseRoutingRules('## Work Type Agent')).toEqual([]); + expect(parseRoutingRules('## Work Type → Agent')).toEqual([]); }); it('handles emoji in agent name column', () => { @@ -221,18 +221,18 @@ describe('ralph triage parser helpers', () => { it('parses Module Ownership table', () => { const modules = parseModuleOwnership(ROUTING_MD); expect(modules.length).toBeGreaterThan(0); - // Verify structure  agent names change during team rebirths + // Verify structure — agent names change during team rebirths expect(modules[0]).toHaveProperty('modulePath'); expect(modules[0]).toHaveProperty('primary'); }); - it('handles "" as secondary (should be null)', () => { + it('handles "—" as secondary (should be null)', () => { const markdown = [ '## Module Ownership', '', '| Module | Primary | Secondary |', '|--------|---------|-----------|', - '| `src/ralph/` | Runtime Engineer |  |', + '| `src/ralph/` | Runtime Engineer | — |', ].join('\n'); expect(parseModuleOwnership(markdown)).toEqual([ @@ -250,7 +250,7 @@ describe('ralph triage parser helpers', () => { '', '| Module | Primary | Secondary |', '|--------|---------|-----------|', - '| `SRC\\CLI\\` | Fenster |  |', + '| `SRC\\CLI\\` | Fenster | — |', ].join('\n'); expect(parseModuleOwnership(markdown)).toEqual([ @@ -423,15 +423,15 @@ describe('triage parity', () => { it('SDK and script use same routing priority order', () => { // Verify the SDK triage priority is: module-ownership > routing-rule > role-keyword > lead-fallback // This is the documented contract both implementations must follow - const routingMd = `## Work Type Agent + const routingMd = `## Work Type → Agent | Work Type | Agent | Examples | |---|---|---| -| Runtime | Fenster =' | streaming, event loop | +| Runtime | Fenster 🔧 | streaming, event loop | ## Module Ownership | Module | Primary | Secondary | |---|---|---| -| src/runtime/ | Fenster =' |  |`; +| src/runtime/ | Fenster 🔧 | — |`; const teamMd = `## Members | Name | Role | |---|---| @@ -476,7 +476,7 @@ describe('triage parity', () => { '| Quality | Quality Engineer | failure |', '| Docs | Ann | readme |', '| Punctuation | AB | punctuation |', - '| Decorated | **Anna** = | handbook |', + '| Decorated | **Anna** 📚 | handbook |', ].join('\n'); const parsedRoster = parseTeam(teamMd); const parsedRules = parseRules(routingMd); @@ -509,7 +509,7 @@ describe('triage parity', () => { }); }); -describe('resolveGithubApiBase()  GitHub Enterprise support', () => { +describe('resolveGithubApiBase() — GitHub Enterprise support', () => { const require = createRequire(import.meta.url); const { resolveGithubApiBase } = require('../templates/ralph-triage.js');