An opinionated, Spec-Driven Development orchestration system for Hermes Agent. One orchestrator, nine agent roles, and a review chain that turns "trust me" into hashes — OpenSpec holds the requirements inside each project's repo.

• ⚡ TL;DR
• 🎯 The pitch
• 📁 Repository layout
• 🔄 The loop & the gate
• 🔗 The evidence chain (8 bins)
• 🤖 Agent roles
• 🎚️ Task levels
• 🧠 Skill catalog (65 skills · 23 personas + 42 process)
• 🧪 Fixture suites
• 📜 Operating rules
• 🚀 Quick start
• 🐕 How this repo eats its own dogfood

AI coding agents forget, improvise, and self-report. Three failures break every AI-assisted workflow unless you build against them:

1. Context amnesia — a new session starts from zero and asks you what the files already answer. State lives in memory instead of the repo.
2. Smoke — an agent says "I tested it" about content it may never have seen, or a tree that changed five minutes later. The review describes code that no longer exists.
3. Depth by mood — big migrations get skimmed, small fixes get three passes, because review depth follows whoever is on shift instead of the diff's real risk.

The fix is structural: state in files, evidence as hashes, review depth derived from the diff. An agent's output is a self-report until a command proves it — always re-verify in the repo.

agents/         agent contracts (discovery · openspec · architect · planner ·
                builder · reviewer · pr-reviewer · qa · release) + README
bin/            the 8 evidence bins: no-smoke-worktree · skill-registry ·
                review-snapshot · review-tier · agency-next · run-trace ·
                change-collision · phase-gate
rules/          orchestration · openspec · sdd · quality · coding · testing ·
                project-boundaries
workflows/      initialize-project · idea-to-openspec · openspec-to-architecture ·
                plan-change · implement-change · review-change · qa-change ·
                release-change · pr-review · autonomous-change · continue-change
templates/      final-report · review-report · qa-report · adr · spec · tasks · …
docs/           evidence-bins · sdd-feature-lifecycle · usage-examples · FAQ
skill-bundles/  15 slash-command bundles: /agency /feature /do /review /qa …
skills/         60 process skills (23 agency personas + 37 workflow skills)
fixtures/       8 runnable test suites that pin the bins themselves
openspec/specs/ 7 capability specs — the agency's own requirements, versioned

One principle, everywhere (rules/project-boundaries.md): Hermes provides the process; the project provides the product. Global instructions are reusable and never carry a product requirement; product knowledge lives in the project's repo.

┌─────────────── the canonical loop ───────────────────────────────┐
│  0 initialize-project   (no code)                                │
│  1 discovery · idea / PRD                                        │
│  2 openspec · proposal + deltas     ◄── GATE: validate, no ERROR │
│  3 architect · design + ADRs                                     │
│  4 planner · tasks.md                                            │
│  5 builder · code + tests (TDD by hard rule)                     │
│  6 reviewer · adversarial diff    ◄── can BLOCK (BLOCKER/MAJOR)  │
│  7 qa · executes the scenarios   ◄── can BLOCK (qa: fail)        │
│  8 release · notes + archive + sync + evidence-comparison         │
└──────────────────────────────────────────────────────────────────┘
   gate: no code without a validated change · two failures with the
   same error ⇒ the spec is wrong, go back a stage — never in circles

Hermes is the only orchestrator: it decides which stage runs, delegates one bounded task per agent, validates every output in the real repo, applies retries and blockers, asks the human on ambiguity, and closes with a final report. Order: initialize-project → discovery → propose → validate → plan → apply → verify → release.

One principle: an agent's report is a self-report, not a fact. Eight small commands read files, print hashes, and never trust memory. The chain: freeze → tier → review → compare. Full step-by-step guide with real outputs: docs/evidence-bins.md.

• no-smoke-worktree — content fingerprint of the working tree (tracked + untracked + ignored). Reviewer, QA and release record it; a mismatch at delivery means the evidence describes content that no longer exists. Survives rebase/amend; changes when any source changes.
• review-snapshot — freezes the candidate before anything reads it (base, HEAD, fingerprint, diff hash). Findings bind to that snapshot; --compare at delivery is content-based, so a clean rebase matches while a real change trips the alarm.
• review-tier — depth from the diff's shape: ≤400 authored lines ⇒ medium; schema/migration, auth, security config or dependency manifests ⇒ high; an unmeasurable diff ⇒ cannot assess, never a rubber-stamp low. Informational — never blocks.
• agency-next — the derived state + the single valid next transition, read from files. A missing input narrows the answer; it never defaults to optimistic, and it never blocks, merges or archives.
• skill-registry — read-only inventory: exact SKILL.md path, description, tags, and flags for the frontmatter defects that make a skill load but mis-route (BLOCK-SCALAR content-less indicator, MISSING-DESCRIPTION, NO-FRONTMATTER, UNCLOSED-FRONTMATTER). Pinned by its own fixture suite.
• run-trace — reads reports/<runId>.jsonl (the NDJSON the loop appends at every stage) and prints the run's stages, statuses, blockers and assumed decisions — so a dead session resumes and an audit reads the same truth the runner wrote. Honest by design: an absent file or an invalid line reports that, never an optimistic "nothing happened".
• change-collision — prints parallelizable / collision / cannot assess for two changes given a base: overlapping paths, or both touching a high-risk family (schema/migrations, openspec/, contracts/auth, dependency manifests) → collision; unmeasurable input → cannot assess, never a silent parallelizable. Wired into rules/orchestration.md ("Parallel execution of changes"): the verdict decides ordering, never approval.
• phase-gate — the project's phase as a fact in the repository, not a memory. pass (0) · refuse (1) · cannot assess (2). A validated OpenSpec change is necessary, never sufficient: a complete, apply-ready change in a documentation-phase project is still refused, and an undeclared phase is not an open one. Wired into the implementation preflight, rules/coding.md, the builder brief and rules/orchestration.md (blocker class decision). Guide: docs/phase-gate.md.

All eight are informational or evidence-bound: they surface truth, they never silently approve. The gates remain the reviewer's and QA's verdicts.

Every output returns in the mandatory envelope (status / summary / projectRoot / filesCreated / filesModified / blockers / nextRecommendedStep / evidence / openQuestions), and Hermes re-verifies every claim against the real repo before the next stage.

Language contract (rules/sdd.md): everything the system produces is English — specs, code, branches, commits, PRs, docs. The only exception is the conversation with the user.

Descriptions read from each skill's own SKILL.md frontmatter — generated by the repo's own skill-registry bin, so the catalog can't drift from what ships.

Generated from skills/**/SKILL.md frontmatter by bin/skill-registry — the catalog's source of truth is the repo.

The bins are pinned by runnable suites, not by fixtures that never run. A suite that can't run fails loudly (exit 3), never passes silently.

One command installs the process tree, skills and 15 bundles into a Hermes home (default ~/.hermes; interactive menu, guarded against accidental overwrites, idempotent):

bash <(curl -fsSL https://raw.githubusercontent.com/mcabreradev/hermes-sdd-agency/main/install.sh)

Then, in any project:

hermes        # > let's run SDD: add SSO login to the web app
/agency       # run the loop stage by stage
/feature      # feature-level (full loop, discovery-first)
/do           # autonomous: run the whole loop, end in a PR for your morning review
/continue     # resume an existing change from its pending stage, update the PR

For /feature's discovery step, install the four discovery skills once (superpowers:brainstorming + mattpocock's grilling, grill-with-docs, domain-modeling) — the installer warns, never installs. Full guide: INSTALL.md.

This repository is maintained by the process it ships: every feature here went through the same loop — an OpenSpec change, adversarial review, a formal PR QA gate (#15), a frozen-candidate evidence chain (#19), and the fix of a false positive (skill-registry) that a real reviewer caught because the loop demands evidence over assertion. The skill catalog above is generated by one of the bins it ships. If one day this README becomes a self-report, the loop is designed to notice.

The process is the product. MIT — the persona skills under skills/agents/ keep their upstream provenance (aitmpl.com) in their frontmatter.