claude-mds/TODO.md

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.