Skip to main content

Agent Taxonomy

This is the single basis the platform's brain speaks on. Every expert agent is decomposed by the principle below, and every new agent is checked against this roster before it is authored. The goal is granularity with relevant expertise — many focused specialists, loaded only when a task actually touches their surface, never a few monolithic generalists.

It supersedes the earlier 16-agent roster that was derived from agents-developer-kit (which we no longer use as a source — see Sourcing). This roster is derived from a scan of the real bewith-dev GitHub org (≈60 repos), not from a template.

The decomposition principle​

Agents fall on two axes, plus an orthogonal group:

  • Vertical implementers — "who writes the code in this surface/runtime." Bound to a technology surface (NestJS, React/Next, Flutter, Yii2, the design-system package, infrastructure). They implement.
  • Horizontal specialists — "what specialized knowledge applies across surfaces." Cross-cutting expertise (auth, data, payments, notifications, observability, i18n, …). They advise and own a boundary; any vertical calls them.
  • Orthogonal gate / design / product agents — the lifecycle agents that are not tied to a surface or a domain (architect, code-reviewer, process-guardian, prd-writer, gatekeeper, product-manager).

This mirrors Team Topologies: vertical implementers are stream-aligned (deliver in a surface), horizontal specialists are enabling/platform (cross-cutting depth), and the boundaries between them are DDD bounded contexts.

When a concern earns its own agent​

A concern becomes its own agent (not a rule inside another agent, not a skill) when both hold:

  1. Distinct body of knowledge — a different human specialist would own it (a security engineer ≠ a backend dev ≠ a DBA ≠ an SRE). The depth justifies its own 15–25 KB context.
  2. Cross-cutting reuse OR independent trigger — it applies across multiple surfaces (so baking it into one implementer would force duplication in the others), OR a policy/workflow invokes it independently.

It stays a rule inside an agent (or a skill the agent calls) when it is specific to one surface and lacks the depth to warrant a separate context.

Why fine granularity is safe here​

The usual objection to many agents — "a single task would load eight of them and blow the context budget" — does not apply, because loading is lazy and policy-driven. At /continue step 4 the Policy Engine matches the files in play; step 5 (via agent-guard) loads only the agents those policies require. A pure backend task loads backend-developer; the moment it touches auth, auth-security joins; a schema change pulls database. You never pay for granularity you do not use — which is exactly why fine decomposition is correct, not wasteful.

Sourcing​

When authoring any agent, the source hierarchy is:

  1. Anthropic sub-agent conventions — the form (_template.md, 7 sections, frontmatter).
  2. Platform needs end-to-end — derived from the real codebase across the whole bewith-dev org.
  3. Own engineering judgment — build it as it should be.
  4. cursor-rules — a non-binding reference. Mine it per-agent for good rules to merge in; do not treat it as ground truth, do not copy wholesale. (Real value already found there: MobX observer patterns, .styles.ts convention, RTL/Hebrew handling via stylis-plugin-rtl, WCAG-AA + MUI-palette a11y, strict-equality lint.)
  5. Other resources — fill gaps.
  6. Decomposition — split out anything that crept in by mistake.

agents-developer-kit is ignored (Aviad's call — generic/outdated). Gali's three laws (API-first, observability, activation) are aspirational, not implemented reality: author toward a similar result, but map what is when scanning.

The real landscape (what the org actually runs)​

Grounding for the roster (from the org scan, 2026-06-01):

  • Backend: NestJS monorepo (backend-services, 20+ apps) — Mongoose and TypeORM; MongoDB (primary) + Aurora/MySQL + Redis + S3 + OpenSearch; @MessagePattern RPC; @nestjs/schedule cron. Plus sqs-consumer, migrations-tool.
  • Frontend (web): React/Next.js family — organization-dashboard (Next SSR, community managers), management-webapp (Next, internal), bewith-consumer-frontend (Next 15 App Router + Zustand + Tailwind + next-intl), facility-rentals, support-tool-frontend (CRA). MUI + Emotion, MobX (dashboards) / Zustand (consumer), i18next/next-intl, RTL. Plus Angular 8 (superco-management) and embedded widgets (with-calendar, grids) served via iframe inside the PHP consumer.
  • Mobile: Flutter/Dart — leaders-app (GetX, SSE notifications, region-aware) and consumer-mobile (Provider/Riverpod). No BFF — both hit backend-services /api/v2 directly.
  • Legacy: Yii2 PHP (superco-consumer, superco-management backend) — Twilio, yii2-queue, ActiveRecord migrations.
  • Design system: @bewith-dev/design-system — Storybook, 40+ MUI components, tokens, Tiptap, an AIChatBox, MCP-UI.
  • Infra: EKS primary (Terraform EKS module + Pulumi + Helm + ArgoCD GitOps), ECS secondary (CDK); GitHub Actions; GHCR/ECR base images. (Note: ADR-001 names ECS Fargate primary — that record looks superseded by the EKS move; flagged for a separate ADR.)
  • Auth: Cognito passwordless — custom Lambda triggers (create/define/verify challenge), email/SMS OTP, JWT refresh; client SDK amazon-cognito-identity-js.
  • AI/LLM (production, small share): apps/assistant-ai (Anthropic + OpenAI), apps/vector-search (OpenSearch vectors + Voyage embeddings + tiktoken), with-agents (Strands multi-agent: orchestrator/query-builder/summarizer/visualizer), with-agents-platform (Python/FastAPI/Bedrock).
  • Payments: Stripe + Payme (apps/payments).
  • Notifications: sqs-consumer hub — 9 SQS queues, multi-channel (SES email, Vonage/Smsim SMS, Meta WhatsApp, Bulldog in-app), campaigns, OTP, retries.
  • Observability: vendor-neutral — Grafana Loki + CloudWatch + Winston structured logging. Datadog is being dropped — define obs generically.
  • Integrations: Monday.com CRM (crm-integration, Python/Flask), Meta/WhatsApp BSP, webhooks.
  • Tooling: custom @bewith-dev/eslint-plugin (15 rules, BE + FE).

The roster​

Group 0 — Gate / Design / Product (orthogonal; mostly exist)​

AgentOwnsStatus
architectDesign authority, ADR judgment✅ shipped
code-reviewerPre-PR ten-point review✅ shipped
process-guardianDefinition of Done (closure gate)✅ shipped
prd-writerProduces PRDs✅ shipped
gatekeeperReadiness gates (PRD + Design Doc)✅ shipped
product-managerSpec quality + prioritizationplanned

Group 1 — Vertical implementers (by surface)​

AgentSurfaceNotes
backend-developerNestJS (backend-services + microservice apps)Controller/service/repository; defers every cross-cutting boundary below
frontend-developerReact + Next.js family (org-dash SSR, management, consumer, facility, support-tool)MUI/Emotion/Tailwind, MobX + Zustand, hooks, SSR/SPA/App-Router modes
frontend-angularAngular 8 (superco-management)DEPRECATION TARGET — no new features; smallest-safe-change only. New UI is built as React components and embedded via iframe (the embed rule below), not added to Angular.
mobile-developerFlutter/Dart (leaders-app, consumer-mobile)GetX / Provider / Riverpod; consumes the shared API (no BFF)
design-system@bewith-dev/design-systemTokens, components, Storybook, RTL/theme; SoT all web frontends consume
devops-infraTerraform + Pulumi + Helm + ArgoCD + CDKEKS primary, ECS secondary; CI/CD; base images
legacy-php-guideYii2 (superco-consumer, superco-management BE)DEPRECATION TARGET — no new features; smallest-safe-change only; auth/payments → human review. New UI is built as React and mounted via iframe (the embed rule below), not added to PHP.

Group 2 — Horizontal specialists (cross-cutting; lazy-loaded)​

AgentDomainKey surface
auth-securityCognito passwordless (Lambda triggers, OTP), JWT, RBAC, OWASPmandatory on any auth touch
databaseMongo (Mongoose) + Aurora/MySQL (TypeORM) + Redis + migrationsone DBA persona, cross-store consistency
contracts-schemaFE↔BE + inter-service contractsin flight
ai-llmLLM providers (Bedrock/Anthropic/OpenAI), prompts, agent orchestration (Strands)assistant-ai, with-agents*
search-vectorOpenSearch full-text + vector; embeddings (Voyage); RAGapps/vector-search
async-messagingSQS, @MessagePattern RPC, cron, event-driven, idempotencythe eventing backbone
notificationsMulti-channel delivery (SES/Vonage/Smsim/Meta/Bulldog), campaigns, OTPsqs-consumer hub
paymentsStripe + Payme; refunds, withdrawalshigh-stakes (money)
observabilityVendor-neutral logs/metrics/traces (Loki/CloudWatch/Winston)post-Datadog
qa-engineerVitest/Jest, Playwright E2E, Testcontainers, coverageall surfaces
i18n-localizationi18next/next-intl, he/en, RTL (stylis-plugin-rtl)all frontends
privacy-complianceGDPR + Israeli Privacy Law, PII, retentiondata-handling changes
integrations3rd-party/CRM (Monday.com), webhooks, BSPinbound/outbound integration discipline

Group 3 — Stays a rule or skill (NOT an agent)​

ConcernFormWhy not an agent
a11y (WCAG AA, RTL)skill a11y-review + rule in frontend-developer/design-systema procedure + invariant, not a standalone persona
performancechecklist/rule in backend-developer + frontend-developera cross-cutting checklist, surface-applied
styling (focus/motion/z-index)rule in frontend-developer/design-systemsingle-surface
coding-standards@bewith-dev/eslint-plugin + global rulealready enforced by tooling
realtime (WebSockets/SSE)rule/section in backend-developer + relevant frontend/mobilethin; revisit if depth grows
embedded widgets (React in PHP via iframe)shared rule: frontend-developer builds the embeddable bundle, legacy-php-guide mounts the iframe; the embed contract (bundle format, postMessage, sizing, token) is the rule both referencea delivery pattern across two surfaces, not a distinct body of knowledge — holds while the consumer is PHP + iframe (OQ-2)
domain skills to promote from cursor-rulesskills: a11y-review, obs-logs (generalized from datadog-logs), i18next-translation, permissions-demo-tokens, identify-bug, mermaid-diagrams, coderabbit-implementreusable procedures, agent-agnostic

Build sequence — by impact × criticality​

Everything is being authored within ~24–48h; this is the order, not a gate.

  • Wave 0 — ground the existing (do first): correctness/grounding pass on the already-shipped agents (architect, code-reviewer, process-guardian) + the artifacts we created — fix stale references and any agents-developer-kit-flavored content, so we do not keep revisiting them (OQ-3).
  • Wave A — core (every task depends on these): backend-developer, database, auth-security, contracts-schema (in flight), frontend-developer. (Gate/design agents already shipped.)
  • Wave B — high-impact subsystems: payments (money), notifications (huge subsystem), async-messaging (backbone), qa-engineer, observability.
  • Wave C — broad coverage: i18n-localization, devops-infra, privacy-compliance, design-system.
  • Wave D — smaller share, still soon: ai-llm, search-vector, mobile-developer, frontend-angular, legacy-php-guide, integrations. (embedded-widgets resolved to a shared rule, not an agent — OQ-2.)

Ownership boundaries (who defers to whom)​

The vertical implementers defer every cross-cutting boundary to its horizontal owner — this is what keeps each agent focused and prevents one bloated generalist:

  • backend-developer defers → database (schema/migrations), contracts-schema (DTO shape), auth-security (any auth), async-messaging (queue/RPC patterns), notifications (delivery), payments (money), search-vector (indexing), ai-llm (LLM), observability (logs/metrics), qa-engineer (test strategy).
  • frontend-developer defers → design-system (components/tokens), i18n-localization (strings/RTL), contracts-schema (the API it consumes), a11y-review skill, qa-engineer.
  • mobile-developer / frontend-angular defer to the same horizontals as frontend-developer, minus design-system specifics.

A horizontal specialist never implements a feature end-to-end; it owns its boundary and hands the implementation back to the vertical.

Maintenance​

  • Adding an agent? Check it against the decomposition rule first. If it fails either test, it is a rule or a skill, not an agent.
  • Splitting an existing agent? Justify with the same rule — distinct body of knowledge and cross-cutting/independent-trigger. "It feels big" is not enough.
  • This document is the reference the new-artifact skill consults when someone proposes a new agent.

See also​