# Guia para Agentes de IA - Platform Marketing Content

**Version:** 1.0
**Ultima actualizacion:** 2026-01-04
**Basado en:** Estandar-SCRUM.md (Principio SIMCO)

---

## 1. Estructura del Proyecto

### Ubicaciones Clave

| Tipo | Ubicacion |
|------|-----------|
| Documentacion general | `/docs/` |
| Planificacion | `/docs/planning/` |
| Vision general | `/docs/00-vision-general/` |
| Analisis referencias | `/docs/01-analisis-referencias/` |
| Definicion modulos | `/docs/02-definicion-modulos/` |
| Requerimientos | `/docs/03-requerimientos/` |
| Modelado | `/docs/04-modelado/` |
| User Stories/EPICs | `/docs/05-user-stories/` |
| Transversal | `/docs/90-transversal/` |
| Guias desarrollo | `/docs/95-guias-desarrollo/` |
| Quick Reference | `/docs/96-quick-reference/` |
| ADRs | `/docs/97-adr/` |
| Backlog | `/docs/04-fase-backlog/` |
| Tablero Kanban | `/docs/planning/Board.md` |
| Orquestacion | `/orchestration/` |
| Trazas | `/orchestration/trazas/` |

### Estructura de una EPIC

```
docs/05-user-stories/EPIC-XXX-nombre.md
```

Cada EPIC contiene:
- Descripcion de la epica
- User Stories con formato "Como... Quiero... Para..."
- Criterios de aceptacion
- Notas tecnicas
- Dependencias

---

## 2. Prefijos de Nomenclatura

| Prefijo | Tipo | Ejemplo | Descripcion |
|---------|------|---------|-------------|
| EPIC- | Epica | EPIC-001-SETUP | Epicas del proyecto |
| US- | Historia de Usuario | US-001-001 | User Stories |
| TASK- | Tarea | TASK-001 | Tareas ejecutables |
| BUG- | Bug | BUG-001 | Defectos/errores |
| RF-PMC- | Requerimiento Funcional | RF-PMC-001-TENANTS | Requerimientos |
| PMC- | Modulo | PMC-001-TENANTS | Definicion de modulos |
| ADR- | Decision Record | ADR-001 | Decisiones arquitectonicas |

---

## 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

### EPIC

```yaml
---
id: "EPIC-001"
title: "Setup y Autenticacion"
type: "Epic"
status: "Done"
priority: "Alta"
project: "platform_marketing_content"
phase: 1
story_points: 40
created_date: "2025-12-08"
updated_date: "2026-01-04"
---
```

### Historia de Usuario (US)

```yaml
---
id: "US-001-001"
title: "Crear Tenant Inicial"
type: "User Story"
status: "Done"
priority: "Alta"
assignee: "@Backend-Agent"
epic: "EPIC-001"
story_points: 5
created_date: "2025-12-08"
updated_date: "2026-01-04"
---
```

### Requerimiento Funcional (RF)

```yaml
---
id: "RF-PMC-001"
title: "Tenants Module"
type: "Requirement"
status: "Done"
priority: "Alta"
module: "tenants"
project: "platform_marketing_content"
version: "1.0"
created_date: "2025-12-08"
updated_date: "2026-01-04"
---
```

### ADR (Architecture Decision Record)

```yaml
---
id: "ADR-001"
title: "Seleccion de Stack Tecnologico"
type: "ADR"
status: "Accepted"
date: "2025-12-08"
deciders: ["Architecture Team"]
tags: ["backend", "frontend", "database"]
created_date: "2025-12-08"
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-001-001"
epic: "EPIC-001"
estimated_hours: 4
actual_hours: 4.5
created_date: "2025-12-08"
completed_date: "2025-12-08"
---
```

---

## 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, tenants, crm, generation (modulos)
- database, backend, frontend (capas)
- US-XXX, TASK-XXX, BUG-XXX (referencias)

Ejemplos:
- feat(auth): Implement JWT authentication
- fix(BUG-001): Resolve login redirect issue
- docs(EPIC-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) |

### Para ADRs

| Estado | Descripcion |
|--------|-------------|
| Proposed | Propuesto, en discusion |
| Accepted | Aceptado |
| Deprecated | Obsoleto |
| Superseded | Reemplazado por otro ADR |

---

## 8. Archivos Importantes

| Archivo | Proposito |
|---------|-----------|
| `/docs/planning/Board.md` | Tablero Kanban actual |
| `/docs/planning/config.yml` | Configuracion del proyecto |
| `/docs/04-fase-backlog/README.md` | Backlog priorizado |
| `/docs/04-fase-backlog/DEFINITION-OF-READY.md` | Criterios DoR |
| `/docs/04-fase-backlog/DEFINITION-OF-DONE.md` | Criterios DoD |
| `/orchestration/trazas/TRAZA-TAREAS-*.md` | Trazas de tareas por area |
| `/docs/90-transversal/roadmap/ROADMAP-PMC.md` | Roadmap del proyecto |

---

## 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 Sistema

| Modulo | Descripcion | EPIC |
|--------|-------------|------|
| PMC-001-TENANTS | Multi-tenancy y planes | EPIC-001 |
| PMC-002-CRM | Clientes, marcas, productos | EPIC-002 |
| PMC-003-PROJECTS | Proyectos y campanas | EPIC-003 |
| PMC-004-GENERATION | Motor IA de generacion | EPIC-004 |
| PMC-005-AUTOMATION | Flujos n8n | EPIC-006 |
| PMC-006-ASSETS | Biblioteca DAM | EPIC-005 |
| PMC-007-ADMIN | Administracion | EPIC-008 |
| PMC-008-ANALYTICS | Dashboards y reportes | EPIC-007 |

---

## 12. Contacto y Soporte

Para dudas sobre el proceso:
- Revisar `/orchestration/00-guidelines/`
- Consultar `/orchestration/directivas/`
- Ver ejemplos en EPICs completadas

---

**Creado:** 2026-01-04
**Mantenido por:** Architecture Team
**Version:** 1.0