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

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.
**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:
**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.
```
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)
```
Every layer connects:
- **`/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
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.
## 🤖 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
# Organize your vault and fix broken links
claude "Use the note-organizer agent to audit my vault"
# Clone and set up
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
claude "Use the weekly-reviewer agent for my weekly review"
# Open vault in Obsidian, then start Claude Code:
cd ~/your-vault-location
claude
```
# Check if daily work aligns with long-term goals
claude "Use the goal-aligner agent to analyze my recent activity"
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.
# 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"
```
## 🔄 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
# 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/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)
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)
# Update agents, hooks, settings
cp vault-template/.claude/agents/*.md your-vault/.claude/agents/
# 4. Update existing skills (adds cascade features)
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
cp vault-template/.claude/hooks/* your-vault/.claude/hooks/
cp vault-template/.claude/settings.json your-vault/.claude/
chmod +x your-vault/.claude/hooks/*.sh
```
### From v1.x to v3.0
### From v1.x
```bash
# 1. Copy all new directories to your vault
cp -r vault-template/.claude-plugin your-vault/
cp -r vault-template/.claude/agents your-vault/.claude/
cp -r vault-template/.claude/skills your-vault/.claude/
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
cp -r vault-template/.claude your-vault/
cp vault-template/CLAUDE.md your-vault/
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.