adopt

---
name: adopt
description: Scaffold the PKM system onto an existing Obsidian vault. Scans your vault structure, maps folders interactively, and generates configuration — no template required.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
model: sonnet
user-invocable: true
---

# Adopt Skill

Bring Your Own Vault (BYOV) — install the Claude PKM system onto an existing Obsidian vault.

## Usage

```
/adopt    # Run from the root of your existing Obsidian vault
```

## When to Use

- You have an existing Obsidian vault and want to add the Claude PKM system
- You don't want to start from the vault template
- You want to keep your current folder structure

## Phase 1: Scan Vault Structure

Analyze the existing vault to understand its organization.

### Steps

1. **List top-level directories** using `ls`, excluding system dirs (`.obsidian`, `.git`, `.claude`, `.trash`, `.claude-plugin`)

2. **For each directory**, gather signals:
   - Count `.md` files (using Glob)
   - Check for date-named files (`YYYY-MM-DD*.md`) — indicates daily notes
   - Grep for goal/review/template keywords in filenames and content
   - Check for existing `CLAUDE.md` in subdirs — indicates projects

3. **Detect organization method** based on signals:
   - **PARA**: Folders named Projects, Areas, Resources, Archives
   - **Zettelkasten**: Numeric-prefixed notes, heavy wiki-linking, flat structure
   - **Johnny Decimal**: `00-09`, `10-19` style folder names
   - **LYT (Linking Your Thinking)**: Folders named Atlas, Calendar, Cards, Extras, Sources
   - **Flat**: Few folders, most files at root
   - **Custom**: None of the above patterns match

4. **Present findings** to the user:
   ```
   Vault scan complete!

   Found 342 notes across 8 folders:
     Daily/           → 180 notes (date-named — likely daily notes)
     Projects/        → 45 notes (has CLAUDE.md files — likely projects)
     Goals/           → 12 notes (contains goal keywords)
     Templates/       → 8 notes (contains template keywords)
     Archive/         → 67 notes
     Inbox/           → 15 notes
     Resources/       → 10 notes
     Meeting Notes/   → 5 notes

   Detected method: PARA-like structure
   ```

## Phase 2: Map Folders to Roles

Use AskUserQuestion to confirm or correct the detected mappings.

### Roles to Map

Each role maps a PKM function to a folder in the user's vault:

| Role | Purpose | Detection Signal |
|------|---------|-----------------|
| Daily Notes | Daily journal entries | Date-named files (`YYYY-MM-DD`) |
| Goals | Goal cascade (3-year → weekly) | Files with goal/review keywords |
| Projects | Active projects | Subdirs with CLAUDE.md or project keywords |
| Templates | Reusable note structures | Files with template keywords or in Templates/ |
| Archives | Completed/inactive content | Folder named Archive(s) or with old dates |
| Inbox | Uncategorized captures | Folder named Inbox, or files tagged #inbox |

### Interactive Mapping

For each role, ask the user to confirm or correct:

**Question format (use AskUserQuestion):**
- "Which folder holds your **daily notes**?"
- Options: detected candidate(s), "I don't have one (create it)", "Skip — I don't use this"
- For optional roles (Inbox), include "Skip" as a default

**Edge cases:**
- **Existing CLAUDE.md at root**: Ask the user — back up as `CLAUDE.md.backup` or merge content
- **No candidate for a role**: Offer to create the folder
- **Multiple candidates**: Present all and let the user choose

### Save Mappings

Store the folder mapping for use in later phases:
```
dailyNotes → "Daily"
goals → "Goals"
projects → "Projects"
templates → "Templates"
archives → "Archive"
inbox → "Inbox"     (or null if skipped)
```

## Phase 3: Personalize Preferences

Ask the same 4 questions as `/onboard`:

**Question 1: Your name**
- "What should I call you?"
- Used for personalized prompts and greetings

**Question 2: Preferred review day**
- "What day do you prefer for your weekly review?"
- Options: Sunday (Recommended), Saturday, Monday, Friday
- Used by `/review` auto-detection and session-init nudges

**Question 3: Primary goal areas**
- "Which areas are most important to you right now? (Pick 2-4)"
- Options: Career & Professional, Health & Wellness, Relationships, Personal Growth
- Also offer: Financial, Creativity & Fun, Learning, Other
- multiSelect: true
- Used to customize goal template suggestions

**Question 4: Work style**
- "How do you prefer Claude to interact?"
- Options: Direct and concise (Recommended), Coaching and challenging, Detailed and thorough, Minimal — just do the task
- Sets output style preference

## Phase 4: Generate Configuration

### 4a. Write `settings.json`

Write `.claude/settings.json` with permissions scoped to the user's actual folders:

```json
{
  "permissions": {
    "allow": [
      "Read",
      "Write **/{mapped-daily}/**",
      "Write **/{mapped-goals}/**",
      "Write **/{mapped-projects}/**",
      "Write **/{mapped-templates}/**",
      "Edit **/{mapped-daily}/**",
      "Edit **/{mapped-goals}/**",
      "Edit **/{mapped-projects}/**",
      "Glob",
      "Grep"
    ]
  }
}
```

Replace `{mapped-*}` with actual folder names from Phase 2.

### 4b. Write root `CLAUDE.md`

Generate a root `CLAUDE.md` that describes the user's **actual** vault structure. Use the same format as the template's CLAUDE.md but with:
- Their folder names in the Directory Structure table
- Their goal areas in the System Purpose section
- Their actual skills table (same as template)
- Cascade section adapted to their folder names

If the user had an existing `CLAUDE.md`, merge their content into the appropriate sections (preserve their mission statement, custom conventions, etc.).

### 4c. Write `vault-config.json`

Write `vault-config.json` in the vault root:
```json
{
  "name": "User's name",
  "reviewDay": "Sunday",
  "goalAreas": ["Career & Professional", "Health & Wellness"],
  "workStyle": "Direct and concise",
  "setupDate": "2026-02-17",
  "version": "3.1",
  "adoptedVault": true,
  "folderMapping": {
    "dailyNotes": "Daily",
    "goals": "Goals",
    "projects": "Projects",
    "templates": "Templates",
    "archives": "Archive",
    "inbox": "Inbox"
  }
}
```

### 4d. Set Environment Variables

Write or update `CLAUDE.local.md` with env var exports for hooks:
```markdown
## Environment Overrides

These env vars allow hooks and scripts to find your folders:

<!--
Export these in your shell profile or they'll be set by session-init:
-->
DAILY_NOTES_DIR={mapped daily notes folder}
GOALS_DIR={mapped goals folder}
PROJECTS_DIR={mapped projects folder}
TEMPLATES_DIR={mapped templates folder}
INBOX_DIR={mapped inbox folder}
ARCHIVES_DIR={mapped archives folder}
```

Also create `.claude/hooks/adopt-env.sh` that exports these variables:
```bash
#!/bin/bash
# Environment variables for adopted vault folder mapping
# Generated by /adopt — edit vault-config.json and re-run /adopt to update

export DAILY_NOTES_DIR="{mapped daily notes}"
export GOALS_DIR="{mapped goals}"
export PROJECTS_DIR="{mapped projects}"
export TEMPLATES_DIR="{mapped templates}"
export INBOX_DIR="{mapped inbox}"
export ARCHIVES_DIR="{mapped archives}"
```

Then add a `source` line to `session-init.sh` if not already present:
```bash
# Source adopted vault env vars if present
ADOPT_ENV="$VAULT_PATH/.claude/hooks/adopt-env.sh"
if [ -f "$ADOPT_ENV" ]; then
    source "$ADOPT_ENV"
fi
```

## Phase 5: Scaffold Missing Pieces

Check what's missing and offer to create it. **Always ask before creating.**

### 5a. Goal Cascade Files

If the goals folder is empty or newly created:
- "Your goals folder is empty. Want me to create the goal cascade? (3-year vision, yearly goals, monthly goals, weekly review)"
- If yes: copy the standard templates, adapting paths to the user's folder names
- If no: skip

### 5b. Templates

If the templates folder is empty or newly created:
- "Want me to add standard templates? (Daily, Weekly Review, Project)"
- If yes: copy templates, adapting internal links to the user's folder names
- If no: skip

### 5c. CLAUDE.local.md.template

If `CLAUDE.local.md.template` doesn't exist:
- Copy it from the standard template
- Adapt any folder references

### 5d. Claude Config Directories

Ensure these directories exist (create silently):
- `.claude/skills/` (for future skill additions)
- `.claude/rules/`
- `.claude/hooks/`
- `.claude/agents/`

Copy standard rules files if `.claude/rules/` is empty:
- `markdown-standards.md`
- `productivity-workflow.md`
- `project-management.md`
- `task-tracking.md`

## Phase 6: Verify & Next Steps

### 6a. Validation

Run quick checks:
- `vault-config.json` is valid JSON (read it back)
- All mapped folders exist
- `CLAUDE.md` is present and non-empty
- `.claude/hooks/adopt-env.sh` is present and executable

### 6b. Summary

Present a summary:
```
Adoption complete!

Vault: /path/to/vault
Method: PARA-like (preserved your existing structure)
Mapped folders:
  Daily Notes → Daily/
  Goals       → Goals/
  Projects    → Projects/
  Templates   → Templates/
  Archives    → Archive/
  Inbox       → Inbox/

Created:
  ✓ CLAUDE.md (vault context)
  ✓ vault-config.json (preferences)
  ✓ .claude/hooks/adopt-env.sh (folder mapping)
  ✓ Goal cascade files (4 files)
  ✓ Standard templates (3 files)

Your vault structure is unchanged — only configuration files were added.
```

### 6c. Next Steps

Suggest what to do next:
- "Try `/daily` to create today's note using your vault's structure"
- "Try `/review` for a guided weekly review"
- "Run `/push` to commit these changes to git"
- "Edit `CLAUDE.local.md` for private preferences (not committed to git)"

## Error Handling

- **Not in a vault**: If no `.obsidian` directory found, warn: "This doesn't look like an Obsidian vault. Continue anyway?"
- **Already adopted**: If `vault-config.json` exists with `adoptedVault: true`, ask: "This vault was already adopted. Re-run adoption? (This will regenerate config files.)"
- **Permission errors**: If `.claude/` can't be written, suggest checking permissions
- **Empty vault**: If no `.md` files found, suggest using `/onboard` with the template instead

## Integration

Works with:
- `/onboard` — adopt replaces onboard for existing vaults
- `/daily` — uses mapped daily notes folder
- `/weekly` — uses mapped goals folder
- `/review` — respects adopted vault structure
- `/push` — commits adoption changes
- All hooks — read env vars from `adopt-env.sh`