Agent Roles

July 22, 2026 · View on GitHub

Agent Roles is a host-neutral specification for packaging specialist AI agents as portable, mountable Roles.

A Role bundles everything a specialist agent needs — skills, memory, tool dependencies, plugin content, and host adapter metadata — into a single portable unit. It can be mounted into a target project's agent, then cleanly unmounted when no longer needed, without affecting the main environment, user global config, or other agents.

The specification is designed to push multi-agent collaboration toward clearer structure:

AudienceShift
DevelopersFrom building isolated skills to shipping complete Roles
UsersFrom managing scattered skills/plugins to managing roles

Languages: 简体中文 | 日本語 | 繁體中文 | 한국어 | More

Why Agent Roles

A specialist agent's content is typically scattered across multiple directories, config files, and runtimes:

  • System prompts
  • Skills pulled on demand
  • Project memory and long-term memory
  • Tool dependencies
  • Host-specific adapter configuration

Migrating means manually copying, installing, and debugging. Unmounting means guessing which files belong to the agent versus the main environment or other agents.

Agent Roles organizes all of this into a standardized Role format, so a specialist agent can be defined, distributed, mounted, and unmounted as a single independent unit.

Core Concepts

Role

A Role is the core object in Agent Roles — a complete specialist agent definition. It is not just a prompt and not just a skill collection; it is an encapsulation unit that carries its own capabilities, context, and adapter information.

Role Definition

A Role Definition is the manifest file for a Role. It describes the Role's responsibilities, required skills, tool dependencies, plugin content, host adapter configuration, and the rules for mounting and unmounting.

Each Role Definition carries Role revision metadata. version is the Role's own semantic version, separate from the agent-roles npm/PyPI package version. Published catalog Roles should also include created_at, updated_at, and a catalog level so users and hosts can compare Role revisions before installing, updating, or mounting them.

Host Adapter

A Host Adapter describes how a Role enters a specific host environment. The same Role can be read and mounted by multiple hosts. The Host Adapter captures the differences in directory layout, config format, tool entry points, and plugin projection for each host.

Package And Runtime Operations

OperationDescription
InstallCopy, validate, and record a Role in the local .roles/installed store without changing any project or host runtime
UpdateRefresh one already installed Role from its original source; it fails if the Role is not installed yet
UpgradeUser-facing alias for update; upgrade --all refreshes all installed Roles
MountAttach a Role to a target project by dynamically loading its contents via an index, establishing connections between the Role, the target project, and the host environment
UnmountDetach a Role from the target project; session files are retained as needed, all other content is cleared immediately, without affecting the main environment, user global config, or other agents

What a Role Can Carry

ContentDescription
role instructionsRole responsibilities, behavior boundaries, and working style
skillsCapability modules the role uses
memoryMemory or project context carried by the role
toolsCommands, scripts, or external tools the role depends on
pluginsPlugin content the role projects into the host environment
host adaptersAdapter metadata for different host environments
lifecycle rulesRules for handling mount, update, and unmount

Design Goals

  • Specialist agent roles can be clearly defined and independently distributed
  • Roles can migrate across projects, be mounted on demand, and be cleanly unmounted
  • Role content boundaries are explicit and do not interfere with the main environment or other agents
  • Provide a unified specification for CLI, role manager, and mount runtime

Published Roles

These are the currently published catalog Roles. Each entry is installable through agent-roles and may expose host-specific adapters.

agentroles.archi - Architecture Reviewer
  • Version: 0.5.0
  • Level: stable
  • Purpose: Reviews architecture drift, boundaries, topology, decisions, change impact, reliability tradeoffs, and structural risk without depending on one tool.
  • Best for: architecture reviews, dependency topology and cycles, module boundaries, architecture fitness functions, ADR drift, migration blast radius, distributed-system reliability tradeoffs, optional Architec/Hippo evidence, project-native architecture checks, vendored review skills, and practical next-step sequencing.
  • Contents: Role instructions, architecture review skills, evidence-map routing, focused topology/boundary/fitness/decision/impact/reliability methods, vendored public code-review skills, architecture toolbox and provenance references, live evaluation suite, reusable prompts, tool documentation, plugin content, and host adapters.
  • Adapters: CCB, Claude Code, Codex, HIVE.
  • Add: agent-roles add agentroles.archi
  • Update: agent-roles update agentroles.archi
  • Source: roles/archi
agentroles.coder - Coder
  • Version: 0.1.0
  • Level: experimental
  • Purpose: Implements focused code changes that match repository patterns, stay narrow in scope, and are backed by appropriate verification.
  • Best for: small feature work, bug fixes with proof, focused refactors, failing-test and CI fixes, test-backed implementation, large-file growth control, fallback discipline, repository style matching, and approval-gated dependency changes.
  • Contents: Coder memory, lightweight implementation skills, coding discipline and boundary references, reusable implementation templates, host adapter notes, and validation prompts.
  • Adapters: CCB, Claude Code, Codex, HIVE.
  • Add: agent-roles add coder
  • Update: agent-roles update coder
  • Source: roles/coder
agentroles.frontend_engineer - Frontend Design Engineer
  • Version: 0.3.0
  • Level: experimental
  • Purpose: Designs, implements, reviews, and validates production frontend interfaces with design-system, vendored UI/UX Pro Max intelligence, accessibility, browser QA, role-scoped runtime setup, optional private MCP tools, and reviewed AGY delegation.
  • Best for: frontend briefs, visual direction, design-token and component-system work, Figma-to-code flows, responsive accessibility checks, browser quality validation, role runtime setup checks, and reviewed Google Antigravity CLI (agy) delegation.
  • Contents: Frontend design-engineering memory, focused frontend skills, design-system and browser-quality references, MCP/AGY tool notes, role_setup runtime setup guidance, a role-scoped MCP/tool manifest, frontend MCP toolbox template content, host adapter notes, and validation prompts.
  • Adapters: CCB, Claude Code, Codex, HIVE.
  • Add: agent-roles add frontend
  • Update: agent-roles update frontend
  • Source: roles/frontend-engineer
agentroles.mobile_app_engineer - Mobile App Engineer
  • Version: 0.2.0
  • Level: experimental
  • Purpose: Designs, implements, reviews, validates, and virtual-device-tests production mobile apps across iOS, Android, React Native, Expo, Flutter, SwiftUI, and Jetpack Compose.
  • Best for: mobile app briefs, platform and stack selection, native-feeling flows, mobile component systems, icon/animation/material library curation, Android Emulator and iOS Simulator setup/control plans, simulator/device QA, accessibility, performance, and App Store or Google Play readiness.
  • Contents: Mobile app engineering memory, focused mobile skills, vendored UI/UX Pro Max design intelligence, virtual-device lab workflow, platform and stack references, public skill and asset-library catalog, quality/release guidance, reusable prompt, tool notes, host adapter notes, and validation notes.
  • Adapters: CCB, Claude Code, Codex, HIVE.
  • Add: agent-roles add mobile
  • Update: agent-roles update mobile
  • Source: roles/mobile-app-engineer
agentroles.mother - Role Mother
  • Version: 0.2.3
  • Level: preview
  • Purpose: Creates, researches, blueprints, ingests, and audits spec-compliant Agent Roles with evidence-backed gates.
  • Best for: drafting new Roles, auditing Role source, research briefs, candidate scorecards, blueprint gates, source-ingest copy-treatment decisions, checking catalog readiness, and researching skill-construction tools and techniques.
  • Skill research: Uses bounded public web research, preferring official docs and maintained examples, and records sources when research affects the design.
  • Contents: Role authoring memory, creation/audit, source-ingest, research, candidate-score, and blueprint skills, reusable prompts, skill-construction research reference, artifact templates, vendoring-aware preview schemas, local inventory script, validation notes, and host adapter display metadata.
  • Adapters: CCB, Claude Code, Codex, HIVE.
  • Add: agent-roles add mother
  • Update: agent-roles update mother
  • Source: roles/mother
agentroles.mobile_app_engineer - Mobile App Engineer
  • Version: 0.1.0
  • Level: experimental
  • Purpose: Designs, implements, reviews, and validates production mobile apps across iOS, Android, React Native, Expo, Flutter, SwiftUI, and Jetpack Compose.
  • Best for: mobile app briefs, platform and stack selection, native-feeling flows, mobile component systems, icon/animation/material library curation, simulator/device QA, accessibility, performance, and App Store or Google Play readiness.
  • Contents: Mobile app engineering memory, focused mobile skills, platform and stack references, public skill and asset-library catalog, quality/release guidance, reusable prompt, tool notes, host adapter notes, and validation notes.
  • Adapters: CCB, Claude Code, Codex, HIVE.
  • Add: agent-roles add mobile
  • Update: agent-roles update mobile
  • Source: roles/mobile-app-engineer
agentroles.su_ccb - SU-CCB Workflow Operator
  • Version: 0.1.0
  • Level: preview
  • Purpose: Packages the SU-CCB Claude coordinator workflow and Codex execution skills into one Role.
  • Best for: SU-CCB projects that need requirement analysis, technical design, task breakdown, dispatch, execution receipts, review gates, archive, status recovery, and reconciliation across Claude and Codex.
  • Contents: Claude-side coordinator skills, Codex-side executor/documentation skills, runtime helper library, SU-CCB kernel references, project templates, Claude plugin metadata, validation notes, and host adapter notes.
  • Adapters: CCB, Claude Code, Codex.
  • Add: agent-roles add su-ccb
  • Update: agent-roles update su-ccb
  • Source: roles/su-ccb

Package Manager Preview

This repository now includes a preview agent-roles package-management CLI. It is intentionally narrower than the future mount/unmount runtime: it focuses on role discovery, local installation, updates, sync, diagnostics, and machine-readable resolution.

Install the current public preview with npm:

npm install -g agent-roles
agent-roles --version

The npm package provides the agent-roles command through a Node wrapper that invokes the bundled Python module, so it requires Python 3.11+ on PATH. The PyPI package is prepared but still pending trusted-publishing completion; once it is live, pipx install agent-roles and pip install agent-roles will provide the same command and the agent_roles Python module.

The npm package does not bundle the installable roles/ catalog. Role catalog changes are published through the GitHub catalog, so adding or updating Roles does not require an agent-roles npm/PyPI package release. Use agent-roles list to discover available Roles from the configured catalog and agent-roles add <role> to add only the Roles you need. Role aliases such as archi resolve to their canonical catalog IDs, such as agentroles.archi.

Daily commands:

agent-roles list
agent-roles add frontend
agent-roles check frontend
agent-roles update archi

add installs Role source into the local .roles/installed store. check reports whether a Role is available and installed. update refreshes an already installed Role and will not silently install a missing Role.

Advanced compatibility commands:

agent-roles install archi
agent-roles install --all
agent-roles upgrade archi
agent-roles upgrade --all
agent-roles sync .
agent-roles doctor archi
agent-roles resolve archi

install and doctor remain stable compatibility names for scripts and Host Adapters; add and check are the simpler user-facing names. upgrade --all refreshes every installed Role, and install --all installs every currently discoverable catalog Role. Add --json when an adapter or automation flow needs machine-readable output; JSON includes the Role version, catalog_level, digest, update_reason, and available revision timestamps when the source Role provides them. Same-version content patches can be represented by digest changes without publishing a new agent-roles package version.

Role-private runtime setup should be exposed as one future setup or provider mount action, not as a nested tools install/doctor/uninstall command tree. Role-carried setup skills should use broad lifecycle names such as role_setup when they cover MCP, plugin projection, provider config, repair, or setup diagnostics. Role config uninstall should be owned by agent-roles or the Host Adapter layer, not by an in-agent setup script. Tool manifests remain declarations until a Host Adapter explicitly projects them.

For reusable MCP tools, the preferred model is provider-shared runtime plus project-private binding. A provider can install the MCP packages and wrapper commands once, then a lightweight project binding decides which Role tools are enabled for the current project and supplies project-specific values such as Figma frames, Storybook URLs, or local app URLs. When the provider supports it, one agent-roles bridge/router should be projected into provider config so new projects can reuse downloaded tools without globally exposing every Role tool.

By default, the CLI discovers Roles from the current catalog-like directory and from the public agent-roles-spec catalog cloned into ~/.roles/catalogs. Set AGENT_ROLES_STORE to choose a different store root, AGENT_ROLES_SPEC_HOME or AGENT_ROLES_CATALOG to point at local catalogs, and AGENT_ROLES_NO_REMOTE=1 to disable the default Git catalog.

The repo-local cli/agent-roles wrapper and python -m agent_roles run the same CLI module. Host adapters should consume the JSON output; live mount and unmount commands remain deferred until the Host Adapter contracts stabilize.

Current Status

The specification is in early design stage.

Current focus:

  • Role concept boundaries and Role Definition structure
  • How skills, memory, tools, and plugins are organized
  • How Host Adapters are expressed
  • Preview package-management CLI and .roles store behavior
  • Minimum behavioral constraints for mount / unmount

Upcoming: schema expansion, examples, role manager integration, and live mount/unmount runtime.

Adapter Roadmap

Host Adapter development will begin with these multi-agent projects:

Adapters for Claude Code, Codex, and other major hosts are also planned. We will actively work toward native Role format support across platforms.