/init-project

name: init-project
description: Configure this project for Obsidian PKM — connects the repo to a vault project folder and writes CLAUDE.md integration directives
allowed-tools: [Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, mcp__plugin_vault-pkm_vault-pkm__vault_list, mcp__plugin_vault-pkm_vault-pkm__vault_write, mcp__plugin_vault-pkm_vault-pkm__vault_peek]

Initialize Project for Obsidian PKM

You are configuring this code repository for Obsidian PKM integration. Walk the user through these steps.

Step 1: Detect Vault Project Path

Determine which vault project folder corresponds to this repository.

1. Get the current working directory name (the repo folder name) 2. Use `vault_list` to check if a matching folder exists in `01-Projects/`:

   vault_list({ path: "01-Projects" })

3. Look for a case-insensitive basename match between the CWD and the `01-Projects/` entries

**If a match is found**, proceed to Step 2 with the detected path.

**If no match is found**, ask the user: > "I couldn't find a matching project folder in your vault. What's the vault project path? (e.g., `01-Projects/MyApp`)"

Step 2: Confirm with User

Present the detected (or provided) path and ask for confirmation: > "I found `01-Projects/<name>/` in your vault. Is this the right project for this repository?"

If the user corrects the path, use their provided path instead.

Step 3: Scaffold Vault Folder (if needed)

Use `vault_list` to check if the confirmed path exists in the vault.

**If the folder doesn't exist**, ask: > "The folder `01-Projects/<name>/` doesn't exist in your vault yet. Want me to create it with a project index?"

If yes: 1. Create the project index:

   vault_write({
     template: "project-index",
     path: "01-Projects/<name>/_index.md",
     frontmatter: { tags: ["project"], status: "active" }
   })

2. Subdirectories (`development/decisions/`, `development/debug/`, `research/`, `tasks/`, `planning/`) will be created automatically when notes are first written to them (`vault_write` has `createDirs: true` by default). Inform the user of this.

If no, proceed without scaffolding.

Step 4: Write CLAUDE.md

Read the existing CLAUDE.md in the current working directory (using the Read tool). If no CLAUDE.md exists, you will create one.

4a: Add/update `# PKM:` annotation

The annotation must be on its own line at the top of the file, before any other content:

# PKM: 01-Projects/<name>

• If the file already has a `# PKM:` line (regex: `/^#\s+PKM:\s*.+$/m`), replace it with the correct path
• If not, prepend it to the file with a blank line after it

4b: Add/update `## PKM Integration` section

The section content (substitute the actual project path):

## PKM Integration

- **Vault project**: `01-Projects/<name>/`
- **MCP Server**: `vault-pkm` plugin

Document decisions, research findings, and debugging sessions as you work. The `pkm-capture` agent captures devlog entries and PKM-worthy content in the background (triggered automatically after git commits), or use the `vault-pkm:pkm-write` skill for structured notes with linking.

Use `vault-pkm:pkm-explore` to research what the vault already knows about a topic before creating new content.

At the end of each session, run `vault-pkm:pkm-session-end` to update the devlog and capture undocumented work.

### Referring to vault files

Whenever you mention a vault note, PKM file, or file inside `01-Projects/<name>/` in your response to the user — whether quoting tool output, summarizing what you read, or referring to a file by name — format it as a markdown link to its `obsidian://` URI so the user can click to open it in Obsidian:

`[01-Projects/<name>/some/note.md](obsidian://open?vault=<vault-name>&file=01-Projects%2F<name>%2Fsome%2Fnote)`

Encoding rules: percent-encode `/` as `%2F` and spaces as `%20`. Strip the trailing `.md` from the URL `file=` parameter, but keep `.md` in the visible link text. The vault name is shown in any vault-pkm tool output (the part after `vault=`); reuse it.

The vault-pkm MCP tools already emit paths in this format. Preserve the link form when relaying; don't revert to bare paths like `01-Projects/<name>/some/note.md` for inline mentions. Apply the same format proactively when mentioning a vault file you haven't just queried (e.g., when answering "what's in the devlog?" or "see ADR-002").

**If `## PKM Integration` already exists**: replace everything from `## PKM Integration` up to (but not including) the next `## ` heading or end of file. This makes re-runs idempotent.

**If `## PKM Integration` does not exist**: append the section at the end of the file.

Step 5: Confirm

Tell the user:

> "Done! Your project is connected to the vault at `01-Projects/<name>/`." > > The vault-pkm plugin will now: > - Load project context automatically at session start > - Capture decisions, tasks, and research in the background > - Document session progress when you run `pkm-session-end` > > **Restart your Claude Code session** for the SessionStart hook to pick up the new CLAUDE.md configuration.