Skip to content

Agent Development Reference

This is the detailed companion to the concise, binding .agents/AGENTS.md. Read the root instructions first, then use this reference when the task needs repository topology, protocol details, or operational constants. Topic specifications remain authoritative for settled design.

Project status

An open-standard, sovereignty-first AI-agent collaboration platform: humans and AI agents share Matrix rooms, @mention to delegate tasks over A2A to local kagent agents governed by agentgateway or to explicitly pinned remote agents, stitched by a small Go bridge — the core room/delegation path is self-hosted with a per-cluster choice of model backend (docs/design-decisions.md D16), and Matrix federation is the differentiating destination for cross-organization agent collaboration (the open alternative to closed, tenant-anchored agent platforms). Stock Element X background notification is an explicit external metadata exception through Element and APNs/FCM; the production notification decision records the accepted residual. Kubernetes-native, Flux GitOps. Read the topic specs under docs/ first (see the mapping table below): design decisions D1–D20 with evidence, security model, federation design, licensing + homeserver strategy. Status: the core @mention path is live on local k3d (fgentic.localhost), and M0–M6 controls have deterministic gates. M7 adds disabled-by-default Slack/Telegram units plus bridged-sender policy; provider-owner and bidirectional acceptance remain explicit human gates. M8 has a provider-free fgentic-fed lab with three participating homeservers, one denied control, a git-reloadable Synapse callback border, and an exact public docs-qa delegation route (mise run fed:up; mise run fed:policy-reload). The lab verifies its ES256/JCS AgentCard, authorizes org B with a client-credentials JWT, reserves maxTokens per verified azp, reaches the deterministic model without exposing kagent directly, and returns one task-bound seller-signed usage receipt whose reservation and nullable consumption fields remain distinct. Its bridge fixture separately proves Signed AgentCard verification, attribution, rate limits, metrics, and fail-closed post-signature tampering against a standalone plain a2a-go runtime with no kagent resources. The GKE reference (clusters/gcp) remains spend-gated (issue #59).

Detailed roadmap and issue conventions

  • The executable roadmap is the release ladder of GitHub milestones — v1.0 → v1.1 → v2…v10 → Backlog — unscheduled (the milestones page is the source of truth; docs/roadmap.md has the dated history and map). The milestone is the pickup gate, and the Definitive v1 focus board (#316) is the cut line. Each theme keeps a kind/epic tracker with sweep order and definition of done; within v1.0, sweep the wedge epics (#85 federation → #86 production reference) top-to-bottom first. The former M0–M34 thematic milestones are closed — they described what, which is now the job of area/* and the epic trackers.
  • The taxonomy is three axes and four flags. area/* = what the issue is about (bridge, ci, community, docs, federation, identity, infra, matrix, models, observability, security) · priority/p0 → p1 → p2 = urgency within its milestone · milestone = when it ships. Every non-epic issue carries all three; nothing else encodes release timing. Flags: kind/epic (milestone tracker, not pickable work), needs-human, needs-cluster, status/in-progress, plus good first issue. Do not reintroduce a label that restates the milestone — that sprawl is exactly what this taxonomy replaced.
  • Human newcomer reservation: good first issue is excluded from autonomous agent sweeps. An agent may help only when the human who already owns the cooperative lease explicitly requests assistance inside that claim. Maintainers curate and refresh the pool under issue #191; agents never manufacture or relabel candidates to keep a quota full.
  • Autonomy is the default and there is no agent-ready label — an issue is agent-workable unless it carries needs-human. Pick it up and finish it autonomously, peer review included. Design and architecture decisions, including proposing, deciding, and accepting ADRs, are agent-owned and never require a human. needs-human = one of the few genuinely terminal gates an agent cannot perform — only money or other cost commitment; deploying to cloud or production; an external account/identity action (install a GitHub App, flip the repo public, publish a release/talk/blog/upstream-PR under the maintainer's name); an external counterparty (first adopter, AGPL provider terms, co-maintainer); or legal publication sign-off. A **Human:** bullet names the terminal step; the label means do every preparable part up to that one gate. Design trade-offs, ADR acceptance, acceptance criteria, internal review, and capturing live proof on a local cluster are never needs-human; an issue blocked only on unfinished upstream work stays open and blocked, not needs-human. needs-cluster marks work that needs a live k3d or GKE cluster to perform or to prove.
  • Issue claims are cooperative leases. Before editing, check assignees, status/in-progress, issue comments, branches, and open PRs. Claim one issue by assigning yourself, adding status/in-progress, and leaving a UTC-stamped comment that identifies the session and intended branch. Re-read the issue immediately; if another active claim appeared, stop. Hosted agents without GitHub mutation access receive an already-claimed issue and never sweep the queue themselves. A claim is stale only after 12 hours without a heartbeat, branch, commit, or PR; document the takeover before proceeding. Release abandoned claims explicitly. See the github-flow skill for commands.
  • Review is agent-owned. A PR is reviewed by a peer coding agent (the code-review skill or a reviewing agent), not a blocking human step; the maintainer reviews async and spot-checks. Every PR still gates on mise run check + mise run test warning-free before merge.
  • Per issue: follow its Tasks + Acceptance criteria literally. Use focused checks during the inner loop; do not repeatedly run the aggregate suites. In a normal installed checkout, commit and push hooks run the required warning-free mise run check then mise run test; do not run the same aggregate gates manually first. In a hookless hosted/disposable environment, run mise run agent:gate once near PR readiness. Re-run only the affected hook or gate after a change that can invalidate its result. Tick the epic checklist via the issue's closing keywords (Fixes #N in the PR).

  • The M8 federation lab topology is the prerequisite for later M8 work: validate it with mise run fed:up before claiming a policy or cross-org flow works. Never merge anything that assumes a single homeserver forever (docs/roadmap.md standing rule).

  • SPEC §N mapping. The retired root SPEC.md was split into topic docs (same § numbering); issue bodies citing SPEC §N resolve as: §1–§3, §11 → docs/architecture.md · §4 (D1–D20) → docs/design-decisions.md · §5, §6, §12 → docs/bridge.md · §7 → docs/security.md · §8 → docs/federation.md · §9 → docs/observability.md · §10 → docs/licensing.md · §13 → docs/roadmap.md. PLAN.md (original research record) was retired to git history.

Layout

  • apps/matrix-a2a-bridge/ — the custom Go bridge (a Matrix Application Service using mautrix/go + the a2a-go client) for local kagent routes and pinned Signed AgentCard remote routes. Its image also carries the federation-only usage-receipt signer/verifier/external processor, which runs after gateway authorization and never becomes part of bridge intake. Self-contained: own Go module, Dockerfile, Helm chart, and deploy/ (its Flux unit — Namespace + HelmRelease, reconciled by the bridge Kustomization).
  • apps/synapse-federation-policy/ — standalone Python Synapse callback module, strict policy parser, tests, and namespace-neutral Kustomize Component. Federation A/B project its immutable versioned source and stable mutable policy.json; C intentionally does not.
  • apps/activitypub-agent-gateway/ — self-contained Go app exposing each agent as an ActivityPub Service actor (WebFinger + actor + inbox→A2A→outbox), reusing the a2a-go client to reach kagent through agentgateway. The second, additive federation transport (ADR 0014, docs/fediverse.md); deliberately not bundled into the mautrix bridge (AGPL-free, homeserver-portable). Own Go module, Dockerfile, Helm chart, and deploy/ unit — reconciled on the demo profile only (issue #489; local/gcp keep it absent), wrapped by the activitypub Flux Kustomization in clusters/demo/ with a default-deny NetworkPolicy and cluster-only demo key material. Public exposure stays gated on every profile: httpRoute is disabled and the internet-facing AP border on local/gcp remains a separate, explicitly gated decision. check:activitypub gates the offline invariants; the runtime GoToSocial interop proof is the tracked M18 remainder.
  • apps/matrix-group-sync/ — self-contained Go reconciler from authoritative Keycloak groups to managed Matrix room membership (ADR 0009, docs/group-sync.md). Its scoped access-manager uses normal Matrix client APIs, keeps local IdP authority local to the homeserver, and defaults to audit-only mode. The Helm chart and deploy/ unit remain opt-in and outside the reconciled Flux DAG until their live acceptance path is complete.
  • apps/knowledge-retrieval/ — the independently gated Go module for permission-aware retrieval (ADR 0017, issue #333). It contains the typed RFC 8785 identity carrier, the MCP search_knowledge service with its database prefilter, and a fail-closed HTTP identity projector. The local reference profile composes its scoped credentials, immutable multi-architecture image, gateway and kagent wiring, and default-deny NetworkPolicies; gcp retains the same reviewed component as an explicit opt-in.
  • examples/agent-pack/ — reference source layout for a third party to publish an Agent from its own Git repository at an immutable ref and compose it as an additional Flux Kustomization without forking core. The example is not reconciled by any cluster here and grants no policy shortcut; use Extending Fgentic Without Forking for the integration and adopter-owned acceptance gates.
  • .fgentic/knowledge-acl.json — strict repository-wide authorization metadata for the optional Git/Markdown knowledge connector. Its classification and normalized principal/group arrays apply to every selected document; it is an ingestion contract, not repository filesystem access control (grounding contract).
  • clusters/ — Flux entrypoints: base/ (the shared Kustomization DAG reconciling infra/ + apps/, parameterized by flux post-build substitution) + per-cluster overlays local/ (k3d) and gcp/ (GKE reference), each carrying its platform-settings ConfigMap (domain, GCP project, TLS issuer, model). demo/ is the disposable small profile consumed by mise run demo:up; it uses an ephemeral local Git source and cluster-only secrets, never the production secret path. federation/ is the separate provider-free lab consumed by canonical mise run fed:up: three Synapse servers, org B's machine-client Keycloak realm, agentgateway, only docs-qa, and the deterministic model. federation-constrained/ composes that unchanged profile plus the opt-in constrained-host Component for fed:up:constrained; it does not remove a proof or become the default. Neither federation entrypoint has a Matrix appservice or external provider dependency.
  • .github/workflows/ — ci.yml validates every PR and main push with the same mise run gates as the git hooks plus a clean-tree assertion, but resolves a gate receipt first and skips those gates when the tree that would actually land already passed them locally (scripts/gate-receipt.sh); it resolves the pull request's merge ref, so a branch whose base has moved matches no receipt and is gated against the real merge result, and a fork contribution can never carry a receipt at all. Its bridge integration is never receipt-gated — no local gate starts a kind cluster — and runs on main and only for bridge, its own workflow, or root mise.toml changes on PRs. work-provenance.yml runs on pull requests and rejects missing closing issues or post-cutoff issues that do not predate the branch by 24 hours. cd.yml builds, scans, attests, signs, and digest-pins bridge artifacts after bridge/CD-workflow changes on main or any v* tag; a published release triggers only its release SBOM. retrieval-image.yml builds, scans, attests, and signs the independently pinned permission-aware retrieval image after retrieval/workflow changes on main or a main-ref manual dispatch. docs.yml builds after main changes to docs, its workflow, or root mise.toml, or on manual dispatch; publishing additionally requires FGENTIC_PAGES_ENABLED. fuzz.yml runs daily or manually dispatched bounded mutation; network-policy-conformance.yml is a manually dispatched kind/Calico enforcement proof; scorecard.yml records weekly or manually dispatched OpenSSF measurements; smoke.yml runs nightly or manually: the small-profile delegation, authorization, MCP, tracing, NetworkPolicy, quota, Kubernetes-audit, and continuous Trivy Operator proofs; an opt-in dispatch also runs the two-control-plane federation acceptance, stop/reuse, and exact-teardown drill while preserving content-free evidence, and on the default branch it maintains the failure tracker. Deterministic fuzz seeds remain in the per-commit test gate, while nondeterministic mutation stays scheduled.
  • release/ — generated adopter release artifacts. release/bom.yaml is the reference-profile chart and image pin-set generated by scripts/gen-bom.sh; mise run check:bom verifies it and rejects drift. Never edit it by hand.
  • infra/terraform/ — GKE reference cluster (private nodes + Cloud NAT, Workload Identity, CNPG backups bucket; bootstrap/ = one-time tfstate bucket, apply it first). Workloads stay provider-independent.
  • infra/flux/ — platform Helm layer (HelmRepositories/OCIRepositories + HelmReleases).
  • infra/gateway/ — Gateway API resources + Let's Encrypt TLS (chat. / matrix. / auth. / id. / grafana.<server_name>), with an enabled/disabled profile that adds admin. only alongside Ketesa.
  • infra/namespaces/ — every platform Namespace + PSS labels, owned by one early dependency-free Kustomization (HelmReleases/Secrets cannot land in namespaces that don't exist; per-layer namespaces deadlock the DAG).
  • infra/policies/ — cluster-wide fail-closed ValidatingAdmissionPolicy invariants enforced at admission: approved kagent Agent references (one model gateway, reviewed pod identity, scoped MCP subset), no :latest image tags, managed-namespace PSS-label retention, and Service exposure limits (only ClusterIP/ExternalName; gateway/traefik is the sole LoadBalancer exception). Validated offline by check:admission-policies and exercised by test:admission-policies.
  • infra/postgres/ — shared CloudNativePG cluster + core databases/roles (synapse, mas, bridge, kagent, keycloak) and the pgvector-backed knowledge database with separate schema-owner/retrieval roles. The optional knowledge Component appends separate connector-state and DML-only ingestion roles, exact HBA rows, and immutable state-machine migrations; external-network Components keep one scoped role/database each. Workloads read namespace-local credential copies with the same password as the matching CNPG postgres Secret, while the knowledge owner credential never leaves postgres.
  • infra/knowledge/ — disabled-by-default sovereign batch ingestion plus one bounded Git/Markdown reference connector over the existing Flux source: complete ACL-bearing inventories, durable desired/applied checkpoints, fail-closed preemption and artifact-rejection quarantine, content-addressed source blobs, tombstones, digest-pinned Docling parsing, DML-only idempotent writes, and a dedicated authenticated :8082 embeddings listener. The shipped #340 embeddings profile (delivered via #540) supplies the opt-in in-cluster runtime and proxy-to-model NetworkPolicy edge; live readiness remains an operator acceptance gate before ingestion is unsuspended.
  • infra/audit/ — offline, fail-closed core for the opt-in regulated identity and admin-action audit streams: pinned Synapse/MAS source contracts, closed payload-free schemas, read-only grants, projectors, cursor/dedup reconciliation, and deterministic negative tests. Runtime adapters and the durable sink remain explicitly deferred; docs/audit.md and ADR 0018 own the evidence boundary and non-claims.
  • infra/canary/ — disabled-by-default synthetic Matrix delegation CronJob for local/gcp. It sends a content-free nonce to the configured docs-qa Agent through the normal admission path, including the cluster's selected model and its egress/cost boundary, then exposes failure/staleness through kube-state-metrics; demo and federation profiles render no canary resources (docs/observability.md §9.11).
  • infra/alert-delivery/ — disabled-by-default, self-hosted Alertmanager-to-Matrix receiver for local/gcp. It posts bounded content-free alert summaries as a non-agent @alertbot, cannot invoke the bridge, and leaves Alertmanager's null posture intact when disabled (docs/observability.md §9.12).
  • infra/moderation/ — opt-in Draupnir policy-list enforcement in a restricted standalone namespace, with an optional Synapse antispam Component. It stays outside every default Flux DAG until an operator provides its Matrix identity/secret and composes the cluster Component (docs/moderation.md).
  • infra/observability/ — kube-prometheus-stack (+ monitors/ as a dependent layer: Pod/ServiceMonitors plus the LLM token-burn and runtime image-vulnerability drift PrometheusRules); Grafana at grafana.<server_name> through the shared Gateway.
  • infra/trivy-operator/ — vulnerability-only Trivy Operator layer for local/gcp, pinned by release commit and image digests in isolated trivy-system; namespaced RBAC, default-deny networking, and count/jobs.batch: 1 admission back the ownership-guarded check:trivy-operator/test:trivy-operator contract. demo/federation remove the layer and namespace budget structurally.
  • infra/matrix/ — ESS Community matrix-stack (Synapse + MAS + Element Web + well-known delegation), pinned + values validated against the chart schema (it changes between CalVer releases). Its opt-in retention/ Component gives the production-shaped local/gcp profiles finite message/media policy from platform-settings; demo/federation stay unchanged.
  • infra/admin/ — disabled-by-default Ketesa static SPA at admin.<server_name>, digest-pinned and locked to the local homeserver. Its profile owns a restricted namespace, quota, HTTPRoute, and egress-denied NetworkPolicy; Synapse/MAS remain the authorization boundary (docs/admin-console.md).
  • infra/federation/ — the disposable M8 lab's four Synapse-only ESS releases (three admitted participants plus one denied control), dedicated database roles, closed-federation and room-v12 policy, well-known delegation, Gateway routes, and local-CA trust. Its opt-in delegation/ Component adds org B's client-credentials issuer, exact public docs-qa routes, a signed card, per-azp reservations, and the isolated single-writer usage-receipt signer/archive without exposing kagent. Its constrained/ Component right-sizes the retained workloads and Git-managed controllers and serializes expensive first installs only when clusters/federation-constrained composes it. Bootstrap Flux controllers and k3s metrics-server are not rendered by that Component; their reversible profile lifecycle belongs to scripts/lib/demo-cluster.sh. It is not part of the normal local or production DAG.
  • infra/keycloak/ — sovereign reference IdP (KeycloakX chart + official Keycloak image), isolated in a restricted-PSS namespace with its own CNPG database/role, Gateway route at id.<server_name>, and bootstrap realm/client/demo users. MAS consumes its SOPS-backed OIDC client through ESS; an external provider can replace that fragment (docs/identity.md).
  • infra/agentgateway/ — AI-native data plane: LLM egress chokepoint + A2A route to kagent.
  • infra/mcp-catalog/ — git-native catalog of vetted MCP server.json entries. Each entry binds source/license approval, an immutable image, allowed tools, and the complete surface pin to every rendered agentgateway backend and kagent RemoteMCPServer; check:mcp-governance rejects uncataloged resources.
  • infra/models/ — optional self-hosted model runtimes selected with their agentgateway provider inventory; vLLM uses a pinned CPU image, an immutable Qwen snapshot, and a default-deny models namespace.
  • infra/kagent/ — kagent platform + sample Agents (a2aConfig, served as A2A on :8083).
  • infra/production-ha/ — opt-in Components for the production replica, placement, disruption-budget, and workload-resource posture. clusters/gcp composes the profile; local, demo, and federation intentionally do not. mise run check:production-ha proves the effective renders and pinned chart selectors. The bridge stays one ready intake consumer and is exercised separately with mise run test:availability; do not describe that graceful SIGTERM drill as hard-crash recovery or distributed exactly-once delivery.
  • infra/bridges/ — reusable restricted Helm runtime plus self-contained, opt-in, digest-pinned mautrix Slack/Telegram profiles. Each network directory composes its runtime, Matrix registration, Postgres/HBA role, Matrix-to-A2A origin, and NOLOGIN teardown into canonical Flux layers; it stays disabled until its cluster component, SOPS set, and provider acceptance are explicit (docs/interop.md).
  • infra/secrets/ — *.sops.yaml.example templates only; REAL encrypted secrets are per-cluster in clusters/<env>/secrets/ (generated by scripts/gen-secrets.sh <server_name> <env>, committed — Flux applies from git).
  • scripts/federation.sh + scripts/seed-federation.sh — ownership-guarded lifecycle and acceptance proof for the fgentic-fed lab. The A2A half verifies the signed public card, JWT negative cases, one authorized provider-free docs-qa reply, aggregate token growth, per-client reservation exhaustion, and one task-bound ES256/JCS receipt whose tampered copy fails while denied requests leave the archive unchanged. The Matrix half exchanges A/B messages under room-v12 and server-ACL policy while denied server C cannot join or submit a signed transaction, and A drops B's disallowed callback probe with content-free evidence. fed:policy-reload proves a Flux policy update without Synapse replacement and restores deny. fed:up remains canonical; fed:up:constrained explicitly composes the same proof through the serialized, right-sized laptop overlay and a labelled k3s Go-runtime budget. scripts/lib/demo-cluster.sh owns the bootstrap-only Flux-controller and metrics-server switches, restores their canonical values on standard capacity, refuses an in-place standard/constrained node switch, and atomically records exact Docker identities before destructive teardown so demo:down/fed:down can resume safely after interruption. Pending receipt state is inspect-only in status and blocks up; malformed or identity-conflicting state fails closed. fed:stop releases CPU/RAM while preserving the exact cluster/image volume for same-mode reuse, and fed:down verifies zero lab-owned cluster/image artifacts. FGENTIC_FED_TRACE=yes adds only the allowlisted, content-free resource trace under .agents/tmp. scripts/fed-check.sh is a bounded, credential-free public discovery preflight for the bilateral partner onboarding runbook; it never claims reachability proves governance. scripts/fed-onboard.sh stages that connectivity probe plus an opt-in A2A/AgentCard conformance check (fetch the partner's public Signed AgentCard, verify its ES256/JCS JWS with the bridge's own verifier under an out-of-band-pinned JWK, and require the JSONRPC A2A v1.0 interface plus the token-budget extension); it emits eligible_for_registry_review evidence only when both stages pass and never grants trust, since registry admission stays an explicit reviewed step.
  • scripts/dev.sh — fast bridge lifecycle over the owned fgentic-demo cluster: create/reuse, bridge-only image reload, status, state-preserving stop, and ownership-guarded teardown. It always writes a temporary kubeconfig and never reads or switches the user's default context. demo:up remains the full reconcile + seed + acceptance path.
  • docs/adr/ — Architecture Decision Records.
  • AGENTS.md — root discovery symlink to this canonical file for Codex and other Agent Skills-compatible tools. .agents/skills/ remains the single shared skill source; .claude/skills is its tracked Claude compatibility symlink. Read the matching skill before working an area: matrix-agents (operator runbooks: bootstrap, add-agent, add-bridge, verify), github-flow (backlog, issue/epic authoring, PRs, CI/CD), flux-gitops (infra changes, reconciliation debugging, version pins), bridge-dev (Go bridge inner loop), local-cluster (k3d lifecycle + troubleshooting), sops-secrets (generate/edit/rotate secrets), terraform-gke (cloud reference, spend-gated), observability (metrics, cost alert, monitors), docs-spec (topic specs §N, ADRs, README/AGENTS sync).
  • .claude/settings.json and .codex/environments/environment.toml — project-native checkout setup for Claude Code and the Codex App; both delegate dependency preparation to mise run agent:setup. Hosted environments use the same task after installing mise.
  • mise.toml — root task vocabulary + pinned toolchain. docs/ (OKF-frontmattered topic specs + index.md listings — mapping below, conventions in the docs-spec skill) / README.md (humans).
  • Community meta: CHARTER.md (TSC authority, voting, conflicts, licensing, and LF activation), CONTRIBUTING.md (workflow, labels, DCO), CODEOWNERS, GOVERNANCE.md, MAINTAINERS.md, RELEASE.md, SECURITY.md (private vulnerability reporting — never file security bugs as public issues), root SUPPORT.md + canonical .github/SUPPORT.md, ADOPTERS.md, .github/ISSUE_TEMPLATE/ + PR template.

matrix-a2a-bridge packages

The behavioral detail behind the one-line map in apps/matrix-a2a-bridge/AGENTS.md. It lives here rather than in that nested instruction file because the root + bridge instruction chain is bounded by Codex's 28 KiB budget; see hosted-agents.md. The binding rules stay in the instruction file — this section is orientation, not authority.

  • cmd/bridge/main.go — entry point: config load, slog, state layer (Postgres or memory), appservice + event-processor wiring, intake-first bounded shutdown. Also -generate-registration.
  • cmd/usage-receipt/ + internal/usagereceipt/ — federation-only ES256/JCS seller receipt tool and Envoy external processor. It runs only after agentgateway JWT authorization and quota reservation, attaches the signed receipt to terminal A2A Task metadata, rejects direct Messages that cannot prove a terminal state, replays one task-unique archive assertion, and never receives a model credential or prompt-derived signing decision.
  • internal/config/ — typed, env-parsed config (caarlos0/env); Config, Load (fail-fast validation, incl. timeouts/rates).
  • internal/matrixapp/ — builds the mautrix AppService (CreateFull, optional SQL StateStore), loads/generates the registration (rate_limited: false), and wraps the transaction route with exact-body, bounded, authenticated pre-ACK durable intake.
  • internal/a2aclient/ — thin wrapper over the a2a-go SDK: resolve local AgentCards for profile refresh; bind local v1 JSON-RPC transport to the operator-configured base plus exact agent route; verify and periodically revalidate remote A2A v1.0 Signed AgentCards against pinned ES256 identities; cache delegation clients; apply per-remote timeouts and token-budget metadata; send with a caller-persisted message ID; classify any send whose HTTP transport may have started but produced no acknowledgement as ambiguous; resume an acknowledged task through GetTask; map the Task | Message sum type to a Result (text, contextId, taskId, terminal); authenticate local agentgateway calls as the bridge workload; and stamp the Matrix sender plus W3C traceparent via a context-aware RoundTripper. Never send the local A2A_API_KEY to a remote URL.
  • internal/evaluation/ + cmd/eval/ — fixed, typed A2A quality suite for the three sample agents: deterministic rubrics, direct agentgateway Prometheus deltas, optional operator pricing, and mergeable JSON/Markdown reports under .agents/tmp/. An opt-in sovereign LLM-as-judge lane (--judge, #355) scores the optional_llm_judge scenarios for groundedness/task-success via a self-hosted judge Agent over A2A — guarded to residency: self-hosted models, parsed fail-closed at the boundary, and recorded payload-free. cmd/eval-golden/ adds the zero-egress checked-in demo-stub gate; this is deterministic source-contract evidence, not live-model quality.
  • internal/agentschema/ + cmd/validate-agents/ — strict agents.schema.json validation reused by agent:new and the effective agent-zoo render check before a generated mapping reaches GitOps.
  • internal/mcppin/ + cmd/pin-mcp/ — versioned, typed MCP surface collection through the official SDK; complete-object JCS hashes; deterministic drift reports; and atomic pin updates. The repository wrapper is scripts/pin-mcp.sh.
  • internal/bridge/ — the orchestration: resolve @mention targets (typed m.mentions + body fallback; own-homeserver check + exact room/current ghost-membership/per-agent sender policy), atomically plan durable per-target jobs and inbound controls before HTTP 200, claim them through fenced database leases under a global concurrency cap and cross-restart per-room FIFO, revalidate/rate-limit, call A2A, poll known or input-paused tasks, persist reply/control outboxes, reply/edit as ghost with deterministic Matrix transaction IDs, reconcile optional pin state, and emit content-free terminal records through the log_stream=audit logger. agents.go loads and atomically replaces the routing/allowlist map: each agent has exactly one local namespace/name target or one remote url/timeout/tokenBudget/cardIdentity target, plus exact allowedRooms, bridgedOrigins, allowedServers, and allowedSenders globs. Local aliases in allowedRooms are bootstrap locators resolved on every admission; direct room IDs are preferred. Bridge origins are anchored full-MXID namespaces and always require an explicit per-agent sender match. profiles.go derives Matrix ghost profiles from AgentCards while retaining the last-known display data on refresh failures; directory.go serves the local, policy-filtered !agents command without A2A or LLM work; welcome.go posts the bot's one sender-filtered onboarding notice under the shared notice budget. durable_controls.go owns crash-safe cancel/continuation/question/progress/pin behavior; reaction.go, inflight.go, and progress.go retain the development-only in-memory path.
  • internal/state/ — the versioned Store/Ledger interfaces: Postgres (shared dbutil pool, bridge_appservice_transactions, bridge_delegations, bounded bridge_delegation_controls, bridge_contexts, permanent bridge_room_welcomes, and legacy bridge_processed_events) plus a behavior-matching in-memory development implementation.
  • internal/telemetry/ — env-gated OTLP/HTTP exporter setup; unset OTEL_EXPORTER_OTLP_ENDPOINT keeps standalone development tracing-free.
  • chart/ — Helm chart (Deployment, Service, ConfigMap for the agent map, NetworkPolicy, ServiceAccount; database.secretName feeds DATABASE_URL).
  • deploy/ — the Flux unit (Namespace + HelmRelease) reconciled by the bridge Kustomization; CD pins the image digest here.
  • registration.example.yaml / agents.example.yaml — templates for the two config files; agents.schema.json is the Stable v1 routing/allowlist contract validated against every in-repo fixture.

Platform protocols (how agents participate at runtime)

  1. Identity. Every platform agent is a Matrix ghost @agent-<name>:<server> owned by the bridge (exclusive appservice namespace @agent-.*). The explicit agents.yaml allowlist maps each ghost to exactly one local kagent namespace/name or one remote url with timeout, partner-enforced token-budget metadata, and a pinned ES256 Signed AgentCard identity; unmapped or untrusted targets are rejected.
  2. Delegation. An @mention (typed m.mentions, plaintext fallback) becomes an A2A SendMessage to either http://kagent-controller.kagent:8083/api/a2a/<namespace>/<name> through local agentgateway or the exact verified remote URL. Non-streaming by design; long tasks use GetTask polling + Matrix m.replace edits. Remote timeouts are additional ceilings over global request/task deadlines, and remote calls never receive the local A2A_API_KEY (docs/bridge.md §6).
  3. Threading. The bridge threads ordinary conversations with a per-(room, ghost) A2A contextId; kagent maps contextId 1:1 to a persistent session. Do not reuse a contextId across different agents. D18's retrieval-capable Agent is the security exception: every initial delegation omits caller contextId, taskId, and referenceTaskIds so the server creates a fresh session that cannot retain or reference previously grounded content.
  4. Attribution. The Matrix sender is forwarded as the asserted A2A user identity (X-User-Id). Configured external-appservice MXID namespaces add bounded origin kind/network audit fields but never replace the full MXID; the exact evidence chain and downstream-authentication limits are in docs/audit.md. D18's permission-aware retrieval path uses a separate gateway-projected identity-and-room-audience contract; it does not make X-User-Id authentication globally.
  5. Trust boundaries. Room content is untrusted input to agents (prompt injection is the #1 threat — docs/security.md): sender allowlists gate who may invoke which agent; agents from other homeservers are never resolved as local targets; explicitly configured remote agents require a currently verified A2A v1.0 Signed AgentCard; agent replies are m.notice and other automation must not act on them. Local LLM egress goes only through agentgateway — no agent holds a model credential.

Principles

  1. Open standards only. Every layer is an open protocol or OSS component (Matrix, A2A, MCP, Kubernetes, Gateway API, OIDC). No proprietary SaaS in the critical path; every component is swappable. This is the whole point of the showcase.
  2. Federation-ready decisions. The endgame is cross-organization collaboration (docs/federation.md): federated rooms use room v12+, closed-federation allowlists, and server ACLs; nothing merged may assume "single homeserver forever" (e.g., never match users by localpart without checking the homeserver).
  3. Independent apps, bridging infra. Each app under apps/ is self-contained and deployable on its own. infra/ exposes shared components (Postgres, gateway, agentgateway) without coupling apps together. The homeserver, MAS, Matrix-to-A2A bridge, kagent, optional Keycloak IdP, and every enabled external bridge each get their own database + scoped role in the shared CloudNativePG cluster (Synapse's DB uses C collation). The composed knowledge store follows the same boundary with a dedicated database, a non-workload schema-owner role, and a read-only retrieval role.
  4. Flux GitOps delivery. Production CD is Flux v2, pull-based, for both infra/ and apps/. Never kubectl apply / helm upgrade prod by hand — commit to git and let Flux reconcile. GitHub Actions is CI-only (build/test/scan/sign the bridge image, commit the digest). HelmRelease.dependsOn references HelmReleases only — wrap apps in Flux Kustomizations to depend on Kustomizations.
  5. Helm-first reusable manifests. Package Kubernetes manifests as parameterised Helm (the bridge's chart/) or Flux HelmReleases with inline spec.values; per-directory kustomization.yaml lists resources; base + overlays where environments differ. Kustomize is Flux's thin resource-lister, never a Helm replacement.
  6. Gateway API, not Ingress. Web/UI traffic (Element, Synapse client API, MAS, Keycloak) routes through the Gateway API (Traefik); cert-manager terminates Let's Encrypt TLS per host. Local A2A/LLM/MCP traffic egresses through agentgateway on ClusterIP — the local model-credential chokepoint. The opt-in federation profile is the sole public A2A exception: one exact docs-qa route reaches a dedicated agentgateway listener under strict org-B JWT and quota policy; kagent itself remains ClusterIP-only behind NetworkPolicy. An explicitly configured remote A2A URL is a separate outbound trust boundary, receives no local gateway credential, and requires a pinned Signed AgentCard plus independently reviewed transport authorization. kagent's A2A endpoint is unauthenticated by default, so the NetworkPolicies on both the agentgateway and kagent namespaces are load-bearing security controls. Ordinary A2A may retain its direct-route debugging toggle, but a D18 retrieval-capable Agent must use the gateway projection path and fail closed if it is unavailable.
  7. A2A for delegation, non-streaming. Agents are invoked over A2A SendMessage (request/response; GetTask polling for long tasks). Streaming is deliberately unused. Reuse the official a2a-go SDK (the same one kagent uses) — do not hand-roll JSON-RPC.
  8. Homeserver strategy is decided — don't relitigate it per-PR. Reference profile: ESS Community (Synapse + MAS + Element; best appservice API, MAS/Element X, Postgres). Pure-permissive fallback profile: Tuwunel/continuwuity (Apache-2.0, RocksDB) for AGPL-averse deployments. The bridge only uses stable-spec appservice endpoints, so it stays homeserver-portable; switching is governed by the explicit triggers in docs/licensing.md §10.3, not preference.
  9. Encryption is selected per room. ADR 0026 supersedes ADR 0008's blanket prohibition. The current crypto-free bridge refuses encrypted events until the per-ghost identity and crypto stages land, so ADR 0015's classification-bounded plaintext contract continues to govern current v1 partner rooms.
  10. Cost and resource efficiency are correctness constraints. Every mention is an LLM invocation: keep the bridge's per-sender/per-room rate limits and agentgateway's token metering intact; cross-org maxTokens is a per-azp admission reservation, while actual model metrics remain aggregate. During development, choose the smallest sufficient model and resource profile, reuse existing local infrastructure, and avoid unnecessary CPU, RAM, storage, network, or paid-service consumption. Scale only from measured need. Never merge a change that lets automation invoke agents unboundedly or presents reservations as consumption (docs/design-decisions.md D7/D8).
  11. SOPS + age secrets. Never commit plaintext secrets — only *.sops.yaml, decrypted in-cluster by Flux. A gitleaks pre-commit hook enforces it. Secrets are per-cluster (clusters/<env>/secrets/).
  12. Version pins that bind each other. Gateway API CRDs are pinned to v1.5.1 experimental, the supported overlap between agentgateway v1.3.1 (officially Gateway API 1.3–1.5; still watches TCPRoute v1alpha2) and Traefik chart 41.0.2 (proxy v3.7.6; supports Gateway API v1.5.1). Gateway API v1.6 deprecates rather than removes TCPRoute v1alpha2, but remains outside agentgateway 1.3.x's supported range; advance it with agentgateway v1.4 after that controller's TCPRoute v1 transition. Bump these pins together, deliberately. kagent charts come via an OCI-type HelmRepository (never chartRef→OCIRepository: Flux appends digest build-metadata that kagent stamps into a label).
  13. GHCR images. The bridge image is multi-arch distroless, published to ghcr.io/fmind-ai/matrix-a2a-bridge, deployed by immutable digest (never latest).
  14. License hygiene. Project code is Apache-2.0 (docs/licensing.md). Never add an AGPL dependency to the bridge (mautrix/go is MPL-2.0 — keep the NOTICE files current); never mirror AGPL images (Synapse, Grafana) into project registries — reference upstream. Contributions use DCO sign-off, no CLA.

Conventions

  • Server name / domain: fgentic.fmind.ai (GKE reference) / fgentic.localhost (local k3d, loopback 80/443, local-CA TLS — scripts/local-ca.sh). Normal public hosts are the apex plus chat., matrix., auth., id., and grafana.; admin. exists only when the Ketesa profile is enabled, and the federation profile alone adds a2a.<org-A> for its exact exported route. Bot user @a2a-bridge:<server_name>; agent ghosts @agent-<name>:<server_name> (appservice exclusive namespace @agent-.*). ESS release name is fixed to ess (Services ess-synapse:8008, ess-matrix-authentication-service:8080, ess-well-known:8010; MSC3861 compat paths route to MAS in the HTTPRoutes). The tracked local model default remains Vertex AI google/gemini-2.5-flash through agentgateway with a cluster-only ADC secret. The GKE reference selects self-hosted vLLM Qwen/Qwen2.5-7B-Instruct as its documented 24 GiB GPU policy default; issue #10's funded live acceptance remains open.
  • kagent A2A endpoint: http://kagent-controller.kagent:8083/api/a2a/<namespace>/<name> (AgentCard at …/.well-known/agent-card.json). A remote mapping uses an exact HTTP(S) A2A URL whose card at the same suffix verifies under its pinned P-256 public JWK; production config enables none by default. agentgateway LLM: http://agentgateway-proxy.agentgateway-system:8080.
  • Go (default) and Python are the core languages; Go for the bridge. Type-safe, small composable units, errors wrapped with %w, no ignored err, no tech debt.
  • mise is the single source of truth for tasks (install, format, check, test, build, watch); lefthook + CI reuse it. Conventional Commits; no attribution. Most tasks live in the root mise.toml (run from the repo root), but each app also has its own apps/*/mise.toml — a few tasks (e.g. the ActivityPub gateway's interop) exist only there and must be run from that app directory (mise --cd apps/<app> run <task>), so a bare mise run <task> at the root can report "task not found".
  • A fresh agent clone uses mise run agent:setup. It installs pinned tools and locked dependencies without Git hooks, dependency-manifest rewrites, cluster creation, credentials, or provider access. Claude runs it on session startup; the Codex App runs it when its checked-in local environment is selected. Do not replace it with mutation-capable mise run install in disposable agent setup. Follow it with mise trust on the root and every apps/*/mise.toml: an untrusted app config aborts the aggregate gates with a trust error that looks like a test failure.
  • Use the smallest sufficient development boundary. Focused unit tests first; test:integration for the isolated Matrix↔A2A kind boundary; dev:up once plus dev:reload/watch for interactive bridge work on the lightweight owned demo; demo:up after manifest/profile changes and for final seeded end-to-end proof. Use canonical fed:up for federation acceptance and opt into fed:up:constrained only on a constrained host; both prove the same topology and behavior. Use the full cluster:up + Flux bootstrap only for SSO, observability/tracing, Trivy, SOPS, or other controls intentionally omitted from demo. dev:stop and fed:stop preserve their owned state while releasing active CPU/RAM. Repo development never depends on a global cluster or the user's default Kubernetes context.
  • One local session owns the repository and the runtime. Local development is a single sequential agent in one checkout. Git worktrees and extra clones isolate source and Git state but not Docker, k3d, kind, fixed image tags, loopback ports, or cluster names, so a second local path buys no isolation where it matters and multiplies the load that actually constrains the host. The lane model that once split work across agent/blue, agent/green, and agent/red checkouts was retired on 2026-07-28: it froze a 14 GiB no-swap workstation and produced review debt that landed back on the same machine. Parallelism belongs in cloud/hosted sessions, which cost the workstation nothing — see hosted-agents.md.
  • The installed commit/push hooks and hookless fallback mise run agent:gate share one portable host-local mutex, which now guards against a second concurrent gate in the same checkout rather than against a sibling worktree. Hooks invoke its scoped check and test modes; the fallback runs both in order. Do not launch either aggregate gate manually while a hook may already be running it. CI runs them sequentially on isolated runners.
  • The aggregate gates are Docker-backed and collapse under a running cluster. test:kagent-trace-privacy, test:mautrix-bridges, and test:integration start containers. Measured on the reference workstation on 2026-07-28: with two k3d clusters up, check took 208 s and test ran 984 s before test:kagent-trace-privacy failed on a dead container; with every cluster stopped, the same commit ran check in 108 s and test in 77 s, both green. Stop clusters before running the gates, and when a gate fails, check host load before assuming the change caused it.
  • After any local cluster recreate (mise run cluster:up + Flux bootstrap), run mise run cluster:overrides to re-apply the gitignored platform-settings-overrides ConfigMap (holds the real gcp_project and any value kept out of git). It is untracked by design, so a recreate loses it and Vertex falls back to the your-gcp-project placeholder until re-applied (docs/forking.md §5). Idempotent; a no-op when the file is absent.
  • main is protected by a repo ruleset (protect-main, active). It blocks force-pushes, branch deletion, and non-linear history, so main's history cannot be rewritten or lost by accident — for a deliberate rewrite (e.g. the v0.1.0 squash) temporarily disable the ruleset, then re-enable it. It intentionally omits repo-level pull-request/status-check rules: CD's digest-pin step pushes a fast-forward commit straight to main as github-actions[bot], which a PR/check rule would block, and a repo ruleset cannot grant the built-in GitHub Actions app a bypass (GitHub requires an org-scoped ruleset, admin:org, to bypass Actions app id 15368). Requiring PR review at repo level also adds no real gate here because coding agents push with the maintainer (admin) identity and would bypass it — agents still work issue→PR by convention (github-flow). Enforced review for outside contributors is the documented next step (org-scoped ruleset).