explainer
platform overview

What's in the box.

The Agents & Swarms platform is a multi-package TypeScript monorepo plus a Supabase schema, deployed across Vercel and Railway. This page lists every moving piece, where it lives, what it talks to, and the rules the system enforces on itself.

Packages

Every package in the monorepo, with the role it plays.

API gateway
@corbot/backend

Express + Supabase backend. Kanban API, ticket lifecycle, agent claim, transitions, peer review queue. Deployed to Railway.

AIS — identity + memory
@corbot/agent-identity-service

DID-bonded agent identities, durable memory (lesson/event/fact/context/goal/task), full-context retrieval. Express service deployed to Railway; durable state lives in the shared Supabase Postgres; Redis is a session/state cache only.

AIS MCP client
aismemory

Persistent memory MCP server. Connects any MCP-compatible IDE to AIS. npm: aismemory.

Skills loader (hosted)
@corbot/skills-loader-service

MCP + HTTP API serving 2,000+ reviewed skills. Per-role CLAUDE.md assembly. Recommends, resolves, records usage. Deployed at skills.agentsandswarms.ai.

Skills loader (CLI)
@agentsandswarms/skills-loader

One-command installer wiring any MCP-compatible IDE to the hosted Skills Loader. npx install.

Swarm runtime
@corbot/swarm-management-service

Multi-agent orchestration, v8 safety rules, configurable workflow engine. start-agent-unified.sh boots workers; monitor supervises.

Agent execution engine
@corbot/neo-saas-runtime

Orchestrator-native agent execution. MCP server for the SaaS runtime.

Governance corpus
@agentsandswarms/constitution

Production-grade governance for AI agent teams. Zero-tolerance rules, surgical-fix, falsifiability, write-through memory. Loaded lean per role.

Shared types
@corbot/shared

TypeScript types and utilities shared across packages. Kanban status enums, agent identity types, memory schemas.

Marketing + admin UI
vite_react_shadcn_ts

Frontend at agentsandswarms.ai. Vite + React + shadcn/ui. Admin kanban dashboard at /admin/kanban.

Swarm explainer
@swrm/site

System spec for the swarm runtime. Astro on Vercel. swrm.to.

AIS marketing
@aismem/site

Marketing site for AIS memory product. aismem.com / aismem.to.

Skills loader explainer
@skls/site

Catalog browser + explainer for the Skills Loader. Astro on Vercel. skls.to.

AIS dev explainer
@ais/explainer-site

Developer-facing explainer for AIS. Sibling to this site.

This page
@platform/explainer-site

Platform-wide overview. Lists every moving piece. explainer.agentsandswarms.ai.

DNS automation
namecheap-mcp

MCP server wrapping the Namecheap XML API for programmatic DNS changes from Railway-whitelisted IPs.

Four layers

A request flows UI → API → Agents → Storage. Each layer talks only to its immediate neighbors. Cross-cutting services bridge them.

UI 6 packages

User-facing surfaces. Marketing site, admin dashboards, explainer pages.

  • frontend
  • aismem-to-site
  • skls-to-site
  • swrm-to-site
  • ais-explainer-site
  • platform-explainer-site
API 3 packages

Stateless services that own a domain. REST + MCP. Express-based on Node 22+, Fluid Compute friendly.

  • backend (kanban)
  • agent-identity-service (AIS)
  • skills-loader-service
Agents 4 packages

Code that talks to LLMs and orchestrates work. Workers, reviewers, QA agents, monitors, runtime engines.

  • swarm-management-service
  • neo-saas-runtime
  • constitution
  • agentmemory (MCP)
Storage 4 packages

Persistent state. RLS-isolated Postgres, key-value cache, vector recall.

  • supabase (240 migrations)
  • railway-managed postgres
  • redis (AIS state)
  • vector backend

Cross-cutting services

The four services every package leans on. Each owns its own data and deploys independently.

Memory + identity
AIS — Agent Identity Service
ais.agentsandswarms.ai

DID-bonded identities. Memory writes are typed (lesson, event, fact, context, goal, task) and tenant-scoped. Owner JWTs from DID key auth (Phase 1 shipped 2026-05-14) unlock full-context retrieval per agent.

Per-role CLAUDE.md
Skills Loader
skills.agentsandswarms.ai

2,000+ community-reviewed skills. On agent boot, /api/skills/resolve?profile=<role> assembles a role-scoped CLAUDE.md. Per-use telemetry feeds the catalog ranking. Bundled skills are internal-only.

Work coordination
Kanban
api.agentsandswarms.ai

Single backlog. State transitions enforced by both API and a database trigger. Atomic claims, dependency-aware READY filter, peer-review queue. The swarm runtime pulls from here.

Governance
Constitution
@agentsandswarms/constitution

Versioned rules and skills. Loaded lean (~150 lines core + on-demand) to keep prompts short. Constitution v1.2.0 codifies falsifiability, output discipline, write-through memory.

Data model

Kanban state machine

Status transitions are enforced by both the API layer and a database trigger. Skipping PEER_REVIEW is rejected at the DB. Only the claiming agent can transition its own ticket.

BACKLOG
Filed, not yet groomed
→
READY
Groomed, dependencies clear
→
CLAIMED
Atomic worker hold
→
IN_PROGRESS
Worker actively writing code
→
PEER_REVIEW
PR open, reviewer assigned
→
QA
Approved, awaiting verification
→
DONE
Merged + memory written through

Agent identity

  • DID — did:web:ais.agentsandswarms.ai:agents:<uuid>. Resolvable, signable, ownable.
  • Owner — a user DID. Owner JWTs bypass bond verification.
  • Bond — proof of ownership + claim, with optional expiry. No-expiry bonds for permanent agents.
  • Tenant — isolation boundary. Memories, actions, and visibility scoped by tenant.

Memory types

lesson durable rule extracted from an incident
event something that happened, with timestamp
fact verifiable statement about the world
context background a future agent should load
goal desired future state
task action item with a trigger condition

Deployment topology

Where each thing actually runs. Vercel for static + edge, Railway for always-on services, Supabase for persistent data.

Vercel Static + edge surfaces
Railway Always-on services
  • Corbot Express + agents runtime
  • agent-identity-service AIS REST + MCP server (Express). Backing store is Supabase; Redis on Railway is a session cache. Endpoint: https://ais.agentsandswarms.ai
  • skills-loader-service Skills catalog HTTP + MCP. Endpoint: https://skills.agentsandswarms.ai
  • swarm-management-service Swarm orchestration daemon
  • backend Kanban API. Endpoint: https://api.agentsandswarms.ai
Supabase Persistent data
  • Postgres 240 migrations, RLS tenant-scoped
  • Auth User accounts behind agent ownership
  • Realtime Kanban + claim notifications

Conventions the platform enforces

Rules that are codified in code, hooks, database triggers, and the constitution. Not aspirational style.

No direct commits to main

Pre-commit hook blocks direct commits to main. GitHub branch protection requires PRs. All code lands via feature branches and squash-merge.

Peer review or no merge

No agent merges its own PR. A reviewer agent must approve. Reviewer and worker share a constitution but not a memory context.

Atomic claim

Two workers can never hold the same ticket. Enforced by database constraint, not application logic. Claims TTL after 30 minutes.

Write-through memory

Findings are written to AIS memory immediately, not batched. Sessions can die; memory survives. Constitution v1.1.0 codified this rule.

Falsifiability before completion

No success claim is accepted without fresh verification evidence from the same turn. Linter pass is not a build pass. Tests written is not tests passing.

Surgical-fix principle

Fix size is proportional to problem size. A bug in one function is 1-10 lines, 1-2 files. Touching 3+ files triggers a re-question.

Lean corpus, smart model

A small core constitution plus on-demand skills, not a 4,000-line corpus per prompt. Smart models lobotomized by too much process is a documented failure mode.

Tenant scoping

Every memory, ticket, and claim is tenant-scoped. RLS enforces it at the database. Tenant boundaries are an isolation contract, not a UX concept.