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:proposeo/speckit.specifyde 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/.
| Rol | Prompt |
|---|---|
| architect | agents/architect/AGENT.md |
| backend | agents/backend/AGENT.md |
| frontend | agents/frontend/AGENT.md |
| mobile | agents/mobile/AGENT.md |
| qa | agents/qa/AGENT.md |
| devops | agents/devops/AGENT.md |
| product | agents/product/AGENT.md |
| ux | agents/ux/AGENT.md |
| security | agents/security/AGENT.md |
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.
| Agente | Sesió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 |
| OpenCode | opencode.json · .opencode/context.md · .opencode/skills/ (espejo) · .opencode/commands/ |
| Claude Code | CLAUDE.md · .claude/skills/ (espejo; speckit-* vía Spec Kit) · .claude/commands/ |
| Gemini CLI | GEMINI.md · .gemini/skills/ (espejo) · .gemini/commands/*.toml (speckit.* vía Spec Kit) |
| ChatGPT Codex | AGENTS.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
afterFileEdithace fan-out al editar.cursor/skills|commands. - Sync manual:
./scripts/sync-agents.sh --from <surface>(--dry-runpara previsualizar). .agents/skills/es el espejo Codex; no confundir con el catálogo de rolesagents/<rol>/.
Ver DOC-013 y docs/README-METODOLOGIA-SESION.md.
Fuentes de verdad (orden de lectura)
memory/project_estado_actual.md— snapshot tácticodocs/vision/DOC-001-product-vision.md— visión (crear si falta)docs/adr/— decisiones arquitectónicas (incl. ADR-010…015 defaults)docs/architecture/DOC-010-architecture-coding-principles.md— principios cross-projectdocs/domain/— modelo de dominio (cuando exista)docs/backlog/DOC-009-product-backlog.md— epics y storiesdocs/ux/— specs UX (pantallas S-xxx, wireframes)docs/development/DOC-013-ai-sdlc-hybrid-workflow.md— Spec Kit vs OpenSpecdocs/development/DOC-012-feature-discovery-workflow.md— flujo sd-discoverspecs/— iniciativas estratégicas (Spec Kit)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.mdantes 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.mdy.specify/checklists/ux.mdcuando 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 endocs/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 mapascreen-assets.json. Usar los recursos registrados endocs/ux/assets/site-v1/manifest.json; los renders completos V3 son referencias, no fondos de página. - CLIs AI-SDLC:
openspecyspecifyobligatorios en el PATH. En/init-sessioncorrermake doctor; si fallan → STOP e instrucciones enDOC-014·.cursor/rules/seed-tooling.mdc.
Stack
| Capa | Tecnología |
|---|---|
| Producto | Accepted — pnpm, Turborepo, Next.js, NestJS, PostgreSQL, Prisma, REST. Sin móvil. Índice: docs/adr/README.md. |
| Specs | GitHub Spec Kit (specs/) + OpenSpec (openspec/) |
| CLIs | openspec + specify — DOC-014 |
| DX | Makefile fachada (ADR-016) — make help |
| Git | GitHub Flow (ADR-017) — ramas cortas → PR → merge a master |
| Distribución | GitHub 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
| Nivel | Herramienta | Ubicación |
|---|---|---|
| Estratégico | GitHub Spec Kit | specs/<NNN-feature>/ |
| Operativo | OpenSpec | openspec/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.
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.
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.