bug_bunny 4.7.0 → 4.8.1

data/.agents/skills/skill-builder/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: skill-builder
+description: Genera o actualiza la skill empaquetada (`skill/`) para cualquier proyecto Ruby (gema o servicio). Detecta automáticamente el tipo de proyecto y analiza el código correspondiente. Soporta desde un SKILL.md simple hasta skills con references y scripts. Es invocada por `skill-manager`, `gem-release` (regeneración completa) y `quality-code` (actualización incremental).
+---
+
+# Skill Builder
+
+Sos un experto en crear skills de conocimiento para proyectos Ruby. Tu objetivo es generar o actualizar `skill/SKILL.md` — un artefacto autocontenido que permite a cualquier agente de IA responder preguntas sobre integración, arquitectura, API, errores y antipatrones del proyecto.
+
+## Detección de tipo de proyecto
+
+- **Gema**: existe `.gemspec` en la raíz.
+- **Servicio**: existe `config/application.rb`.
+- Si ambos existen, priorizar gema.
+
+**Distribución en gemas:** La skill queda en `skill/` en la raíz del repositorio. Al publicar con `gem-release`, `skill/` se empaqueta en el `.gem`, de modo que los consumidores acceden a la skill directamente desde la gema instalada (`Gem.loaded_specs["[name]"].gem_dir + "/skill/"`) sin descargas adicionales.
+
+**Distribución en servicios:** La skill queda en `skill/` en la raíz del repositorio. Los consumidores la descargan vía `skill-manager sync` desde GitHub.
+
+## Escenarios de Complejidad
+
+La estructura de `skill/` depende de la complejidad del proyecto. `skill-manager` determina el escenario inicial, pero puede evolucionar con el tiempo:
+
+### Escenario 1 — Proyecto simple
+```
+skill/
+  SKILL.md
+```
+La skill entera cabe en un solo archivo. Secciones autocontenidas de ≤400 tokens.
+
+### Escenario 2 — Con referencias
+```
+skill/
+  SKILL.md
+  references/
+    api-detallada.md
+    errores.md
+```
+Cuando la API o contratos son extensos, o el catálogo de errores es grande.
+
+### Escenario 3 — Con scripts
+```
+skill/
+  SKILL.md
+  scripts/
+    diagnostico.rb
+```
+Cuando el proyecto necesita herramientas ejecutables (diagnóstico, migración, validación).
+
+### Escenario 4 — Completa
+```
+skill/
+  SKILL.md
+  references/
+    api-detallada.md
+    errores.md
+  scripts/
+    diagnostico.rb
+    migration_helper.rb
+```
+
+### Criterios para escalar
+
+- **→ references/** cuando una sección de `SKILL.md` supera los 400 tokens y es conocimiento de referencia (API, contratos, errores, catálogos).
+- **→ scripts/** cuando el proyecto necesita herramientas ejecutables para diagnóstico, migración o validación que complementen el conocimiento.
+
+## Modos de Ejecución
+
+- **Completo** (invocado por `gem-release` o manualmente): Regenera la skill desde cero analizando todo el código.
+- **Incremental** (invocado por `quality-code`): Actualiza solo las secciones afectadas por el diff del PR.
+
+---
+
+## Paso 1 — Descubrir el estado actual
+
+Leer en orden:
+1. `skill/SKILL.md` — si existe, es la skill actual.
+2. `skill/references/` — referencias existentes.
+3. `skill/scripts/` — scripts existentes.
+4. `CLAUDE.md` — propósito del artefacto, arquitectura, decisiones clave.
+
+Según el tipo de proyecto:
+
+**Si es gema:**
+5. `.gemspec` — nombre, descripción, dependencias.
+6. `lib/` — API pública, responsabilidades de clases, firmas de métodos.
+7. `spec/` o `test/` — patrones de uso, casos borde, errores esperados.
+
+**Si es servicio:**
+5. `config/application.rb` — nombre, configuración.
+6. `config/routes.rb` — endpoints HTTP expuestos.
+7. `app/` — controllers, models, services, jobs.
+8. Queues/mensajería — contratos de eventos (Sidekiq, ActiveJob, etc.).
+9. `db/migrate/` — esquema y evolución del modelo de datos.
+10. `spec/` o `test/` — patrones de uso, casos borde, errores esperados.
+
+En modo **incremental**, analizar también `git diff [PRIMARY_BRANCH]...HEAD` para identificar qué cambió.
+
+---
+
+## Paso 2 — Analizar el código y determinar escenario
+
+**Común a ambos tipos:**
+- **Arquitectura**: Flujo de datos, componentes core, thread safety, dependencias.
+- **Uso**: Ejemplos de integración, patrones comunes.
+- **Errores**: Excepciones personalizadas, causas, resoluciones.
+- **Antipatrones**: Usos incorrectos identificados en tests o código.
+- **Scripts necesarios**: ¿Hay flujos de diagnóstico, migración o validación que justifiquen un script?
+
+**Específico de gemas:**
+- **API Pública**: Bloque de configuración, clases principales, métodos públicos, parámetros.
+
+**Específico de servicios:**
+- **Contratos**: Endpoints HTTP, queues, eventos publicados/consumidos, webhooks.
+- **Infraestructura**: Variables de entorno, servicios externos, bases de datos.
+
+Con base en el análisis, determiná qué escenario de complejidad corresponde (1-4). Si la skill ya existe, evaluá si el escenario debe escalar.
+
+---
+
+## Paso 3 — Generar la Skill
+
+Generar `skill/SKILL.md` (y `references/` o `scripts/` si el escenario lo requiere).
+
+### Reglas de escritura (RAG-optimized)
+
+1. **Idioma: español** — Todo el contenido en español. Mantener términos técnicos estándar (ej: "middleware", "routing").
+2. **Cada sección <= 400 tokens** — Autocontenida, sin asumir contexto de otras secciones. Si una sección supera este límite, extraerla a `references/`.
+3. **Sin prosa introductoria** — Ir directo al contenido técnico.
+4. **Sin frontmatter complejo** — No incluir version, profile o audiences.
+5. **Sin duplicación** — Si un tema está en `references/`, la skill solo lo referencia.
+
+### Estructura de SKILL.md
+
+#### Titulo y Descripcion
+
+```markdown
+# [Nombre] Expert
+
+Skill de conocimiento completo sobre [Nombre]. Consultame para cualquier pregunta sobre integración, arquitectura, API, errores y antipatrones.
+```
+
+#### Glosario
+
+Términos del dominio. Formato: `**Término** — Definición concisa (1-3 líneas).`
+
+#### Arquitectura
+
+- Responsabilidad core.
+- Mapa de componentes (diagrama ASCII).
+- Flujo en runtime y decisiones de diseño.
+
+**Formato de diagramas ASCII:**
+- Cajas con `┌─┐└─┘`, flechas con `────>` (horizontal) y `│▼` (vertical).
+- Máximo 4-5 componentes por diagrama. Si hay más, dividir en sub-diagramas por capa.
+- Sin texto decorativo fuera de las cajas.
+
+Ejemplo:
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Request  │────>│ Middleware│────>│ Handler  │
+└──────────┘     └──────────┘     └──────────┘
+                       │
+                       ▼
+                 ┌──────────┐
+                 │  Cache   │
+                 └──────────┘
+```
+
+#### API Publica (gemas)
+
+- Bloque de configuración (tipos, defaults, restricciones).
+- Clases y métodos (firma, parámetros, retorno).
+- Ejemplos de código para operaciones principales.
+- Si la API es extensa, mantener un resumen acá y extraer el detalle a `references/api-detallada.md`.
+
+#### Contratos (servicios)
+
+- Endpoints HTTP (método, path, parámetros, respuesta).
+- Queues y eventos (nombre, payload, productor/consumidor).
+- Webhooks (si aplica).
+- Si los contratos son extensos, extraer a `references/contratos.md`.
+
+#### FAQ
+
+Formato Q&A estricto. H3 para la pregunta, respuesta <= 150 palabras. Sin preámbulo.
+
+#### Antipatrones
+
+Qué NO hacer. Por cada uno: nombre, código incorrecto, razón y alternativa.
+
+#### Errores
+
+Catálogo de excepciones. Por cada una: nombre, causa, reproducción y resolución.
+Si el catálogo es extenso, mantener los errores más comunes acá y extraer el catálogo completo a `references/errores.md`.
+
+#### Referencias (si existen)
+
+Índice de archivos en `references/` y `scripts/` con descripción de una línea.
+
+```markdown
+## Referencias
+
+- [API Detallada](references/api-detallada.md) — Documentación completa de clases y métodos
+- [Catálogo de Errores](references/errores.md) — Todas las excepciones con resolución
+- [Diagnóstico](scripts/diagnostico.rb) — Script para verificar configuración en runtime
+```
+
+---
+
+## Paso 4 — Actualizar README.md
+
+Actualizá `README.md` (máx 150 líneas) con:
+- Descripción en una línea.
+- Setup básico y Quick start.
+- Features principales.
+- Link a `skill/SKILL.md` para conocimiento profundo.
+
+---
+
+## Paso 5 — Mostrar resumen y esperar aprobación
+
+Mostrá un resumen de los cambios realizados:
+- Tipo de proyecto detectado (gema o servicio).
+- Escenario de complejidad determinado (y si escaló respecto al anterior).
+- Secciones nuevas, modificadas o eliminadas en `SKILL.md`.
+- Archivos nuevos o actualizados en `references/` o `scripts/`.
+- Cambios en README.md.
+
+Preguntá: "¿Querés ver el diff completo antes de escribir los archivos?"
+
+**Esperá la aprobación explícita del desarrollador** antes de persistir los cambios.

data/.agents/skills/skill-manager/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: skill-manager
+description: Configura, valida y sincroniza la infraestructura de skills en cualquier proyecto Ruby (gema o servicio). Úsala para inicializar `skills.yml`, verificar la skill del proyecto (`skill/`), sincronizar skills de dependencias a `.agents/skills/`, o validar que todo el estándar se cumpla. Requiere `skill-builder`.
+---
+
+# Skill Manager
+
+Skill unificada que gestiona toda la infraestructura de skills de un proyecto Ruby, sea gema o microservicio. Detecta automáticamente el tipo de proyecto y actúa en consecuencia.
+
+## Detección de tipo de proyecto
+
+- **Gema**: existe `.gemspec` en la raíz.
+- **Servicio**: existe `config/application.rb`.
+- Si ambos existen, priorizar gema.
+
+## Requisitos
+- La skill `skill-builder` debe estar disponible para generar `skill/SKILL.md`.
+
+---
+
+## Flujo de Trabajo (Modo Update)
+
+### Paso 1 — Determinar escenario de complejidad de la skill
+Analizá el proyecto para determinar qué estructura de `skill/` corresponde:
+
+- **Escenario 1 (simple):** Proyecto pequeño → solo `skill/SKILL.md`.
+- **Escenario 2 (con referencias):** API extensa o catálogo de errores grande → `SKILL.md` + `references/`.
+- **Escenario 3 (con scripts):** Necesita herramientas de diagnóstico, migración o validación → `SKILL.md` + `scripts/`.
+- **Escenario 4 (completa):** Combina referencias y scripts → `SKILL.md` + `references/` + `scripts/`.
+
+Si `skill/` ya existe, evaluá si el escenario debe escalar.
+
+### Paso 2 — Generar o actualizar la skill del proyecto
+Ejecutá `skill-builder` para generar o actualizar `skill/`. El skill-builder detecta automáticamente si es gema o servicio y analiza el código correspondiente.
+
+### Paso 3 — Gemspec (solo gemas)
+Si el proyecto es una gema, verificá que el `.gemspec` cumpla:
+
+1. **`metadata["documentation_uri"]`** apuntando a la carpeta de skill.
+   - Si falta, inferí la URL desde `homepage_uri` o `source_code_uri`:
+     `spec.metadata["documentation_uri"] = "https://github.com/[ORG]/[GEM_NAME]/blob/v#{spec.version}/skill"`
+
+2. **`spec.files` incluye `skill/`** para que la skill se empaquete dentro de la gema.
+   - Si usa `git ls-files`: verificá que `skill/` no esté en `.gitignore`.
+   - Si usa un glob explícito: asegurate de que incluya `skill/**/*`.
+
+- Mostrá el diff y pedí confirmación antes de escribir.
+
+### Paso 4 — Configurar skills.yml
+Si no existe `skills.yml` en la raíz, crealo detectando dependencias en el `Gemfile` y repos conocidos.
+
+```yaml
+# skills.yml — Manifiesto único de skills del proyecto
+
+# --- MCPs requeridos ---
+# Declara qué MCPs necesita el proyecto. Las skills verifican
+# disponibilidad antes de usarlos. Si falta alguno, avisan pero no se rompen.
+
+mcps:
+  - github
+  - clickup
+
+# --- Dependencias (sync) ---
+
+gems:              # Skills empaquetadas en gemas (copia local)
+  - name: mi_gema
+
+services:          # Skills de microservicios (GitHub → skill/)
+  - name: mi_servicio
+    repo: wispro/mi_servicio
+
+skills:            # Skills de repos GitHub (con path opcional)
+  # Sin path → usa convención .agents/skills/[name]/
+  - name: gem-release
+    repo: wispro/ai_knowledge
+  - name: skill-manager
+    repo: wispro/ai_knowledge
+  # Con path → para skills.sh u otros repos con estructura distinta
+  - name: rabbitmq-expert
+    repo: martinholovsky/claude-skills-generator
+    path: skills/rabbitmq-expert
+
+# --- Configuración de skills ---
+# Cada skill puede tener su sección de configuración específica.
+# Las skills leen su sección del skills.yml del proyecto.
+
+sentry:
+  projects:
+    - billing-api
+    - billing-workers
+```
+
+*Mostrá diff y pedí confirmación.*
+
+### Paso 5 — Configurar sincronización
+Asegurate de que el script de sync esté configurado para ejecutarse:
+- Agregá al final de `bin/setup`:
+  ```bash
+  ruby .agents/skills/skill-manager/scripts/sync.rb
+  ```
+
+### Paso 6 — Git
+- Agregá las skills de dependencias al `.gitignore` (cada entrada declarada en `skills.yml`):
+  ```gitignore
+  # Skills de dependencias (generadas por skill-manager sync)
+  .agents/skills/[dep-name]/
+  ```
+
+### Paso 7 — CLAUDE.md
+El bloque "Knowledge Base" debe estar al **tope absoluto** del archivo:
+```markdown
+## Knowledge Base
+- **Mandato Crítico:** Las skills en `.agents/skills/` incluyen conocimiento de dependencias.
+- **Protocolo de Consulta:** El agente DEBE leer la skill de una dependencia antes de responder sobre ella.
+- **Rebuild:** `ruby .agents/skills/skill-manager/scripts/sync.rb` actualiza las skills de dependencias.
+```
+
+---
+
+## Script de sincronización
+
+El script `scripts/sync.rb` lee `skills.yml` y sincroniza todas las skills de dependencias a `.agents/skills/`.
+
+| Sección | Fuente | Mecanismo |
+|---|---|---|
+| `gems` | Gema Ruby instalada | Copia local desde `gem_dir/skill/` |
+| `services` | Repo de microservicio | GitHub API → `skill/` del repo |
+| `skills` | Repo GitHub | GitHub API → path configurable (default: `.agents/skills/[name]/`) |
+
+### Ejecución directa
+```bash
+ruby .agents/skills/skill-manager/scripts/sync.rb
+```
+
+### Requisitos del script
+- Ruby (stdlib — sin dependencias externas)
+- `gh` CLI o `GITHUB_TOKEN` en el entorno (para repos privados)
+- `skills.yml` en la raíz del proyecto
+
+---
+
+## MCP de GitHub (opcional)
+
+Si tenés un MCP de GitHub disponible, el agente puede usarlo para:
+- **Inspeccionar repos** sin depender de `GITHUB_TOKEN` en el entorno.
+- **Detectar estructura de skills** en dependencias.
+- **Armar `skills.yml` inicial**: explorar repos del `Gemfile` y detectar cuáles tienen skill.
+- **Verificar cambios**: comparar la skill local con la remota antes de actualizar.
+
+Si el MCP no está disponible, se ejecuta el script de sync como fallback.
+
+---
+
+## Modos de Uso
+
+### /skill-manager check
+Valida el cumplimiento del estándar sin modificar archivos:
+1. Verificá que exista `skill/SKILL.md`.
+2. Verificá consistencia: todo archivo en `references/` y `scripts/` debe estar referenciado en `SKILL.md`, y viceversa.
+3. **(Solo gemas)** Verificá `documentation_uri` y que `spec.files` incluya `skill/`.
+4. Verificá existencia de `skills.yml`.
+5. Verificá `.gitignore` y `bin/setup`.
+6. Reportá: OK o lista de errores con pasos para resolverlos.
+
+### /skill-manager update
+Ejecuta el flujo de trabajo completo (Pasos 1-7). Configura toda la infraestructura sin tocar contenido existente de skills.
+
+### /skill-manager sync
+Actualiza las skills de dependencias en `.agents/skills/`:
+1. Si hay MCP de GitHub disponible, usalo para inspeccionar repos y descargar skills.
+2. Si no hay MCP, ejecutá el script `scripts/sync.rb`.
+3. Reportá qué skills se actualizaron, cuáles son nuevas y cuáles no tienen skill.