# Guia para Agentes de IA - Trading Platform

**Version:** 2.0.0
**Ultima actualizacion:** 2026-02-06
**Basado en:** SIMCO v4.0.0 + NEXUS v4.0

---

## 1. Estructura del Proyecto

### Ubicaciones Clave

| Tipo | Ubicacion |
|------|-----------|
| Documentacion general | `/docs/` |
| Planificacion | `/docs/planning/` |
| Definicion de Modulos | `/docs/02-definicion-modulos/` |
| Backlog | `/docs/04-fase-backlog/` |
| Transversal | `/docs/90-transversal/` |
| Guias de Desarrollo | `/docs/95-guias-desarrollo/` |
| Quick Reference | `/docs/96-quick-reference/` |
| ADRs | `/docs/97-adr/` |
| Tareas | `/docs/planning/tasks/` |
| Bugs | `/docs/planning/bugs/` |
| Tablero Kanban | `/docs/planning/Board.md` |
| Orquestacion | `/orchestration/` |
| Inventarios | `/orchestration/inventarios/` |
| Tareas Activas | `/orchestration/tareas/` |
| Tareas Archivadas | `/orchestration/tareas/_archive/` |

### Estructura de un Modulo (Epica)

```
docs/02-definicion-modulos/OQI-XXX-{nombre}/
├── _MAP.md              # Indice del modulo
├── README.md            # Descripcion del modulo
├── historias-usuario/   # User Stories (US-*.md)
├── requerimientos/      # Requerimientos Funcionales (RF-*.md)
├── especificaciones/    # Especificaciones Tecnicas (ET-*.md)
└── implementacion/      # Trazabilidad de implementacion
```

---

## 2. Prefijos de Nomenclatura

| Prefijo | Tipo | Ejemplo | Descripcion |
|---------|------|---------|-------------|
| OQI- | Epica/Modulo | OQI-001-fundamentos-auth | Modulos principales |
| US- | Historia de Usuario | US-AUTH-001 | User Stories |
| TASK- | Tarea | TASK-001 | Tareas ejecutables |
| BUG- | Bug | BUG-001 | Defectos/errores |
| RF- | Requerimiento Funcional | RF-AUTH-001 | Requerimientos |
| ET- | Especificacion Tecnica | ET-AUTH-001 | Especificaciones |
| ADR- | Decision Record | ADR-001 | Decisiones arquitectonicas |

### Categorias de User Stories

| Sufijo | Modulo | Epica |
|--------|--------|-------|
| AUTH | Autenticacion | OQI-001 |
| EDU | Educacion | OQI-002 |
| TRD | Trading Charts | OQI-003 |
| INV | Investment Accounts | OQI-004 |
| PAY | Payments/Stripe | OQI-005 |
| ML | ML Signals | OQI-006 |
| LLM | LLM Agent | OQI-007 |
| PFM | Portfolio Manager | OQI-008 |

---

## 3. Como Trabajar con Tareas

### Tomar una Tarea

1. **Identificar tarea** en `/docs/planning/Board.md` (columna "Por Hacer")
2. **Leer archivo** `TASK-XXX.md` correspondiente
3. **Editar YAML front-matter**:
   ```yaml
   status: "In Progress"
   assignee: "@NombreAgente"
   started_date: "YYYY-MM-DD"
   ```
4. **Mover tarea** a columna "En Progreso" en Board.md
5. **Commit**: `git commit -m "Start TASK-XXX: [descripcion breve]"`

### Completar una Tarea

1. **Verificar** TODOS los criterios de aceptacion cumplidos
2. **Editar YAML front-matter**:
   ```yaml
   status: "Done"
   completed_date: "YYYY-MM-DD"
   actual_hours: X
   ```
3. **Agregar seccion** "## Notas de Implementacion" con detalles
4. **Mover tarea** a columna "Hecho" en Board.md
5. **Commit**: `git commit -m "Fixes TASK-XXX: [descripcion breve]"`

### Reportar Bloqueo

1. Cambiar `status: "Blocked"`
2. Agregar seccion "## Bloqueo" con:
   - Descripcion del bloqueo
   - Dependencias faltantes
   - Accion requerida
3. Notificar en Board.md

---

## 4. Como Trabajar con Bugs

### Reportar un Bug

1. **Crear archivo** `/docs/planning/bugs/BUG-XXX-descripcion.md`
2. **Usar plantilla YAML**:
   ```yaml
   ---
   id: "BUG-XXX"
   title: "Descripcion del bug"
   type: "Bug"
   status: "Open"
   severity: "P0|P1|P2|P3"
   priority: "Critica|Alta|Media|Baja"
   assignee: ""
   affected_module: "Backend|Frontend|Database"
   steps_to_reproduce:
     - "Paso 1"
     - "Paso 2"
   expected_behavior: "Lo que deberia pasar"
   actual_behavior: "Lo que pasa realmente"
   created_date: "YYYY-MM-DD"
   ---
   ```
3. **Incluir secciones**: Descripcion, Contexto, Impacto
4. **Commit**: `git commit -m "Report BUG-XXX: [descripcion]"`

### Resolver un Bug

1. Editar YAML: `status: "Done"`, agregar `resolved_date`
2. Documentar solucion en seccion "## Solucion Implementada"
3. Agregar referencia al commit: `fix_commit: "abc123"`
4. **Commit**: `git commit -m "Fix BUG-XXX: [descripcion]"`

---

## 5. Formato YAML Front-Matter

### Historia de Usuario (US)

```yaml
---
id: "US-AUTH-001"
title: "Registro con Email"
type: "User Story"
status: "Done"
priority: "Alta"
assignee: "@Backend-Agent"
epic: "OQI-001"
story_points: 5
created_date: "2025-12-05"
updated_date: "2026-01-04"
---
```

### Tarea (TASK)

```yaml
---
id: "TASK-001"
title: "Implementar endpoint POST /auth/register"
type: "Task"
status: "Done"
priority: "P1"
assignee: "@Backend-Agent"
parent_us: "US-AUTH-001"
epic: "OQI-001"
estimated_hours: 4
actual_hours: 4.5
created_date: "2025-12-05"
completed_date: "2025-12-05"
---
```

### Requerimiento Funcional (RF)

```yaml
---
id: "RF-AUTH-001"
title: "OAuth Multi-proveedor"
type: "Requirement"
status: "Done"
priority: "Alta"
module: "auth"
epic: "OQI-001"
version: "1.0"
created_date: "2025-12-05"
updated_date: "2026-01-04"
---
```

### Especificacion Tecnica (ET)

```yaml
---
id: "ET-AUTH-001"
title: "OAuth Providers Implementation"
type: "Specification"
status: "Done"
rf_parent: "RF-AUTH-001"
epic: "OQI-001"
version: "1.0"
created_date: "2025-12-05"
updated_date: "2026-01-04"
---
```

---

## 6. Convenciones de Commit

```
<tipo>(<scope>): <descripcion>

Tipos:
- feat: Nueva funcionalidad
- fix: Correccion de bug
- docs: Documentacion
- refactor: Refactoring
- test: Tests
- chore: Mantenimiento

Scopes comunes:
- auth, education, trading, investment, payments, ml, llm, portfolio
- database, backend, frontend (capas)
- US-XXX, TASK-XXX, BUG-XXX (referencias)

Ejemplos:
- feat(auth): Implement OAuth 2.0 with Google
- fix(BUG-001): Resolve login redirect issue
- docs(US-AUTH-001): Add acceptance criteria
- Start TASK-XXX: Begin implementation
- Fixes TASK-XXX: Complete implementation
```

---

## 7. Estados Validos

### Para Tareas y User Stories

| Estado | Descripcion |
|--------|-------------|
| Backlog | En cola, no planificado |
| To Do | Planificado para sprint actual |
| In Progress | En desarrollo activo |
| Blocked | Bloqueado por dependencia |
| In Review | En revision/testing |
| Done | Completado y validado |

### Para Bugs

| Estado | Descripcion |
|--------|-------------|
| Open | Reportado, pendiente |
| In Progress | En investigacion/correccion |
| Fixed | Corregido, pendiente validacion |
| Done | Corregido y validado |
| Won't Fix | No se corregira (documentar razon) |

---

## 8. Archivos Importantes

| Archivo | Proposito |
|---------|-----------|
| `/docs/planning/Board.md` | Tablero Kanban actual |
| `/docs/planning/config.yml` | Configuracion del proyecto |
| `/docs/04-fase-backlog/DEFINITION-OF-READY.md` | Criterios para Ready |
| `/docs/04-fase-backlog/DEFINITION-OF-DONE.md` | Criterios para Done |
| `/docs/_MAP.md` | Mapa de navegacion principal |
| `/docs/02-definicion-modulos/_MAP.md` | Indice de modulos |

---

## 9. Validaciones Antes de Commit

- [ ] YAML front-matter valido (sin errores de sintaxis)
- [ ] Campo `id` presente y unico
- [ ] Campo `status` actualizado correctamente
- [ ] Board.md actualizado si cambio estado
- [ ] Referencias cruzadas verificadas
- [ ] Criterios de aceptacion actualizados (si aplica)
- [ ] _MAP.md actualizado si se agrego/elimino archivo

---

## 10. Flujo de Trabajo Recomendado

```
1. Consultar Board.md para ver tareas disponibles
2. Seleccionar tarea de "Por Hacer"
3. Leer archivo TASK-XXX.md completo
4. Verificar dependencias resueltas
5. Cambiar status a "In Progress"
6. Ejecutar trabajo
7. Documentar notas de implementacion
8. Verificar criterios de aceptacion
9. Cambiar status a "Done"
10. Actualizar Board.md
11. Commit con mensaje apropiado
```

---

## 11. Modulos del Proyecto

| Epica | Nombre | Progreso | Estado |
|-------|--------|----------|--------|
| OQI-001 | Fundamentos Auth | 85% | Implementado (parcial) |
| OQI-002 | Education | 55% | En Desarrollo |
| OQI-003 | Trading Charts | 60% | En Desarrollo |
| OQI-004 | Investment Accounts | 55% | En Desarrollo |
| OQI-005 | Payments Stripe | 65% | En Desarrollo |
| OQI-006 | ML Signals | 75% | Implementado (parcial) |
| OQI-007 | LLM Agent | 45% | En Desarrollo |
| OQI-008 | Portfolio Manager | 45% | En Desarrollo |
| OQI-009 | Marketplace | Docs:100% Impl:0% | Solo Documentacion |
| OQI-010 | LLM Trading Integration | 0% | Planificacion |
| OQI-011 | MT4 Gateway | 15% | NO FUNCIONAL |

### Metricas del Proyecto (SSOT: orchestration/inventarios/)

| Capa | Metrica | Valor |
|------|---------|-------|
| Database | Schemas / Tablas | 11 / 101 |
| Backend | Modulos / Endpoints | 18 / 116 |
| Frontend | Componentes / Paginas | 225 / 58 |
| Documentacion | OQIs / US / RF / ET | 11 / 101 / 56 / 81 |

---

## 12. Contacto y Soporte

Para dudas sobre el proceso:
- Revisar `/docs/README.md` para vision general
- Consultar `/orchestration/directivas/` para directivas
- Ver ejemplos en modulos completados (OQI-001 a OQI-008)

---

**Creado:** 2026-01-04
**Actualizado:** 2026-02-06
**Mantenido por:** Architecture Team
**Version:** 2.0.0