## https://sploitus.com/exploit?id=581A10FE-47F5-5557-B48C-9A9723CA1FD0
# opencode-dev-agents
**Agentes AI y comandos personalizados para OpenCode CLI que automatizan tareas diarias de desarrollo de software** β code reviews, reportes de sprint, migraciones, generacion de tests y auditorias de seguridad.
---
## Objetivo
Esta POC demuestra como un desarrollador puede usar **agentes de inteligencia artificial** desde su terminal para automatizar tareas repetitivas del dia a dia: revisar codigo, consultar el estado del sprint, generar tests, analizar seguridad o planificar migraciones β todo con un solo comando, sin salir del editor.
El foco no esta en reemplazar al desarrollador, sino en **eliminar el trabajo manual repetitivo** y dejar que el humano se enfoque en decisiones, diseΓ±o y problemas complejos.
---
## Conceptos Clave: LLM, MCP y Agentes
Si es la primera vez que escuchas estos terminos, aca va una explicacion simple:
### LLM (Large Language Model)
Un LLM es un modelo de inteligencia artificial entrenado con grandes cantidades de texto que puede entender y generar lenguaje natural y codigo. Ejemplos conocidos: **ChatGPT** (OpenAI), **Claude** (Anthropic), **Gemini** (Google).
**Que hace:** Entiende lo que le pedis en lenguaje natural y genera respuestas, codigo, analisis o resumenes.
**Limitacion:** Por si solo, un LLM solo puede "hablar". No puede entrar a tu Jira, leer tu GitLab ni consultar metricas de Grafana.
### MCP (Model Context Protocol)
MCP es un protocolo abierto que le da al LLM la capacidad de **conectarse con herramientas externas**. Funciona como un "puente" entre el modelo de IA y tus sistemas reales.
**Que hace:** Permite que el LLM lea merge requests de GitLab, consulte tickets de Jira, busque logs en Grafana, etc. Sin MCP, el LLM no puede acceder a nada fuera de la conversacion.
**Analogia:** Si el LLM es un cerebro, el MCP son las manos y los ojos que le permiten interactuar con el mundo real.
### Agente
Un agente es un **LLM con un rol especializado, instrucciones especificas y acceso a herramientas** (via MCP) que le permiten ejecutar tareas de forma autonoma.
**Que hace:** Recibe una tarea (ej: "revisa este merge request"), decide que herramientas usar, ejecuta multiples pasos y entrega un resultado completo.
**Ejemplo concreto:**
- Le decis al agente `dev-reviewer`: *"Revisa el MR !245 del proyecto api-valuation"*
- El agente usa el MCP de GitLab para leer el diff
- Analiza el codigo buscando problemas de seguridad, performance y mejores practicas
- Te entrega un reporte con hallazgos clasificados por severidad
### Como se relacionan
```
Tu (terminal) β Agente (rol + instrucciones) β LLM (cerebro) β MCP (puente) β GitLab / Jira / Grafana
```
1. Vos ejecutas un comando: `/review MR_ID=245 PROJECT=api-valuation`
2. El **agente** `dev-reviewer` recibe la tarea y sabe que tiene que hacer un code review
3. El **LLM** (Claude) procesa la solicitud y decide que necesita leer el diff del MR
4. El **MCP** de GitLab se conecta a tu instancia y trae el codigo
5. El LLM analiza el codigo y el agente te entrega el reporte
---
## Por que usar agentes y no un pipeline de CI/CD?
Es una pregunta valida. Si ya tenemos pipelines en GitLab/GitHub que ejecutan linters, tests y scans automaticamente, para que necesitamos agentes?
La respuesta corta: **son complementarios, no competidores**. Resuelven problemas diferentes.
### Pipeline de CI/CD
| Caracteristica | Pipeline |
|----------------|----------|
| **Cuando se ejecuta** | Automaticamente al hacer push/MR |
| **Que hace** | Reglas predefinidas y rigidas (lint, test, build, deploy) |
| **Flexibilidad** | Baja: solo hace lo que esta configurado |
| **Interaccion** | Ninguna: es un proceso batch |
| **Resultado** | Pass/fail con logs |
### Agente AI
| Caracteristica | Agente |
|----------------|--------|
| **Cuando se ejecuta** | Cuando vos lo necesitas (on-demand) |
| **Que hace** | Tareas que requieren razonamiento y contexto |
| **Flexibilidad** | Alta: entiende lenguaje natural y se adapta |
| **Interaccion** | Conversacional: podes pedir aclaraciones o ajustes |
| **Resultado** | Reportes con explicaciones, sugerencias concretas y codigo |
### Que puede hacer un agente que un pipeline NO puede
| Tarea | Pipeline | Agente |
|-------|----------|--------|
| Revisar un MR y explicar *por que* algo es un problema | β Solo marca errores de lint | β Explica el impacto, sugiere como corregirlo |
| Generar un reporte de sprint cruzando datos de Jira | β No tiene acceso a Jira | β Ejecuta 7 queries JQL y arma un reporte consolidado |
| Planificar una migracion de Java 8 a 17 | β No razona sobre dependencias | β Analiza pom.xml, identifica breaking changes, genera un plan por fases |
| Generar tests unitarios para un service sin cobertura | β Solo mide cobertura, no genera codigo | β Lee el service, entiende la logica y genera tests con mocks |
| Detectar un password hardcodeado y explicar el riesgo | β Un regex puede encontrarlo, pero no explica el impacto | β Identifica el secreto, explica el riesgo y sugiere como usar un vault |
| Responder "que hicimos esta semana?" | β Imposible | β Cruza GitLab + Jira + Grafana y genera un resumen |
### En resumen
> **Pipeline** = automatizacion rigida que valida reglas en cada push.
> **Agente** = asistente inteligente que razona, cruza datos de multiples fuentes y se adapta a lo que le pedis.
Lo ideal es usar **ambos**: el pipeline para las validaciones automaticas obligatorias, y los agentes para las tareas que requieren criterio, contexto y flexibilidad.
---
## Quick Start
```bash
# 1. Instalar OpenCode
curl -fsSL https://opencode.ai/install | bash # Linux/macOS
irm https://opencode.ai/install.ps1 | iex # Windows
# 2. Configurar Anthropic
opencode auth login
# 3. Configurar variables de entorno
cp .env.example .env
# Editar .env con tus tokens reales (GitLab, Jira, Grafana)
# 4. Verificar MCPs
opencode mcp list
# 5. Iniciar
opencode
```
## Estructura
```
poc-opencode-agent-mcp/
opencode.json # Config: provider, MCPs, commands
.env.example # Variables de entorno (plantilla)
.opencode/agents/
dev-reviewer.md # Code review (GitLab)
ops-monitor.md # Observabilidad (Grafana)
pm-assistant.md # Gestion de proyecto (Jira)
daily-standup.md # Orquestador diario (todos)
migration-advisor.md # Migraciones Java/Angular
test-generator.md # Generacion de tests
security-auditor.md # Auditoria de seguridad
teams-notifier.md # Notificaciones Teams
docs/
confluence-poc-opencode.md # Documentacion completa
```
## MCPs Integrados
| MCP | Paquete | Conecta a | Tipo |
|-----|---------|-----------|------|
| **GitLab** | `gitlab-mcp` (npx) | `gitlab.acme-seguros.com` | Self-hosted |
| **Jira** | `@aashari/mcp-server-atlassian-jira` (npx) | `acme-seguros.atlassian.net` | Cloud (API Token) |
| **Grafana** | `mcp-grafana` (uvx) | `grafana.acme-seguros.com` | Self-hosted |
## Agentes
| Agente | Rol | Modelo | Invocar |
|--------|-----|--------|---------|
| `dev-reviewer` | Code review de MRs | Sonnet | `@dev-reviewer` |
| `ops-monitor` | Dashboards, metricas, logs, alertas | Haiku | `@ops-monitor` |
| `pm-assistant` | Gestion Jira, sprints, reportes | Sonnet | `@pm-assistant` |
| `daily-standup` | Resumen diario (orquestador) | Sonnet | Tab o `opencode --agent daily-standup` |
| `migration-advisor` | Migraciones Java/Angular/Spring Boot | Sonnet | `@migration-advisor` |
| `test-generator` | Generar tests, escanear cobertura | Sonnet | `@test-generator` |
| `security-auditor` | Auditoria de seguridad, CVEs, secretos | Sonnet | `@security-auditor` |
| `teams-notifier` | Notificaciones a Microsoft Teams | Sonnet | `@teams-notifier` |
## Commands
### Desarrollo y Operaciones
| Command | Que hace | Ejemplo |
|---------|----------|---------|
| `/review` | Code review de un MR | `/review MR_ID=245 PROJECT=api-valuation` |
| `/review-jira` | Code review + crear Deuda Tecnica en Jira | `/review-jira MR_ID=38 PROJECT=auto-claims LABEL=BE` |
| `/standup` | Resumen daily standup | `/standup` |
| `/alerts` | Alertas activas en Grafana | `/alerts` |
| `/dashboard` | Consultar dashboard Grafana | `/dashboard NOMBRE=Claims Platform APIs` |
| `/logs` | Buscar logs en Loki | `/logs SERVICE=api-valuation HOURS=2` |
### Sprint Report (Reportes de Gestion TL)
| Command | Que hace | Ejemplo |
|---------|----------|---------|
| `/sprint-report` | Reporte completo de gestion (7 queries) | `/sprint-report` |
| `/avances` | Avances de producto (iniciativas de negocio) | `/avances` |
| `/sprint-status` | Estado del sprint con distribucion por area | `/sprint-status` |
| `/bugs-prod` | Bugs productivos del sprint activo | `/bugs-prod` |
| `/bugs-semana` | Bugs PROD y NO PROD de la semana anterior | `/bugs-semana` |
| `/dt-balance` | Balance DT vs Iniciativas vs Bugs PROD | `/dt-balance` |
### Migration Advisor (Migraciones)
| Command | Que hace | Ejemplo |
|---------|----------|---------|
| `/migrate-analyze` | Analizar proyecto y generar plan de migracion | `/migrate-analyze PROJECT_PATH=../api-claims` |
| `/migrate-java` | Migrar version de Java | `/migrate-java PROJECT_PATH=../api-claims FROM=8 TO=11` |
| `/migrate-angular` | Migrar version de Angular | `/migrate-angular PROJECT_PATH=../web-portal FROM=15 TO=17` |
| `/migrate-springboot` | Plan de migracion de Spring Boot | `/migrate-springboot PROJECT_PATH=../api-claims FROM=2.3 TO=2.7` |
#### Ejemplos de uso en la CLI
```bash
# Analizar que necesita un proyecto legacy para migrar
opencode -p "/migrate-analyze PROJECT_PATH=../api-claims"
# Migrar un proyecto de Java 8 a Java 11
opencode -p "/migrate-java PROJECT_PATH=../api-claims FROM=8 TO=11"
# Plan de migracion de Spring Boot 2.3 a 2.7
opencode -p "/migrate-springboot PROJECT_PATH=../be-claims-escalation FROM=2.3 TO=2.7"
# Migrar Angular 10 a Angular 17
opencode -p "/migrate-angular PROJECT_PATH=../web-inspectors FROM=10 TO=17"
# Analizar migracion de un frontend moderno
opencode -p "/migrate-analyze PROJECT_PATH=../web-providers"
```
### Test Generator (Generacion de Tests)
| Command | Que hace | Ejemplo |
|---------|----------|---------|
| `/test-scan` | Escanear proyecto y detectar archivos sin tests | `/test-scan PROJECT_PATH=../api-claims` |
| `/test-generate` | Generar tests para un archivo especifico | `/test-generate FILE_PATH=../api-claims/core/src/main/.../ClaimService.java` |
| `/test-run` | Ejecutar tests y reportar resultados | `/test-run PROJECT_PATH=../api-claims` |
| `/test-coverage` | Workflow completo: detectar + generar + ejecutar | `/test-coverage PROJECT_PATH=../api-claims` |
#### Ejemplos de uso en la CLI
```bash
# Escanear un proyecto backend para ver que archivos no tienen tests
opencode -p "/test-scan PROJECT_PATH=../api-valuation"
# Generar tests para un Service critico
opencode -p "/test-generate FILE_PATH=../api-valuation/core/src/main/java/com/acme/valuacion/service/ValuacionService.java"
# Generar tests para un componente Angular
opencode -p "/test-generate FILE_PATH=../web-portal/src/app/components/dashboard/dashboard.component.ts"
# Workflow completo: detectar archivos sin test, generar los 5 mas criticos, ejecutar
opencode -p "/test-coverage PROJECT_PATH=../be-claims-escalation"
# Ejecutar tests de un proyecto y ver resultados
opencode -p "/test-run PROJECT_PATH=../api-claims"
```
### Security Auditor (Seguridad)
| Command | Que hace | Ejemplo |
|---------|----------|---------|
| `/security-scan` | Auditoria completa de seguridad | `/security-scan PROJECT_PATH=../api-claims` |
| `/security-secrets` | Buscar secretos expuestos en codigo | `/security-secrets PROJECT_PATH=../api-billing` |
| `/security-deps` | Analizar dependencias vulnerables (CVEs) | `/security-deps PROJECT_PATH=../api-valuation` |
| `/security-docker` | Auditar Dockerfiles | `/security-docker PROJECT_PATH=../be-notifications` |
#### Ejemplos de uso en la CLI
```bash
# Auditoria de seguridad completa de un proyecto
opencode -p "/security-scan PROJECT_PATH=../api-billing"
# Buscar secretos en todos los archivos de configuracion
opencode -p "/security-secrets PROJECT_PATH=../api-claims"
# Verificar si hay dependencias con CVEs conocidos
opencode -p "/security-deps PROJECT_PATH=../api-valuation"
# Auditar la seguridad del Dockerfile
opencode -p "/security-docker PROJECT_PATH=../be-claims-escalation"
# Escanear un proyecto Angular por dependencias vulnerables
opencode -p "/security-deps PROJECT_PATH=../web-portal"
```
### Teams Notifier (Notificaciones)
| Command | Que hace | Ejemplo |
|---------|----------|---------|
| `/review-teams` | Code review de MR + notificar en Teams | `/review-teams MR_ID=245 PROJECT=api-valuation` |
| `/sprint-teams` | Reporte de sprint + enviar a Teams | `/sprint-teams` |
| `/alerta-teams` | Alertas criticas de Grafana + notificar en Teams | `/alerta-teams` |
| `/notify-teams` | Mensaje personalizado a Teams | `/notify-teams TITULO="Deploy OK" MENSAJE="Se desplegΓ³ v2.1.0"` |
#### Ejemplos de uso en la CLI
```bash
# Code review de un MR y notificar al equipo en Teams
opencode -p "/review-teams MR_ID=245 PROJECT=api-valuation"
# Enviar reporte de sprint al canal del equipo
opencode -p "/sprint-teams"
# Chequear alertas criticas y notificar si hay
opencode -p "/alerta-teams"
# Enviar mensaje personalizado al canal
opencode -p "/notify-teams TITULO=\"Deploy exitoso\" MENSAJE=\"api-claims v2.1.0 desplegado en produccion\""
```
## Prerequisitos
- **Node.js 18+** (para gitlab-mcp y jira-mcp via npx)
- **Python 3.10+** con `uv`/`uvx` (para mcp-grafana)
- **OpenCode** (ultima version)
## Tokens Necesarios
| Token | Donde obtenerlo |
|-------|-----------------|
| `GITLAB_TOKEN` | GitLab > Settings > Access Tokens (scopes: `api`, `read_repository`) |
| `JIRA_TOKEN` / `JIRA_API_TOKEN` | Atlassian > Account Settings > Security > API Tokens |
| `GRAFANA_SERVICE_ACCOUNT_TOKEN` | Grafana > Administration > Service Accounts > Add token |
| `TEAMS_WEBHOOK_URL` | Teams > Canal > Workflows > "Post to a channel when a webhook request is received" |
## Documentacion Completa
Ver [`docs/confluence-poc-opencode.md`](docs/confluence-poc-opencode.md) para:
- Arquitectura y decisiones tecnicas
- Guia detallada de setup
- Guia de uso con ejemplos
- Troubleshooting