Openspec

openspec

OpenSpec is a spec-driven development layer for AI coding assistants. In Hermes, this integration is delivered as normal Hermes skills. Users invoke workflows by loading a skill, for example:

• /skill openspec-propose then describe the change
• hermes -s openspec-apply-change from a project root
• natural language: "Use OpenSpec to verify add-dark-mode"

This repository covers all current OpenSpec features, not just the quick path:

• Core workflows: propose, explore, apply, sync, archive
• Expanded workflows: new, continue, ff, verify, bulk-archive, onboard
• CLI management: init, update, list, show, validate, archive, instructions, templates, schemas
• Customization: project config, rules, custom schemas, schema fork/init/validate/which
• Workspaces, context stores, initiatives, and local shared coordination features

Hermes operating rules for OpenSpec

• Work from the user's project root. If unknown, inspect the current directory first.
• Ensure the OpenSpec CLI exists before using it: openspec --version. If missing, install with npm install -g @fission-ai/openspec@latest.
• Initialize projects with openspec init --tools none unless the user also wants other AI-tool integrations. Hermes uses these skills, not OpenSpec-generated slash commands.
• Prefer agent-compatible OpenSpec CLI calls with --json where available: openspec list --json, openspec status --change <id> --json, openspec instructions <artifact> --change <id> --json, openspec validate --all --json.
• Read generated artifacts before editing or implementing. Do not invent OpenSpec state.
• Run validation after changing OpenSpec artifacts: openspec validate <change> or openspec validate --all.
• Keep changes focused. If user scope diverges, update the existing change only when intent is the same; otherwise create a new change.

Recommended single-skill paths

Use these when the user wants Hermes to handle the whole recommended path automatically:

Skill	Runs
openspec-quick-path	propose -> apply -> verify -> archive when safe
openspec-expanded-path	new -> ff -> apply -> verify -> archive when safe
openspec-ship-change	detect state -> finish planning -> apply -> verify -> archive when safe

Quick use from Hermes

1. In a project root: openspec init --tools none
2. Load one workflow skill: openspec-explore, openspec-propose, openspec-new-change, openspec-continue-change, openspec-ff-change, openspec-apply-change, openspec-verify-change, openspec-sync-specs, openspec-archive-change, openspec-bulk-archive-change, or openspec-onboard.
3. Use OpenSpec's CLI as source of truth for state and templates.

Command mapping

OpenSpec command	Hermes skill
/opsx:explore	openspec-explore
/opsx:propose	openspec-propose
/opsx:new	openspec-new-change
/opsx:continue	openspec-continue-change
/opsx:ff	openspec-ff-change
/opsx:apply	openspec-apply-change
/opsx:verify	openspec-verify-change
/opsx:sync	openspec-sync-specs
/opsx:archive	openspec-archive-change
/opsx:bulk-archive	openspec-bulk-archive-change
/opsx:onboard	openspec-onboard

Full workflow examples

Quick path: openspec-propose -> review artifacts -> openspec-apply-change -> openspec-verify-change -> openspec-archive-change

Expanded path: openspec-new-change -> openspec-continue-change repeatedly, or openspec-ff-change -> openspec-apply-change -> openspec-verify-change -> openspec-archive-change

Parallel changes: Use explicit change names in every skill, run openspec list --json to inspect active changes, and use openspec-bulk-archive-change only after completed changes have been verified.