clone

a hermes agent plugin for openspec: tools for spec workflows and a dashboard tab for browsing changes and specs

main
hermes-openspec / openspec / changes / archive / 2026-06-22-fix-init-instructions-workflow / proposal.md
proposal.md 1.8K rendered
1## Why23Fresh OpenSpec repositories exposed three maintainer-visible workflow problems:451. Before initialization, OpenSpec list operations fail with `No OpenSpec changes directory found`; the plugin should make dashboard initialization create a complete, CLI-listable OpenSpec layout.62. `openspec init --tools none` creates `changes/` and `specs/` but not the plugin-supported `ideas/` directory, and may omit `changes/archive/` in fallback paths; the dashboard should normalize the layout after either CLI init or fallback init.73. `openspec_instructions` can fail in freshly initialized repositories because the OpenSpec CLI requires an existing change, and the tool description advertised `spec` even though the CLI artifact is `specs`; the agent tool should accept the natural alias and return useful template guidance when no change exists.89## What Changes1011- Add layout normalization after dashboard source initialization so initialized sources always contain `openspec/changes/`, `openspec/changes/archive/`, `openspec/specs/`, and `openspec/ideas/`.12- Add fallback behavior to `openspec_instructions` for no-change repositories by returning the package template for the requested artifact.13- Normalize `artifact="spec"` to `artifact="specs"` for the tool and schema description.14- Add regression tests for the initialization layout and fresh-repo instruction fallback.15- Make the plugin package importable under pytest from the repository root so regression tests can run locally.1617## Capabilities1819### New Capabilities20- None2122### Modified Capabilities23- `dashboard-sources`: source initialization must normalize all plugin-supported OpenSpec directories.24- `agent-tools`: instructions lookup must tolerate fresh repositories and the `spec` alias.2526## Impact2728- `dashboard/plugin_api.py`29- `tools.py`30- `schemas.py`31- `__init__.py`32- `tests/test_openspec_workflow_fixes.py`