BIGboss248/nextjs-wordpress

Skill Universal de Configuración y Entorno de Repositorio (setup-repository)

Este skill establece, configura y valida el entorno de desarrollo estándar para cualquier repositorio de software. Maneja el descubrimiento de metadatos del proyecto, higiene de git, inteligencia de código con codebase-memory-mcp (configurado en el workspace y globalmente solo para Google Antigravity / AGY), estandarización de commits con Husky y Commitlint, contenedorización Docker de producción y despliegue CI/CD automatizado con Release Please y GHCR multi-arquitectura.

---

Resumen del Flujo de Trabajo

flowchart TD
    A["1. Descubrimiento Automatizado y Escaneo sin Interrupción"] --> B["2. Verdad Fundamental de Metadatos del Proyecto (docs/project.json)"]
    B --> C["3. Configuración del MCP de Memoria del Código (Workspace y AGY Global)"]
    C --> D["4. Configuración de Hooks de Git y Commitlint"]
    D --> E["5. Pilas Docker y Compose de Producción"]
    E --> F["6. Release Please y CI/CD GHCR Multi-Arquitectura"]
    F --> G["7. Verificación de Sanidad del Entorno"]
    G --> H["8. Informe de Ejecución Estandarizado y Guía de Git"]

---

Paso 1: Descubrimiento Automatizado y Escaneo del Repositorio (Regla de Cero Interrupciones)

[!IMPORTANT] NO PREGUNTES AL USUARIO SI LA INFORMACIÓN ESTÁ DISPONIBLE EN LOS ARCHIVOS DEL REPOSITORIO. Escanea primero los archivos del repositorio, configuraciones y documentación en docs/. Deduce automáticamente el runtime, las herramientas y las convenciones. Solo pregunta al humano por configuración faltante o ambigua.

1.1. Inspección Automatizada (Regla de Cero Interrupciones)

1. Detectar Framework y Runtime:
   • Inspeccionar manifiestos de paquetes: package.json (Node/Bun), pyproject.toml / requirements.txt (Python), Cargo.toml (Rust), go.mod (Go), etc.
   • Detectar gestor de paquetes a partir de lockfiles:
     • pnpm-lock.yaml → pnpm
     • bun.lockb / bun.lock → bun
     • yarn.lock → yarn
     • package-lock.json → npm
2. Escaneo de Documentación Existente:
   • Leer CONTEXT.md, docs/plan.md, docs/adr/*.md y README.md para extraer estándares arquitectónicos, suites de prueba y convenciones de lenguaje.
3. Verificar el Árbol de Trabajo de Git:
   • Comprobar el estado de git y la rama. Todos los pasos de inspección y comando deben ejecutarse como operaciones individuales discretas sin encadenar.

1.2. Aclaración Interactiva (Andamiaje Asistido por IA)

Si faltan parámetros críticos, son ambiguos o no se pueden determinar a partir de los archivos existentes, haz al usuario preguntas enfocadas utilizando opciones claras:

### 📋 Configuración del Repositorio y CI/CD

Para configurar el flujo de trabajo CI/CD estándar para este repositorio, por favor confirma o especifica:

1. **Lenguaje y Runtime Principal**: (ej. Node.js / TypeScript, Python, Go, Rust, Java, C++)
2. **Comando de Prueba**: (ej. `pnpm test`, `pytest`, `cargo test`, `go test ./...`)
3. **Comando de Compilación**: (ej. `pnpm run build`, `cargo build --release`, `go build`, `ninguno`)
4. **Destino de Publicación / Lanzamiento**:
   - [ ] Imagen de Contenedor Docker (GHCR / Docker Hub)
   - [ ] Registro de Paquetes (npm, PyPI, Crates.io, Maven)
   - [ ] Archivos de Versión Binaria (GitHub Releases)
   - [ ] Sitio Estático / Documentación (GitHub Pages)
   - [ ] Ninguno (Solo CI Testing y Git Tags SemVer)

---

Paso 2: Verdad Fundamental de Metadatos del Proyecto (docs/project.json)

Mantén un archivo de configuración central legible por máquina en docs/project.json para que todos los agentes de IA y skills especializados compartan un contexto idéntico.

Plantilla Estándar de docs/project.json:

{
  "project_context_and_metadata": {
    "project_name": "my-project",
    "runtime": "node",
    "package_manager": "pnpm",
    "source_dir": "src",
    "test_command": "pnpm test",
    "build_command": "pnpm run build",
    "testing_library": ["jest", "playwright"],
    "containerization": "docker-standalone",
    "ci_cd_provider": "github-actions",
    "release_automation": "release-please",
    "publish_target": "container"
  }
}

1. Asegurarse de que exista el directorio docs/.
2. Escribir o actualizar docs/project.json con los valores de configuración descubiertos o confirmados.

---

Paso 3: Configurar el Servidor de Inteligencia de Código codebase-memory-mcp

Equipa el repositorio con el servidor de grafo de conocimiento persistente codebase-memory-mcp (162 lenguajes, AST Tree-sitter, resolución de tipos semántica híbrida LSP y búsqueda vectorial 100% local).

3.1. Instalar el Binario

Elige el método de la plataforma:

• Windows (PowerShell):

  Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
  Unblock-File .\install.ps1
  .\install.ps1
  Remove-Item .\install.ps1
  

• macOS / Linux (Bash):

  curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
  

• Alternativa Global de Paquete npm:

  npm install -g codebase-memory-mcp@latest
  

3.2. Registrar el Servidor MCP (Workspace y AGY Global Solamente)

[!IMPORTANT] El Registro Global de MCP es SOLO para Antigravity (AGY). Antigravity descubre y carga servidores MCP que están configurados globalmente en el sistema anfitrión. Nunca configures ni registres servidores MCP globalmente para otros agentes de codificación (ej. Claude Desktop, Cursor, VS Code, Cline). Registra el servidor MCP en las siguientes ubicaciones:

1. mcp.json Raíz del Workspace:

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

2. Configuración del Agente del Workspace (.agents/mcp_config.json) (si el repo usa .agents/):

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3. Configuración Global del Host (Google Antigravity / AGY Solamente): Añadir codebase-memory estrictamente a las configuraciones del host AGY:
   • ~/.gemini/antigravity/mcp_config.json
   • ~/.gemini/config/mcp_config.json (NO registrar en Claude Desktop, Cursor u otros agentes de codificación):

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3.3. Configurar Exclusiones .cbmignore (Prevenir Parpadeo del Editor y Cambios Continuos)

• Solo Local (Por Defecto): Añadir .codebase-memory/ a .gitignore.

[!IMPORTANT] Prevención de Parpadeo y Exclusiones de Alto Cambio (.cbmignore): codebase-memory-mcp lee un archivo .cbmignore ubicado estrictamente en la raíz del repositorio (<repo>/.cbmignore) usando la sintaxis de .gitignore. Sin .cbmignore, los archivos que no son de código (como documentos de planificación, memoria del agente, artefactos de prueba y cachés de compilación) desencadenan descubrimiento continuo de AST, resolución de tipos y escrituras en disco cada vez que se editan. Generar siempre <repo>/.cbmignore en la raíz del repositorio:

# Reglas de ignorado de codebase-memory-mcp (.cbmignore)
# Previene que archivos no-código y de alto cambio activen la indexación del grafo o inflen el grafo AST.

# Registros del agente, metadatos y documentos de planificación (alto cambio durante sesiones activas)
.agents/
docs/
*.md

# Artefactos de compilación y cachés
build/
test-results/
.test-results/
.coverage/
.playwright/
storybook-static/
*storybook.log

# Artefactos locales de Codebase Memory (prevenir bucles de autoactivación)
.codebase-memory/

# Archivos del sistema y registros
*.log
*.tsbuildinfo
.DS_Store

# Activos estáticos y multimedia (símbolos de código cero)
public/
assets/
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.ico
*.webp
*.mp4
*.mp3
*.pdf

# Entorno y lockfiles
.env*
*.pem
*.lock
pnpm-lock.yaml
package-lock.json
yarn.lock
bun.lockb

3.4. Deshabilitar la Vigilancia Automática de Archivos de Sesión (auto_watch = false)

[!CAUTION] Prevención de Parpadeo del Sistema: Por defecto, codebase-memory-mcp registra automáticamente los proyectos conectados con su vigilante de git en segundo plano (auto_watch = true). En Windows y sistemas multitarea, el vigilante detecta los guardados de archivos, genera un proceso de trabajo index.supervisor y comprime .codebase-memory/graph.db.zst vía zstd en cada pulsación de tecla/guardado, lo que provoca micro-parpadeos severos en la UI del editor y el gestor de ventanas. Deshabilitar siempre la vigilancia automática de sesiones globalmente:

codebase-memory-mcp config set auto_watch false

Cuando está deshabilitado, las sesiones no se registran con el vigilante de fondo, eliminando completamente los congelamientos del editor. El grafo se consulta a través de herramientas MCP y se actualiza explícitamente bajo demanda.

3.5. Higiene y Persistencia de Git

• Solo Local (Por Defecto): Añadir .codebase-memory/ a .gitignore. Nunca confirmar el artefacto binario en cada guardado.
• Compartición de Instantáneas en Equipo: Si se confirma la instantánea del grafo pre-indexado para el equipo, rastrear .codebase-memory/graph.db.zst con Git LFS en .gitattributes raíz:

  .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text
  

3.6. Indexación Inicial Bajo Demanda y Script de Cadencia

1. Ejecutar la indexación inicial bajo demanda (usando el modo moderate o fast para saltar cálculos pesados de embeddings semánticos):

   codebase-memory-mcp cli index_repository --repo-path "<ruta-canónica-del-repo>" --mode moderate
   

2. Añadir un script de cadencia a package.json para refrescar el índice en hitos/commits importantes:

   {
     "scripts": {
       "cbm:update": "codebase-memory-mcp cli index_repository --repo-path . --mode moderate --persistence true"
     }
   }
   

---

Paso 4: Configurar Hooks de Git con Husky y Commitlint

Impone Commits Convencionales y garantiza que las suites de prueba se ejecuten antes de que el código pueda ser enviado a ramas remotas.

1. Instalar Dependencias de Desarrollo:

   pnpm add -D husky @commitlint/cli @commitlint/config-conventional
   

2. Configurar commitlint.config.mjs:

   export default {
     extends: ["@commitlint/config-conventional"],
   };
   

3. Inicializar Husky:

   pnpm exec husky init
   

4. Configurar el Hook commit-msg:

   echo "pnpm exec commitlint --edit \$1" > .husky/commit-msg
   

5. Configurar el Hook pre-push: Obliga a ejecutar la suite de pruebas antes de permitir cualquier git push:

   echo "pnpm run test:all" > .husky/pre-push
   

   [!NOTE] Asegúrate de que los scripts de prueba en package.json incluyan banderas seguras (ej. --passWithNoTests) para que los repositorios sin archivos de prueba salgan con código 0 en lugar de romper los envíos. Nunca crear archivos de prueba de muestra/dummy en el workspace.

---

Paso 5: Configurar Contenedorización Docker Multi-Etapa de Producción

Configurar la contenedorización estrictamente para compilaciones y despliegues de producción independientes. El desarrollo local se ejecuta en la máquina anfitriona usando el gestor de paquetes nativo del proyecto.

5.1. Configurar .dockerignore

Excluir artefactos locales, historial de git y secretos:

node_modules/
.pnp/
.pnpm-store/
dist/
build/
coverage/
test-results/
.env*
*.log
.git/
.dockerignore
Dockerfile*
docker-compose*.yml
.codebase-memory/

5.2. Dockerfile Multi-Etapa

Crear una compilación multi-etapa de 3 etapas (dependencies → builder → runner) ejecutándose bajo un usuario seguro no root:

ARG NODE_VERSION=22-slim

FROM node:${NODE_VERSION} AS dependencies
WORKDIR /app
ENV CI=true
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
  if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm install --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  else yarn install --frozen-lockfile; fi

FROM node:${NODE_VERSION} AS builder
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; else npm run build; fi

FROM node:${NODE_VERSION} AS runner
WORKDIR /app
ENV NODE_ENV=production
ARG PORT=3000
ENV PORT=${PORT}
ENV HOSTNAME="0.0.0.0"
COPY --from=builder --chown=node:node /app/dist ./dist
USER node
EXPOSE ${PORT}
CMD ["node", "dist/index.js"]

5.3. Pilas Docker Compose

1. Compilación y Prueba Local (docker-compose.yml):

   services:
     app:
       build:
         context: .
         dockerfile: Dockerfile
       container_name: app-production
       restart: unless-stopped
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

2. Pila Pre-Compilada de Producción (docker-compose.prod.yml): Extrae imágenes multi-arquitectura pre-compiladas directamente de GHCR sin código fuente:

   services:
     app:
       image: ghcr.io/<owner-minusculas>/<repo-minusculas>:${IMAGE_TAG:-latest}
       container_name: app-production
       restart: always
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

---

Paso 6: Configurar CI/CD Optimizado para Créditos y Automatización de Release Please

Automatizar versiones semánticas, changelogs y publicación multi-arquitectura (AMD64 y ARM64) en GitHub Container Registry a través de .github/workflows/release-please.yml:

Reglas de Diseño Core DevOps:

1. Puerta de Pruebas Automatizada: Ejecuta las pruebas del proyecto en pull requests y commits a main.
2. Automatización de Release Please: Automatiza incrementos de versión, changelogs y PRs de lanzamiento.
3. concurrency.cancel-in-progress: false: Nunca cancelar flujos de trabajo de lanzamiento o despliegues de rama principal en curso.
4. Matriz de Compilación Multi-Arquitectura de Dos Etapas: Compilar AMD64 y ARM64 en máquinas ejecutoras nativas (ubuntu-latest y ubuntu-24.04-arm) sin emulación QEMU. Empujar imágenes por digest.
5. Fusión de Manifiestos Digest: Un trabajo merge-manifest downstream fusiona los digests AMD64 y ARM64 en una etiqueta multi-arquitectura unificada.
6. Nombre de Repositorio en Minúsculas: Transformar siempre github.repository a minúsculas vía t

...