MultiPhysicsVault/CONTRIBUTING.md

Contributing to claude-obsidian

Thanks for your interest in improving this plugin. claude-obsidian is a small, focused project; contributions that match its philosophy land quickly.

Philosophy

Three constraints shape every change:

1. Read before write. Every contribution starts by reading the affected files, their tests, and their callers. Removals break assumptions as often as additions.
2. Smallest unit that works. No speculative abstraction. Complexity is earned, not anticipated. Three real callers minimum before an abstraction lands.
3. Failure is the spec. Every new failure mode needs explicit handling. Untrusted input, network calls, and state changes need an explicit blast-radius answer.

The full kernel lives in /best-practices (composable Claude Code skill). The pre-commit verifier agent at agents/verifier.md enforces it for non-trivial changes.

Workflow

1. Open an issue first (for non-trivial changes)

For typo fixes, doc clarifications, or single-line changes, skip straight to a PR. For anything bigger:

• Open an issue using the bug-report or feature-request template
• Describe the problem, the proposed change, and the blast radius
• Wait for a thumbs-up before investing time

2. Fork + branch

Contributions are accepted on the public canonical repo. Fork AgriciDaniel/claude-obsidian on GitHub, then:

git clone https://github.com/<your-username>/claude-obsidian.git
cd claude-obsidian
git checkout -b your-feature-name

ℹ️ The public repo (AgriciDaniel/claude-obsidian) is the canonical source of truth. Raise all PRs against it. AI Marketing Hub Pro members working from the early-access mirror (AI-Marketing-Hub/claude-obsidian) should target the public canonical too, so contributions land in one place.

Branch names: fix/..., feat/..., docs/..., refactor/....

3. Set up locally

The plugin runs anywhere Claude Code runs. For development:

# Run the hermetic test suite — required before submitting a PR
make test

# Optionally provision the v1.7 retrieval pipeline (requires consent for API egress)
bash bin/setup-retrieve.sh

# Optionally pick a methodology mode for testing the v1.8 routing
bash bin/setup-mode.sh

4. Make the change

Follow the six-cut kernel:

• Read every file you're touching
• Name new identifiers like the next reader is hostile
• Smallest unit that works
• Delete more than you add (when superseding)
• Evidence over intuition (tests for new behavior)
• Failure-mode + undo plan documented

If you add a new skill, agent, script, or hook, also add a test under tests/. The 9 hermetic test suites are the project's safety net.

5. Run the tests

make test

All 9 suites must pass (~1240 assertions). Tests are hermetic: no network, no ollama, no Anthropic API. If your change adds a network call, gate it behind a --consent/--allow-egress/env-var pattern matching scripts/contextual-prefix.py or scripts/tiling-check.py.

6. Run the verifier (optional but recommended)

For multi-file changes:

# After git add, before git commit, dispatch the verifier agent
# (Claude Code: invoke agents/verifier.md on the staged diff)

The verifier applies the six-cut + agent kernel to your staged diff and returns findings in BLOCKER / HIGH / MEDIUM / LOW tiers. Address BLOCKER + HIGH before committing.

7. Commit

Commit message convention (Conventional Commits):

<type>(<scope>): <short description>

<longer body if needed>

Types: feat, fix, docs, chore, refactor, test, perf, style.

Example:

fix(wiki-mode): close path-traversal in route_path safe_name

Sanitize routing input via safe_name() before string-concat into
the vault-relative path. Adds 9 hermetic test assertions for traversal
vectors. Closes audit finding S1.

8. Update CHANGELOG.md

Add an entry under ## [Unreleased] (create the section if needed). Follow the Keep a Changelog format:

## [Unreleased]

### Added
- Description of new feature

### Fixed
- Description of bug fix

The maintainer will move your entry to a versioned section at release time.

9. Open a PR

Use the PR template. Required fields:

• What changed
• Why
• How it was tested (paste make test output if relevant)
• Audit/verifier results if applicable

PRs are reviewed against the kernel. Expect feedback on naming, scope, and failure-mode coverage.

Testing standards

• Hermetic. No network, no external services, no user-specific environment.
• Fast. The full suite runs in under a minute.
• Deterministic. Same input → same output, every time.
• Documented. Every test asserts a named behavior, not a coincidence.

If you can't make your test hermetic, ask in the issue whether a mocked alternative is acceptable.

What we will NOT merge

• Code without tests for new behavior
• Speculative abstractions (no real callers yet)
• Network calls without an explicit consent gate
• Path construction from user input without sanitization (see scripts/wiki-mode.py:safe_name)
• Skills/agents that shell out without documenting the failure mode
• Anything that breaks the existing test suite without a documented reason

Security

Found a vulnerability? Do NOT open a public issue. See SECURITY.md for disclosure.

License

By contributing, you agree your contributions are licensed under the MIT License.

Code of Conduct

Participation is governed by the Contributor Covenant Code of Conduct.