bug_bunny 4.8.0 → 4.9.0

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

@@ -0,0 +1,225 @@
+---
+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.
+
+mcps:
+  - github
+  - clickup
+
+# --- Gemas ---
+# Array de nombres. El sync busca skill/ en cada gema instalada.
+
+gems:
+  - mi_gema
+  - otra_gema
+
+# --- Servicios ---
+# Hash { nombre => config }. Descarga skill/ del repo remoto.
+
+services:
+  mi_servicio:
+    repo: wispro/mi_servicio
+
+# --- Skills ---
+# Hash { nombre => config }. Formato estilo docker-compose.
+# Cada skill es una clave con su configuración.
+#
+# Claves disponibles:
+# - repo (requerido): org/repo de GitHub
+# - scope (opcional): global | local (default: local)
+# - path (opcional): path custom en el repo (default: skills/[nombre])
+# - environment (opcional): configuración específica de la skill
+
+skills:
+  skill-manager:
+    repo: sequre/ai_knowledge
+    scope: global
+  quality-code:
+    repo: sequre/ai_knowledge
+    scope: global
+  gem-release:
+    repo: sequre/ai_knowledge
+  service-release:
+    repo: sequre/ai_knowledge
+  skill-builder:
+    repo: sequre/ai_knowledge
+  yard:
+    repo: sequre/ai_knowledge
+  sentry:
+    repo: sequre/ai_knowledge
+    environment:
+      url: "https://sentry.cloud.wispro.co"
+      org: "wispro"
+      projects:
+        - billing-api
+        - billing-workers
+  agent-review:
+    repo: sequre/ai_knowledge
+    environment:
+      space_id: "90144913465"
+      list_id: "901415149921"
+  ai-reports:
+    repo: sequre/ai_knowledge
+    environment:
+      space_id: "90144913465"
+      bug_reports_list_id: "901415148810"
+      improvements_list_id: "901415148812"
+  # Skills externas con path custom
+  documentation-writer:
+    repo: github/awesome-copilot
+    path: skills/documentation-writer
+  rabbitmq-expert:
+    repo: martinholovsky/claude-skills-generator
+    path: skills/rabbitmq-expert
+```
+
+### Variables de entorno en skills.yml
+El parser expande `${VAR}` con el valor de la variable de entorno. Útil para tokens o IDs sensibles:
+
+```yaml
+skills:
+  ai-reports:
+    repo: sequre/ai_knowledge
+    environment:
+      space_id: "${CLICKUP_SPACE_ID}"
+      bug_reports_list_id: "${CLICKUP_BUG_REPORTS_LIST}"
+```
+
+*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á `.agents/skills/` completo al `.gitignore`:
+  ```gitignore
+  # Skills locales (descargadas por sync + propias del dev)
+  .agents/skills/
+  ```
+- `.agents/skills/` es siempre local y no se commitea. Contiene skills descargadas por el sync y opcionalmente skills privadas del dev.
+- Si una skill debe ser compartida, se declara en `skills.yml` y se distribuye via sync.
+
+### 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: `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.

data/.agents/skills/skill-manager/scripts/sync.rb

@@ -0,0 +1,356 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+require 'json'
+require 'net/http'
+require 'uri'
+
+module SkillsSync
+  SKILLS_YML = 'skills.yml'
+  SKILLS_LOCK = 'skills.lock'
+  SKILLS_DIR = File.join('.agents', 'skills')
+
+  GLOBAL_SKILL_PATHS = [
+    File.join(Dir.home, '.agents', 'skills'),
+    File.join(Dir.home, '.claude', '.agents', 'skills'),
+    File.join(Dir.home, '.claude', 'skills')
+  ].freeze
+
+  class << self
+    def run
+      config_path = File.join(Dir.pwd, SKILLS_YML)
+
+      unless File.exist?(config_path)
+        puts "skill-manager sync — ERROR: #{SKILLS_YML} no encontrado en #{Dir.pwd}"
+        exit 1
+      end
+
+      config = load_config(config_path)
+      @local_skills_path = File.join(Dir.pwd, SKILLS_DIR)
+      FileUtils.mkdir_p(@local_skills_path)
+
+      @use_gh = !gh_available?.nil?
+      @token = ENV['GITHUB_TOKEN']
+
+      unless @use_gh || @token
+        puts "skill-manager sync — WARNING: ni 'gh' CLI ni GITHUB_TOKEN disponibles. Solo se sincronizarán gemas locales."
+      end
+
+      @previous_lock = load_lock
+      @current_lock = []
+
+      sync_gems(config['gems'] || [])
+      sync_services(config['services'] || [])
+      sync_skills(config['skills'] || [])
+
+      cleanup_removed_skills
+      save_lock
+
+      puts 'skill-manager sync — OK.'
+    end
+
+    private
+
+    # --- Config parsing ---
+
+    # Lee skills.yml y expande variables de entorno ${VAR}
+    def load_config(path)
+      content = File.read(path)
+      content = content.gsub(/\$\{(\w+)\}/) { ENV[Regexp.last_match(1)].to_s }
+      YAML.safe_load(content)
+    end
+
+    # --- Lock file ---
+
+    def load_lock
+      lock_path = File.join(Dir.pwd, SKILLS_LOCK)
+      return [] unless File.exist?(lock_path)
+
+      data = YAML.safe_load_file(lock_path)
+      data['skills'] || []
+    rescue StandardError
+      []
+    end
+
+    def save_lock
+      lock_path = File.join(Dir.pwd, SKILLS_LOCK)
+      data = {
+        'synced_at' => Time.now.strftime('%Y-%m-%d %H:%M:%S'),
+        'skills' => @current_lock.sort_by { |s| s['name'] }
+      }
+      File.write(lock_path, YAML.dump(data))
+    end
+
+    def record_lock(name, scope, path)
+      @current_lock << { 'name' => name, 'scope' => scope || 'local', 'path' => path }
+    end
+
+    def cleanup_removed_skills
+      previous_names = @previous_lock.map { |s| s['name'] }
+      current_names = @current_lock.map { |s| s['name'] }
+      removed = previous_names - current_names
+
+      removed.each do |name|
+        entry = @previous_lock.find { |s| s['name'] == name }
+        path = entry['path']
+
+        if File.exist?(path)
+          puts "  #{name} — eliminado (ya no está en #{SKILLS_YML})"
+          FileUtils.rm_rf(path)
+        end
+      end
+    end
+
+    # --- Scope resolution ---
+
+    # Retorna un hash { dest:, install: } donde install indica si hay que descargar.
+    # Si install es false (porque ya existe globalmente), dest contiene el path global
+    # para que igualmente se registre en el lock y no se borre en cleanup.
+    def resolve_dest(name, scope)
+      case scope
+      when 'global'
+        global_path = find_global_path(name) || default_global_path
+        dest = File.join(global_path, name)
+        local_path = File.join(@local_skills_path, name)
+
+        # Si existe local, borrarla
+        if File.exist?(local_path)
+          puts "  #{name} — eliminando copia local (scope: global)"
+          FileUtils.rm_rf(local_path)
+        end
+
+        { dest: dest, install: true }
+      else # local o sin especificar
+        # Si existe global, saltear la instalación pero registrar en el lock
+        existing_global = find_global_path(name)
+        if existing_global
+          global_dest = File.join(existing_global, name)
+          puts "  #{name} — disponible globalmente en #{global_dest}. Saltando."
+          return { dest: global_dest, install: false }
+        end
+
+        { dest: File.join(@local_skills_path, name), install: true }
+      end
+    end
+
+    def find_global_path(name)
+      GLOBAL_SKILL_PATHS.find do |path|
+        File.exist?(File.join(path, name, 'SKILL.md'))
+      end
+    end
+
+    def default_global_path
+      existing = GLOBAL_SKILL_PATHS.find { |p| File.directory?(p) }
+      return existing if existing
+
+      path = GLOBAL_SKILL_PATHS.first
+      FileUtils.mkdir_p(path)
+      path
+    end
+
+    # --- Sync methods ---
+
+    # Nuevo formato: gems es un array de strings (nombres de gemas)
+    def sync_gems(gems)
+      return unless gems.is_a?(Array)
+
+      gems.each do |name|
+        resolution = resolve_dest(name, 'local')
+        next unless resolution
+
+        unless resolution[:install]
+          record_lock(name, 'local', resolution[:dest])
+          next
+        end
+
+        begin
+          spec = Gem::Specification.find_by_name(name)
+        rescue Gem::MissingSpecError
+          puts "  WARNING: gema '#{name}' no instalada. Saltando."
+          next
+        end
+
+        skill_dir = File.join(spec.gem_dir, 'skill')
+        skill_file = File.join(skill_dir, 'SKILL.md')
+
+        unless File.exist?(skill_file)
+          puts "  WARNING: #{name} v#{spec.version} no incluye skill en skill/. Saltando."
+          next
+        end
+
+        puts "  #{name} v#{spec.version} (local)"
+        replace_dir(resolution[:dest])
+        FileUtils.cp_r(Dir[File.join(skill_dir, '*')], resolution[:dest])
+        record_lock(name, 'local', resolution[:dest])
+      end
+    end
+
+    # Nuevo formato: services es un Hash { nombre => config }
+    # Cada servicio tiene: repo (requerido), scope (opcional)
+    def sync_services(services)
+      return unless services.is_a?(Hash)
+
+      services.each do |name, service_config|
+        service_config ||= {}
+        scope = service_config['scope']
+        resolution = resolve_dest(name, scope)
+        next unless resolution
+
+        unless resolution[:install]
+          record_lock(name, scope, resolution[:dest])
+          next
+        end
+
+        repo = service_config['repo']
+        unless repo
+          puts "  WARNING: service '#{name}' no tiene 'repo' definido. Saltando."
+          next
+        end
+
+        scope_label = scope == 'global' ? 'global' : 'local'
+        puts "  #{name} (GitHub: #{repo}, skill/) [#{scope_label}]"
+        replace_dir(resolution[:dest])
+        download_github_dir(repo, 'main', 'skill', resolution[:dest])
+        record_lock(name, scope, resolution[:dest])
+      end
+    end
+
+    # Nuevo formato: skills es un Hash { nombre => config }
+    # Cada skill tiene: repo (requerido), scope (opcional), path (opcional), environment (opcional)
+    def sync_skills(skills)
+      return unless skills.is_a?(Hash)
+
+      skills.each do |name, skill_config|
+        skill_config ||= {}
+        scope = skill_config['scope']
+        resolution = resolve_dest(name, scope)
+        next unless resolution
+
+        unless resolution[:install]
+          record_lock(name, scope, resolution[:dest])
+          next
+        end
+
+        repo = skill_config['repo']
+        unless repo
+          puts "  WARNING: skill '#{name}' no tiene 'repo' definido. Saltando."
+          next
+        end
+
+        remote_path = skill_config['path'] || "skills/#{name}"
+        scope_label = scope == 'global' ? 'global' : 'local'
+        puts "  #{name} (GitHub: #{repo}, #{remote_path}/) [#{scope_label}]"
+        replace_dir(resolution[:dest])
+        download_github_dir(repo, 'main', remote_path, resolution[:dest])
+        record_lock(name, scope, resolution[:dest])
+      end
+    end
+
+    # --- Helpers ---
+
+    def replace_dir(dest)
+      FileUtils.rm_rf(dest)
+      FileUtils.mkdir_p(dest)
+    end
+
+    def download_github_dir(repo, ref, remote_path, dest)
+      entries = list_github_dir(repo, ref, remote_path)
+
+      if entries.empty?
+        puts "  WARNING: #{remote_path}/ no encontrado en #{repo}@#{ref}. Saltando."
+        return
+      end
+
+      entries.each do |entry|
+        next unless entry['type'] == 'file'
+
+        relative_path = entry['path'].sub(%r{^#{Regexp.escape(remote_path)}/}, '')
+        file_dest = File.join(dest, relative_path)
+        FileUtils.mkdir_p(File.dirname(file_dest))
+
+        content = if @use_gh
+                    gh_fetch_file(repo, ref, entry['path'])
+                  else
+                    fetch_url(entry['download_url'])
+                  end
+
+        if content
+          File.write(file_dest, content)
+        else
+          puts "  WARNING: no se pudo descargar #{entry['path']} de #{repo}."
+        end
+      end
+    end
+
+    def list_github_dir(repo, ref, path)
+      response = if @use_gh
+                   gh_api("repos/#{repo}/contents/#{path}?ref=#{ref}")
+                 else
+                   fetch_url("https://api.github.com/repos/#{repo}/contents/#{path}?ref=#{ref}")
+                 end
+      return [] unless response
+
+      items = JSON.parse(response)
+      return [] unless items.is_a?(Array)
+
+      all_entries = []
+      items.each do |item|
+        if item['type'] == 'dir'
+          all_entries.concat(list_github_dir(repo, ref, item['path']))
+        else
+          all_entries << item
+        end
+      end
+      all_entries
+    end
+
+    # --- GitHub CLI ---
+
+    def gh_available?
+      `which gh 2>/dev/null`.strip
+      $?.success? ? true : nil
+    rescue StandardError
+      nil
+    end
+
+    def gh_api(endpoint)
+      output = `gh api "#{endpoint}" 2>/dev/null`
+      $?.success? ? output.force_encoding('UTF-8') : nil
+    rescue StandardError
+      nil
+    end
+
+    def gh_fetch_file(repo, ref, path)
+      output = `gh api "repos/#{repo}/contents/#{path}?ref=#{ref}" --jq '.content' 2>/dev/null`
+      return nil unless $?.success?
+
+      require 'base64'
+      Base64.decode64(output).force_encoding('UTF-8')
+    rescue StandardError
+      nil
+    end
+
+    # --- HTTP directo ---
+
+    def fetch_url(url)
+      uri = URI.parse(url)
+      request = Net::HTTP::Get.new(uri)
+      request['Authorization'] = "Bearer #{@token}" if @token
+      request['User-Agent'] = 'skill-manager/1.0'
+      request['Accept'] = 'application/vnd.github.v3+json' if url.include?('api.github.com')
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+        http.request(request)
+      end
+
+      response.code == '200' ? response.body.force_encoding('UTF-8') : nil
+    rescue StandardError => e
+      puts "  ERROR fetching #{url}: #{e.message}"
+      nil
+    end
+  end
+end
+
+SkillsSync.run if __FILE__ == $PROGRAM_NAME