werk

werk

Plain-language machine description in, engineering package out, with the gaps it found written down.

werk is a Hermes Agent plugin. You describe a piece of equipment in ordinary words. werk turns that into an engineering package. It triages the description into engineering domains and breaks the work into tracked work items. Model roles draft and adversarially review each one. Domain packs run measured checks (for mechanical work, a build123d 3D model and its checks). Then werk writes a COVER.md that lists every verification gap it could not close.

NOT FOR CONSTRUCTION. werk is a proof of concept. Every package it produces carries the banner "NOT FOR CONSTRUCTION - proof of concept, requires review by a licensed engineer". Do not build, energise or sell anything from a werk package without that review.

Read what werk does on your machine and known limits before installing.

The presentation still from the verified demo run, as the mech pack drew it. Its COVER.md is docs/example/COVER.md.

Install

Commands marked (not run here) were not run for this release's docs. They need a model, a terminal, the network or a catalog listing.

hermes plugins install werk           # once werk is listed in the catalog (not run here)
hermes plugins install aaddrick/werk --ref <40-char commit sha>   # before that (not run here)
hermes plugins enable werk            # (not run here)
hermes werk doctor                    # read-only checks
hermes werk doctor --setup            # interactive; asks first (not run here)

doctor --setup creates the Kanban worker profiles werk-builder and werk-reviewer, the board werk, and one uv venv per pack. It changes nothing in your own profile. Then map the model tiers (opus, sonnet, haiku) in werk's tiers setting. Getting started has the full steps.

Quickstart

mkdir -p ~/werk-projects
hermes werk project new "${HERMES_HOME:-$HOME/.hermes}/plugins/werk/werk/data/demo/conveyor.md" \
    --dir ~/werk-projects/conveyor
hermes werk run --project ~/werk-projects/conveyor --runner real --dry-run   # routes only, changes nothing
hermes werk run --project ~/werk-projects/conveyor --runner real             # model calls, spends tokens (not run here)

The demo description is a 2 m carton infeed belt conveyor. It ships inside the plugin as werk/data/demo/conveyor.md. Start reading the result at ~/werk-projects/conveyor/package/COVER.md.

In the verified run of this demo on the code in this release, werk built a STEP model of 39 solids, used 3,865,868 tokens in 35 min, and passed its 5 mech checks. Its COVER.md lists not-covered 29, safety unverified 4 and open work 12. The full record is in The package.

Requirements

• Linux, Hermes Agent >= 0.23.0, and a model provider configured in Hermes (mapped to werk's model tiers).
• uv on PATH for hermes werk doctor --setup, which builds the pack venvs.
• Projects on a local disk, not NFS/SMB/sshfs or a synced folder. Full list: Getting started.

Documentation

The rest of the manual lives in docs/:

• Index: every page with a one-line description.
• Getting started: requirements, install, doctor --setup, model tiers and the first run.
• Running a project: creating, running, watching, stopping and resuming a project, budgets and the other commands.
• Packs: what a domain pack is, pack.yaml, the shipped packs, pack validate and pack prove.
• The package: what a run produces, manifest.json, trails, and COVER.md section by section.
• Architecture: the core, the nine stages, the roles, packs, hooks and tools.
• What werk does on your machine: model spend, commands, network, files, credentials.
• Known limits: every limit of this release, in full.
• Troubleshooting: symptom, cause and what to do.

What makes it trustworthy

werk reports what it did not check. Each item below ends with the limit that bounds it. All of them are in known limits.

• COVER.md lists the verification gaps. Every package has a COVER.md. It lists exactly the manifest's files and, under ## Verification Gaps, every open gap by class (blocks-safety, blocks-function, needs-hardware-data, cosmetic, not-covered). Domains with no pack are not dropped: they become declared gaps. Limit: COVER.md does not find every gap. In the verified run it says four arrangement requirements are "verified by CHK-MEC-011", a connectivity check that cannot fail on them. Read those lines as unverified.
• UNMEASURED is never PASS. A check that cannot measure reports UNMEASURED. It never reports a pass it did not measure. Limit: a check that does measure can still be bound to a requirement it cannot tell apart. And the mass and size check compares the model with limits the design set for itself.
• Builders never grade their own work. Each design item goes through builder sessions and adversarial review gates. A builder's claim that it fixed a reviewer finding goes back to the reviewer that raised it. Limit: reviewer calibration is not passed (in the latest live calibration, 1 of 7 roles met the bar). Treat review findings as leads, not as sign-off.
• What review left unsettled is printed on COVER.md. A fix claim that no later review round checked is listed as "builder claims fixed, not independently re-checked". Every requirement bound to a check gets its own line. A requirement that a part is present, bound only to checks that cannot detect a missing part, reads "unverified; bound to CHK-..., but this check cannot detect absence". A reviewer that rules again on its own closed finding is ignored, and the review closes normally. Limit: that ignored ruling is recorded in the trail only, not on COVER.md. A deferred finding does not carry the "not independently re-checked" wording.
• Reviewers are tested with planted faults. Reviewer roles are scored on planted-defect fixtures. COVER.md's reviewer flags name a role that approves planted defects as a rubber stamp. Limit: in an earlier acceptance run the domain contrarian reviewer was flagged "rubber-stamp [plants 5, caught 0]". Treat its approvals as unchecked.
• NOT FOR CONSTRUCTION. Every package carries the banner and needs review by a licensed engineer. Limit: only the 3D model is designed and checked. The electrical safety circuit, the power supply and drive, and the safety controls are listed as gaps, not designed.

What werk does on your machine

A summary for the Hermes plugin catalog (rule 13). Full detail: docs/disclosures.md.

• Model spend. hermes werk run --runner real makes many model calls and can run for hours. It is capped by a token budget (default 60M tokens) and a wall-clock budget (default 24 h). triage --agent, calibrate and doctor --llm-probe also make model calls.
• Commands. Argument lists, never a shell: hermes kanban and hermes profile/config/plugins commands, uv (setup only, after you consent), pack tools in their own venvs with the network cut where the system allows, kicad-cli if it is on your PATH, and ssh-keygen -Y verify|sign for signed overrides.
• Network. Model calls go through Hermes's providers. doctor --setup downloads a CPython 3.12 build (through uv) and the packs' hash-pinned packages from PyPI (three elec packages are built from source; see disclosures). werk's own code opens no network connections, and nothing is downloaded at run time.
• Files. werk writes inside the project directory you name and in its Hermes plugin data directory. It reads the allowed_signers file you name in its settings. It writes nothing inside its own install directory.
• Background processes. None outlive a command. hermes werk run is a foreground process: no service, cron job or gateway task. The dashboard page polls werk's own route every 3 s while it is open.
• Credentials. No .env, auth.json or other credential store is read. The three optional supplier-key settings are not read by any code in this version.
• Interactive steps. Setup and trust pinning ask [y/N] at a terminal and refuse when there is none.
• No self-update, no telemetry. Usage accounting stays in the local project store.

Known limits

The full list, with every item in full: docs/known-limits.md. The main ones:

• NOT FOR CONSTRUCTION. Proof of concept; every package needs review by a licensed engineer.
• Mechanical only is designed. Elec, power and safety are gaps. Neither pack has passed hermes werk pack prove.
• Reviewer calibration is not passed. Treat review findings as leads, not as sign-off.
• Cost per run is several million tokens. The verified run used 3,865,868. The token budget (default 60M) caps every run.
• The mechanical review can loop. It loops on requirements its checks cannot tell apart. The final round closes as nonblocking to avoid a loop.

Repo layout

plugin.yaml        the Hermes plugin manifest: tools, hooks, settings and their defaults
__init__.py        registration only: tools, the `hermes werk` CLI, the `/werk` command, hooks, skills
werk/              the core: store, driver, work items, review, packages, CLI; data/demo/conveyor.md
skills/            one role prompt per directory (SKILL.md), registered as werk:<role>
packs/             domain packs: mech, elec (each with its own pyproject.toml and uv.lock, run in its own venv,
                   never imported into Hermes); _smoke is a test pack for the venv setup, not a domain pack
dashboard/         werk's page in the Hermes web dashboard: manifest.json, dist/ bundle, and plugin_api.py,
                   the backend API both pages use
desktop/           werk's page for the Hermes Desktop app (plugin.js)
ui/                the UI sources and build.py, which builds dashboard/ and desktop/ (--check verifies them)
docs/              index.md and the topic guides; example/ holds the verified run's COVER.md and still; diagrams/ holds
                   the D2 sources, their light and dark SVGs, and render.sh

To work on werk from a checkout instead of installing it, see Working from a checkout.

Author

aaddrick · LinkedIn

Licence

Apache-2.0, see LICENSE. GPL tools a pack uses (KiCad's kicad-cli) run only as separate processes.

README from the reviewed commit 457f4aa; it updates when the author re-pins.