init-project
propósito
Inicializar el sistema de documentación de agente de un nuevo proyecto a partir de un paquete portátil en un solo paso. Después de la inicialización, el proyecto se mantiene por sí mismo utilizando el estándar desplegado (árbol de decisión doc-organization.md §8.3 + meta-estándares portátiles). init se ejecuta una vez por proyecto; update se puede volver a ejecutar posteriormente en ese proyecto para extraer archivos portátiles más nuevos del paquete (fusión segura de 3 vías — nunca sobrescribe ediciones locales no promocionadas). check/promote mantienen el paquete en sí y se ejecutan solo en este repositorio maestro.
dependencias
./portable/rules/ — 7 reglas portátiles (siempre cargadas + ámbito de ruta)./portable/agent-guide/ — five-why.md, markdown.md, mermaid.md, orchestration-policy.md, worktree.md (desplegar en docs/agent-guide/general/)./portable/skills/ — skill-designer/, skill-writer/, document-writer/ (árboles completos)./portable/agents/ — skill-writer-auditor.md./templates/ — CLAUDE.md.tpl, agent-guide/index.md.tpl, docs/index.md.tpl./VERSION — versión del paquete, aumentada en cada promociónscripts/update.mjs (raíz del repositorio) — motor para el modo update (fusión 3 vías paquete→directorio); scripts/sync-version.mjs — sincronización de fuente única de versión
modos
| invocación | se ejecuta en | acción |
|---|
/init-project | nuevo proyecto | desplegar paquete (flujo de trabajo a continuación) |
/init-project check | repositorio maestro | comparación sha256 de paquete ↔ directorio por mapa → reportar desviaciones |
/init-project promote | repositorio maestro | copiar directorio → paquete para cada archivo mapeado, aumentar VERSION |
/init-project update | proyecto inicializado | extraer archivos portátiles más nuevos del paquete → directorio, fusión segura de 3 vías (manifiesto ↔ directorio ↔ paquete); saltar conflictos (flujo de trabajo a continuación) |
flujo de trabajo (init — nuevo proyecto)
- Escanear proyecto: detectar pila tecnológica + módulos opcionales según la columna de señal de la
## matriz de módulos. Salida: conjunto de módulos propuesto + valores de ranura descubiertos.
- Entrevista: confirmar el conjunto de módulos propuesto; preguntar por ranuras no escaneables (puertos de desarrollo en uso, propiedad del ámbito, lenguaje de documentación). Ranura sin respuesta → dejar marcador TODO, nunca inventar un valor; módulo incierto → omitirlo.
- Copiar
portable/ textualmente: portable/rules/* → .claude/rules/; portable/agent-guide/* → docs/agent-guide/general/; portable/skills/* → .claude/skills/; portable/agents/* → .claude/agents/.
- Renderizar plantillas: rellenar
{{slots}} de la entrevista en CLAUDE.md, docs/agent-guide/index.md, docs/index.md; ranura faltante → mantener marcador TODO.
- Generar reglas opcionales: para cada módulo opcional confirmado, escribir una regla ajustada al proyecto en
docs/agent-guide/general/ según rule-writing-standards, y añadir su línea de activación a CLAUDE.md en el mismo paso — sin plantilla codificada.
- Escribir manifiesto
.claude/init-manifest.json: { version, deployedAt, files:[{path,sha256}], templates:[{path,sha256}], modules:[...] } (procedencia; files[] leído por update para detección de desviaciones de 3 vías — mantener sha256 preciso; templates[] registra el sha de la .tpl con la que se construyó cada archivo renderizado — path = ruta de la plantilla relativa a templates/, ej. CLAUDE.md.tpl, usado por update para ADVERTIR cuando una plantilla cambió desde el despliegue).
- Verificar: cada archivo desplegado está en el nivel correcto; cada archivo de regla/guía de agente lleva metadatos
scope:; CLAUDE.md dentro del presupuesto de tokens; cada archivo bajo demanda que afecta el comportamiento tiene una línea de activación o entrada de enrutador (alcanzabilidad, archivo→activación); cada activación MUST Read en CLAUDE.md resuelve a un archivo desplegado (alcanzabilidad, activación→archivo — sin activaciones muertas); no queda ningún {{slot}} sin renderizar excepto marcadores TODO intencionales. Hecho = lista de verificación aprobada + manifiesto escrito.
mapa paquete ↔ directorio (check / promote — repositorio maestro; update — proyecto inicializado)
| ruta del paquete | ruta del directorio |
|---|
portable/rules/* | .claude/rules/* |
portable/agent-guide/* | docs/agent-guide/general/* |
portable/skills/* | .claude/skills/* |
portable/agents/* | .claude/agents/* |
check: sha256 de cada par → listar discrepancias. La dirección de actualización predeterminada es directorio → paquete (promote); corregir el directorio primero, luego promover.promote: copiar directorio → paquete para cada archivo mapeado, luego aumentar la versión mediante node scripts/sync-version.mjs set <x.y.z> (escribe el VERSION canónico + lo refleja en .claude-plugin/* y la insignia del README).
flujo de trabajo (update — proyecto inicializado)
Dirección paquete → directorio (inverso de promote). Toca solo el conjunto portátil textual; el fenotipo renderizado (CLAUDE.md, index.md, guías creadas por el proyecto) está fuera del alcance. Invocar update.mjs por su ruta dentro del plugin instalado (se localiza a sí mismo desde su propia ubicación); --project es la raíz del proyecto inicializado y por defecto es el directorio actual.
- Simulación:
node <plugin>/scripts/update.mjs --project <project-root> → revisar el plan de AÑADIR / ACTUALIZAR / CONFLICTO y el delta de versión.
- Resolver cada CONFLICTO primero — un conflicto = un archivo portátil editado localmente desde el despliegue. Promoverlo río arriba (para que la mejora entre al paquete) o sobrescribir manualmente después de revisar. Nunca sobrescribir a ciegas.
- Aplicar:
node <plugin>/scripts/update.mjs --apply --project <project-root> → escribe AÑADIR + ACTUALIZAR, salta conflictos, actualiza version del manifiesto + files[].sha256.
- Solo aditivo e in situ —
update nunca elimina: un archivo eliminado del paquete permanece en el proyecto, y un archivo eliminado localmente se vuelve a añadir. Podar esos manualmente si es necesario.
templates/* (CLAUDE.md, index.md — fenotipo renderizado) nunca se sobrescriben: sus ranuras contienen valores específicos del proyecto. update solo emite una ADVERTENCIA cuando una .tpl cambió desde el despliegue (sha vs manifest.templates[]); volver a renderizar manualmente (diff de .tpl vs directorio, re-aplicar cambios estructurales, mantener valores de ranura) o volver a ejecutar /init-project. La ADVERTENCIA persiste hasta que el próximo init vuelva a registrar el sha de la plantilla.
- Código de salida: 0 = actualizado o aplicado limpiamente; 1 = quedan conflictos; 2 = error de configuración (sin manifiesto → el proyecto no fue inicializado por este plugin).
matriz de módulos
| módulo | incluye | desplegar cuando | señal de escaneo (ejemplos, no exhaustiva) |
|---|
| core | portable/* (los 4 grupos) + 3 plantillas | siempre | — |
| runtime | agent-guide/general/local-runtime.md + activación de CLAUDE.md (el skill escribe según escaneo, paso 5) | el proyecto ejecuta un servidor de desarrollo | scripts dev/start en package.json, launchSettings.json, configuración vite/next/dotnet/django/cargo |
| e2e | agent-guide/general/<tool>.md (nombrado según la herramienta detectada) + activación de CLAUDE.md (paso 5) | el proyecto tiene pruebas E2E de navegador | dependencia playwright/cypress/selenium, carpeta e2e/, configuración E2E |
- Módulo opcional se despliega solo cuando el escaneo confirma O el usuario confirma en la entrevista — incierto → omitir.
- Git: guardarraíl mínimo (hacer commit solo a solicitud, nunca hacer push) se entrega en
CLAUDE.md.tpl; la política detallada es scope: project — el proyecto escribe docs/agent-guide/general/git.md bajo demanda, añadiendo su línea de activación en el mismo commit (alcanzabilidad — nunca una activación que apunte a un archivo faltante).
- Un módulo omitido que se necesite más tarde → el proyecto escribe la regla por sí mismo según el estándar desplegado. Un nuevo módulo entra al paquete solo mediante
promote después de que un proyecto real pruebe el patrón.
reglas de independencia
- El skill se ejecuta una vez por proyecto; los archivos desplegados no hacen referencia a ningún archivo de este repositorio maestro; las reglas del proyecto nunca nombran este skill.
- Autónomo excepto por el mapa paquete↔directorio anterior, que se ejecuta solo en el repositorio maestro para check/promote.
ejemplos
✅ el escaneo encuentra package.json con script "dev" → proponer módulo runtime → paso 5 escribe
general/local-runtime.md + añade "Ejecutar servidor de desarrollo → MUST Read ..." a CLAUDE.md
❌ desplegar módulo runtime sin señal de escaneo ni confirmación en entrevista (módulo adivinado)
✅ /init-project check → "DISCREPANCIA: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
→ corregir directorio primero → /init-project promote
❌ editar portable/* directamente y luego iniciar un nuevo proyecto (el paquete diverge silenciosamente del directorio)
archivos de referencia
- paquete:
./portable/**
- plantillas:
./templates/**
- versión:
./VERSION