Merge branch 'docs/plugins-y-subagentes-2026-09-20'

workloads/docs-portal/docs/arquitectura/plugins-y-subagentes.md

@@ -0,0 +1,111 @@
+# Plugins y subagentes de Claude Code (sesión "lab")
+
+Inventario de qué plugins/skills se instalaron en la sesión principal
+`lab` (no `cloud-practice`, que sigue su propia línea de práctica
+multi-cloud — ver [ADR 0012](../decisiones/0012-practica-multicloud-gcp-azure.md))
+y qué subagentes propios se configuraron, con la fuente real de cada
+uno y por qué se aceptó o se descartó.
+
+## Por qué esto queda documentado como el resto del lab
+
+Dos frentes reales motivaron esto: (a) trabajo visual del storefront
+ARI Shopping — ADR 0008 ya costó tres ciclos completos de
+implementar-y-descartar una identidad en producción por no verla
+renderizada antes de aprobarla; (b) crecimiento de habilidades de
+Platform Engineering/DevOps. Un plugin instala instrucciones que
+Claude sigue automáticamente, algunos con hooks que se ejecutan sin
+pedir confirmación en cada uso — se aplicó la misma disciplina de
+verificación que el resto del lab: quién publica (Anthropic vs
+comunitario), qué permisos/hooks declara, y popularidad como señal de
+confianza, antes de instalar cualquiera que no fuera 100% de Anthropic.
+
+## Plugins instalados
+
+| Plugin | Marketplace | Publica de verdad | Hooks | Notas |
+|---|---|---|---|---|
+| `frontend-design` | `claude-plugins-official` | **Anthropic** (verificado en `plugin.json`) | Ninguno | Solo skills, sin red externa |
+| `context7` | `claude-plugins-official` | **Upstash** (tag `community-managed` — está *hospedado* en el catálogo oficial, no *publicado* por Anthropic) | Sin hooks, pero es un MCP que manda cada consulta al servidor remoto de Upstash (`mcp.context7.com`) | Aceptado con esa salvedad explícita de datos saliendo a un tercero |
+| `superpowers` | `claude-plugins-official` | **Jesse Vincent** (`obra/superpowers`, MIT, 288k+ ⭐ en GitHub) — **NO es de Anthropic** pese a estar listado en el catálogo oficial | Sí: `SessionStart` corre un script que inyecta contexto en cada sesión nueva (revisado: solo lee su propio skill local, sin red ni nada destructivo) | Aceptado con esa salvedad — cambia comportamiento de arranque sin pedir confirmación cada vez |
+| `gitops-workflows` | `devops-skills` (`ahmedasmar/devops-claude-skills`) | Ahmad Asmar (comunitario) | Ninguno (skill pura, sin ejecución automática) | |
+| `k8s-troubleshooter` | `devops-skills` | Ahmad Asmar | Ninguno | |
+| `ci-cd` | `devops-skills` | Ahmad Asmar | Ninguno | |
+| `monitoring-observability` | `devops-skills` | Ahmad Asmar | Ninguno | |
+
+**Descartados, no instalados:**
+
+- **`iac-terraform`** (del mismo marketplace `devops-skills`) — descartado a propósito, no por falta de calidad. Terraform ya se maneja aparte vía `hashicorp/agent-skills` en la sesión `cloud-practice` (ver ADR 0012 Fase 2); instalarlo acá también duplicaría/confundiría la fuente de verdad.
+- **`aws-cost-optimization`** (mismo marketplace) — no se pidió, se dejó afuera para no sumar alcance no solicitado.
+- **`theme-factory`** — investigado y descartado: el mismo nombre aparece en al menos 4 fuentes comunitarias distintas y no relacionadas entre sí (`kivilaid`, `shipshitdev`, `composiohq`, etc.), ninguna en el catálogo oficial de Anthropic. Sin una fuente única verificable, no se instaló nada con ese nombre.
+- **`ui-theme-designer`** (alternativa considerada del catálogo oficial) — es de **SAP SE**, específico para el SAP Fiori Design System / UI5 Web Components. No tiene nada que ver con el stack real de ARI Shopping (Next.js + Tailwind) — se descartó por no aplicar, no por falta de confianza.
+
+## Subagentes propios (`~/.claude/agents/`)
+
+Tres subagentes con propósito acotado y tools restringidas, definidos
+como archivos markdown con frontmatter YAML (formato estándar de
+Claude Code — ver [documentación oficial](https://code.claude.com/docs/en/sub-agents)).
+
+### `devsecops-auditor`
+
+Solo lectura y explicación del pipeline DevSecOps real (Gitleaks,
+Trivy, Semgrep, Syft, Cosign) en `apps-registry`/`platform-infra`/
+`scripts`. `tools: Read, Grep, Glob, Bash` + `disallowedTools: Write,
+Edit` — nunca modifica código de producción, su único output es
+diagnóstico contra el YAML/config real, citando archivo:línea, nunca
+teoría genérica de CI/CD.
+
+### `frontend-critic`
+
+Revisa visualmente un cambio del storefront **antes** de aprobarlo —
+formaliza la disciplina "simular antes de implementar" que costó tres
+ciclos de descarte en ADR 0008. Regla dura: si no puede ver el
+resultado renderizado en esa corrida puntual, el veredicto es "no
+puedo aprobar esto sin verlo", nunca un aprobado condicional.
+
+Vía de verificación, en orden de preferencia:
+1. Chrome DevTools / Claude in Chrome — **hoy no disponible en esta
+   sesión** (corre headless dentro de `tmux-host`, sin navegador real
+   conectado — mismo gotcha ya documentado para Claude in Chrome en
+   general).
+2. Playwright vía Docker en la NAS (el workaround ya validado este
+   mismo lab, ver `.browser-scratch/README.md`) contra
+   `shop.cruzcloud.net`/`staging.cruzcloud.net` reales.
+
+Usa la skill `frontend-design` (oficial, ver tabla de arriba) como
+marco de criterio de calidad visual.
+
+### `cloud-cost-auditor`
+
+Definido de antemano, a propósito, **sin nada que auditar todavía**.
+Necesita los MCP de GCP/Azure que se configuran en la sesión
+`cloud-practice` (ADR 0012) para funcionar — no va a tener recursos
+reales que revisar hasta que esa línea de trabajo pase de la Fase 1.
+Su propio system prompt tiene la regla dura de decir explícitamente
+"no tengo nada que auditar todavía" en vez de inventar un análisis si
+lo invocan antes de tiempo. No es un bloqueante para nada de lo demás,
+solo queda listo para cuando aplique.
+
+## Alcance y persistencia de la instalación
+
+Los 7 plugins quedaron en **`scope: user`** (confirmado con
+`claude plugin list`), no a nivel de proyecto de un repo específico.
+Los 3 subagentes viven en `~/.claude/agents/` (también scope de
+usuario, ubicación estándar según la doc oficial).
+
+**Verificado en vivo que sobrevive a un reinicio del contenedor**,
+mismo criterio que el resto de la configuración persistente de
+`tmux-host` (ver [Sesión tmux persistente](sesion-tmux-persistente.md)):
+`stat -c '%d' /root/.claude` y `stat -c '%d'
+/DATA/AppData/k3d-lab-v3/claude-code-home` devuelven el mismo device
+ID — es el mismo bind mount ya validado para login/confianza de
+carpeta, no un directorio efímero del contenedor.
+
+**Gotcha encontrado en vivo:** tanto los plugins como los subagentes
+nuevos **no quedaron activos en la misma sesión donde se instalaron/
+crearon** — la doc oficial de subagentes dice que se cargan sin
+reinicio, *excepto* la primera vez que se crea el directorio
+`~/.claude/agents/` (que no existía antes en este lab). Confirmado en
+vivo: invocar `devsecops-auditor` en la misma sesión dio
+`Agent type 'devsecops-auditor' not found`. Ambos (plugins y
+subagentes) quedan pendientes de confirmar activos recién en el
+próximo arranque real de la sesión — no es una falla de instalación,
+es el comportamiento documentado.

workloads/docs-portal/mkdocs.yml

@@ -86,6 +86,7 @@ nav:
       - Flujo GitOps: arquitectura/gitops-flujo.md
       - Agente de monitoreo: arquitectura/agente-monitoreo.md
       - Sesión tmux persistente: arquitectura/sesion-tmux-persistente.md
+      - Plugins y subagentes: arquitectura/plugins-y-subagentes.md
       - Glosario: arquitectura/glosario.md
   - Decisiones (ADRs):
       - "0001 · Por qué k3d": decisiones/0001-por-que-k3d.md