Flujo de agentes — política mandatoria

Las 6 reglas duras

1 · Ningún cambio de auth se mergea sin `security` agent

Lo que cuenta como “cambio de auth”:

Modificaciones al middleware tenancy (shared-libs/go-bjungle-tenancy)
Cambios en schemas de auth (api_keys, wallets, wallet_passkeys, step_up_tokens, webauthn_challenges, tenant_operators)
Endpoints nuevos que reciben Bearer / cookie / X-API-Key
Cambios en bearerAuth, requireBootstrapToken, requireInternalToken
Cualquier modificación a audit_log, rate_limit_buckets
Cualquier flow nuevo de bmonkey que toque face_match, sarlaft, consent, OTP

2 · Ningún feature de backend Go se mergea sin `backend-dev`

Excepciones:

Doc-only changes (*.mdx, *.md)
Migraciones simples sin cambio de service layer
Configuraciones (Makefile, docker-compose)

Cuando aplica:

Cualquier endpoint nuevo
Repos nuevos o métodos nuevos de un repo
Servicios nuevos o cambio de lógica de negocio
Tests integration

3 · Ningún cambio de UI se mergea sin `ux-ui` + type-check

Lo que cuenta:

Páginas nuevas en platform/frontend/* o website/digital-jungle-site/
Componentes nuevos que el usuario ve
Cambios de copy de errores / éxito
Mobile screens

4 · Ningún PR se mergea sin tests por `qa`

Mínimo:

1 happy path test (unit o integration)
2 unhappy paths (rejected input, server error)
E2E si el feature toca UI crítica del wallet o portal

5 · Toda decisión arquitectónica importante = ADR

Lo que cuenta como “arquitectónica”:

Nuevo módulo top-level
Cambio del modelo de auth / autorización
Cambio de almacenamiento de PII / claves
Nueva integración externa (KMS, payment provider, OAuth provider)
Cambio de pricing / Açaí flow

6 · Cualquier cambio AWS discutido con `tech-lead` ANTES + Well-Architected + ahorro

Lo que cuenta como “cambio AWS”:

Nuevo recurso AWS (KMS, S3, RDS, ECS, IAM, etc.)
Cambio de IAM policy (incluso agregar 1 statement)
Cambio de Terraform module o creación de uno nuevo
Cambio de azure-pipelines/*.yml o azure-pipelines.yml raíz
Cambio de service connection / variable group en Azure DevOps
Cualquier terraform apply a producción

Flujo obligatorio:

infra-architect agent prepara propuesta con:
- Recursos a crear/modificar con tabla
- Costo proyectado en USD/mes (cost optimization pillar)
- IAM least-privilege documentado (security pillar)
- Plan de reverso (operational excellence pillar)
- Blast radius + failure modes (reliability pillar)
- Alternativas más baratas evaluadas (performance vs cost trade-off)
tech-lead revisa contra AWS Well-Architected Framework (5 pilares: Operational Excellence, Security, Reliability, Performance Efficiency, Cost Optimization) — discusión escrita en el PR / commit body
Solo después de la luz verde del tech-lead, terraform apply o merge del pipeline change

Tabla de roles

Rol	Responsabilidad	Modelo
`tech-lead`	ADRs, plan, dependency graph, qué va al sprint, Well-Architected review	opus
`backend-dev`	Implementa Go (services, repos, handlers, tests integration)	sonnet
`frontend-dev`	Implementa React/Astro (pages, components, type-check)	sonnet
`security`	Review de todo cambio de auth + pen-tests	sonnet
`qa`	Tests unit/integration/E2E, smoke regressions	sonnet
`ux-ui`	Revisar UI antes de mergear, copy, accesibilidad	sonnet
`infra-architect`	AWS IaC + Azure DevOps Pipelines + IAM + cost-aware design	sonnet

Cuándo invocar cada agente

`security`

Agent · security  con prompt:
  "Pen-test focal del PR <link>. Specific scope: <archivos>."

Casos típicos: cambio de auth, nuevo endpoint con Bearer, modificación de audit_log o rate_limit, nuevo flow de bmonkey con biometría u OTP.

`backend-dev`

Agent · backend-dev  con prompt:
  "Review + completar implementación de <feature>. Checklist:
   - GOWORK=off go build ./... verde
   - tests integration cobrando los happy + 2 unhappy paths
   - audit log writes (si aplica)
   - error mapping a HTTP correcto"

`ux-ui`

Agent · ux-ui  con prompt:
  "Review UI de <feature>. Específico:
   - jerarquía visual + accesibilidad ARIA
   - copy en español de Colombia, no genérico
   - estados loading / error / empty cubiertos
   - mobile breakpoints"

`qa`

Agent · qa  con prompt:
  "Tests para <feature>. Target coverage:
   - Unit tests: happy + edge cases
   - Integration: roundtrip contra postgres dev
   - E2E (si aplica): smoke en scripts/e2e/specs/<spec>.spec.ts
   Outcome: GOWORK=off go test ./... + make e2e verdes."

`infra-architect`

Agent · infra-architect  con prompt:
  "Diseñar/revisar <recurso AWS> para <caso de uso>.
   Constraints:
   - Cost optimization first
   - IAM least-privilege (no '*' en Action o Resource)
   - Blast radius mínimo
   - Reversibilidad con terraform destroy
   - Alternativas más baratas evaluadas y descartadas con justificación"

Después:
Agent · tech-lead  con prompt:
  "Review Well-Architected de la propuesta <link>. Validar 5 pilares.
   ¿Hay alternativa más barata? ¿Está justificado el costo?"

El agente `infra-architect`

Rol nuevo (creado en 2026-05-30). Spec completa en .claude/agents/infra-architect.md.

Atributo	Valor
Nombre	`infra-architect`
Modelo	sonnet
Activar en	Cualquier feature que requiera recurso AWS nuevo; cambio a `azure-pipelines/*.yml`; cambio de IAM; discusión “movemos X de Y a Z” cuando Z es infraestructura
Scope	AWS IaC (Terraform) + Azure DevOps Pipelines + IAM + cost-aware provisioning
NO scope	Application code (Go, React) — ese trabajo es de `backend-dev` / `frontend-dev`

Flujo infra-architect → tech-lead (Regla #6 obligatorio)

infra-architect prepara propuesta Well-Architected
         │
         ▼
tech-lead (opus) revisa 5 pilares + costo
         │
         ├── ✅ luz verde escrita → terraform apply / merge pipeline
         └── ❌ cambios pedidos → infra-architect revisa → vuelta a tech-lead

Su prime directive

“What’s the cheapest, smallest-blast-radius way to accomplish this that still meets the SLA?”

Si la respuesta es “una Lambda” en vez de “una task ECS dedicada” → propone Lambda. Si la respuesta es “reusar un role existente con un inline policy nuevo” → lo propone con el trade-off documentado.

Checklist pre-commit

Antes de cualquier git commit que toque más que docs:

☐ ¿Cambia auth?         → security agent invocado y respondió
☐ ¿Cambia backend Go?   → backend-dev agent invocado
☐ ¿Cambia UI?           → ux-ui agent invocado + npm run type-check verde
☐ ¿Hay tests nuevos?    → qa agent invocado o tests añadidos
☐ ¿Es arquitectónico?   → ADR en estado Accepted antes de commit
☐ ¿Hay migration nueva? → aplicada en dev + back-fill probado
☐ ¿Build verde?         → GOWORK=off go build ./... sin errors
☐ ¿Cambia AWS / IaC?    → infra-architect + tech-lead aprobaron primero

Anti-patrones que esta política previene

Anti-patrón	Por qué es peligroso
”Es chiquito, lo hago yo”	Los bugs de seguridad más críticos del wallet SSI (BMK-PT-01..04) aparecieron exactamente así
”El UI no tiene tests porque es simple”	Los locators frágiles se detectan solo cuando Playwright corre
”ADR después, código primero”	Cuando el código existe primero, la decisión se cristaliza alrededor de lo ya hecho
”Aplico el terraform directamente — es una línea”	La historia muestra que los costos AWS suben silenciosamente cuando se saltea el handshake

Excepciones explícitas

Caso	Qué se permite saltar
Hot-fix de producción	qa formal (corre smoke manual + commit con `hotfix:`)
Cambio doc-only	backend-dev, frontend-dev (pero NUNCA security si la doc describe auth)
Migración de schema reversible	backend-dev (pero NUNCA security si toca tablas de auth)
Refactor sin cambio de comportamiento observable	qa formal (pero los tests existentes deben seguir pasando)

Flujo de agentes — política mandatoria

Las 6 reglas duras

1 · Ningún cambio de auth se mergea sin security agent

2 · Ningún feature de backend Go se mergea sin backend-dev

3 · Ningún cambio de UI se mergea sin ux-ui + type-check

4 · Ningún PR se mergea sin tests por qa