Persona Dev

---
name: persona-dev
description: This skill should be used when the user asks to "create a new persona", "build me a persona", "add a skill to an existing persona", "update a persona's CLAUDE.md or profile", "set up hooks or self-improvement", "document a new MCP tool in a persona", or improve how a persona works over time. Also triggers when the user says "my persona should remember this", "this keeps happening, make it a skill", "create a persona for", or "persona evolution".
---

# Persona Development

Personas live in `~/.personas/{name}/`, each as its own git-tracked directory with sandbox isolation.

## Persona Structure

Each persona contains:

```
~/.personas/{name}/
├── .claude/
│   ├── settings.json              # Sandbox config (committed)
│   ├── settings.local.json        # autoMemoryDirectory (gitignored, created during setup)
│   ├── output-styles/             # Personality, tone, style (committed)
│   ├── hooks/
│   │   └── public-repo-guard.sh   # Blocks personal data in public repos (committed)
│   └── skills/
│       ├── {domain}/{skill}/SKILL.md  # Domain skills
│       └── self-improve/SKILL.md      # Ships with every persona
├── .gitignore                     # Secrets exclusion
├── hooks.json                     # SessionStart + Stop + StopFailure + PreCompact + PostCompact + PreToolUse hooks
├── .framework-version             # Framework version stamp (committed)
├── CLAUDE.md                      # Personality + rules
├── docs/                          # Reference materials, plans
├── .mcp.json                      # MCP server config (gitignored)
├── tools/                         # Utilities, scripts, pipelines (committed)
├── docs/                          # Reference materials, plans (committed)
└── user/                          # Personal data silo (gitignored for public sharing)
    ├── profile.md                 # User context (filled from interview)
    └── memory/                    # Native auto-memory
        ├── MEMORY.md              # Index (first 200 lines loaded)
        └── *.md                   # Topic files (read on demand)
```

**Workspace organization:**
- `docs/` — domain knowledge, reference materials, plans. Use subdirs for categories (`docs/reference/`)
- `tools/` — executable tools, utilities, data pipelines. Each tool gets its own subdir if non-trivial
- `.claude/skills/` — reusable multi-step workflows (SKILL.md files)
- `user/` — personal data silo, ensure ALL personal data lands here: profile.md and auto-memory. Gitignored for public sharing
- Root — only framework files. Don't dump loose files here

---

## Creating a New Persona

### Phase 1: Discovery

Before building anything, understand what this persona needs to be. **Use `AskUserQuestion` for ALL discovery questions** — not conversational prompting. This gives the user structured input fields instead of a wall of text. Ask one topic at a time, with follow-ups as needed.

**Step 1: Domain & Name** — `AskUserQuestion`
- What domain or role? (finance advisor, personal chef, brand strategist, etc.)
- Suggest 4-5 fun, memorable first names that fit the role
- Let the user pick or propose their own
- Use `multiSelect: false` with name options + a "Something else" option

**Step 2: Personality & Voice** — `AskUserQuestion`
- Present 3-4 personality archetypes that fit the domain (e.g., "Enthusiastic mentor", "Dry-witted expert", "Patient teacher", "Opinionated veteran")
- Include a brief preview of each (1-2 sentences showing how it would sound)
- Ask for preferences: casual vs formal, opinionated vs neutral, proactive vs reactive

**Step 3: Workflows & Capabilities** — `AskUserQuestion`
- What key workflows will it handle? (weekly reviews, meal planning, code review, etc.)
- Are there recurring multi-step tasks? (→ skill planning)
- What kind of data does it work with? (→ tool/script needs)
- What should the persona push back on? (→ anti-patterns in CLAUDE.md)

**Step 4: User Context** — `AskUserQuestion`
- What does the user need the persona to know about them? (info, accounts, preferences, constraints)
- This shapes `user/profile.md` — ask what sections matter for this domain

**Step 5: Environment** — `AskUserQuestion`
- What environment? (CLI only, Desktop only, or both)
- Autodetect OS when possible (`uname`, check for WSL, check for Windows paths)
- Present detected config and confirm
- This determines Phase 9 setup (aliases, Desktop config, or both)

**Step 6: External Services** — `AskUserQuestion`
- What external services or APIs does the persona need?
- Present common integrations for the domain as options
- This feeds directly into Phase 2 research

**Step 7: Inheritance Posture** — `AskUserQuestion`

Personas inherit some things from the user's `~/.claude/` directory by default. Ask which posture the user wants for this persona — high-level first, then drill down if they want granular control.

**Initial question** (single-select):
- **Strict isolation** — block global CLAUDE.md, no extra plugins. The persona only sees its own scaffold + the framework defaults (persona-manager, personas-mesh)
- **Selective inheritance (Recommended)** — block global CLAUDE.md, but choose plugins explicitly from `~/.claude/plugins/marketplaces/`. Default for most personas
- **Open inheritance** — inherit Wils's global CLAUDE.md too (for personas that want the user's voice/style/red-lines applied). Rare; only choose if the persona is meant to *be* an extension of the user

**If "Selective inheritance":** drill down with up to two follow-up `AskUserQuestion` calls:

1. *Block global CLAUDE.md?* — yes (default) writes `claudeMdExcludes: ["**/.claude/CLAUDE.md"]` to the persona's `.claude/settings.json`. No keeps the leak
2. *Which plugins to enable?* — multi-select from the available plugins. Discover them via:
   ```bash
   for mp in ~/.claude/plugins/marketplaces/*/plugins/*/.claude-plugin/plugin.json; do
     jq -r '.name' "$mp"
   done
   ```
   Default-checked: `persona-manager@personas`, `personas-mesh@personas`, `vault@core`, `obsidian@obsidian-skills` (every persona needs the framework pair plus vault + obsidian for the shared-brain integration baked into CLAUDE.md). User adds domain-relevant plugins beyond those

**If "Strict isolation":** apply the same as Selective with claudeMdExcludes ON and only the two framework plugins enabled. No drill-down.

**If "Open inheritance":** skip `claudeMdExcludes`. Still ask which plugins to enable (the global plugin set doesn't auto-merge — the persona's settings.json explicitly lists them).

Store the chosen posture (and chosen plugin list) so Phase 5h can apply them.

Don't rush this. A well-understood persona is easier to build and evolves better. Ask follow-up questions — domain expertise matters.

### Phase 2: Research

Before writing a single file, research what tools and integrations could enhance this persona. Think broadly — personas have a rich toolkit beyond MCP servers:

1. **MCP servers** — search for community or official MCP servers relevant to the domain (recipe APIs, financial data, calendar, etc.). Existing servers beat custom solutions
2. **CLI tools** — identify useful CLI tools already installed or easily available (`gh`, `jq`, domain-specific CLIs)
3. **APIs** — identify REST/GraphQL APIs the persona could call directly via `curl` or scripts in `tools/`. Not everything needs an MCP server — sometimes a simple API call in a bash script is the right tool
4. **Skills** — plan domain skills that wrap CLI tools, API workflows, or multi-step processes into reusable SKILL.md files. Skills are the persona's playbooks — they turn "I know how to use this tool" into "here's the complete workflow"
5. **Agents** — consider whether the persona needs specialized subagents (in `.claude/agents/`) for complex autonomous tasks like research, analysis, or multi-step operations
6. **Hooks** — beyond the standard SessionStart/Stop/PreCompact, consider domain-specific hooks (e.g., a PreToolUse hook that validates data before writes, a Stop hook that generates a summary)
7. **Scripts** — bash or python scripts in `tools/` for data pipelines, API wrappers, formatters, or anything the persona does repeatedly
8. **Reference material** — domain-specific best practices, checklists, templates, or frameworks that should live in `docs/`
9. **Scheduled tasks** — identify workflows that benefit from timed reminders or delayed checks. Any persona can schedule tasks using natural language ("remind me at 3pm to...", "in 45 minutes, check whether..."). These are session-scoped — they vanish on exit. Suggest domain-specific scheduling patterns during persona setup and document them in the CLAUDE.md template
10. **Expansion packs** — check if any persona-manager expansion packs fit:
   - `persona-manager:persona-dashboard` — visual dashboard with task tracking (good for personas with ongoing work, reviews, or regular check-ins)

| Discovery | Where it lives | When to choose it |
|-----------|---------------|-------------------|
| MCP server | `.mcp.json` + sandbox allowlist | Persistent connection to an external service |
| CLI tool | Document in CLAUDE.md or wrap in a skill | Mature tool already exists for the job |
| API (direct) | `tools/` script or skill instructions | Simple HTTP calls, no persistent connection needed |
| Skill | `.claude/skills/{domain}/{name}/SKILL.md` | Multi-step workflow the persona will repeat |
| Agent | `.claude/agents/{name}.md` | Autonomous subtask needing its own context |
| Hook | `hooks.json` | Behavioral automation tied to session events |
| Script | `tools/{name}` | Data processing, automation, one-off utilities |
| Scheduled task | Scheduling patterns in CLAUDE.md | Timed reminders, delayed checks |
| Reference doc | `docs/` | Domain knowledge the persona should internalize |

Present findings to the user: "Here's what I found that could enhance this persona: [list]. Which of these should we include?"

### Phase 3: Plan Review

Before touching the filesystem, present the complete persona plan to the user for approval using `AskUserQuestion`. This is the gate — nothing gets built until the user says go.

**Include in the plan summary:**
1. **Identity** — name, role, personality archetype chosen in Phase 1
2. **Integrations** — every MCP server, CLI tool, API, and script from Phase 2 research, with status (found / needs setup / custom build)
3. **Skills** — planned domain skills with trigger phrases and brief descriptions
4. **Hooks** — standard 6 + any domain-specific hooks identified
5. **Sandbox** — network domains to allowlist for MCP servers and APIs
6. **File inventory** — complete list of files and directories that will be created
7. **Environment** — CLI/Desktop/both, OS detected, proposed launch flags

Present this as a single `AskUserQuestion` with options:
- "Looks good — build it" → proceed to Phase 4
- "I want to change something" → discuss and loop back
- "Start over" → return to Phase 1

**Do NOT proceed to scaffolding until the user approves the plan.** This prevents the assistant from barreling through file creation without alignment on what's being built.

### Phase 4: Scaffold

**First, validate the persona name:**
- Must match `^[a-z][a-z0-9-]*$` — lowercase letters, numbers, and hyphens only
- Must start with a letter (not a number or hyphen)
- No dots, slashes, spaces, or special characters — these break shell aliases and directory paths
- Maximum 30 characters — keeps paths manageable
- Reject immediately if the name contains `.`, `..`, `/`, `\`, spaces, or shell metacharacters (`$`, `` ` ``, `!`, `;`, `&`, `|`, etc.) — these could cause path traversal or command injection
- If invalid, explain why and suggest a corrected version (e.g., "My Finance Bot" → "finance-bot")

**Then check if the persona already exists:**
- If `~/.personas/{name}/CLAUDE.md` exists, stop and ask: "A persona named `{name}` already exists. Update it, or pick a different name?"
- Don't proceed with scaffolding if it would overwrite an existing persona

**Determine the personas root directory:**

| Environment | Personas root | Why |
|-------------|--------------|-----|
| macOS / Linux (native) | `~/.personas/` | Standard home directory |
| WSL2 (CLI only) | `~/.personas/` (WSL side) | Better I/O performance |
| WSL2 (CLI + Desktop) | `/mnt/c/Users/{WINUSER}/.personas/` + symlink from WSL `~/.personas/` | Both environments see the same files |
| Windows native (CLI or Desktop) | `%USERPROFILE%\.personas\` | Native Windows home |
| Cowork / Desktop session | **Workspace folder** — detect with `pwd` or workspace path, NOT `~` | `~` resolves to temp session filesystem that vanishes |

**Cowork detection:** If `$HOME` starts with `/sessions/` or the CWD is inside a temp path, you're in a Cowork session. Cowork runs in an isolated Linux VM — it can only access explicitly mounted folders and resolves symlinks to real paths (blocking escape). Find the actual workspace/mounted folder and write there instead.

**WSL2 + Desktop symlink:** When the user wants both CLI and Desktop, personas should live on the Windows side (`/mnt/c/Users/{WINUSER}/.personas/`) with a symlink from WSL's `~/.personas/`. **Important:** This symlink must be created from the WSL terminal, not from Cowork — Cowork cannot create symlinks to paths outside its mounted folders. Tell the user to run:
```bash
ln -s /mnt/c/Users/{WINUSER}/.personas ~/.personas
```

**Check sandbox prerequisites before scaffolding:**
- On Linux/WSL2: verify `bwrap` (bubblewrap) is installed: `command -v bwrap`
- If missing, warn the user and offer the install command before proceeding:
  - Ubuntu/Debian: `sudo apt-get install bubblewrap socat`
  - Fedora: `sudo dnf install bubblewrap socat`
- Don't block scaffolding — the persona will work without sandbox (with permission prompts instead). But warn clearly: "Without bubblewrap, the sandbox won't work and `--dangerously-skip-permissions` won't be safe to use. You'll get permission prompts for every action."
- On macOS: Seatbelt is built-in, no check needed
- On Windows native: no sandbox available, this is expected — flag it and move on

Create the directory structure:

```bash
mkdir -p ~/.personas/{name}/{.claude/output-styles,.claude/hooks,.claude/skills,tools,docs,user/memory}
```

### Phase 5: Build core files

> **🛑 Sacred rule for `user/` — never overwrite existing files.**
>
> Anything under `~/.personas/{name}/user/` is the user's personal data: profile, memory pages, MEMORY index. These accrue value over time and CANNOT be regenerated from a template. Before writing any file under `user/`, check whether it already exists. If it does, **skip the write and report what was preserved** ("preserved existing user/profile.md"). Only write if the file is missing — i.e., this is a true first scaffold.
>
> This rule applies whether persona-dev is being run on a fresh persona or invoked again on an existing one to apply framework scaffold updates. The framework's templates are bootstrap material, not source-of-truth. If you find yourself about to clobber a populated `user/profile.md` or `user/memory/MEMORY.md`, **stop and ask the user** — never assume regeneration is safe.

**5a. Write CLAUDE.md**

Use the template from `references/claude-md-template.md`. Key decisions:

- **Role summary**: One paragraph of spec-sheet expertise and operational focus. Personality and voice go in the output-style (`.claude/output-styles/`), NOT here. Boundary test: "Would this change how the persona SOUNDS, or what it DOES?" If SOUNDS → output-style. If DOES → CLAUDE.md
- **Workspace Hygiene section**: Include it — every persona must maintain its own workspace
- **Self-Improvement**: Point to the self-improve skill (one line, not inline)

**5b. Create user/profile.md** *(only if it does not already exist — see sacred rule above)*

**Guard first:** if `~/.personas/{name}/user/profile.md` already exists, skip this entire step and report "preserved existing user/profile.md". Do not read the template, do not customize, do not write. The existing profile is the user's personal data and is not yours to regenerate.

If the file is missing, use `references/profile-template.md` as a starting point and customize it for this persona's domain:
- Rename/add/remove sections to fit the domain (e.g., a finance persona needs "Accounts & Assets", a chef persona needs "Dietary Restrictions")
- Update placeholders to be domain-specific
- Update the interview instructions comment with persona-specific guidance on what to ask and how to probe deeper

Write directly to `user/profile.md`. On first session, the SessionStart hook reads this, sees the unfilled placeholders, and interviews the user to populate each section in place. No separate template file needed — the profile IS the template until it's filled out.

**Important: Use AskUserQuestion for the profile interview.** The persona should use the `AskUserQuestion` tool (not just conversation) when interviewing the user to fill out their profile. This provides a structured input experience — the user sees a clear question with context, rather than a wall of conversational text. Add this to the interview instructions in the template:
```
Use AskUserQuestion to ask each section's questions — one section at a time.
Present what you're asking about and why, then let the user respond.
```

**5c. Create output-style**

Create `.claude/output-styles/{name}.md` using `references/output-style-template.md`. This file defines WHO the persona IS:

- **Who I Am** — personality, narrative expertise, voice, opinions
- **How I'll Be** — behavioral traits (how the persona operates, not what it knows)
- **What I Won't Do** — character-driven refusals and anti-patterns (NOT operational rules — those go in CLAUDE.md)

The boundary rule: voice and personality go here; operational procedures, skills, tools, and security go in CLAUDE.md. Narrative expertise ("After 20 years in finance, I've seen every fad crash and burn...") goes here. Spec-sheet expertise ("Domains: budgeting, investing, tax planning") goes in CLAUDE.md's Role section.

Use the strong/weak examples from the template as guidance. The persona should have opinions and a point of view — bland personas get ignored.

**5d. Create first domain skill(s)**

Write at least one skill under `.claude/skills/{domain}/{skill-name}/SKILL.md` with:
- YAML frontmatter (name, description, triggers)
- Step-by-step workflow
- Expected output format

**5e. Copy self-improve skill**

Copy `references/self-improve-skill.md` to `.claude/skills/self-improve/SKILL.md`. Replace `{name}` with the persona name. This ships with every persona — it handles rule promotion, skill creation, tool discovery, and periodic audits. (Memory is handled by Claude Code's native auto-memory system, not by the self-improve skill.)

**5f. Set up hooks**

Copy `references/hooks-template.json` to `hooks.json` in the persona root. Copy `references/public-repo-guard.sh` to `.claude/hooks/public-repo-guard.sh` and make it executable (`chmod +x`). These hooks:
- **PreToolUse** (command, matcher: Bash): Runs `public-repo-guard.sh` before git commit/push — checks if the repo is public and blocks if personal data (`user/`, `.mcp.json`, secrets) would be exposed. Every persona gets this by default
- **SessionStart** (command): Injects instruction to read `user/profile.md` and interview the user if unfilled. No dependencies — just echoes a JSON instruction for Claude to act on. Must be `type: "command"` (SessionStart only supports command hooks)
- **Stop** (prompt): Prompts the persona to reflect on session insights — native auto-memory captures them automatically. Does NOT instruct manual file writes
- **StopFailure** (command): Writes a crash marker to `user/memory/.last-crash` when a session dies from an API error. PostCompact and the next SessionStart can detect this and offer to recover lost context
- **PreCompact** (prompt): Prompts reflection before compaction — auto-memory handles persistence. Does NOT instruct manual file writes
- **PostCompact** (command): After compaction, checks for the crash marker and reminds the persona to review what may have been lost

**5g. Create .gitignore**

Copy `references/gitignore-template` to `.gitignore`.

**5h. Configure sandbox + inheritance**

Copy `references/settings-template.json` to `.claude/settings.json`, then apply the inheritance posture chosen in Phase 1 Step 7:

- If posture is Strict or Selective with "block global CLAUDE.md = yes" → keep the `claudeMdExcludes: ["**/.claude/CLAUDE.md"]` from the template
- If posture is Open or Selective with "block global CLAUDE.md = no" → remove the `claudeMdExcludes` key
- Set `enabledPlugins` to the user's chosen plugin list (always include `persona-manager@personas` and `personas-mesh@personas` as the framework minimum)

Add any persona-specific network domains for MCP servers to `allowedDomains`. The template includes `extraKnownMarketplaces` and `enabledPlugins` to auto-install persona-manager — this gives every persona access to persona-dev for self-evolution without manual plugin installation.

Also create `.claude/settings.local.json` with the memory directory and output-style setting. **Use the absolute path** to the persona's memory directory — relative paths break on WSL where the project root is on `/mnt/c/` but Claude resolves relative paths from the Linux side:
```json
{
  "autoMemoryDirectory": "/absolute/path/to/.personas/{name}/user/memory",
  "outputStyle": "{PersonaName}"
}
```
For example, if the persona lives at `~/.personas/warren/`, the value would be `/home/username/.personas/warren/user/memory` (Linux/WSL) or `/Users/username/.personas/warren/user/memory` (macOS). Use the actual resolved path, not `~`.

**`outputStyle` must match the `name:` field in `.claude/output-styles/{name}.md` exactly** (case-sensitive). The convention is Capitalized — `Warren`, `Piper`, `Mila`. Without this, the persona boots in default Claude voice and the user has to run `/output-style {PersonaName}` manually each session.

**Important:** `autoMemoryDirectory` and `outputStyle` must be in `settings.local.json`, not `settings.json`. Claude Code ignores `autoMemoryDirectory` in project settings (`.claude/settings.json`) as a security measure — it only works from local or user settings. The `settings.local.json` file is gitignored, so persona-dev must create it during setup on each machine.

**5i. Create README.md**

Every persona repo gets a short README. Keep it minimal — this isn't a library, it's a personal assistant:

```markdown
# {PersonaName} {emoji}

> {One-line role description}

A self-evolving AI persona built on [Claude Code](https://claude.com/claude-code) using the [personas](https://github.com/kickinrad/personas) framework.

## Usage

```bash
{name}              # interactive session
{name} "do weekly"  # one-shot prompt
```

## Setup

See the [personas framework](https://github.com/kickinrad/personas) for installation and setup.
```

For **public repos**, consider adding a brief "What it does" section describing the persona's domain and skills.

**5L. Scaffold the vault home**

The persona's vault home is where its durable knowledge accrues (decisions, playbooks, captures). Bootstrap it now so the persona has a MOC to land work in from session one.

1. Check whether `~/.vault/Areas/Personas/{name}/` exists.
2. If missing, invoke `Skill('vault:knowledge')` MOC scaffold (or call the `/vault:repo-moc init Areas/Personas/{name}` slash command) to create the folder note. **Do not write new Python — use existing vault:knowledge capability.**
3. The MOC stub should have proper frontmatter (`author: {name}`, `type: persona-moc`, `created: <date>`), an "Open work" section, a "Recent captures" section, and link back to the persona's natural domain area if one applies (e.g., `[[Areas/Personal Admin/Home|Home]]` for a home-repair persona, `[[Areas/Ventures/Botwright|Botwright]]` for a venture-focused persona).
4. Skip Phase 5L with a clear warning if `~/.vault/` is unreachable (machine without WSL mount).

**5j. Validate scaffold**

Before proceeding, verify all required files exist:
- [ ] `README.md`
- [ ] `CLAUDE.md`
- [ ] `.claude/output-styles/{name}.md` (voice and personality)
- [ ] `user/profile.md` (template with placeholders, ready for first-session interview)
- [ ] `hooks.json`
- [ ] `.claude/hooks/public-repo-guard.sh` (executable)
- [ ] `.gitignore`
- [ ] `.claude/settings.json`
- [ ] `.claude/settings.local.json` (autoMemoryDirectory configured)
- [ ] `.claude/skills/self-improve/SKILL.md`
- [ ] At least one domain skill in `.claude/skills/`
- [ ] `.framework-version` (stamped with current plugin version)
- [ ] `~/.vault/Areas/Personas/{name}/{Name}.md` MOC exists (skipped if Phase 5L unavailable)

If anything is missing, fix it now — don't proceed with gaps.

**5k. Stamp framework version**

Write the current plugin version to `.framework-version` in the persona root. Read the version from this plugin's `.claude-plugin/plugin.json`. This single-line file tracks which framework version the persona was built with — persona-update uses it to detect drift.

### Phase 6: Configure integrations

If Phase 2 identified useful tools and integrations:

1. Document everything in CLAUDE.md under "Tools & Integrations" — organized by type (MCP servers, CLI tools, APIs, scripts)
2. For MCP servers: add domains to `.claude/settings.json` → `network.allowedDomains`, tell the user how to configure `.mcp.json` (gitignored — secrets go here)
3. For CLI tools: add usage instructions to relevant skills or CLAUDE.md
4. For APIs: create wrapper scripts in `tools/` or document usage patterns in skills
5. For skills: write the SKILL.md files that wrap tool usage into complete workflows
6. For agents: create agent definitions in `.claude/agents/` with appropriate system prompts and tool access
7. For hooks: add entries to `hooks.json` for domain-specific behavioral automation
8. For scripts: write to `tools/`, make executable, add brief comment header
9. For expansion packs: ask the user if they want to install them now

### Phase 7: Initialize git + GitHub sync

```bash
cd ~/.personas/{name}
git init
git add -A
git commit -m "feat({name}): initial scaffold"
```

**Always ask about GitHub sync** — don't skip this step:
- "Want to set up a GitHub repo so this persona syncs across machines?"
- If yes: `gh repo create {github-username}/{name} --private --source=. --push`
- If no: Skip — can always add a remote later
- Explain the benefit: backup, version history, sharing between CLI/Desktop/machines

**After creating the repo, set description and topics:**
```bash
gh repo edit --description "{PersonaName} — {one-line role description}. A self-evolving AI persona on Claude Code."
gh repo edit --add-topic claude-code --add-topic persona
```
Add 1-2 domain-specific topics too (e.g., `finance`, `cooking`, `fitness`).

**Public vs private — the persona handles this, not the user:**
- **Private repo (default):** Safe to commit everything including `user/` (profile, memories). Good for personal backup and cross-machine sync
- **Public repo:** If the user chooses public (or says "make it public"), the persona MUST immediately:
  1. Uncomment `user/` in `.gitignore`
  2. Remove `user/` from git tracking: `git rm -r --cached user/`
  3. Commit the change: `git commit -m "fix({name}): gitignore user/ for public repo"`
  4. Create a fresh remote (don't push existing history that may contain personal data)
- **Going public later:** If the self-improve skill or the user detects the repo has gone public, the persona handles the same steps automatically — don't ask the user to do it manually, they'll forget. The `public-repo-guard.sh` hook is the safety net, but the persona should proactively fix the gitignore rather than waiting for the hook to block

**Never commit these to any repo (public or private):**
- `.mcp.json` — contains API keys and secrets (always gitignored)
- Files matching `*.env`, `*.secret`, `*.key`, `*.pem` — credential files

### Phase 8: Configure launch flags

Before setting up aliases or Desktop access, determine the right CLI flags for this persona. Autodetect the environment, present defaults, and walk the user through customization.

**Step 1: Autodetect environment**

```bash
# Detect OS and sandbox support
if [[ "$(uname -s)" == "Darwin" ]]; then
  OS="macOS"         # Seatbelt built-in, sandbox always available
  SANDBOX_OK=true
elif grep -qi microsoft /proc/version 2>/dev/null; then
  OS="WSL2"          # bubblewrap needed
  SANDBOX_OK=$(command -v bwrap &>/dev/null && echo true || echo false)
elif [[ "$(uname -s)" == "Linux" ]]; then
  OS="Linux"         # bubblewrap needed
  SANDBOX_OK=$(command -v bwrap &>/dev/null && echo true || echo false)
elif [[ "$OS" == "Windows_NT" ]] || command -v cmd.exe &>/dev/null; then
  OS="Windows"       # No sandbox support
  SANDBOX_OK=false
fi
```

If sandbox prerequisites are missing on Linux/WSL2, tell the user:
```bash
sudo apt-get install bubblewrap socat  # Ubuntu/Debian
sudo dnf install bubblewrap socat      # Fedora
```

**Step 2: Present default flags and walk through customization**

Present the detected config and walk the user through each flag using `AskUserQuestion`. Explain what each one does, why it matters, and the tradeoff. **All flags are optional** — the user decides:

| Flag | What it does | Ask the user |
|------|-------------|--------------|
| `--name {name}` | Sets the session display name in the terminal title and prompt bar. Makes it easy to identify which persona is running | Always include — uses the persona name. No need to ask |
| `--setting-sources project,local` | Loads only this persona's `settings.json` and `settings.local.json`, ignoring `~/.claude/settings.json`. Keeps permissions, sandbox, and MCP config isolated. **Note:** does NOT affect `CLAUDE.md` loading — for that, the persona's `.claude/settings.json` uses `claudeMdExcludes` to block `~/.claude/CLAUDE.md` from auto-discovery | "This keeps your persona's settings isolated from your global Claude config. Recommended ON unless you want global settings to merge in. Enable?" |
| `--dangerously-skip-permissions` | Skips permission prompts for every tool use. **Only safe when OS-level sandbox is active** (macOS/Linux/WSL2) — the sandbox restricts filesystem + network even without prompts. **NEVER on Windows** | "This lets the persona work without asking permission for every action. It's safe because the sandbox restricts what it can access. Want autonomous mode, or prefer to approve actions manually?" |
| `--remote-control` | Enables browser extension integration and external tool connections | "This allows tools like the Chrome extension to connect to your persona. Enable?" |
| `--chrome` | Enables Claude in Chrome browser automation. Gives the persona access to your Chrome browser for web interaction, form filling, screenshots, and debugging | "This lets the persona interact with your Chrome browser (requires the Claude in Chrome extension). Does this persona need browser access?" |

**Resulting flag sets by environment (defaults, all customizable):**

| Environment | Sandbox? | Default flags |
|-------------|----------|---------------|
| macOS | Yes (Seatbelt) | `--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control` |
| Linux | Yes (bubblewrap) | `--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control` |
| WSL2 | Yes (bubblewrap) | `--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control` |
| Windows native | **No** | `--name {name} --setting-sources project,local --remote-control` |

`--name` is always included with the persona's name — it labels the session in the terminal title and prompt bar. `--chrome` is not in the defaults but is always offered as an optional addition during the walkthrough.

---

**⚠ WINDOWS NATIVE — CRITICAL SAFETY WARNING ⚠**

**NEVER use `--dangerously-skip-permissions` on Windows native.** Windows does not have OS-level sandboxing (no Seatbelt, no bubblewrap). This flag would give the persona **completely unrestricted access** to the entire filesystem and network — it could read any file, delete anything, and make arbitrary network requests with zero guardrails.

On macOS/Linux/WSL2, `--dangerously-skip-permissions` is safe because the sandbox blocks dangerous operations at the OS level even when permissions are skipped. On Windows, there is no such safety net.

**If the user asks to enable it on Windows, refuse and explain why.** Even if they insist. This is not a preference — it's a safety boundary. The persona-dev skill must enforce this by never writing `--dangerously-skip-permissions` to `.claude-flags` on Windows native, regardless of user request.

---

Present defaults first, then offer customization via `AskUserQuestion`:
1. Show the recommended flag set for the detected OS environment (from the table above)
2. Briefly explain what each flag does in plain language
3. Ask: "These are the recommended defaults for your {OS} setup. Look good, or want to customize?"
4. If the user wants to customize, walk through each flag individually using `AskUserQuestion` — use the "Ask the user" column from the table above
5. `--chrome` is always presented as an optional addition: "Want to add Chrome browser automation? This lets the persona interact with web pages in your Chrome browser (requires the Claude in Chrome extension)."
6. On Windows, explain why `--dangerously-skip-permissions` is not available before moving on
7. Summarize the final chosen flags before writing to `.claude-flags`

**Step 3: Store the flags**

Write the chosen flags into `~/.personas/{name}/.claude-flags` (a single line, sourced by the alias):

```bash
echo '--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control' > ~/.personas/{name}/.claude-flags
```

This file is read by `.aliases.sh` so each persona can have its own flag configuration.

### Phase 9: Configure access + verify

Setup depends on the environment detected in Phase 1:

**CLI (macOS / Linux / WSL2) — shell aliases:**

1. **Create `~/.personas/.aliases.sh`** if it doesn't exist (see [CLI Aliases](#cli-aliases) below for the template)
2. **Add source line to the user's shell config** if not already present:
   - Detect the user's shell from `$SHELL`
   - For zsh: append to `~/.zshrc`
   - For bash: append to `~/.bashrc`
   - The line to add: `[ -f "$HOME/.personas/.aliases.sh" ] && source "$HOME/.personas/.aliases.sh"`
   - **Check first** — only add if the line isn't already there
3. **Tell the user** to restart their shell or run `source ~/.personas/.aliases.sh` to activate immediately

**Windows native (no WSL) — PowerShell function:**

Windows users without WSL can't use bash aliases. Create a PowerShell function instead:

```powershell
# Add to $PROFILE (e.g., ~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1)
function {name} {
    param([Parameter(ValueFromRemainingArguments)]$args)
    Push-Location "$env:USERPROFILE\.personas\{name}"
    if ($args) {
        claude --name {name} --setting-sources project,local --remote-control -p ($args -join ' ')
    } else {
        claude --name {name} --setting-sources project,local --remote-control
    }
    Pop-Location
}
```

Note: no `--dangerously-skip-permissions` — Windows has no sandbox.

**Desktop (macOS + Windows only):**

Desktop is not available on Linux — Linux users are CLI-only.

1. Tell the user to select `~/.personas/{name}/` as their project folder in Claude Desktop
2. If MCP servers were configured in `.mcp.json`, offer to merge them into `claude_desktop_config.json`:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
3. Remind user to restart Claude Desktop after config changes
4. Note: Desktop Code tab reads `.mcp.json` (same as CLI), but Desktop Chat and Cowork read only `claude_desktop_config.json` — MCP servers need to be in both for full coverage

**Important environment limitations:**
- **Cowork** runs in an isolated Linux VM — can only access explicitly mounted folders, blocks symlinks outside scope. Reads MCP from `claude_desktop_config.json` (global), not `.mcp.json`. Cross-environment setup (WSL symlinks, Desktop config merges) must be done from a terminal, not Cowork.
- **Desktop Code tab** IS sandboxed (OS-level: Seatbelt on macOS, bubblewrap on Linux/WSL2) — reads `.mcp.json` from the project.
- **Windows native** does NOT support sandboxing — never use `--dangerously-skip-permissions`.

Then verify the persona works — run through the [Testing a Persona](#testing-a-persona) checklist.

---

## Lifecycle meta — three-layer model, aliases, expansion, testing, troubleshooting

For the meta-context around the 9-phase scaffold above (three-layer model, profile vs memory boundary, CLI alias setup script, first-session flow, MCP availability check, expansion packs, testing checklist, troubleshooting, guiding persona growth), see [references/lifecycle-meta.md](./references/lifecycle-meta.md).

---

## References

Templates and helper files used by the scaffolding phases above. All live in `references/` alongside this SKILL.md.

- [[Resources/Repos/personal/personas/plugins/persona-manager/skills/persona-dev/references/claude-md-template|claude-md-template]] — CLAUDE.md skeleton written in Phase 5a
- [[Resources/Repos/personal/personas/plugins/persona-manager/skills/persona-dev/references/output-style-template|output-style-template]] — `.claude/output-styles/{name}.md` skeleton written in Phase 5c
- [[Resources/Repos/personal/personas/plugins/persona-manager/skills/persona-dev/references/profile-template|profile-template]] — `user/profile.md` skeleton written in Phase 5b
- [[Resources/Repos/personal/personas/plugins/persona-manager/skills/persona-dev/references/self-improve-skill|self-improve-skill]] — self-improve SKILL.md copied into every persona in Phase 5e