AI agent instructions

Global rules for Cursor, Copilot and OpenSpec (AGENTS.md).

Source: AGENTS.md

LogicCore — Instrucciones para agentes IA

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

Estado del proyecto

Fase actual: fundación de plataforma. Solo existe scaffold técnico; no hay features ERP implementadas.

  • Visión: docs/vision/DOC-001-product-vision.md (Approved v2.0, 2026-11-12).
  • Glosario inicial: .cursor/rules/seed-domain.mdc.
  • Stack Accepted: ADR-019…ADR-028 y ADR-032/033; ADR-034…040 Accepted. Índice en docs/adr/README.md.
  • Antes de /opsx:propose o /speckit.specify de dominio: brief aprobado. Infra del monorepo puede ir por OpenSpec directo (DOC-013).

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

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 necesitas PR sin merge; cierre con ship completo.

AgenteSesión / Git / Producto
Cursor.cursor/commands/sd-* · skills canónicos en .cursor/skills/
GitHub Copilot.github/prompts/sd-* · .github/skills/ (espejo) · .github/copilot-instructions.md
OpenCodeopencode.json · .opencode/context.md · .opencode/skills/ (espejo) · .opencode/commands/
Claude CodeCLAUDE.md · .claude/skills/ (espejo; speckit-* vía Spec Kit) · .claude/commands/
Gemini CLIGEMINI.md · .gemini/skills/ (espejo) · .gemini/commands/*.toml (speckit.* vía Spec Kit)
ChatGPT CodexAGENTS.md (nativo) · .agents/skills/ (espejo) · invocación $skill (sin thin commands)

Sincronización de superficies

.cursor/skills/ y .cursor/commands/ son el hub (formato de los generadores). Puedes editar en cualquier superficie; después promueves y regeneras 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       # editaste .agents/skills (ChatGPT Codex)
  • Thin prompts (init-session, sd-*) se regeneran: edita el SKILL.md de tu superficie, no el thin.
  • Codex no tiene thin commands (custom prompts deprecados): invoca el skill ($init-session, $sd-branch, $openspec-propose).
  • Spec Kit gestiona speckit.* / speckit-* — el sync no los toca.
  • Cursor: hook afterFileEdit hace fan-out al editar .cursor/skills|commands.
  • Sync manual: ./scripts/sync-agents.sh --from <surface> (--dry-run para previsualizar).
  • .agents/skills/ es el espejo Codex; no confundir con el catálogo de roles agents/<rol>/.

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/ — modelo de dominio (cuando exista)
  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

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/.
  • Stack Accepted (ADR-019…028, ADR-032): pnpm, Turborepo, Next.js, NestJS, PostgreSQL, Prisma, REST. Sin app móvil nativa. No sustituir ese stack por otro framework. Páginas y módulos de dominio solo con brief aprobado y spec de pantalla cuando haya UI.
  • 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.
  • Superficies UX: S-001…S-007 identifican el sitio público y conservan su aprobación visual. DOC-018 registra S-008…S-036 para portal/ERP; leer docs/ux/handoff/platform-v1/README.md, su contrato visual, spec y mapa. Specs S-008…S-036 e imágenes seleccionadas aprobadas en docs/ux/design/platform-v1/approval.md; controles nativos y briefs por feature aún requeridos. No aplicar el handoff público como diseño del ERP.
  • Maquetación LogicCore: leer docs/ux/handoff/README.md, el contrato visual, la spec S-xxx y el mapa screen-assets.json. Usar los recursos registrados en docs/ux/assets/site-v1/manifest.json; los renders completos V3 son referencias, no fondos de página.
  • 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

CapaTecnología
ProductoAccepted — pnpm, Turborepo, Next.js, NestJS, PostgreSQL, Prisma, REST. Sin móvil. Índice: docs/adr/README.md.
SpecsGitHub Spec Kit (specs/) + OpenSpec (openspec/)
CLIsopenspec + specify — DOC-014
DXMakefile fachada (ADR-016) — make help
GitGitHub Flow (ADR-017) — ramas cortas → PR → merge a master
DistribuciónGitHub Template Repository (ADR-018) — DOC-015

Developer experience (Makefile)

Interfaz canónica para humanos y agentes. Package manager: pnpm (ADR-020). Los targets install, check y local-up se cablean con el scaffold de infra.

make help      # listado de comandos
make doctor    # diagnóstico seed (falla si faltan openspec/specify)
make github-template  # dry-run: marcar la semilla como plantilla GitHub (ADR-018)
make check     # gate de calidad (SKIP hasta cablear stack)
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. Plantilla GitHub: DOC-015. 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

NivelHerramientaUbicación
EstratégicoGitHub Spec Kitspecs/<NNN-feature>/
OperativoOpenSpecopenspec/changes/

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 internacional (tú; sin voseo). Código, APIs, nombres de entidades y commits en inglés.

Estilo de código: .specify/memory/coding-style.md. Baseline de seguridad: .specify/memory/security.md.

<!-- SPECKIT START -->

specs/001-public-website/plan.md está implementado (PR #5). Foundation identity + shell archivada (2026-11-19-identity-*, design-system-shell, admin-foundation-screens, portal-foundation-screens, contextual-help-and-profile). Sin changes OpenSpec activos. Producción A-lite: logiccore.mercorahub.com (ADR-044). Stack: pnpm, Next.js, NestJS, Prisma, PostgreSQL.

<!-- SPECKIT END -->

Alcance actualizado 2026-11-12

La web pública no es todo el producto. La plataforma incluirá portal cliente (registro Google/email, ProjectRequest, proyectos, contratos, facturas y soporte) y ERP interno (CRM, ventas, delivery y finance), más Help Center, Developer Docs y observabilidad. Ver DOC-001, DOC-002, DOC-017, DOC-018 y ADR-034…040 Accepted. No implementar por mera existencia de estos documentos: visión y ADR ratificados no sustituyen briefs, specs y validaciones por feature. Aprobación en docs/vision/approval-platform-v2.md.