Omh Agent Instructions

Agent Instructions

This is a Hermes-native agent-instructions workflow skill.

Why This Exists

agent-instructions exists because the file every handoff target reads first had no owner: rules-distill extracts rule candidates, codebase-onboarding builds a human reading path, and context aligns terminology, and each reads that file without writing it.

First Steps

• List every instruction file and which agent reads it before proposing a section.
• Run or ask for the observed run of each command before marking it verified.

Do Not Use When

• The ask is distilling repeated lessons into reviewed rule candidates; use rules-distill.
• The ask is a reading path through the codebase for a new engineer; use codebase-onboarding.
• The ask is project terminology alignment -- reviewing the terms this project uses and correcting inconsistent vocabulary; use context.
• The ask is user-facing product documentation; use product-docs.

Examples

Good example:

• Prompt: update our CLAUDE.md
• Expected behavior: Inventory the instruction files, run or collect each build and test command, mark each verified or unverified, and replace only the marked region with the commands, the generated-file map, the gates, and the costed pitfalls, refusing any count or line number.
• Why: An instruction file that states an unrun command or a stale count sends every later agent the wrong way.

Bad example:

• Prompt: add that the suite has 4,100 tests and the router is at line 212 of chat.py
• Expected behavior: Refuse both values, and write the command that counts the tests and the symbol that locates the router instead.
• Why: Both numbers were already wrong by the next merge.

Completion Checklist

• Every instruction file and its reader are listed.
• Every command is marked verified with an observed run, or unverified.
• Only the marked region changed, and hand-written text is byte-for-byte.
• No count, line number, or value the code already states was written.
• Every generated file names its source, its regenerate command, and its gate.

Recovery Notes

• If a command cannot be run here, write it marked unverified with what would verify it.
• If the file has no markers, insert them once around the new section and leave everything else untouched.

Workflow Lane

• Current lane: Coding handoff (idea-to-deploy, llm-app-dev, cto-loop, deploy-and-monitor, code-review, build-failure-triage, verification-gate, security-safety-review, +28 more) - coding owners, handoffs, review, CI, and merge evidence.
• If intent belongs to another lane, hand back to oh-my-hermes or name the adjacent workflow.
• Shared product, routing, compatibility, and evidence rules: omh-routing/references/skill-common-rail.md.

Use When

Use when the repository's agent instruction file is being written or kept current: AGENTS.md, CLAUDE.md, GEMINI.md, a Cursor rule, or a Copilot instructions file. The output is the build and test commands each marked verified or unverified, the generated-file map with its regenerate command and gate, the byte-exact gates, and the pitfalls that cost time, written inside a marker-delimited region so hand-written sections survive.

Strong routing signals: `agent-instructions`, `agents.md`, `claude.md`, `gemini.md`, `copilot-instructions.md`, `.cursorrules`, `cursor rules`, `cursor rule`, `agent instruction file`, `agent instructions file`, `instructions file for agents`, `set up agents.md`, `update our claude.md`, `write an agents.md`

Catalog Metadata

Category: planning Phase: agent-instructions Hermes role: planner Quality tier: verified-command-and-region-gated Reasoning demand: standard

Quality bar:

• Inventory every instruction file first and respect closest-file-wins nesting.
• Load references/instruction-file-method.md for the section order, the marker convention, the verified and unverified command form, and the drift rules instead of recalling them.
• Record each pitfall with what it cost, so a reader can tell a scar from a preference.
• Pair every generated file with its source, its regenerate command, and the gate that checks it.
• Keep prepared, verified, and written as separate states for every command and section.

Handoff policy:

Keep the section plan, the command verification record, and the region update in Hermes. Every command's outcome is recorded only from executor, operator, or wrapper observed output; the file is written by the executor, and only inside its marked region.

Required inputs:

• which instruction files exist, where they sit, and which agents read them
• the build, test, lint, and regenerate commands the repository uses
• which files are generated, from what source, and which gate checks them
• the pitfalls that have cost time, each with what it cost
• observed output for every command written into the file