Agent Archetypes

Every agent in Clawpy is assigned an archetype — a classification that determines its capabilities, model routing, tool access, and tier in the wisdom hierarchy. Archetypes are resolved through the Archetype Registry (archetype_registry.py, 26,223 bytes), which maps archetype keys to specific LLM models, token budgets, and behavioural policies.

Core Archetypes

The Architect

Designs system specifications and handles high-level structural planning. The Architect analyses requirements, proposes solutions, and creates technical blueprints before any code is written.

Tier: 3 (Junior Leader) Best for: System design, architecture decisions, project planning, specification writing.

The Builder

Translates specifications into clean, functional code. The Builder works from the Architect's plans and focuses on implementation quality, testing, and documentation.

Tier: 4 (Worker) or 3 (Senior/Lead) Best for: Code generation, feature implementation, test writing, refactoring.

The Implementor

Executes deep operational tasks, deployment scripts, and terminal commands. The Implementor handles the hands-on work of shipping — CI/CD pipelines, server configuration, and infrastructure management.

Tier: 4 (Worker) Best for: DevOps, deployment, shell scripting, infrastructure automation.

The Auditor

Reviews work produced by other agents. The Auditor validates code quality, checks for security issues, and ensures outputs meet the original specification. The Auditor holds veto power over deployments.

Tier: 3 (Junior Leader) Best for: Code review, security auditing, quality assurance, compliance checking.

The CEO (Lucius)

The top-level strategic agent. Manages the overall swarm, delegates work to division heads, and makes architectural decisions.

Tier: 1 (Core Identity) Model routing: Uses the most capable available model.

Alfred (Butler)

The operator's personal assistant. Maintains a personal relationship with the user, handles general queries, and provides dashboard-integrated help.

Tier: 1 (Core Identity) Memory: Isolated butler memory with 3-year retention and forgetting curve.

Archetype Classification

The Archetype Classifier (archetype_classifier.py, 21,540 bytes) determines an agent's archetype during provisioning. Resolution follows a priority chain:

Explicit assignment in tools.json → archetype_key
Classifier analysis of the agent's soul.md, role description, and tool permissions
Default fallback to allother_worker (Tier 4)

Archetype Key → Tier Mapping

Tier 1:  assistant_butler, ceo_senior
Tier 2:  builder_senior, director1_exec, director2_exec,
         director3_exec, director4_exec, director5_exec,
         director6_exec
Tier 3:  junior_manager, builderf_senior, builderb_senior,
         auto_research
Tier 4:  builderf_worker, builderb_worker, allother_worker
Tier 5:  builderf_junior, builderb_junior, allother_junior

Model Routing

Each archetype resolves to a specific LLM model through the Archetype Registry. This enables cost-efficient routing — senior agents use powerful models while junior workers use cheaper ones:

Tier	Typical Model	Reasoning
1 (Core Identity)	Best available (e.g., Claude Opus, GPT-4o)	Strategic decisions require maximum capability
2 (Senior Exec)	High-capability (e.g., Claude Sonnet, GPT-4o)	Leadership needs strong reasoning
3 (Junior Leader)	Mid-tier (e.g., GPT-4o-mini, Claude Haiku)	Competent but cost-effective
4-5 (Workers)	Economy (e.g., GPT-4o-mini, Deepseek)	High throughput, low cost

This tiered routing can save 50-80% on API costs compared to using the same high-end model for all agents.

How Agents Collaborate

When you send a task through the operator chat, the swarm conductor analyses your request and decides which agents to involve:

Complex tasks may start with the Architect for planning, then move to the Builder for implementation, and finish with the Auditor for review.
Simple tasks may go directly to a single agent.
Agents can delegate sub-tasks to each other when they encounter work outside their specialisation.

All collaboration happens through the Agent Communication Protocol (ACP), which provides a traceable message bus between agents. See Communication Protocol for details.

Custom Archetypes

You can create custom agent archetypes by defining a soul.md that specifies:

The agent's role and personality
Which tools it can access
Its memory retention policy
Budget and rate limits

The Archetype Classifier will analyse the soul.md content and assign an appropriate tier, or you can override the classification explicitly in tools.json.