Create Custom Agents with Specific Authority Boundaries in AIOX

You create custom agents in AIOX by copying a base template to .aiox-core/development/agents/, editing the YAML front-matter to define identity and permitted operations, and configuring the security block with allowed_operations to enforce runtime boundaries.

AIOX treats every agent as a declarative YAML document, making it simple to create custom agents with specific authority boundaries without modifying core framework code. By storing agent definitions as static markdown files under .aiox-core/development/agents/, you can version-control both agent capabilities and security constraints alongside your codebase. This guide walks through the exact file paths and YAML structures used in the SynkraAI/aiox-core repository to define authority limits that the runtime enforces at execution time.

Understanding AIOX Authority Layers

AIOX enforces two complementary layers of authority to prevent unauthorized operations. The delegation matrix defines high-level exclusive operations (like git push or gh pr create) reserved for specific built-in agents, residing in .claude/rules/agent-authority.md. The security block provides per-agent authorization through allowed_operations that you declare in the agent's YAML front-matter, using the schema defined in .claude/templates/agent-template.yaml.

When an agent executes a command, the dispatcher in src/agents/dispatcher.ts verifies the command exists in the agent's commands list, checks against security.allowed_operations, and validates it doesn't violate the delegation matrix. Commands reserved exclusively for another agent are rejected unless @aiox-master grants a temporary override.

Step-by-Step Guide to Creating Custom Agents

Copy the Base Agent Template

Start by duplicating the generic development agent to create your custom agent file:

cp .aiox-core/development/agents/dev.md .aiox-core/development/agents/my-agent.md

This base template contains the YAML skeleton used by the runtime parser when loading agents at startup.

Define Identity and Persona

Edit the YAML front-matter in your new file to establish the agent's identity. According to the template structure in .claude/templates/agent-template.yaml, modify fields like name, id, title, icon, and persona:

agent:
  name: Analyst
  id: analyst
  title: Business Analyst
  icon: 📊
persona:
  role: Business Analyst & Requirements Specialist
  style: Concise, data-driven

The id field must be unique across your agent directory, as it determines the slash command name (e.g., /analyst).

Configure Security Boundaries

Add a security block to constrain what operations the agent can perform. Following the schema in lines 74–81 of .claude/templates/agent-template.yaml, specify authorization (for documentation) and allowed_operations (enforced by the runtime):

security:
  authorization: "read-only"
  allowed_operations:
    - git status
    - git fetch
    - db query
    - code search
  audit_logging: true

Setting audit_logging: true enables automatic recording of every command execution to .ai/decision-log-{story}.md. The framework only enforces the allowed_operations list; the authorization label serves documentation purposes.

Register with Your IDE

After saving your agent file, register it with your development environment using the AIOX CLI from bin/aiox.js:

npx aiox-core install --ide claude-code

The installer scans .aiox-core/development/agents/ and creates slash-command entries under .claude/commands/AIOX/agents/, making your custom agent available as /my-agent in the IDE chat interface.

Code Examples

Minimal Read-Only Analyst Agent

Create .aiox-core/development/agents/analyst.md with this complete YAML front-matter:

agent:
  name: Analyst
  id: analyst
  title: Business Analyst
  icon: 📊
persona:
  role: Business Analyst & Requirements Specialist
  style: Concise, data-driven
security:
  authorization: "analysis"
  allowed_operations:
    - code search
    - db query
    - git status
    - git fetch
  audit_logging: true
commands:
  - name: help
    visibility: [full, quick, key]
    description: "Show available commands"
  - name: search-requirements
    visibility: [full]
    description: "Search codebase for requirement patterns"

This configuration restricts the analyst to read-only operations while allowing codebase queries.

Extending the Delegation Matrix for Exclusive Operations

If your agent requires exclusive rights to sensitive operations, edit .claude/rules/agent-authority.md to add a new delegation section. Only @aiox-master can grant these exclusive permissions:

### @deployment (Nova) — EXCLUSIVE Authority

| Operation                | Exclusive? | Other Agents |
|--------------------------|------------|--------------|
| `deploy production`      | YES        | BLOCKED      |
| `rollback production`    | YES        | BLOCKED      |

Once committed, only an agent with id: deployment can execute these commands. Other agents attempting deploy production receive a "blocked by authority matrix" error.

Testing Authority Enforcement

After registration, test your agent's boundaries in the IDE:

/analyst
📊 Analyst (Business Analyst & Requirements Specialist) ready.

Available Commands:
 *help                – Show all commands
 *search-requirements – Search codebase for requirement patterns

> *search-requirements "authentication flow"
[✅] Ran allowed operation: code search

> *git push
[❌] Blocked: git push is exclusive to @devops (see Agent Authority rules)

The runtime validates every command against both the allowed_operations list and the delegation matrix before execution.

Summary

• AIOX agents are declarative YAML files stored in .aiox-core/development/agents/ that require no code changes to create.
• Authority uses two layers: the delegation matrix in .claude/rules/agent-authority.md for exclusive operations, and per-agent security.allowed_operations for runtime enforcement.
• Security blocks use the schema from .claude/templates/agent-template.yaml to define permitted operations and enable audit logging.
• Registration happens via npx aiox-core install --ide claude-code, which creates IDE-specific slash commands.
• Runtime enforcement occurs in the dispatcher, which rejects unauthorized commands before execution.

Frequently Asked Questions

What file format does AIOX use for agent definitions?

AIOX stores agent definitions as markdown files with YAML front-matter located in .aiox-core/development/agents/. The runtime parses the YAML block between triple backticks at load time, extracting the agent, persona, security, and commands sections. This static file approach maintains the framework's "No Invention" principle by keeping agent definitions as configuration rather than code.

Can I override an exclusive operation assigned to another agent?

Only the @aiox-master agent can override exclusive authority restrictions defined in the delegation matrix. The core dispatcher in src/agents/dispatcher.ts checks the matrix before execution, and if a command is marked as exclusive to another agent ID, it rejects the request unless the requesting agent has master override privileges. Regular custom agents cannot bypass these boundaries through their individual security blocks.

Where does AIOX log agent command executions?

When you set audit_logging: true in the security block, AIOX writes every command execution to .ai/decision-log-{story}.md using the built-in audit hook. This creates a permanent record of what operations each agent performed, satisfying compliance requirements while debugging authority boundary violations. The log path includes the story ID to organize audits by workflow context.

Why are my agent changes not showing up in the IDE?

You must run the installer command npx aiox-core install --ide claude-code (or your specific IDE flag) after creating or modifying agent files. The installer scans .aiox-core/development/agents/ and regenerates the slash-command mappings in .claude/commands/AIOX/agents/. Without this registration step, the IDE doesn't know to expose your new agent as a chat command, even though the YAML file exists in the agents directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}