{"id":51011455,"url":"https://github.com/xsa-dev/hermes-spec-harness","last_synced_at":"2026-06-21T03:03:39.889Z","repository":{"id":364808588,"uuid":"1269292370","full_name":"xsa-dev/hermes-spec-harness","owner":"xsa-dev","description":"OpenSpec-governed engineering harness for Hermes Agent","archived":false,"fork":false,"pushed_at":"2026-06-14T15:39:16.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T16:44:24.239Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xsa-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T14:33:40.000Z","updated_at":"2026-06-14T15:39:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xsa-dev/hermes-spec-harness","commit_stats":null,"previous_names":["xsa-dev/hermes-spec-harness"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/xsa-dev/hermes-spec-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xsa-dev%2Fhermes-spec-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xsa-dev%2Fhermes-spec-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xsa-dev%2Fhermes-spec-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xsa-dev%2Fhermes-spec-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xsa-dev","download_url":"https://codeload.github.com/xsa-dev/hermes-spec-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xsa-dev%2Fhermes-spec-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34592057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-21T03:03:39.123Z","updated_at":"2026-06-21T03:03:39.876Z","avatar_url":"https://github.com/xsa-dev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hermes Spec Harness\n\nOpenSpec-governed engineering harness for Hermes Agent.\n\nHermes Spec Harness packages a practical workflow for teams that want Hermes to work from reviewed specs instead of directly changing a codebase. It combines a Hermes profile distribution, a reusable Hermes skill, project `AGENTS.md` rails, OpenSpec schema bundles, bootstrap scripts, and examples.\n\n## Problem Statement\n\nAgentic coding can drift when the workflow is implicit. Large repositories need a stable source of truth, clear review points, safe delegation, and a commit boundary that matches the approved change. Hermes Spec Harness makes those constraints installable and repeatable.\n\n## Why Profile-First Packaging\n\nThe repository can be installed as a Hermes profile distribution. Profile mode gives the harness its own identity, configuration, skills, sessions, and runtime state while keeping credentials, user memories, and local machine state outside the published package.\n\nThe profile is not a filesystem sandbox. Use worktrees, Docker, a remote terminal backend, or a constrained project cwd when work needs isolation.\n\n## Why Skill-First Packaging Still Matters\n\nThe skill can be installed without adopting a full profile. Skill-only mode is portable, easy to inspect, and works with an existing Hermes setup. It keeps the OpenSpec workflow close to the agent without requiring changes to Hermes itself.\n\n## Why OpenSpec Is Source Of Truth\n\nOpenSpec is the source of truth for all non-trivial changes. Source code changes only happen after an OpenSpec change exists, specs/tasks are reviewed, and the implementation scope is approved. Completed changes should be archived before the commit boundary.\n\n## Repository Layout\n\n```text\nhermes-spec-harness/\n├── distribution.yaml\n├── SOUL.md\n├── config.yaml\n├── README.md\n├── install.sh\n├── uninstall.sh\n├── scripts/init-project.sh\n├── templates/AGENTS.md\n├── skills/hermes-spec-harness/SKILL.md\n├── openspec-schemas/\n├── examples/\n└── docs/\n```\n\n## Installation Mode A: Skill-Only\n\nSkill-only installation:\n\n```bash\n./install.sh --verbose\n```\n\nThe default destination is `~/.hermes/skills/hermes-spec-harness`. Use `--skill-path PATH` to install somewhere else. Use `--force` only when replacing an existing different skill directory is intentional.\n\n## Installation Mode B: Profile Distribution\n\nProfile distribution installation:\n\n```bash\nhermes profile install github.com/xsa-dev/hermes-spec-harness --name hsh --alias --yes\nhsh chat\n```\n\nIf `hsh` already exists, update the installed distribution instead:\n\n```bash\nhermes profile update hsh --force-config --yes\n```\n\n`profile update` takes the profile name, not the GitHub URL. Use `--force-config` when you want new distribution defaults such as the bundled `gpt-5.5` model config to replace the installed profile config. The install command also supports `--force` for a reinstall; there is no `--overwrite` flag.\n\nThe profile has its own config, identity, skills, sessions, and runtime state. It defaults to `openai-codex` with model `gpt-5.5`, and its context compression summarizer is also pinned to `auxiliary.compression.provider: openai-codex` + `auxiliary.compression.model: gpt-5.5` so preflight summaries do not auto-route to OpenRouter. It ships no API keys or OAuth secrets; users must configure provider auth locally. Secrets and user memories must not be shipped in the distribution. The profile is not a filesystem sandbox; still use worktrees, Docker/remote terminal backend, or constrained project cwd.\n\n## Using Hermes Spec Harness as a profile\n\nHermes Spec Harness profile = Hermes Agent + OpenSpec workflow + HSH skill + project `AGENTS.md` + safe review/verify/archive discipline. Use it when you want a dedicated OpenSpec-governed engineering agent rather than only a portable skill in an existing profile.\n\n## Uninstall\n\nPreview first:\n\n```bash\n./uninstall.sh --dry-run --verbose\n```\n\nThen remove the installed skill directory:\n\n```bash\n./uninstall.sh --verbose\n```\n\nOnly the exact `hermes-spec-harness` skill directory is removed.\n\n## Bootstrap A Legacy Project\n\n```bash\n./scripts/init-project.sh /path/to/project --default-schema hsh-legacy-audit --allow-external-write --verbose\n```\n\nThe bootstrap script initializes OpenSpec with `--tools none` when needed, copies the HSH schema bundles into `openspec/schemas/`, configures a default schema safely, and creates `AGENTS.md` from the template when missing.\n\nIf the target project already has `.hermes.md` or `HERMES.md`, those files may override `AGENTS.md` and should be reviewed. Existing `AGENTS.md` is preserved unless `--overwrite-agents` or `--force` is provided.\n\n## OpenSpec Schemas\n\n- `hsh-fix`: bounded implementation work after specs/tasks are approved.\n- `hsh-investigation`: diagnosis and recommendation without source changes.\n- `hsh-legacy-audit`: audit-first onboarding for existing projects with proposal, specs, and tasks.\n\n## Safety And Idempotence\n\nAll scripts support `--dry-run`, `--verbose`, and `--help`. They are designed to be idempotent: repeated runs should not duplicate content or rewrite unrelated files. The overwrite policy is safe by default. Existing project files are preserved unless an explicit overwrite flag is passed.\n\nExternal-write safety is enforced by `scripts/init-project.sh`: a target outside the caller's current working directory is refused unless `--allow-external-write` is provided.\n\nNo commits are performed by scripts.\n\n## Connecting To External Tools Such As Paperclip\n\nThe primary integration path is a Hermes API server or OpenAI-compatible endpoint if the external tool can target agent/model endpoints. A webhook bridge can translate external events into Hermes prompts. An MCP bridge may be possible, but confirm the direction: Paperclip may expect Hermes to act as an MCP server, while Hermes deployments may primarily act as an agent/API client.\n\n## Testing\n\n```bash\nfind . -type f | sort\nsh -n install.sh\nsh -n uninstall.sh\nsh -n scripts/init-project.sh\n./install.sh --dry-run --verbose\n./uninstall.sh --dry-run --verbose\n```\n\nFor a local bootstrap smoke test, create a temporary git project and run `scripts/init-project.sh` against it. If network access is available, also run:\n\n```bash\nnpx --yes @fission-ai/openspec@latest schema validate\n```\n\n## Publishing\n\nThis project is licensed under the Apache License 2.0. See `LICENSE`.\n\nPublish the GitHub repository, optionally publish the Hermes skill, publish the profile distribution entry, and share the OpenSpec schema bundle as a community schema package.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxsa-dev%2Fhermes-spec-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxsa-dev%2Fhermes-spec-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxsa-dev%2Fhermes-spec-harness/lists"}