# PLAN DE ESTANDARIZACION - DOCUMENTACION WORKSPACE **Fecha:** 2026-01-10 **Fase:** 2 - Planeacion **Estado:** EN_PROGRESO **Version:** 1.0.0 **Referencia:** ANALISIS-ESTANDARES-DOCUMENTACION-WORKSPACE-2026-01-10.md --- ## 1. OBJETIVO DEL PLAN Crear y documentar estandares, directivas y lineamientos para la documentacion de proyectos en el workspace, basados en los patrones identificados en: - gamilit (madurez 5.0) - erp-core (madurez 4.75) - michangarrito (madurez 3.75) - template-saas (madurez 3.5) --- ## 2. SEGMENTACION DE TAREAS ### 2.1 BLOQUE A: Directivas SIMCO Nuevas (7 directivas) | ID | Directiva | Prioridad | Dependencias | Tokens Est. | |----|-----------|-----------|--------------|-------------| | A1 | SIMCO-DOCUMENTACION-PROYECTO.md | P0 | Ninguna | ~800 | | A2 | SIMCO-NOMENCLATURA.md | P0 | A1 | ~600 | | A3 | SIMCO-ESTRUCTURA-DOCS.md | P0 | A1, A2 | ~700 | | A4 | SIMCO-INVENTARIOS.md | P1 | A1 | ~500 | | A5 | SIMCO-TESTING.md | P0 | Ninguna | ~600 | | A6 | SIMCO-MIGRACIONES-BD.md | P0 | SIMCO-DDL | ~500 | | A7 | SIMCO-INTEGRACIONES-EXTERNAS.md | P1 | Ninguna | ~500 | ### 2.2 BLOQUE B: Templates Nuevos (5 templates) | ID | Template | Prioridad | Dependencias | Tokens Est. | |----|----------|-----------|--------------|-------------| | B1 | TEMPLATE-EPICA-ESTANDAR.md | P0 | A3 | ~400 | | B2 | TEMPLATE-MODULO-ESTANDAR.md | P0 | A3 | ~400 | | B3 | TEMPLATE-MAP-INDICE.md | P0 | A2 | ~300 | | B4 | TEMPLATE-INVENTARIO-PROYECTO.md | P1 | A4 | ~350 | | B5 | TEMPLATE-INTEGRACION-EXTERNA.md | P1 | A7 | ~300 | ### 2.3 BLOQUE C: Checklists (3 checklists) | ID | Checklist | Prioridad | Dependencias | Tokens Est. | |----|-----------|-----------|--------------|-------------| | C1 | CHECKLIST-DOCUMENTACION-PROYECTO.md | P0 | A1, A2, A3 | ~400 | | C2 | CHECKLIST-INVENTARIOS.md | P1 | A4 | ~300 | | C3 | CHECKLIST-NOMENCLATURA.md | P0 | A2 | ~300 | ### 2.4 BLOQUE D: Actualizacion de Indices y Referencias | ID | Archivo | Accion | Prioridad | |----|---------|--------|-----------| | D1 | INDICE-DIRECTIVAS-WORKSPACE.yml | Agregar nuevas directivas | P0 | | D2 | orchestration/directivas/simco/_MAP.md | Actualizar indice | P0 | | D3 | orchestration/templates/_MAP.md | Actualizar indice | P0 | | D4 | orchestration/checklists/_MAP.md | Crear/Actualizar | P0 | | D5 | shared/knowledge-base/standards/ | Agregar estandares | P1 | ### 2.5 BLOQUE E: Integracion en Proyectos | ID | Proyecto | Accion | Prioridad | |----|----------|--------|-----------| | E1 | gamilit | Validar conformidad, ajustar si necesario | P2 | | E2 | erp-core | Validar conformidad, ajustar si necesario | P2 | | E3 | michangarrito | Aplicar estandares faltantes | P1 | | E4 | template-saas | Aplicar estandares faltantes | P1 | --- ## 3. DETALLE DE TAREAS POR BLOQUE ### 3.1 BLOQUE A: Directivas SIMCO #### A1: SIMCO-DOCUMENTACION-PROYECTO.md **Objetivo:** Establecer el estandar base para documentacion de proyectos **Contenido:** ``` 1. Proposito y alcance 2. Principios fundamentales de documentacion 3. Estructura obligatoria de /docs 4. Estructura obligatoria de /orchestration 5. Archivos minimos requeridos 6. Ciclo de vida de documentos 7. Validaciones requeridas ``` **Secciones obligatorias:** - Estructura de directorios - Archivos minimos - Convenciones de actualizacion - Referencias cruzadas #### A2: SIMCO-NOMENCLATURA.md **Objetivo:** Estandarizar nomenclatura de archivos y directorios **Contenido:** ``` 1. Principios de nomenclatura 2. Patrones por tipo de archivo: - Requerimientos (RF-*) - Especificaciones (ET-*) - User Stories (US-*) - Epicas (EAI-*, EXT-*, MCH-*, MGN-*) - Modulos (SAAS-*) - ADRs (ADR-*) - Planes (PLAN-*) - Analisis (ANALISIS-*) - Reportes (REPORTE-*) - Trazas (TRAZA-*) - Inventarios (*_INVENTORY.yml) - Indices (_MAP.md) 3. Patrones de directorios: - Numeracion de fases (00-99) - Kebab-case para nombres 4. Casos especiales 5. Anti-patrones a evitar ``` #### A3: SIMCO-ESTRUCTURA-DOCS.md **Objetivo:** Definir estructura interna de documentos **Contenido:** ``` 1. Frontmatter YAML obligatorio 2. Estructura de contenido por tipo: - Requerimientos - Especificaciones - User Stories - Epicas/Modulos - ADRs - _MAP.md (indices) 3. Secciones obligatorias vs opcionales 4. Formato de tablas 5. Diagramas ASCII 6. Referencias cruzadas 7. Footer de documentos ``` #### A4: SIMCO-INVENTARIOS.md **Objetivo:** Estandarizar inventarios YAML **Contenido:** ``` 1. Proposito de inventarios 2. Tipos de inventarios: - MASTER_INVENTORY.yml - DATABASE_INVENTORY.yml - BACKEND_INVENTORY.yml - FRONTEND_INVENTORY.yml 3. Estructura YAML por tipo 4. Campos obligatorios 5. Actualizacion y mantenimiento 6. Validacion de inventarios ``` #### A5: SIMCO-TESTING.md **Objetivo:** Establecer estandares minimos de testing **Contenido:** ``` 1. Principios de testing 2. Cobertura minima por tipo: - Backend: 70% unit, 50% integration - Frontend: 60% components - Database: 100% migrations 3. Tipos de tests requeridos: - Unit tests - Integration tests - E2E tests (si aplica) 4. Nomenclatura de archivos de test 5. Estructura de carpetas de test 6. Comandos de ejecucion 7. Integracion con CI/CD ``` #### A6: SIMCO-MIGRACIONES-BD.md **Objetivo:** Protocolo de migraciones de base de datos **Contenido:** ``` 1. Principios de migraciones 2. Nomenclatura de archivos: - {TIMESTAMP}-{descripcion}.sql 3. Estructura de migracion 4. Rollback obligatorio 5. Testing de migraciones 6. Documentacion requerida 7. Flujo de aprobacion 8. Integracion con SIMCO-DDL ``` #### A7: SIMCO-INTEGRACIONES-EXTERNAS.md **Objetivo:** Estandar para documentar APIs externas **Contenido:** ``` 1. Cuando usar esta directiva 2. Estructura de documentacion: - Proveedor y proposito - Credenciales requeridas - Endpoints utilizados - Rate limits - Manejo de errores - Fallbacks 3. Multi-tenant considerations 4. Variables de entorno 5. Testing de integraciones ``` --- ### 3.2 BLOQUE B: Templates #### B1: TEMPLATE-EPICA-ESTANDAR.md ```markdown # {ID}: {Nombre Epica} ## Metadata - **Codigo:** {ID} - **Fase:** {N} - {Nombre Fase} - **Prioridad:** {P0|P1|P2|P3} - **Estado:** {Completado|En Proceso|Pendiente|Documentado} - **Fecha inicio:** {YYYY-MM-DD} - **Fecha fin estimada:** {YYYY-MM-DD} - **Story Points:** {N} ## Descripcion {Parrafo descriptivo del proposito de la epica} ## Objetivos 1. {Objetivo 1} 2. {Objetivo 2} 3. {Objetivo 3} ## Alcance ### Incluido - {Feature incluida 1} - {Feature incluida 2} ### Excluido - {Feature excluida 1} - {Feature excluida 2} ## Arquitectura {Diagrama ASCII o descripcion de arquitectura} ## Entregables | Entregable | Archivo/Ubicacion | Estado | |------------|-------------------|--------| | {Entregable 1} | {ruta} | {estado} | ## Dependencias ### Depende de - {Epica/Modulo del que depende} ### Bloquea a - {Epica/Modulo que bloquea} ## Criterios de Aceptacion - [ ] {Criterio 1} - [ ] {Criterio 2} - [ ] {Criterio 3} ## Notas Tecnicas {Consideraciones tecnicas importantes} ## Historias de Usuario Relacionadas - [US-{ID}](ruta/al/archivo.md) --- **Ultima actualizacion:** {YYYY-MM-DD} **Autor:** {Rol/Nombre} ``` #### B2: TEMPLATE-MODULO-ESTANDAR.md ```markdown # {ID}: {Nombre Modulo} ## Metadata - **Codigo:** {ID} - **Modulo:** {Nombre} - **Prioridad:** {P0|P1|P2} - **Estado:** {Completado|Implementado|Documentacion} - **Fase:** {N} - {Nombre Fase} ## Descripcion {Parrafo con proposito del modulo} ## Objetivos 1. {Objetivo 1} 2. {Objetivo 2} ## Alcance ### Incluido - {Feature incluida} ### Excluido - {Feature excluida} ## Modelo de Datos ### Tablas (schema: {schema_name}) **{nombre_tabla}** | Columna | Tipo | Descripcion | |---------|------|-------------| | id | UUID | PK | | tenant_id | UUID | FK tenants | | {campo} | {tipo} | {descripcion} | | created_at | TIMESTAMP | Fecha creacion | | updated_at | TIMESTAMP | Fecha actualizacion | ## Endpoints API | Metodo | Endpoint | Descripcion | |--------|----------|-------------| | POST | /api/{recurso} | Crear | | GET | /api/{recurso} | Listar | | GET | /api/{recurso}/:id | Obtener | | PUT | /api/{recurso}/:id | Actualizar | | DELETE | /api/{recurso}/:id | Eliminar | ## Configuracion ### Variables de Entorno ```env {PREFIJO}_{VARIABLE}={valor_ejemplo} ``` ## Roadmap / Estado | Feature | Estado | Prioridad | |---------|--------|-----------| | {Feature} | {estado} | {P0-P3} | --- **Ultima actualizacion:** {YYYY-MM-DD} ``` #### B3: TEMPLATE-MAP-INDICE.md ```markdown # _MAP: {Nombre Seccion} **Carpeta:** {ruta/relativa}/ **Proposito:** {Descripcion del proposito} **Estado:** {Actualizado|En construccion} **Ultima actualizacion:** {YYYY-MM-DD} --- ## Resumen | Metrica | Valor | |---------|-------| | Total archivos | {N} | | Documentos completados | {N} | | Documentos pendientes | {N} | | Progreso | {N}% | --- ## Contenido | Archivo | Tipo | Estado | Descripcion | |---------|------|--------|-------------| | [{archivo.md}](./{archivo.md}) | {tipo} | {estado} | {descripcion} | --- ## Navegacion por Caso de Uso ### Para {caso de uso 1}: 1. Leer [{archivo}](./{archivo}) 2. Revisar [{archivo}](./{archivo}) ### Para {caso de uso 2}: 1. Consultar [{archivo}](./{archivo}) --- ## Subdirectorios | Directorio | Descripcion | Archivos | |------------|-------------|----------| | [{dir}/](./{dir}/) | {descripcion} | {N} | --- ## Referencias Externas - [{Referencia}](../ruta/archivo.md) --- **Mantenido por:** {Rol} **Version:** {SEMVER} ``` #### B4: TEMPLATE-INVENTARIO-PROYECTO.md ```yaml # Inventario: {TIPO} # Proyecto: {nombre} # Version: {SEMVER} # Actualizado: {YYYY-MM-DD} metadata: proyecto: "{nombre}" tipo: "{MASTER|DATABASE|BACKEND|FRONTEND}" version: "{SEMVER}" updated: "{YYYY-MM-DD}" # Para MASTER_INVENTORY resumen: progreso_mvp: "{N}%" story_points_completados: {N} story_points_totales: {N} tareas_completadas: {N} tareas_totales: {N} fases: - nombre: "Fase {N}" codigo: "{CODIGO}" estado: "{completado|en_progreso|pendiente}" progreso: "{N}%" epicas: {N} aplicaciones: backend: - servicio: "{nombre}" ruta: "{ruta/relativa}" puerto: {N} estado: "{activo|inactivo}" frontend: - servicio: "{nombre}" ruta: "{ruta/relativa}" puerto: {N} estado: "{activo|inactivo}" # Para DATABASE_INVENTORY schemas: - nombre: "{schema}" descripcion: "{descripcion}" tablas: - nombre: "{tabla}" columnas: {N} estado: "{implementada|pendiente}" # Para BACKEND_INVENTORY modulos: - nombre: "{modulo}" ruta: "{ruta/relativa}" controllers: {N} services: {N} endpoints: {N} estado: "{implementado|pendiente}" # Para FRONTEND_INVENTORY paginas: - nombre: "{pagina}" ruta: "{ruta/relativa}" componentes: {N} estado: "{implementada|pendiente}" ``` #### B5: TEMPLATE-INTEGRACION-EXTERNA.md ```markdown # INT-{NNN}: {Nombre Integracion} ## Metadata - **Codigo:** INT-{NNN} - **Proveedor:** {Nombre del proveedor} - **Tipo:** {Pagos|Auth|Notificaciones|Storage|etc} - **Estado:** {Implementado|Documentado|Pendiente} - **Multi-tenant:** {Si|No} ## Descripcion {Proposito de la integracion} ## Credenciales Requeridas | Variable de Entorno | Descripcion | Requerido | |---------------------|-------------|-----------| | {PREFIJO}_{VAR} | {descripcion} | {Si|No} | ## Endpoints/SDK Utilizados | Operacion | Endpoint/Metodo | Descripcion | |-----------|-----------------|-------------| | {operacion} | {endpoint} | {descripcion} | ## Rate Limits - {limite}: {valor} ## Manejo de Errores | Codigo | Descripcion | Accion | |--------|-------------|--------| | {codigo} | {descripcion} | {accion} | ## Fallbacks - {Estrategia de fallback si aplica} ## Multi-tenant {Descripcion de como funciona en multi-tenant} ## Testing ```bash # Comando para probar integracion {comando} ``` ## Referencias - [Documentacion oficial]({url}) - [Modulo relacionado](../01-modulos/SAAS-{NNN}-{nombre}.md) --- **Ultima actualizacion:** {YYYY-MM-DD} ``` --- ### 3.3 BLOQUE C: Checklists #### C1: CHECKLIST-DOCUMENTACION-PROYECTO.md ```markdown # Checklist: Documentacion de Proyecto ## Estructura de /docs - [ ] Existe directorio /docs en raiz del proyecto - [ ] Existe /docs/_MAP.md como indice principal - [ ] Existe /docs/README.md - [ ] Existe /docs/00-vision-general/ - [ ] Existen directorios de fases numerados (01-, 02-, etc.) - [ ] Existe /docs/90-transversal/ si aplica - [ ] Existe /docs/97-adr/ si hay decisiones arquitectonicas ## Estructura de /orchestration - [ ] Existe directorio /orchestration - [ ] Existe CONTEXT-MAP.yml - [ ] Existe PROJECT-STATUS.md - [ ] Existe /orchestration/inventarios/ - [ ] Existe MASTER_INVENTORY.yml - [ ] Existe 00-guidelines/HERENCIA-SIMCO.md o HERENCIA-DIRECTIVAS.md ## Archivos Minimos - [ ] _MAP.md en cada directorio principal - [ ] README.md en /docs raiz - [ ] Al menos un inventario YAML ## Nomenclatura - [ ] Archivos siguen patron establecido (RF-, ET-, US-, etc.) - [ ] Directorios usan numeracion y kebab-case - [ ] Fechas en formato YYYY-MM-DD ## Contenido - [ ] Documentos tienen metadata (frontmatter o tabla) - [ ] IDs son unicos y siguen patron - [ ] Estados son consistentes - [ ] Referencias cruzadas funcionan ``` #### C2: CHECKLIST-INVENTARIOS.md ```markdown # Checklist: Inventarios YAML ## MASTER_INVENTORY.yml - [ ] Existe el archivo - [ ] Tiene campo metadata (proyecto, version, updated) - [ ] Tiene campo resumen con progreso - [ ] Tiene listado de fases - [ ] Tiene listado de aplicaciones - [ ] Fecha updated es reciente ## DATABASE_INVENTORY.yml - [ ] Existe el archivo - [ ] Lista todos los schemas - [ ] Cada schema tiene tablas documentadas - [ ] Estados son correctos (implementada/pendiente) ## BACKEND_INVENTORY.yml - [ ] Existe el archivo - [ ] Lista todos los modulos - [ ] Cuenta de controllers y services es correcta - [ ] Estados reflejan realidad ## FRONTEND_INVENTORY.yml - [ ] Existe el archivo - [ ] Lista todas las paginas - [ ] Cuenta de componentes es correcta - [ ] Estados reflejan realidad ## Validacion General - [ ] YAML es valido (sin errores de sintaxis) - [ ] Datos son consistentes entre inventarios - [ ] Numeros coinciden con codigo real ``` #### C3: CHECKLIST-NOMENCLATURA.md ```markdown # Checklist: Nomenclatura ## Archivos - [ ] Requerimientos: RF-{MODULO}-{NUM}.md - [ ] Especificaciones: ET-{TIPO}-{MODULO}.md - [ ] User Stories: US-{EPICA}-{NUM}-{desc}.md - [ ] ADRs: ADR-{NUM}-{descripcion}.md - [ ] Planes: PLAN-{DESC}-{FECHA}.md - [ ] Analisis: ANALISIS-{DESC}-{FECHA}.md - [ ] Reportes: REPORTE-{DESC}-{FECHA}.md - [ ] Trazas: TRAZA-{TIPO}-{DESC}.md - [ ] Inventarios: {TIPO}_INVENTORY.yml - [ ] Indices: _MAP.md ## Directorios - [ ] Vision: 00-vision-general/ - [ ] Fases: {NN}-fase-{nombre}/ o {NN}-{nombre}/ - [ ] Transversal: 90-transversal/ - [ ] Guias: 95-guias-desarrollo/ - [ ] Quick ref: 96-quick-reference/ - [ ] ADRs: 97-adr/ - [ ] Finiquito: 99-finiquito/ ## IDs - [ ] Epicas: EAI-{NUM}, EXT-{NUM}, MCH-{NUM}, MGN-{NUM} - [ ] Modulos: SAAS-{NUM} - [ ] Numeracion secuencial sin saltos - [ ] IDs unicos en todo el proyecto ## Fechas - [ ] Formato ISO 8601: YYYY-MM-DD - [ ] En nombres de archivo cuando aplica - [ ] En metadata de documentos ``` --- ## 4. ORDEN DE EJECUCION ### Sprint 1: Directivas Base (P0) ``` Dia 1-2: ├── A1: SIMCO-DOCUMENTACION-PROYECTO.md ├── A2: SIMCO-NOMENCLATURA.md └── A3: SIMCO-ESTRUCTURA-DOCS.md Dia 3: ├── A5: SIMCO-TESTING.md └── A6: SIMCO-MIGRACIONES-BD.md ``` ### Sprint 2: Templates y Checklists (P0) ``` Dia 1: ├── B1: TEMPLATE-EPICA-ESTANDAR.md ├── B2: TEMPLATE-MODULO-ESTANDAR.md └── B3: TEMPLATE-MAP-INDICE.md Dia 2: ├── C1: CHECKLIST-DOCUMENTACION-PROYECTO.md └── C3: CHECKLIST-NOMENCLATURA.md ``` ### Sprint 3: Complementarios (P1) ``` Dia 1: ├── A4: SIMCO-INVENTARIOS.md ├── A7: SIMCO-INTEGRACIONES-EXTERNAS.md └── B4: TEMPLATE-INVENTARIO-PROYECTO.md Dia 2: ├── B5: TEMPLATE-INTEGRACION-EXTERNA.md └── C2: CHECKLIST-INVENTARIOS.md ``` ### Sprint 4: Indices y Actualizaciones (P0) ``` Dia 1: ├── D1: INDICE-DIRECTIVAS-WORKSPACE.yml ├── D2: orchestration/directivas/simco/_MAP.md ├── D3: orchestration/templates/_MAP.md └── D4: orchestration/checklists/_MAP.md Dia 2: └── D5: shared/knowledge-base/standards/ ``` ### Sprint 5: Integracion en Proyectos (P1-P2) ``` Dia 1-2: ├── E3: michangarrito (aplicar estandares) └── E4: template-saas (aplicar estandares) Dia 3: ├── E1: gamilit (validar conformidad) └── E2: erp-core (validar conformidad) ``` --- ## 5. DEPENDENCIAS ENTRE TAREAS ``` A1 (SIMCO-DOCUMENTACION) ─────┬─────> B1 (TEMPLATE-EPICA) ├─────> B2 (TEMPLATE-MODULO) └─────> C1 (CHECKLIST-DOCS) A2 (SIMCO-NOMENCLATURA) ──────┬─────> B3 (TEMPLATE-MAP) └─────> C3 (CHECKLIST-NOMENCLATURA) A3 (SIMCO-ESTRUCTURA-DOCS) ───┬─────> B1 (TEMPLATE-EPICA) └─────> B2 (TEMPLATE-MODULO) A4 (SIMCO-INVENTARIOS) ───────┬─────> B4 (TEMPLATE-INVENTARIO) └─────> C2 (CHECKLIST-INVENTARIOS) A7 (SIMCO-INTEGRACIONES) ─────────> B5 (TEMPLATE-INTEGRACION) Todos (A*, B*, C*) ──────────────> D* (Indices) D* (Indices) ────────────────────> E* (Proyectos) ``` --- ## 6. ARCHIVOS A CREAR (RESUMEN) ### Directivas (7 archivos) ``` /orchestration/directivas/simco/ ├── SIMCO-DOCUMENTACION-PROYECTO.md [NUEVO] ├── SIMCO-NOMENCLATURA.md [NUEVO] ├── SIMCO-ESTRUCTURA-DOCS.md [NUEVO] ├── SIMCO-INVENTARIOS.md [NUEVO] ├── SIMCO-TESTING.md [NUEVO] ├── SIMCO-MIGRACIONES-BD.md [NUEVO] └── SIMCO-INTEGRACIONES-EXTERNAS.md [NUEVO] ``` ### Templates (5 archivos) ``` /orchestration/templates/ ├── TEMPLATE-EPICA-ESTANDAR.md [NUEVO] ├── TEMPLATE-MODULO-ESTANDAR.md [NUEVO] ├── TEMPLATE-MAP-INDICE.md [NUEVO] ├── TEMPLATE-INVENTARIO-PROYECTO.md [NUEVO] └── TEMPLATE-INTEGRACION-EXTERNA.md [NUEVO] ``` ### Checklists (3 archivos) ``` /orchestration/checklists/ ├── CHECKLIST-DOCUMENTACION-PROYECTO.md [NUEVO] ├── CHECKLIST-INVENTARIOS.md [NUEVO] └── CHECKLIST-NOMENCLATURA.md [NUEVO] ``` ### Actualizaciones (5 archivos) ``` /orchestration/INDICE-DIRECTIVAS-WORKSPACE.yml [ACTUALIZAR] /orchestration/directivas/simco/_MAP.md [ACTUALIZAR] /orchestration/templates/_MAP.md [ACTUALIZAR] /orchestration/checklists/_MAP.md [CREAR] /shared/knowledge-base/standards/ [AGREGAR] ``` **Total: 20 archivos** --- ## 7. METRICAS DE EXITO | Metrica | Objetivo | Validacion | |---------|----------|------------| | Directivas creadas | 7/7 | Contar archivos | | Templates creados | 5/5 | Contar archivos | | Checklists creados | 3/3 | Contar archivos | | Indices actualizados | 5/5 | Verificar links | | Proyectos validados | 4/4 | Ejecutar checklists | | Conformidad promedio | >4.0 | Matriz de madurez | --- **Documento generado:** 2026-01-10 **Siguiente fase:** VALIDACION DE PLANEACION