# Día 3 - Guía paso a paso

## Objetivo general

Construir una experiencia de Spec Driven Development y Agentic Engineering sobre ReqFlow manteniendo la estructura oficial del Día 3:

```text
S1 - OpenSpec / Spec Kit + Constitution
S2 - Specify -> Plan -> Tasks -> Validate
S3 - Fundamentos: model + tools + context + loop
S4 - Patrones básicos: routing, evaluator, HITL
```

## Entrada del día: handoff del Día 2

Desde la carpeta del laboratorio, verifica el handoff del Día 2 (al menos 1 repo en `[OK]`):

```powershell
python tools/check_handoff.py --day 2 ../reqflow-workspace
```

Si el chequeo falla, parte de la rama `checkpoint/day2` que entrega el instructor.

## 0. Leer el caso

Revisa [el contexto vigente del producto](s03-reqflow-setup/CASE.md) antes de configurar Agents o modificar código.

## Mapa agenda -> práctica

Los módulos del repositorio no sustituyen las sesiones oficiales; se reutilizan a lo largo de ellas:

| Agenda                                  | Práctica utilizada                                     |
|-----------------------------------------|--------------------------------------------------------|
| S1 OpenSpec / Spec Kit + Constitution   | teoría + `s04` Step 0 y primeros artefactos del cambio |
| S2 Specify -> Plan -> Tasks -> Validate | `s04` Steps 1-5                                        |
| S3 model + tools + context + loop       | `s01`, `s02`, `s03`                           |
| S4 routing + evaluator + HITL           | agentes de `s01` + Skills + gates de `s04`       |

## Módulo práctico 1 - Custom Agents

Ruta: [`s01-custom-agents/`](s01-custom-agents/)

```text
modo Agent genérico
-> rol persistente
-> límites
-> contexto/tools permitidos
```

Primero se entiende el agente individual; después los diferentes perfiles permiten mostrar routing.

## Módulo práctico 2 - Agent Skills

Ruta: [`s02-agent-skills/`](s02-agent-skills/)

```text
Agent = quién actúa
Skill = procedimiento reutilizable
```

Skills como `reqflow-definition-of-done` serán utilizados más adelante como parte de la evaluación.

## Módulo práctico 3 - Producto multi-repo + GitHub MCP

Ruta: [`s03-reqflow-setup/`](s03-reqflow-setup/)

```text
3 repositorios
 -> workspace de producto
 -> GitHub MCP oficial
 -> 1 GitHub Project
 -> backlog distribuido
```

Aquí el contexto multi-repo y las tools MCP hacen concreto el modelo `model + tools + context + loop`.

Los hallazgos revisados se convierten en GitHub Issues y uno de ellos se selecciona para el flujo SDD guiado.

## Módulo práctico 4 - SDD guiado con OpenSpec + GitHub

Ruta: [`s04-openspec-sdd/`](s04-openspec-sdd/)

Repositorio guiado:

```text
workshop-auth-backend
```

Patrón del temario:

```text
Specify -> Plan -> Tasks -> Validate
```

Materialización principal con OpenSpec:

```text
proposal + specs
 -> design
 -> tasks
 -> validate
 -> characterization
 -> apply
 -> tests
 -> PR + checks
```

Flujo:

```text
Issue confirmado y priorizado
 -> rama del Issue
 -> OpenSpec proposal + specs
 -> HITL
 -> OpenSpec design
 -> HITL
 -> OpenSpec tasks
 -> HITL
 -> pruebas de caracterización
 -> OpenSpec apply
 -> implementación incremental
 -> tests / evaluators
 -> PR final rama del Issue -> main
 -> checks automatizados
 -> Definition of Done
 -> HITL de cierre
 -> archive posterior del cambio OpenSpec cuando corresponda
```

No se prescribe de antemano cuál hallazgo debe corregirse. Debe surgir del análisis real de la línea base.

### Ejecución alternativa desde GitHub Copilot Agents

El recorrido principal se ejecuta desde VS Code sobre `reqflow-workspace`. Cuando los artefactos, instrucciones y contexto necesarios ya están versionados, determinadas tareas pueden delegarse alternativamente a GitHub Copilot Agents.

Esa ruta no reemplaza los pasos que dependen explícitamente de la CLI de OpenSpec y utiliza las ramas administradas por la sesión `copilot/*`.

Consulta [Ejecución alternativa desde GitHub Copilot Agents](s04-openspec-sdd/GITHUB_COPILOT_AGENTS.md).

## Cómo reconocer los patrones de S4

### Routing

```text
PM/PO -> Discovery -> Architect -> Developer
```

La selección puede hacerla explícitamente el participante.

### Evaluator

```text
OpenSpec validate
+ tests
+ Definition of Done
+ GitHub checks
```

### HITL

```text
evidencia
-> revisión humana
-> avanzar / corregir / detener
```

## Challenge

Ruta: [`challenge/README.md`](challenge/README.md)

Los participantes repiten el patrón sobre:

```text
workshop-auth-backend
workshop-login-frontend
```

## Qué NO haremos durante el Día 3

No intentaremos:

- ejecutar dos frameworks SDD completos en paralelo; Spec Kit se compara conceptualmente y OpenSpec se usa en el lab;
- resolver todos los hallazgos de los tres repositorios;
- eliminar GitHub Issues porque exista `tasks.md`;
- convertir `tasks.md` en un backlog de producto alternativo a GitHub Project;
- construir un orquestador autónomo multi-agent para demostrar routing;
- completar toda la matriz de seguridad del caso;
- construir o modificar los pipelines de CI existentes.

## Flujo final esperado

```text
ReqFlow
  -> especificación OpenSpec
  -> Agent especializado
  -> contexto + tools/MCP
  -> tareas implementadas
  -> evaluator
  -> HITL
  -> PR final con evidencia
```

## Regla de convivencia

```text
OpenSpec proposal/specs/design = definición del cambio
OpenSpec tasks.md = plan/checklist de implementación
GitHub Issue = trabajo comprometido y trazabilidad de producto
GitHub Project = prioridad y coordinación
GitHub PR = integración y evidencia
```