AI agent instructions

MercoraHub — Instrucciones para agentes IA

Este archivo aplica a Cursor, GitHub Copilot, OpenSpec y cualquier agente que trabaje en el repositorio.

Estado del proyecto

Fase actual: implementación incremental (Release 1). Auth foundation en apps/api (modules/identity/). Specs UX y backlog siguen en paralelo. No generar implementación sin spec aprobada (ADR-009).

Agente backend activo: agents/backend/AGENT.md.

Agentes por rol

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

Memoria de sesión

Al abrir una sesión en Cursor: ejecutar /fh-init-session (lee memory/).
Al cerrar: /fh-wrap (actualiza memory/ versionado en git y ejecuta fh-ship para PR → merge).

Git (ADR-016): /fh-branch al iniciar trabajo; cierre con /fh-wrap → scripts/fh-ship.sh (make ship). /fh-pr solo si necesitás PR sin merge automático.

Ver DOC-013.

Ver docs/README-METODOLOGIA-SESION.md y memory/MEMORY.md.

Desarrollo local

Ver docs/development/DOC-011-local-development-guide.md — prerrequisitos, make local-up, modos Docker/nativo, checklist.

Quick start: pnpm install → cp devops/docker/.env.docker.example devops/docker/.env.docker → make doctor → make local-up.

Developer Docs portal: http://localhost:3003/en (NEXT_PUBLIC_DOCS_BASE_URL — admin sidebar, footer, marketing links).

Admin UI (Metronic referencia completa): make metronic-reference → docs/ux/references/external/metronic-v9.5.0/ (gitignored, ~1 GB). Catálogo: docs/ux/references/metronic/REFERENCE-CATALOG.md.

Fuentes de verdad (orden de lectura)

1. memory/project_estado_actual.md — snapshot táctico (si existe sesión previa)
2. docs/vision/DOC-001-product-vision.md — visión y alcance MVP
3. docs/adr/ — decisiones arquitectónicas (40 ADRs)
4. docs/domain/DOC-002-domain-model.md — entidades y reglas
5. docs/domain/DOC-003-bounded-contexts.md — límites de módulos
6. docs/domain/DOC-004-event-catalog.md — eventos de dominio
7. docs/database/DOC-006A-core-database-schema.md (+ 006B, 006C)
8. docs/api/DOC-005-api-contract-strategy.md
9. docs/backlog/DOC-009-product-backlog.md — epics y stories
10. docs/ux/ — specs UX (ADR-042): sitemap, pantallas S-xxx, wireframes
11. docs/development/DOC-013-ai-sdlc-hybrid-workflow.md — Spec Kit vs OpenSpec (ADR-009)
12. docs/development/DOC-012-feature-discovery-workflow.md — flujo fh-discover
13. specs/ — iniciativas estratégicas (GitHub Spec Kit)
14. openspec/changes/ — cambio activo OpenSpec (si existe)

Reglas obligatorias

• No modificar arquitectura sin ADR o amendment documentado.
• No escribir código de features sin story en DOC-009 u OpenSpec change en openspec/changes/.
• Features de dominio: brief aprobado en docs/product/features/*/brief.md antes de /opsx:propose (ver DOC-012).
• Features con UI: spec de pantalla en docs/ux/screens/S-xxx.md + entrada en docs/ux/sitemap.md (ADR-042).
• Multi-tenant: toda entidad de negocio lleva tenantId; filtrar en repositorios (ADR-013).
• Location, no Restaurant, como unidad operativa en schema y APIs (DOC-002).
• Pagos: distinguir SaaS billing (ADR-021) de order payments (ADR-040).
• Comunicación entre contextos: solo eventos de dominio o use cases, nunca repositorios cruzados (DOC-003).
• Patrones de código: .cursor/rules/foodhub-code-patterns.mdc (hexagonal, feature-based, API, tests).
• Implementation coherence (DOC-015): una sola forma canónica FE+BE — search→Mirror→reuse→extract+catalog. Catálogo docs/development/canonical-implementations.md; gates .specify/memory/implementation-coherence.md + checklist .specify/checklists/implementation-coherence.md (constitution XII). List CRUD admin tenant+platform: docs/ux/patterns/platform-admin-crud.md.
• Lint/format: @foodhub/eslint-config; pnpm lint o make lint (ADR-041).
• Tests (ADR-015): cada use case/guard con *.spec.ts; slices API con E2E. Gates en .specify/memory/testing.md y .specify/checklists/test.md.
• UX visual (ADR-042): wireframes P0 + design tokens + patrón marketplace. Gates en .specify/memory/ux.md y .specify/checklists/ux.md.
• Admin wizards: estándar único S-012 — docs/ux/patterns/admin-wizard.md · .cursor/rules/foodhub-admin-wizard.mdc.
• Help content (ADR-045): toda pantalla/flujo user-facing (S-xxx) MUST incluir MDX + registry Help en el mismo slice, con calidad explicativa (qué significan KPIs/campos y cómo se calculan — no solo pasos de navegación). Gates en .specify/memory/help-content.md, .specify/checklists/help-content.md y .cursor/rules/foodhub-help-content.mdc.
• Developer Docs portal (FEAT-080): todo change con impacto en contrato OpenAPI, guías docs/ (allowlist), DX local (Docker/Makefile/DOC-011) o shell apps/docs MUST incluir tareas Developer Docs explícitas en el mismo slice. Gates en .specify/memory/dev-docs-content.md, .specify/checklists/dev-docs-content.md y .cursor/rules/foodhub-dev-docs-content.mdc.
• Changelog (DOC-019): todo change mergeable notable (UI, API, DX, fixes relevantes) MUST actualizar CHANGELOG.md ([Unreleased]) en el mismo slice. Gates en .specify/memory/changelog.md, .specify/checklists/changelog.md y .cursor/rules/foodhub-changelog.mdc.
• Platform IAM (FEAT-041): toda capacidad nueva en /platform MUST declarar código(s) en platform_permissions, plan de asignación (roles/overrides) y enforcement por permiso efectivo. Gates en .specify/memory/platform-iam.md y .specify/checklists/platform-iam.md (constitution XI).

Stack

AI-SDLC híbrido (ADR-009)

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

Constitution: .specify/memory/constitution.md

GitHub Spec Kit (estrategico)

Comandos Cursor: /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement
Comandos Copilot: mismos en .github/prompts/speckit.*

Flujo: /fh-feature-brief (approved) → /speckit.specify → plan → tasks → implement

OpenSpec (operativo)

Comandos sesión: /fh-init-session, /fh-wrap
Comandos OpenSpec: /opsx:propose, /opsx:apply, /opsx:archive

CLI:

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

Los cambios viven en openspec/changes/<nombre>/. Las specs consolidadas en openspec/specs/.

Estructura del monorepo (objetivo)

Ver docs/architecture/DOC-010-monorepo-folder-structure.md.

apps/api | web | mobile
packages/ui | types | sdk | config
docs/ | packages/api-contract/ | openspec/ | agents/

Idioma

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