Contribuer à la communauté HagiTask

Public concerné : contributeurs et responsables des tâches communautaires HagiTask.

Prérequis :

Vous avez cloné hagitask-community-packages et préparé Node.js/npm.
Vous pouvez initialiser le checkout hagitask imbriqué dans ce dépôt.
Vous connaissez JSON, Markdown et les pull requests Git.

Cette page constitue le guide complet pour les contributeurs. Le README de Community Packages se limite aux responsabilités du dépôt et aux références des répertoires et des commandes.

Responsabilités des dépôts et chaîne de publication

Community Packages fait autorité pour les définitions des tâches communautaires. Les contributeurs modifient data/<taskId>/ ; HagiTask maintient le schéma partagé des paquets. HagiTask Site lit un commit précis de Community Packages, normalise les données et génère :

/index.json : un catalogue léger pour découvrir les tâches.
/tasks/<taskId>.json : des documents détaillés contenant toutes les ressources et les informations de compatibilité.
/packages/<taskId>.zip : des archives destinées à l’installation par l’application.

Ces fichiers JSON et ZIP sont des artefacts générés : ne les créez pas et ne les modifiez pas manuellement dans Community Packages. L’archive contient tout le répertoire data/<taskId>/ ; les nouvelles ressources ajoutées à ce répertoire seront donc publiées avec le paquet.

1. Préparer le schéma et le dépôt

Exécutez ces commandes dans le dépôt Community Packages :

git submodule update --init --recursive
npm install

La source faisant autorité pour le schéma partagé des paquets se trouve dans repos/hagitask/schemas/task-preset-plugin/. Community Packages l’utilise au moyen d’un checkout imbriqué. Ne copiez pas et ne modifiez pas le schéma dans Community Packages ou HagiTask Site.

2. Créer un paquet de tâches

Placez toute nouvelle tâche dans data/<taskId>/. Le taskId doit être stable, unique et écrit en kebab-case minuscule ; il doit toujours correspondre exactement au taskPresetId de manifest.json. Renommer le répertoire modifie les URL publiées des détails et de l’archive.

Parmi les identifiants canoniques actuellement publiés figurent :

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

agentsmd et portytail sont seulement des alias courants, pas des identifiants de tâche du protocole.

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # nécessaire uniquement si un répertoire de commandes est fourni
  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

manifest.json, frontend/panel.json, backend/task-preset.json, backend/prompts.json, les fichiers de locale anglais et chinois, les deux pages de boutique ainsi que les modèles de prompts pour chaque langue déclarée sont obligatoires. N’ajoutez commands.json que si le paquet fournit réellement un répertoire de commandes.

Influence des fichiers sur le catalogue

Fichier source	Résultat publié
`version` dans `manifest.json`	Version dans le catalogue et les détails
`owner` dans `manifest.json`	Éditeur
`localization` dans `manifest.json`	Ensemble de traductions chargé par le client
`requirements` dans `backend/task-preset.json`	Exigences de la tâche et informations de compatibilité dérivées
`title` / `summary` de la page de boutique	Nom, résumé et description multilingues
`catalog` / `tags` de la page de boutique anglaise	Catégorie et étiquettes

Si la page anglaise n’a pas de champ catalog, la catégorie utilise d’abord la première étiquette, puis General. Seuls les champs catalog et tags de la page anglaise participent à la génération des catégories et des étiquettes du catalogue.

3. Référencer le schéma et renseigner les ressources

Conservez dans chaque fichier JSON le champ $schema approprié, avec l’URL publique du schéma :

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

La correspondance entre fichiers et schémas est définie dans hagitask/schemas/task-preset-plugin/. manifest.json doit déclarer l’identifiant de tâche, la version, l’éditeur, l’ensemble de traductions ainsi que les chemins des ressources frontend et backend. Les fichiers de locale doivent contenir le même ensemble de clés.

store-page/index.en-US.md et index.zh-CN.md nécessitent au minimum les champs frontmatter locale, slug, title et summary. Placez catalog et tags sur la page anglaise, car le site de publication en dérive les catégories et les étiquettes.

4. Versionner et valider

À chaque modification d’un contenu déjà publié, mettez à jour la valeur version de manifest.json selon les règles du versionnement sémantique. Ne réutilisez pas un ancien numéro de version : les métadonnées du catalogue et l’empreinte du paquet deviendraient ambiguës.

Lancez la validation existante :

npm run validate

Le validateur contrôle les identifiants canoniques, le schéma, les déclarations des ressources, la couverture des traductions, les modèles de prompts et le frontmatter des pages de boutique. En cas d’échec, corrigez les fichiers sources dans data/<taskId>/ ; ne modifiez ni /index.json, ni /tasks/<taskId>.json, ni /packages/<taskId>.zip. Ces artefacts sont générés par HagiTask Site à chaque publication.

Le workflow de validation s’exécute sur les pull requests qui modifient le contenu des paquets et sur les pushs vers main. Un échec de validation empêche la fusion du paquet.

Pour vérifier plus avant le contrat de publication, vous pouvez exécuter ces commandes dans le checkout hagitask-site :

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

La construction du site normalise à nouveau les données et vérifie les schémas de publication. Si elle réussit, le catalogue et les détails générés respectent les contrats community-index-v1 et community-task-detail-v1.

5. Soumettre une pull request

Soumettez la pull request à hagitask-community-packages, et non à hagitask-site ni à hagitask. Après la fusion, HagiTask Site met à jour le commit précis de Community Packages qu’il utilise et régénère le catalogue, les détails et les archives ZIP.

hagitask est responsable du schéma partagé et des préréglages intégrés. Si le contrat du format des paquets doit changer, proposez séparément une modification du schéma dans le dépôt HagiTask. Community Packages ne maintient que les données sources sous data/ ; le site ne publie que les résultats générés.

En cas d’échec de la validation

Corrigez les fichiers sources de data/<taskId>/ indiqués par l’erreur :

Erreur de schéma du paquet : corrigez le fichier JSON concerné ; ne supprimez pas $schema et n’assouplissez pas la validation.
Ressource ou locale manquante : mettez à jour le manifeste, les fichiers de locale, les modèles de prompts ou les pages de boutique pour que les déclarations correspondent aux fichiers réels.
Erreur de schéma des détails du catalogue ou de l’archive : vérifiez le paquet source et les données fournies à la normalisation du site, sans retoucher le JSON généré.

Si le problème concerne le contrat du schéma lui-même, proposez une modification de ce contrat dans le dépôt HagiTask au lieu de dupliquer le schéma dans ce dépôt.

Étape suivante : Installer HagiTask ou Utiliser HagiTask.