---
type: SPEC
asset_id: SPEC-EL-WORX-GitMarketplace-AutoUpdate-v01
version: v01
status: Listo para ejecución (infra · Alex)
owner: Victor Heredia
sherpa_owner: Jay
ratificador: Victor Heredia (L3+)
fecha_creacion: 2026-07-07
intellbank: IB-EL-EmpowerLabs
subbank: PB-EL-Project-Bank / PB-WORX-Worx
proposito: Specs técnicos para que Alex configure el repo git privado del marketplace con AUTO-UPDATE de skills y plugins para todo el equipo.
relacionados:
  - empowerlabs-plugins.zip (contenido semilla del repo · ya corregido y con /wx-)
  - SOP-EL-SkillsAlta-v02 (ciclo de vida de skills)
  - TP-EL-PluginMarketplace-Handoff-v01 (qué sigue · equipo)
tags: [SPEC, infra, git, marketplace, auto-update, plugins, skills, alex, github]
---

# SPEC · Git Marketplace con Auto-Update
## Para Alex (infra) — configurar la distribución automática de skills y plugins

> **Objetivo:** que el equipo reciba las skills/plugins nuevos y sus actualizaciones **solos**,
> sin instalar a mano, desde un repo git privado de EmpowerLabs.
>
> **Resultado esperado:** un colaborador clona el repo de trabajo (o abre Cowork con el settings
> correcto) → los 4 plugins WORX se instalan y se auto-actualizan al arrancar.

**Fuentes oficiales (confirmar contra la doc vigente):**
`code.claude.com/docs/en/plugin-marketplaces` · `.../settings` · `.../github-actions`

---

## 1. Arquitectura

```
Repo git privado (GitHub)  ──►  Marketplace "empowerlabs"  ──►  Máquinas del equipo
  empowerlabs-plugins/            (.claude-plugin/marketplace.json)     (.claude/settings.json
  (FUERA del vault Intellibanks)   lista los 4 plugins                    con autoUpdate: true)
```
- **Regla dura:** el repo vive FUERA del vault Intellibanks. La sync del vault corrompe los dotfolders (`.claude-plugin`→`archivo.claude-plugin`, `plugin.json`→`plugin_json.md`). El repo git es la fuente única.

---

## 2. Prerrequisitos
- Cuenta/organización de GitHub de EmpowerLabs con permiso para crear **repos privados**.
- Cada máquina del equipo con Claude Code / Cowork y acceso al repo (ver §5, auth).
- El contenido semilla: **`empowerlabs-plugins.zip`** (ya corregido, con los comandos `/wx-` y `wx-buzon`).

---

## 3. Paso 1 — Crear y sembrar el repo
1. Crea el repo **privado vacío** `empowerlabs/empowerlabs-plugins` (sin README).
2. Extrae `empowerlabs-plugins.zip` en una carpeta local **fuera del vault** (ej. `~/dev/empowerlabs-plugins/`).
3. Sube:
   ```bash
   cd ~/dev/empowerlabs-plugins
   bash init-repo.sh empowerlabs/empowerlabs-plugins    # incluido en el zip
   # o manual: git init && git add . && git commit -m "seed" && git branch -M main
   #           git remote add origin git@github.com:empowerlabs/empowerlabs-plugins.git && git push -u origin main
   ```

**Estructura del repo (así debe quedar):**
```
empowerlabs-plugins/
├── .claude-plugin/marketplace.json      ← lista los 4 plugins. SIN campo "version" (no se usa).
├── worx-core/.claude-plugin/plugin.json
├── worx-empowerlabs/.claude-plugin/plugin.json
├── worx-wikix/.claude-plugin/plugin.json
├── worx-ultrasherpas/.claude-plugin/plugin.json
└── .gitignore                            ← bloquea *_json.md, archivo.*, .DS_Store
```

---

## 4. Paso 2 — Cómo funciona el AUTO-UPDATE (el corazón)
La detección de actualización se basa en **el campo `version` de cada `plugin.json`** (SemVer):
- Subes `version` (`0.4.1` → `0.4.2`) → `git push` → las máquinas con `autoUpdate: true` jalan la nueva versión al arrancar.
- **Si NO subes `version`, no pasa nada** aunque hagas push. El bump es obligatorio.
- El `marketplace.json` **NO** lleva `version` (ese campo es ignorado; omítelo).

---

## 5. Paso 3 — Config del equipo (`.claude/settings.json`)
Pega este bloque en el `.claude/settings.json` del **repo de trabajo compartido** (o en `~/.claude/settings.json` de cada máquina). `autoUpdate` es **hermano** de `source`, no va anidado:

```json
{
  "extraKnownMarketplaces": {
    "empowerlabs": {
      "source": { "source": "github", "repo": "empowerlabs/empowerlabs-plugins" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "worx-core@empowerlabs": true,
    "worx-empowerlabs@empowerlabs": true,
    "worx-wikix@empowerlabs": true,
    "worx-ultrasherpas@empowerlabs": true
  }
}
```
- `autoUpdate: true` → Claude refresca el marketplace y actualiza los plugins **al arrancar**.
- Los del repo de proyecto ganan sobre los de `~/.claude/settings.json`.
- Para fijar a una rama/tag: `"repo": "empowerlabs/empowerlabs-plugins@v1.0.0"`.

---

## 6. Paso 4 — Autenticación del repo PRIVADO (el punto delicado)
| Método | Instalación manual | Auto-update en background |
|---|---|---|
| **`GITHUB_TOKEN` (env var)** | ⚠️ limitado | ✅ **Es el que funciona** para el sync automático |
| SSH key (ssh-agent) | ✅ | ❌ (prompts interactivos suprimidos) |
| `gh auth login` (HTTPS) | ✅ | ❌ (helper solo para ops manuales) |

**Para que el auto-update funcione en un repo privado, cada máquina necesita:**
```bash
export GITHUB_TOKEN="ghp_..."   # PAT con acceso de lectura al repo privado
```
> El subproceso git de Claude **no hereda** `GIT_ASKPASS` ni `GH_TOKEN` — **solo** `GITHUB_TOKEN`. Pruébalo temprano. (Alternativa: repo público de solo-lectura para plugins no sensibles, y evitas el token.)

---

## 7. Paso 5 — CI de validación (GitHub Action · antes de publicar)
Evita que un plugin roto (como el "Found 4 plugin.json" o los `archivo.*`) llegue al equipo. `.github/workflows/validate.yml`:
```yaml
name: Validate Plugins
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Estructura (defensa contra corrupción de sync)
        run: |
          set -e
          # marketplace.json válido
          python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))"
          # cada plugin: EXACTAMENTE 1 plugin.json válido, y sin artefactos de mutilación
          for d in worx-core worx-empowerlabs worx-wikix worx-ultrasherpas; do
            n=$(find "$d" -name plugin.json | wc -l)
            [ "$n" -eq 1 ] || { echo "❌ $d tiene $n plugin.json (debe ser 1)"; exit 1; }
            python3 -c "import json; json.load(open('$d/.claude-plugin/plugin.json'))"
          done
          # nada corrupto por sync
          ! find . -name "archivo.*" -o -name "*_json.md" | grep . || { echo "❌ artefactos de sync detectados"; exit 1; }
          echo "✅ validación OK"
```
> Opcional, si está disponible: `claude plugin validate .claude-plugin/marketplace.json` (valida schema, IDs duplicados, SemVer).

---

## 8. Paso 6 — Workflow de publicación (el día a día)
1. Editas la fuente **en el repo git** (nunca en el vault, nunca el caché `.remote-plugins/`).
2. Subes `version` en el `plugin.json` del plugin que cambió (SemVer).
3. `git commit && git push`. La Action valida.
4. El equipo recibe el update solo (autoUpdate) o con `/plugin marketplace update`.

**Comandos de referencia:**
`/plugin marketplace add empowerlabs/empowerlabs-plugins` · `/plugin marketplace update` · `/plugin install <plugin>@empowerlabs` · `/plugin update <plugin>@empowerlabs` · `/plugin marketplace list`

---

## 9. Guardrails (para que no se rompa)
- El repo del marketplace **NUNCA** dentro del vault Intellibanks.
- Nunca editar el caché `.remote-plugins/`.
- `.gitignore` bloquea `*_json.md`, `archivo.*`, `.DS_Store`.
- Cada plugin: exactamente 1 `plugin.json`. El zip del marketplace (varios) NO se sube por el botón de "un plugin".

---

## 10. Criterios de aceptación (verificación de Alex)
- [ ] Repo privado creado y sembrado; la Action de validación pasa en verde.
- [ ] En una máquina de prueba con el `settings.json` + `GITHUB_TOKEN`: los 4 plugins aparecen instalados al arrancar.
- [ ] Bump de prueba (`version` +1 en un plugin) + push → la máquina de prueba lo recibe **solo** al reiniciar (auto-update).
- [ ] `/wx-arrancaroom` y `wx-buzon` disparan; `/wx-wikixcreadocaprende` escribe a `IB-WikiX/` y no crea `LLM-Wiki/`.
- [ ] Documentado el token/onboarding para el resto del equipo.

## CHANGELOG
| Versión | Fecha | Cambio |
|---|---|---|
| v01 | 2026-07-07 | Creación. Spec de repo git + auto-update: arquitectura, settings.json exacto, GITHUB_TOKEN para background, CI de validación, workflow de publicación, criterios de aceptación. |