Como contribuir com a comunidade HagiTask

Para quem é este guia: Colaboradores e mantenedores de tarefas da comunidade HagiTask.

Pré-requisitos:

Ter clonado hagitask-community-packages e ter Node.js/npm disponíveis.
Poder inicializar o checkout aninhado de hagitask desse repositório.
Conhecer JSON, Markdown e Pull Requests do Git.

Esta página contém o fluxo completo para colaboradores. O README do Community Packages apresenta apenas os limites de responsabilidade do repositório e referências de diretórios e comandos.

Responsabilidades dos repositórios e fluxo de publicação

O Community Packages é a fonte de referência das definições de tarefas da comunidade. Colaboradores editam data/<taskId>/; o HagiTask mantém o Schema compartilhado dos pacotes; o HagiTask Site lê um commit específico do Community Packages, normaliza o conteúdo e gera:

/index.json: catálogo compacto para descoberta de tarefas.
/tasks/<taskId>.json: documento de detalhes com todos os recursos e informações de compatibilidade.
/packages/<taskId>.zip: arquivo usado pelo aplicativo para instalar a tarefa.

Esses arquivos JSON e ZIP são gerados; não os crie nem modifique manualmente no Community Packages. O arquivo inclui todo o diretório data/<taskId>/, portanto novos recursos adicionados a ele também são publicados com o pacote.

1. Preparar o Schema e o repositório

No repositório Community Packages, execute:

git submodule update --init --recursive
npm install

A fonte oficial do Schema compartilhado dos pacotes é repos/hagitask/schemas/task-preset-plugin/; o Community Packages o utiliza por meio do checkout aninhado. Não copie nem modifique o Schema no Community Packages ou no HagiTask Site.

2. Criar um pacote de tarefas

Coloque a nova tarefa em data/<taskId>/. O taskId deve ser estável, único, em letras minúsculas e no formato kebab-case; ele deve sempre corresponder exatamente ao taskPresetId em manifest.json. Renomear o diretório altera as URLs publicadas dos detalhes e do arquivo.

Os IDs canônicos atualmente publicados incluem:

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

agentsmd e portytail são apenas apelidos legíveis, não IDs de tarefas do protocolo.

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # necessário apenas se houver um catálogo 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

São obrigatórios manifest.json, frontend/panel.json, backend/task-preset.json, backend/prompts.json, os arquivos de locale em inglês e chinês, as duas páginas da loja e os modelos de prompt para cada idioma declarado. Inclua commands.json somente se o pacote realmente oferecer um catálogo de comandos.

Como os arquivos afetam o catálogo

Arquivo de origem	Resultado publicado
`version` em `manifest.json`	Versão no catálogo e nos detalhes
`owner` em `manifest.json`	Publicador
`localization` em `manifest.json`	Bundle de locale carregado pelo cliente
`requirements` em `backend/task-preset.json`	Requisitos da tarefa e informações de compatibilidade derivadas
`title` / `summary` da página da loja	Nome, resumo e descrição em vários idiomas
`catalog` / `tags` da página da loja em inglês	Categoria e tags

Se a página em inglês não tiver catalog, a categoria passa a ser a primeira tag ou, na ausência de tags, General. Apenas catalog e tags da página em inglês são usados para gerar a classificação do catálogo.

3. Referenciar o Schema e preencher os recursos

Mantenha o $schema correspondente em cada arquivo JSON, usando a URL pública do Schema:

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

Consulte hagitask/schemas/task-preset-plugin/ para saber qual Schema corresponde a cada arquivo. O manifest.json deve declarar o ID da tarefa, a versão, o publicador, o bundle de localização e os caminhos dos recursos de frontend e backend. Os arquivos de locale devem conter o mesmo conjunto de chaves.

store-page/index.en-US.md e index.zh-CN.md precisam conter, no mínimo, locale, slug, title e summary no frontmatter. Coloque catalog e tags na página em inglês, pois o site de publicação usa essa página para gerar as categorias e tags.

4. Versionar e validar

Sempre que o conteúdo publicado mudar, atualize a version em manifest.json conforme o versionamento semântico. Não reutilize uma versão antiga: isso criaria ambiguidade entre os metadados do catálogo e o resumo do pacote.

Execute a validação existente:

npm run validate

O validador verifica o ID canônico, o Schema, as declarações de recursos, a cobertura de localização, os modelos de prompt e o frontmatter das páginas da loja. Se houver falhas, corrija os arquivos de origem em data/<taskId>/, não /index.json, /tasks/<taskId>.json ou /packages/<taskId>.zip: estes são artefatos gerados a cada publicação pelo HagiTask Site.

O fluxo de validação é executado em Pull Requests que alteram o conteúdo de pacotes e em pushes para main; uma falha impede a integração do pacote.

Para conferir também o contrato de publicação, execute no checkout de hagitask-site:

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

A compilação do site executa novamente a normalização e valida o Schema de publicação. Uma compilação bem-sucedida indica que o catálogo e os detalhes gerados atendem aos contratos community-index-v1 e community-task-detail-v1.

5. Enviar um Pull Request

Envie o Pull Request para hagitask-community-packages, não para hagitask-site ou hagitask. Após a integração, o HagiTask Site atualiza a referência ao commit específico do Community Packages e gera novamente o índice, os detalhes e os arquivos ZIP.

O hagitask é responsável pelo Schema compartilhado e pelas predefinições integradas. Se o próprio contrato do formato dos pacotes precisar mudar, proponha uma alteração de Schema separadamente no repositório HagiTask. O Community Packages mantém apenas os dados de origem em data/, e o site publica apenas os resultados gerados.

Se a validação falhar

Corrija os arquivos de origem em data/<taskId>/ indicados pelo erro:

Erro no Schema do pacote: corrija o JSON correspondente; não remova $schema nem enfraqueça a validação.
Recurso ou locale ausente: atualize o manifest, o locale, o modelo de prompt ou a página da loja para que as declarações correspondam aos arquivos reais.
Erro no Schema dos detalhes do catálogo ou do arquivo: confira o pacote de origem e a entrada de normalização do site; não remende o JSON gerado.

Se o problema estiver no próprio contrato do Schema, proponha a alteração no repositório HagiTask, em vez de copiar o Schema para este repositório.

Próximo passo: Como instalar o HagiTask ou Como usar o HagiTask.