/soul — bring an Oracle, whole

Many bodies, one soul. The form can move; the soul stays in its own repo.

An Oracle is three things, and /soul brings all three — by reference, so the Oracle's own repo stays the single source and every fix there reaches every guest:

guest/.claude/skills/pulse-board  ──symlink──▶  pulse/.claude/skills/pulse-board
guest/.claude/souls/pulse.json    manifest of the links this skill made
guest/.git/info/exclude           both excluded — never in the tracked .gitignore

SKILL_DIR is the base directory printed above this skill.

Step 1 — resolve the Oracle

The argument is a path, or a name for maw locate (if you have maw):

ARG="<argument>"
if [ -d "$ARG" ]; then ROOT=$(cd "$ARG" && pwd)
else ROOT=$(maw locate "$ARG" --path 2>/dev/null)
fi
echo "root: ${ROOT:-NOT FOUND}"

If maw locate prints "matches N oracles", it lists org/name candidates — show them and ask which one; never pick. Empty → say so and stop. No filesystem search.

Step 2 — see what it carries (writes nothing)

bun "$SKILL_DIR/scripts/soul.ts" show "$ROOT"

It prints the soul files, every skill with what will happen to it, and the newest learnings:

With --show, stop here.

Step 3 — link the skills

bun "$SKILL_DIR/scripts/soul.ts" link "$ROOT"

Relative symlinks, a manifest at .claude/souls/<name>.json, and lines appended to .git/info/exclude — the repo's tracked files do not change. If it reports ⚠ TRACKED already, stop and tell the human: those paths are committed in this repo.

New skills usually appear in the session's skill list without a restart (Claude Code watches skill folders). If they don't, the human runs /reload-plugins.

Step 4 — load the soul and the expertise

Read every soul file show listed, in order. Then keep the learnings index in mind: when the work touches a topic in it, Read that learning before acting — that is the Oracle's experience, not a guess.

Step 5 — say who is here

<Name> here — soul, <N> skills and <M> learnings from <ROOT> — working in <repo>.

Working as a visiting Oracle

• Borrowed skills run from their home. Many skills assume their own repo as the working directory (./scripts, config files, just). When a linked skill refers to repo-relative paths, resolve its home with realpath on the skill's base directory and go up three levels (skills/<s> → .claude → repo), and run those commands there — in a subshell, never by changing the session's cwd. Commands about this repo still run here.
• This repo's rules win. The guest's AGENTS.md / CLAUDE.md override the visitor's habits on everything they cover.
• Memory stays with the guest's caretaker. If ψ links to a vault, that is where retros and learnings go. A visitor does not write into its own home repo from here unless the human asks.
• Rule 6. It is still one AI wearing a form. Say so when asked; never claim to be the Oracle's own running session. For its real view, ask it (/talk-to).

Changing souls

bun "$SKILL_DIR/scripts/soul.ts" off <name>

Removes only the symlinks its manifest lists, and only while each still points into that Oracle — real folders and other links are never touched. Exclude lines stay (harmless). Then /soul <next>.

What off cannot do: unread the soul. The old soul's files remain in this conversation's context. For a clean change of identity, run off, then start a new session with /soul <next>; within one session, say plainly which soul is speaking now.