Claude Personas v2 Design

# claude-personas v2 — Design

**Date**: 2026-05-07
**Status**: Approved (ready for implementation planning)
**Author**: Jin-Ho Lee (with Claude Code)

## Background

`claude-personas` v1 ships per-role memory directories (`developer/`, `pm/`, `designer/`, `shared/`) and wires each project worktree to the matching role via Claude Code's `autoMemoryDirectory` setting in project-level `.claude/settings.local.json`.

That setting has been silently ignored at project level since at least 2026-03-20 (see [issue #55801](https://github.com/anthropics/claude-code/issues/55801) and related #36636, #39204, #46701, #49995). Empirically:

- Project-level `autoMemoryDirectory` in `.claude/settings.local.json` is silently dropped — system prompt reports the default `~/.claude/projects/<hash>/memory/` path
- User-level `autoMemoryDirectory` in `~/.claude/settings.json` IS honored, but as a *literal* path with no per-project sub-structure — all projects collide in one flat directory

In short: there is no working configuration that lets multiple projects each have their own memory directory via `autoMemoryDirectory`. v1's documented pattern is non-functional. v1 only continues to work in practice because of a custom `CLAUDE.local.md` + skill-based workaround that bypasses the setting entirely.

This spec defines v2: replace `autoMemoryDirectory` with native filesystem symlinks at Claude Code's existing per-project hash-derived memory paths. No reliance on Claude Code settings beyond defaults.

## Decisions made during brainstorming

1. **Scope**: mechanism swap + cleanup. Not a full structural rethink.
2. **Memory location**: each role's memory dir at Claude Code's native `~/.claude/projects/<hash>/memory/` is symlinked into a `claude-personas` clone.
3. **Release strategy**: replace v1 — tag old as `v1.0`, merge v2 as new `main`.
4. **Repo strategy**: claude-personas is cloned **once per project** (not once globally as in v1).
5. **Shared layer**: per-project shared via project's main-repo hash dir, surfaced through a triple-symlink chain.
6. **Migration**: no dedicated migration script (no real v1 user base to support); short manual recipe in CHANGELOG.

## Architecture

### Topology

Per-project setup. The "main repo" is unused by any role — every role gets its own worktree.