.agents/context/ Personal Context Layer, Rollout Plan

Date: 2026-07-13 Status: DRAFT / living (co-edited). Scoped via the planning skill. Design: ../specs/2026-07-13-agents-config-hierarchy-design.md (the context/ schema, loading model, parallel-session active-context, and worktree seeding are already designed there; this plan resolves the open decisions and lays out the build). Reconciles with: ../specs/2026-06-12-onboarding-bootstrap-cli-design.md (the lantern CLI + postinstall entry point). The /onboard context step plugs INTO that entry point; it does not build a new one. Also touches: today's Claude memory at ~/.claude/projects/<repo>/memory/ (source of the initial migration).

Consolidation (rule 13)

• No open issues on context/onboarding/voice.
• Design is not a gap (parent spec covers it). The gaps are the four decisions below and the build sequence.
• Onboarding entry point is not a gap either (the 2026-06-12 CLI spec owns it). We add a content step, not a new trigger.

Decisions

1. Communication splits (per Mechelle, 2026-07-13)

The current .agents/rules/project/communication.md is really two things. Split it:

• Comms style (warm, recommendation-first, the decision matrix) is your voice, personal. It moves to context/my-voice.md (gitignored, per-user) and OUT of AGENTS.md.
• The origins convention (log naming origins to docs/fireside/ORIGINS.md, keep them plain) is project infrastructure any agent maintains. It stays a project rule, renamed naming-origins (still baked into every tool).

2. Single source of truth: context/ is canonical, Claude memory is a view (recommended)

Option	What it does	Risk
context/ is the source; Claude memory is generated/symlinked from it (rec)	One place authors context; ~/.claude/.../memory becomes a view	A sync/symlink step to maintain
Memory stays Claude-native; context/ mirrors it out	No change to Claude memory	Two authored sources = the exact drift the whole .agents/ effort fights

Recommendation: context/ is canonical. The one-time migration imports today's ~/.claude memory into context/; thereafter Claude reads context/ (via symlink from ~/.claude/.../memory to the context home, or a small sync). No file is authored in two places.

3. Gitignore-but-readable: sidestepped by the machine-level home

Context lives at a per-user machine home keyed by repo (~/.agents/context/<repo>/), which is OUTSIDE any repo, so there is no gitignore tension there. Each worktree gets a gitignored .agents/context/ that SYMLINKS to that home (the .gitignore entry already exists). Tools read the symlinked-in copy; git ignores it. Same pattern as the .env.local symlink.

4. Cross-tool reach: Claude first, others are best-effort later

Claude is the primary tool and reads memory natively, so Phase 1 targets Claude. Copilot/Cursor/Gemini have weak or no personal-context slots; fanning context out to them is the hardest, lowest-value part and is deferred to a late phase. Be honest that full cross-tool personal context may never be as clean as Claude's.

Rollout

1. Split Communication. Move comms style to context/my-voice.md (seed from user_communication_style.md); rename the origins half to a naming-origins project rule; remove the communication project rule. Recompile AGENTS.md. (Small, do first.)
2. Stand up context/ at the machine home with the schema (my-voice.md, people.md, active-context.md, projects.yaml, memories/). Migrate today's ~/.claude memory in. Make Claude read it (symlink or sync). Decide memories/ vs decisions/ split (open question in the parent spec).
3. /onboard content step wired into the lantern CLI / postinstall entry point (2026-06-12 spec): interview a new user (title, voice, people) and write their context/. Re-runnable. For Mechelle it is a migration, not an interview.
4. Worktree seeding helper (npm run worktree:add <branch>): symlink durable context in, stamp a fresh per-branch active/<branch>.md.
5. Cross-tool fan-out (Copilot/Cursor/Gemini): best-effort, last.

Live status

• [x] 1. Split Communication: comms style -> .agents/context/my-voice.md (gitignored), origins -> naming-origins project rule, communication rule removed, AGENTS.md recompiled (2026-07-13)
• [~] 2. context/ machine home stood up via context-bootstrap.mjs (2026-07-13): ~/.agents/context/<repo>/ with my-voice (seeded) + people + active-context + projects.yaml, and memories symlinked to the live Claude memory. Safety refinement: for the memory subtree, Claude memory stays the source and context points AT it (inverts the "context canonical" direction for memories only, to avoid destructive surgery on the live memory this session depends on). my-voice/people/etc. are new-in-the-home. Still open: flipping memory to context-canonical, and wiring non-Claude tools to read the home (Phase 5).
• [x] 3. context-onboard skill authored (2026-07-13): /context-onboard runs context-bootstrap, interviews the user (voice/people/projects), and writes the home. Now wired into the lantern CLI as lantern onboard (runs context-bootstrap, then points at /context-onboard for the agent-driven interview), shipped 2026-07-13 with the onboarding CLI (2026-06-12 spec, #595). (The interview is agent-driven and conversational, so it is not auto-testable here.)
• [x] 4. worktree-add.mjs (npm run worktree:add -- <branch>): git worktree add (or --new off origin/dev) + .env.local symlink + .agents/context symlink to the machine home + a fresh per-branch active/<branch>.md + npm ci. Dry-run verified; the agent cannot run the real worktree op (rule 17), the user does. .gitignore tightened so the context symlink is ignored. (2026-07-13)
• [x] 5. context-sync-tools.mjs (npm run context:sync-tools): fans my-voice out to gitignored Cursor (.cursor/rules/my-voice.local.mdc) + Copilot (.github/instructions/my-voice.local.instructions.md) files, which those tools read by path regardless of git. Best-effort (personal, gitignored); Claude gets voice natively. (2026-07-13). Still deferred by choice: flipping the memory subtree to context-canonical (Phase 2 note).

Open questions

• memories/ vs decisions/ (facts vs ADR-style rationale): one folder or two? (inherited from the parent spec)
• Symlink vs small compiler for the Claude-memory view: symlink is simpler; a compiler is needed if the memory format diverges from the context/ format.
• Where exactly the machine home lives and how it is keyed (git common dir vs remote URL) so it resolves to the repo, not the worktree.