@yemi33/squad 0.1.6 → 0.1.7
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/docs/distribution.md +95 -0
- package/package.json +1 -1
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Distribution & Publishing
|
|
2
|
+
|
|
3
|
+
Squad is distributed as an npm package (`@yemi33/squad`) from a sanitized copy of the main repo.
|
|
4
|
+
|
|
5
|
+
## Two-Repo Architecture
|
|
6
|
+
|
|
7
|
+
| Repo | Purpose | What's included |
|
|
8
|
+
|------|---------|----------------|
|
|
9
|
+
| **origin** (`yemishin_microsoft/squad`) | Full working repo with all session state | Everything — history, notes, decisions, work items, CLAUDE.md |
|
|
10
|
+
| **personal** (`yemi33/squad`) | Clean distribution for others | Engine, dashboard, playbooks, charters, skills, docs, npm package files |
|
|
11
|
+
|
|
12
|
+
## What Gets Stripped
|
|
13
|
+
|
|
14
|
+
These files are removed during sync to personal:
|
|
15
|
+
|
|
16
|
+
| Category | Pattern | Reason |
|
|
17
|
+
|----------|---------|--------|
|
|
18
|
+
| Agent history | `agents/*/history.md` | Session-specific task logs |
|
|
19
|
+
| Notes archive | `notes/archive/*` | Historical agent findings |
|
|
20
|
+
| Notes inbox | `notes/inbox/*` | Pending agent findings |
|
|
21
|
+
| Notes summary | `notes.md` | Consolidated knowledge (runtime) |
|
|
22
|
+
| Work items | `work-items.json` | Runtime dispatch tracking |
|
|
23
|
+
| Project instructions | `CLAUDE.md` | Org-specific context |
|
|
24
|
+
|
|
25
|
+
## npm Package
|
|
26
|
+
|
|
27
|
+
**Package:** `@yemi33/squad`
|
|
28
|
+
**Registry:** https://www.npmjs.com/package/@yemi33/squad
|
|
29
|
+
|
|
30
|
+
### What's in the package
|
|
31
|
+
|
|
32
|
+
Controlled by the `files` field in `package.json`:
|
|
33
|
+
- `bin/squad.js` — CLI entry point
|
|
34
|
+
- `engine.js`, `dashboard.js`, `dashboard.html`, `squad.js` — core scripts
|
|
35
|
+
- `engine/spawn-agent.js`, `engine/ado-mcp-wrapper.js` — engine helpers
|
|
36
|
+
- `agents/*/charter.md` — agent role definitions
|
|
37
|
+
- `playbooks/*.md` — task templates
|
|
38
|
+
- `config.template.json` — starter config
|
|
39
|
+
- `routing.md`, `team.md` — editable team config
|
|
40
|
+
- `skills/`, `docs/` — documentation and workflows
|
|
41
|
+
|
|
42
|
+
### How `squad init` works
|
|
43
|
+
|
|
44
|
+
1. Copies all package files from `node_modules/@yemi33/squad/` to `~/.squad/`
|
|
45
|
+
2. Creates `config.json` from `config.template.json` if it doesn't exist
|
|
46
|
+
3. Creates runtime directories (`engine/`, `notes/inbox/`, `notes/archive/`, etc.)
|
|
47
|
+
4. Runs `squad.js init` to populate config with default agents
|
|
48
|
+
5. On `--force`, overwrites `.js` and `.html` files but preserves user-modified `.md` files
|
|
49
|
+
|
|
50
|
+
### How updates work
|
|
51
|
+
|
|
52
|
+
- Users run `npm update -g @yemi33/squad` then `squad init --force` to update engine code
|
|
53
|
+
- `npx @yemi33/squad` always fetches the latest version
|
|
54
|
+
|
|
55
|
+
## Auto-Publishing
|
|
56
|
+
|
|
57
|
+
A GitHub Action on the personal repo auto-publishes to npm on every push to master.
|
|
58
|
+
|
|
59
|
+
### How it works
|
|
60
|
+
|
|
61
|
+
1. Push to `yemi33/squad` master triggers `.github/workflows/publish.yml`
|
|
62
|
+
2. Action queries npm for the current published version
|
|
63
|
+
3. Bumps patch version (e.g., `0.1.5` → `0.1.6`)
|
|
64
|
+
4. Publishes to npm with the new version
|
|
65
|
+
5. Commits the version bump back to the repo with `[skip ci]` to prevent loops
|
|
66
|
+
|
|
67
|
+
### Why version comes from npm, not the repo
|
|
68
|
+
|
|
69
|
+
The sync-to-personal workflow force-pushes, which overwrites any version bump commits from previous action runs. So the action reads the latest version from the npm registry and bumps from there.
|
|
70
|
+
|
|
71
|
+
### Setup requirements
|
|
72
|
+
|
|
73
|
+
- `NPM_TOKEN` secret on `yemi33/squad` — a granular access token with publish permissions and 2FA bypass enabled
|
|
74
|
+
- The workflow file (`.github/workflows/publish.yml`) is gitignored on the org repo and force-added during sync
|
|
75
|
+
|
|
76
|
+
## Sync Workflow
|
|
77
|
+
|
|
78
|
+
Run `/sync-to-personal` or manually:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# 1. Create dist branch, strip files, add workflow, force-push
|
|
82
|
+
git checkout -b dist-clean
|
|
83
|
+
git rm --cached agents/*/history.md notes.md work-items.json CLAUDE.md
|
|
84
|
+
git rm -r --cached notes/archive/ notes/inbox/ notes/
|
|
85
|
+
# ... add .gitkeep files, .gitignore entries, workflow file
|
|
86
|
+
git add -f .github/workflows/publish.yml
|
|
87
|
+
git commit -m "Strip for distribution"
|
|
88
|
+
git push personal dist-clean:master --force
|
|
89
|
+
|
|
90
|
+
# 2. Return to master
|
|
91
|
+
git checkout master
|
|
92
|
+
git branch -D dist-clean
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The full workflow is documented in `.claude/skills/sync-to-personal/SKILL.md`.
|
package/package.json
CHANGED