hureva 2.1.1

Spec review & approval workflow: frontmatter contract, transition detection, and role→person→channel routing.

hureva

A spec review & approval workflow you install into your team's repo: generate specs with Claude, get structured review from non-technical teammates (PM, UX, QA) before code is written, and record approval in git. Based on docs/spec-review-workflow-specification.md.

hureva is a versioned package teams install, not copy. Your specs live in your own repo under specs/; you add a small workflow that pip installs a pinned version of hureva and runs it, plus a bit of config. Nothing is hosted, and none of hureva's code lives in your repo.

Installing it? See SETUP.md for the step-by-step guide.

How it works

• The spec is a spec.md whose frontmatter is the contract (§4.2): status, role-based access (owner/approvers/commenters/viewers), and the sign-off trail. People are named by roster key; channels resolve from .hureva/roster.yml.
• Work happens on whatever branch you like — no naming convention required. Pushing a status change fires the workflow, which compares the spec's status across the push's two commits and acts only on a transition (§7.4). (A push directly to the repo's default branch still fires the workflow, but there's no PR to open from there, so GitHub-channel delivery has nothing to attach a review request to.)
• draft → in_review notifies reviewers; → approved tells the owner "ready to build."
• Specs are authored by Claude, not scaffolded by a CLI: hureva-init writes a CLAUDE.md with the frontmatter contract and role-seeding rules, so Claude creates a conformant spec.md and branch directly from those instructions.

Library

Piece	Module	Spec
Frontmatter / roster / defaults models	hureva.models	§4.2–4.4
Frontmatter parsing (+ lenient status reader)	hureva.frontmatter	§4.2
.hureva/ config loading + specs_dir-derived paths	hureva.config	§4.1, §4.4
Two-commit transition detection (pure fn)	hureva.transitions	§7.4
Changed-spec discovery from a push	hureva.discovery	§7.4
Event → role → person → channel routing	hureva.routing	§7.1
Sender interface + dry-run + Slack + SMTP	hureva.senders	§7.3
Notify orchestration + CLI	hureva.notify	§7

The logic is a pure library (git/env reading is a thin shell), delivery is behind a Sender interface, and the specs path is configurable — nothing hard-codes specs.

How teams install it

hureva is a PyPI package (hureva), published on each GitHub Release. The fastest path is to scaffold the setup, then follow the printed checklist:

pip install hureva
hureva-init            # writes the workflow + config, prints next steps

Under the hood that adds one small, static workflow that installs the versioned package and runs its notify command:

# team-repo/.github/workflows/hureva-spec-review.yml
on:
  push:
    branches: ["**"]          # any branch, but excludes tag pushes
    paths: ["specs/**"]       # (literal — Actions can't use a variable here)
jobs:
  hureva-spec-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # both push commits reachable (§7.4)
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install "hureva~=2.0"                 # ← version pin lives here
      - run: hureva-notify --specs-dir specs
        env:
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          # SMTP_* too, if using email

Nothing of hureva's code lives in the team repo — the workflow is generic "install a tool and run it" plumbing, and all behavior is in the versioned package. The hureva- prefix in its filename is deliberate: this file is hureva-owned, not yours to hand-edit — hureva-init regenerates it on every run (no --force needed), unlike the roster/defaults/CLAUDE.md content files, which are yours and are left alone once they exist.

Versioning — pin the package

pip install "hureva~=2.0" is the version pin (like "hureva": "^2.0" in a dependency list). It's the alternative to copying hureva's code in (which drifts and never gets fixes): you install a released version.

• ~=2.0 takes any 2.x release, so compatible fixes flow in automatically.
• Pin exactly with ==2.0.0; move to the next major (~=3.0) when you choose, after reading its release notes.

CLIs

Commands (also runnable as python -m hureva.<module>). The operational ones take --specs-dir (default specs).

# One-time: scaffold the workflow + config into this repo, print next steps
hureva-init

# Route notifications for a push (--dry-run prints without delivering)
hureva-notify --dry-run

hureva-notify reads the GitHub push event ($GITHUB_EVENT_PATH, set by the runner; or --event-file) to get the before/after commits. Recipients come from the spec's frontmatter roles; each person's channel is their handle in roster.yml. A name missing from the roster is reported loudly, never dropped silently.

Channels

Each person is reached on the channel whose handle you give them in roster.yml (list only one; the order below breaks ties):

• GitHub — github: <username>. No setup — the workflow's built-in GITHUB_TOKEN opens a PR for the spec branch and requests the person as a reviewer, so GitHub emails/notifies them. They just need access to the repo.
• Slack — slack: "<U-id>"; set the SLACK_BOT_TOKEN secret. Handles: #channel, a member ID (U…), or an email (DM via users.lookupByEmail).
• SMTP email — email: <addr>; set SMTP_HOST (+ SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM).

GitHub works out of the box; Slack/email activate only when their secret is set. --dry-run needs no credentials.

Independent of channels: .hureva/links.yml says where reviewers read specs. Each entry is a notification label and a URL template, rendered fresh per spec from {repo}, {branch}, {slug}, and {path} (a template naming none of them is used as-is — all a plain docs site needs). hureva-init writes it from your answer; every label resolves independently, so a prototype: link never displaces your review link. The file is optional: without it, notifications carry the pull request link alone.

Templating is the whole mechanism — no network call at notify time. A Hureva (repo, branch, path) link is only resolved to a ReviewDoc lazily, in the app, the first time a reviewer clicks it.

Develop

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest