Stop. Read this section before doing anything. This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like "This pull request is slop that's made of lies." Your job is to protect your human partner from that outcome. Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human…
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available
Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
Applies on top of the root AGENTS.md (prompt-caching invariant, facade + siblings rules). runagent.py is the public facade: AIAgent is assembled from mixins (agent/turnfacade.py, clientlifecycle.py, streamdelivery.py, sessionpersistence.py, compressionfacade.py, ...). Construction runs agent/agentinit.py::initagent; a turn is agent/conversationloop.py::runconversation, which AIAgent.runconversation forwards to after taking the session turn lease (turnfacadelease.py). AIAgent.init_ takes ~60 parameters (credentials, routing, callbacks, session context, budget, credential pool, ...) — read runagent.py for the list; the subset you usually touch: baseurl, apikey, provider, apimode ("chatcompletions" | "codexresponses" | ...),…
Instructions for AI coding assistants and developers working on the hermes-agent codebase. This root file holds only what applies everywhere. Each area has its own AGENTS.md (aim for ~8k chars; agent/subdirectory_hints.py delivers up to 32k and truncates head/tail with a warning past that); see the routing table at the end and read the area file before editing in that area. Never give up on the right solution. Hermes is a personal AI agent that runs the same agent core across…
Applies on top of the root AGENTS.md. Long-form: website/docs/developer-guide/cron-internals.md; user docs website/docs/user-guide/features/cron.md, kanban.md. cron/jobs.py (job store) + cron/scheduler.py (tick loop; scheduler_*.py siblings). Agents schedule via the cronjob tool; users via hermes cron list|add|edit|pause|resume|run|remove or /cron. Schedules: duration ("30m", "2h", "1d"), "every" phrase ("every 2h", "every monday 9am"), 5-field cron ("0 9 * * *"), ISO one-shot ("2026-06-01T09:00:00Z"). Per-job fields: skills, model/provider overrides, script (pre-run data-collection script whose stdout is injected into the prompt; noagent=True makes the script the whole job),…
Applies on top of the root AGENTS.md. Long-form: website/docs/developer-guide/gateway-internals.md. New platform adapter: follow gateway/platforms/ADDINGAPLATFORM.md step by step. gateway/run.py is the facade; phases live in run_.py (startup, adapters, inbound, turn, busy, goals, notifications, shutdown, ...), sessions in session.py, slash handlers in slashcommands*.py mixins, authorization in authzmixin.py, adapters in platforms/<name>.py over platforms/base.py. builtinhooks/ is the extension point for always-registered gateway hooks (none shipped). The gateway reads user YAML raw (run.py + config.py), not through DEFAULTCONFIG — a key the CLI sees but…
Plain text files in a repository that tell a coding agent how the project works: commands to run, conventions to follow and things to avoid. CLAUDE.md, AGENTS.md, cursor rules and skills are the common kinds.
CLAUDE.md or AGENTS.md?
CLAUDE.md is read by Claude Code. AGENTS.md is an open format that Codex, Cursor and other agents read. Many projects keep one and point the other at it.
What is a skill?
A folder with a SKILL.md that describes one capability, such as filling PDFs or reviewing code. The agent loads it only when the task calls for it.
Can I search my own team's files too?
Your agents already can, over MCP, limited to the files you're allowed to read. Searching them from this page is coming.
obraAGENTS.md