Contribuir a la comunidad HagiTask

A quién va dirigida: colaboradores y responsables de tareas comunitarias HagiTask.

Requisitos previos:

Has clonado hagitask-community-packages y tienes preparados Node.js/npm.
Puedes inicializar el checkout anidado de hagitask en ese repositorio.
Conoces JSON, Markdown y las pull requests de Git.

Esta página es la guía completa para colaboradores. El README de Community Packages se limita a las responsabilidades del repositorio y a la referencia de directorios y comandos.

Responsabilidades de los repositorios y proceso de publicación

Community Packages es la fuente de referencia para las definiciones de tareas comunitarias. Los colaboradores editan data/<taskId>/; HagiTask mantiene el esquema compartido de los paquetes. HagiTask Site lee un commit concreto de Community Packages, normaliza los datos y genera:

/index.json: un catálogo ligero para descubrir tareas.
/tasks/<taskId>.json: documentos de detalle con todos los recursos y la información de compatibilidad.
/packages/<taskId>.zip: archivos para instalar desde la aplicación.

Estos archivos JSON y ZIP son artefactos generados: no los crees ni modifiques a mano en Community Packages. El archivo incluye todo el directorio data/<taskId>/, de modo que cualquier recurso nuevo que añadas a ese directorio se publicará con el paquete.

1. Preparar el esquema y el repositorio

Ejecuta estos comandos en el repositorio Community Packages:

git submodule update --init --recursive
npm install

La fuente de referencia del esquema compartido de paquetes está en repos/hagitask/schemas/task-preset-plugin/. Community Packages la utiliza mediante un checkout anidado. No copies ni modifiques el esquema en Community Packages ni en HagiTask Site.

2. Crear un paquete de tareas

Coloca las tareas nuevas en data/<taskId>/. El taskId debe ser estable, único y estar escrito en kebab-case con minúsculas; además, siempre debe coincidir exactamente con taskPresetId en manifest.json. Si cambias el nombre del directorio, cambiarán las URL publicadas de los detalles y del archivo.

Entre los ID canónicos publicados actualmente se encuentran:

Nombre visible	`taskId`
UI Master	`ui-master`
AgentsMD	`claude-md-update`
Last 30 Days	`last30days`
Ponytail	`ponytail`
Goal	`goal`
OpenSpec Spec Compress	`openspec-spec-compress`

agentsmd y portytail son solo alias habituales, no ID de tareas del protocolo.

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # solo si se proporciona un directorio de comandos
  backend/
    task-preset.json
    prompts.json
    templates/<locale>/
      system.md
      user.hbs
  locales/
    en-US.json
    zh-CN.json
  store-page/
    index.en-US.md
    index.zh-CN.md

Son obligatorios manifest.json, frontend/panel.json, backend/task-preset.json, backend/prompts.json, los archivos de idioma inglés y chino, las dos páginas de la tienda y las plantillas de prompts para cada idioma declarado. Añade commands.json solo cuando el paquete incluya realmente un directorio de comandos.

Cómo afectan los archivos al catálogo

Archivo fuente	Resultado publicado
`version` de `manifest.json`	Versión en el catálogo y los detalles
`owner` de `manifest.json`	Editor
`localization` de `manifest.json`	Conjunto de traducciones cargado por el cliente
`requirements` de `backend/task-preset.json`	Requisitos de la tarea e información de compatibilidad derivada
`title` / `summary` de la página de la tienda	Nombre, resumen y descripción en varios idiomas
`catalog` / `tags` de la página de la tienda en inglés	Categoría y etiquetas

Si la página en inglés no tiene catalog, se utiliza la primera etiqueta como categoría y, si tampoco existe, General. Solo los campos catalog y tags de la página en inglés intervienen en la generación de categorías y etiquetas del catálogo.

3. Referenciar el esquema y completar los recursos

Conserva en cada archivo JSON el campo $schema que le corresponda, con la URL pública del esquema:

https://tasks.hagicode.com/schemas/task-preset-plugin/<schema>.schema.json

La correspondencia entre archivos y esquemas se define en hagitask/schemas/task-preset-plugin/. manifest.json debe declarar el ID de la tarea, la versión, el editor, el conjunto de traducciones y las rutas de los recursos frontend y backend. Los archivos de idioma deben contener el mismo conjunto de claves.

store-page/index.en-US.md e index.zh-CN.md necesitan al menos los campos de frontmatter locale, slug, title y summary. Coloca catalog y tags en la página en inglés, ya que el sitio de publicación genera las categorías y etiquetas a partir de ella.

4. Versionar y validar

Cada vez que cambie contenido ya publicado, actualiza version en manifest.json siguiendo las reglas del versionado semántico. No reutilices un número de versión anterior: los metadatos del catálogo y el resumen del paquete dejarían de ser inequívocos.

Ejecuta la validación existente:

npm run validate

El validador comprueba los ID canónicos, el esquema, las declaraciones de recursos, la cobertura de idiomas, las plantillas de prompts y el frontmatter de las páginas de la tienda. Si falla, corrige los archivos fuente de data/<taskId>/; no edites /index.json, /tasks/<taskId>.json ni /packages/<taskId>.zip. HagiTask Site genera estos artefactos en cada publicación.

El flujo de validación se ejecuta en las pull requests que modifican el contenido de los paquetes y en los push a main. Si la validación falla, el paquete no se puede fusionar.

Para comprobar más a fondo el contrato de publicación, puedes ejecutar estos comandos en el checkout de hagitask-site:

npm install
npm run typecheck
npm run build
npm run stage:schemas
npm run verify

Durante la compilación del sitio se vuelven a normalizar los datos y a validar los esquemas de publicación. Si termina correctamente, el catálogo y los detalles generados cumplen los contratos community-index-v1 y community-task-detail-v1.

5. Enviar una pull request

Envía la pull request a hagitask-community-packages, no a hagitask-site ni a hagitask. Tras fusionarla, HagiTask Site actualiza el commit concreto de Community Packages que utiliza y vuelve a generar el catálogo, los detalles y los ZIP.

hagitask se encarga del esquema compartido y de las tareas predefinidas. Si hay que cambiar el contrato del formato de paquetes, propón el cambio de esquema por separado en el repositorio HagiTask. Community Packages solo mantiene los datos fuente de data/; el sitio solo publica los resultados generados.

Si falla la validación

Corrige los archivos fuente de data/<taskId>/ indicados por el error:

Error del esquema del paquete: corrige el JSON correspondiente; no elimines $schema ni relajes la validación.
Faltan recursos o archivos de idioma: actualiza el manifest, los archivos de idioma, las plantillas de prompts o las páginas de la tienda para que las declaraciones coincidan con los archivos reales.
Error del esquema de los detalles del catálogo o del archivo: revisa el paquete fuente y los datos de entrada de la normalización del sitio; no retoques el JSON generado.

Si el problema está en el propio contrato del esquema, propón modificarlo en el repositorio HagiTask en lugar de duplicar el esquema en este repositorio.

Siguiente paso: Instalar HagiTask o Usar HagiTask.