Contrato Engram Unificado¶
Engram es la memoria persistente compartida del ecosistema Marketplace Inteliside. Permite que los plugins escriban y lean datos estructurados entre sesiones, entre fases de un pipeline, y entre diferentes roles del equipo (PM, Designer, Dev). Cada plugin define topic keys con schemas JSON fijos que otros plugins consumen de forma determinista.
Si eres un humano: este documento describe como se organiza la memoria compartida entre plugins. Consultalo cuando necesites saber que dato produce un plugin y quien lo consume.
Si eres un agente de IA: usa las tablas de topic keys para saber exactamente que leer y donde escribir. Los prefijos de topic keys (project/, team/, sdd/, legacy/, re-wizard/, ux-studio/, intake/, pipeline/) determinan el scope y la propiedad del dato.
Proyectos Engram¶
El ecosistema usa dos patrones de proyecto Engram. Todos los plugins de un mismo proyecto comparten el mismo valor de engram_project.
| Patron | Nombre del proyecto | Scope | Plugins que lo usan | Persistencia |
|---|---|---|---|---|
| Team | {nombre-proyecto}-dev |
Conocimiento permanente del equipo: decisiones de arquitectura, patrones, bugs resueltos, features completadas, convenciones | ATL Inteliside, SDD-Wizards, SDD-Legacy, RE-Wizard, SDD-Intake | Permanente — sobrevive entre features y sesiones |
| Pipeline | {nombre-proyecto}-dev/atl |
Estado efimero del pipeline de implementacion activo: artefactos del DAG, progreso de tasks, estado del pipeline | ATL Inteliside (exclusivo) | Efimero — se limpia al archivar cada feature |
Adicionalmente, n8n-studio usa un proyecto independiente:
| Patron | Nombre del proyecto | Scope | Plugins que lo usan | Persistencia |
|---|---|---|---|---|
| Automation | {nombre-proyecto}-n8n |
Estado del pipeline de automatizacion: specs, build plans, test reports, patrones reutilizables | n8n-studio (exclusivo) | Mixto — patrones permanentes, pipeline efimero |
Configuracion en CLAUDE.md¶
## ATL Inteliside
engram_project: "nombre-proyecto-dev"
github_owner: "org-o-usuario"
github_repo: "nombre-repo"
El pipeline key se deriva automaticamente: engram_pipeline = "{engram_project}/atl". Solo se configura engram_project.
Topic Keys por Plugin¶
SDD-Wizards¶
Prefijo principal: project/. Escribe los artefactos fundacionales del proyecto (PRD, stack, features).
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
project/prd |
JSON (PRD completo) | prd-wizard | feature-spec-wizard, ATL orchestrador | PRD con overview, users, stories, requirements, scope, risks, stack |
project/stack |
JSON (stack seleccionado) | prd-wizard (via tech-stack-selector) | feature-spec-wizard, ATL orchestrador | Archetype, components, ADRs, referencias CLI/MCP |
project/github-context |
JSON (contexto GitHub) | prd-wizard (Phase 9) | feature-spec-wizard, ATL, SDD-Legacy, RE-Wizard, SDD-Intake | owner, repo, visibility, project number |
project/features/{feature-name} |
JSON (Feature Spec) | feature-spec-wizard | ATL orchestrador | User stories, ACs, BRs, data model, API, errors |
project/features-index |
JSON (indice acumulativo) | feature-spec-wizard | feature-spec-wizard (continuation), ATL | Indice de features con status, metricas de calidad |
project/handoff/{feature} |
JSON (senal de handoff) | feature-spec-wizard (Phase 8) | ATL sdd-from-github | Senal de que la feature esta lista para ATL con metricas y links |
ATL Inteliside — Proyecto de Equipo (engram_project)¶
Prefijo principal: team/. Conocimiento permanente que sobrevive entre features.
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
team/decisions/{tema} |
JSON (decision de arquitectura) | sdd-design, sdd-archive | sdd-explore, sdd-apply | Decisiones de arquitectura tomadas durante implementacion |
team/patterns/{area} |
JSON (patron de codigo) | sdd-apply, sdd-archive | sdd-apply, sdd-explore | Patrones de codigo establecidos por area |
team/bugs/{descripcion} |
JSON (bug resuelto) | sdd-apply, sdd-verify | sdd-explore, sdd-apply | Bugs resueltos con root cause y fix |
team/completed/{feature} |
JSON (feature completada) | sdd-archive | sdd-explore, SDD-Intake | Historial de features completadas |
ATL Inteliside — Proyecto de Pipeline (engram_project/atl)¶
Prefijo principal: sdd/{feature}/. Estado efimero del pipeline activo.
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
sdd/{feature}/feature-spec |
JSON (Feature Spec del PM) | sdd-from-github | sdd-explore, sdd-verify | Feature Spec ingestado desde GitHub |
sdd/{feature}/exploration |
JSON (analisis del codebase) | sdd-explore | sdd-propose | Que existe, que construir, conflictos |
sdd/{feature}/proposal |
JSON (propuesta de cambio) | sdd-propose | sdd-spec, sdd-design | Intent, alcance, enfoque, rollback plan |
sdd/{feature}/spec |
JSON (delta spec tecnica) | sdd-spec | sdd-tasks, sdd-verify | Spec tecnica con RFC 2119 y Given/When/Then |
sdd/{feature}/design |
JSON (decisiones de arquitectura) | sdd-design | sdd-tasks, sdd-apply | Patrones, restricciones de implementacion |
sdd/{feature}/tasks |
JSON (tasks breakdown) | sdd-tasks | sdd-apply, sdd-verify | Tasks atomicas por fase |
sdd/{feature}/test-plan/{phase} |
JSON (test plan por fase) | sdd-write-tests | sdd-apply, sdd-verify | Tests derivados de la spec |
sdd/{feature}/current-task |
JSON (progreso en tiempo real) | sdd-apply | orchestrador | Task actual, status, contadores |
sdd/{feature}/pipeline-state |
JSON (estado del DAG) | orchestrador | orchestrador | Stage, substage, approvals, timestamps |
sdd/{feature}/verify-report |
JSON (reporte de verificacion) | sdd-verify | sdd-archive | Resultado de validacion ACs + RFs |
project/github-context |
JSON (contexto GitHub) | sdd-from-github | todos | owner, repo, milestone |
project/config |
JSON (configuracion de proyecto) | sdd-init | todos | Stack detectado, convenciones |
project/stack-constraints |
JSON (restricciones de stack) | sdd-from-github | sdd-init, sdd-design | Stack definido por el PM en el PRD |
SDD-Legacy¶
Prefijo principal: legacy/. Artefactos del pipeline de onboarding.
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
legacy/audit |
JSON (Audit Report) | legacy-audit-wizard | spec-extractor, baseline, conventions, onboard | Health score, tech debt, dependencias, metricas |
legacy/stack |
JSON (stack detectado) | legacy-audit-wizard | spec-extractor, rules-extractor, conventions, onboard | Lenguaje, framework, DB, ORM, auth, testing |
legacy/health-score |
JSON (scores por area) | legacy-audit-wizard | baseline, onboard, SDD-Intake | Score 0-100 por area (backend, frontend, db, testing, infra, security) |
legacy/features/{feature-name} |
JSON (Feature Spec retroactiva) | legacy-spec-extractor | rules-extractor, baseline, SDD-Intake | Formato identico a SDD-Wizards con campos de trazabilidad |
legacy/features-index |
JSON (indice acumulativo) | legacy-spec-extractor | rules-extractor, baseline, onboard, SDD-Intake | Indice de features con sesiones y status |
legacy/prd |
JSON (PRD retroactivo) | legacy-spec-extractor | baseline, onboard | PRD generado desde codigo existente |
legacy/rules/{domain} |
JSON (reglas de negocio) | legacy-rules-extractor | baseline, onboard, SDD-Intake | Reglas con trazabilidad file:line y test cases |
legacy/test-cases/{domain} |
JSON (test cases G/W/T) | legacy-rules-extractor | baseline, onboard | Test cases compatibles con sdd-write-tests |
legacy/rules-index |
JSON (indice de reglas) | legacy-rules-extractor | baseline, onboard, SDD-Intake | Dominios, conteos, reglas criticas |
legacy/preexisting-issues |
JSON (issues preexistentes) | legacy-spec-extractor | baseline | Issues de GitHub existentes antes del onboarding |
legacy/baseline |
JSON (plan de deuda tecnica) | legacy-baseline-wizard | onboard, SDD-Intake | Tasks priorizadas por categoria y area |
legacy/conventions |
JSON (convenciones detectadas) | legacy-conventions-wizard | onboard, SDD-Intake | Patrones de naming, estructura, testing |
legacy/onboard-status |
JSON (estado de onboarding) | legacy-onboard-wizard | ATL orchestrador, SDD-Intake | Checklist completo, ready_for_atl flag |
legacy/handoff/{feature} |
JSON (handoff per-feature) | legacy-handoff | ATL sdd-from-github (opcional) | Senal de feature lista con metricas y prerequisitos |
project/github-context |
JSON (contexto GitHub) | legacy-audit-wizard | todos (compatible con ATL) | owner, repo, detectado desde git config |
project/config |
JSON (configuracion) | legacy-onboard-wizard | todos (compatible con ATL sdd-init) | Stack, convenciones, proyecto SDD-ready |
RE-Wizard¶
Prefijo principal: re-wizard/{analysis-id}/. Artefactos del analisis de ingenieria inversa.
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
re-wizard/{id}/config |
JSON (configuracion del analisis) | Step 1 (mode selection) | Todas las fases | Modo, paths, goals, stack target |
re-wizard/{id}/recon |
JSON (reconocimiento) | Phase 0 (re-wizard-recon) | Phase 1+ | Stack, estructura, metricas, dependencias |
re-wizard/{id}/architecture |
JSON (arquitectura) | Phase 1 (re-wizard-structure) | Phase 2+ | Patron arquitectonico, capas, patrones de diseno |
re-wizard/{id}/data-model |
JSON (modelo de datos) | Phase 1 (re-wizard-structure) | Phase 2+ | Entidades, relaciones, indices |
re-wizard/{id}/api-spec |
JSON (spec de API) | Phase 1 (re-wizard-structure) | Phase 2+ | Endpoints con metodos, params, auth |
re-wizard/{id}/features |
JSON (inventario de features) | Phase 2 (re-wizard-functional) | Phase 3+ | Features con evaluacion de complejidad |
re-wizard/{id}/user-flows |
JSON (flujos de usuario) | Phase 2 (re-wizard-functional) | Phase 3+ | Roles, permisos, flujos por feature |
re-wizard/{id}/business-rules |
JSON (reglas de negocio) | Phase 2 (re-wizard-functional) | Phase 3+, SDD-Intake | Reglas con trazabilidad file:line |
re-wizard/{id}/system-overview |
JSON (vision del sistema) | Phase 3 (re-wizard-domain) | Phase 4 | Dominio, NFRs, deuda tecnica, ADRs |
re-wizard/{id}/synthesis-status |
JSON (estado de sintesis) | Phase 4 (re-wizard-synthesis) | Usuario | Features procesadas, specs generados |
Topic keys de handoff a ATL (compatibilidad total con SDD-Wizards):
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
project/features/{feature-name} |
JSON (Feature Spec) | Phase 4 | ATL sdd-from-github | Feature Spec completo en formato ATL |
project/features-index |
JSON (indice) | Phase 4 | ATL, SDD-Intake | Indice de features con waves |
project/github-context |
JSON (contexto GitHub) | Phase 4 (si crea milestones) | ATL sdd-from-github | owner, repo, milestone numbers |
project/stack |
JSON (stack detectado) | Phase 0 | ATL sdd-init | Stack del codebase analizado |
UX Studio¶
Prefijo principal: ux-studio/. Artefactos del pipeline de diseno.
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
ux-studio/research-report |
JSON (Research Report) | ux-researcher (Phase 1) | ux-designer | Tendencias, competencia, referencias |
ux-studio/ux-brief |
JSON (UX Brief) | ux-discovery (Phase 2) | ux-designer | Preferencias del cliente: marca, mood, plataforma, motion |
ux-studio/design-direction |
JSON (Design Direction) | ux-designer (Phase 3) | ux-designer (Phase 4+), ux-reviewer | Visual + Motion + Interaction + Responsive specs |
ux-studio/design-prompts |
JSON (Design Prompts) | ux-designer (Phase 4) | ux-designer (Phase 5) | 3 opciones por componente (A: conservadora, B: diferenciada, C: bold) |
ux-studio/pen-files |
JSON (metadata .pen) | ux-designer (Phase 5) | ux-reviewer, PM Review | Paths a archivos .pen generados |
ux-studio/design-review |
JSON (Design Review) | ux-reviewer (Phase 6) | orchestrador | Resultado de validacion por 6 dimensiones |
ux-studio/pm-selections |
JSON (selecciones del PM) | PM Review (Phase 7) | Design Handoff | Opciones elegidas por el PM por componente |
ux-studio/design-spec |
JSON (Design Spec final) | Design Handoff (Phase 8) | ATL sdd-design | Spec consolidado con tokens, motion, interactions, responsive |
SDD-Intake¶
Prefijo principal: intake/. Plugin primariamente consumidor.
Lo que escribe:
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
intake/{feature_name}/enrichment |
JSON (analisis cruzado) | client-intake-wizard | Solo interno (debug) | Requerimiento + contexto cruzado |
sdd/{feature_name}/feature-spec |
JSON (Feature Spec) | client-intake-wizard | ATL sdd-from-github | Formato identico a SDD-Wizards con seccion extra "Context from Existing Codebase" |
project/github-context |
JSON (contexto GitHub) | client-intake-wizard | ATL sdd-init | Solo si no existe previamente |
Lo que lee: topic keys de SDD-Legacy (legacy/*), ATL equipo (team/*), ATL pipeline (project/config, project/github-context). Ver tabla completa en docs/plugins/sdd-intake.md.
n8n-studio¶
Prefijo principal: pipeline/ y patterns/. Proyecto Engram independiente.
| Topic Key | Tipo dato | Writer | Reader | Descripcion |
|---|---|---|---|---|
pipeline/automation-spec |
string (ruta al spec) | Orquestador | n8n-analyst | Ruta al Automation Spec generado |
pipeline/build-plan |
JSON (plan de construccion) | n8n-analyst | n8n-builder | Nodos, conexiones, configuracion, credenciales |
pipeline/workflow-id |
string (ID del workflow) | n8n-builder | n8n-tester, n8n-reviewer | ID del workflow creado en n8n |
pipeline/test-report |
JSON (resultados de tests) | n8n-tester | n8n-reviewer, n8n-deploy | PASS/FAIL por criterio de aceptacion |
pipeline/review-report |
JSON (review de calidad) | n8n-reviewer | n8n-deploy | Veredicto: APPROVED, NEEDS_CHANGES, BLOCKED |
pipeline/state |
JSON (estado del DAG) | Orquestador | Orquestador | Estado actual del pipeline |
patterns/{tipo} |
JSON (patrones reutilizables) | automation-wizard | automation-wizard (futuras sesiones) | Patrones de automatizacion descubiertos |
Convenciones de Naming¶
Prefijos de topic keys por plugin¶
| Prefijo | Propietario | Descripcion |
|---|---|---|
project/ |
Compartido | Datos del proyecto visibles para todos los plugins |
team/ |
ATL Inteliside | Conocimiento permanente del equipo |
sdd/{feature}/ |
ATL Inteliside (pipeline) | Artefactos efimeros del pipeline de implementacion |
legacy/ |
SDD-Legacy | Artefactos del onboarding legacy |
re-wizard/{id}/ |
RE-Wizard | Artefactos del analisis de ingenieria inversa |
ux-studio/ |
UX Studio | Artefactos del pipeline de diseno |
intake/ |
SDD-Intake | Artefactos internos del intake |
pipeline/ |
n8n-studio | Estado del pipeline de automatizacion |
patterns/ |
n8n-studio | Patrones de automatizacion reutilizables |
Reglas de naming¶
- Separador: barra (
/) para jerarquia, guion (-) para palabras dentro de un segmento. - Formato de nombres: kebab-case en minusculas (
feat-user-auth, nofeat_User_Auth). - IDs parametricos:
{feature-name},{domain},{analysis-id},{tema},{area},{descripcion}— siempre kebab-case. - Prefijo obligatorio: cada plugin DEBE usar su prefijo asignado. RE-Wizard nunca escribe a
sdd/,team/nilegacy/. - Excepcion
project/: topic keys bajoproject/son compartidos. Multiples plugins pueden escribirlos, pero con reglas de prioridad (el primero que lo cree gana; los demas lo detectan y reutilizan). - Excepcion
sdd/{feature}/feature-spec: SDD-Intake escribe en este topic key usando el mismo formato que SDD-Wizards. ATL no distingue el origen.
Reglas de convivencia entre plugins¶
| Regla | Descripcion |
|---|---|
| No sobreescribir sin confirmacion | Si project/features/{name} ya existe (de otro plugin), pedir confirmacion al usuario |
| Deteccion antes de creacion | Siempre buscar si el topic key existe antes de escribir en project/* |
| Aislamiento de prefijos | Cada plugin solo escribe en sus prefijos propios + project/* compartido |
| Compatibilidad de schemas | Feature Specs de todos los origenes (Wizards, Legacy, RE-Wizard, Intake) DEBEN seguir el mismo schema |
Flujo de Datos Inter-Plugin¶
Path A: Proyecto nuevo (greenfield)¶
SDD-Wizards ATL Inteliside
─────────── ──────────────
project/prd ─────────────────────→ orchestrador lee PRD
project/stack ───────────────────→ sdd-init lee stack
project/github-context ──────────→ sdd-from-github lee repo info
project/features/{name} ─────────→ sdd-from-github lee Feature Spec
project/handoff/{name} ──────────→ sdd-from-github detecta feature lista
sdd/{feature}/feature-spec ──→ pipeline interno
team/decisions/{tema} ───────→ conocimiento permanente
team/patterns/{area} ────────→ conocimiento permanente
team/completed/{feature} ────→ conocimiento permanente
Path B: Con diseno UI/UX¶
SDD-Wizards UX Studio ATL Inteliside
─────────── ───────── ──────────────
project/prd ──────→ ux-studio/research-report
ux-studio/ux-brief
ux-studio/design-direction
ux-studio/design-spec ──────→ sdd-design lee Design Spec
Path C: Proyecto legacy¶
SDD-Legacy SDD-Intake ATL Inteliside
────────── ────────── ──────────────
legacy/audit ─────────────────────→ lee health score
legacy/features/{name} ──────────→ detecta solapamiento
legacy/rules/{domain} ───────────→ reglas a respetar
legacy/conventions ──────────────→ patrones a referenciar
legacy/onboard-status ───────────→ determina nivel
project/github-context ──────────→ sdd-from-github
project/config ──────────────────→ sdd-init
sdd/{feat}/feature-spec →sdd-from-github
Path D: Ingenieria inversa¶
RE-Wizard ATL Inteliside
───────── ──────────────
re-wizard/{id}/recon
re-wizard/{id}/architecture
re-wizard/{id}/features
re-wizard/{id}/business-rules ────→ (SDD-Intake puede cruzar)
project/features/{name} ──────────→ sdd-from-github lee Feature Spec
project/features-index ───────────→ ATL conoce todas las features
project/github-context ───────────→ ATL sabe donde estan los milestones
project/stack ────────────────────→ sdd-init lee stack detectado
Path E: Automatizacion n8n (independiente)¶
n8n-studio (proyecto Engram separado)
──────────
pipeline/automation-spec → n8n-analyst
pipeline/build-plan ─────→ n8n-builder
pipeline/workflow-id ────→ n8n-tester → n8n-reviewer → n8n-deploy
patterns/{tipo} ─────────→ automation-wizard (futuras sesiones)
Protocolos Comunes¶
Startup Read Protocol¶
Cada subagente o wizard al iniciar DEBE:
1. mem_context(project: {engram_project}) → contexto general
2. mem_search(project: {engram_project}, query: "{artefactos esperados}") → buscar prerequisitos
3. Si el prerequisito no existe y es bloqueante → BLOQUEAR con mensaje claro
Write Protocol¶
Al completar trabajo, cada componente DEBE llamar mem_save con:
{
"project": "{proyecto correcto (team o pipeline)}",
"title": "[Verbo] + [que] en [feature]",
"type": "decision | pattern | bugfix | discovery | config",
"topic_key": "{prefijo}/{artefacto}",
"content": { "...schema JSON fijo..." }
}
Recuperacion Post-Compactacion¶
1. mem_context(project: {engram_project/pipeline})
2. mem_search(project: {engram_project/pipeline}, query: "{feature activa}")
3. mem_get_observation({id del artefacto mas reciente})
4. Recien entonces continuar
Contrato Engram Unificado — Marketplace Inteliside v1.1.0