architect

Record an architectural decision as a numbered ADR in docs/adr/, capturing the context, the options that were rejected, the deciding factor, the consequences accepted, and the conditions that should reopen it. Use immediately after a human chooses between architectural options, or when asked to write down or supersede a decision.

Design and gate an AI feature end to end — agentic tool use, RAG over internal data, or a model call in the request path — covering tool authority, retrieval authorization, prompt-injection posture, failure and fallback, cost and latency budgets, evaluation as a release gate, and rollout with a kill switch. Use whenever a developer is building anything with a language model in the path.

Design or change a contract other teams depend on — REST endpoints, gRPC services, or event schemas — contract-first from an OpenAPI/proto/AsyncAPI specification, applying the org standards for resources, status codes, errors, pagination, idempotency, compatibility, deprecation, and the edge gateway boundary. Use whenever an OpenAPI document, .proto file, AsyncAPI spec, or event payload is created or modified, and before any change that could break a consumer.

Review a change, branch, or PR against all ten governed architecture domains — boundaries, contracts, data access, security, scale, reliability, observability, metrics, and recorded decisions — and return findings ranked by consequence with citations to the specific standard. Use when reviewing a diff or PR for architectural drift rather than line-level bugs.

Design a service's authentication and authorization against Red Hat SSO — client type and flow, service-to-service credentials, token validation, the role and tenant model, and the split between what the gateway checks and what the service must re-check. Use when building a new service, adding an entry point, integrating with SSO, or reviewing anything auth-related.

The organization's architecture doctrine in full — decision rights, the human-in-the-loop contract, the ten governed domains, and the standards index. Use when someone asks what the architecture rules are, why a rule exists, which skill applies to a situation, or when you need the governing principle behind a review comment.

Produce a high-level architecture for a new system, service, or capability — boundaries, responsibilities, data flow, datastores, messaging, and non-functional targets — pausing at each real fork for a human decision and recording the outcome as an ADR. Use before writing code for a new service, a new integration, a new datastore, or any change to an existing service boundary.

Produce the component-level design that sits under a high-level architecture — internal module structure, data model and indexes, interfaces with timeouts and retries, sequences including failure paths, concurrency and idempotency, configuration, and test strategy. Use after the system shape is agreed and before implementing a non-trivial component.

Decide whether an internal capability warrants an MCP server, then design its tool surface — tool granularity, input schemas, read/write separation, authorization as the calling user, confirmation on destructive tools, audit, and versioning. Use when someone proposes exposing internal services as MCP tools for Claude or internal AI agents.

Define what a service measures and what wakes someone up — SLIs tied to user experience, SLO targets and error budget policy, the baseline RED and USE metrics, burn-rate alerts, and a dashboard that is readable during an incident. Enforces low-cardinality metric labels. Use when defining SLOs, adding metrics or alerts, when the pager is noisy, or before a production readiness review.

Plan OpenTelemetry instrumentation for a service — the spans it emits, resource attributes, context propagation across HTTP and message boundaries, structured logs correlated to traces, sampling, and how the instrumentation gets verified. Use when building a new service, adding a component to a flow, when an incident was hard to diagnose, or before a production readiness review.

Run the production readiness gate before a service's first deploy — verifying design and ADRs, contracts, security, capacity, reliability, observability, metrics and alerting, and operational readiness against evidence rather than assertions, and returning a go / go-with-conditions / no-go verdict. Use before a first production deploy, a go-live, or a major launch.

Work out how a service fails and what it does about it — timeouts, retries with backoff and budgets, idempotency, dead-letter handling, circuit breakers, graceful shutdown, degraded modes, and recovery objectives — producing a failure-mode table with a defined response for each. Use when designing a service, when adding a dependency, after an incident, or before a production readiness review.

Turn a traffic model into concrete capacity decisions — resource requests and limits, replica counts, Kafka partitions, Mongo working set and indexes, Elasticsearch shards, connection pools, and autoscaling triggers — and identify what breaks first under overload. Use when sizing a new service, when load is expected to grow, when something is slow under load, or before a production readiness review.

Decide where a boundary belongs — new service versus new module, how layers depend on each other, and where coupling has crept in — using an explicit cost test rather than taste. Use when asked whether to split or extract a service, when a module has grown unclear, when two components keep changing together, or when reviewing dependency direction.

Choose a technology for a specific need, working within the fixed on-premise platform set (OpenShift, MongoDB, Elasticsearch, RabbitMQ, Kafka, OpenTelemetry) and applying a real cost test to anything outside it. Ends in a human decision and an ADR. Use when choosing between Kafka and RabbitMQ, Mongo and Elasticsearch, or when someone proposes adding a new component, library, or datastore.

Design a component's test strategy and make the SonarQube quality gate winnable honestly — what to test at each level, which exclusions are legitimate, and how to close a coverage gap by testing the untested behaviour rather than gaming the metric. Use when planning tests, when the Sonar gate fails, or when deciding what to exclude from coverage.

Threat model a system or change — trust boundaries, entry points, STRIDE threats with mitigations, secrets handling, the authorization rule written out, data classification, and network posture — producing a document with named owners for anything left open. Use before a new service ships, when adding an entry point or integration, when handling personal or regulated data, or when reviewing anything auth-related.