Imported from serverlessclaw/serverlessclaw (docs/intelligence/AGENTS.md). Install upstream with npx skills add serverlessclaw/serverlessclaw --skill intelligence. Copyright stays with the author.

Agent Registry & Roles

Navigation: ← Index Hub

This document serves as the central registry for both autonomous agents and system handlers. It defines their roles, hosting tiers, and the process for expanding the swarm.

🤖 Agent Roster

We distinguish between Autonomous Agents (LLM-powered decision-makers) and System Handlers (deterministic logic for monitoring and recovery).

1. Autonomous Agents (LLM-Powered)

Agent	Host (Tier)	Responsibilities
SuperClaw	`Standard`	Nimble Orchestrator. See `packages/core/agents/superclaw.ts` and `constants.ts`.
Coder Agent	`High-Power`	Writes code, validates deployments, and enforces concrete evolution delivery artifacts (`patch` or `buildId`) plus acknowledged execution handoffs for autonomous runs. When a gap-scoped run succeeds without returning an artifact, the handler also attempts a direct git patch recovery from the prepared workspace before failing the evolution. See `packages/core/agents/coder.ts`.
Researcher	`High-Power`	Deep exploration. See RESEARCH.md & `packages/core/agents/researcher.ts`.
Strategic Planner	`High-Power`	Technical Auditor. Plans capability work, hard-fails coder dispatch errors, and keeps single-gap auto-evolution plans intact unless explicit structured subtasks are provided. See `packages/core/agents/strategic-planner.ts`.
QA Auditor	`Standard`	Verifies changes. See `packages/core/agents/qa.ts`.
Facilitator	`Standard`	Session Moderator. See `packages/core/agents/facilitator.ts`.
Merger	`Standard`	Code Integration. See `packages/core/agents/merger.ts`.
Critic	`Standard`	Logic Oversight. See `packages/core/agents/critic.ts`.
Cognition Reflector	`Light`	Knowledge Custodian. See `packages/core/agents/cognition-reflector.ts`.
Mission Orchestrator	`Core`	Durable Planning. Manages high-level intents and multi-step missions. See `packages/core/lib/agent/mission-orchestrator.ts`.

2. System Handlers (Logic-Powered)

Component	Trigger	Responsibilities
Build Monitor	CodeBuild Event	Observes builds, updates gap status, circuit breaking.
Recovery Handler	Health Failure	Automated rollback orchestration. See RESILIENCE.md.
Event Handler	AgentBus Event	Routes system signals and manages recursion depth.
Real-time Bridge	AgentBus Event	Bridges signals to AWS IoT (MQTT). See DASHBOARD.md.

🦾 The Backbone Registry

The system identity is defined in packages/core/lib/backbone.ts. Centralized registry acts as the "genetic code" of the stack.

Topology vs. Permissions

Topology Connectivity: Declared in backbone.ts for visualization in the System Pulse dashboard sector.
IAM Permissions: Managed in infra/agents.ts via the link property. This is the hard security layer.

[!WARNING] Visualizing a connection in the dashboard does NOT grant AWS permissions. You must modify infra/agents.ts to grant actual resource access.

🛠️ Adding a New Agent

To evolve the system with a new specialized node:

Implement: Create packages/core/agents/<name>.ts (or packages/core/agents/<name>/index.ts) with agent logic and tools. Modular constants should go in packages/core/agents/<name>/constants.ts.
Register Identity: Add the agent to BACKBONE_REGISTRY in packages/core/lib/backbone.ts.
Link Infra: In infra/agents.ts, create the Lambda and link necessary resources.
Subscribe: Ensure the agent is subscribed to its task type in the EventBus.
Cognitive Resilience: Autonomous agents will automatically receive the Environmental Constraints feed (from SystemContext) via the AgentAssembler. Ensure your agent logic can reason about available package.json dependencies.

🔄 Session Promotion Flow (Diagram A)

Agents can transition from a private 1:1 session to a multi-agent Collaboration Hub. This is typically triggered when a task requires specialized peer review or a human invites more help.

    [ 1:1 SESSION ]             [ TRIGGER ]             [ COLLABORATION HUB ]
(Human <-> SuperClaw)      (Invite Agent / Gap)     (Multi-Agent / Shared)
          |                         |                        |
          |---- (1) Incubation ---->|                        |
          |                         |                        |
          |                         |--- (2) Promo Action -->|
          |                         |   (transitToCollab)    |
          |                         |                        |
          |                         |                        |---- (3) Seeding ---+
          |                         |                        |  (History Summary) |
          v                         v                        v                    |
    [ ARCHIVED ]              [ LOG RECORDED ]          [ ACTIVE HUB ]  <---------+
                                                     (Facilitator joins)

Collaboration Lifecycle

Incubation: A task starts as a direct interaction with the system orchestrator (SuperClaw).
Promotion: A strategic gap or a manual human request triggers a "Promotion to Collaboration."
Execution: Multiple sub-agents (Critics, Coders) join the shared session. The Facilitator moderates.
Conclusion: The Owner agent summarizes the verdict, executes the action, and archives the hub.

🧪 Testing Agent Interfaces

To ensure coordination doesn't break, follow a Contract-First pattern:

Define Schema: Update packages/core/lib/schema/events.ts with any new event types.
Standard Defaults: Leverage BASE_EVENT_SCHEMA for shared metadata.
Interactive Signaling: Ensure the agent supports APPROVE_TOOL_CALL, REJECT_TOOL_CALL, and CLARIFY_TOOL_CALL signals via its executor.
Contract Test: Add a test case to packages/core/tests/contract.test.ts and verify signal interception in packages/core/lib/agent/executor.test.ts.

🛰️ Tactical Feedback Loop

Agents provide real-time visibility into their progress via the Mission Control interface. This is achieved by emitting structured signals during execution:

Mission Briefing Updates: Agents emit MISSION_STATUS and PHASE_TRANSITION signals to update the left-hand Mission Briefing sidebar (e.g., Analysis -> Deployment).
HUD Telemetry: Performance metrics (Trust, Stability, Budget) are derived from the Usage and CognitiveHealth signals emitted at the end of each reasoning turn.
Thought Streaming: Intermediate reasoning steps are published to the TEXT_MESSAGE_CONTENT stream, providing the human with a "monologue" of the agent's internal logic.

📥 Related Documentation

SWARM.md: Orchestration, mission decomposition, and parallel dispatch.
RESEARCH.md: Specialized research agent workflows.
COLLABORATION.md: Multi-human workspaces and moderated sessions.
STANDARDS.md: Engineering standards for agent and human contributors.

intelligence

About