Uniterra-Solutions Jovaltus Setup
Guide the agent through installing and configuring the Jovaltus Hermes plugin by reading the official documentation. Never hardcode setup steps — always fetch the latest docs from the Jovaltus repository to avoid staleness.
Goal
A working Jovaltus installation: plugin enabled, profile created, skills available, and installation verified.
Core Principle: Docs Are the Source of Truth
This skill does not contain setup instructions. It tells the agent where to find them. The Jovaltus docs live in the canonical GitHub repository and are the authoritative reference for every step.
If a step in the docs fails, do not guess a fix — check the troubleshooting section in the same document first, then consult the repo's README.
Workflow
Phase 1: Fetch the Setup Documentation
Read the canonical setup guide from the Jovaltus repository:
https://raw.githubusercontent.com/Uniterra-Solutions/jovaltus/main/docs/setup.md
This document covers prerequisites, installation, plugin enabling, profile creation, and verification. It is the single source of truth.
Phase 2: Execute Setup Steps in Order
Follow every step from setup.md exactly as written, in the order they
appear. Do not skip or reorder steps.
After each step, verify success before moving to the next one:
- Prerequisites check: Confirm every required tool is installed at the minimum version before proceeding.
- Install: Run the install command and confirm no errors.
- Enable: Run
hermes plugins enable jovaltusand verify withhermes plugins list. - Setup: Run
hermes jovaltus setup. In non-TTY environments the defaults are safe — the plugin handles this automatically. - Verify: Run
hermes jovaltus statusand check the output matches the expected shape from the docs.
Phase 3: Verify Skills Are Available
After setup completes, confirm the bundled skills are discoverable:
hermes -p jovaltus-agent
In the session, ask the agent to list skills matching "jovaltus". Expect to see all 11 bundled skills (8 pipeline + 3 utility).
Phase 4: Troubleshoot If Needed
If any step fails, consult these resources in order:
- The troubleshooting table in the Jovaltus README
- The Jovaltus architecture doc for understanding how the plugin works
- The Jovaltus workflows doc for common recipes
Common issues and their first checks:
| Symptom | First check |
|---|---|
| Skills not appearing | Plugin symlink in profile's plugins/ directory |
| "No inference provider configured" | Profile config.yaml has model + provider |
| "Unknown command: jovaltus" | hermes plugins enable jovaltus was run |
| 401 Authentication Error | Profile .env has API key |
Gotchas
- The setup doc is the authority. If this skill's workflow contradicts
setup.md, the doc wins. The doc is updated with the plugin; this skill may lag. - Non-TTY environments are supported.
hermes jovaltus setupdetects when no terminal is available and uses safe defaults — no SOUL.md overwrite, no interactive prompts. Do not try to work around this. - Profile binding uses symlinks, not directory installs. The old
hermes plugins install <directory>approach is deprecated for Jovaltus. Always usepip install jovaltus+hermes plugins enable jovaltus. - fabricium is auto-installed. Jovaltus self-bootstraps its dependency on import — no need to install it separately.
- The
jovaltus-agentprofile is separate from other profiles. It is not directory-bound; the same profile works across all projects.
References
- Jovaltus Setup Guide — Prerequisites, install, enable, verify
- Jovaltus README — Installation overview + troubleshooting table
- Jovaltus Architecture — System design, skill-driven pipeline
- Jovaltus Workflows — Common recipes and debugging