Migration Architecture

An honest update to the v1 explainer. What changed, what stuck, what's still up for grabs — informed by your pushback, the prior-chat ingestion (session 85df5ee5), and the conventions research that just landed.

The 30-second version. Move work out of iCloud Documents. New home is ~/dev/, an exact mirror of your VPS /home/dev/ — same folder names, same shape, no wrapper. Inside it, projects/ is just where projects live (no double duty). Master folders like handoffs/, ideas/, context/, knowledge/ sit as siblings to projects/. Multi-CLI parity (Claude/Gemini/Codex/OpenCode) works naturally because each project carries its own per-CLI config and shared skills live in ~/.agents/skills/. Your knowledge system is its own downstream subcategory and gets its own handoff stack.

The new shape, all on one diagram

# Mac home — macOS clutter ignored # Claude Code user-config (hardcoded, hidden) # Gemini config (hidden) # Codex config (hidden) └── dev/ ← MIRROR of /home/dev/ on VPS. The new home. │ ├── .agents/ │ └── skills/ # cross-CLI skills, symlinked into each CLI's skill dir │ ├── projects/ # ONLY project subfolders. No wrapper duty. │ ├── CLAUDE.md # parent CLAUDE.md (@imports shared/) │ ├── n8n/ # own .claude/, .gemini/, AGENTS.md, CLAUDE.md, .mcp.json │ ├── kdp/ │ ├── lever/ │ ├── praul/ # brain-dump router (NOT just personal — see §B note) │ ├── dev-environment/ │ └── hcyr/ │ ├── handoffs/ # sibling — work-handoff files ├── ideas/ # 5-stage lifecycle │ ├── 1-parking-lot/ │ ├── 2-backburner/ │ ├── 3-frontburner/ │ ├── 4-in-progress/ │ ├── 5-done/ │ │ └── abandoned/ # subfolder, not a peer of done │ ├── IDEAS.md │ └── TEMPLATE.md │ ├── context/ # deep on-demand knowledge (distinct from memory/) │ ├── businesses/ │ ├── people/ │ │ └── family/ │ ├── clients/ │ ├── decisions/ # numbered ADRs (001, 002, …) │ └── goals.md │ ├── knowledge/ # Karpathy wiki + future vaults (own security model) │ └── wiki/ # ~/wiki symlinks here │ ├── questions/ # questions-by-recipient (josh/, hcyr/, ...) ├── apps/ # built/runnable things (tools/, games/) ├── reports/ # generated outputs │ └── session-summaries/ # per-session logs ├── scripts/ # automation, sync helpers ├── shared/ # bootstrap context (@imported into CLAUDE.md) │ ├── soul.md │ ├── user.md │ └── priorities.md ├── downloads/ # curated (siteintel/, etc.) ├── _dev0/ # Dev 0 orchestrator (our addition) └── _resources/ # cross-project shared patterns (our addition) Plus a friendly shortcut: ~/wiki → ~/dev/knowledge/wiki/ # symlink, so wiki is invokable from anywhere

Why this beats v1 (the lovebuilt/ wrapper): exact VPS parity (~/dev/projects/n8n/ ↔ /home/dev/projects/n8n/), projects/ keeps its narrow meaning, master folders (handoffs/ideas/context/) sit at their conceptual scope (cross-project), multi-CLI parity is natural per-project, and your hidden CLI configs (~/.claude/, ~/.gemini/) sit at the actual user root because Claude Code hardcodes them there. The macOS clutter is invisible noise; ~/dev/ is the only visible folder we care about.

Section-by-section update

§A — Top-level home CONFIRMED

✓ HELD UP

Out of iCloud. Conventions research agrees: most community setups use ~/projects/ or ~/dev/ (community split). The refinement: we're going with ~/dev/ because it mirrors your VPS exactly and keeps projects/ available for its narrow meaning.

§B — Per-project structure SHIFTED

⟳ MAJOR REWRITE

lovebuilt/ wrapper is dead. Flat ~/dev/ mirror with master folders as siblings to projects/. ~10 new folder categories adopted from VPS (already implemented).

v1 (the FINAL HTML you haven't read)

~/projects/lovebuilt/
├── CLAUDE.md
├── memory/
├── _handoffs/
├── _dev0/
├── _resources/
├── wiki/
├── n8n/
├── kdp/
├── lever/
└── praul/  ← "personal/family"

v2 — refined

~/dev/
├── .agents/skills/   (cross-CLI)
├── projects/
│   ├── CLAUDE.md
│   ├── n8n/, kdp/, lever/, praul/, ...
├── handoffs/
├── ideas/  (5-stage)
├── context/  (deep knowledge)
├── knowledge/  (wiki + vaults)
├── questions/
├── apps/
├── reports/
├── scripts/
├── shared/  (bootstrap)
├── _dev0/
└── _resources/

PRAUL reframe (P-2): Not personal/family. It's your brain-dump routing intelligence — Personal Robot for Achieving Unlimited Lifetimes, ingests anything (business musings, $5M ideas, emotional struggles, kids dreams, gratitude), classifies, routes to the right downstream vault.

§C — Username rename UNCHANGED

✓ STILL DEFERRED

Out of scope for this migration. Separate handoff later. 2,286 references to /Users/coach in ~/.claude/ alone, plus macOS short-name renames touch keychain/login/FileVault recovery. Doing it after the new home settles makes the future project smaller.

§D — Local↔VPS sync CONFIRMED

§E — Wiki / knowledge SHIFTED + PARTIALLY UNSETTLED

⟳ MOVED — and finer placement deferred

Wiki belongs under ~/dev/knowledge/, NOT inside a project folder. ~/wiki stays as the friendly symlink — that part holds. The full vault topology (personal master / business / Lever / friend-shares / client vaults / etc.) is its own knowledge-system handoff stack, scheduled after the foundational migration.

What's deferred: vault topology (one vs many), RAG vs NLM vs Obsidian-only, sync mechanism, encryption stack, brain-dump routing logic, security hardening, multi-user permissions. All in the knowledge-system handoff stack at _dev0/migration/knowledge/.

§F — Path-rewrite CONFIRMED + FLAGGED

⚠ NEEDS VERIFICATION BEFORE EXEC

Manual sed for the 647 mutable refs is right. The session-history symlink trick is the right idea — BUT the conventions research surfaced that it relies on undocumented Claude Code path-keying behavior, possibly tied to open Anthropic issues #38469 / #40300 / #65 05-reference §F.

Action: RT-A (architecture review) must verify those bug numbers actually exist on github.com/anthropics/claude-code. If real and unresolved, the symlink approach is fragile — Migration 02 needs a fallback (re-indexed copy of the project-id directory). 5-minute test session before commitment is non-negotiable.

§G — Basecamp folder CONFIRMED

✓ HELD UP — minimal version still right

Build ~/dev/_basecamp/ with CLAUDE.md (minimal MCPs) + INDEX.md ("if you want X, open folder Y"). Routing skill = v2 only when the static index outgrows itself (~15+ entries).

§H — iTerm canonical, not VS Code CONFIRMED

✓ EVIDENCE STRONG

VS Code eagerly spawns every configured MCP per session (~534 processes for 16 sessions). iTerm lazy-loads. Conventions research adds: community patterns also lean iTerm or plain shell as canonical, with VS Code reserved for editing. Fresh-chat workflow stays: open iTerm → cd ~/dev/projects/<sub-project> → claude.

Folders A–H didn't acknowledge (now adopted)

The conventions research caught this. Your VPS already implements ~10 folders A–H ignored. The Mac mirror inherits all of them.

What's still genuinely unsettled

These are open questions reviewers should chew on or that get answered downstream. Listed honestly so we don't pretend they're decided.

What feeds the orchestrator

Folder	What it's for	Why A–H missed it
`ideas/`	5-stage lifecycle: parking-lot → backburner → frontburner → in-progress → done (+ done/abandoned)	The plan file leaned on "memory/" being the catch-all
`context/`	Deep on-demand knowledge (businesses, people, clients, decisions, goals). Distinct from `memory/`	A–H collapsed memory + context into one concept
`.agents/skills/`	Cross-CLI skill convention. Symlinked into each CLI's skill dir. Universal YAML+MD format.	A–H said "multi-CLI" but didn't name the mechanism
`questions/`	Questions-by-recipient (josh/, hcyr/, publishing/, general/) with TEMPLATE.md	Useful pattern, just unlogged
`apps/`	Built/runnable things — distinct from projects (WIPs)	A–H collapsed these
`reports/`	Generated outputs (maintenance, audits, session-summaries/)	A–H put session summaries under `_dev0/`; the VPS convention is here
`scripts/`	Automation, sync helpers	—
`shared/`	Bootstrap context loaded via `@import` into every `CLAUDE.md` (soul, user, priorities — small files)	A–H discussed CLAUDE.md walk-up but missed the @import-based pattern
`downloads/`	Curated subfolders (siteintel/, etc.)	"Mac already has this" hid it from A–H
`knowledge/`	Karpathy wiki + downstream vaults — own security model	A–H put the wiki under projects/lovebuilt/; wrong layer

Open question	Where it gets resolved
Does Claude Code's `CLAUDE.md` walk-up correctly inherit from `~/dev/projects/CLAUDE.md` when you `cd` into a sub-project? Or do we need explicit `@import` in each sub-project's CLAUDE.md?	RT-A must test in 5 minutes; if walk-up fails, we adopt the @import-everywhere pattern from prior-chat ADRs.
Does Claude Code accept a symlinked project-id directory at `~/.claude/projects/-Users-coach-…/`?	RT-A test. Must verify Anthropic bugs #38469/#40300/#65 are real before committing.
Where exactly does session-summary logging live? Prior chat picked `~/reports/session-summaries/`; CC Advanced suggests SessionEnd hook + Memory 2.0; Paterson uses `~/llm-data/daily-log/`	Orchestrator picks based on `00b-prior-chat-jsonl-mined.md` patterns + your preference.
Wiki as git submodule vs regular subfolder of the lovebuilt repo?	Subfolder for now. Promote only if a second consumer materializes.
Vault topology for the knowledge system (one vault with permissions vs many separate vaults)	Knowledge-system research handoff (`_dev0/migration/knowledge/01`). Post-migration.
RAG vs NotebookLM vs Obsidian-only for personal KB queries	Same — knowledge-system handoff stack.
When does the static `_basecamp/INDEX.md` need to become a v2 routing skill?	Trigger: ~15 entries.
Ship the "VS Code zombie reaper" preemptively?	Lean: yes, 10-line script.

When you're ready to spawn the 00.1 orchestrator chat, it has a much richer evidence base than v1 had. It reads:

From all that, the orchestrator drafts the actual reviewer charters — Red Team A (architecture A–H), Red Team B (handoff §1–§9), Synthesis. Then those run.

The Migration, Refined