Merge pull request #152 from 2-Coatl/feature/check-if-changes-are-implemented-06-31-48

Add domain agent catalog alignment and coverage

Author: NestorMonroy

.agent/README.md

@@ -5,14 +5,30 @@ Este directorio concentra la gobernanza operativa de los agentes autónomos del
 ## Relación con la documentación oficial
 - La guía funcional completa se encuentra en `docs/ai/SDLC_AGENTS_GUIDE.md`, donde se documenta el flujo de trabajo esperado para cada agente y cómo coordinarse con el resto del SDLC.
 - Las revisiones consolidadas y lineamientos de documentación están centralizados en `docs/analisis/`, siguiendo lo establecido por el ETA-AGENTE CODEX.
+- El ExecPlan maestro para la orquestación multi-LLM es `docs/plans/EXECPLAN_codex_mcp_multi_llm.md`; la evolución del catálogo por dominio se mantiene en `docs/plans/EXECPLAN_agents_domain_alignment.md`.
 
 ## Relación con los ejecutables
 - Los agentes que ejecutan validaciones automáticas viven en `scripts/coding/ai/agents/` (por ejemplo `scripts/coding/ai/agents/documentation/eta_codex_agent.py`).
 - Sus pruebas unitarias están en `scripts/coding/tests/ai/agents/`, lo que permite garantizar cobertura mínima del 80 % conforme a nuestra política TDD.
+- Los orquestadores y builders multi-LLM residen en `scripts/coding/ai/orchestrators/` y se verifican con `pytest scripts/coding/tests/ai/orchestrators/`.
+
+## Mapa de dominios y agentes
+
+El proyecto está dividido en cinco dominios operativos. Cada uno cuenta con una ficha de agente dedicada en `.agent/agents/` que explica procedimientos, relaciones con ExecPlans y scripts de soporte.
+
+| Dominio | Directorio raíz | Agente principal | ExecPlans y guías clave |
+|---------|-----------------|------------------|-------------------------|
+| Backend (API) | `api/` | ApiAgent (`api_agent.md`) | `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/ai/SDLC_AGENTS_GUIDE.md`, `scripts/coding/ai/orchestrators/codex_mcp_workflow.py` |
+| Frontend (UI) | `ui/` | UiAgent (`ui_agent.md`) | `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/ai_capabilities/prompting/CODE_GENERATION_GUIDE.md` |
+| Infrastructure | `infrastructure/` | InfrastructureAgent (`infrastructure_agent.md`) | `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/gobernanza/metodologias/agentes_automatizacion.md` |
+| Documentación | `docs/` | DocsAgent (`docs_agent.md`) | `docs/analisis/AGENTS.md`, `scripts/coding/ai/agents/documentation/eta_codex_agent.py` |
+| Scripts/Automatización | `scripts/` | ScriptsAgent (`scripts_agent.md`) | `docs/plans/EXECPLAN_codex_mcp_multi_llm.md`, `scripts/coding/ai/generators/llm_generator.py` |
+
+Cada agente de dominio describe cómo coordinarse con los agentes por proveedor (Claude, ChatGPT, Hugging Face) y con los agentes operativos (GitOps, Release, Dependency).
 
 ## Cómo usar este directorio
-1. **Planifica primero**: para cada refactor o feature relevante crea un ExecPlan según `.agent/PLANS.md`.
-2. **Selecciona el agente**: consulta `.agent/agents/README.md` para elegir el agente adecuado o crear uno nuevo.
-3. **Documenta y prueba**: enlaza el ExecPlan desde el issue template correspondiente y asegura que los scripts/pruebas mencionados arriba respalden la automatización.
+1. **Planifica primero**: para cada refactor o feature relevante crea un ExecPlan según `.agent/PLANS.md` y referencia si aplica los planes existentes (`EXECPLAN_codex_mcp_multi_llm.md`, `EXECPLAN_agents_domain_alignment.md`).
+2. **Selecciona el agente**: consulta `.agent/agents/README.md` para elegir el agente por proveedor o por dominio adecuado, o para crear uno nuevo siguiendo el estándar.
+3. **Documenta y prueba**: enlaza el ExecPlan desde el issue template correspondiente y asegura que los scripts/pruebas mencionados arriba respalden la automatización. Captura resultados en `docs/qa/registros/`.
 
-Al mantener este repositorio unificado en `.agent/`, los colaboradores encuentran en un solo lugar la planificación, la documentación de alto nivel y las rutas a los artefactos ejecutables que soportan a cada agente.
+Al mantener este repositorio unificado en `.agent/`, los colaboradores encuentran en un solo lugar la planificación, la documentación de alto nivel y las rutas a los artefactos ejecutables que soportan a cada agente y dominio del proyecto.

.agent/agents/README.md

@@ -38,6 +38,40 @@ Estos agentes vinculan la planificación (`.agent/PLANS.md`), la configuración
   - Scripts: `scripts/coding/ai/generators/llm_generator.py` (`llm_provider="huggingface"`) y `scripts/coding/ai/orchestrators/codex_mcp_workflow.py`.
   - Guías: `docs/ai/SDLC_AGENTS_GUIDE.md`, `docs/ai_capabilities/prompting/PHI3_PROMPT_ENGINEERING_PLAYBOOK.md` y `docs/ai_capabilities/orchestration/CODEX_MCP_MULTI_AGENT_GUIDE.md`.
 
+### Agentes por dominio
+
+Los siguientes agentes conectan la estructura del repositorio (api, ui, infrastructure, docs, scripts) con los ExecPlans y scripts multi-LLM. Cada ficha se encuentra en `.agent/agents/`.
+
+#### ApiAgent (Backend)
+
+- **Archivo**: `api_agent.md`
+- **Directorio base**: `api/`
+- **Relaciones clave**: `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/ai/SDLC_AGENTS_GUIDE.md`, `scripts/coding/ai/orchestrators/codex_mcp_workflow.py`.
+
+#### UiAgent (Frontend)
+
+- **Archivo**: `ui_agent.md`
+- **Directorio base**: `ui/`
+- **Relaciones clave**: `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/ai_capabilities/prompting/CODE_GENERATION_GUIDE.md`, `docs/ai_capabilities/prompting/PHI3_PROMPT_ENGINEERING_PLAYBOOK.md`.
+
+#### InfrastructureAgent
+
+- **Archivo**: `infrastructure_agent.md`
+- **Directorio base**: `infrastructure/`
+- **Relaciones clave**: `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/gobernanza/metodologias/agentes_automatizacion.md`, planes `SPEC_INFRA_*`.
+
+#### DocsAgent
+
+- **Archivo**: `docs_agent.md`
+- **Directorio base**: `docs/`
+- **Relaciones clave**: `docs/analisis/AGENTS.md`, `scripts/coding/ai/agents/documentation/eta_codex_agent.py`, `docs/testing/test_documentation_alignment.py`.
+
+#### ScriptsAgent
+
+- **Archivo**: `scripts_agent.md`
+- **Directorio base**: `scripts/`
+- **Relaciones clave**: `docs/plans/EXECPLAN_codex_mcp_multi_llm.md`, `docs/scripts/README.md`, `scripts/coding/ai/generators/llm_generator.py`.
+
 ### 1. GitOpsAgent
 
 **Archivo**: `gitops_agent.md`
@@ -439,6 +473,6 @@ Ver estadísticas en: `docs/qa/registros/metricas_agentes.md` (si existe)
 
 ---
 
-**Última actualización**: 2025-11-05
-**Total de agentes**: 5
-**Versión de documentación**: 1.0.0
+**Última actualización**: 2025-11-06
+**Total de agentes**: 14
+**Versión de documentación**: 1.2.0

.agent/agents/api_agent.md

@@ -0,0 +1,32 @@
+# ApiAgent
+
+## Propósito
+
+Guiar cualquier automatización relacionada con el backend (`api/`) asegurando que la planificación, la selección de LLMs y los scripts de soporte sigan los ExecPlans vigentes. ApiAgent actúa como punto de unión entre los agentes por proveedor y los runbooks de infraestructura de la API.
+
+## Integraciones Clave
+
+- **ExecPlans**: `docs/plans/EXECPLAN_agents_domain_alignment.md` (relación dominio ↔ agentes) y `docs/plans/EXECPLAN_codex_mcp_multi_llm.md` (estrategia multi-LLM).
+- **Guías SDLC**: `docs/ai/SDLC_AGENTS_GUIDE.md` y `docs/ai_capabilities/orchestration/CODEX_MCP_MULTI_AGENT_GUIDE.md` para coordinación multi-agente.
+- **Scripts**: `scripts/coding/ai/orchestrators/codex_mcp_workflow.py` (briefs de trabajo) y `scripts/coding/ai/generators/llm_generator.py` (TDD asistido).
+- **Config**: variables en `.env` gestionadas por `scripts/coding/ai/shared/env_loader.py` (autodetección de `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `HUGGINGFACEHUB_API_TOKEN`).
+- **Infraestructura API**: pipelines documentados en `infrastructure/` y runbooks en `docs/operaciones/`.
+
+## Procedimiento Recomendado
+
+1. **Planificación**: crea o actualiza el ExecPlan del cambio siguiendo `.agent/PLANS.md`. Referencia explícita al agente proveedor (ClaudeAgent, ChatGPTAgent, HuggingFaceAgent) que soportará la implementación.
+2. **Selección de LLM**: usa `CodexMCPWorkflowBuilder` para generar briefs ajustados al proveedor elegido y habilita MCP si se requiere colaboración multi-agente.
+3. **Desarrollo guiado por TDD**:
+    - Genera pruebas con `LLMGenerator` y `pytest` antes de modificar código en `api/`.
+    - Ejecuta suites específicas (`pytest api/tests` o equivalentes) tras cada iteración Red→Green→Refactor.
+4. **Documentación**: actualiza el ExecPlan (`Progress`, `Decision Log`, `Surprises`) y registra resultados en `docs/qa/registros/`.
+5. **Release**: coordina con `GitOpsAgent` o `ReleaseAgent` según corresponda para despliegues y tagging.
+
+## Validación
+
+- `pytest scripts/coding/tests/ai/orchestrators/test_codex_mcp_workflow.py`
+- `pytest scripts/coding/tests/ai/generators/test_llm_generator.py`
+- `pytest docs/testing/test_documentation_alignment.py`
+- Suites de backend (`pytest api/tests` o equivalentes definidos en el ExecPlan específico).
+
+ApiAgent garantiza que cada modificación al backend se ejecute con planificación trazable, soporte multi-LLM y validaciones consistentes con las políticas del repositorio.

.agent/agents/docs_agent.md

@@ -0,0 +1,29 @@
+# DocsAgent
+
+## Propósito
+
+Garantizar que los cambios en `docs/` sigan la gobernanza del ETA-AGENTE CODEX y que la documentación permanezca alineada con los ExecPlans y agentes ejecutables. DocsAgent coordina con los agentes por proveedor para automatizar redacciones, manteniendo la traza con los validadores documentales.
+
+## Integraciones Clave
+
+- **Agente rector**: `docs/analisis/AGENTS.md` (ETA-AGENTE CODEX) y `scripts/coding/ai/agents/documentation/eta_codex_agent.py`.
+- **ExecPlans**: `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/plans/EXECPLAN_codex_mcp_multi_llm.md`.
+- **Pruebas**: `docs/testing/test_documentation_alignment.py` asegura consistencia de enlaces y ubicación.
+- **Playbooks**: `docs/ai_capabilities/orchestration/CODEX_MCP_MULTI_AGENT_GUIDE.md`, `docs/ai_capabilities/prompting/CODE_GENERATION_GUIDE.md`.
+
+## Procedimiento Recomendado
+
+1. **Planificación**: antes de modificar documentación, produce un ExecPlan y verifica las reglas del ETA-AGENTE CODEX.
+2. **Automatización**:
+    - Usa `CodexMCPWorkflowBuilder` o `LLMGenerator` para preparar borradores siguiendo la sección "Planificación" del ExecPlan.
+    - Refuerza auto-CoT y Self-Consistency incorporando citas y validaciones que los tests puedan inspeccionar.
+3. **Validadores**: ejecuta `pytest docs/testing/test_documentation_alignment.py` y, si aplica, pruebas asociadas a agentes (por ejemplo, `pytest scripts/coding/tests/ai/agents/documentation/test_eta_codex_agent.py`).
+4. **Registro**: documenta hallazgos en el ExecPlan y añade referencias en índices (`docs/index.md`, `docs/ai/SDLC_AGENTS_GUIDE.md`) cuando corresponda.
+
+## Validación
+
+- `pytest docs/testing/test_documentation_alignment.py`
+- `pytest scripts/coding/tests/ai/agents/documentation/test_eta_codex_agent.py`
+- Otros tests específicos declarados en el ExecPlan (por ejemplo, validadores de enlaces o generadores de documentación).
+
+DocsAgent mantiene la documentación coherente con los agentes automatizados y con la política de revisiones consolidadas del proyecto.

.agent/agents/infrastructure_agent.md

@@ -0,0 +1,29 @@
+# InfrastructureAgent
+
+## Propósito
+
+Coordinar automatizaciones relacionadas con `infrastructure/`, incluyendo IaC, pipelines y configuración de entornos. InfrastructureAgent vincula la planificación ExecPlan con los agentes de dependencias, seguridad y despliegue para evitar desviaciones entre infraestructura y servicios consumidos por los LLMs.
+
+## Integraciones Clave
+
+- **ExecPlans**: `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/plans/EXECPLAN_codex_mcp_multi_llm.md` y los planes específicos de infraestructura (`docs/plans/SPEC_INFRA_*.md`).
+- **Gobernanza**: `docs/gobernanza/metodologias/agentes_automatizacion.md` y runbooks en `docs/operaciones/`.
+- **Agentes complementarios**: `DependencyAgent` para escaneos de paquetes, `ReleaseAgent` para coordinaciones de despliegue, `SecurityAgent` (si aplica) para hardening.
+- **Scripts**: `scripts/infrastructure/` (si existe) y pipelines en `infrastructure/`.
+
+## Procedimiento Recomendado
+
+1. **Planificación**: registra en el ExecPlan cómo impactará el cambio en IaC, entornos y credenciales. Determina si se requiere coordinación multi-LLM (por ejemplo, despliegues de servicios MCP).
+2. **Validación previa**: ejecuta `DependencyAgent` o `SecurityAgent` cuando haya cambios en toolchains, contenedores o runtime.
+3. **Implementación**:
+    - Usa `CodexMCPWorkflowBuilder` para generar briefs que automaticen actualización de manifiestos o pipelines, asegurando que el sandbox MCP cuente con permisos apropiados.
+    - Mantén los archivos de configuración bajo control TDD mediante tests de `scripts/tests/` o validaciones específicas (por ejemplo, `terraform validate`, `ansible-lint`).
+4. **Documentación**: actualiza ExecPlan y registra resultados en `docs/qa/registros/` indicando entornos afectados.
+
+## Validación
+
+- `pytest docs/testing/test_documentation_alignment.py`
+- `pytest scripts/coding/tests/ai/orchestrators/test_codex_mcp_workflow.py`
+- Herramientas de IaC declaradas en el ExecPlan (`terraform validate`, `ansible-lint`, `kubectl diff`, etc.).
+
+InfrastructureAgent asegura que los cambios de infraestructura permanezcan sincronizados con la planificación multi-LLM y con las políticas de seguridad y gobernanza del repositorio.

.agent/agents/scripts_agent.md

@@ -0,0 +1,30 @@
+# ScriptsAgent
+
+## Propósito
+
+Orquestar cambios en `scripts/` garantizando que las automatizaciones, generadores y validadores permanezcan sincronizados con los ExecPlans multi-LLM y con las pruebas de regresión. ScriptsAgent sirve como guía para extender herramientas CLI, validadores y pipelines internos.
+
+## Integraciones Clave
+
+- **ExecPlans**: `docs/plans/EXECPLAN_agents_domain_alignment.md`, `docs/plans/EXECPLAN_codex_mcp_multi_llm.md`.
+- **Código**: `scripts/coding/ai/` (generators, orchestrators, shared utilities) y `scripts/tests/`.
+- **Pruebas**: `pytest scripts/coding/tests/...` y `pytest scripts/tests/...`.
+- **Documentación**: `docs/scripts/README.md`, `docs/scripts/SCRIPTS_MATRIX.md` y `docs/operaciones/verificar_servicios.md`.
+
+## Procedimiento Recomendado
+
+1. **Planificación**: identifica en el ExecPlan qué scripts serán modificados/creados, qué agentes los consumirán y qué cobertura de pruebas se requiere.
+2. **Implementación TDD**:
+    - Redacta pruebas en `scripts/coding/tests/...` antes de modificar los scripts correspondientes.
+    - Usa `LLMGenerator` cuando se necesiten esbozos iniciales, siempre asegurando iteraciones Red→Green→Refactor.
+3. **Orquestación multi-LLM**: utiliza `CodexMCPWorkflowBuilder` para generar briefs que coordinen agentes y aseguren políticas MCP (`approval-policy`, `sandbox`).
+4. **Documentación**: registra nuevas utilidades en `docs/scripts/README.md` y en la matriz de scripts. Actualiza ExecPlan y `docs/qa/registros/` con resultados de pruebas.
+
+## Validación
+
+- `pytest scripts/coding/tests/ai/orchestrators/test_codex_mcp_workflow.py`
+- `pytest scripts/coding/tests/ai/generators/test_llm_generator.py`
+- `pytest docs/testing/test_documentation_alignment.py`
+- Otras suites específicas (`pytest scripts/tests/test_*.py`, `bash scripts/tests/...`).
+
+ScriptsAgent asegura que la carpeta `scripts/` evolucione con disciplina TDD, manteniendo alineada la automatización interna con los agentes y ExecPlans vigentes.

.agent/agents/ui_agent.md

@@ -0,0 +1,31 @@
+# UiAgent
+
+## Propósito
+
+Alinear el trabajo automatizado sobre el frontend (`ui/`) con las prácticas de diseño, pruebas y despliegue descritas en nuestros ExecPlans y guías de prompting. UiAgent sirve como guía única para combinar planificación, generación asistida de código y validaciones de experiencia de usuario.
+
+## Integraciones Clave
+
+- **ExecPlans**: `docs/plans/EXECPLAN_agents_domain_alignment.md` y `docs/plans/EXECPLAN_codex_mcp_multi_llm.md`.
+- **Playbooks**: `docs/ai_capabilities/prompting/CODE_GENERATION_GUIDE.md` y `docs/ai_capabilities/prompting/PHI3_PROMPT_ENGINEERING_PLAYBOOK.md`.
+- **Orquestación**: `scripts/coding/ai/orchestrators/codex_mcp_workflow.py` (multi-agente) y `scripts/coding/ai/generators/llm_generator.py` (generación guiada por TDD).
+- **Documentación UX**: briefs y wireframes creados por el Designer Agent se ubican en `docs/` o `design/` según el ExecPlan activo.
+
+## Procedimiento Recomendado
+
+1. **Planificación**: crea ExecPlan conforme a `.agent/PLANS.md` identificando componentes UI afectados y experimentos a realizar (por ejemplo, wireframes asistidos por LLM).
+2. **Diseño + Desarrollo**:
+    - Coordina con Designer Agent para obtener `design_spec.md` y wireframes.
+    - Usa `CodexMCPWorkflowBuilder` con `llm_provider` correspondiente para producir briefs que generen HTML/CSS/JS siguiendo las especificaciones.
+    - Aplica TDD generando pruebas end-to-end o unitarias con `LLMGenerator` si procede.
+3. **Pruebas visuales**: registra capturas o instrucciones en `docs/qa/registros/` y, si el cambio es visual, adjunta evidencia conforme a la política de screenshots.
+4. **Documentación**: actualiza ExecPlan (`Progress`, `Decision Log`) y enlaza resultados desde `docs/ai/SDLC_AGENTS_GUIDE.md` si se introduce un nuevo patrón.
+
+## Validación
+
+- `pytest scripts/coding/tests/ai/orchestrators/test_codex_mcp_workflow.py`
+- `pytest scripts/coding/tests/ai/generators/test_llm_generator.py`
+- `pytest docs/testing/test_documentation_alignment.py`
+- Suites front-end (`npm test`, `pnpm vitest`, etc.) según el stack declarado en el ExecPlan.
+
+UiAgent permite mantener el frontend consistente con las guías de diseño, asegurando que la colaboración multi-LLM se refleje en entregables reproducibles y probados.

docs/ai/SDLC_AGENTS_GUIDE.md

@@ -134,6 +134,18 @@ Para asegurar coherencia entre planificación, credenciales y herramientas, cons
 
 Estas fichas son complementarias a esta guía y deben revisarse antes de ejecutar tareas multi-LLM.
 
+### Agentes por dominio
+
+Para alinear la arquitectura del repositorio con los agentes automatizados, consulta también las fichas por dominio en `.agent/agents/`:
+
+- **ApiAgent** (`api_agent.md`): centraliza la coordinación del backend (`api/`) con los ExecPlans `EXECPLAN_agents_domain_alignment.md` y `EXECPLAN_codex_mcp_multi_llm.md`, además de los briefs generados por `CodexMCPWorkflowBuilder`.
+- **UiAgent** (`ui_agent.md`): une los entregables del Designer Agent con la implementación en `ui/`, reutilizando los playbooks de prompting (`CODE_GENERATION_GUIDE.md`, `PHI3_PROMPT_ENGINEERING_PLAYBOOK.md`).
+- **InfrastructureAgent** (`infrastructure_agent.md`): orquesta cambios en `infrastructure/` en conjunto con los agentes operativos (Dependency, Release, Security) y los planes `SPEC_INFRA_*`.
+- **DocsAgent** (`docs_agent.md`): asegura que toda modificación en `docs/` respete al ETA-AGENTE CODEX y a los validadores de documentación.
+- **ScriptsAgent** (`scripts_agent.md`): gobierna la evolución de `scripts/` manteniendo el enfoque TDD y sincronización con los generadores/orquestadores LLM.
+
+Cada vez que inicies un ExecPlan nuevo, referencia tanto la ficha del proveedor LLM como la del dominio involucrado para mantener la trazabilidad completa.
+
 ### 1. SDLCFeasibilityAgent
 
 **Propósito:** Evalúa la viabilidad técnica de una feature antes de implementarla.