v3.1: Onboarding, upgrade system, and positioning overhaul
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
@@ -13,6 +13,25 @@ export CURRENT_WEEK=$(date +%Y-W%V)
|
||||
# Daily note path
|
||||
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
|
||||
if [ ! -f "$VAULT_PATH/CLAUDE.md" ]; then
|
||||
echo "Note: Not in a vault root directory (no CLAUDE.md found)"
|
||||
|
||||
35
vault-template/.claude/hooks/skill-discovery.sh
Executable file
35
vault-template/.claude/hooks/skill-discovery.sh
Executable 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
|
||||
@@ -47,6 +47,17 @@
|
||||
]
|
||||
}
|
||||
],
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": ".claude/hooks/skill-discovery.sh",
|
||||
"timeout": 5000
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
|
||||
@@ -1,30 +1,96 @@
|
||||
---
|
||||
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.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
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, Write, Edit, Glob, Grep, Bash, AskUserQuestion
|
||||
model: sonnet
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
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
|
||||
```
|
||||
/onboard Projects/MyProject
|
||||
## First-Run Setup
|
||||
|
||||
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**
|
||||
- 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
|
||||
- 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
|
||||
- Project structures and status
|
||||
- Workflow preferences
|
||||
|
||||
123
vault-template/.claude/skills/review/SKILL.md
Normal file
123
vault-template/.claude/skills/review/SKILL.md
Normal 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
145
vault-template/.claude/skills/upgrade/SKILL.md
Normal 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
|
||||
Reference in New Issue
Block a user