Add /adopt skill for BYOV (Bring Your Own Vault) support

Adds a 6-phase skill that scaffolds the PKM system onto existing Obsidian vaults: scan structure, map folders, personalize, generate config, scaffold missing pieces, and verify. Replaces hardcoded folder paths in hooks with env var lookups (${VAR:-Default}) so adopted vaults with custom folder names work correctly while template-based vaults remain unaffected. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-17 17:54:13 -08:00
parent b2151c075a
commit 5f0444fe5f
6 changed files with 357 additions and 13 deletions
--- a/vault-template/.claude/skills/adopt/SKILL.md
+++ b/vault-template/.claude/skills/adopt/SKILL.md
@@ -0,0 +1,331 @@
+---
+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`