workspace-v1/orchestration/procesos/GUIA-ONBOARDING-PROYECTO.md

GUIA: ONBOARDING DE NUEVO PROYECTO

Version: 1.0.0 Fecha: 2025-12-12 Sistema: SIMCO + CAPVED Proposito: Checklist completo para crear un nuevo proyecto con estructura SIMCO

---

RESUMEN

Esta guia proporciona todos los pasos necesarios para crear un nuevo proyecto en el workspace que cumpla con el sistema SIMCO y permita trabajar con agentes de forma efectiva.

---

PREREQUISITOS

antes_de_empezar:
  - [ ] Nombre del proyecto definido (lowercase, sin espacios)
  - [ ] Tipo de proyecto identificado (STANDALONE | SUITE | VERTICAL)
  - [ ] Stack tecnologico decidido
  - [ ] Workspace clonado y actualizado

---

FASE 1: CREAR ESTRUCTURA DE CARPETAS

1.1 Estructura Base del Proyecto

# Reemplazar {proyecto} con el nombre real
PROJECT_NAME="{proyecto}"
PROJECT_PATH="${HOME}/workspace/projects/${PROJECT_NAME}"

# Crear estructura principal
mkdir -p "${PROJECT_PATH}"/{apps,docs,orchestration}

# Crear estructura de apps
mkdir -p "${PROJECT_PATH}/apps"/{database,backend,frontend}

# Crear estructura de database
mkdir -p "${PROJECT_PATH}/apps/database"/{ddl,seeds,scripts}
mkdir -p "${PROJECT_PATH}/apps/database/ddl/schemas"

# Crear estructura de backend
mkdir -p "${PROJECT_PATH}/apps/backend"/{src,test}
mkdir -p "${PROJECT_PATH}/apps/backend/src"/{modules,shared,config}

# Crear estructura de frontend
mkdir -p "${PROJECT_PATH}/apps/frontend"/{src,public}
mkdir -p "${PROJECT_PATH}/apps/frontend/src"/{components,hooks,pages,stores,types,services}

1.2 Estructura de Orchestration (SIMCO)

# Crear estructura de orchestration completa
mkdir -p "${PROJECT_PATH}/orchestration"/{00-guidelines,01-analisis,02-planeacion,03-tareas,04-ejecucion-logs,05-validaciones,06-subagentes,estados,inventarios,trazas,directivas,prompts,templates}

1.3 Estructura de Documentacion

# Crear estructura de docs
mkdir -p "${PROJECT_PATH}/docs"/{00-vision-general,95-guias-desarrollo,97-adr}

---

FASE 2: CREAR ARCHIVOS OBLIGATORIOS

2.1 CONTEXTO-PROYECTO.md

Crear orchestration/00-guidelines/CONTEXTO-PROYECTO.md:

# Contexto del Proyecto - {NOMBRE_PROYECTO}

## Identificacion

| Campo | Valor |
|-------|-------|
| **Nombre** | {NOMBRE_PROYECTO} |
| **Tipo** | {Descripcion del proyecto} |
| **Estado** | Inicial |
| **Version** | 0.1.0 |

## Descripcion

{Descripcion breve del proyecto y su proposito}

---

## VARIABLES PARA DIRECTIVAS GLOBALES

```yaml
# Identificacion del Proyecto
PROJECT:             {proyecto}
PROJECT_NAME:        {NOMBRE_PROYECTO}

# Paths Principales
PROJECT_ROOT:        ~/workspace/projects/{proyecto}
APPS_ROOT:           ~/workspace/projects/{proyecto}/apps
DOCS_ROOT:           ~/workspace/projects/{proyecto}/docs
ORCHESTRATION:       ~/workspace/projects/{proyecto}/orchestration

# Base de Datos
DB_NAME:             {proyecto}_db
DB_DDL_PATH:         ~/workspace/projects/{proyecto}/apps/database/ddl
DB_SCRIPTS_PATH:     ~/workspace/projects/{proyecto}/apps/database
DB_SEEDS_PATH:       ~/workspace/projects/{proyecto}/apps/database/seeds

# Backend
BACKEND_ROOT:        ~/workspace/projects/{proyecto}/apps/backend
BACKEND_SRC:         ~/workspace/projects/{proyecto}/apps/backend/src

# Frontend
FRONTEND_ROOT:       ~/workspace/projects/{proyecto}/apps/frontend
FRONTEND_SRC:        ~/workspace/projects/{proyecto}/apps/frontend/src

Stack Tecnologico

Backend

• Framework: {NestJS / Express / FastAPI}
• Lenguaje: {TypeScript / Python}
• ORM: {TypeORM / Prisma / SQLAlchemy}

Frontend

• Framework: {React / Vue / Next.js}
• Lenguaje: TypeScript
• State: {Zustand / Redux / Pinia}

Database

• Engine: PostgreSQL 15+
• Schemas: {lista de schemas planificados}

Paths de Trabajo

~/workspace/projects/{proyecto}/
├── apps/
│   ├── backend/          → API
│   ├── frontend/         → UI
│   └── database/         → DDL PostgreSQL
├── docs/                 → Documentacion
└── orchestration/        → Sistema SIMCO

### 2.2 HERENCIA-SIMCO.md

Copiar template desde core y adaptar:

```bash
cp "${HOME}/workspace/core/orchestration/templates/HERENCIA-SIMCO.md" \
   "${PROJECT_PATH}/orchestration/00-guidelines/HERENCIA-SIMCO.md"

Luego editar y reemplazar variables {VARIABLE}.

2.3 PROXIMA-ACCION.md

Crear orchestration/PROXIMA-ACCION.md:

# PROXIMA ACCION

**Fecha actualizacion:** {YYYY-MM-DD}
**Actualizado por:** {Agente/Humano}
**Proyecto:** {NOMBRE_PROYECTO}

## Estado del Desarrollo

**Fase actual:** Inicial
**Progreso:** 0%

## Siguiente Tarea Prioritaria

**ID:** SETUP-001
**Tipo:** Configuracion
**Descripcion:** Configurar entorno de desarrollo inicial

### Pre-requisitos
- [x] Estructura de carpetas creada
- [ ] Dependencias instaladas
- [ ] Base de datos configurada

### Contexto
Proyecto recien creado, necesita configuracion inicial.

## Tareas Pendientes

1. **SETUP-001:** Configurar package.json y dependencias
2. **SETUP-002:** Crear esquema inicial de base de datos
3. **SETUP-003:** Configurar backend con primera entidad

## Bloqueadores Activos

Ninguno

## Notas para Siguiente Sesion

Proyecto recien creado con estructura SIMCO.

2.4 REGISTRO-SUBAGENTES.json

Crear orchestration/estados/REGISTRO-SUBAGENTES.json:

{
  "version": "2.0",
  "proyecto": "{proyecto}",
  "fecha_creacion": "{YYYY-MM-DD}",
  "ultima_actualizacion": "{YYYY-MM-DD}T00:00:00Z",
  "limite_maximo": 15,
  "slots_disponibles": 15,
  "subagentes": {
    "NEXUS-DATABASE": {
      "nombre": "NEXUS-DATABASE",
      "tipo": "especializado",
      "estado": "disponible",
      "responsabilidades": [
        "Gestion de esquemas SQL",
        "DDL: tablas, indices, constraints",
        "Seeds y migraciones"
      ],
      "areas": ["apps/database/"],
      "prompt": "core/orchestration/agents/perfiles/PERFIL-DATABASE.md",
      "ultima_interaccion": null,
      "salud": {"status": "ready"}
    },
    "NEXUS-BACKEND": {
      "nombre": "NEXUS-BACKEND",
      "tipo": "especializado",
      "estado": "disponible",
      "responsabilidades": [
        "API REST endpoints",
        "Services y DTOs",
        "Logica de negocio"
      ],
      "areas": ["apps/backend/"],
      "prompt": "core/orchestration/agents/perfiles/PERFIL-BACKEND.md",
      "ultima_interaccion": null,
      "salud": {"status": "ready"}
    },
    "NEXUS-FRONTEND": {
      "nombre": "NEXUS-FRONTEND",
      "tipo": "especializado",
      "estado": "disponible",
      "responsabilidades": [
        "Componentes UI",
        "Paginas y hooks",
        "Integracion con APIs"
      ],
      "areas": ["apps/frontend/"],
      "prompt": "core/orchestration/agents/perfiles/PERFIL-FRONTEND.md",
      "ultima_interaccion": null,
      "salud": {"status": "ready"}
    }
  }
}

2.5 Inventarios Iniciales

Crear orchestration/inventarios/MASTER_INVENTORY.yml:

# INVENTARIO MAESTRO - {NOMBRE_PROYECTO}

version: "1.0.0"
proyecto: "{NOMBRE_PROYECTO}"
fecha_creacion: "{YYYY-MM-DD}"
ultima_actualizacion: "{YYYY-MM-DD}"

resumen:
  estado_general: "INICIAL"

  database:
    schemas: 0
    tables: 0
    status: "PENDIENTE"

  backend:
    modules: 0
    entities: 0
    endpoints: 0
    status: "PENDIENTE"

  frontend:
    components: 0
    pages: 0
    status: "PENDIENTE"

Crear archivos vacios para inventarios por capa:

touch "${PROJECT_PATH}/orchestration/inventarios/DATABASE_INVENTORY.yml"
touch "${PROJECT_PATH}/orchestration/inventarios/BACKEND_INVENTORY.yml"
touch "${PROJECT_PATH}/orchestration/inventarios/FRONTEND_INVENTORY.yml"

2.6 Trazas Iniciales

touch "${PROJECT_PATH}/orchestration/trazas/TRAZA-TAREAS-DATABASE.md"
touch "${PROJECT_PATH}/orchestration/trazas/TRAZA-TAREAS-BACKEND.md"
touch "${PROJECT_PATH}/orchestration/trazas/TRAZA-TAREAS-FRONTEND.md"

---

FASE 3: CONFIGURAR PROYECTO TECNICO

3.1 Backend (NestJS ejemplo)

cd "${PROJECT_PATH}/apps/backend"
npm init -y
# O usar CLI de NestJS:
# npx @nestjs/cli new . --skip-git --package-manager npm

3.2 Frontend (React + Vite ejemplo)

cd "${PROJECT_PATH}/apps/frontend"
npm create vite@latest . -- --template react-ts

3.3 Database

Crear script inicial apps/database/create-database.sh:

#!/bin/bash
# Script para crear/recrear base de datos

DB_NAME="${1:-{proyecto}_db}"

echo "Creando base de datos: $DB_NAME"

# Ejecutar DDL
for schema_dir in ddl/schemas/*/; do
    if [ -d "$schema_dir" ]; then
        echo "Procesando schema: $(basename $schema_dir)"
        # ... logica de creacion
    fi
done

echo "Base de datos creada exitosamente"

---

FASE 4: VALIDAR ESTRUCTURA

4.1 Ejecutar Script de Validacion

~/workspace/devtools/scripts/validation/validate-propagation.sh

4.2 Checklist Manual

estructura_carpetas:
  - [ ] apps/database/ddl/ existe
  - [ ] apps/backend/src/ existe
  - [ ] apps/frontend/src/ existe
  - [ ] orchestration/00-guidelines/ existe
  - [ ] orchestration/inventarios/ existe
  - [ ] orchestration/estados/ existe
  - [ ] orchestration/trazas/ existe

archivos_obligatorios:
  - [ ] CONTEXTO-PROYECTO.md creado y configurado
  - [ ] HERENCIA-SIMCO.md copiado y adaptado
  - [ ] PROXIMA-ACCION.md creado
  - [ ] REGISTRO-SUBAGENTES.json creado
  - [ ] MASTER_INVENTORY.yml creado

configuracion_tecnica:
  - [ ] package.json en backend
  - [ ] package.json en frontend
  - [ ] Script de creacion de DB

---

FASE 5: PRIMER COMMIT

cd "${PROJECT_PATH}"

git init
git add .
git commit -m "feat: Initial project structure with SIMCO

- Created folder structure for apps, docs, orchestration
- Added CONTEXTO-PROYECTO.md with project variables
- Added HERENCIA-SIMCO.md for directive inheritance
- Added REGISTRO-SUBAGENTES.json for agent tracking
- Added initial inventories and traces

Generated with SIMCO system v2.2.0"

---

FASE 6: REGISTRAR EN WORKSPACE

6.1 Actualizar WORKSPACE-STATUS.md

Agregar entrada en ~/workspace/orchestration/WORKSPACE-STATUS.md:

## Proyectos Activos

| Proyecto | Estado | Ultima Actividad |
|----------|--------|------------------|
| {proyecto} | INICIAL | {YYYY-MM-DD} |

6.2 Actualizar WORKSPACE-INDEX.md (si existe)

Agregar referencia al nuevo proyecto.

---

CHECKLIST FINAL

onboarding_completo:
  fase_1_estructura:
    - [ ] Carpetas de apps creadas
    - [ ] Carpetas de orchestration creadas
    - [ ] Carpetas de docs creadas

  fase_2_archivos:
    - [ ] CONTEXTO-PROYECTO.md
    - [ ] HERENCIA-SIMCO.md
    - [ ] PROXIMA-ACCION.md
    - [ ] REGISTRO-SUBAGENTES.json
    - [ ] MASTER_INVENTORY.yml
    - [ ] Inventarios por capa (vacios)
    - [ ] Trazas (vacias)

  fase_3_tecnico:
    - [ ] Backend inicializado
    - [ ] Frontend inicializado
    - [ ] Scripts de DB creados

  fase_4_validacion:
    - [ ] Script de validacion ejecutado
    - [ ] Sin errores criticos

  fase_5_git:
    - [ ] Primer commit realizado

  fase_6_workspace:
    - [ ] Registrado en WORKSPACE-STATUS

---

PROXIMO PASO

Una vez completado el onboarding, el proyecto esta listo para recibir tareas usando el patron:

"Seras {PERFIL}-Agent en {PROYECTO} para {TAREA}"

Los agentes cargaran automaticamente:

1. CONTEXTO-PROYECTO.md
2. HERENCIA-SIMCO.md
3. Inventarios del proyecto
4. Directivas SIMCO relevantes

---

Version: 1.0.0 | Sistema: SIMCO + CAPVED