Authoring agents

~26 expert agents form the platform's roster (reconciled to agent-taxonomy.md, ADR-002 — the source of truth). Each is a single markdown file under .claude/agents/, sized 15–25 KB, written in the canonical template (the agent template). The Policy Engine loads them lazily at step 5 of /continue based on the matched policies' required_agents clauses — see policy-engine.md and ai-engineering-strategy.md §12.

This page is the authoring guide. The live roster renders at the Agents landing (auto-generated from the agent files); the agent template is the shape to copy.

How agent files work in Claude Code

Claude Code reads agent files from .claude/agents/<name>.md (project) and ~/.claude/agents/<name>.md (user). The frontmatter is parsed; the body becomes the agent's custom system prompt when the auto-router or an explicit @agent-<name> invocation activates it. Reference: Anthropic sub-agents docs.

Each BeWith agent uses these frontmatter fields:

• name (required) — kebab-case, matches filename.
• description (required) — what the agent owns and when it's invoked. Includes "use proactively" when auto-routing is desired (Anthropic's documented pattern).
• tools (recommended) — restrictive allowlist. Most BeWith reviewer/gatekeeper agents are limited to Read, Grep, Glob, Bash so they can inspect but not modify; implementer agents inherit all tools.
• model: inherit (recommended) — follow the session's model unless there's a reason to override.

Status

#	Agent	Status	Owns	Tools	Source for content
1	process-guardian	written	Definition-of-Done gate before any task closes	Read, Grep, Glob, Bash	AI_GOVERNANCE/workflows/definition-of-done.md
2	code-reviewer	written	Ten-point pre-PR review; loaded automatically before PR open	Read, Grep, Glob, Bash	agents-developer-kit/agents/CODE_REVIEWER.md (1322 lines)
3	architect	written	Design authority — microservice boundaries, RPC vs HTTP, DB choice, code archaeology, legacy boundary, ADR-vs-design-doc judgment	Read, Grep, Glob, WebFetch, Write	agents-developer-kit/agents/ARCHITECT.md (1155 lines, distilled)
4	backend-developer	written	NestJS implementer (backend-services monorepo) — controller/service/repository in the existing pattern; follows @bewith-dev/eslint-plugin rules; defers data/contracts/auth/messaging/payments/search/AI/obs to their owners.	inherit all	org scan of backend-services + @bewith-dev/eslint-plugin rules
5	frontend-developer	written	React + Next implementer — dashboards (Next+MobX+MUI/Emotion) and consumer (Next15+Zustand+Tailwind+next-intl); rhf+Zod, TanStack Query, RTL/a11y. Assembles from the DS; defers components/i18n/contract/a11y to owners.	inherit all	org scan of the web frontends + @bewith-dev/eslint-plugin FE rules
6	qa-engineer	written	Testing authority across all levels — Jest (+ @nestjs/testing, supertest), mongodb-memory-server (in-memory Mongo) / Testcontainers for integration, Playwright e2e; owns strategy + coverage, implementers write unit tests.	inherit all	org scan (real stack is Jest, not Vitest)
7	product-manager	written	Product judgment — is this worth building, business/ICP-aligned, and what's the priority (owns prioritization between unrelated features). Owns the AI-consumable PRD→Design Doc chain. Distinct from gatekeeper (readiness).	Read, Grep, Glob, WebFetch, Write	product-rd-handoff + docs/company + Gali
8	design-system	written	Owns @bewith-dev/design-system — tokens (palette.ts), ~40 MUI components, Storybook, RTL/theme, the COMPONENTS.md catalog (PRD §7.2 anchors to it), changesets. The shared UI SoT.	inherit all	org scan: @bewith-dev/design-system repo
9	database	written	One DBA persona — schema design + migrations (via migrations-tool) + indexing + query perf + cross-store consistency across Mongo (Mongoose), Aurora/MySQL (TypeORM), Redis. OpenSearch is search-vector's.	inherit all	org scan of libs/schemas + migrations-tool CLI
10	devops-infra	written	EKS primary (Terraform EKS + Pulumi + Helm + ArgoCD GitOps), ECS secondary (CDK); GitHub Actions CI/CD; ECR/GHCR base images; Secrets Manager; multi-region; the shared CI hard-gate.	inherit all	org scan: IAC-Terraform, Kubernetes-deployments, cdk-infra
11	auth-security	written	Auth + security authority — Cognito passwordless (OTP Lambda triggers), JWT (aws-jwt-verify), RBAC (org/community/resident), OWASP, secrets. Mandatory on any auth touch; designs+reviews, hands impl to backend-developer.	Read, Grep, Glob, Bash	org scan: cognito-lambdas + apps/auth/apps/authorization
12	privacy-compliance	written	GDPR + Israeli Privacy Law — PII classification, minimization, lawful basis/consent, retention, user rights (erasure cascade incl. Cognito), no PII in logs/3rd-party, cross-border. Advises; escalates real legal Qs.	Read, Grep, Glob	standard content + bewith data context
13	contracts-schema	written	FE↔BE + inter-service contract oversight — classifies additive/breaking, scans all repos for consumers + updates them (frontends hand-roll Zod, v3/v4 drift), defines contracts up-front against the real DTO. No codegen (Aviad).	Read, Grep, Glob, Bash, Edit, Write	contracts-schema audit
14	observability	written	Vendor-neutral logs + metrics + traces + dashboards + alerts (Grafana Loki + CloudWatch + Winston). Defines what to emit + post-deploy watch; implementers add lines. Datadog being dropped — no vendor coupling.	Read, Grep, Glob, Bash	org scan: Winston + loki-cloudwatch-forwarder
15	i18n-localization	written	i18n + RTL authority — i18next/next-i18next/next-intl (per app), he/en locale files, camelCase keys + namespaces + typed resources, RTL via stylis-plugin-rtl, useAppData→useTranslation migration.	Read, Grep, Glob, Edit, Bash	org scan + cursor-rules i18n conventions
16	legacy-php-guide	written	Yii2/PHP (superco-consumer, superco-management BE) — DEPRECATION TARGET: bug fixes / smallest-safe-change, NO new features (→ NestJS / React-in-iframe); auth/payments → human review. PHP = separate PHPCS/PHPStan track.	Read, Grep, Glob, Bash	org scan: superco-consumer
17	prd-writer	written	Produces PRDs that R&D reads (audience: product). Fills the PRD template, anchors UI to COMPONENTS.md, self-checks Definition of Ready, hands to gatekeeper. WHAT/WHY only, never HOW.	Read, Grep, Glob, WebFetch, Write	docs/templates/prd.md + docs/methodology/product-rd-handoff.md (PR #44)
18	gatekeeper	written	Dual-mode readiness gate (audience: both). Mode A: PRD Definition of Ready before draft → ready-for-rd. Mode B: Design Doc readiness before draft → approved. Independent binary block on any P0 gap; the pre-build twin of process-guardian.	Read, Grep, Glob	docs/templates/prd.md + docs/templates/design-doc.md + closed v1 (PR #43)
19	payments	written	Money authority — Stripe + Payme; charges/refunds/withdrawals, idempotency, webhooks, reconciliation, no raw card data. Mandatory on money touches; designs+reviews, hands plumbing to backend-developer.	Read, Grep, Glob, Bash	org scan: apps/payments (Stripe ^9.4.0 + Payme + withdrawals)
20	notifications	written	Multi-channel delivery (SES/Vonage/Smsim/Meta WhatsApp/Bulldog), campaigns, OTP, channel routing+fallback, idempotent send, status/retries, opt-out. Owns delivery; rides async-messaging; content→i18n.	Read, Grep, Glob, Bash	org scan: sqs-consumer notification hub
21	async-messaging	written	Eventing backbone — SQS, @MessagePattern RPC, cron, idempotency, at-least-once+DLQ, outbox, ordering. Defines delivery semantics; backend-developer wires handlers.	Read, Grep, Glob, Bash	org scan: sqs-consumer 9-queue hub + RPC
22	ai-llm	written	LLM authority — provider abstraction (Bedrock/Anthropic/OpenAI), prompt engineering + structured output, Strands multi-agent orchestration (bounded), tiktoken/cost, grounding. Defers retrieval to search-vector.	Read, Grep, Glob, Bash	org scan: apps/assistant-ai, with-agents*
23	search-vector	written	OpenSearch full-text + vector, Voyage embeddings, index mappings (he/en analyzers), relevance, freshness, query-time scoping, RAG retrieval. Pairs with ai-llm (retrieve vs generate).	Read, Grep, Glob, Bash	org scan: apps/vector-search
24	integrations	written	External-system boundary — inbound/outbound webhooks (verify+idempotent), CRM sync (Monday.com field-mapping), BSP/Meta connectors, outbound resilience. Defers delivery→async-messaging, PII→privacy-compliance.	Read, Grep, Glob, Bash	org scan: crm-integration + BSP
25	mobile-developer	written	Flutter/Dart (leaders-app GetX/SSE/region-aware · consumer-mobile Provider-Riverpod/Dio/Firebase-off); consumes shared /api/v2 (no BFF), JWT+refresh, offline states, he/en, store release.	inherit all	org scan: real Flutter repos
26	frontend-angular	written	Angular 8 (superco-management) — DEPRECATION TARGET: bug fixes / smallest-safe-change only, NO new features (new UI = React via iframe). ng-zorro/Material/RxJS era patterns.	Read, Grep, Glob, Bash, Edit	org scan: superco-management

The roster above is reconciled to docs/methodology/agent-taxonomy.md (ADR-002), which is the source of truth for the decomposition principle, ownership boundaries, and impact-ordered build sequence. Rows flip planned → written as each agent ships. (frontend-developer row 5 covers the React/Next family; embedded-widgets is a shared rule, not an agent — OQ-2.)

Sequencing rationale

The order above is sized by load-bearing first. Agents the Policy Engine fires automatically for every relevant change come first:

• process-guardian — runs at /done on every closing task. Smallest scope. Written first as the test of the template.
• code-reviewer — runs before every PR open. Highest call frequency in the whole roster.
• architect — runs on every design-affecting change. Sets the bar for "do we know what we're building."
• backend-developer / frontend-developer — pair-load on most implementation tasks.
• qa-engineer — runs whenever behavioral code changes.

The domain specialists (rows 8–16) come after the load-bearing five because they load only when the Policy Engine's triggers match their narrower scope.

Roster changes (2026-05-27/28):

• Removed team-leader — no cross-team / stage-approval reality for a single-developer team. Priority decisions between unrelated tasks moved to product-manager.
• Removed decision-recorder as an agent — replaced by an /adr skill plus a rule carried by architect and product-manager. Mechanical ADR creation is a procedure, not a judgment role.
• Added design-system — consolidates UX, component library, and Storybook conventions under one owner (per the consolidate-by-default heuristic).
• Added privacy-compliance — GDPR and Israeli Privacy Law coverage that no existing agent held.
• Added contracts-schema — active oversight of FE↔BE and inter-service contract discipline. Scope finalised with Aviad: no codegen, no version standardization; the agent scans all repos and updates consumers on breaking changes.

Conventions for adding an agent

1. Read the agent template first. The seven body sections — Role → When invoked → Checklist → Output format → Handoff points → Cross-references → Anti-patterns — are the writing convention. Frontmatter is enforced by Claude Code.
2. Pick a kebab-case name. It becomes the filename and the name: frontmatter field. Both must match.
3. Write the description: for routing. Include "use proactively" if you want auto-delegation. Mention specific trigger context (when to load, what stack/files).
4. Pick tools: deliberately. A reviewer/gatekeeper should not have Edit/Write. An implementer needs all default tools.
5. Source the body. Most agents have an existing source (see Source column). The rewrite is to the BeWith template, not from scratch — preserve the domain content; normalize the structure.
6. Reflect the actual BeWith projects. Reference real repos (backend-services, management-webapp, consumer-php-base, etc.), real commands (pnpm lint, composer test), real validators (scripts/checks/check-cu-id.sh), real env vars (REQUIRE_CU_ID in git-hooks/config.env). Generic agents that could apply anywhere are weaker than specific ones that name the platform.
7. Size discipline. Target 15–25 KB. If you blow past 30 KB, ask whether a sibling skill or a sub-doc could carry weight.
8. Add a row above with the new file linked and Status flipped to written.
9. Cross-reference forward. Section 6 of the template links every agent this one hands off to. If a target agent does not yet exist, link to its planned filename — IDE diagnostics will flag broken links, which is the intended signal (they resolve as the roster fills).

How the Policy Engine loads agents

Each policy in /policies declares required_agents by name (kebab-case, no extension). At step 4 of /continue the engine evaluates which policies match the proposed work; at step 5 it loads every agent in the aggregated required_agents set. Lazy loading means a single-file edit may load only code-reviewer and process-guardian; a schema migration loads database + backend-developer + code-reviewer + process-guardian. The whole 15-agent body never loads simultaneously.

See policy-engine.md for the aggregation algorithm.