AGENTS.md

AGENTS.md — protocolo de desarrollo del repo

Archivo estándar agents.md, leído por agentes como Codex, OpenCode, Cursor (modo AGENTS) y otros. Claude Code usa además CLAUDE.md; Gemini CLI usa además GEMINI.md. Los tres apuntan a la misma fuente de verdad: la skill dev-protocol. No dupliques su contenido acá.

Para cualquier tarea de implementación, bug, review o entrega

Seguí el protocolo en .agents/skills/dev-protocol/SKILL.md.

• Arranque de Sesión / Relevo: Leé siempre al inicio .ai/global_instructions.md (directrices de comportamiento) y .ai/current_task.md (estado e historial de la tarea activa) para sincronizar tu contexto cognitivo de relevo de forma automatizada.

• Leé SKILL.md primero: rol (Principal Software Architect, no-fluff), §3 entorno (Python/uv + reglas LLM), §0 flujo idea→entrega con approval gate, higiene de contexto.

• Leé los módulos solo cuando la tarea lo pida (carga bajo demanda):

  Tarea	Módulo
  diseño / TDD / vertical slices	.agents/skills/dev-protocol/code-design.md
  bug o tests rojos	.agents/skills/dev-protocol/debugging.md
  review de diff / filing de issues	.agents/skills/dev-protocol/qa-review.md
  commit / pre-commit / push / merge	.agents/skills/dev-protocol/git-workflow.md
  docs (manifest/spec/CONTEXT)	.agents/skills/dev-protocol/documentation.md

Lecciones aprendidas del repo (leer antes de entregar)

Gotchas específicos de este repo (entrega/versión, verificación, invariantes backend/frontend) en LESSONS.md. Complementa al protocolo genérico; agregá nuevas lecciones ahí.

Reglas duras

• Dependencias Python solo con uv — nunca pip install ni venv manual (SKILL.md §3.1).
• Secrets fuera de código y de git — .env gitignored, commiteá .env.example (SKILL.md §3.2).
• No push ni merge a la base sin "OK" explícito del usuario — approval gate (git-workflow.md §3).

Verificación antes de push (obligatorio)

Gate local completo: npm run verify — unit tests + linters + dead code (~2 min, sin gastar Actions).

Tocaste…	Panel (./setup.sh)	Corré
Cualquier entrega / sesión IA	—	npm run verify
Solo frontend JS	Opción 4	npm test
Solo backend Python	Opción 5	cd backend && uv run --project . pytest -q
UI / full-stack	E2E en setup.sh	npm run verify -- --e2e (servers :5173 + :8000)

CI remoto: solo unit tests en push a main (repo privado, free tier). Sin PR obligatorio. Mapa completo en CONTRIBUTING.md.

Nota de fidelidad: los agentes sin disclosure progresiva pueden cargar todos los módulos de una. Si te importa el ahorro de tokens, mantené la referencia a SKILL.md y dejá que el agente abra los módulos cuando los necesite. Cómo portar a más herramientas: .agents/skills/dev-protocol/USAGE.md §3.