Agentic Identity Broker — Agent Context

Read the relevant source and documents before you decide. Do not infer repository behavior from general knowledge.

How to Use This File

Paths in this file are relative to the repository root. Read the nearest child AGENTS.md before you change an area. Use the indexes to select relevant sources, not as a requirement to read every document.

Maintain shared instructions in the root or nearest child AGENTS.md. Keep tool-specific instruction files limited to scope metadata and routes to those owners. Read routed files before implementation or review. A route is not a substitute for its instructions.

Docs Index (Retrieval Targets)

Read the source that governs the change. The summaries here do not replace the constitution, accepted ADRs, or API contracts.

Architecture & Decisions

ARCHITECTURE.md | Source of truth for system design adrs/ | Architecture decisions and status (see the ADR index) .specify/memory/constitution.md | Binding constitution — 15 principles governing all work CONTRIBUTING.md | Setup, contribution process, and verification requirements docs/resources/assurance-case.md | Threat model, trust boundaries, and security evidence

Coding Standards

coding-standards/LOGGING.md | Structured logging: plumbing, record shape, levels, principals, permitted data. Read before you add or change a log call. coding-standards/OPENTELEMETRY.md | Traces and metrics: plumbing, span names and status, attribute keys, instruments, permitted data. Read before you add or change a span or metric.

Section-Specific Agent Context

internal/AGENTS.md | Backend hexagonal architecture, builder pattern, testing conventions internal/domain/AGENTS.md | Domain layer rules, zero-infra imports, data models, error types internal/domain/id/AGENTS.md | Strongly typed entity IDs, code generation, type catalogue internal/ports/AGENTS.md | Port interface catalogue, ISP rules, error conventions internal/adapters/AGENTS.md | Adapter map, cross-adapter ban, storage/encryption/HTTP details internal/extproc/AGENTS.md | Standalone ExtProc token exchange service, config, architecture web/AGENTS.md | React SPA, design system, API client, testing infra/AGENTS.md | AWS CDK encryption stack, IRSA, environment parameterization tests/AGENTS.md | E2E + integration test suite overview tests/e2e/AGENTS.md | Ginkgo E2E rules, fixtures, dual-server pattern, anti-patterns tests/e2e/frontend/AGENTS.md | Playwright browser tests, page objects tests/integration/AGENTS.md | Self-contained and infrastructure-backed integration test guidance

Runtime Entry Points

cmd/agentic-identity-broker/ | Broker CLI, configuration, and dual-server startup cmd/extproc-token-exchange/ | ExtProc CLI, telemetry bridge, and gRPC startup

API Contracts

api/enduser/openapi.yaml | End-user API: consent, OAuth2, sessions, and approvals api/admin/openapi.yaml | Admin API: agents, services, resources, permission sets, and session sweep

Specs (Feature Requirements)

specs/NNN-<name>/spec.md | Feature requirements + acceptance scenarios specs/NNN-<name>/plan.md | Implementation approach specs/NNN-<name>/tasks.md | Trackable task list .specify/templates/overrides/spec-template.md | Spec template: required sections, including concrete example journeys (Principle XIV) .specify/examples/specification-by-example.md | Worked example journey and Wireloom render command (Principle XIV) .specify/templates/overrides/tasks-template.md | Tasks template: mandatory Phase 2 design and Phase N compliance tasks

For feature work, read its spec.md, plan.md, and tasks.md before implementation. Spec Kit selects SPECIFY_FEATURE_DIRECTORY first, then .specify/feature.json. Check that this selection matches the task. Do not infer the feature from the branch name alone. .specify/scripts/bash/common.sh defines this selection order.

Encryption Deep Reference

.agents/skills/aws-crypto-go/SKILL.md | AWS Encryption SDK Go — patterns, rules .agents/skills/aws-crypto-go/reference.md | API reference .agents/skills/aws-crypto-go/examples.md | Code examples

Design System (Frontend)

web/src/design-system/docs/INDEX.md | Complete design system documentation index web/src/design-system/docs/COMMON_MISTAKES.md | Read before you work on a styled component web/src/design-system/docs/DECISION_TREES.md | Which component to use when

Operations & Guides

docs/ENCRYPTION_INTEGRATION_GUIDE.md | Encryption integration guide docs/STORAGE_EXTENSION_GUIDE.md | Adding new storage entities docs/STORAGE_TROUBLESHOOTING.md | Storage debugging docs/configuration.md | Configuration reference docs/deployment/ | Deployment guides (Kubernetes, IRSA) docs/operations/ | Operations runbooks examples/config/ | Example configuration files charts/agentic-identity-broker/ | Helm deployment contract migrations/ | PostgreSQL schema migrations mocks/ | Standalone test services and OAuth2 clients configs/ | Development, test, production, and container configuration scripts/ | Development helpers and deployment checks justfile | Maintained commands and their dependencies .github/workflows/ | CI, security, coverage, and release gates assets/docusaurus/ | Documentation-site source and build configuration

Constitution (Binding) — 15 Principles

Treat .specify/memory/constitution.md as BINDING. Apply these principles:

1. Security-First — Fail closed. Do not bypass security controls. Only accepted ADR 031 permits unsigned subjects, with its full controls. This exception applies only to explicit unverified-subject rules in local-mode impersonation. Client assertions, actor tokens, and signed subjects still require signature verification.
2. Accepted ADRs are Binding — Only ADRs with status "Accepted" are binding. Use ARCHITECTURE.md as the source of truth. Follow Principle II for same-PR ADR acceptance and revisions. A merged Accepted ADR requires an Accepted superseding ADR for deviations.
3. Library-First Security — Do not use custom crypto. Use Go crypto/*, golang.org/x/crypto, or AWS Encryption SDK.
4. OpenAPI Transparency — Define APIs in api/{enduser,admin}/openapi.yaml before implementation.
5. Domain-Driven Design — Enforce ubiquitous language. Add new concepts to the ARCHITECTURE.md glossary.
6. Hexagonal Architecture — Domain services depend on ports, not adapters. Adapters implement ports. Prevent these violations:
   • Port bypass: Route handlers through domain services to ports. Do not route a handler to a port directly.
   • Anemic domain: Make services enforce invariants. Do not only proxy port calls.
   • Domain logic leakage: Put conditional logic beyond input parsing in domain services, not handlers.
   • Domain packaging: Make each new domain/X/ a genuinely independent bounded context.
7. Configuration-Driven — Use internal/ports/config.go for broker configuration. ExtProc has its own schema under accepted ADR 011. Update configuration documentation and examples with each parameter change. Update Helm values and templates only for workloads that the chart deploys.
8. TDD — Use red-green-refactor. Write tests first. Make each test fail before implementation.
9. Persistence Consistency — Define ISP repos in internal/ports/storage.go. Use sqlx for PostgreSQL. Provide both in-memory and postgres adapters.
10. API-First — Design APIs before implementation. Get stakeholder agreement before changes.
11. Design System Compliance — Use shared semantic tokens and WCAG 2.1 AA. Check light and dark themes. Keep brand assets in the repository. Read the current visual direction in web/src/design-system/docs/DESIGN_PRINCIPLES.md. A change to that direction requires an ADR.
12. DI via Builder — Put broker dependency wiring in internal/app/builder.go. Do not instantiate services in routing.
13. E2E Acceptance Tests — Use a 1:1 specification-to-test mapping in tests/e2e/. Test a complete user journey. Do not test one endpoint segment.
14. Specification by Example — In each spec, add concrete user journeys and link them to the Given/When/Then scenarios. Where applicable, show configuration, RFC-style HTTP exchanges, Wireloom wireframes, and decoded JWT claims.
15. Binding Coding Standards — Follow every applicable standard in coding-standards/, including its review checklist and required tests, contracts, and registry entries. See Principle XV for scoped exceptions.

Monorepo Structure

Import rules: Do not let the domain import adapters or app. Define contracts in ports. Let driven adapters import ports and domain. HTTP routing receives handlers from app. It can use routing middleware and configuration. Do not couple independent adapter subsystems. Read internal/adapters/AGENTS.md for existing factory and shared-helper composition.

ADR Decision Index

Read relevant ADRs before implementation. Only accepted decisions are binding. Check each file's status and superseding decisions. A proposal does not become binding because its code exists. ADR numbers are not unique in this repository. Use the full filename. You can mark an ADR introduced on this branch as Accepted in the same PR. Before the branch merges into main, you can revise that ADR in the same PR, even after acceptance. The final ADR and code MUST agree before merge. After that merge, a change or deviation requires a new Accepted superseding ADR. See Principle II in .specify/memory/constitution.md.

Domain Glossary

Read ARCHITECTURE.md for the full glossary and relationships.

Development Workflow

Use just as the command runner. Run just --list for the full listing.

After Go, test, or infrastructure changes, run just check. Then run the smallest matching test command. Do not rely only on editor diagnostics. Before a pull request, run the full gate from CONTRIBUTING.md.

Code Style

Use these rules for all monorepo code (Go, TypeScript, CDK):

• Minimize comments — Write a comment only for context that code alone cannot convey.
• Never restate code — Do not write comments that add no information.
• No debug artifacts — Do not leave debug logging, commented-out code, TODO stubs, or future-implementation references.
• Match surrounding style — Keep naming, error handling, and file structure consistent with adjacent code.
• Explicit over clever — Make intent clear without tracing abstractions.
• Extend, do not duplicate — Use an existing mechanism (for example, JWE for ephemeral state). Do not introduce a competing one.
• Explicit SQL columns — List required result columns in SQL queries, including queries in migrations and tests. Do not use SELECT *, table.*, or RETURNING *. Wildcard projections hide data dependencies and couple readers to schema changes. COUNT(*) and EXISTS (SELECT 1 ...) are permitted.
• Structured logging — Follow coding-standards/LOGGING.md. Log principals only as id.Principal. Never log credentials.
• OpenTelemetry — Follow coding-standards/OPENTELEMETRY.md. Use constant span names. Set principals on spans only through id.Principal.SpanAttribute, and add none until #356 provides it. Never put a principal in a metric or a credential in any signal.
• No test-only production APIs — Put test helpers in _test.go or tests/. Assert through production APIs.

Database Migrations

Use NNN_description.{up,down}.sql in migrations/. Test both directions against PostgreSQL with the production migrations. Each migration must be atomic, as required by Constitution Principle IX. Non-atomic migrations require an accepted ADR exception. adrs/039-concurrent-session-expiry-index.md permits concurrent index creation and removal only for migration 037. Keep its first-line -- migrate:no-transaction comment in both directions. The comment is informational, not enforced by the migration runners. Migration 030 is historical, not an approved template for new non-atomic migrations. Read tests/integration/AGENTS.md for migration tests.

Active Technologies

Read go.mod and each module's manifest for exact versions. The stack uses chi v5, sqlx, pgx v5, Ginkgo/Gomega, Viper/Cobra, CVA, OpenTelemetry (otelhttp, otelslog), and Envoy ExtProc. PostgreSQL is the production store. In-memory storage is for development and tests.