How to use Hermes as an external engineer

Hermes is an external engineer, not a supported woostack host or installed woostack runtime. Install woostack in OMP or another supported coding harness. Hermes may coordinate decisions and review evidence, but it must not edit implementation source or replace repository evidence.

Before you start

You need:

• an approved bounded task;
• an isolated worktree for that task;
• an interactive OMP profile with woostack installed; and
• an argument-safe process or PTY interface that keeps a process handle.

The OMP session owns the worktree, implementation, worker routing, and focused verification. Hermes owns the contract boundary and reviews the returned evidence.

1. Start one persistent OMP session

Drive one persistent OMP session per live interaction. Keep one OMP process identity for each active bounded interaction. Do not switch processes during a live interaction.

Pass the profile, working directory, and initial prompt as separate argument values. Confirm the installed CLI flags with omp --help. For current OMP releases:

omp --profile <profile> --cwd <worktree> <prompt>

Do not add -p or --print. Those flags select non-interactive mode and exit after one response. If the process interface cannot set a working directory, put the canonical worktree path in the prompt and require OMP to verify it before reading or writing. Stop on a profile, working directory, repository, branch, head, or allowed-path mismatch.

2. Keep using the same process

Retain the interactive process handle. Send every correction and responsible-user response as new input through that handle. Do not interpolate task, artifact, issue, or user-response prose into a shell command.

The same process must remain attached to the same isolated worktree during retries, approval relay, and bounded redispatch.

3. Keep decisions inside the approved contract

Hermes may interpret the approved contract, inspect OMP's diff and command results, review the evidence, accept an in-contract result, or request one bounded correction. It may not expand scope, edit source, run implementation commands, commit, push, open a pull request, or infer missing context.

OMP workers return observations, changes, commands, results, and blockers. Hermes reviews that evidence independently. Missing, contradictory, or stale evidence stops the interaction.

4. Escalate contract changes

Send any new path, changed acceptance criterion, unresolved decision, or out-of-contract question to the responsible user. Keep OMP at the last verified boundary while waiting. A user question is not implicit approval.

5. Relay the user's response verbatim

When OMP presents an Ask during an active conversation, only the responsible user's live response may decide it. Relay that response verbatim and unmodified through the same OMP process that presented the Ask. Do not summarize, rewrite, splice, or replay it.

A provider record, status, assignment, label, cached transcript, or Hermes-authored message is not a decision. If the process restarts during the active conversation, present a fresh Ask, obtain a fresh response, and continue through that new process.

6. Review evidence before accepting or redispatching

Check the exact worktree, branch and head, changed paths, complete diff, commands, observed results, focused verification, and blockers. Compare them with the approved contract and acceptance criteria.

If the evidence is complete and in contract, accept the result or send one bounded correction through the same process and worktree. Read the complete evidence again after a correction. Do not silently change the profile, worktree, process, or contract.

Git, Graphite, and GitHub remain authoritative for source, ancestry, commits, pull requests, reviews, and merges. Hermes acceptance is not source-control evidence.

7. Resume a retained run later

Build and project-backed Fix retain project-spec.md, execution-plan.md, and the run manifest under .woostack/tmp/runs/<run-id>/. A later OMP process may resume unchanged approved artifacts with:

/woostack-execute --run <exact-run-id> [--recheck]

This cross-session resume path validates the retained run. It does not permit process switching during an active conversation or reuse of a previous live response.

8. Clean up legacy launchers when safe

Clean up is optional and manual. Legacy installations may contain host-owned launch-omp or bind-engineer-unit files. Verify that no active session or recovery path depends on them, preserve needed evidence, and remove only the files the owner selects. Woostack does not install, invoke, repair, or delete those launchers.