91 lines
4.6 KiB
Markdown
91 lines
4.6 KiB
Markdown
# TODO
|
|
|
|
## Bootstrap installer (next session — 2026-08-14)
|
|
|
|
**Goal:** clone this repo on any machine, run one command, and every file lands
|
|
where the tooling expects it.
|
|
|
|
git clone <this repo> ~/projects/claude-mds && ~/projects/claude-mds/install.sh
|
|
|
|
### Shape
|
|
|
|
- **A manifest, not a script full of paths.** Declare `repo path -> target path`
|
|
in one file and let `install.sh` walk it. Adding a doc later should mean one
|
|
manifest line, not editing shell.
|
|
- **Symlinks, not copies.** Same reason as here: two copies drift, and the point
|
|
of the repo is that an edit lands in git. `ln -sfn`.
|
|
- **Idempotent.** Safe to re-run after every `git pull`. Re-linking an existing
|
|
correct link is a no-op.
|
|
- **Conditional targets.** `user/CLAUDE.md` installs everywhere. `officer.dev/`
|
|
only where that workspace exists. A manifest entry needs a "only if this path
|
|
exists" condition.
|
|
- **Never clobber silently.** If the target is a real file and not our link,
|
|
back it up (`.bak-<date>`) and say so. That file may be the only copy of
|
|
something written by hand on that machine.
|
|
- **Dry run by default, or at least `--dry-run`.** Show what it would link.
|
|
|
|
### Tools are installed, not referenced in place — DECIDED
|
|
|
|
`tools/` stays in the repo as the source, and the installer puts it under
|
|
`~/.local/claude-scripts/` (confirm the name), with `mask-secret` linked onto
|
|
`~/.local/bin` so it is a command rather than a path.
|
|
|
|
That fixes a real bug: `user/CLAUDE.md` currently hardcodes
|
|
`~/projects/claude-mds/tools/mask-secret.py`, which is only true on this
|
|
machine. Once installed, the doc says `mask-secret` and is true everywhere.
|
|
|
|
Carry `mask-hooks.d/` across with it, keeping the executable bits. The hooks are
|
|
the machine-specific half, so the installer should place only the hooks that
|
|
belong on that machine — same "only if this path exists" condition as the docs.
|
|
`officer-chat-events` should not land on a laptop with no Officer install, even
|
|
though it already exits cleanly when it finds no database.
|
|
|
|
Update `user/CLAUDE.md` to name the command in the same change, or the doc and
|
|
the layout disagree the moment this ships.
|
|
|
|
### Prior art to discuss: akitaonrails/ai-memory
|
|
|
|
<https://github.com/akitaonrails/ai-memory> — read 2026-08-13. Solves a superset
|
|
of this: cross-vendor long-term memory so you can quit Claude Code mid-task and
|
|
continue in Codex without re-explaining. A Rust binary plus a data dir, served
|
|
over MCP, with `install-mcp` and `install-hooks` subcommands.
|
|
|
|
Worth stealing even if we never run it:
|
|
|
|
- **`_global` scope.** A reserved project that is unioned into every query —
|
|
standing personal rules, tech choices, style. Exactly what `user/CLAUDE.md`
|
|
is. Confirms the split we already made.
|
|
- **Page categories**: `_rules/`, `decisions/`, `procedures/`, `gotchas/`.
|
|
Better than one growing file. Our `user/CLAUDE.md` is six sections and will
|
|
not stay readable at twenty.
|
|
- **Authority-aware retrieval.** Maintained rules outrank episodic session
|
|
evidence, but do not become absolute. A good answer to "the doc says X but
|
|
the code does Y" — which bit us today with the stale `pm2` rule.
|
|
- **`.ai-memory.toml` marker file** in a repo ancestor to pin which
|
|
workspace/project a directory belongs to. Directly relevant to our manifest's
|
|
"only if this path exists" condition — a marker is more explicit than a path
|
|
test.
|
|
- **`bootstrap`** seeds pages from `git log`, README, `docs/`, module headers.
|
|
The thing we would want when adding a new machine or repo.
|
|
|
|
**His position, stated up front: not a fan of MCP, and never was.** So this is a
|
|
source of ideas, not a thing to adopt. Do not open tomorrow by proposing we
|
|
install it. Harvest the taxonomy and the concepts, build our own on plain files.
|
|
|
|
The real decision: it is a **running service** (daemon, SQLite, FTS5,
|
|
embeddings, MCP, hooks). Ours is plain files and symlinks, readable with `cat`,
|
|
and works when nothing is installed. That simplicity is a feature, especially
|
|
given today's "code on disk is not what is running here" problem. Options:
|
|
adopt it, borrow the taxonomy only, or stay flat and revisit when the flat file
|
|
gets unreadable.
|
|
|
|
### Open questions
|
|
|
|
- Which files are genuinely universal vs this-machine-only? Right now
|
|
`officer.dev/CLAUDE.md` is the only machine-specific one, but the
|
|
`platform-appstore/` set is a candidate and was never folded in.
|
|
- Should `settings.json` / hooks be managed here too, or only `.md` files? The
|
|
repo is named for the docs but already carries `tools/`.
|
|
- Bootstrapping the bootstrap: the machine needs git and the repo URL before any
|
|
of this runs. Worth a one-line `curl | sh`, or deliberately not.
|