malpercio.dev
WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
docs: add documentation synchronization workflow to CLAUDE.md
After discovering drift between codebase reality and project tracking
(ATB-10 was complete but marked as Backlog), established a clear
workflow for keeping these synchronized:
- docs/atproto-forum-plan.md (master plan with phase checklist)
- Linear issues (task tracker)
New section explains when and how to update both sources of truth
when completing work, with commit prefix convention for plan updates.
Also updated MEMORY.md with critical reminder about doc sync.
+24
CLAUDE.md
+24
CLAUDE.md
···
84
84
- **Glob expansion in npm scripts:** `@atproto/lex-cli` needs file paths, not globs. Use `bash -c 'shopt -s globstar && ...'` to expand `**/*.json` in npm scripts.
85
85
- **`.env` loading:** Dev and spike scripts use Node's `--env-file=../../.env` flag to load the root `.env` file. No `dotenv` dependency needed.
86
86
87
+
## Documentation & Project Tracking
88
+
89
+
**Keep these synchronized when completing work:**
90
+
91
+
1. **`docs/atproto-forum-plan.md`** — Master project plan with phase checklist
92
+
- Mark items complete `[x]` when implementation is done and tested
93
+
- Add brief status notes with file references and Linear issue IDs
94
+
- Update immediately after completing milestones
95
+
96
+
2. **Linear issues** — Task tracker at https://linear.app/atbb
97
+
- Update status: Backlog → In Progress → Done
98
+
- Add comments documenting implementation details when marking Done
99
+
- Keep status in sync with actual codebase state, not planning estimates
100
+
101
+
3. **Workflow:** When finishing a task:
102
+
```sh
103
+
# 1. Verify implementation is complete (tests pass, code reviewed)
104
+
# 2. Update plan document: mark [x] and add completion note
105
+
# 3. Update Linear: change status to Done, add implementation comment
106
+
# 4. Commit: include "docs:" prefix for plan updates
107
+
```
108
+
109
+
**Why this matters:** The plan document and Linear can drift from reality as code evolves. Regular synchronization prevents rediscovering completed work and ensures accurate project status.
110
+
87
111
## Git Conventions
88
112
89
113
- Do not include `Co-Authored-By` lines in commit messages.