@bradygaster/squad-sdk 0.9.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +296 -296
- package/dist/agents/history-shadow.js +30 -30
- package/dist/build/github-dist.js +42 -42
- package/dist/config/init.js +173 -173
- package/dist/sharing/consult.js +78 -78
- package/package.json +1 -1
- package/templates/casting/Futurama.json +9 -9
- package/templates/casting-history.json +4 -4
- package/templates/casting-policy.json +37 -37
- package/templates/casting-reference.md +104 -104
- package/templates/casting-registry.json +3 -3
- package/templates/ceremonies.md +41 -41
- package/templates/charter.md +53 -53
- package/templates/constraint-tracking.md +38 -38
- package/templates/cooperative-rate-limiting.md +229 -229
- package/templates/copilot-instructions.md +46 -46
- package/templates/history.md +10 -10
- package/templates/identity/now.md +9 -9
- package/templates/identity/wisdom.md +15 -15
- package/templates/issue-lifecycle.md +412 -412
- package/templates/keda-scaler.md +164 -164
- package/templates/machine-capabilities.md +74 -74
- package/templates/mcp-config.md +90 -90
- package/templates/multi-agent-format.md +28 -28
- package/templates/plugin-marketplace.md +49 -49
- package/templates/ralph-circuit-breaker.md +313 -313
- package/templates/raw-agent-output.md +37 -37
- package/templates/roster.md +60 -60
- package/templates/routing.md +39 -39
- package/templates/run-output.md +50 -50
- package/templates/schedule.json +19 -19
- package/templates/scribe-charter.md +119 -119
- package/templates/skill.md +24 -24
- package/templates/skills/agent-collaboration/SKILL.md +42 -42
- package/templates/skills/agent-conduct/SKILL.md +24 -24
- package/templates/skills/architectural-proposals/SKILL.md +151 -151
- package/templates/skills/ci-validation-gates/SKILL.md +84 -84
- package/templates/skills/cli-wiring/SKILL.md +47 -47
- package/templates/skills/client-compatibility/SKILL.md +89 -89
- package/templates/skills/cross-squad/SKILL.md +114 -114
- package/templates/skills/distributed-mesh/SKILL.md +287 -287
- package/templates/skills/distributed-mesh/mesh.json.example +30 -30
- package/templates/skills/distributed-mesh/sync-mesh.ps1 +111 -111
- package/templates/skills/distributed-mesh/sync-mesh.sh +104 -104
- package/templates/skills/docs-standards/SKILL.md +71 -71
- package/templates/skills/economy-mode/SKILL.md +114 -114
- package/templates/skills/external-comms/SKILL.md +329 -329
- package/templates/skills/gh-auth-isolation/SKILL.md +183 -183
- package/templates/skills/git-workflow/SKILL.md +204 -204
- package/templates/skills/github-multi-account/SKILL.md +95 -95
- package/templates/skills/history-hygiene/SKILL.md +36 -36
- package/templates/skills/humanizer/SKILL.md +105 -105
- package/templates/skills/init-mode/SKILL.md +102 -102
- package/templates/skills/model-selection/SKILL.md +117 -117
- package/templates/skills/nap/SKILL.md +24 -24
- package/templates/skills/personal-squad/SKILL.md +57 -57
- package/templates/skills/project-conventions/SKILL.md +56 -56
- package/templates/skills/release-process/SKILL.md +423 -423
- package/templates/skills/reskill/SKILL.md +92 -92
- package/templates/skills/reviewer-protocol/SKILL.md +79 -79
- package/templates/skills/secret-handling/SKILL.md +200 -200
- package/templates/skills/session-recovery/SKILL.md +155 -155
- package/templates/skills/squad-conventions/SKILL.md +69 -69
- package/templates/skills/test-discipline/SKILL.md +37 -37
- package/templates/skills/windows-compatibility/SKILL.md +74 -74
- package/templates/workflows/squad-ci.yml +24 -24
- package/templates/workflows/squad-docs.yml +54 -54
- package/templates/workflows/squad-heartbeat.yml +171 -171
- package/templates/workflows/squad-insider-release.yml +61 -61
- package/templates/workflows/squad-issue-assign.yml +161 -161
- package/templates/workflows/squad-label-enforce.yml +181 -181
- package/templates/workflows/squad-preview.yml +55 -55
- package/templates/workflows/squad-promote.yml +120 -120
- package/templates/workflows/squad-release.yml +77 -77
- package/templates/workflows/squad-triage.yml +260 -260
- package/templates/workflows/sync-squad-labels.yml +169 -169
|
@@ -1,204 +1,204 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: "git-workflow"
|
|
3
|
-
description: "Squad branching model: dev-first workflow with insiders preview channel"
|
|
4
|
-
domain: "version-control"
|
|
5
|
-
confidence: "high"
|
|
6
|
-
source: "team-decision"
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Context
|
|
10
|
-
|
|
11
|
-
Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.**
|
|
12
|
-
|
|
13
|
-
| Branch | Purpose | Publishes |
|
|
14
|
-
|--------|---------|-----------|
|
|
15
|
-
| `main` | Released, tagged, in-npm code only | `npm publish` on tag |
|
|
16
|
-
| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge |
|
|
17
|
-
| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync |
|
|
18
|
-
|
|
19
|
-
## Branch Naming Convention
|
|
20
|
-
|
|
21
|
-
Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}`
|
|
22
|
-
|
|
23
|
-
Examples:
|
|
24
|
-
- `squad/195-fix-version-stamp-bug`
|
|
25
|
-
- `squad/42-add-profile-api`
|
|
26
|
-
|
|
27
|
-
## Workflow for Issue Work
|
|
28
|
-
|
|
29
|
-
1. **Branch from dev:**
|
|
30
|
-
```bash
|
|
31
|
-
git checkout dev
|
|
32
|
-
git pull origin dev
|
|
33
|
-
git checkout -b squad/{issue-number}-{slug}
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
2. **Mark issue in-progress:**
|
|
37
|
-
```bash
|
|
38
|
-
gh issue edit {number} --add-label "status:in-progress"
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
3. **Create draft PR targeting dev:**
|
|
42
|
-
```bash
|
|
43
|
-
gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
4. **Do the work.** Make changes, write tests, commit with issue reference.
|
|
47
|
-
|
|
48
|
-
5. **Push and mark ready:**
|
|
49
|
-
```bash
|
|
50
|
-
git push -u origin squad/{issue-number}-{slug}
|
|
51
|
-
gh pr ready
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
6. **After merge to dev:**
|
|
55
|
-
```bash
|
|
56
|
-
git checkout dev
|
|
57
|
-
git pull origin dev
|
|
58
|
-
git branch -d squad/{issue-number}-{slug}
|
|
59
|
-
git push origin --delete squad/{issue-number}-{slug}
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## Parallel Multi-Issue Work (Worktrees)
|
|
63
|
-
|
|
64
|
-
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.
|
|
65
|
-
|
|
66
|
-
### When to Use Worktrees vs Sequential
|
|
67
|
-
|
|
68
|
-
| Scenario | Strategy |
|
|
69
|
-
|----------|----------|
|
|
70
|
-
| Single issue | Standard workflow above — no worktree needed |
|
|
71
|
-
| 2+ simultaneous issues in same repo | Worktrees — one per issue |
|
|
72
|
-
| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) |
|
|
73
|
-
|
|
74
|
-
### Setup
|
|
75
|
-
|
|
76
|
-
From the main clone (must be on dev or any branch):
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
# Ensure dev is current
|
|
80
|
-
git fetch origin dev
|
|
81
|
-
|
|
82
|
-
# Create a worktree per issue — siblings to the main clone
|
|
83
|
-
git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev
|
|
84
|
-
git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`).
|
|
88
|
-
|
|
89
|
-
Each worktree:
|
|
90
|
-
- Has its own working directory and index
|
|
91
|
-
- Is on its own `squad/{issue-number}-{slug}` branch from dev
|
|
92
|
-
- Shares the same `.git` object store (disk-efficient)
|
|
93
|
-
|
|
94
|
-
### Per-Worktree Agent Workflow
|
|
95
|
-
|
|
96
|
-
Each agent operates inside its worktree exactly like the single-issue workflow:
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
cd ../squad-195
|
|
100
|
-
|
|
101
|
-
# Work normally — commits, tests, pushes
|
|
102
|
-
git add -A && git commit -m "fix: stamp bug (#195)"
|
|
103
|
-
git push -u origin squad/195-fix-stamp-bug
|
|
104
|
-
|
|
105
|
-
# Create PR targeting dev
|
|
106
|
-
gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
All PRs target `dev` independently. Agents never interfere with each other's filesystem.
|
|
110
|
-
|
|
111
|
-
### .squad/ State in Worktrees
|
|
112
|
-
|
|
113
|
-
The `.squad/` directory exists in each worktree as a copy. This is safe because:
|
|
114
|
-
- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs)
|
|
115
|
-
- Each agent appends to its own section; union merge reconciles on PR merge to dev
|
|
116
|
-
- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only
|
|
117
|
-
|
|
118
|
-
### Cleanup After Merge
|
|
119
|
-
|
|
120
|
-
After a worktree's PR is merged to dev:
|
|
121
|
-
|
|
122
|
-
```bash
|
|
123
|
-
# From the main clone
|
|
124
|
-
git worktree remove ../squad-195
|
|
125
|
-
git worktree prune # clean stale metadata
|
|
126
|
-
git branch -d squad/195-fix-stamp-bug
|
|
127
|
-
git push origin --delete squad/195-fix-stamp-bug
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state.
|
|
131
|
-
|
|
132
|
-
---
|
|
133
|
-
|
|
134
|
-
## Multi-Repo Downstream Scenarios
|
|
135
|
-
|
|
136
|
-
When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad):
|
|
137
|
-
|
|
138
|
-
### Setup
|
|
139
|
-
|
|
140
|
-
Clone downstream repos as siblings to the main repo:
|
|
141
|
-
|
|
142
|
-
```
|
|
143
|
-
~/work/
|
|
144
|
-
squad-pr/ # main repo
|
|
145
|
-
squad-sdk/ # downstream dependency
|
|
146
|
-
user-app/ # consumer project
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
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}`.
|
|
150
|
-
|
|
151
|
-
### Coordinated PRs
|
|
152
|
-
|
|
153
|
-
- Create PRs in each repo independently
|
|
154
|
-
- Link them in PR descriptions:
|
|
155
|
-
```
|
|
156
|
-
Closes #42
|
|
157
|
-
|
|
158
|
-
**Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature)
|
|
159
|
-
```
|
|
160
|
-
- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli)
|
|
161
|
-
|
|
162
|
-
### Local Linking for Testing
|
|
163
|
-
|
|
164
|
-
Before pushing, verify cross-repo changes work together:
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
# Node.js / npm
|
|
168
|
-
cd ../squad-sdk && npm link
|
|
169
|
-
cd ../squad-pr && npm link squad-sdk
|
|
170
|
-
|
|
171
|
-
# Go
|
|
172
|
-
# Use replace directive in go.mod:
|
|
173
|
-
# replace github.com/org/squad-sdk => ../squad-sdk
|
|
174
|
-
|
|
175
|
-
# Python
|
|
176
|
-
cd ../squad-sdk && pip install -e .
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs.
|
|
180
|
-
|
|
181
|
-
### Worktrees + Multi-Repo
|
|
182
|
-
|
|
183
|
-
These compose naturally. You can have:
|
|
184
|
-
- Multiple worktrees in the main repo (parallel issues)
|
|
185
|
-
- Separate clones for downstream repos
|
|
186
|
-
- Each combination operates independently
|
|
187
|
-
|
|
188
|
-
---
|
|
189
|
-
|
|
190
|
-
## Anti-Patterns
|
|
191
|
-
|
|
192
|
-
- ❌ Branching from main (branch from dev)
|
|
193
|
-
- ❌ PR targeting main directly (target dev)
|
|
194
|
-
- ❌ Non-conforming branch names (must be squad/{number}-{slug})
|
|
195
|
-
- ❌ Committing directly to main or dev (use PRs)
|
|
196
|
-
- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead)
|
|
197
|
-
- ❌ Using worktrees for cross-repo work (use separate clones)
|
|
198
|
-
- ❌ Leaving stale worktrees after PR merge (clean up immediately)
|
|
199
|
-
|
|
200
|
-
## Promotion Pipeline
|
|
201
|
-
|
|
202
|
-
- dev → insiders: Automated sync on green build
|
|
203
|
-
- dev → main: Manual merge when ready for stable release, then tag
|
|
204
|
-
- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent
|
|
1
|
+
---
|
|
2
|
+
name: "git-workflow"
|
|
3
|
+
description: "Squad branching model: dev-first workflow with insiders preview channel"
|
|
4
|
+
domain: "version-control"
|
|
5
|
+
confidence: "high"
|
|
6
|
+
source: "team-decision"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.**
|
|
12
|
+
|
|
13
|
+
| Branch | Purpose | Publishes |
|
|
14
|
+
|--------|---------|-----------|
|
|
15
|
+
| `main` | Released, tagged, in-npm code only | `npm publish` on tag |
|
|
16
|
+
| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge |
|
|
17
|
+
| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync |
|
|
18
|
+
|
|
19
|
+
## Branch Naming Convention
|
|
20
|
+
|
|
21
|
+
Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}`
|
|
22
|
+
|
|
23
|
+
Examples:
|
|
24
|
+
- `squad/195-fix-version-stamp-bug`
|
|
25
|
+
- `squad/42-add-profile-api`
|
|
26
|
+
|
|
27
|
+
## Workflow for Issue Work
|
|
28
|
+
|
|
29
|
+
1. **Branch from dev:**
|
|
30
|
+
```bash
|
|
31
|
+
git checkout dev
|
|
32
|
+
git pull origin dev
|
|
33
|
+
git checkout -b squad/{issue-number}-{slug}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
2. **Mark issue in-progress:**
|
|
37
|
+
```bash
|
|
38
|
+
gh issue edit {number} --add-label "status:in-progress"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
3. **Create draft PR targeting dev:**
|
|
42
|
+
```bash
|
|
43
|
+
gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
4. **Do the work.** Make changes, write tests, commit with issue reference.
|
|
47
|
+
|
|
48
|
+
5. **Push and mark ready:**
|
|
49
|
+
```bash
|
|
50
|
+
git push -u origin squad/{issue-number}-{slug}
|
|
51
|
+
gh pr ready
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
6. **After merge to dev:**
|
|
55
|
+
```bash
|
|
56
|
+
git checkout dev
|
|
57
|
+
git pull origin dev
|
|
58
|
+
git branch -d squad/{issue-number}-{slug}
|
|
59
|
+
git push origin --delete squad/{issue-number}-{slug}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Parallel Multi-Issue Work (Worktrees)
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
### When to Use Worktrees vs Sequential
|
|
67
|
+
|
|
68
|
+
| Scenario | Strategy |
|
|
69
|
+
|----------|----------|
|
|
70
|
+
| Single issue | Standard workflow above — no worktree needed |
|
|
71
|
+
| 2+ simultaneous issues in same repo | Worktrees — one per issue |
|
|
72
|
+
| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) |
|
|
73
|
+
|
|
74
|
+
### Setup
|
|
75
|
+
|
|
76
|
+
From the main clone (must be on dev or any branch):
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
# Ensure dev is current
|
|
80
|
+
git fetch origin dev
|
|
81
|
+
|
|
82
|
+
# Create a worktree per issue — siblings to the main clone
|
|
83
|
+
git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev
|
|
84
|
+
git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`).
|
|
88
|
+
|
|
89
|
+
Each worktree:
|
|
90
|
+
- Has its own working directory and index
|
|
91
|
+
- Is on its own `squad/{issue-number}-{slug}` branch from dev
|
|
92
|
+
- Shares the same `.git` object store (disk-efficient)
|
|
93
|
+
|
|
94
|
+
### Per-Worktree Agent Workflow
|
|
95
|
+
|
|
96
|
+
Each agent operates inside its worktree exactly like the single-issue workflow:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
cd ../squad-195
|
|
100
|
+
|
|
101
|
+
# Work normally — commits, tests, pushes
|
|
102
|
+
git add -A && git commit -m "fix: stamp bug (#195)"
|
|
103
|
+
git push -u origin squad/195-fix-stamp-bug
|
|
104
|
+
|
|
105
|
+
# Create PR targeting dev
|
|
106
|
+
gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
All PRs target `dev` independently. Agents never interfere with each other's filesystem.
|
|
110
|
+
|
|
111
|
+
### .squad/ State in Worktrees
|
|
112
|
+
|
|
113
|
+
The `.squad/` directory exists in each worktree as a copy. This is safe because:
|
|
114
|
+
- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs)
|
|
115
|
+
- Each agent appends to its own section; union merge reconciles on PR merge to dev
|
|
116
|
+
- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only
|
|
117
|
+
|
|
118
|
+
### Cleanup After Merge
|
|
119
|
+
|
|
120
|
+
After a worktree's PR is merged to dev:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# From the main clone
|
|
124
|
+
git worktree remove ../squad-195
|
|
125
|
+
git worktree prune # clean stale metadata
|
|
126
|
+
git branch -d squad/195-fix-stamp-bug
|
|
127
|
+
git push origin --delete squad/195-fix-stamp-bug
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Multi-Repo Downstream Scenarios
|
|
135
|
+
|
|
136
|
+
When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad):
|
|
137
|
+
|
|
138
|
+
### Setup
|
|
139
|
+
|
|
140
|
+
Clone downstream repos as siblings to the main repo:
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
~/work/
|
|
144
|
+
squad-pr/ # main repo
|
|
145
|
+
squad-sdk/ # downstream dependency
|
|
146
|
+
user-app/ # consumer project
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
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}`.
|
|
150
|
+
|
|
151
|
+
### Coordinated PRs
|
|
152
|
+
|
|
153
|
+
- Create PRs in each repo independently
|
|
154
|
+
- Link them in PR descriptions:
|
|
155
|
+
```
|
|
156
|
+
Closes #42
|
|
157
|
+
|
|
158
|
+
**Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature)
|
|
159
|
+
```
|
|
160
|
+
- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli)
|
|
161
|
+
|
|
162
|
+
### Local Linking for Testing
|
|
163
|
+
|
|
164
|
+
Before pushing, verify cross-repo changes work together:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
# Node.js / npm
|
|
168
|
+
cd ../squad-sdk && npm link
|
|
169
|
+
cd ../squad-pr && npm link squad-sdk
|
|
170
|
+
|
|
171
|
+
# Go
|
|
172
|
+
# Use replace directive in go.mod:
|
|
173
|
+
# replace github.com/org/squad-sdk => ../squad-sdk
|
|
174
|
+
|
|
175
|
+
# Python
|
|
176
|
+
cd ../squad-sdk && pip install -e .
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs.
|
|
180
|
+
|
|
181
|
+
### Worktrees + Multi-Repo
|
|
182
|
+
|
|
183
|
+
These compose naturally. You can have:
|
|
184
|
+
- Multiple worktrees in the main repo (parallel issues)
|
|
185
|
+
- Separate clones for downstream repos
|
|
186
|
+
- Each combination operates independently
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Anti-Patterns
|
|
191
|
+
|
|
192
|
+
- ❌ Branching from main (branch from dev)
|
|
193
|
+
- ❌ PR targeting main directly (target dev)
|
|
194
|
+
- ❌ Non-conforming branch names (must be squad/{number}-{slug})
|
|
195
|
+
- ❌ Committing directly to main or dev (use PRs)
|
|
196
|
+
- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead)
|
|
197
|
+
- ❌ Using worktrees for cross-repo work (use separate clones)
|
|
198
|
+
- ❌ Leaving stale worktrees after PR merge (clean up immediately)
|
|
199
|
+
|
|
200
|
+
## Promotion Pipeline
|
|
201
|
+
|
|
202
|
+
- dev → insiders: Automated sync on green build
|
|
203
|
+
- dev → main: Manual merge when ready for stable release, then tag
|
|
204
|
+
- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent
|
|
@@ -1,95 +1,95 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: github-multi-account
|
|
3
|
-
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.
|
|
4
|
-
confidence: high
|
|
5
|
-
source: https://github.com/tamirdresher/squad-skills/tree/main/plugins/github-multi-account
|
|
6
|
-
author: tamirdresher
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# GitHub Multi-Account — AI-Driven Setup
|
|
10
|
-
|
|
11
|
-
## When to Activate
|
|
12
|
-
When the user has multiple GitHub accounts (check with `gh auth status`). If you see 2+ accounts listed, this skill applies.
|
|
13
|
-
|
|
14
|
-
## What to Do (as the AI agent)
|
|
15
|
-
|
|
16
|
-
### Step 1: Detect accounts
|
|
17
|
-
Run: `gh auth status`
|
|
18
|
-
Look for multiple accounts. Note which usernames are listed.
|
|
19
|
-
|
|
20
|
-
### Step 2: Ask the user
|
|
21
|
-
Ask: "I see you have multiple GitHub accounts: {list them}. Which one is your personal account and which is your work/EMU account?"
|
|
22
|
-
|
|
23
|
-
### Step 3: Run the setup automatically
|
|
24
|
-
Once the user confirms, do ALL of this for them:
|
|
25
|
-
|
|
26
|
-
```powershell
|
|
27
|
-
# 1. Define the functions
|
|
28
|
-
$personal = "THEIR_PERSONAL_USERNAME"
|
|
29
|
-
$work = "THEIR_WORK_USERNAME"
|
|
30
|
-
|
|
31
|
-
# 2. Add to PowerShell profile
|
|
32
|
-
$profilePath = $PROFILE.CurrentUserAllHosts
|
|
33
|
-
if (!(Test-Path $profilePath)) { New-Item -Path $profilePath -Force | Out-Null }
|
|
34
|
-
$existing = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue
|
|
35
|
-
if ($existing -notmatch "gh-personal") {
|
|
36
|
-
$block = @"
|
|
37
|
-
|
|
38
|
-
# === GitHub Multi-Account Aliases ===
|
|
39
|
-
function gh-personal { gh auth switch --user $personal 2>`$null | Out-Null; gh @args }
|
|
40
|
-
function gh-work { gh auth switch --user $work 2>`$null | Out-Null; gh @args }
|
|
41
|
-
Set-Alias ghp gh-personal
|
|
42
|
-
Set-Alias ghw gh-work
|
|
43
|
-
"@
|
|
44
|
-
Add-Content -Path $profilePath -Value $block
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
# 3. Create CMD wrappers
|
|
48
|
-
$binDir = Join-Path $env:USERPROFILE ".squad\bin"
|
|
49
|
-
if (!(Test-Path $binDir)) { New-Item -ItemType Directory -Path $binDir -Force | Out-Null }
|
|
50
|
-
"@echo off`ngh auth switch --user $personal >nul 2>&1`ngh %*" | Out-File "$binDir\ghp.cmd" -Encoding ascii
|
|
51
|
-
"@echo off`ngh auth switch --user $work >nul 2>&1`ngh %*" | Out-File "$binDir\ghw.cmd" -Encoding ascii
|
|
52
|
-
|
|
53
|
-
# 4. Add to PATH
|
|
54
|
-
$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
|
|
55
|
-
if ($userPath -notmatch [regex]::Escape($binDir)) {
|
|
56
|
-
[Environment]::SetEnvironmentVariable("PATH", "$binDir;$userPath", "User")
|
|
57
|
-
$env:PATH = "$binDir;$env:PATH"
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
# 5. Load in current session
|
|
61
|
-
function gh-personal { gh auth switch --user $personal 2>$null | Out-Null; gh @args }
|
|
62
|
-
function gh-work { gh auth switch --user $work 2>$null | Out-Null; gh @args }
|
|
63
|
-
Set-Alias ghp gh-personal
|
|
64
|
-
Set-Alias ghw gh-work
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### Step 4: Verify for the user
|
|
68
|
-
Run these and show the results:
|
|
69
|
-
```powershell
|
|
70
|
-
ghp api user --jq '.login' # should show personal username
|
|
71
|
-
ghw api user --jq '.login' # should show work username
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### Step 5: Tell the user
|
|
75
|
-
"All set! From now on use `ghp` for personal repos and `ghw` for work repos. I'll use them too."
|
|
76
|
-
|
|
77
|
-
## After Setup — Usage Rules
|
|
78
|
-
|
|
79
|
-
1. **NEVER** use bare `gh` for repo operations — always `ghp` or `ghw`
|
|
80
|
-
2. **NEVER** manually `gh auth switch` — the aliases handle it
|
|
81
|
-
3. Determine alias by repo owner:
|
|
82
|
-
- Personal account repos → `ghp` / `gh-personal`
|
|
83
|
-
- Work/EMU account repos → `ghw` / `gh-work`
|
|
84
|
-
|
|
85
|
-
## Repo-Specific Account Binding
|
|
86
|
-
|
|
87
|
-
This repo (`bradygaster/squad`) is bound to the **bradygaster** (personal) account.
|
|
88
|
-
All `gh` operations in this repo MUST use `ghp` / `gh-personal`.
|
|
89
|
-
|
|
90
|
-
## For Squad Agents
|
|
91
|
-
At the TOP of any script touching GitHub, define:
|
|
92
|
-
```powershell
|
|
93
|
-
function gh-personal { gh auth switch --user bradygaster 2>$null | Out-Null; gh @args }
|
|
94
|
-
function gh-work { gh auth switch --user bradyg_microsoft 2>$null | Out-Null; gh @args }
|
|
95
|
-
```
|
|
1
|
+
---
|
|
2
|
+
name: github-multi-account
|
|
3
|
+
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.
|
|
4
|
+
confidence: high
|
|
5
|
+
source: https://github.com/tamirdresher/squad-skills/tree/main/plugins/github-multi-account
|
|
6
|
+
author: tamirdresher
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# GitHub Multi-Account — AI-Driven Setup
|
|
10
|
+
|
|
11
|
+
## When to Activate
|
|
12
|
+
When the user has multiple GitHub accounts (check with `gh auth status`). If you see 2+ accounts listed, this skill applies.
|
|
13
|
+
|
|
14
|
+
## What to Do (as the AI agent)
|
|
15
|
+
|
|
16
|
+
### Step 1: Detect accounts
|
|
17
|
+
Run: `gh auth status`
|
|
18
|
+
Look for multiple accounts. Note which usernames are listed.
|
|
19
|
+
|
|
20
|
+
### Step 2: Ask the user
|
|
21
|
+
Ask: "I see you have multiple GitHub accounts: {list them}. Which one is your personal account and which is your work/EMU account?"
|
|
22
|
+
|
|
23
|
+
### Step 3: Run the setup automatically
|
|
24
|
+
Once the user confirms, do ALL of this for them:
|
|
25
|
+
|
|
26
|
+
```powershell
|
|
27
|
+
# 1. Define the functions
|
|
28
|
+
$personal = "THEIR_PERSONAL_USERNAME"
|
|
29
|
+
$work = "THEIR_WORK_USERNAME"
|
|
30
|
+
|
|
31
|
+
# 2. Add to PowerShell profile
|
|
32
|
+
$profilePath = $PROFILE.CurrentUserAllHosts
|
|
33
|
+
if (!(Test-Path $profilePath)) { New-Item -Path $profilePath -Force | Out-Null }
|
|
34
|
+
$existing = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue
|
|
35
|
+
if ($existing -notmatch "gh-personal") {
|
|
36
|
+
$block = @"
|
|
37
|
+
|
|
38
|
+
# === GitHub Multi-Account Aliases ===
|
|
39
|
+
function gh-personal { gh auth switch --user $personal 2>`$null | Out-Null; gh @args }
|
|
40
|
+
function gh-work { gh auth switch --user $work 2>`$null | Out-Null; gh @args }
|
|
41
|
+
Set-Alias ghp gh-personal
|
|
42
|
+
Set-Alias ghw gh-work
|
|
43
|
+
"@
|
|
44
|
+
Add-Content -Path $profilePath -Value $block
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
# 3. Create CMD wrappers
|
|
48
|
+
$binDir = Join-Path $env:USERPROFILE ".squad\bin"
|
|
49
|
+
if (!(Test-Path $binDir)) { New-Item -ItemType Directory -Path $binDir -Force | Out-Null }
|
|
50
|
+
"@echo off`ngh auth switch --user $personal >nul 2>&1`ngh %*" | Out-File "$binDir\ghp.cmd" -Encoding ascii
|
|
51
|
+
"@echo off`ngh auth switch --user $work >nul 2>&1`ngh %*" | Out-File "$binDir\ghw.cmd" -Encoding ascii
|
|
52
|
+
|
|
53
|
+
# 4. Add to PATH
|
|
54
|
+
$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
|
|
55
|
+
if ($userPath -notmatch [regex]::Escape($binDir)) {
|
|
56
|
+
[Environment]::SetEnvironmentVariable("PATH", "$binDir;$userPath", "User")
|
|
57
|
+
$env:PATH = "$binDir;$env:PATH"
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
# 5. Load in current session
|
|
61
|
+
function gh-personal { gh auth switch --user $personal 2>$null | Out-Null; gh @args }
|
|
62
|
+
function gh-work { gh auth switch --user $work 2>$null | Out-Null; gh @args }
|
|
63
|
+
Set-Alias ghp gh-personal
|
|
64
|
+
Set-Alias ghw gh-work
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Step 4: Verify for the user
|
|
68
|
+
Run these and show the results:
|
|
69
|
+
```powershell
|
|
70
|
+
ghp api user --jq '.login' # should show personal username
|
|
71
|
+
ghw api user --jq '.login' # should show work username
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Step 5: Tell the user
|
|
75
|
+
"All set! From now on use `ghp` for personal repos and `ghw` for work repos. I'll use them too."
|
|
76
|
+
|
|
77
|
+
## After Setup — Usage Rules
|
|
78
|
+
|
|
79
|
+
1. **NEVER** use bare `gh` for repo operations — always `ghp` or `ghw`
|
|
80
|
+
2. **NEVER** manually `gh auth switch` — the aliases handle it
|
|
81
|
+
3. Determine alias by repo owner:
|
|
82
|
+
- Personal account repos → `ghp` / `gh-personal`
|
|
83
|
+
- Work/EMU account repos → `ghw` / `gh-work`
|
|
84
|
+
|
|
85
|
+
## Repo-Specific Account Binding
|
|
86
|
+
|
|
87
|
+
This repo (`bradygaster/squad`) is bound to the **bradygaster** (personal) account.
|
|
88
|
+
All `gh` operations in this repo MUST use `ghp` / `gh-personal`.
|
|
89
|
+
|
|
90
|
+
## For Squad Agents
|
|
91
|
+
At the TOP of any script touching GitHub, define:
|
|
92
|
+
```powershell
|
|
93
|
+
function gh-personal { gh auth switch --user bradygaster 2>$null | Out-Null; gh @args }
|
|
94
|
+
function gh-work { gh auth switch --user bradyg_microsoft 2>$null | Out-Null; gh @args }
|
|
95
|
+
```
|
|
@@ -1,36 +1,36 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: history-hygiene
|
|
3
|
-
description: Record final outcomes to history.md, not intermediate requests or reversed decisions
|
|
4
|
-
domain: documentation, team-collaboration
|
|
5
|
-
confidence: high
|
|
6
|
-
source: earned (Kobayashi v0.6.0 incident, team intervention)
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Context
|
|
10
|
-
|
|
11
|
-
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.
|
|
12
|
-
|
|
13
|
-
## Patterns
|
|
14
|
-
|
|
15
|
-
- **Record the final outcome**, not the initial request.
|
|
16
|
-
- **Wait for confirmation** before writing to history — don't log intermediate states.
|
|
17
|
-
- **If a decision reverses**, update the entry immediately — don't leave stale data.
|
|
18
|
-
- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened.
|
|
19
|
-
|
|
20
|
-
## Examples
|
|
21
|
-
|
|
22
|
-
✓ **Correct:**
|
|
23
|
-
- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)"
|
|
24
|
-
- "Reverted to Node 18 per Brady's explicit request on 2024-01-15"
|
|
25
|
-
|
|
26
|
-
✗ **Incorrect:**
|
|
27
|
-
- "Brady directed v0.6.0" (when later reversed)
|
|
28
|
-
- Recording what was *requested* instead of what *actually happened*
|
|
29
|
-
- Logging entries before outcome is confirmed
|
|
30
|
-
|
|
31
|
-
## Anti-Patterns
|
|
32
|
-
|
|
33
|
-
- Writing intermediate or "for now" states to disk
|
|
34
|
-
- Attributing decisions without confirming final direction
|
|
35
|
-
- Treating history like a draft — history is the source of truth
|
|
36
|
-
- Assuming readers will cross-reference or verify; they won't
|
|
1
|
+
---
|
|
2
|
+
name: history-hygiene
|
|
3
|
+
description: Record final outcomes to history.md, not intermediate requests or reversed decisions
|
|
4
|
+
domain: documentation, team-collaboration
|
|
5
|
+
confidence: high
|
|
6
|
+
source: earned (Kobayashi v0.6.0 incident, team intervention)
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
## Patterns
|
|
14
|
+
|
|
15
|
+
- **Record the final outcome**, not the initial request.
|
|
16
|
+
- **Wait for confirmation** before writing to history — don't log intermediate states.
|
|
17
|
+
- **If a decision reverses**, update the entry immediately — don't leave stale data.
|
|
18
|
+
- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened.
|
|
19
|
+
|
|
20
|
+
## Examples
|
|
21
|
+
|
|
22
|
+
✓ **Correct:**
|
|
23
|
+
- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)"
|
|
24
|
+
- "Reverted to Node 18 per Brady's explicit request on 2024-01-15"
|
|
25
|
+
|
|
26
|
+
✗ **Incorrect:**
|
|
27
|
+
- "Brady directed v0.6.0" (when later reversed)
|
|
28
|
+
- Recording what was *requested* instead of what *actually happened*
|
|
29
|
+
- Logging entries before outcome is confirmed
|
|
30
|
+
|
|
31
|
+
## Anti-Patterns
|
|
32
|
+
|
|
33
|
+
- Writing intermediate or "for now" states to disk
|
|
34
|
+
- Attributing decisions without confirming final direction
|
|
35
|
+
- Treating history like a draft — history is the source of truth
|
|
36
|
+
- Assuming readers will cross-reference or verify; they won't
|