Skip to content

Commit b17b754

Browse files
2-Coatl2-Coatl
authored
Merge pull request #169 from 2-Coatl/feature/implement-hamilton-framework-with-sdlc-11-53-17
Add Codex MCP workspace playbooks
2 parents 7ff7ebe + fffecf8 commit b17b754

10 files changed

Lines changed: 659 additions & 4 deletions

File tree

‎docs/EXECPLAN_codex_mcp_workspace.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# ExecPlan: Integrar playbooks Codex MCP en el workspace de infraestructura
2+
3+
Esta ExecPlan es un documento vivo; debe actualizarse durante la implementación según `.agent/PLANS.md`.
4+
5+
## Purpose / Big Picture
6+
7+
Incorporar un workspace autocontenible que documente y codifique la integración de Codex CLI como servidor MCP, junto con playbooks para sistemas mono-agente y multi-agente que usan el Agents SDK. La meta es que el repositorio disponga de artefactos reproducibles (código + pruebas + documentación) que muestren cómo orquestar estos agentes sin depender de llamadas externas durante la ejecución de CI.
8+
9+
## Progress
10+
11+
- [x] (2025-11-20 15:30Z) ExecPlan creado con alcance inicial y validaciones esperadas.
12+
- [x] (2025-11-20 16:05Z) Pruebas TDD escritas en `infrastructure/workspace/tests/codex_mcp/test_playbooks.py` y actualización del registro estructural.
13+
- [x] (2025-11-20 16:30Z) Implementación del módulo `infrastructure/workspace/codex_mcp/` con blueprints declarativos.
14+
- [x] (2025-11-20 16:45Z) Documentación y registros actualizados (`docs/index.md`, `docs/infraestructura/workspace/README.md`, `docs/infraestructura/workspace/codex_mcp.md`, `infrastructure/workspace/__init__.py`).
15+
- [x] (2025-11-20 17:00Z) Validaciones ejecutadas (`pytest` del workspace completo y prueba documental dirigida) con resultados documentados.
16+
17+
## Surprises & Discoveries
18+
19+
- Ajuste requerido: las instrucciones de los agentes deben incluir exactamente la cadena `"sandbox": "workspace-write"` con espacios para cumplir la política documentada y las expectativas de los tests.
20+
Evidence: Primera ejecución de las pruebas falló hasta normalizar el formato de la cadena Codex MCP.
21+
22+
## Decision Log
23+
24+
- Decision: Representar servidores y agentes como dataclasses inmutables y construir playbooks declarativos en lugar de scripts ejecutables.
25+
Rationale: Evita dependencias externas (`openai-agents`, `codex`) durante la ejecución de CI, pero mantiene la trazabilidad de configuraciones y handoffs descrita por el stakeholder.
26+
Date/Author: 2025-11-20 / coding-agent
27+
28+
## Outcomes & Retrospective
29+
30+
- El workspace Codex MCP quedó alineado al árbol `infrastructure/workspace/` con documentación y pruebas TDD.
31+
- La guía de infraestructura refleja la disponibilidad del nuevo playbook junto a Hamilton y Dev Tools.
32+
- Restan correr las validaciones finales del plan antes de cerrarlo.
33+
34+
## Context and Orientation
35+
36+
La guía entregada por el stakeholder describe paso a paso cómo levantar Codex CLI como servidor MCP, definir agentes especializados y orquestar flujos mono y multi-agente con el Agents SDK, incluyendo requisitos de entorno y trazabilidad. Actualmente el repositorio no refleja estos playbooks; sí cuenta con un workspace Hamilton (`infrastructure/workspace/hamilton_llm`) y herramientas de lenguaje (`infrastructure/workspace/dev_tools`).
37+
38+
Integraremos el contenido en `infrastructure/workspace/codex_mcp/` como código Python basado en dataclasses que represente la configuración declarativa de servidores y agentes. Las pruebas vivirán en `infrastructure/workspace/tests/codex_mcp/`, siguiendo el patrón de TDD establecido.
39+
40+
## Plan of Work
41+
42+
1. Crear pruebas unitarias que describan:
43+
- La configuración del servidor MCP (`command`, `args`, timeout) y su asociación a los agentes.
44+
- El contenido crítico de las instrucciones (por ejemplo, `approval-policy`, `workspace-write`, uso del `RECOMMENDED_PROMPT_PREFIX`).
45+
- La secuencia de handoffs y artefactos requeridos en el flujo multi-agente.
46+
2. Implementar dataclasses y funciones en `infrastructure/workspace/codex_mcp/playbooks.py` expuestas vía `__init__.py`.
47+
3. Registrar el nuevo workspace en `infrastructure.workspace.TEST_SUITES` y exportarlo en `__all__`.
48+
4. Actualizar documentación relevante (`docs/infraestructura/workspace/README.md`, índice general y guías de gobernanza si aplica).
49+
5. Ejecutar pytest sobre el nuevo paquete y las pruebas de documentación pertinentes.
50+
6. Completar las secciones de progreso, decisiones y hallazgos del ExecPlan.
51+
52+
## Concrete Steps
53+
54+
1. Añadir archivo `infrastructure/workspace/tests/codex_mcp/test_playbooks.py` con casos para servidor, agentes y handoffs.
55+
2. Ejecutar `python3 -m pytest infrastructure/workspace/tests/codex_mcp/test_playbooks.py` para observar el fallo inicial (Red).
56+
3. Implementar `infrastructure/workspace/codex_mcp/__init__.py` y `playbooks.py` satisfaciendo los tests.
57+
4. Ajustar `infrastructure/workspace/__init__.py` y `infrastructure/workspace/tests/test_registry.py` para registrar el workspace.
58+
5. Actualizar documentación y volver a ejecutar las suites relevantes (Green) antes de refactorizar.
59+
60+
## Validation and Acceptance
61+
62+
Se considerará completo cuando:
63+
- `python3 -m pytest infrastructure/workspace/tests/codex_mcp/test_playbooks.py` pase sin fallos.
64+
- `python3 -m pytest infrastructure/workspace/tests` incluya el workspace Codex sin romper las suites existentes.
65+
- La documentación de infraestructura describa el workspace y la guía de gobierno enlace el recurso cuando corresponda.
66+
67+
## Idempotence and Recovery
68+
69+
Los playbooks serán representaciones declarativas sin efectos secundarios. Ejecutar las pruebas no generará archivos externos ni requerirá conexiones a servicios. Ante fallos, basta con revertir cambios en el módulo y reejecutar `pytest`.
70+
71+
## Artifacts and Notes
72+
73+
- `python3 -m pytest infrastructure/workspace/tests/codex_mcp/test_playbooks.py`
74+
- `python3 -m pytest infrastructure/workspace/tests`
75+
- `python3 -m pytest docs/qa/testing/test_documentation_alignment.py::test_hamilton_framework_integration_doc_is_published`
76+
77+
## Interfaces and Dependencies
78+
79+
El módulo expondrá funciones y dataclasses puramente locales, sin dependencias externas al repositorio. Se espera que otras herramientas puedan consumir la metadata retornada para generar scripts reales si así se decide en el futuro.

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ Este índice combina lo implementado con la visión futura del proyecto, clarame
8989
- **Gestión de contexto multi-LLM**: [`ai_capabilities/orchestration/CONTEXT_MANAGEMENT_PLAYBOOK.md`](ai_capabilities/orchestration/CONTEXT_MANAGEMENT_PLAYBOOK.md) y módulo reutilizable [`scripts/coding/ai/shared/context_sessions.py`](../scripts/coding/ai/shared/context_sessions.py).
9090
- **Hamilton Data→Prompt→LLM ejemplo**: [`infrastructure/workspace/hamilton_llm/`](../infrastructure/workspace/hamilton_llm/) con pruebas [`infrastructure/workspace/tests/hamilton_llm/test_driver.py`](../infrastructure/workspace/tests/hamilton_llm/test_driver.py).
9191
- **Hamilton Language Server (Dev Tools)**: [`infrastructure/workspace/dev_tools/language_server/hamilton_lsp/`](../infrastructure/workspace/dev_tools/language_server/hamilton_lsp/) con pruebas [`infrastructure/workspace/tests/dev_tools/language_server/test_hamilton_lsp.py`](../infrastructure/workspace/tests/dev_tools/language_server/test_hamilton_lsp.py).
92+
- **Codex MCP Playbooks**: [`infrastructure/workspace/codex_mcp/`](../infrastructure/workspace/codex_mcp/) y guía [`docs/infraestructura/workspace/codex_mcp.md`](infraestructura/workspace/codex_mcp.md) con validaciones [`infrastructure/workspace/tests/codex_mcp/test_playbooks.py`](../infrastructure/workspace/tests/codex_mcp/test_playbooks.py).
9293

9394
#### [PLANIFICADO] Planificados (ver [`docs/scripts/README.md`](scripts/README.md))
9495
- `scripts/sdlc_agent.py` - CLI SDLC

‎docs/infraestructura/workspace/README.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,26 @@ python3 -m pytest infrastructure/workspace/tests/dev_tools/language_server/test_
3737

3838
Las pruebas cubren el registro de features LSP, la construcción del grafo al abrir documentos, los comandos de visualización y la extracción de símbolos.
3939

40+
## Codex MCP Playbooks
41+
42+
- **Código**: `infrastructure/workspace/codex_mcp/`
43+
- **Pruebas**: `infrastructure/workspace/tests/codex_mcp/test_playbooks.py`
44+
- **Documentación**: [`codex_mcp.md`](codex_mcp.md)
45+
46+
El workspace Codex MCP define blueprints declarativos para:
47+
48+
1. Inicializar Codex CLI como servidor MCP (`npx -y codex mcp`).
49+
2. Ejecutar un flujo mono-agente (Designer → Developer) con políticas `workspace-write` automáticas.
50+
3. Orquestar el equipo multi-agente (Project Manager, Designer, Frontend, Backend, Tester) con handoffs gateados.
51+
52+
### Cómo validarlo
53+
54+
```bash
55+
python3 -m pytest infrastructure/workspace/tests/codex_mcp/test_playbooks.py
56+
```
57+
58+
Las pruebas comprueban el blueprint del servidor, la presencia de las políticas Codex MCP, las secuencias de handoffs y los deliverables esperados por cada rol.
59+
4060
## Registro de suites
4161

42-
Para verificar la alineación estructural del workspace, se expone `infrastructure/workspace/tests/test_registry.py`, que afirma la presencia de `TEST_SUITES` en el paquete raíz y que ambos workspaces quedan registrados para futuras automatizaciones.
62+
Para verificar la alineación estructural del workspace, se expone `infrastructure/workspace/tests/test_registry.py`, que afirma la presencia de `TEST_SUITES` en el paquete raíz y que todos los workspaces quedan registrados para futuras automatizaciones.

‎docs/infraestructura/workspace/codex_mcp.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
id: DOC-INFRA-WORKSPACE-CODEX-MCP
3+
estado: borrador
4+
propietario: equipo-infraestructura
5+
ultima_actualizacion: 2025-11-20
6+
relacionados: ["DOC-INFRA-INDEX", "EXECPLAN_codex_mcp_workspace"]
7+
---
8+
# Workspace Codex MCP
9+
10+
Este workspace documenta cómo inicializar Codex CLI como servidor MCP y cómo orquestar agentes con el Agents SDK siguiendo el flujo presentado por OpenAI.
11+
12+
## 1. Prerrequisitos
13+
14+
- **Variable de entorno**: crear un archivo `.env` con `OPENAI_API_KEY`.
15+
- **Dependencias**: instalar `openai-agents` y `openai` en el entorno activo.
16+
```bash
17+
%pip install openai-agents openai
18+
```
19+
- **IDE recomendado**: VS Code o Cursor para aprovechar integraciones MCP.
20+
21+
## 2. Servidor MCP
22+
23+
El blueprint `codex_cli_server_blueprint()` expuesto por `infrastructure.workspace.codex_mcp` describe el comando canónico:
24+
25+
```python
26+
from infrastructure.workspace.codex_mcp import codex_cli_server_blueprint
27+
28+
server = codex_cli_server_blueprint()
29+
print(server.command, server.args, server.client_session_timeout_seconds)
30+
```
31+
32+
Este blueprint inicia `npx -y codex mcp` con timeout extendido a 360000 segundos para permitir ejecuciones largas.
33+
34+
## 3. Sistema mono-agente
35+
36+
La función `single_agent_system()` genera la configuración Designer → Developer:
37+
38+
- **Designer**: crea un brief de 3 frases y transfiere la tarea.
39+
- **Developer**: implementa `index.html` usando Codex con `{"approval-policy": "never", "sandbox": "workspace-write"}` para persistir archivos sin pedir autorización.
40+
41+
```python
42+
from infrastructure.workspace.codex_mcp import single_agent_system
43+
44+
system = single_agent_system()
45+
print(system.entrypoint) # Game Designer
46+
print(system.expected_artifacts) # ('index.html',)
47+
```
48+
49+
## 4. Orquestación multi-agente
50+
51+
`multi_agent_workflow()` modela al Project Manager y el equipo especializado:
52+
53+
1. **Project Manager** redacta `REQUIREMENTS.md`, `TEST.md`, `AGENT_TASKS.md` y controla los handoffs.
54+
2. **Designer** produce `/design/design_spec.md` y `/design/wireframe.md`.
55+
3. **Frontend** genera `/frontend/index.html`, `styles.css`, `game.js`.
56+
4. **Backend** implementa `/backend/server.js` y `package.json` (sin base de datos externa).
57+
5. **Tester** documenta `/tests/TEST_PLAN.md` y `test.sh`.
58+
59+
Cada handoff está gateado: el Project Manager solo libera al siguiente agente cuando existen los artefactos esperados.
60+
61+
```python
62+
from infrastructure.workspace.codex_mcp import multi_agent_workflow
63+
64+
workflow = multi_agent_workflow()
65+
for rule in workflow.handoffs:
66+
print(f"{rule.source} → {rule.target}: {rule.required_artifacts}")
67+
```
68+
69+
El `task_list_template` incluido replica el ejemplo “Bug Busters” para acelerar la puesta en marcha.
70+
71+
## 5. Observabilidad y Traces
72+
73+
Aunque el repositorio no conecta con el panel de Traces, los playbooks mantienen la estructura descrita por OpenAI para facilitar la observabilidad (prompts, handoffs, tiempos de ejecución, etc.). Quien despliegue el sistema real puede enviar los eventos generados por Codex MCP al dashboard para auditar conversaciones y tiempos de respuesta.
74+
75+
## 6. Validaciones
76+
77+
Ejecutar las pruebas asociadas desde la raíz del repositorio:
78+
79+
```bash
80+
python3 -m pytest infrastructure/workspace/tests/codex_mcp/test_playbooks.py
81+
python3 -m pytest infrastructure/workspace/tests
82+
```
83+
84+
Las pruebas verifican:
85+
- Blueprint del servidor (`npx -y codex mcp`).
86+
- Políticas `workspace-write` en los agentes.
87+
- Gating de artefactos antes de cada handoff.
88+
- Deliverables mínimos para frontend, backend y testing.
89+
90+
## 7. Próximos pasos
91+
92+
- Integrar la captura de trazas reales hacia el dashboard de OpenAI.
93+
- Automatizar el aprovisionamiento de dependencias con scripts de infraestructura.
94+
- Conectar el workspace con agentes existentes (`ai_capabilities/`).
95+
96+
## Recursos
97+
98+
- Código: `infrastructure/workspace/codex_mcp/`
99+
- Pruebas: `infrastructure/workspace/tests/codex_mcp/`
100+
- ExecPlan: `docs/EXECPLAN_codex_mcp_workspace.md`

‎infrastructure/workspace/__init__.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
1-
"""Workspace automation modules, including Hamilton examples and dev tools."""
1+
"""Workspace automation modules, including Hamilton examples, Codex playbooks and dev tools."""
22

33
from pathlib import Path
44

5-
from . import dev_tools, hamilton_llm
5+
from . import codex_mcp, dev_tools, hamilton_llm
66

7-
__all__ = ("dev_tools", "hamilton_llm")
7+
__all__ = ("codex_mcp", "dev_tools", "hamilton_llm")
88

99
TEST_SUITES = {
1010
"hamilton_llm": Path("infrastructure/workspace/tests/hamilton_llm"),
1111
"dev_tools_language_server": Path("infrastructure/workspace/tests/dev_tools/language_server"),
12+
"codex_mcp": Path("infrastructure/workspace/tests/codex_mcp"),
1213
}
1314
"""Mapping from workspace identifier to the directory containing its tests."""

‎infrastructure/workspace/codex_mcp/__init__.py‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
"""Codex MCP playbooks for initializing servers and orchestrating agents."""
2+
3+
from .playbooks import (
4+
AgentBlueprint,
5+
ENVIRONMENT_SETUP,
6+
HandoffRule,
7+
MCPServerBlueprint,
8+
MultiAgentWorkflow,
9+
RECOMMENDED_PROMPT_PREFIX_TOKEN,
10+
SingleAgentSystem,
11+
codex_cli_server_blueprint,
12+
multi_agent_workflow,
13+
single_agent_system,
14+
)
15+
16+
__all__ = [
17+
"AgentBlueprint",
18+
"ENVIRONMENT_SETUP",
19+
"HandoffRule",
20+
"MCPServerBlueprint",
21+
"MultiAgentWorkflow",
22+
"RECOMMENDED_PROMPT_PREFIX_TOKEN",
23+
"SingleAgentSystem",
24+
"codex_cli_server_blueprint",
25+
"multi_agent_workflow",
26+
"single_agent_system",
27+
]

0 commit comments

Comments
 (0)