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 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" | ...),…
Applies on top of the root AGENTS.md. Authoring guide + canonical compat contract: website/docs/developer-guide/plugins/index.md. Per-kind guides: memory-provider-plugin.md, model-provider-plugin.md, context-engine-plugin.md, image-gen-provider-plugin.md, ... Plugins live in their own directory and work within the ABCs / hooks / ctx surface we provide. A plugin MUST NOT modify runagent.py, cli.py, gateway/run.py, hermescli/main.py, etc. If it needs a capability the framework lacks, widen the generic plugin surface (new hook, new ctx method) and have the plugin use it — never hardcode plugin-specific logic into core…
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
