1# Contributing to hermes-openspec23Thanks for your interest in improving this plugin. This is a small, focused4project — the bar is a clean diff that fixes a real bug or adds a feature5that fits the plugin's scope (OpenSpec integration for Hermes Agent).67## Reporting issues891. **Check existing issues** first to avoid duplicates.102. **Include a reproduction**: the exact steps, what you expected, and what11 happened. If it's a dashboard issue, note your browser and Hermes version.123. **Include the error**: paste the full traceback or the HTTP response. A13 screenshot of the dashboard is fine for UI bugs.144. **Note your environment**: OS, Hermes version, OpenSpec CLI version15 (`openspec --version`), and whether the `openspec` binary is on `PATH`.1617## Submitting pull requests1819### Before you start2021If the change is non-trivial (new endpoint, new UI component, schema change),22open an issue or draft PR first to scope it. This avoids wasted work on23something that doesn't fit the design.2425### Branches2627This repo uses trunk-based development on `main`:2829- `main` is the only long-lived branch. All PRs target `main`.30- Branch short-lived feature branches off `main`, PR back, delete after merge.31- Releases are tagged on `main` (`v0.1.0`, `v1.0.0`, …). No release branch.3233### What we look for3435- **Fix real bugs.** Reproduce the symptom on `main`, point to the exact line,36 and fix the whole bug class — not just the one site you hit.37- **Keep the core narrow.** This plugin extends Hermes at the edge. Don't add38 hooks, callbacks, or extension points with no concrete consumer.39- **No new env vars for non-secret config.** Behavioral settings go in the40 Hermes config, not `.env`. Only credentials belong in `.env`.41- **Match existing style.** The frontend is a hand-written IIFE in42 `dashboard/dist/index.js` — no build step, no framework, no JSX. The backend43 is plain FastAPI in `dashboard/plugin_api.py`. Follow the patterns already44 there.45- **Don't break the registry DB.** `registry.py` manages a SQLite DB at46 `~/.hermes/openspec.db`. Schema changes must be backward-compatible or47 include a migration. Never delete user data.4849### Testing5051There's no automated test suite yet. Before submitting:52531. Install your changes: copy the plugin dir to `~/.hermes/plugins/openspec/`54 (only `openspec.db` persists across updates — everything else is55 overwritten).562. Restart Hermes and verify the dashboard tab loads.573. Exercise the affected code path manually — register a source, browse58 changes/specs, trigger the bug you fixed.594. If you added a backend route, confirm it returns sane responses for both60 the happy path and error cases (missing source, invalid path, etc.).6162### Commit messages6364Follow the existing convention:6566```67type: short description6869Optional body explaining why, not what.70```7172Types: `fix`, `feat`, `docs`, `refactor`, `chore`.7374### Deploying for development7576```bash77# Copy from repo to installed plugin location78cp -r ~/repos/hermes-openspec/* ~/.hermes/plugins/openspec/7980# If backend routes changed, restart Hermes to remount them81# Frontend-only changes can be hot-reloaded via dashboard rescan82```8384The `openspec.db` database lives at `~/.hermes/openspec.db` (outside the85plugin directory) and survives plugin updates. Do not include it in PRs.8687## Questions8889Open an issue with the `question` label.