ariffazil/Agent Onboarding

Agent Onboarding

Overview

When a new agent joins the federation, it needs an identity card, a home directory, and a registry entry. This skill ensures every agent is created with the same canonical structure and does not claim authority it does not own.

When to Use

• A new agent role is defined (e.g., "security-auditor")
• An existing agent is being refactored or renamed
• Quarterly agent registry audit

When NOT to Use

• Do not use to create agents that duplicate existing roles
• Do not use to grant constitutional authority (888_JUDGE, 999_VAULT) — those are arifOS organs
• Do not use without verifying the agent name is unique across the federation

Inputs

| Input | Required | Description | |-------|----------|-------------| | agent_id | yes | Unique kebab-case ID (e.g., security-auditor) | | agent_name | yes | Human-readable name | | agent_role | yes | One of: operator, engineer, auditor, witness, planner | | domain_plane | yes | One of: AAA, A-FORGE, GEOX, WEALTH, WELL, arifOS | | allowed_tools | no | Array of tool IDs this agent may use | | allowed_skills | no | Array of skill IDs this agent may load |

Procedure

Step 1: Validate Uniqueness

Check that agent_id does not already exist in:

• registries/agents.yaml
• a2a/registry/agents.yaml
• Any agents/<existing-id>/ directory

If duplicate → reject and suggest alternative ID.

Step 2: Create Agent Identity Directory

Create agents/<agent_id>/ with these required files:

agents/<agent_id>/
├── IDENTITY.md       # Who this agent is
├── SOUL.md           # Personality and behavior contract
├── AGENTS.md         # Agent-specific instructions
├── MEMORY.md         # Memory and context rules
├── TOOLS.md          # Allowed tools and boundaries
├── BOOTSTRAP.md      # Boot sequence
├── HEARTBEAT.md      # Health check protocol
├── USER.md           # Sovereign reference (Arif)
└── agent-card.json   # A2A capability card

Contents must include:

• Clear statement of subordination to arifOS
• Explicit boundary: "This agent does NOT render constitutional verdicts"
• Escalation path to arifOS 888_JUDGE for dangerous actions
• Escalation path to Arif for irreversible actions

Step 3: Create A2A Agent Card

Create a2a/agent-cards/<agent_id>.json with:

• agent_id, name, description
• capabilities array
• endpoints object
• auth_required: true

Step 4: Register in AAA Registry

Add entry to registries/agents.yaml:

- id: <agent_id>
  name: <agent_name>
  role: <agent_role>
  domain_plane: <domain_plane>
  host_binding: <host>
  allowed_tools: <allowed_tools>
  allowed_skills: <allowed_skills>
  allowed_peers: []
  intelligence_band: <band>
  intelligence_tier: <tier>
  separation_of_duties:
    cannot_self_seal: true  # engineers must set this

Step 5: Register in A2A Registry

Add entry to a2a/registry/agents.yaml:

- agent_id: <agent_id>
  card_path: a2a/agent-cards/<agent_id>.json
  status: active
  trust_tier: standard

Step 6: Validate

Run npm run validate:aaa to ensure:

• Agent ID is unique
• Card file exists
• Registry cross-references are valid
• No workflow references are broken

Allowed Tools

| Tool | Purpose | |------|---------| | file-write | Create identity files | | directory-create | Create agent directory | | registry-update | Add registry entries |

Forbidden Actions

• NEVER assign role: judge — only arifOS APEX can judge
• NEVER assign role: sovereign — only Arif is sovereign
• NEVER set cannot_self_seal: false for engineer agents
• NEVER skip the validation step

Output Format

## Skill Result: agent-onboarding

### Summary
Agent `<agent_id>` onboarded successfully.

### Files Created
- `agents/<agent_id>/IDENTITY.md`
- `agents/<agent_id>/SOUL.md`
- ...
- `a2a/agent-cards/<agent_id>.json`

### Registry Entries
- `registries/agents.yaml`
- `a2a/registry/agents.yaml`

### Validation
- [x] `npm run validate:aaa` passes

### Escalations
- None / [list]

Escalation Path

| Condition | Escalate To | Method | |-----------|-------------|--------| | Validation fails | AAA agent | Fix and re-run | | Duplicate agent ID found | Arif | Human decision on naming | | Agent requests judge role | arifOS 888_JUDGE | Reject + education |

---

Skill version 1.0.0 — AAA Skill Library