@bradygaster/squad-cli 0.8.24 → 0.9.0

package/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.

package/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

package/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 }
+```

package/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 (Kobayashi v0.6.0 incident, team intervention)
+---
+
+## 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.
+
+## 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 Brady)"
+- "Reverted to Node 18 per Brady's explicit request on 2024-01-15"
+
+✗ **Incorrect:**
+- "Brady 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

package/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 (RFC #426 — PAO External Communications)"
+---
+
+## Context
+
+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 PAO 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, 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://...")
+- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information