# ASDD Agents — Registro Central

Índice de todos los agentes especializados disponibles en este proyecto.

## Agentes Disponibles

### Orchestración & Planning
- **[orchestrator](./agents/orchestrator.md)** — Orquestador ASDD principal. Coordina flujo paralelo: Spec → Backend ∥ Frontend → Tests ∥ → QA
- **[spec-generator](./agents/spec-generator.md)** — Genera especificaciones técnicas integrales considerando TODO el ciclo de vida

### Implementación
- **[backend-developer](./agents/backend-developer.md)** — Implementa backend Spring Boot con arquitectura hexagonal. Ejecutar post-spec aprobada
- **[frontend-developer](./agents/frontend-developer.md)** — Implementa frontend Next.js + React con diseño Tailwind CSS v4. Ejecutar post-spec aprobada
- **[database-agent](./agents/database-agent.md)** — Diseña esquemas, modelos, migrations y seeders. Ejecutar si spec incluye cambios de datos

### Testing & Quality
- **[test-engineer-backend](./agents/test-engineer-backend.md)** — Genera tests unitarios + integración para Spring Boot. Post-backend completado
- **[test-engineer-frontend](./agents/test-engineer-frontend.md)** — Genera tests unitarios para Next.js. Post-frontend completado
- **[qa-agent](./agents/qa-agent.md)** — Estrategia QA completa: Gherkin, casos de prueba, E2E. Posterior a implementación + tests

### DevOps & Infraestructura
- **[devops-infrastructure-expert](./agents/devops-infrastructure-expert.md)** ⭐ **NEW** — SR expert. Diseña, despliega y escala sistemas con Kubernetes, Docker, AWS, CI/CD, IaC

### Documentación
- **[documentation-agent](./agents/documentation-agent.md)** — Genera documentación técnica: README, API docs, ADRs, guías onboarding

---

## Cómo Invocar Agentes

### En Claude Code CLI
```bash
claude ask <agent-name> "<descripción-tarea>"

# Ejemplos:
claude ask orchestrator "Orquesta el nuevo feature de validación cruzada"
claude ask backend-developer "Implementa UseCase de validación"
claude ask devops-infrastructure-expert "Diseña arquitectura Kubernetes escalable"
```

### En GitHub Copilot (Chat)
```
@agent-name <task>

# Ejemplos:
@orchestrator Orquesta el flujo completo del feature HU-3.2
@backend-developer Implementa el repositorio de validación
@devops-infrastructure-expert Crea pipeline CI/CD con GitHub Actions
```

---

## Matriz de Responsabilidades

| Fase | Agente Recomendado | Entrada | Salida |
|------|-------------------|---------|--------|
| **1. Spec** | `spec-generator` | Requerimiento | `.github/specs/*.spec.md` (APPROVED) |
| **2a. Backend** | `backend-developer` | Spec APPROVED | Spring Boot + tests unitarios |
| **2b. Frontend** | `frontend-developer` | Spec APPROVED | Next.js + tests unitarios |
| **2c. Database** | `database-agent` | Spec APPROVED | Models + migrations + seeders |
| **3a. Test BE** | `test-engineer-backend` | Backend completado | JUnit + Mockito tests (80%+ coverage) |
| **3b. Test FE** | `test-engineer-frontend` | Frontend completado | Vitest tests (80%+ coverage) |
| **4. QA** | `qa-agent` | Impl + tests completos | Gherkin scenarios + test cases |
| **5. DevOps** | `devops-infrastructure-expert` | Aplicación listâ para prod | Terraform + K8s + CI/CD + Observability |
| **6. Docs** | `documentation-agent` | Feature implementado | README + API docs + ADRs |

---

## Flujo ASDD Completo

```
┌─────────────────────────────────────────────────────────────┐
│ 1. SPEC-GENERATOR: Crea especificación técnica aprobada     │
│    Input: Requerimiento                                      │
│    Output: .github/specs/feature.spec.md (status: APPROVED)  │
└─────────────────────────────────────────────────────────────┘
                            ↓
        ┌───────────────────┼───────────────────┐
        ↓                   ↓                   ↓
    ┌────────┐        ┌──────────┐      ┌─────────────┐
    │BACKEND │        │FRONTEND  │      │DATABASE     │
    │develop │        │developer │      │agent        │
    │(parallel)       │(parallel)│      │(if needed)  │
    └────────┘        └──────────┘      └─────────────┘
        ↓                   ↓                   ↓
     Backend             Frontend          Models +
     complete            complete          Migrations
        ↓                   ↓                   ↓
    ┌────────┐        ┌──────────┐
    │TEST    │        │TEST      │          (integrated ↓)
    │ENGINEER│        │ENGINEER  │
    │Backend │        │Frontend  │
    └────────┘        └──────────┘
        ↓                   ↓
    Unit tests          Unit tests
    (80%+)              (80%+)
        ↓                   ↓
        └───────────────────┤
                            ↓
          ┌─────────────────────────────┐
          │ QA-AGENT: Test cases + E2E  │
          │ Gherkin scenarios            │
          └─────────────────────────────┘
                            ↓
          ┌─────────────────────────────┐
          │ DEVOPS-EXPERT: CI/CD ready  │
          │ K8s, Terraform, Observability│
          └─────────────────────────────┘
                            ↓
          ┌─────────────────────────────┐
          │ DOCUMENTATION-AGENT: Docs   │
          │ README, API, ADRs           │
          └─────────────────────────────┘
                            ↓
                    ✅ FEATURE READY
```

---

## Configuración de Agentes

Cada agente está configurado con:
- **Nome & Descripción**: en YAML frontmatter
- **Permiso**: `acceptEdits` (puede editar código automáticamente)
- **Memoria**: `project` (context del proyecto)
- **Modelo**: `sonnet` (velocidad + calidad balanceado)
- **Herramientas**: read, write, edit, bash, terminal

Ver cada archivo `.claude/agents/*.md` para detalles específicos.

---

## Tips para Mejor Productividad

### ✅ DO
- Invocar **spec-generator primero** — siempre genera spec antes de código
- Usar **orchestrator** para features complejos (coordina múltiples agentes)
- Ejecutar agentes **en orden** del flujo ASDD
- Dejar que agentes **modifiquen código automáticamente** (acceptEdits)
- **Revisar outputs** antes de next step (no skip)

### ❌ DON'T
- Saltarse la spec
- Invocar múltiples backend-developers en paralelo (conflictos)
- Modificar files que agentes están editando en el mismo instant
- Ejecutar tests sin implementación completada
- Desactivar aceptEdits

---

## Troubleshooting

### Agente no encuentra spec
→ Verificar `.github/specs/feature.spec.md` existe y status es `APPROVED`

### Conflictos de edición
→ Esperar a que agente anterior complete (check `.claude/agent-memory/`)

### Tests fallando
→ Pedir a test-engineer que revise cobertura y refactor código

### Deployment fallando
→ Invocar `devops-infrastructure-expert` con erro logs

---

## Referencias

- **SKILL.md files**: Responsabilidades detalladas de cada skill
- **.claude/rules/**: Convenciones y stack (backend.md, frontend.md, database.md)
- **.github/workflows/**: Pipelines CI/CD actuales
- **README.md (raíz)**: Stack general, setup, comandos

---

**Last Update**: March 30, 2026  
**Framework Version**: ASDD 3.0