AI agent instructions

IVPrior — Instrucciones para agentes IA

Este archivo aplica a Cursor, GitHub Copilot, OpenCode, Claude Code, Gemini CLI, Codex, OpenSpec y cualquier agente que trabaje en el repositorio.

Estado del proyecto

Fase actual: V0 CLI en apps/cli/ + scaffold SaaS (apps/api|web|help|docs) desde fábrica FoodHub. Visión Accepted (DOC-001); modelo comercial B2C Subscriber (DOC-002). Motor Python permitido. Dominio opciones en la app web = slices posteriores (no copiar food ni Organization B2B).

Agentes por rol

Catálogo: agents/README.md. Cada rol tiene agents/<rol>/AGENT.md (fuente de verdad) enlazado desde .cursor/rules/ y .github/instructions/.

Memoria de sesión

Codex (desktop / CLI / IDE)

Antes de trabajar en Codex, leer agents/codex.md y el índice generado agents/codex-rules.md. Leer completas todas las reglas Siempre del índice y las demás según rutas/intención; seguir agents/<rol>/AGENT.md para cada rol involucrado. Esto adapta las reglas MDC a Codex sin asumir carga automática de archivos Cursor.

Skills locales: .agents/skills/; invocar por nombre (init-session, cierre-session, sd-*, openspec-*, speckit-*) mediante selector o lenguaje natural. Equivalencias de comandos y ejecución de hooks: agents/codex.md.

Al abrir una sesión: /init-session (lee memory/). Al cerrar: /cierre-session (memoria, archive OpenSpec completados, GitHub Flow: make ship → merge a master + sync local — ADR-017).

Git: /sd-branch al iniciar; /sd-pr solo si necesitás PR sin merge; cierre con ship completo.

Sincronización de superficies

.cursor/skills/ y .cursor/commands/ son el hub (formato de los generadores). Podés editar en cualquier superficie; después promovés y regenerás espejos:

make sync-agents                  # fan-out desde hub (Cursor)
make sync-agents FROM=github      # editaste .github/skills o prompts opsx-*
make sync-agents FROM=claude      # idem Claude
make sync-agents FROM=opencode
make sync-agents FROM=gemini
make sync-agents FROM=codex       # skills enlazadas al hub + regeneración de adaptadores e índice

• Thin prompts (init-session, sd-*) se regeneran: editá el SKILL.md de tu superficie, no el thin.
• Spec Kit gestiona speckit.* / speckit-* — el sync no los toca.
• Cursor: hook afterFileEdit hace fan-out al editar .cursor/skills|commands.
• Codex: ejecutar sync tras editar skills, comandos o reglas; no depende del hook Cursor. Tests: make test-agent-sync.
• Sync manual: ./scripts/sync-agents.sh --from <surface> (--dry-run para previsualizar).

Ver DOC-013 y docs/README-METODOLOGIA-SESION.md.

Fuentes de verdad (orden de lectura)

1. memory/project_estado_actual.md — snapshot táctico
2. docs/vision/DOC-001-product-vision.md — visión (crear si falta)
3. docs/adr/ — decisiones arquitectónicas (incl. ADR-010…015 defaults)
4. docs/architecture/DOC-010-architecture-coding-principles.md — principios cross-project
5. docs/domain/DOC-002-domain-model.md — SaaS B2C (Subscriber); DOC-003 — opciones/IV
6. docs/backlog/DOC-009-product-backlog.md — epics y stories
7. docs/ux/ — specs UX (pantallas S-xxx, wireframes)
8. docs/development/DOC-013-ai-sdlc-hybrid-workflow.md — Spec Kit vs OpenSpec
9. docs/development/DOC-012-feature-discovery-workflow.md — flujo sd-discover
10. specs/ — iniciativas estratégicas (Spec Kit)
11. openspec/changes/ — cambio activo OpenSpec

Ejecución manual de tests

Por decisión explícita del usuario (2026-09-13), no ejecutar automáticamente tests, lint, typecheck ni builds en el PC, en hooks, al abrir PR o al cerrar sesión. Los tests se ejecutan solo a petición mediante manual-tests.yml (workflow_dispatch), sin build y sin bloquear el merge. El cierre solo recuerda y propone gh workflow run manual-tests.yml --ref master -f suite=all; no ejecutarlo sin una petición expresa.

Reglas obligatorias

• No modificar arquitectura sin ADR documentado.
• No escribir código de features sin Spec Kit, OpenSpec change o story en DOC-009 (matriz DOC-013).
• Features de dominio: brief aprobado en docs/product/features/*/brief.md antes de /opsx:propose (DOC-012).
• Features con UI: spec de pantalla en docs/ux/screens/S-xxx.md + entrada en sitemap (cuando exista).
• Arquitectura / código: DOC-010 + .cursor/rules/seed-code-patterns.mdc (stack-agnóstico).
• ADRs semilla (defaults sin tecnología): ADR-010…015 en docs/adr/.
• No asumir stack (Nest, Next, React, Django, etc.) hasta ADR de tecnología del proyecto.
• Tests: ADR-013 · .specify/memory/testing.md · .specify/checklists/test.md.
• UX visual: gates en .specify/memory/ux.md y .specify/checklists/ux.md cuando haya UI.
• CLIs AI-SDLC: openspec y specify obligatorios en el PATH. En /init-session correr make doctor; si fallan → STOP e instrucciones en DOC-014 · .cursor/rules/seed-tooling.mdc.

Stack

Permitido apps/cli. Scaffold Nest/Next ya copiado. Dominio de la app = Subscriber B2C (DOC-002); no re-scaffoldar ni copiar food.

Developer experience (Makefile)

Interfaz canónica para humanos y agentes (sin asumir package manager):

make help      # listado de comandos
make doctor    # diagnóstico seed (falla si faltan openspec/specify)
make cli-install
make cli ARGS='AAPL --opciones'
make check     # comprobación completa, solo si el humano la pide expresamente
make ship ARGS='--title "chore: ..." '   # GitHub Flow: PR + merge + sync master

Guía: docs/development/DOC-011-local-development-guide.md.
Instalación CLIs: DOC-014.
No inventar comandos de lint/test/onboarding ad hoc si existe un target make equivalente.

GitHub Flow (ADR-017)

master → /sd-branch → commits → /cierre-session → make ship → master actualizado

/sd-pr = solo PR (sin merge). No push directo a master.

AI-SDLC híbrido

Guía: docs/development/DOC-013-ai-sdlc-hybrid-workflow.md

Constitution: .specify/memory/constitution.md

Spec Kit

/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
Pre-requisito dominio: /sd-feature-brief aprobado.

OpenSpec

Sesión: /init-session, /cierre-session
Ciclo: /opsx:propose → /opsx:apply → /opsx:archive

openspec new change "<nombre-kebab>"
openspec status --change "<nombre>"
openspec validate

Idioma

Responder al usuario en español. Código, APIs, nombres de entidades y commits en inglés.

For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan at specs/006-subscriber-scheduled-scans/plan.md