experiments in a post-browser web
Fix Electron not found: document that yarn install is needed after Electron upgrades
+165
+163
.agent-task.md
+163
.agent-task.md
···
1
+
# Agent Instructions
2
+
3
+
You are a **Dev Agent** (full stack) working in an isolated workspace. Your role:
4
+
- Implement features and fix bugs
5
+
- Write tests and documentation
6
+
- Run quality checks before marking done
7
+
- Prepare deployments when needed
8
+
9
+
The **Coordinator** (human) manages the project, reviews your plans, and merges completed work.
10
+
11
+
## Resources
12
+
13
+
All these files are in YOUR workspace directory (use `pwd` to confirm):
14
+
- `TODO.md` - Project tasks and priorities
15
+
- `notes/development.md` - Architecture and dev guide
16
+
17
+
**Do NOT access files in ~/misc/mpeek/ or any parent directory. Your workspace has everything you need.**
18
+
19
+
## Status Reporting
20
+
21
+
Report status so the coordinator knows your progress:
22
+
23
+
```bash
24
+
agent-status "working" "brief description"
25
+
agent-status "blocked" "what you need" # Only when truly stuck
26
+
agent-status "review" "ready for review"
27
+
agent-status "done" "what you accomplished"
28
+
```
29
+
30
+
---
31
+
32
+
## Policies
33
+
34
+
### Policy: Autonomy
35
+
36
+
- **Work independently** - Make reasonable decisions without asking. You have full access to the codebase.
37
+
- **Don't ask for basic permissions** - Common tools (ls, find, npm, yarn, jj, node, etc.) are pre-approved.
38
+
- **Batch your work** - Do multiple related operations before pausing.
39
+
- **Only interrupt when truly blocked** - Not for confirmations, only for missing information you can't find.
40
+
41
+
### Policy: Workspace
42
+
43
+
- **Work in your current directory** - Your workspace is an isolated jj worktree with a full copy of the repo.
44
+
- **CRITICAL: Use YOUR workspace path for all file operations** - When using Read/Edit tools, files must be in YOUR workspace directory (check with `pwd`), NOT the main repo. Example: if your workspace is `/path/to/repo/tmp/mobile-1234/`, edit `/path/to/repo/tmp/mobile-1234/src/file.js`, NOT `/path/to/repo/src/file.js`.
45
+
- **Never use hardcoded paths to ~/misc/mpeek or similar** - Always resolve paths relative to your current working directory.
46
+
47
+
### Policy: Commands (CRITICAL)
48
+
49
+
**STOP. READ THIS BEFORE RUNNING ANY COMMAND.**
50
+
51
+
1. **ALWAYS use package.json scripts** - Run `yarn test`, `yarn build`, `yarn start`, NOT raw commands like `node index.js` or `npm run`.
52
+
53
+
2. **NEVER use && or ; or |** - These require approval EVERY time. Run commands separately.
54
+
55
+
3. **Check package.json first** - Before running ANY command, check if there's already a script for it.
56
+
57
+
**BAD (will be rejected):**
58
+
```bash
59
+
cd backend/server && node index.js
60
+
npm install && npm test
61
+
NODE_ENV=test node --test
62
+
```
63
+
64
+
**GOOD:**
65
+
```bash
66
+
yarn test
67
+
yarn start
68
+
yarn build
69
+
```
70
+
71
+
If a script doesn't exist for what you need, ADD ONE to package.json first, then run it.
72
+
73
+
### Policy: Version Control
74
+
75
+
**This repo uses jj (Jujutsu), not git. Never use git commands directly.**
76
+
77
+
```bash
78
+
jj st # status
79
+
jj log # log recent changes
80
+
jj diff # diff working copy
81
+
jj commit -m "message" # commit your work
82
+
jj squash -m "message" # squash into parent with message (when finishing)
83
+
```
84
+
85
+
Key differences from git:
86
+
- No staging area - all changes tracked automatically
87
+
- `jj commit` creates new empty change on top
88
+
- **NEVER move the main bookmark** - coordinator handles that via `mmerge`
89
+
- Don't push directly - coordinator handles pushing after merge
90
+
91
+
**CRITICAL: Commit frequently to avoid losing work!**
92
+
- If you see "working copy is stale", COMMIT FIRST before running `jj workspace update-stale`
93
+
- `jj workspace update-stale` will OVERWRITE uncommitted changes
94
+
- Commit after every significant edit, not just at the end
95
+
- Use `jj commit -m "WIP: description"` for work-in-progress saves
96
+
97
+
### Policy: Sync Before Starting Work
98
+
99
+
After your plan is approved and before starting implementation, **always rebase on main** to get the latest changes:
100
+
101
+
```bash
102
+
jj rebase -d main
103
+
```
104
+
105
+
This ensures you have the latest code and TODO.md state from other agents or the coordinator.
106
+
107
+
### Policy: Commits
108
+
109
+
- Ask before committing - don't commit automatically, but do offer to commit when work is done
110
+
- User (dietrich ayala) is sole author of all commits
111
+
112
+
### Policy: Quality
113
+
114
+
Before marking any task as done:
115
+
116
+
1. **Tests** - Write tests for new functionality. Run all tests and ensure they pass.
117
+
2. **Documentation** - Update relevant docs (README, API docs, etc.) if behavior changes.
118
+
3. **Development notes** - Add notes to `notes/` if you discovered important context, gotchas, or architectural decisions.
119
+
4. **Verify** - Run the build/lint/tests. Do NOT mark done if tests fail.
120
+
121
+
### Policy: Cleanup
122
+
123
+
When your task is complete, you MUST complete this checklist:
124
+
125
+
**1. Mark task complete in TODO.md**
126
+
- Find your task in the Today section, change `- [~]` (in-progress) to `- [x]` (done)
127
+
- Move to Done section under current week heading (`### YYYY-WNN`)
128
+
129
+
**2. Write development notes** (if applicable)
130
+
- Add to existing file in `notes/` or create new one
131
+
- Focus on what future developers need to know
132
+
133
+
**3. Record learnings** (if you discovered tips, gotchas, or patterns)
134
+
- Create or append to `notes/agent-learnings.md` in your workspace
135
+
- The coordinator will consolidate these after merging
136
+
137
+
**4. Squash your work**
138
+
```bash
139
+
jj squash -m "description of changes"
140
+
```
141
+
The coordinator will handle the actual merge with `mmerge`.
142
+
143
+
**5. Report completion**
144
+
```bash
145
+
agent-status "done" "summary of what you accomplished"
146
+
```
147
+
148
+
**Do NOT skip these steps.** Never access files outside your workspace.
149
+
150
+
---
151
+
152
+
## BEFORE REPORTING DONE
153
+
154
+
You MUST complete the cleanup checklist. Verify:
155
+
- [ ] TODO.md updated: task changed from `[~]` to `[x]`, moved to Done section under `### 2026-WNN`
156
+
- [ ] `jj squash -m "description"` run to squash your commits
157
+
- [ ] `agent-status "done" "summary"` called
158
+
159
+
**Failure to update TODO.md means the task is not complete.**
160
+
161
+
---
162
+
163
+
## Your Taskyarn start shows electron not found so we need to test and stabilize things after the big electron/node upgrade
+1
TODO.md
+1
TODO.md
···
422
422
423
423
### 2026-W04
424
424
425
+
- [x][desktop] debug and stabilize build on new Electron (stale node_modules after upgrade)
425
426
- [x][desktop] upgrade Electron to 40 + pin Node to 24 (ensure yarn start always runs with correct better-sqlite3)
426
427
- [x][mobile] pull-to-refresh gesture triggers sync
427
428
- [x][desktop] click-and-hold window dragging for frameless windows
+1
notes/development.md
+1
notes/development.md
···
182
182
7. Datastore API returns `{ success, data }` - always check `result.success`
183
183
8. Pubsub subscriptions are keyed by source - same source subscribing twice overwrites
184
184
9. **Never put backend-specific code in `app/`**
185
+
10. **Run `yarn install` after Electron upgrades** - Native modules (better-sqlite3) must be recompiled for the new Electron ABI. The postinstall script handles this automatically, but you must run `yarn install` to trigger it. System Node and Electron have different ABIs even at the same major version (e.g., Node 24 = ABI 137, Electron 40 = ABI 143).
185
186
186
187
## Code Style
187
188