b2151c075a
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>
117 lines
5.0 KiB
Markdown
117 lines
5.0 KiB
Markdown
# 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.
|