# Behavioral roles > Behavioral roles are versioned rule-sets from the roles catalog that make an agent work like a named professional: ordered task flows, hard constraints, an output contract and quality gates. Attach them to a config on Govern → Roles and layer your own overlay rules. They are not model roles, which bind a model to each engine role. As of September 25, 2026, OpenEng AI isn't live yet. A **behavioral role** is a versioned rule-set that makes an execution component — an agent, a delegator, a sub-delegator or a sub-agent — *work like* a named professional: a Security Auditor, a Technical Writer, an SRE. It gives the component an ordered task flow, hard constraints, an output contract and quality gates. You attach roles from the catalog to a config on **Govern → Roles** and can layer your own rules on top. > [!WARNING] Status on September 25, 2026: OpenEng AI isn't live yet > The Console and Web Console interfaces load, but the OpenEng AI API routes and the Broker aren't > deployed. Nothing can be saved or published, and no AI engine can register or connect. Pro, > Enterprise and pay-as-you-go launch in Q4 2026 and can't be purchased yet. This page describes > OpenEng AI as it works once those services are live ([status](ai.md)). > [!NOTE] Not the same as model roles > **Model roles** (agent, planner, reviewer, summarizer and the rest) decide > *which model* serves each part of the engine; you bind them on > [Models](models.md#role-models) and in a > config's Models step. **Behavioral roles** decide *how* a component works, > whatever model it runs on. That's why the Console's page lives at > `/role-rules` and the catalog ids start with `role_def_`. The > [glossary](glossary.md#model-role-behavioral-role) compares the two. *Figure: Govern → Roles — pick a config, attach base rule-sets from the roles catalog, layer your own overlays, and read the effective order the engine applies.* ## What a role contains Each catalog role (`role_def_`, versioned with SemVer) carries: | Part | What it is | |---|---| | **Task flow** | Ordered steps; a step can be marked parallelizable or as a gate | | **Constraints** | Hard rules the component must keep | | **Output contract** | What the result must look like | | **Quality gates** | Checks the result must pass | | **Prompt overlay** | Short guidance text added to the component's prompt | | **Components** | Which components may take the role (agent, delegator, subDelegator, subAgent) | | **Capability requirements** | What the component must be able to do: coding, planning, review, summarization, docResearch, codeResearch, document, image, audio, video | | **Tool affinity** | Hints about useful tools, never grants | The first constraint of every role is the platform's security-floor line. A role can steer how a component works but never widen what it may do: tool grants come only from the engine's gateway, never from role text. ## The catalog The catalog is published at **[roles.openeng.app](https://roles.openeng.app)**, where each role also has a long-form brief. As of 2026-09-25 it holds **1,524 roles** in 19 categories: Artist / Designer, Coder, Data Analyst, Data Engineer, Delegator, DevOps Engineer, Document Writer, Image Generator, ML/AI Engineer, Product / Planner, QA / Test Engineer, Researcher, Reviewer / Critic, Security Auditor, SRE / Incident Responder, Sub-Delegator, Summary Writer, Technical Writer, and Video / Media Producer. How catalog ids and `@` pins work is on [Catalogs](catalogs.md#ids). ## The Roles page Everything on the page is scoped to one config, chosen in the **config picker** at the top right. The heading tells you where that config stands: **Enforced since v1.2.0** when what you see is published, or a **Draft — not published** chip with a **Publish the config to enforce** link when you've changed something since. The page has two tabs. ### Attachments **Attach role…** opens the catalog browser. Each card shows the role's name, id, version, category, the components it can bind to, its capability requirements and its description; **View details** shows its brief as plain text, and **Attach to config** adds it. Attaching **freezes** the role's full definition into the config at that moment, recorded as `role_def_@`. The catalog never changes an attached role behind your back: when the catalog has a newer version, the row says so (*Catalog has 1.2.0 — re-attach and publish to adopt*). Each attachment row shows the role, its id, the frozen version, its target and its order, with chips for **disabled**, **Draft — not published** and an overlay if it has one. **Enable** / **Disable**, **Detach** and **Delete** act on it. At the bottom, **Effective order** is the read-only list the engine applies: base rule-sets and their overlays in ascending order. Disabled entries never apply. ### Overlays An overlay is your own layer on an attachment, with an id of the form `role_usr_`. Overlays **sharpen only**: they add rules and can never remove the base role's. An overlay has: - **Target** — which boundary binds the rule-set. **Agent** (with the agent's name or id) is the live path; `any` also works, and the other kinds shown are reserved for later. - **Component** — which execution component takes the role; it must be one the base role allows. - **Order** — its place in the ordered table. - **Prompt overlay** — up to 4,000 characters of extra guidance, fenced as untrusted text when it reaches the prompt. - **Overlay rules** — added flow steps, constraints, quality gates or an output contract. - **Placeholders** — named values, each a `${ENV_VAR}` placeholder, never a literal. Use **Move up** / **Move down** on the Overlays tab to change the order. ## Use roles in a config Attachments belong to the config you picked on this page; publish the config to make them part of the served version. The config builder also has a **Roles** step that picks from your own rule-sets ([Configs](configs.md#components)). On a machine, the engine takes the attached rule-sets from the published config itself: the full definitions travel frozen inside it, so the engine never fetches the catalog to apply them. The engine also keeps the whole catalog as a signed pack from releases.openeng.app, verified against its signature before use, and can shortlist roles from it for the steps of a planned run; when a config picks roles in its Roles step, only those are considered. Release builds of the engine apply behavioral roles by default. Setting `OPENENG_ROLE_RULES=off` on a machine turns them off there; `assign` lets the engine pick roles without applying their rules. ## Plan & tier notes Behavioral roles are a **Pro and Enterprise** feature. On Free, the page explains what they do in place of its content, and publishing a config with an enabled role attachment is refused; the same attachment disabled still publishes. Pro and Enterprise launch in Q4 2026 and can't be purchased yet ([Plans & billing](account.md#ai-pricing)). ## Troubleshooting **A Draft — not published chip won't go away.** The page shows the config's saved draft; publish the config and the chip clears. **A role doesn't pick up a catalog update.** By design: attachments are frozen. Re-attach the role and publish. **"No roles in the catalog".** The browser couldn't load roles.openeng.app. Try again later; attachments you already have are unaffected. **Publishing is refused with a plan limit.** The config has an enabled role attachment and the account is on Free. Disable the attachment to publish. **A placeholder is refused.** Placeholder values must look like `${UPPER_CASE_NAME}`.