registro-proyecto

Copyright (C) 2026 ZionXiaoxiSuOGLocGo SPDX-License-Identifier: GPL-3.0-or-later

project-docs

Crea y mantiene un sistema de tres documentos para el conocimiento del proyecto. Soporta todos los tipos de proyecto detectados por project-onboard — selecciona automáticamente la plantilla correcta según el tipo de proyecto.

Sistema de Tres Documentos

Archivo	Propósito	Frecuencia de Actualización
AGENTS.md	Visión general del proyecto: identidad, estructura de directorios, arquitectura de clases, puntos de entrada, dependencias, Notas	Por cada hito (~3-5 archivos/clases nuevos)
PROJECT_STATE.md	Documento vivo: espectro completo de clases/fuentes (con parámetros), configuración, mapa de módulos, flujos del sistema, lista de hecho/pendiente	Al final de cada sesión
DEVLOG.md	Registro de desarrollo: entradas de la línea de tiempo — qué se hizo, por qué, qué se aprendió	Por día o por hito de funcionalidad

Consulte maintenance-spec.md para reglas detalladas sobre desencadenantes de actualización, límites de contenido y verificaciones de consistencia.

Selección de Plantilla

Las plantillas siguen el mismo patrón de autodescubrimiento que los paquetes de reglas de project-onboard. El skill intenta cargar templates/<type>/PROJECT_STATE.md.tmpl donde <type> es el valor de Type de AGENTS.md Basic Information en minúsculas. Si no existe una plantilla específica para el tipo, se usa la plantilla genérica templates/PROJECT_STATE.md.tmpl.

templates/<type>/PROJECT_STATE.md.tmpl ¿existe? → usarla
                                             no → usar templates/PROJECT_STATE.md.tmpl (fallback genérico)

Para añadir soporte a un nuevo motor o framework: cree templates/<type>/PROJECT_STATE.md.tmpl. No se necesitan cambios de código — el skill lo descubre automáticamente.

Todos los tipos comparten templates/DEVLOG.md.tmpl (independiente del tipo de proyecto).

Mapeo de Campos AGENTS.md → PROJECT_STATE.md

Al precargar el PROJECT_STATE.md desde los datos de AGENTS.md, use este mapeo:

Sección de AGENTS.md	Campo de AGENTS.md	Sección de Plantilla STATE	Marcador de STATE
Basic Information	Type, Language, Framework/Engine, Key Dependencies	§1 Identidad del Proyecto	{{PROJECT_TYPE}}, {{LANGUAGE}}, {{FRAMEWORK}}, {{KEY_DEPENDENCIES}}
Basic Information	Engine (para proyectos de juegos)	§1 Identidad del Proyecto	{{ENGINE_VERSION}}
Directory Structure	Directorios y descripciones	§2 Estructura de Directorios	{{DIRECTORY_TREE}} (genérico) o Source/{{MODULE_NAME}}/... (UE)
Core Architecture	Archivos/clases clave y roles	§3 Espectro de Fuentes/Scripts	{{CLASS_NAME}}, {{RESPONSIBILITY}}, {{FILE_NAME}}
Dependencies	Resumen de paquetes	§4 Configuración / §7 Dependencias	{{CONFIG_KEY}}, {{DEP_NAME}} (depende del contexto)
Build & Run	Comandos de compilación/prueba	§9 Compilación y Ejecución	{{BUILD_CMD}}, {{RUN_CMD}}, {{TEST_CMD}}
Entry Points	Archivo/escena de inicio y rol	§1 Identidad del Proyecto (Módulo)	{{MODULE_NAME}}

Para salida en idioma no inglés: traduzca los encabezados de secciones, etiquetas y descripciones de marcadores, pero mantenga intactos los marcadores {{PLACEHOLDER}}.

Cuándo Usar Este Skill

• El usuario dice "init project docs" / "建立文档体系" / "project-docs"
• Un nuevo proyecto necesita PROJECT_STATE.md y DEVLOG.md
• Un proyecto existente tiene AGENTS.md pero faltan los otros dos documentos
• El usuario pide actualizar el estado del proyecto después de una sesión

Flujo de Trabajo

1. Inicializar (proyecto nuevo / documentos faltantes)

0. Pregunte al usuario en qué idioma generar los documentos. Por defecto, inglés si omite la respuesta o dice "no me importa". Cualquier idioma que el LLM pueda generar es compatible — el agente maneja la traducción en el momento de la generación:

   "¿En qué idioma deben escribirse los documentos del proyecto? Por defecto: inglés. Cualquier idioma que el LLM pueda generar es compatible."

1. Verifique si existe AGENTS.md.

   • Si no existe: Ofrezca ejecutar primero el skill project-onboard para generar AGENTS.md. Deténgase aquí.
   • Si existe: Lea AGENTS.md y extraiga:
     • Nombre del proyecto
     • Type (de Basic Information — ej., "unreal", "unity", "nodejs", "python")
     • Arquitectura central (clases, archivos, roles)

2. Detectar plantilla: Basándose en el Type extraído (en minúsculas), intente cargar una plantilla específica del tipo. Si no hay coincidencia, use la plantilla genérica:

   • Primero intente templates/<type>/PROJECT_STATE.md.tmpl
   • Si ese archivo no existe, use templates/PROJECT_STATE.md.tmpl (genérico)

3. Genere PROJECT_STATE.md a partir de la plantilla seleccionada:

   • Precargue las secciones §1-§3 desde los datos de AGENTS.md usando la tabla de mapeo de campos anterior.
   • Deje las secciones restantes con su estructura de marcadores para futuras actualizaciones.

4. Genere DEVLOG.md a partir de templates/DEVLOG.md.tmpl:

   • Rellene el nombre del proyecto.
   • Deje la plantilla de entrada lista para la primera entrada del registro de desarrollo.

5. Anteponga el siguiente bloque al inicio de AGENTS.md, justo después de la línea del encabezado # Project Name (pero antes del resto del contenido):

   ## Lea Esto Primero
   
   1. Lea `PROJECT_STATE.md` — estado actual de la tarea y elementos pendientes (§10)
   2. Lea `DEVLOG.md` — historial reciente de desarrollo
   
   ---
   

6. Reporte qué se creó, qué plantilla se usó y en qué idioma.

2. Actualizar (documentos existentes)

1. Lea PROJECT_STATE.md → identifique la lista de tareas pendientes de §10
2. Pregunte al usuario qué se completó / qué cambió
3. Actualice las secciones afectadas:
   • §1-§2: si la identidad del proyecto o la estructura de directorios cambió
   • §3: nuevas clases, archivos o miembros clave
   • §4: cambios de configuración (propiedades de blueprint, ajustes de prefab o configuración genérica)
   • §5: enlaces de entrada, asignaciones de acciones o cambios en módulos/paquetes
   • §6: cambios en la lógica del sistema, flujo de arquitectura o sistema de juego
   • §7: cambios en la configuración de escenas/niveles o servicios externos
   • §8: cualquier cambio en parámetros numéricos
   • §9: problemas de compilación, nuevos errores de compilación o cambios de comandos
   • §10: siempre actualizar — lista de hecho, lista de pendientes, problemas conocidos
4. Añada una entrada a DEVLOG.md (según el formato de maintenance-spec.md)
5. Si la arquitectura cambió (nuevas clases, plugins, directorios) → actualice AGENTS.md

3. Verificación de Consistencia

Después de cualquier actualización, verifique:

• No hay datos superpuestos entre AGENTS.md y PROJECT_STATE.md (visión general de la arquitectura vs. detalles de parámetros)
• Las entradas de estructura de directorios en AGENTS.md tienen todas su contraparte en PROJECT_STATE.md
• Los valores de los parámetros en PROJECT_STATE.md §8 coinciden con los valores por defecto reales de la fuente (ej., valores por defecto en .h, valores de archivos de configuración, anulaciones de CDO de BP)
• La lista de tareas pendientes de PROJECT_STATE.md §10 no contradice la última entrada de DEVLOG.md (si DEVLOG dice hecho, STATE debe coincidir)
• No hay información duplicada entre los tres documentos (un hecho = un lugar)

Plantillas

Las plantillas se autodescubren por tipo de proyecto — no hay una tabla de mapeo fija. El directorio refleja la estructura de referencia de project-onboard:

templates/
├── DEVLOG.md.tmpl              ← Todos los tipos (genérico)
├── PROJECT_STATE.md.tmpl       ← Fallback (genérico)
├── unreal/PROJECT_STATE.md.tmpl     ← Unreal Engine
└── unity/PROJECT_STATE.md.tmpl      ← Unity

Los archivos templates/<type>/PROJECT_STATE.md.tmpl son opcionales. El skill intenta cargar uno que coincida con el Type de AGENTS.md; si no existe, usa la plantilla genérica raíz.

Añadir un nuevo tipo: cree templates/<type>/PROJECT_STATE.md.tmpl con secciones específicas del tipo. El skill lo descubre en la siguiente ejecución — cero cambios de código.

Reglas

• Nunca sobrescribir archivos existentes. Si un documento existe, actualícelo en su lugar.
• Respetar los límites de contenido: AGENTS.md = visión general de la arquitectura. PROJECT_STATE.md = detalles de parámetros + estado. DEVLOG.md = narrativa de la línea de tiempo.
• Especificación de mantenimiento: Consulte maintenance-spec.md para desencadenantes de actualización exactos, límites de contenido y prácticas prohibidas.
• Rutas/nombres de clase específicos del proyecto en STATE/DEVLOG son esperados — son documentos del proyecto, no manuales reutilizables.