chill/obsidian-claude-pkm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v3.1: Onboarding, upgrade system, and positioning overhaul

Browse Source 
Reposition as "AI Accountability System" — not just another PKM starter kit.
README restructured to lead with the cascade as the hero feature.

New skills:
- /review — smart router that auto-detects daily/weekly/monthly context
- /upgrade — built-in update system with backup, diff review, safe merge
- /onboard enhanced — interactive first-run setup (name, review day, goal
  areas, work style) writes vault-config.json and personalizes CLAUDE.md

New infrastructure:
- FIRST_RUN marker + session-init welcome for new vaults
- Skill discovery hook (UserPromptSubmit) — lists available skills when
  user mentions "skill", "help", "command"
- CONTRIBUTING.md with architecture overview and good first issues

README:
- Cascade diagram and flow description as opening hero
- "Not another PKM starter kit" positioning
- Skills table with all 10 skills
- Zero dependencies highlighted as a feature
- v2.1→v3.1 and v1.x→v3.1 upgrade instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Bill Allred
2026-02-15 20:07:22 +01:00
parent bb7a9960ce
commit b2151c075a
10 changed files with 692 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,116 @@
# Contributing to Obsidian + Claude Code PKM
Thanks for your interest in contributing! This project aims to be the best AI-powered accountability system for Obsidian, and community contributions make it better for everyone.
## Ways to Contribute
### Report Bugs
- Open an [issue](https://github.com/ballred/obsidian-claude-pkm/issues/new) with steps to reproduce
- Include your OS, Claude Code version, and relevant vault structure
### Suggest Features
- Open an issue with the `enhancement` label
- Describe the problem you're solving, not just the solution
- Bonus: explain how it connects to the goal cascade
### Submit Code
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/my-improvement`)
3. Make your changes in `vault-template/`
4. Test by copying to a fresh vault and running the affected skills
5. Commit with a clear message
6. Open a PR against `main`
### Improve Documentation
- Fix typos, clarify instructions, add examples
- Documentation PRs are always welcome and easy to review
## Good First Issues
Look for issues labeled [`good first issue`](https://github.com/ballred/obsidian-claude-pkm/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). These are scoped tasks that don't require deep knowledge of the full system.
Good candidates for first contributions:
- **New goal templates** — Add alternative goal structures (OKRs, SMART goals, theme-based)
- **New output styles** — Create personas beyond Productivity Coach (Socratic tutor, stoic mentor, etc.)
- **Template variations** — Alternative daily/weekly note formats
- **Documentation** — Improve setup guides, add workflow examples, fix unclear instructions
- **Rule files** — Add new path-specific conventions (e.g., health tracking, learning logs)
## Architecture Overview
Understanding the system helps you contribute effectively:
```
vault-template/
├── .claude/
│ ├── skills/ # Slash commands — each has a SKILL.md
│ │ # user-invocable: true → shows in /skill-name
│ │ # user-invocable: false → auto-triggered
│ ├── agents/ # Multi-turn personas with memory
│ ├── hooks/ # Bash scripts triggered by events
│ ├── rules/ # Always-loaded context conventions
│ ├── output-styles/ # Tone/persona configurations
│ └── settings.json # Permissions, env vars, hook config
├── Goals/ # The cascade files
├── Templates/ # Note templates
└── CLAUDE.md # Root context file
```
### Key Design Principles
1. **Zero dependencies** — No npm, no Python, no external tools. Everything is bash + markdown. This is intentional — keep it that way.
2. **The cascade is the moat** — Every feature should strengthen the connection between goals → projects → daily tasks. If a feature doesn't connect to the cascade, it probably doesn't belong.
3. **Skills, not scripts** — Skills are markdown files that instruct Claude, not executable code. They describe *what to do*, and Claude figures out *how*.
4. **Agents have opinions** — Agents aren't generic assistants. The goal-aligner should challenge you. The weekly-reviewer should ask uncomfortable questions. The productivity coach should hold you accountable.
5. **User content is sacred** — Never modify Daily Notes, Goals, Projects, or Archives without explicit user confirmation. System files in `.claude/` are fair game for upgrades.
## Adding a New Skill
1. Create `vault-template/.claude/skills/your-skill/SKILL.md`
2. Add YAML frontmatter:
```yaml
---
name: your-skill
description: One-line description of what it does.
allowed-tools: Read, Write, Edit, Glob, Grep
model: sonnet
user-invocable: true
---
```
3. Write the skill prompt — describe the workflow, output format, and integration points
4. Add it to `vault-template/CLAUDE.md` skills table
5. Update `README.md` skills table
6. Test in a fresh vault
## Adding a New Agent
1. Create `vault-template/.claude/agents/your-agent.md`
2. Add frontmatter with `memory: project` for cross-session learning
3. Define the agent's personality, responsibilities, and output format
4. Add to `vault-template/CLAUDE.md` agents table
5. Test multi-turn interactions
## Code Style
- **Markdown** — Follow `vault-template/.claude/rules/markdown-standards.md`
- **Bash scripts** — POSIX-compatible where possible, handle both macOS and Linux
- **Commit messages** — Imperative mood, concise summary, body for context
- **File naming** — Skills: `SKILL.md`. Agents: `kebab-case.md`. Rules: `kebab-case.md`.
## Testing
There's no automated test suite (yet). To test your changes:
1. Copy `vault-template/` to a temporary location
2. Open it as an Obsidian vault
3. Start Claude Code in that directory
4. Run the affected skills/agents
5. Verify the output matches expectations
## Questions?
Open an issue or start a discussion. We're happy to help you find the right place to contribute.

346
README.md
View File

@@ -2,144 +2,9 @@
--- ---
# Obsidian + Claude Code PKM Starter Kit 🚀 # Obsidian + Claude Code: AI Accountability System
A complete personal knowledge management system that combines Obsidian's powerful note-taking with Claude Code's AI assistance. Go from zero to a fully functional PKM in 15 minutes or less. **Not another PKM starter kit.** This is an execution system that connects your 3-year vision to what you do today — and holds you accountable with AI.
**v3.0** - The Cascade: end-to-end goals-to-tasks flow with `/project` and `/monthly` skills, agent memory, and agent teams.
## ✨ Features
### Core PKM
- **🎯 Goal-Aligned System** - Cascading goals from 3-year vision to daily tasks
- **📅 Daily Notes System** - Structured daily planning and reflection
- **📱 Mobile Ready** - GitHub integration for notes on any device
- **🔄 Version Controlled** - Never lose a thought with automatic Git backups
- **🎨 Fully Customizable** - Adapt templates and structure to your needs
### AI-Powered (v3.0)
- **🔗 The Cascade** - End-to-end flow: 3-year vision → yearly goals → projects → monthly → weekly → daily tasks
- **📁 Project Management** - `/project` skill to create, track, and archive projects linked to goals
- **📆 Monthly Reviews** - `/monthly` skill rolls up weekly reviews, checks quarterly milestones
- **🧠 Agent Memory** - Agents learn your vault patterns across sessions (goal-aligner remembers misalignment patterns, weekly-reviewer learns your reflection style)
- **👥 Agent Teams** - Parallel weekly reviews with collector, goal-analyzer, and project-scanner agents
- **⚡ Unified Skills** - Skills and slash commands merged (`/daily`, `/weekly`, `/monthly`, `/project`, `/push`, `/onboard`)
- **🪝 Hooks** - Auto-commit on save, session initialization with priority surfacing
- **🤖 Custom Agents** - Note organizer, weekly reviewer, goal aligner, inbox processor
- **📏 Modular Rules** - Path-specific conventions for markdown, productivity, projects
- **🎭 Output Styles** - Productivity Coach for accountability
- **📊 Status Line** - Vault stats in terminal (note count, inbox, uncommitted changes)
- **👁️ Progress Visibility** - See spinner updates during multi-step operations like morning routines
## 🚀 Quick Start
### Prerequisites
- [Obsidian](https://obsidian.md/) installed
- [Claude Code CLI](https://code.claude.com/docs) installed
- Git installed
- GitHub account (optional, for mobile sync)
### 15-Minute Quickstart
```bash
# 1) Install prerequisites (once)
# - Obsidian: https://obsidian.md/
# - Git: https://git-scm.com/
# - Claude Code CLI: https://code.claude.com/docs
# 2) Clone this repository
git clone https://github.com/ballred/obsidian-claude-pkm.git
cd obsidian-claude-pkm
# 3) Run setup (macOS/Linux)
chmod +x scripts/setup.sh
./scripts/setup.sh
# 3b) Windows
scripts\setup.bat
```
### Manual Copy (alternative)
```bash
# Copy the vault template to your preferred location
cp -r vault-template ~/Documents/ObsidianPKM
```
### Open in Obsidian
1. Launch Obsidian
2. Click "Open folder as vault"
3. Select your vault folder (e.g., ~/Documents/ObsidianPKM)
4. Start with today's daily note!
## 📖 Documentation
- **[Setup Guide](docs/SETUP_GUIDE.md)** - Detailed installation instructions
- **[Customization](docs/CUSTOMIZATION.md)** - Make it yours
- **[Workflow Examples](docs/WORKFLOW_EXAMPLES.md)** - Daily routines and best practices
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
## 🗂️ Structure
```
Your Vault/
├── CLAUDE.md # AI context and navigation
├── CLAUDE.local.md.template # Template for personal overrides
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── .claude/
│ ├── agents/ # Custom AI agents
│ │ ├── note-organizer.md
│ │ ├── weekly-reviewer.md
│ │ ├── goal-aligner.md
│ │ └── inbox-processor.md
│ ├── skills/ # Unified skills (invoke with /skill-name)
│ │ ├── daily/ # /daily - Create daily notes, routines
│ │ ├── weekly/ # /weekly - Weekly review process
│ │ ├── monthly/ # /monthly - Monthly review and planning (NEW)
│ │ ├── project/ # /project - Create and track projects (NEW)
│ │ ├── push/ # /push - Git commit and push
│ │ ├── onboard/ # /onboard - Load vault context
│ │ ├── goal-tracking/ # Auto: Track goal progress
│ │ └── obsidian-vault-ops/ # Auto: Vault file operations
│ ├── hooks/ # Event automation (NEW)
│ │ ├── session-init.sh
│ │ └── auto-commit.sh
│ ├── rules/ # Path-specific conventions (NEW)
│ │ ├── markdown-standards.md
│ │ ├── productivity-workflow.md
│ │ └── project-management.md
│ ├── scripts/
│ │ └── statusline.sh # Terminal status display (NEW)
│ ├── output-styles/
│ │ └── coach.md # Productivity Coach
│ └── settings.json # Permissions and config (NEW)
├── Daily Notes/
├── Goals/
├── Projects/
├── Templates/
└── Archives/
```
## 🧠 Output Styles
This starter kit includes a **Productivity Coach** output style that transforms Claude into an accountability partner. The coach will:
- Challenge you to clarify your true intentions
- Point out misalignments between stated goals and actions
- Ask powerful questions to drive momentum
- Hold you accountable to your commitments
- Help you identify and overcome resistance
To use the coach style in Claude Code:
1. The output style is automatically included in `.claude/output-styles/`
2. Start Claude Code and type `/output-style` to select from available styles
3. Or directly activate with: `/output-style coach`
4. The style preference is automatically saved for your project
Learn more about [customizing output styles](docs/CUSTOMIZATION.md#output-styles).
## 🔗 The Cascade
The complete goals-to-tasks flow — the #1 requested feature:
``` ```
3-Year Vision ──→ Yearly Goals ──→ Projects ──→ Monthly Goals ──→ Weekly Review ──→ Daily Tasks 3-Year Vision ──→ Yearly Goals ──→ Projects ──→ Monthly Goals ──→ Weekly Review ──→ Daily Tasks
@@ -148,89 +13,186 @@ The complete goals-to-tasks flow — the #1 requested feature:
(the bridge layer) (the bridge layer)
``` ```
Every layer connects: Every layer connects. `/daily` surfaces your ONE Big Thing from the weekly review. `/weekly` shows project progress. `/monthly` checks quarterly milestones. `/goal-tracking` knows which goals have no active project. Nothing falls through the cracks.
- **`/project new`** creates a project linked to a yearly goal
- **`/daily`** morning routine surfaces your ONE Big Thing + project next-actions
- **`/weekly`** review includes a project progress table
- **`/monthly`** review rolls up weekly reviews and checks quarterly milestones
- **`/goal-tracking`** includes project completion % in goal progress calculations
## 🤖 Custom Agents (v3.0) **v3.1** · Zero dependencies · MIT License
Ask Claude to use specialized agents for common PKM tasks: ## The Cascade
The #1 reason people star this repo: **"I want goals → projects → daily notes → tasks to actually connect."**
| Layer | File | Skill | What It Does |
|-------|------|-------|-------------|
| Vision | `Goals/0. Three Year Goals.md` | `/goal-tracking` | Life areas, long-term direction |
| Annual | `Goals/1. Yearly Goals.md` | `/goal-tracking` | Measurable objectives, quarterly milestones |
| Projects | `Projects/*/CLAUDE.md` | `/project` | Active initiatives linked to goals |
| Monthly | `Goals/2. Monthly Goals.md` | `/monthly` | Roll up weekly reviews, check quarterly progress |
| Weekly | `Goals/3. Weekly Review.md` | `/weekly` | Reflect, realign, plan next week |
| Daily | `Daily Notes/YYYY-MM-DD.md` | `/daily` | Morning planning, evening reflection |
### How It Flows
**Morning** — `/daily` creates today's note, shows your week's ONE Big Thing and active project next-actions. You pick your focus.
**Evening** — `/daily` summarizes which goals and projects got attention today. Unlinked tasks get flagged.
**Sunday** — `/weekly` reads all your daily notes, scans project status, calculates goal progress, and helps you plan next week. Optional agent team mode parallelizes the collection.
**End of month** — `/monthly` rolls up the weekly reviews, checks quarterly milestones against yearly goals, and sets next month's priorities.
**Ad hoc** — `/project new` creates a project linked to a goal. `/project status` shows a dashboard. `/review` auto-detects the right review type based on context.
## Quick Start
### Prerequisites
- [Obsidian](https://obsidian.md/) installed
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
- Git installed
### Setup
```bash ```bash
# Organize your vault and fix broken links # Clone and set up
claude "Use the note-organizer agent to audit my vault" git clone https://github.com/ballred/obsidian-claude-pkm.git
cd obsidian-claude-pkm
chmod +x scripts/setup.sh && ./scripts/setup.sh
# Facilitate weekly review aligned with goals # Open vault in Obsidian, then start Claude Code:
claude "Use the weekly-reviewer agent for my weekly review" cd ~/your-vault-location
claude
```
# Check if daily work aligns with long-term goals On first run, you'll see a welcome message with the cascade visualization. Run `/onboard` to personalize your vault — it asks your name, preferred review day, and goal areas, then configures everything.
claude "Use the goal-aligner agent to analyze my recent activity"
# Process inbox items using GTD principles ### Windows
```bash
git clone https://github.com/ballred/obsidian-claude-pkm.git
cd obsidian-claude-pkm
scripts\setup.bat
```
## Skills (Slash Commands)
| Skill | Command | Purpose |
|-------|---------|---------|
| Daily | `/daily` | Morning planning, midday check-in, evening reflection |
| Weekly | `/weekly` | 30-min weekly review with project rollup |
| Monthly | `/monthly` | Monthly review, quarterly milestone check |
| Project | `/project` | Create, track, archive projects linked to goals |
| Review | `/review` | Smart router — detects morning/Sunday/end-of-month context |
| Push | `/push` | Commit and push vault changes to Git |
| Onboard | `/onboard` | Interactive setup + load vault context |
| Upgrade | `/upgrade` | Update to latest version, preserving your content |
| Goal Tracking | *(auto)* | Track progress across the full cascade |
| Vault Ops | *(auto)* | Read/write files, manage wiki-links |
## AI Agents
Four specialized agents with cross-session memory:
| Agent | What It Does |
|-------|-------------|
| `goal-aligner` | Audits daily activity against stated goals. Flags misalignment. |
| `weekly-reviewer` | Facilitates the 3-phase weekly review. Learns your reflection style. |
| `note-organizer` | Fixes broken links, consolidates duplicates, maintains vault hygiene. |
| `inbox-processor` | GTD-style inbox processing — categorize, clarify, organize. |
```bash
claude "Use the goal-aligner agent to analyze my last 2 weeks"
claude "Use the inbox-processor agent to clear my inbox" claude "Use the inbox-processor agent to clear my inbox"
``` ```
## 🔄 Upgrading Agents use `memory: project` to learn your patterns across sessions — the goal-aligner remembers recurring misalignment patterns, the weekly-reviewer learns what reflection questions resonate.
### From v2.1 to v3.0 ## Productivity Coach
An output style that transforms Claude into an accountability partner:
```bash ```bash
# 1. Copy new skill directories /output-style coach
```
The coach challenges assumptions, points out goal-action misalignment, asks powerful questions, and holds you to your commitments. Pairs naturally with `/daily` and `/weekly`.
## Automation
**Zero dependencies.** Everything runs on bash and markdown.
- **Auto-commit** — Every file write/edit triggers a Git commit via PostToolUse hook
- **Session init** — Surfaces your ONE Big Thing, active project count, and days since last review
- **First-run welcome** — New vaults get a guided onboarding experience
- **Skill discovery** — Mention "skill" or "help" and available commands are listed automatically
- **Path-specific rules** — Markdown standards, productivity workflow, and project management conventions loaded contextually
## Structure
```
Your Vault/
├── CLAUDE.md # AI context and navigation
├── .claude/
│ ├── agents/ # 4 specialized AI agents (with memory)
│ ├── skills/ # 10 skills (8 listed above + 2 auto)
│ ├── hooks/ # Auto-commit, session init, skill discovery
│ ├── rules/ # Path-specific conventions
│ ├── output-styles/ # Productivity Coach
│ └── settings.json # Permissions, env vars, hooks config
├── Daily Notes/ # YYYY-MM-DD.md
├── Goals/ # The cascade (3-year → weekly)
├── Projects/ # Active projects with CLAUDE.md each
├── Templates/ # Reusable note structures
├── Archives/ # Completed/inactive content
└── Inbox/ # Quick captures (optional)
```
## Upgrading
### Built-in upgrade (v3.1+)
```bash
/upgrade check # Preview what's changed
/upgrade # Interactive upgrade with backup
```
The upgrade skill creates a timestamped backup, shows diffs for each changed file, and never touches your content folders (Daily Notes, Goals, Projects, etc.).
### Manual upgrade from v2.1
```bash
# Copy new skill directories
cp -r vault-template/.claude/skills/project your-vault/.claude/skills/ cp -r vault-template/.claude/skills/project your-vault/.claude/skills/
cp -r vault-template/.claude/skills/monthly your-vault/.claude/skills/ cp -r vault-template/.claude/skills/monthly your-vault/.claude/skills/
cp -r vault-template/.claude/skills/review your-vault/.claude/skills/
cp -r vault-template/.claude/skills/upgrade your-vault/.claude/skills/
# 2. Update existing files (review diff first) # Update agents, hooks, settings
cp vault-template/.claude/settings.json your-vault/.claude/
cp vault-template/.claude/hooks/session-init.sh your-vault/.claude/hooks/
# 3. Update agents (adds memory: project)
cp vault-template/.claude/agents/*.md your-vault/.claude/agents/ cp vault-template/.claude/agents/*.md your-vault/.claude/agents/
cp vault-template/.claude/hooks/* your-vault/.claude/hooks/
# 4. Update existing skills (adds cascade features) cp vault-template/.claude/settings.json your-vault/.claude/
cp -r vault-template/.claude/skills/daily your-vault/.claude/skills/
cp -r vault-template/.claude/skills/weekly your-vault/.claude/skills/
cp -r vault-template/.claude/skills/goal-tracking your-vault/.claude/skills/
cp -r vault-template/.claude/skills/onboard your-vault/.claude/skills/
# 5. Review and merge CLAUDE.md changes
# Add /project and /monthly to your skills table, bump version
# 6. Make scripts executable
chmod +x your-vault/.claude/hooks/*.sh chmod +x your-vault/.claude/hooks/*.sh
``` ```
### From v1.x to v3.0 ### From v1.x
```bash ```bash
# 1. Copy all new directories to your vault
cp -r vault-template/.claude-plugin your-vault/ cp -r vault-template/.claude-plugin your-vault/
cp -r vault-template/.claude/agents your-vault/.claude/ cp -r vault-template/.claude your-vault/
cp -r vault-template/.claude/skills your-vault/.claude/ cp vault-template/CLAUDE.md your-vault/
cp -r vault-template/.claude/hooks your-vault/.claude/
cp -r vault-template/.claude/rules your-vault/.claude/
cp -r vault-template/.claude/scripts your-vault/.claude/
cp vault-template/.claude/settings.json your-vault/.claude/
cp vault-template/CLAUDE.local.md.template your-vault/
# 2. Review and merge CLAUDE.md changes
# Your customizations are preserved, just add references to new features
# 3. Make hook scripts executable
chmod +x your-vault/.claude/hooks/*.sh chmod +x your-vault/.claude/hooks/*.sh
chmod +x your-vault/.claude/scripts/*.sh
``` ```
## 🤝 Contributing ## Documentation
Found a bug or have a feature idea? Please open an issue or submit a PR! - **[Setup Guide](docs/SETUP_GUIDE.md)** — Detailed installation instructions
- **[Customization](docs/CUSTOMIZATION.md)** — Make it yours
- **[Workflow Examples](docs/WORKFLOW_EXAMPLES.md)** — Daily routines and best practices
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** — Common issues and solutions
- **[Contributing](CONTRIBUTING.md)** — How to help
## 📄 License ## Contributing
MIT - Use this freely for your personal knowledge management journey. We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Good first issues are labeled — check the [issues page](https://github.com/ballred/obsidian-claude-pkm/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
--- ## License
**Ready to transform your note-taking?** Follow the [Setup Guide](docs/SETUP_GUIDE.md) to get started! MIT — Use this freely for your personal knowledge management journey.

19
vault-template/.claude/hooks/session-init.sh
View File

@@ -13,6 +13,25 @@ export CURRENT_WEEK=$(date +%Y-W%V)
# Daily note path # Daily note path
export DAILY_NOTE="$VAULT_PATH/Daily Notes/$TODAY.md" export DAILY_NOTE="$VAULT_PATH/Daily Notes/$TODAY.md"
# First-run detection
if [ -f "$VAULT_PATH/FIRST_RUN" ]; then
echo ""
echo "Welcome to the Obsidian + Claude Code AI Accountability System!"
echo ""
echo " The Cascade — your goals-to-tasks execution system:"
echo ""
echo " 3-Year Vision -> Yearly Goals -> Projects -> Monthly -> Weekly -> Daily"
echo " | | | | | |"
echo " /goal-tracking /goal-tracking /project /monthly /weekly /daily"
echo ""
echo " Run /onboard to personalize your vault (takes ~2 minutes)."
echo " This will ask your name, preferred review day, and goal areas."
echo ""
echo " After that, try /daily to start your first morning routine."
echo ""
exit 0
fi
# Verify vault structure # Verify vault structure
if [ ! -f "$VAULT_PATH/CLAUDE.md" ]; then if [ ! -f "$VAULT_PATH/CLAUDE.md" ]; then
echo "Note: Not in a vault root directory (no CLAUDE.md found)" echo "Note: Not in a vault root directory (no CLAUDE.md found)"

35
vault-template/.claude/hooks/skill-discovery.sh Executable file
View File

@@ -0,0 +1,35 @@
#!/bin/bash
# Skill discovery hook — triggered on UserPromptSubmit
# Lists available skills when user mentions "skill", "help", "command", or "what can"
# Non-blocking: always exits 0
# Read user prompt from stdin
PROMPT=$(cat)
# Case-insensitive check for trigger words
if echo "$PROMPT" | grep -iqE '\b(skills?|commands?|what can|help me|available|slash)\b'; then
echo ""
echo "Available skills (invoke with /skill-name):"
echo ""
SKILLS_DIR="$(pwd)/.claude/skills"
if [ -d "$SKILLS_DIR" ]; then
for skill_dir in "$SKILLS_DIR"/*/; do
if [ -f "$skill_dir/SKILL.md" ]; then
skill_name=$(basename "$skill_dir")
# Extract description from YAML frontmatter
desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; q; } }' "$skill_dir/SKILL.md")
# Check if user-invocable
invocable=$(sed -n '/^---$/,/^---$/{ /^user-invocable:/{ s/^user-invocable: *//; p; q; } }' "$skill_dir/SKILL.md")
if [ "$invocable" = "true" ]; then
printf " /%s — %s\n" "$skill_name" "$desc"
else
printf " %s (auto) — %s\n" "$skill_name" "$desc"
fi
fi
done
fi
echo ""
fi
exit 0

11
vault-template/.claude/settings.json
View File

@@ -47,6 +47,17 @@
] ]
} }
], ],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": ".claude/hooks/skill-discovery.sh",
"timeout": 5000
}
]
}
],
"PostToolUse": [ "PostToolUse": [
{ {
"matcher": "Write|Edit", "matcher": "Write|Edit",

95
vault-template/.claude/skills/onboard/SKILL.md
View File

@@ -1,30 +1,96 @@
--- ---
name: onboard name: onboard
description: Load CLAUDE.md context files from vault for comprehensive understanding. Discovers hierarchical context, recent notes, and project states. Use at start of session or when Claude needs full vault context. description: Interactive vault setup and context loading. On first run, personalizes your vault. On subsequent runs, loads full context. Use at start of session or when Claude needs full vault context.
allowed-tools: Read, Glob, Grep allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
model: sonnet model: sonnet
user-invocable: true user-invocable: true
--- ---
# Onboard Skill # Onboard Skill
Loads all CLAUDE.md files from your vault to provide comprehensive context for intelligent assistance. Interactive vault setup (first run) and context loading (subsequent runs).
## Usage ## Usage
Invoke with `/onboard` or ask Claude to learn about your vault.
### Full Context Load
``` ```
/onboard /onboard # Full onboard (setup if first run, context load if not)
/onboard Projects/MyProject # Load specific project context
``` ```
### Specific Project Context ## First-Run Setup
```
/onboard Projects/MyProject If the file `FIRST_RUN` exists in the vault root, this is a new vault. Run the interactive setup:
### Step 1: Welcome
Greet the user and explain what will happen:
- "I'll ask a few questions to personalize your vault (~2 minutes)"
- "Your answers are saved locally in vault-config.json"
- "You can change these anytime by editing that file or running /onboard again"
### Step 2: Ask Questions
Use AskUserQuestion to ask these interactively:
**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
### Step 3: Save Configuration
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-15",
"version": "3.1"
}
``` ```
## What This Skill Does ### Step 4: Personalize CLAUDE.md
Edit the root `CLAUDE.md`:
- Replace `[CUSTOMIZE: Add your personal mission statement here]` with a prompt based on their goal areas
- Update the "Current Focus" section to reference their chosen areas
### Step 5: Remove First-Run Marker
```bash
rm FIRST_RUN
```
### Step 6: Confirm Setup
Tell the user:
- "Your vault is set up! Here's what's available:"
- Brief cascade overview
- "Try `/daily` to start your first morning routine"
- "Try `/review` anytime — it auto-detects the right review type"
Then proceed to the standard context loading below.
## Standard Context Loading (Subsequent Runs)
### What This Skill Does
1. **Discovers Context Files** 1. **Discovers Context Files**
- Searches for all CLAUDE.md files - Searches for all CLAUDE.md files
@@ -41,7 +107,12 @@ Invoke with `/onboard` or ask Claude to learn about your vault.
- Extracts project name, phase, progress, and goal linkage - Extracts project name, phase, progress, and goal linkage
- Displays active project count and summary in onboard output - Displays active project count and summary in onboard output
4. **Builds Understanding** 4. **Reads User Preferences**
- Loads `vault-config.json` if present
- Applies name, review day, work style preferences
- Uses goal areas to prioritize context loading
5. **Builds Understanding**
- Your personal mission/goals - Your personal mission/goals
- Project structures and status - Project structures and status
- Workflow preferences - Workflow preferences

123
vault-template/.claude/skills/review/SKILL.md Normal file
View File

@@ -0,0 +1,123 @@
---
name: review
description: Smart review router. Detects context (morning, Sunday, end of month) and launches the appropriate review workflow. Use anytime for the right review at the right time.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList, TaskGet
model: sonnet
user-invocable: true
---
# Review Skill
Smart router that detects context and launches the appropriate review workflow.
## Usage
```
/review # Auto-detect the right review based on time/context
/review daily # Force daily review
/review weekly # Force weekly review
/review monthly # Force monthly review
```
Or simply: "Help me review" — and the right workflow starts.
## Auto-Detection Logic
When invoked without arguments, detect context using these rules:
### 1. Check the Time of Day
```bash
HOUR=$(date +%H)
```
- **Before noon (< 12):** Morning routine — delegate to `/daily` morning workflow
- **After 5 PM (>= 17):** Evening shutdown — delegate to `/daily` evening workflow
- **Midday (12-17):** Midday check-in — delegate to `/daily` midday workflow
### 2. Check the Day of Week
```bash
DAY_OF_WEEK=$(date +%u) # 1=Monday, 7=Sunday
```
- **Sunday (7) or Monday (1):** Weekly review — delegate to `/weekly`
- Override time-of-day detection
- Ask: "Ready for your weekly review?" before proceeding
### 3. Check the Day of Month
```bash
DAY_OF_MONTH=$(date +%d)
DAYS_IN_MONTH=$(date -v+1m -v1d -v-1d +%d 2>/dev/null || date -d "$(date +%Y-%m-01) +1 month -1 day" +%d)
```
- **Last 3 days of month (DAY_OF_MONTH >= DAYS_IN_MONTH - 2):** Monthly review — delegate to `/monthly`
- Override both time-of-day and day-of-week detection
- Ask: "End of month — ready for your monthly review?" before proceeding
- **First day of month (DAY_OF_MONTH == 1):** Also suggest monthly review
- "It's the first of the month. Want to do your monthly review for last month?"
### 4. Check Staleness
Before routing, check for overdue reviews:
```bash
# Read weekly review file for last date
WEEKLY_REVIEW="Goals/3. Weekly Review.md"
# If last weekly review > 7 days ago, suggest weekly regardless of day
```
- **Weekly review overdue (>7 days):** Suggest weekly review
- "Your last weekly review was N days ago. Want to catch up?"
- If user says no, fall through to time-of-day detection
## Routing Behavior
After detecting context:
1. Tell the user what was detected: "It's Sunday evening — launching your weekly review."
2. Delegate to the appropriate skill's workflow
3. The delegated skill handles everything from there
### Delegation
This skill does NOT duplicate the logic of `/daily`, `/weekly`, or `/monthly`. It:
1. Detects context
2. Informs the user
3. Follows the instructions from the target skill's SKILL.md
### Explicit Override
If the user specifies a type (`/review weekly`), skip auto-detection entirely and go directly to that review type.
## Output on Detection
```markdown
### Review Router
**Time:** 7:15 AM (Morning)
**Day:** Sunday
**Month day:** 15th
**Detected:** Weekly review (Sunday override)
**Last weekly review:** 3 days ago (not overdue)
Launching weekly review...
```
## Edge Cases
- **Multiple triggers** (e.g., last Sunday of month): Monthly takes priority over weekly
- **No daily note exists**: Create one first, then continue with review
- **User says "no" to suggestion**: Fall through to next detection level
- **Explicit argument overrides everything**: `/review monthly` runs monthly review even on a Tuesday morning
## Integration
Works with:
- `/daily` — Morning, midday, and evening routines
- `/weekly` — Full weekly review process
- `/monthly` — Monthly review and planning
- Session init hook — Staleness data already calculated

145
vault-template/.claude/skills/upgrade/SKILL.md Normal file
View File

@@ -0,0 +1,145 @@
---
name: upgrade
description: Update vault to the latest version of obsidian-claude-pkm. Creates backup, shows diffs, preserves your content. Use when a new version is available.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
user-invocable: true
---
# Upgrade Skill
Updates your vault's system files to the latest version while preserving all your personal content.
## Usage
```
/upgrade # Interactive upgrade with backup and diff review
/upgrade check # Preview what's changed without making modifications
```
## What Gets Updated (System Files)
- `.claude/skills/*/SKILL.md` — Skill definitions
- `.claude/agents/*.md` — Agent configurations
- `.claude/hooks/*.sh` — Automation scripts
- `.claude/rules/*.md` — Convention rules
- `.claude/output-styles/*.md` — Output style definitions
- `.claude/settings.json` — Permissions and hook config
- `CLAUDE.md` — Root context file (merged carefully)
- `Templates/*.md` — Note templates
## What Never Gets Touched (Your Content)
- `Daily Notes/**` — Your daily journal entries
- `Goals/**` — Your goal files and reviews
- `Projects/**` — Your project folders and CLAUDE.md files
- `Archives/**` — Your archived content
- `Inbox/**` — Your captured items
- `CLAUDE.local.md` — Your personal overrides
- `vault-config.json` — Your preferences
## Upgrade Process
### Step 1: Check for Updates
Read the current version from `CLAUDE.md` (look for "System Version:" line).
Compare with the upstream repo. If using git:
```bash
git fetch origin
git log HEAD..origin/main --oneline
```
If not a git repo or no remote, inform user they need to download the latest `vault-template/` manually.
### Step 2: Create Backup
Before any changes, create a timestamped backup:
```bash
BACKUP_DIR=".backup/upgrade-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r .claude "$BACKUP_DIR/"
cp CLAUDE.md "$BACKUP_DIR/"
cp -r Templates "$BACKUP_DIR/" 2>/dev/null
```
Tell the user: "Backup created at $BACKUP_DIR"
### Step 3: Diff Review
For each system file that differs from upstream:
1. Show a summary of what changed (additions, removals, modifications)
2. Ask user to confirm: "Apply this update? (yes/skip/stop)"
3. If yes: apply the change
4. If skip: leave this file unchanged
5. If stop: halt the upgrade (backup remains, partial changes preserved)
### Step 4: Apply Changes
For each confirmed file:
- Copy the new version from upstream
- For `CLAUDE.md`: merge carefully — preserve user customizations (Personal Mission, Current Focus sections) while updating system sections (Skills table, version number)
- For `settings.json`: merge — add new permissions/hooks, preserve existing customizations
### Step 5: Post-Upgrade
1. Make hook scripts executable: `chmod +x .claude/hooks/*.sh`
2. Show summary of changes applied
3. Update version in CLAUDE.md
4. Suggest running `/onboard` to reload context
## Check Mode (`/upgrade check`)
When invoked with "check":
1. Compare system files against upstream
2. List files that would be updated with brief change description
3. Show version numbers (current → available)
4. Do NOT make any changes
5. Suggest running `/upgrade` to apply
## Output Format
```markdown
## Upgrade Check
**Current version:** 3.0 (The Cascade)
**Available version:** 3.1
### Files to Update
| File | Change Summary |
|------|---------------|
| `.claude/skills/daily/SKILL.md` | Added cascade context surfacing |
| `.claude/agents/goal-aligner.md` | Added memory: project |
| `.claude/hooks/session-init.sh` | Added priority surfacing |
### New Files
- `.claude/skills/review/SKILL.md` — Smart review router
- `.claude/hooks/skill-discovery.sh` — Auto-list skills
### No Changes Needed
- `.claude/rules/` — Already up to date
Run `/upgrade` to apply these updates (backup will be created first).
```
## Safety Features
- Complete backup before any modification
- File-by-file confirmation
- Can be stopped at any point
- User content folders are never touched
- `CLAUDE.local.md` personal overrides preserved
- Backup includes restoration instructions
## Error Handling
- If no git remote: guide user to download latest vault-template manually
- If backup fails: abort entire upgrade
- If a file copy fails: report error, continue with next file
- Always leave vault in a usable state
## Integration
Works with:
- `/onboard` — Reload context after upgrade
- Session init hook — Will reflect updated priorities

6
vault-template/CLAUDE.md
View File

@@ -36,8 +36,10 @@ Skills are invoked with `/skill-name` or automatically by Claude when relevant.
| `weekly` | `/weekly` | Run weekly review, reflect and plan | | `weekly` | `/weekly` | Run weekly review, reflect and plan |
| `monthly` | `/monthly` | Monthly review, quarterly milestone check, next month planning | | `monthly` | `/monthly` | Monthly review, quarterly milestone check, next month planning |
| `project` | `/project` | Create, track, and archive projects linked to goals | | `project` | `/project` | Create, track, and archive projects linked to goals |
| `review` | `/review` | Smart router — auto-detects daily/weekly/monthly based on context |
| `push` | `/push` | Commit and push changes to Git | | `push` | `/push` | Commit and push changes to Git |
| `onboard` | `/onboard` | Load full vault context | | `onboard` | `/onboard` | Interactive setup (first run) + load vault context |
| `upgrade` | `/upgrade` | Update to latest version, preserving your content |
| `goal-tracking` | (auto) | Track progress across goal cascade with project awareness | | `goal-tracking` | (auto) | Track progress across goal cascade with project awareness |
| `obsidian-vault-ops` | (auto) | Read/write vault files, manage wiki-links | | `obsidian-vault-ops` | (auto) | Read/write vault files, manage wiki-links |
@@ -123,7 +125,7 @@ See `CLAUDE.local.md.template` for format.
*See @.claude/rules/ for detailed conventions* *See @.claude/rules/ for detailed conventions*
*Last Updated: 2026-02-15* *Last Updated: 2026-02-15*
*System Version: 3.0 (The Cascade)* *System Version: 3.1*
<claude-mem-context> <claude-mem-context>

2
vault-template/FIRST_RUN Normal file
View File

@@ -0,0 +1,2 @@
This file triggers the first-run welcome message.
It is automatically removed after you run /onboard.