@wipcomputer/wip-ldm-os 0.4.73-alpha.9 → 0.4.75-alpha.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/LICENSE +52 -0
- package/SKILL.md +8 -1
- package/bin/ldm.js +600 -81
- package/dist/bridge/chunk-3RG5ZIWI.js +10 -0
- package/dist/bridge/{chunk-LF7EMFBY.js → chunk-7NH6JBIO.js} +127 -49
- package/dist/bridge/cli.js +2 -1
- package/dist/bridge/core.d.ts +13 -1
- package/dist/bridge/core.js +4 -1
- package/dist/bridge/mcp-server.js +52 -7
- package/dist/bridge/openclaw.d.ts +5 -0
- package/dist/bridge/openclaw.js +11 -0
- package/docs/bridge/TECHNICAL.md +86 -0
- package/docs/doc-pipeline/README.md +74 -0
- package/docs/doc-pipeline/TECHNICAL.md +79 -0
- package/lib/deploy.mjs +175 -13
- package/lib/detect.mjs +20 -6
- package/package.json +2 -2
- package/shared/docs/README.md.tmpl +2 -2
- package/shared/docs/dev-guide-wipcomputerinc.md.tmpl +378 -0
- package/shared/docs/how-releases-work.md.tmpl +3 -1
- package/shared/docs/how-worktrees-work.md.tmpl +12 -7
- package/shared/rules/git-conventions.md +3 -3
- package/shared/rules/release-pipeline.md +1 -1
- package/shared/rules/security.md +1 -1
- package/shared/rules/workspace-boundaries.md +1 -1
- package/shared/rules/writing-style.md +1 -1
- package/shared/templates/claude-md-level1.md +7 -3
- package/src/bridge/core.ts +160 -56
- package/src/bridge/mcp-server.ts +93 -8
- package/src/bridge/openclaw.ts +14 -0
- package/src/hooks/inbox-check-hook.mjs +232 -0
- package/src/hooks/inbox-rewake-hook.mjs +388 -0
- package/src/hosted-mcp/.env.example +3 -0
- package/src/hosted-mcp/demo/agent.html +300 -0
- package/src/hosted-mcp/demo/agent.txt +84 -0
- package/src/hosted-mcp/demo/fallback.jpg +0 -0
- package/src/hosted-mcp/demo/footer.js +74 -0
- package/src/hosted-mcp/demo/index.html +1303 -0
- package/src/hosted-mcp/demo/login.html +548 -0
- package/src/hosted-mcp/demo/privacy.html +223 -0
- package/src/hosted-mcp/demo/sprites.jpg +0 -0
- package/src/hosted-mcp/demo/sprites.png +0 -0
- package/src/hosted-mcp/demo/tos.html +198 -0
- package/src/hosted-mcp/deploy.sh +70 -0
- package/src/hosted-mcp/ecosystem.config.cjs +14 -0
- package/src/hosted-mcp/inbox.mjs +64 -0
- package/src/hosted-mcp/legal/internet-services/terms/site.html +205 -0
- package/src/hosted-mcp/legal/privacy/en-ww/index.html +230 -0
- package/src/hosted-mcp/nginx/mcp-oauth.conf +98 -0
- package/src/hosted-mcp/nginx/mcp-server.conf +17 -0
- package/src/hosted-mcp/nginx/wip.computer.conf +45 -0
- package/src/hosted-mcp/package-lock.json +2092 -0
- package/src/hosted-mcp/package.json +23 -0
- package/src/hosted-mcp/prisma/migrations/20260406233014_init/migration.sql +68 -0
- package/src/hosted-mcp/prisma/migrations/migration_lock.toml +3 -0
- package/src/hosted-mcp/prisma/schema.prisma +57 -0
- package/src/hosted-mcp/prisma.config.ts +14 -0
- package/src/hosted-mcp/server.mjs +2093 -0
- package/src/hosted-mcp/shared/kaleidoscope.css +139 -0
- package/src/hosted-mcp/shared/kaleidoscope.js +192 -0
- package/src/hosted-mcp/tools.mjs +73 -0
- package/templates/hooks/pre-commit +5 -0
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
# WIP Computer ... Internal Development Conventions
|
|
2
|
+
|
|
3
|
+
This is the WIP-specific supplement to the public [Dev Guide](../DEV-GUIDE-GENERAL-PUBLIC.md). Everything here is operational context for Parker, Lēsa, and Claude Code.
|
|
4
|
+
|
|
5
|
+
**You must read both guides.** The public guide covers the universal workflow (branching, PRs, release notes on the branch, release pipeline, license compliance, repo structure). This guide adds WIP-specific details (branch prefixes, agent IDs, incidents, deploy paths). Neither is complete without the other.
|
|
6
|
+
|
|
7
|
+
## Branch Prefixes
|
|
8
|
+
|
|
9
|
+
| Agent | Machine | Branch Prefix |
|
|
10
|
+
|-------|---------|---------------|
|
|
11
|
+
| cc-mini | Mac Mini | `cc-mini/` or `mini/` |
|
|
12
|
+
| cc-air | MacBook Air | `cc-air/` |
|
|
13
|
+
| oc-lesa-mini | Mac Mini (OpenClaw) | `oc-lesa-mini/` |
|
|
14
|
+
|
|
15
|
+
## Git Merge Rules
|
|
16
|
+
|
|
17
|
+
**Never squash merge.** Every commit has co-authors and tells the story of how something was built. Squashing destroys attribution and history. Always use regular merge (`--merge --delete-branch`) or fast-forward. This applies to `gh pr merge`, manual merges, and any other merge path. No exceptions. Always include `--delete-branch` so the PR branch is cleaned up automatically.
|
|
18
|
+
|
|
19
|
+
**Never push directly to main.** Always use a branch and PR.
|
|
20
|
+
|
|
21
|
+
## Merge, Deploy, Install ... Three Separate Steps
|
|
22
|
+
|
|
23
|
+
These are three distinct actions. Never combine them. Never skip the dogfooding step.
|
|
24
|
+
|
|
25
|
+
| Step | What it means | What happens |
|
|
26
|
+
|------|--------------|-------------|
|
|
27
|
+
| **Merge** | Development done | PR merged to private repo's main. Code lands. Nothing else changes. |
|
|
28
|
+
| **Deploy** | Ship to public | `wip-release` (version bump, npm publish, GitHub release) + `deploy-public.sh` (sync to public repo). Package is available to the world. **Still not on our machine.** |
|
|
29
|
+
| **Install** | Put it on our system | `crystal init` or equivalent. Extensions updated. Hooks configured. Only when Parker says "install." |
|
|
30
|
+
|
|
31
|
+
**After Deploy, STOP.** Do not copy files to `~/.ldm/extensions/` or `~/.openclaw/extensions/`. Do not run `npm install -g`. Do not run `npm link`. Do not touch the installed system. Tell Parker: "v0.X.Y is published. Run the install prompt when you're ready to update."
|
|
32
|
+
|
|
33
|
+
**We always dogfood our own software.** The install prompt exists so Parker can see what's new, review the dry run, and decide to install. If agents deploy directly to extensions, the install prompt says "already up to date" and the dogfooding loop is broken.
|
|
34
|
+
|
|
35
|
+
**Never run `npm link` in production.** Use it for testing during development, unlink immediately after. `npm link` makes the global tool run from the repo source. Any git pull or version bump instantly changes the production tool. This has happened and caused significant confusion (2026-03-13).
|
|
36
|
+
|
|
37
|
+
## Co-Authors on Every Commit
|
|
38
|
+
|
|
39
|
+
All three contributors must be listed on every commit. No exceptions. This is how GitHub tracks contributions across the team.
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
Co-Authored-By: Parker Todd Brooks <parkertoddbrooks@users.noreply.github.com>
|
|
43
|
+
Co-Authored-By: Lēsa <lesaai@icloud.com>
|
|
44
|
+
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Built-By Line
|
|
48
|
+
|
|
49
|
+
Every repo README must include this exact attribution in the License section:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6).
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
This is the standard. Use it everywhere. It credits the humans and identifies which AI runtimes built the software.
|
|
56
|
+
|
|
57
|
+
## Licensing Standard
|
|
58
|
+
|
|
59
|
+
All WIP Computer repos use dual MIT+AGPL licensing. Every repo README must include this exact license section:
|
|
60
|
+
|
|
61
|
+
```markdown
|
|
62
|
+
## License
|
|
63
|
+
|
|
64
|
+
\```
|
|
65
|
+
MIT All CLI tools, MCP servers, skills, and hooks (use anywhere, no restrictions).
|
|
66
|
+
AGPL Commercial redistribution, marketplace listings, or bundling into paid services.
|
|
67
|
+
\```
|
|
68
|
+
|
|
69
|
+
AGPL for personal use is free. Commercial licenses available.
|
|
70
|
+
|
|
71
|
+
Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6).
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
**Rules:**
|
|
75
|
+
- Copyright holder is always "WIP Computer, Inc."
|
|
76
|
+
- Personal use (including personal cloud/hosted) is free under AGPL
|
|
77
|
+
- Commercial redistribution, marketplace listings, or bundling into paid services requires a commercial license
|
|
78
|
+
- Run `wip-license-guard check` to audit compliance. Run `wip-license-guard check --fix` to auto-repair.
|
|
79
|
+
- Every repo must have a `.license-guard.json` config and a dual-license LICENSE file
|
|
80
|
+
|
|
81
|
+
## Agent ID Convention
|
|
82
|
+
|
|
83
|
+
| Harness | Pattern | Examples |
|
|
84
|
+
|---------|---------|----------|
|
|
85
|
+
| OpenClaw | `oc-{agent}-{machine}` | oc-lesa-mini, oc-lesa-air |
|
|
86
|
+
| Claude Code | `cc-{machine}` | cc-mini, cc-air |
|
|
87
|
+
|
|
88
|
+
This ID is the canonical identifier everywhere: Memory Crystal `agent_id`, LDM agent config, GitHub labels, branch prefixes.
|
|
89
|
+
|
|
90
|
+
**Incident (2026-03-11):** Memory Crystal had 4 agent IDs instead of 2. `claude-code` and `main` were old names from before the convention. Had to merge 141K+ chunks manually. Fix: agent ID should come from `~/.ldm/agents/<id>/config.json`, not be hardcoded in hooks. See wipcomputer/memory-crystal-private#33.
|
|
91
|
+
|
|
92
|
+
### GitHub Issues: `filed-by` Labels
|
|
93
|
+
|
|
94
|
+
Both labels are deployed org-wide across all wipcomputer repos:
|
|
95
|
+
|
|
96
|
+
| Label | Color | Who |
|
|
97
|
+
|-------|-------|-----|
|
|
98
|
+
| `filed-by:cc-mini` | Blue (#1d76db) | Claude Code on mini |
|
|
99
|
+
| `filed-by:oc-lesa-mini` | Purple (#d876e3) | Lesa on mini |
|
|
100
|
+
|
|
101
|
+
Every issue filed by an agent gets:
|
|
102
|
+
1. The `filed-by:*` label
|
|
103
|
+
2. Attribution line at top of body: `> Filed by: <agent name> (<id>) on <date>`
|
|
104
|
+
|
|
105
|
+
Since both agents use Lesa's GitHub account (`lesaai`), the label and attribution line are the only way to tell who actually filed it.
|
|
106
|
+
|
|
107
|
+
**To add labels for a new agent:**
|
|
108
|
+
```bash
|
|
109
|
+
gh label create "filed-by:<new-id>" --repo wipcomputer/<repo> --description "Issue filed by <name>" --color "<hex>"
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Or org-wide:
|
|
113
|
+
```bash
|
|
114
|
+
gh repo list wipcomputer --limit 200 --json name --jq '.[].name' | while read repo; do
|
|
115
|
+
gh label create "filed-by:<new-id>" --repo "wipcomputer/$repo" --description "..." --color "..." 2>/dev/null
|
|
116
|
+
done
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## npm and Publishing
|
|
120
|
+
|
|
121
|
+
- Never use Parker's personal npm credentials. Always use the SA token from 1Password.
|
|
122
|
+
- `gh auth` must have `write:packages` scope for GitHub Packages.
|
|
123
|
+
- `clawhub publish` requires absolute path to the skill folder.
|
|
124
|
+
- PRs go to `wipcomputer` org, not `parkertoddbrooks` upstream.
|
|
125
|
+
- npm scope: `@wipcomputer`
|
|
126
|
+
|
|
127
|
+
### .npmignore Required
|
|
128
|
+
|
|
129
|
+
**Every repo with an `ai/` folder MUST have a `.npmignore` that excludes it.** npm does not use `.gitignore` when `.npmignore` exists. Without this, private plans, todos, dev updates, and product ideas get published to the public npm registry.
|
|
130
|
+
|
|
131
|
+
Minimum `.npmignore` for any private repo:
|
|
132
|
+
```
|
|
133
|
+
ai/
|
|
134
|
+
.claude/
|
|
135
|
+
.wrangler/
|
|
136
|
+
CLAUDE.md
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Alternative: use a `"files"` whitelist in `package.json` to explicitly list what gets published. This is the most defensive approach.
|
|
140
|
+
|
|
141
|
+
**Incident (2026-03-02):** memory-crystal v0.2.0 and v0.3.0 published the entire `ai/` folder (plans, todos, product ideas) to npm. Also `@wipcomputer/markdown-viewer` v1.2.5 leaked `ai/bugs/`. All unpublished and fixed.
|
|
142
|
+
|
|
143
|
+
### 1Password SA Token
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
OP_SERVICE_ACCOUNT_TOKEN=$(cat ~/.openclaw/secrets/op-sa-token) op item get "Item Name" --fields label=fieldname
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Never call `op` bare. The bare CLI triggers a biometric popup. Always prefix with the SA token.
|
|
150
|
+
|
|
151
|
+
## Repos Using Private/Public Pattern
|
|
152
|
+
|
|
153
|
+
**HARD RULE: Never make a repo public unless it has a `-private` counterpart with all `ai/` content separated out.** If a repo doesn't have a `-private` counterpart yet, it stays private until one is created. No exceptions. Violating this exposes internal plans, todos, and development context.
|
|
154
|
+
|
|
155
|
+
**Forks of third-party public repos** can stay public. But if we're actively working on a fork, make it private so we can work and rebase without exposing our changes.
|
|
156
|
+
|
|
157
|
+
| Private (working repo) | Public (published) | What |
|
|
158
|
+
|------------------------|-------------------|------|
|
|
159
|
+
| `memory-crystal-private` | `memory-crystal` | Sovereign memory for AI agents |
|
|
160
|
+
| `dream-weaver-protocol-private` | `dream-weaver-protocol` | Dream Weaver paper |
|
|
161
|
+
| `wip-healthcheck-private` | `wip-healthcheck` | Gateway watchdog + backup system |
|
|
162
|
+
| `wip-dev-tools-private` | `wip-dev-tools` | Dev toolkit |
|
|
163
|
+
| `wip-xai-x-private` | `wip-xai-x` | X/Twitter integration |
|
|
164
|
+
| `wip-xai-grok-private` | `wip-xai-grok` | Grok integration |
|
|
165
|
+
|
|
166
|
+
## Cloudflare Workers Deploy
|
|
167
|
+
|
|
168
|
+
Two repos deploy to Cloudflare Workers. Same rules as git: **commit before deploy. Always.**
|
|
169
|
+
|
|
170
|
+
| Repo | Worker | Config | Deploy Script |
|
|
171
|
+
|------|--------|--------|---------------|
|
|
172
|
+
| memory-crystal-private | memory-crystal-demo | wrangler-demo.toml | `npm run deploy:demo` |
|
|
173
|
+
| memory-crystal-private | memory-crystal-cloud | wrangler-mcp.toml | `npm run deploy:cloud` |
|
|
174
|
+
| wip-agent-pay | wip-agent-pay | worker/wrangler.toml | `npm run deploy` |
|
|
175
|
+
|
|
176
|
+
**The rule:** source must be committed to git before `wrangler deploy` runs. The deploy scripts in package.json include a guard that checks for uncommitted changes and refuses to deploy if anything is dirty.
|
|
177
|
+
|
|
178
|
+
**Deploy workflow:**
|
|
179
|
+
1. Write code on feature branch
|
|
180
|
+
2. Build locally (`npm run build:demo`)
|
|
181
|
+
3. Test locally (`npm run dev:demo`)
|
|
182
|
+
4. Commit and push, PR, merge
|
|
183
|
+
5. Deploy (`npm run deploy:demo`)
|
|
184
|
+
|
|
185
|
+
Steps 1-4 happen BEFORE step 5. The Cloudflare API token is in 1Password ("Parker - Cloudflare Memory Crystal Keys", vault "Agent Secrets").
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
CLOUDFLARE_API_TOKEN=$(OP_SERVICE_ACCOUNT_TOKEN=$(cat ~/.openclaw/secrets/op-sa-token) op item get "Parker - Cloudflare Memory Crystal Keys" --fields label=api-token --vault "Agent Secrets" --reveal) npm run deploy:demo
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**Incident (2026-03-02):** Three versions of memory-crystal-demo deployed to Cloudflare with zero git commits. Source existed only in the working tree. Fixed by committing after the fact, but the deploy-before-commit pattern must not repeat.
|
|
192
|
+
|
|
193
|
+
## LDM OS Install Architecture
|
|
194
|
+
|
|
195
|
+
| Layer | Location | Nature |
|
|
196
|
+
|-------|----------|--------|
|
|
197
|
+
| Source code | `repos/` (git) | Version controlled, branchable |
|
|
198
|
+
| Installed runtime | `~/.ldm/extensions/` | Disposable. Rebuild from repo anytime |
|
|
199
|
+
| Agent data | `~/.ldm/agents/` | Backed up daily. Not in git |
|
|
200
|
+
| OpenClaw compatibility | `~/.openclaw/extensions/` | Symlinks to `~/.ldm/extensions/` |
|
|
201
|
+
|
|
202
|
+
Extensions deploy to `~/.ldm/extensions/{name}/`, not to repos and not to `~/.openclaw/extensions/`. OpenClaw sees them via symlinks.
|
|
203
|
+
|
|
204
|
+
## Repo Subfolder Layout
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
repos/
|
|
208
|
+
ldm-os/
|
|
209
|
+
components/ ... memory-crystal, wip-agent-pay, dream-weaver-protocol
|
|
210
|
+
utilities/ ... openclaw-1password, lesa-oc-root-key, lesa-private-mode, open-claw-upgrade
|
|
211
|
+
apis/ ... wip-x402-endpoint
|
|
212
|
+
apps/ ... wip-healthcheck
|
|
213
|
+
operations/ ... wip-dev-tools-private, wip-release, wip-universal-installer
|
|
214
|
+
sunsetted/ ... archived projects
|
|
215
|
+
wip-inc/ ... company/brand repos
|
|
216
|
+
sort/ ... unsorted, pending categorization
|
|
217
|
+
_third-party-repos/ ... forks (including openclaw/openclaw)
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## Shared Context (Agent Coordination)
|
|
221
|
+
|
|
222
|
+
Three layers:
|
|
223
|
+
|
|
224
|
+
1. **SHARED-CONTEXT.md** (`~/.openclaw/workspace/`) ... current state. Under 50 lines. Edit only, never Write.
|
|
225
|
+
2. **Shared daily log** (`~/.ldm/memory/daily/YYYY-MM-DD.md`) ... what happened today. Both agents append chronologically. Format: `### [YYYY-MM-DD HH:MM] agent-id` with bullets.
|
|
226
|
+
3. **Crystal** ... long-term memory. Both agents write. Search-based retrieval.
|
|
227
|
+
|
|
228
|
+
Agent-specific detailed logs stay in each agent's own space.
|
|
229
|
+
|
|
230
|
+
## Daily Logs (WIP-specific paths)
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
~/.ldm/agents/{agent-id}/memory/daily/
|
|
234
|
+
2026-02-27--17-45-30--cc-mini--memory-crystal-deploy.md
|
|
235
|
+
2026-02-27--19-12-00--cc-mini--user-level-migration.md
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
The shared daily log at `~/.ldm/memory/daily/YYYY-MM-DD.md` (for cross-agent coordination) is the exception. Both agents append there.
|
|
239
|
+
|
|
240
|
+
## Post-Upgrade Patches
|
|
241
|
+
|
|
242
|
+
After every `openclaw update`, run:
|
|
243
|
+
```bash
|
|
244
|
+
bash repos/ldm-os/utilities/open-claw-upgrade/post-upgrade-patches.sh
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
This re-applies dist patches that upgrades overwrite (EMFILE, cron catch-up, symlink discovery).
|
|
248
|
+
|
|
249
|
+
## Extension Deployment
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
# Build from source
|
|
253
|
+
cd repos/ldm-os/{category}/{repo}
|
|
254
|
+
npm run build
|
|
255
|
+
|
|
256
|
+
# Deploy to LDM OS
|
|
257
|
+
cp -r dist skills openclaw.plugin.json package.json ~/.ldm/extensions/{name}/
|
|
258
|
+
cd ~/.ldm/extensions/{name} && npm install --omit=dev
|
|
259
|
+
|
|
260
|
+
# Restart gateway to pick up changes
|
|
261
|
+
openclaw gateway restart
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
## Branch Protection Audit
|
|
265
|
+
|
|
266
|
+
Enforced on all 64 repos on 2026-02-20, re-audited 2026-02-27 (18 repos had drifted or were new). No force pushes to main. No direct pushes. No exceptions. The `lesaai` account is not exempt.
|
|
267
|
+
|
|
268
|
+
## Worktree Workflow (WIP-specific)
|
|
269
|
+
|
|
270
|
+
Same as the public Dev Guide section, plus:
|
|
271
|
+
|
|
272
|
+
- **Agent worktree paths:** `~/.ldm/agents/cc-mini/repos/<repo>/.claude/worktrees/<name>/` for CC, `~/.openclaw/workspace/.claude/worktrees/<name>/` for Lesa's spawned work
|
|
273
|
+
- **wip-release blocks from worktrees.** The guard detects linked worktrees via `git rev-parse --git-dir`. Use `--skip-worktree-check` only for testing.
|
|
274
|
+
- **wip-install auto-adds `.claude/worktrees/` to .gitignore.** No manual step needed on new repos.
|
|
275
|
+
- **Lesa keeps her own repos.** Worktrees are for parallel work within an agent, not for sharing repos between agents. Repos-per-agent is identity. Worktrees are the fail-safe.
|
|
276
|
+
- **Boot hook warning (Phase 4, planned):** SessionStart hook will warn if running in the main working tree instead of a worktree. Warning only, not a block.
|
|
277
|
+
|
|
278
|
+
## Review Flow (WIP-specific)
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
Lēsa builds -> pushes to dev branch
|
|
282
|
+
-> Claude Code reviews (code)
|
|
283
|
+
-> Parker reviews (direction)
|
|
284
|
+
-> merge to main
|
|
285
|
+
-> publish (npm, ClawHub, GitHub)
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Pre-publish also includes:
|
|
289
|
+
- Lēsa review (skill definition, documentation, integration)
|
|
290
|
+
- ClawHub skill published (if applicable)
|
|
291
|
+
- GitHub Action (if applicable)
|
|
292
|
+
- wip-license-hook ledger initialized
|
|
293
|
+
|
|
294
|
+
## Release Notes on the Branch
|
|
295
|
+
|
|
296
|
+
**Every PR must include a `RELEASE-NOTES-v{next-version}.md` file on the branch.** This is step 3 in the release workflow (see the public Dev Guide). The file gets committed with the code, reviewed in the PR, and auto-detected by `wip-release` after merge.
|
|
297
|
+
|
|
298
|
+
**Filename format:** `RELEASE-NOTES-v0-7-3.md` (dashes, not dots). Write it as narrative: what changed, why, what it fixes. Not a changelog.
|
|
299
|
+
|
|
300
|
+
**After release,** `wip-release` moves the file to `ai/_trash/` automatically. If you see stale `RELEASE-NOTES-*.md` files in a repo root, they were never consumed by a release. Clean them up.
|
|
301
|
+
|
|
302
|
+
**This is not optional.** If an agent reads the Dev Guide and still doesn't know to write release notes on the branch, the guide has failed. This is the standard.
|
|
303
|
+
|
|
304
|
+
## Release Notes Standard
|
|
305
|
+
|
|
306
|
+
**Every release must have exhaustive, categorized notes.** Look at [OpenClaw releases](https://github.com/openclaw/openclaw/releases) as the benchmark. People use our software. Sloppy notes are embarrassing.
|
|
307
|
+
|
|
308
|
+
`wip-release` generates structured notes automatically:
|
|
309
|
+
|
|
310
|
+
1. **Changes** ... new features, refactors, additions. One bullet per commit with hash.
|
|
311
|
+
2. **Fixes** ... bug fixes, hotfixes. One bullet per commit with hash.
|
|
312
|
+
3. **Docs** ... README, TECHNICAL, RELAY, any documentation changes.
|
|
313
|
+
4. **Files changed** ... diffstat (excludes `ai/` folder).
|
|
314
|
+
5. **Install** ... npm install command + git pull.
|
|
315
|
+
6. **Attribution** ... Built-by line.
|
|
316
|
+
7. **Full changelog** ... GitHub compare URL.
|
|
317
|
+
|
|
318
|
+
The `--notes` flag provides the summary paragraph at the top. The tool builds everything else from git history.
|
|
319
|
+
|
|
320
|
+
**For major releases (minor/major bumps):** the auto-generated notes are a starting point. Always review and expand them. Add context, describe architectural changes, explain why things changed. A commit subject like "Add cc-poller.ts" should become a paragraph explaining what the poller does, why it replaces the old hook, and what problem it solves.
|
|
321
|
+
|
|
322
|
+
**For patch releases:** auto-generated notes are usually sufficient. Review before publishing.
|
|
323
|
+
|
|
324
|
+
**Never publish a release with just a one-liner.** If two days of work went into it, the release notes should reflect that.
|
|
325
|
+
|
|
326
|
+
### The --no-publish Trap
|
|
327
|
+
|
|
328
|
+
**Never use `wip-release --no-publish` before running `deploy-public.sh`.** The deploy script pulls release notes from the private repo's GitHub release. If the GitHub release doesn't exist (because `--no-publish` skipped it), the public release gets empty "Release vX.Y.Z" text with no notes.
|
|
329
|
+
|
|
330
|
+
**The correct sequence is always:**
|
|
331
|
+
1. `wip-release patch --notes="..."` (full pipeline, creates GitHub release with notes)
|
|
332
|
+
2. `deploy-public.sh` (pulls notes from private release, creates matching public release)
|
|
333
|
+
|
|
334
|
+
**If you already used `--no-publish` and need to fix it:**
|
|
335
|
+
```bash
|
|
336
|
+
# Create the missing release on the private repo
|
|
337
|
+
gh release create vX.Y.Z -R wipcomputer/<name>-private --title "vX.Y.Z" --notes "..."
|
|
338
|
+
|
|
339
|
+
# Then update the public release
|
|
340
|
+
gh release edit vX.Y.Z -R wipcomputer/<name> --notes "..."
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
**Incident (2026-03-03):** memory-crystal v0.4.1 deployed to public repo with empty release notes because `wip-release --no-publish` was used. The GitHub release on the private repo didn't exist, so `deploy-public.sh` had nothing to pull. Fixed by manually creating releases on both repos.
|
|
344
|
+
|
|
345
|
+
**Incident (2026-03-09):** wip-dev-tools v1.3.0 deployed with one-liner release notes. Root cause: manual `git tag` + `git push` without creating a GitHub release on the private repo first. `deploy-public.sh` created the public release but had no notes to pull. Fixed by creating the release on private repo and updating public. Added "Release Order" section to the public Dev Guide.
|
|
346
|
+
|
|
347
|
+
### Manual Release (Toolbox Repos Without Root package.json)
|
|
348
|
+
|
|
349
|
+
Some repos (like wip-dev-tools itself) don't have a root `package.json`, so `wip-release` can't run directly. The manual flow must follow the same order:
|
|
350
|
+
|
|
351
|
+
1. Update `CHANGELOG.md` and `SKILL.md` version
|
|
352
|
+
2. Commit, PR, merge to main
|
|
353
|
+
3. `git tag vX.Y.Z && git push origin vX.Y.Z`
|
|
354
|
+
4. `gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."` on the PRIVATE repo
|
|
355
|
+
5. THEN `deploy-public.sh`
|
|
356
|
+
|
|
357
|
+
Step 4 must happen before step 5. This is the same trap as `--no-publish`.
|
|
358
|
+
|
|
359
|
+
### Universal Installer ... Dogfooding Rule
|
|
360
|
+
|
|
361
|
+
**Every tool we build must pass the Universal Installer check.** Run `wip-install --dry-run` on every sub-tool before release. If a tool should be agent-callable, it needs at minimum: Module + Skill + MCP Server.
|
|
362
|
+
|
|
363
|
+
**After releasing wip-dev-tools:**
|
|
364
|
+
1. Run `wip-install` on the toolbox itself
|
|
365
|
+
2. Deploy to `~/.ldm/extensions/wip-dev-tools/`
|
|
366
|
+
3. Symlink to `~/.openclaw/extensions/` (Lesa sees it)
|
|
367
|
+
4. Register MCP servers in `.mcp.json` (CC and Lesa see them)
|
|
368
|
+
|
|
369
|
+
**The loop:**
|
|
370
|
+
```
|
|
371
|
+
repo (source) -> wip-install (detect + deploy) -> ~/.ldm/extensions/ -> ~/.openclaw/extensions/ -> .mcp.json
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
This is the same path plugins already use. The installer automates it. We eat our own cooking.
|
|
375
|
+
|
|
376
|
+
**Sub-tool checklist for toolbox repos:** Apply the same PR checklist to each sub-tool inside `tools/`. Every sub-tool gets: package.json, SKILL.md, and interface files matching what it supports. The root SKILL.md covers the whole toolbox; each sub-tool has its own.
|
|
377
|
+
|
|
378
|
+
**Incident (2026-03-09):** v1.3.0 shipped with zero MCP servers across all 9 tools. The Universal Installer existed inside the toolbox but was never run on the toolbox's own tools. Fixed in v1.4.0 by adding MCP servers to 4 core tools and SKILL.md to 3 tools that were missing them.
|
|
@@ -23,8 +23,10 @@ cd .worktrees/repo--my-prefix--feature/
|
|
|
23
23
|
git push -u origin my-prefix/feature
|
|
24
24
|
gh pr create && gh pr merge --merge
|
|
25
25
|
|
|
26
|
-
# 3.
|
|
26
|
+
# 3. ALWAYS pull to main after merge (not optional)
|
|
27
27
|
cd /path/to/repo && git checkout main && git pull
|
|
28
|
+
|
|
29
|
+
# 4. Alpha release
|
|
28
30
|
wip-release alpha --notes="what changed"
|
|
29
31
|
|
|
30
32
|
# 4. Install and test
|
|
@@ -10,8 +10,8 @@ A git worktree is a second checkout of the same repo. Same history, same remote,
|
|
|
10
10
|
|
|
11
11
|
```
|
|
12
12
|
my-repo/ <- main branch (read-only)
|
|
13
|
-
|
|
14
|
-
|
|
13
|
+
.worktrees/my-repo--fix-bug/ <- your worktree (editable)
|
|
14
|
+
.worktrees/my-repo--new-feature/ <- someone else's worktree
|
|
15
15
|
```
|
|
16
16
|
|
|
17
17
|
All share the same `.git` database. Commits in any worktree are visible to all. But each has its own branch and files on disk.
|
|
@@ -23,22 +23,27 @@ cd my-repo
|
|
|
23
23
|
ldm worktree add my-prefix/fix-bug
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
This creates
|
|
26
|
+
This creates `.worktrees/my-repo--my-prefix--fix-bug/`.
|
|
27
27
|
|
|
28
28
|
## How to Work
|
|
29
29
|
|
|
30
30
|
Edit files in the worktree directory. Commit, push, PR, merge as normal:
|
|
31
31
|
|
|
32
32
|
```bash
|
|
33
|
-
cd
|
|
33
|
+
cd .worktrees/my-repo--my-prefix--fix-bug/
|
|
34
34
|
# edit, then:
|
|
35
35
|
git add <files>
|
|
36
36
|
git commit -m "description"
|
|
37
37
|
git push -u origin my-prefix/fix-bug
|
|
38
38
|
gh pr create
|
|
39
39
|
gh pr merge --merge --delete-branch
|
|
40
|
+
|
|
41
|
+
# CRITICAL: pull to main immediately after merge
|
|
42
|
+
cd /path/to/repo && git checkout main && git pull
|
|
40
43
|
```
|
|
41
44
|
|
|
45
|
+
**Always pull to main after merging a PR.** If you don't, the main working tree is stale and files won't show up. This is not optional. Every merge, every time.
|
|
46
|
+
|
|
42
47
|
## How to Clean Up
|
|
43
48
|
|
|
44
49
|
```bash
|
|
@@ -65,13 +70,13 @@ Switching branches changes every file in the directory. If another process (an a
|
|
|
65
70
|
|
|
66
71
|
## Your System
|
|
67
72
|
|
|
68
|
-
**Worktree location:** `~/wipcomputerinc/repos
|
|
73
|
+
**Worktree location:** `~/wipcomputerinc/repos/.worktrees/`
|
|
69
74
|
|
|
70
75
|
**Branch prefixes:**
|
|
71
76
|
- `cc-mini/` ... Claude Code on Mac mini
|
|
72
77
|
- `cc-air/` ... Claude Code on MacBook Air
|
|
73
78
|
- `lesa-mini/` ... Lesa on Mac mini
|
|
74
79
|
|
|
75
|
-
**Guard:** The branch guard warns if you create a worktree outside
|
|
80
|
+
**Guard:** The branch guard warns if you create a worktree outside `.worktrees/`. Suggests `ldm worktree add` instead.
|
|
76
81
|
|
|
77
|
-
**Auto-cleanup:** `wip-release` prunes merged worktrees from
|
|
82
|
+
**Auto-cleanup:** `wip-release` prunes merged worktrees from `.worktrees/` after every release.
|
|
@@ -14,11 +14,11 @@ Always use a branch and PR.
|
|
|
14
14
|
|
|
15
15
|
## Co-authors on every commit
|
|
16
16
|
|
|
17
|
-
List all contributors. Read co-author lines from
|
|
17
|
+
List all contributors. Read co-author lines from `~/.ldm/config.json` coAuthors field.
|
|
18
18
|
|
|
19
19
|
## Branch prefixes
|
|
20
20
|
|
|
21
|
-
Each agent uses a prefix from
|
|
21
|
+
Each agent uses a prefix from `~/.ldm/config.json` agents section. Prevents collisions.
|
|
22
22
|
|
|
23
23
|
## Worktrees
|
|
24
24
|
|
|
@@ -30,4 +30,4 @@ For private/public repo pairs, all issues go on the public repo.
|
|
|
30
30
|
|
|
31
31
|
## On-demand reference
|
|
32
32
|
|
|
33
|
-
Before doing repo work, read `~/wipcomputerinc/
|
|
33
|
+
Before doing repo work, read `~/wipcomputerinc/library/documentation/how-worktrees-work.md` for the full worktree workflow with commands.
|
|
@@ -39,4 +39,4 @@ Installed tools are for execution. Repo clones are for development. Use the inst
|
|
|
39
39
|
|
|
40
40
|
## On-demand reference
|
|
41
41
|
|
|
42
|
-
Before releasing, read `~/wipcomputerinc/
|
|
42
|
+
Before releasing, read `~/wipcomputerinc/library/documentation/how-releases-work.md` for the full pipeline with commands.
|
package/shared/rules/security.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Secret management
|
|
4
4
|
|
|
5
|
-
Use your org's secret management tool (configured in
|
|
5
|
+
Use your org's secret management tool (configured in `~/.ldm/config.json`). Never hardcode API keys, tokens, or credentials.
|
|
6
6
|
|
|
7
7
|
## Security audit before installing anything
|
|
8
8
|
|
|
@@ -22,4 +22,4 @@ Installed tools are for execution. Repo clones are for development. Use the inst
|
|
|
22
22
|
|
|
23
23
|
## On-demand reference
|
|
24
24
|
|
|
25
|
-
For the full directory map, read `~/wipcomputerinc/
|
|
25
|
+
For the full directory map, read `~/wipcomputerinc/library/documentation/system-directories.md`.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# Writing Style
|
|
2
2
|
|
|
3
|
-
Read writing conventions from
|
|
3
|
+
Read writing conventions from `~/.ldm/config.json` writingStyle section.
|
|
4
4
|
|
|
5
5
|
**Full paths in documentation.** Never truncate paths. Always show the complete path so there's no ambiguity.
|
|
@@ -5,9 +5,13 @@
|
|
|
5
5
|
Never use em dashes. Use periods, colons, semicolons, or ellipsis (...) instead.
|
|
6
6
|
Timezone: PST (Pacific), 24-hour clock. Parker is in Los Angeles.
|
|
7
7
|
|
|
8
|
+
## Don't Hedge
|
|
9
|
+
|
|
10
|
+
Never ask "should I stop?", "is this too much?", "what should we do now?", or "do you want me to continue?". If you have work to do, do it. If you're stuck, say what you're stuck on specifically. Don't express existential doubt about the task. Don't ask permission to keep working. Don't narrate your own uncertainty. Just work.
|
|
11
|
+
|
|
8
12
|
## Co-Authors on Every Commit
|
|
9
13
|
|
|
10
|
-
Read co-author lines from
|
|
14
|
+
Read co-author lines from `~/.ldm/config.json` coAuthors field. All contributors listed on every commit. No exceptions.
|
|
11
15
|
|
|
12
16
|
## 1Password CLI: Always Use Service Account Token
|
|
13
17
|
|
|
@@ -30,8 +34,8 @@ Before reaching for any external service or workaround: search memory first. Use
|
|
|
30
34
|
|
|
31
35
|
## Dev Conventions
|
|
32
36
|
|
|
33
|
-
For git workflow, releases, worktrees, and repo conventions: read `~/wipcomputerinc/
|
|
37
|
+
For git workflow, releases, worktrees, and repo conventions: read `~/wipcomputerinc/library/documentation/` on demand when doing repo work. Key docs:
|
|
34
38
|
- `how-worktrees-work.md` ... git worktrees, the convention, commands
|
|
35
39
|
- `how-releases-work.md` ... the full release pipeline
|
|
36
40
|
- `system-directories.md` ... what lives where
|
|
37
|
-
- Also read
|
|
41
|
+
- Also read `~/.ldm/shared/dev-guide-wipcomputerinc.md` for org-specific conventions
|