workspace-v1/orchestration/directivas/simco/SIMCO-DOCUMENTACION-PROYECTO.md

SIMCO-DOCUMENTACION-PROYECTO

Version: 1.0.0 Tipo: Directiva Operacional Prioridad: P0 Alias: @DOC_PROYECTO Creado: 2026-01-10 Hereda: PRINCIPIO-DOC-PRIMERO.md

---

1. Proposito y Alcance

Esta directiva establece el estandar base para la documentacion de proyectos en el workspace. Define la estructura obligatoria de directorios, archivos minimos requeridos y convenciones de actualizacion.

Aplica a: Todos los proyectos en workspace-v1

---

2. Principios Fundamentales

2.1 Documentar Antes de Implementar

Siguiendo @DOC-PRIMERO, toda funcionalidad debe documentarse antes de su implementacion.

2.2 Una Sola Fuente de Verdad (SSOT)

Los inventarios YAML son la fuente canonica de estado del proyecto.

2.3 Estructura Predecible

Todos los proyectos siguen la misma estructura base para facilitar navegacion.

2.4 Trazabilidad Completa

Cada documento debe tener ID unico y referencias cruzadas funcionales.

---

3. Estructura Obligatoria de /docs

docs/
├── _MAP.md                    [OBLIGATORIO] Indice navegable
├── README.md                  [OBLIGATORIO] Introduccion al proyecto
├── 00-vision-general/         [OBLIGATORIO] Vision y estrategia
│   ├── VISION-*.md
│   └── ARQUITECTURA-*.md
├── 01-fase-{nombre}/          [POR FASE] Una carpeta por fase
│   ├── _MAP.md                [OBLIGATORIO en cada fase]
│   ├── requerimientos/
│   ├── especificaciones/
│   └── historias-usuario/
├── 02-fase-{nombre}/
├── ...
├── 90-transversal/            [OPCIONAL] Contenido compartido entre fases
├── 95-guias-desarrollo/       [OPCIONAL] Guias tecnicas
├── 96-quick-reference/        [OPCIONAL] Referencias rapidas
├── 97-adr/                    [SI APLICA] Decisiones arquitectonicas
│   └── ADR-{NNN}-{desc}.md
└── 99-finiquito/              [OPCIONAL] Documentacion de cierre

---

4. Estructura Obligatoria de /orchestration

orchestration/
├── 00-guidelines/             [OBLIGATORIO]
│   ├── CONTEXTO-PROYECTO.md   [OBLIGATORIO] Variables del proyecto
│   └── HERENCIA-SIMCO.md      [OBLIGATORIO] Directivas heredadas
├── analisis/                  [RECOMENDADO] Documentos de analisis
│   ├── ANALISIS-*.md
│   ├── PLAN-*.md
│   └── VALIDACION-*.md
├── inventarios/               [OBLIGATORIO]
│   ├── MASTER_INVENTORY.yml   [OBLIGATORIO]
│   ├── DATABASE_INVENTORY.yml [SI APLICA]
│   ├── BACKEND_INVENTORY.yml  [SI APLICA]
│   └── FRONTEND_INVENTORY.yml [SI APLICA]
├── reportes/                  [RECOMENDADO]
│   └── REPORTE-*.md
├── trazas/                    [OPCIONAL]
│   └── TRAZA-*.md
├── CONTEXT-MAP.yml            [OBLIGATORIO] Mapeo de contexto
├── PROJECT-STATUS.md          [OBLIGATORIO] Estado actual
├── PROXIMA-ACCION.md          [RECOMENDADO] Siguiente paso
└── README.md                  [OBLIGATORIO] Descripcion de orchestration

---

5. Archivos Minimos Requeridos

Por Tipo de Proyecto

Archivo	Standalone	Suite	Suite-Core	Vertical
docs/_MAP.md	SI	SI	SI	SI
docs/README.md	SI	SI	SI	SI
docs/00-vision-general/	SI	SI	SI	OPCIONAL
orchestration/00-guidelines/CONTEXTO-PROYECTO.md	SI	SI	SI	SI
orchestration/00-guidelines/HERENCIA-SIMCO.md	SI	SI	SI	SI
orchestration/inventarios/MASTER_INVENTORY.yml	SI	SI	SI	SI
orchestration/CONTEXT-MAP.yml	SI	SI	SI	SI
orchestration/PROJECT-STATUS.md	SI	SI	SI	SI

---

6. API Versioning

6.1 Estandar de Versionado

Las APIs REST deben seguir el patron de versionado:

/api/v{N}/{recurso}

Ejemplos:
/api/v1/users
/api/v2/products

6.2 Reglas de Versionado

1. Major Version (v1 → v2): Cambios breaking
2. Endpoint Deprecation: Documentar en ADR
3. Header Version: Soportar Accept-Version header como alternativa
4. Documentacion: Cada version debe tener su especificacion OpenAPI

---

7. Ciclo de Vida de Documentos

┌─────────────┐     ┌──────────┐     ┌────────────┐
│  Creacion   │ --> │ Revision │ --> │ Aprobacion │
└─────────────┘     └──────────┘     └────────────┘
                                            │
                                            v
┌─────────────┐     ┌──────────────┐  ┌──────────────┐
│ Deprecacion │ <-- │ Actualizacion │<-│ Publicacion  │
└─────────────┘     └──────────────┘  └──────────────┘

Estados Validos

Estado	Descripcion
Draft	En creacion, no revisado
InReview	Bajo revision
Approved	Aprobado para uso
Published	Publicado y vigente
Updated	Actualizado (version++)
Deprecated	Marcado para eliminacion
Archived	Archivado, no vigente

---

8. Validaciones Requeridas

8.1 Frontmatter

Todos los documentos MD deben tener frontmatter valido:

---
id: "{PREFIJO}-{MODULO}-{NUM}"
title: "{Titulo descriptivo}"
type: "{Requirement|Specification|UserStory|ADR|Epic}"
status: "{Draft|InReview|Approved|Published|Deprecated}"
priority: "{P0|P1|P2|P3}"
version: "{SEMVER}"
created_date: "{YYYY-MM-DD}"
updated_date: "{YYYY-MM-DD}"
---

8.2 Referencias

• Todas las referencias cruzadas deben funcionar (links validos)
• No deben existir referencias huerfanas
• IDs deben ser unicos en el proyecto

8.3 Estados

• Estados deben ser consistentes con el contenido
• Documentos publicados deben estar completos
• Documentos deprecados deben indicar reemplazo

---

9. Validacion de Conformidad

Usar el checklist de documentacion para validar:

Ver: CHECKLIST-DOCUMENTACION-PROYECTO.md

---

10. Referencias

Directiva	Proposito
SIMCO-NOMENCLATURA.md	Patrones de nombres de archivos
SIMCO-ESTRUCTURA-DOCS.md	Estructura interna de documentos
SIMCO-INVENTARIOS.md	Formato de inventarios YAML
CHECKLIST-DOCUMENTACION-PROYECTO.md	Verificacion de conformidad

---

Ultima actualizacion: 2026-01-10 Mantenido por: Orchestration Team