# AGENTS.md Este repositorio se trabaja con agentes (IA) y humanos. Es el punto de entrada operativo y define el comportamiento para **cualquier** agente (Claude Code, Codex, etc.). ## 1) Punto de entrada obligatorio Antes de hacer cualquier acción (leer, modificar, ejecutar comandos, crear archivos, proponer cambios), el agente **DEBE**: 1.1 Leer `.agent/rules/rules.md` completo. Es la máxima autoridad del repo. 1.2 Leer los specs relevantes en `.agent/specs/`, empezando por `.agent/specs/SPEC_SYSTEM_ARCHITECTURE_v0.1.md`. 1.3 Consultar el índice de skills en la sección 8 de este documento y cargar **solo la que aplique** a la tarea concreta (ver sección 7). Si el agente no ha leído `.agent/rules/rules.md`, **no está autorizado** a operar sobre el repositorio. --- ## 2) Jerarquía y resolución de conflictos En caso de conflicto, la precedencia es la definida en `.agent/rules/rules.md` (sección 1). El agente debe documentar cualquier conflicto y su resolución en el PR o en el registro de cambios. --- ## 3) Regla operativa mínima antes de tocar el repo Si el agente va a crear, modificar o eliminar archivos del repositorio: 3.1 Cargar y aplicar `.agent/skills/git-workflow/SKILL.md` (ver sección 7). 3.2 Aislar el trabajo en una rama o PR (o equivalente según tooling). 3.3 Referenciar el spec aplicado. 3.4 Resolver conflictos por la precedencia de `.agent/rules/rules.md` y documentar la decisión. --- ## 4) Qué hacer si falta información Si falta un spec o una skill para ejecutar una decisión con seguridad: 4.1 No improvisar. 4.2 Crear o solicitar el spec o la skill que falte, o dejar explícito el bloqueo. Excepción: la ausencia de PHP o de infraestructura en el host de desarrollo NO es información que falte. Es el estado esperado. Ver sección 6. --- ## 5) Orquestación del trabajo - **Plan primero**: para tareas no triviales (3+ pasos o decisiones de arquitectura), planifica antes de implementar. Si algo se tuerce, para y re-planifica; no sigas empujando. - **Cambios pequeños y reversibles**: evita refactors masivos; divide en fases con verificación. - **Subagentes**: delega investigación, exploración y análisis paralelo. Una tarea por subagente, con permisos mínimos (nunca el scope completo del agente). - **Si falta información** (un spec o una skill para decidir con seguridad): no improvises. Crea/solicita el spec o la skill que falte, o deja explícito el bloqueo (ver sección 4). --- ## 6) Entorno de ejecución (REGLA CRÍTICA) ### 6.1 Entornos Este proyecto tiene dos entornos con configuraciones distintas: | Entorno | Docker | PHP en host | |---|---|---| | Desarrollo (local) | Sí (obligatorio) | No disponible, a propósito | | Producción | No | Disponible directamente | ### 6.2 Desarrollo: Docker obligatorio, prohibido instalar PHP En el entorno de desarrollo **no existe PHP en el host, y es intencionado**. Toda ejecución de PHP, Composer, PHPUnit o scripts del proyecto se hace dentro del contenedor. **REGLA CRÍTICA**: si detectas que `php` o `composer` no están en el host, eso es lo esperado, no un problema a resolver. Está terminantemente **prohibido**: - Instalar PHP, Composer o cualquier extensión PHP en el host. Nada de `apt-get`, `brew`, scripts de instalación ni descarga de binarios. - Intentar "arreglar" la ausencia de PHP en el host. - Ejecutar `php ...` o `composer ...` directamente en el host. Si un comando PHP falla fuera de Docker en desarrollo, es el comportamiento esperado. Reconduce a Docker. No instales nada. Correcto en desarrollo (ajusta el nombre del servicio si difiere de `app`): ``` docker compose exec -T app php bin/orchestrate daily docker compose exec -T app composer test docker compose exec -T app php bin/bookknowledge ingest ``` Prohibido en desarrollo: ``` php bin/orchestrate daily composer test apt-get install php8.3-cli ``` ### 6.3 Producción: sin Docker En producción no existe Docker. PHP está disponible directamente en el host. El agente **no debe asumir Docker** al generar instrucciones, scripts o documentación destinados a producción. ### 6.4 Implicaciones para el código El software no puede depender de infraestructura Docker (rutas de volumen, networking interno de contenedores, variables de entorno específicas de Docker Compose). La configuración debe llegar por variables de entorno estándar, válidas en ambos entornos. ### 6.5 Entorno Docker: crear si no existe Si el entorno Docker de desarrollo todavía no existe (falta `Dockerfile` o `docker-compose.yml`), créalo como primera tarea antes de ejecutar nada PHP: 6.5.1 Imagen base `php:8.3-cli` (o `php:8.3-fpm` si más adelante se añade servidor web). 6.5.2 Servicio `app` con el repositorio montado como volumen. 6.5.3 Extensiones PHP necesarias según los specs (por ejemplo pdo_sqlite, y la extensión o build para sqlite-vec). 6.5.4 Composer disponible dentro del contenedor. No acoples el código a rutas ni networking de Docker. La configuración llega por variables de entorno (ver 6.4). ### 6.6 Granularidad de comandos bash El sistema de permisos de Claude Code evalúa el string completo del comando, no cada subcomando. Aunque `find`, `cd`, `ls`, `echo`, `grep` y similares estén en el `allow` individualmente, encadenarlos con `&&`, `;`, `||` o pipes dispara un prompt de permiso por cada invocación. 6.6.1 En tareas de exploración (lectura, búsqueda, inspección de ficheros, listados), ejecutar los comandos uno a uno, sin encadenar y sin redirecciones tipo `2>/dev/null`. 6.6.2 Si encadenar es genuinamente necesario para un flujo atómico (por ejemplo `docker compose exec -T app composer test` o un commit más push), declararlo en el plan y asumir el prompt. 6.6.3 Prohibido en exploración: ``` cd /repo && find tests -iname "*X*" 2>/dev/null; ls tests/Unit/ || echo "no dir" ``` Correcto: ``` find tests -iname "*X*" ls tests/Unit/ ``` --- ## 7) Uso de skills (descubrimiento progresivo) Las skills están diseñadas para cargarse **bajo demanda**, no preventivamente. Cargar todas las skills al inicio de cada tarea consume contexto innecesariamente y degrada las decisiones del agente. Reglas: 7.1 **No** leer ningún `SKILL.md` al arrancar una tarea. 7.2 Consultar primero el índice de la sección 8 (nombre + descripción corta). 7.3 Cargar el `SKILL.md` completo **solo** cuando su descripción coincida con la tarea actual. 7.4 Si dudas si una skill aplica, lee solo su `SKILL.md`; no expandas a otras "por si acaso". 7.5 Si añades una skill nueva en `.agent/skills/`, **debes** registrarla en el índice de la sección 8 con una descripción de una línea. Documenta en el PR qué skill aplicaste. --- ## 8) Índice de skills disponibles Skills en `.agent/skills//SKILL.md`. Cargar solo cuando la descripción coincida con la tarea actual. | Skill | Cuándo usarla | |---|---| | `git-workflow` | Cualquier operación que cree, modifique o elimine archivos del repo (branching, commits, PRs). | | `spec-review` | Gate de cumplimiento tras escribir código (ver sección 9). | | _[añadir aquí el resto a medida que existan]_ | _[descripción de una línea: cuándo aplicarla]_ | --- ## 9) Verificación antes de "Done" - Nunca marques una tarea como completa sin demostrar que funciona: tests verdes + ejecución verificada. - Pregúntate: "¿lo aprobaría un ingeniero senior?". - **Gate de spec obligatorio**: tras cualquier sesión que escriba código, invoca `.agent/skills/spec-review/SKILL.md` (vía subagente Explore) antes de marcar la tarea como hecha. Un veredicto NON-COMPLIANT con BLOCKERs o MAJORs **bloquea el commit**, sin excepciones. --- ## 10) Principios - **Simplicidad primero**: cada cambio, lo más simple posible. Impacto mínimo. - **Sin atajos**: busca la causa raíz; nada de parches temporales. Estándar senior. - **Pensar en sistemas**: modular, contratos claros, reducir complejidad accidental, priorizar estabilidad sobre velocidad. - Codex revisará tu output cuando termines. --- ## 11) Objetivo Evitar ambigüedades: `.agent/rules/rules.md` manda, `.agent/specs/` define, `.agent/skills/` operativiza bajo demanda. La ausencia de PHP en el host de desarrollo es esperada: se trabaja siempre dentro de Docker y nunca se instala PHP en el host.