obsidian-claude-pkm/CONTRIBUTING.md

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 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. 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:

   ---
   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.