/wiki-init — Wiki Viviente para humanos y agentes

Instala un sistema de documentación completo en cualquier repo. Sirve tanto para un dev nuevo que no sabe nada del proyecto, como para el agente que retoma contexto en cada sesión. Es un documento vivo: cada cambio importante se refleja en el wiki y se sube a Linear como resource del proyecto.

Material extendido (cargar a demanda):

• references/plantillas-wiki.md — templates completos de index, onboarding, testing-guide, changelog, architecture, decisions y reglas para glossary/dont-touch/workflows/reference.
• references/bloque-claude-md.md — bloque que se inserta en CLAUDE.md del repo destino, con reglas de inserción (no sobreescribir si ya existe).
• scripts/wiki-sync.mjs — ejecutar desde el repo destino para subir el wiki a Linear como documents del proyecto.

Precondiciones

1. Estar dentro del repo destino (CWD = root del proyecto).
2. El repo tiene CLAUDE.md en root (si no, crearlo mínimo antes).
3. El repo NO tiene ya /wiki (si lo tiene, avisar y preguntar antes de sobreescribir).

Qué instala

<repo>/
├── wiki/
│   ├── index.md          ← bienvenida + mapa del proyecto (empieza aquí)
│   ├── onboarding.md     ← cómo arrancar desde cero (para humanos)
│   ├── architecture.md   ← stack, capas, datos, auth
│   ├── testing-guide.md  ← flujos que un humano debe probar + tests automáticos
│   ├── decisions.md      ← decisiones técnicas con Por qué / Aplica a
│   ├── changelog.md      ← historial de cambios por sesión (documento vivo)
│   ├── dont-touch.md     ← archivos privados, config sensible, reglas commit
│   ├── glossary.md       ← términos del dominio
│   ├── workflows.md      ← flujos recurrentes + delegación humana
│   └── reference.md      ← IDs Linear/Harvest, Slack, APIs frecuentes
├── raw/
│   └── README.md         ← inbox de notas crudas
├── scripts/
│   └── wiki-sync.mjs     ← sube wiki a Linear como resource (copiar desde este skill)
├── .gitignore            ← + raw/* !raw/README.md
└── CLAUDE.md             ← + bloque "Wiki del proyecto"

Flujo de ejecución

Paso 0 — Modo interactivo (OBLIGATORIO antes de generar)

Antes de crear ningún archivo, hacer estas preguntas al usuario. Esperar respuestas antes de continuar.

Voy a generar el wiki de este proyecto. Necesito 5 respuestas rápidas:

1. ¿Quién va a usar esto además de ti? (ej: dev externo, cliente, equipo interno)
2. ¿Cuál es el flujo principal que debe poder hacer un usuario nuevo sin ayuda?
   (ej: "reservar un set", "crear un proyecto", "generar una factura")
3. ¿Hay algo en este proyecto que parece obvio pero no lo es? ¿Alguna trampa?
4. ¿Qué es lo que más cambia en este proyecto sprint a sprint?
5. ¿Tienes el ID del proyecto en Linear? (para conectar el wiki-sync)

Usar las respuestas para enriquecer el contenido. Si el usuario no tiene alguna respuesta, marcar como TODO en el archivo correspondiente.

Paso 1 — Descubrir el repo

Leer en paralelo:

• package.json o equivalente para stack y scripts
• CLAUDE.md para contexto existente
• README.md si existe
• Estructura top-level
• lib/, src/, app/ — solo listar, no leer todo
• git log --oneline -10 para entender qué ha cambiado recientemente
• CHANGELOG.md o TODOS.md si existen

Nunca inventar datos. Si no se puede inferir algo, marcarlo TODO visible.

Paso 2 — Poblar archivos del wiki

Cargar references/plantillas-wiki.md y usar las plantillas literales adentro. Rellenar placeholders con datos del Paso 0 (modo interactivo) y Paso 1 (descubrimiento).

Reglas:

• Solo rellenar lo que tengas dato. Resto queda TODO visible.
• No inventar URLs, IDs, ni nombres de variables que no encontraste en el repo.

Paso 3 — Copiar scripts/wiki-sync.mjs

Copiar scripts/wiki-sync.mjs de este skill al scripts/ del repo destino. Si scripts/ no existe, crearlo.

Agregar LINEAR_PROJECT_ID= al .env.example si existe.

Paso 4 — Actualizar .gitignore

Agregar al final:

# Wiki raw inbox (notas crudas, privadas)
raw/*
!raw/README.md

Paso 5 — Insertar bloque en CLAUDE.md

Cargar references/bloque-claude-md.md y aplicar las reglas de inserción ahí declaradas. No sobreescribir si ya existe sección similar — preguntar al usuario primero.

Paso 6 — Reporte final

Wiki instalado en [repo]

Archivos creados:
  wiki/index.md
  wiki/onboarding.md
  wiki/architecture.md
  wiki/testing-guide.md
  wiki/decisions.md
  wiki/changelog.md
  wiki/dont-touch.md
  wiki/glossary.md
  wiki/workflows.md
  wiki/reference.md
  raw/README.md
  scripts/wiki-sync.mjs

TODOs pendientes (necesito tu ayuda para completarlos):
  [lista de TODOs específicos que quedaron en los archivos]

Próximos pasos:
1. Agrega LINEAR_PROJECT_ID=[id] a tu .env.local
2. Corre `node scripts/wiki-sync.mjs` para subir el wiki a Linear
3. Revisa wiki/testing-guide.md y completa los flujos de prueba
4. Revisa los TODOs de onboarding.md con las variables de entorno reales

Principios

• No inventar. Si un dato no está en el repo, marcarlo TODO visible.
• Humanos primero. onboarding.md y testing-guide.md son para personas, no para el agente. Lenguaje claro, pasos concretos.
• Documento vivo. El valor real es que se actualice. El protocolo en CLAUDE.md es lo que lo mantiene vivo.
• Linear como fuente de verdad externa. El wiki vive en el repo, Linear es el espejo accesible para clientes y equipo sin acceso al código.
• No duplicar con auto-memory. Auto-memory = preferencias del usuario. Wiki = conocimiento del repo.
• No romper nada existente. Si hay CLAUDE.md con protocolo similar, NO sobreescribir — preguntar.

Referencia canónica

El wiki más maduro vive en c:\Users\mnbon\gabrielneuman\gnbsite\wiki\. Cuando tengas dudas de formato, abrirlo y copiar estructura.