- commit
- c02700d61483b83a0bf0129cd96460db801a1d2e
- parent
- c85eef806594294b1a46d0a9515687f6cf6fe24f
- author
- dami etoile <dami.etoile@gmail.com>
| A | README.md | 115 | ++++++++++++++++++++++++++++++ |
@@ -0,0 +1,115 @@
1+# hermes-openspec2+3+OpenSpec integration plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent) — spec-driven development tools and a dashboard tab for browsing change proposals, specs, and branch diffs across registered repos.4+5+## Why this exists6+7+OpenSpec keeps spec files (`openspec/changes/`, `openspec/specs/`, `openspec/ideas/`) inside the repo alongside code. But there's no way to browse those specs from the Hermes dashboard, and the agent has no native tools to resolve OpenSpec identifiers or run OpenSpec CLI commands.8+9+This plugin closes both gaps:10+11+- **Agent tools** — six tools that wrap the `openspec` CLI so the agent can list, read, validate, and track OpenSpec changes and specs without shelling out manually. The tools are gated behind the CLI binary's availability, so they stay invisible if OpenSpec isn't installed.12+- **Dashboard tab** — a `/openspec` tab in the Hermes dashboard where you register repos, drill into change proposals (tasks, designs, specs, deltas), browse current specs, and compare branch diffs — all without leaving the dashboard.13+14+## What you get15+16+**Agent tools** (gated on `openspec` binary):17+18+| Tool | Does |19+|---|---|20+| `openspec_context` | Resolve a copyable `os_*` identifier (e.g. `puzzletea/os_a1b2c3`) into repo path + change/spec content. Entry point — call this first. |21+| `openspec_list` | List changes or specs in a project, sorted by recent or name. |22+| `openspec_show` | Show a change or spec as JSON — proposals, tasks, designs, deltas, requirements. |23+| `openspec_validate` | Validate OpenSpec changes or specs in a project. |24+| `openspec_status` | Show artifact completion status for a change (turns into kanban updates). |25+| `openspec_instructions` | Enriched instructions for creating artifacts or applying tasks. |26+27+`openspec_context` is always available (reads the registry DB + files only); the other five require the `openspec` CLI binary.28+29+**Dashboard tab** (`/openspec`):30+31+- Register repos by path — each gets a vanity name and stable tokens (`name/os_a1b2c3`).32+- **Changes view** — Kanban-style board: ideas → draft → todo → in_progress → done → archived. Click any change to read its proposal, tasks, design, and spec deltas.33+- **Specs view** — browse current specs in the worktree, sorted alphabetically or by last git commit date. Compare against HEAD (dirty mode) or arbitrary git refs (before/after).34+- Deep-linking via URL hash (`#project-name/token`).35+36+## Requirements37+38+- **Hermes Agent** — any recent build that supports the plugin system (`hermes plugins install`).39+- **OpenSpec CLI** (optional) — needed for five of the six agent tools. The dashboard tab works without it. Install via `npm install -g @openspec/cli` or set `OPENSPEC_BIN` to the binary path.40+- **Git** — used for branch diffs and spec commit-date sorting.41+42+## Quickstart43+44+```bash45+# Install the plugin46+hermes plugins install FelineStateMachine/hermes-openspec47+48+# Enable it (prompts automatically during install, or run explicitly)49+hermes plugins enable openspec50+```51+52+Restart Hermes if it's running. The OpenSpec tab appears in the dashboard at `/openspec`.53+54+To register a repo in the dashboard, open the OpenSpec tab and click **Add source**, or use the agent tool:55+56+```57+openspec_context(identifier="/path/to/your/repo")58+```59+60+The repo needs an `openspec/` directory. Once registered, the dashboard shows changes and specs live from the filesystem.61+62+## Verify63+64+```bash65+# Confirm the plugin is installed and enabled66+hermes plugins list --plain67+68+# Check that the openspec binary is found69+openspec --version70+71+# In the dashboard, open the OpenSpec tab72+# (or curl the API if the dashboard is running on loopback)73+curl http://127.0.0.1:9119/api/plugins/openspec/sources74+```75+76+If `openspec` isn't on your PATH, set `OPENSPEC_BIN`:77+78+```bash79+export OPENSPEC_BIN=/home/user/.npm-global/bin/openspec80+```81+82+## Update83+84+```bash85+hermes plugins update openspec86+```87+88+This pulls the latest from the remote and reloads. If the backend API routes changed (`plugin_api.py`), restart Hermes to remount them — the dashboard rescan (`/api/dashboard/plugins/rescan`) reloads frontend assets but does not remount backend routes.89+90+## Documentation map91+92+```93+hermes-openspec/94+├── plugin.yaml # Tool plugin manifest — declares the six agent tools95+├── __init__.py # Plugin registration — wires tools, sets check_fn gating96+├── schemas.py # Tool parameter schemas (JSON Schema for each tool)97+├── tools.py # Tool handlers — wraps the openspec CLI binary98+├── registry.py # SQLite registry of sources at <hermes_home>/openspec.db99+├── dashboard/100+│ ├── manifest.json # Dashboard tab manifest — tab path, position, entry/css/api101+│ ├── plugin_api.py # FastAPI router mounted at /api/plugins/openspec/102+│ └── dist/103+│ ├── index.js # Dashboard tab frontend (IIFE, uses Hermes plugin SDK)104+│ └── style.css # Plugin styles (uses dashboard --color-* tokens)105+```106+107+| File | What to read it for |108+|---|---|109+| `plugin.yaml` | Which tools the plugin provides |110+| `tools.py` | How CLI commands are wrapped and how the binary is resolved |111+| `registry.py` | Source registry schema, token derivation, DB path |112+| `dashboard/plugin_api.py` | All backend API routes and the spec-browser logic |113+| `dashboard/manifest.json` | Tab registration, entry points |114+| `dashboard/dist/index.js` | Frontend: board, specs view, source dialogs, deep-linking |115+```