Contributing

@maestria/hermes lives in the maestria monorepo under packages/hermes/. It is a Python Hermes plugin using the Hermes Plugin API.

Project Structure

packages/hermes/
├── plugin.yaml                  # Plugin manifest (hooks, commands, tools)
├── __init__.py                  # register() entry point + all handlers
├── permissions.py               # PermissionRole class and ROLES dict
├── modes.py                     # Mode persistence (atomic JSON writes)
├── plugins.py                   # (future) Plugin lifecycle
├── session.py                   # Session lifecycle hooks via SessionDB
├── _version.py                  # Single source of truth for version
├── hooks/
│   ├── pre_llm.py              # Mode injection into user messages
│   ├── pre_tool.py             # Role-based tool gating
│   └── transform.py            # Tool result annotations
├── middleware/
│   └── llm_output.py           # LLM execution wrapper (opt-in mode footer)
├── tools/
│   └── opencode.py             # OpenCode CLI routing tool
├── skills/                      # SKILL.md files (7 specialists + orchestrator + global)
└── sync.config.ts              # Sync configuration for agent directives

Development Setup

# Clone the monorepo
git clone https://github.com/agustinusnathaniel/maestria
cd maestria

# Install dependencies
pnpm install

# Build
pnpm build

Installing Local Changes

To test local changes without publishing:

# Point the hermes plugin to your local clone
hermes plugins install /path/to/maestria/packages/hermes --enable

Or symlink the plugin directory:

ln -s /path/to/maestria/packages/hermes ~/.hermes/plugins/maestria-hermes

Design Principles

1. Methodology portable, adapter thin — Plugin code is the Hermes adapter; the real methodology lives in packages/core/agent-directives/
2. Hermes-native first + memory-agnostic — Use Hermes’ built-in subsystems (delegate_task, ctx.llm, /goal, kanban_*) rather than reimplementing them. Memory is a platform concern (8 providers), not a plugin concern.
3. Self-contained — The plugin has no startup probes for external tools or packages. The opencode_route tool delegates to OpenCode CLI if installed, but does not verify or probe for it at startup.
4. Feel native — Commands, hooks, and config follow Hermes Plugin API conventions

See the ADR-HM-001 for the design rationale behind specific scope decisions.

Testing

# Run plugin-specific tests
pytest packages/hermes/

# Run the full monorepo quality gates
vp check

Extending

Adding a command

1. Create commands/<name>.py with an async function async def cmd_<name>(ctx, args):
2. Register it in __init__.py’s register() via ctx.register_command()
3. Add the command name to plugin.yaml’s commands list

Adding a hook

1. Create hooks/<name>.py with the handler function
2. Wire it in __init__.py’s register() via ctx.register_hook()
3. Add the hook name to plugin.yaml’s hooks list

Adding a skill

1. Create the SKILL.md file in skills/
2. Register it via ctx.register_skill() in __init__.py
3. Skills are namespaced as hermes-maestria:<name> in Hermes