Swarm Hierarchy

Divisions have been retired. Clawpy now uses a flattened hierarchy where all agents live directly inside a SwarmSpace and coordinate through role tiers + explicit reporting lines.

Current Model (Flattened)

Workspace
  └── SwarmSpace (named environment, e.g., "Production")
        └── CEO (Lucius)
              ├── Senior Leaders (CTO / COO / CMO / CFO ...)
              │     └── Leaders
              │           └── Workers
              │                 └── Junior Workers

No division buckets. No per-division ownership boundaries. Authority and routing are determined by tier + reports_to relationships.

Level Definitions

Layer	Entity	Purpose
Workspace	Tenant container	Top-level isolation boundary per customer.
SwarmSpace	Runtime environment	Named operating context (e.g., Production, Staging).
Role Tier	CEO / Senior Leader / Leader / Worker / Junior Worker	Determines decision scope, model routing, and escalation authority.
Agent	Individual runtime	Executes tasks and reports up the chain through `reports_to`.

What Changed

Previous (Retired)	Current
Division-based grouping	Flat SwarmSpace membership
Division heads as hard boundaries	Tier-based leadership chain
Group-level allocation model	SwarmSpace + tier/agent budgeting
Division CRUD lifecycle	Agent-centric lifecycle (hire, assign, report, escalate)

Reporting Chain

Every agent still carries an explicit reporting link in comms.json:

{
  "reports_to": "cto",
  "reports_to_role": "Senior Leader",
  "team": "platform-core"
}

This chain powers:

Escalation routing (worker -> leader -> senior leader -> CEO)
Wisdom Cascade propagation
Leadership-aware context injection

Budget Governance (Post-Division)

Budgets are no longer partitioned by divisions. Governance is applied through workspace, swarmspace, and agent/tier controls:

Workspace budget: $50/month
  └── SwarmSpace budget: $40/month
        ├── CEO cap: $10/month
        ├── Senior Leader pool: $12/month
        ├── Leader pool: $8/month
        └── Worker + Junior pool: $10/month

If one agent exceeds limits, only that agent (or its scoped pool) is paused. The rest of the swarm can continue operating.

Operational Notes

Hiring and staffing remain hierarchy-aware, but not division-aware.
Org charts now visualize reporting lines and tiers, not departmental silos.
Swarm recommendations should be interpreted as role distribution, not division count.