Contributing HagiTask community packages

Who this is for: HagiTask community task contributors and maintainers.

Prerequisites:

You have cloned hagitask-community-packages and have Node.js/npm available.
You can initialize that repository’s nested hagitask checkout.
You understand JSON, Markdown, and Git Pull Requests.

This page is the complete procedural entry point for contributors. The Community Packages README only covers repository boundaries, layout, and command reference.

Repository boundaries and publishing flow

Community Packages is the source of truth for community task definitions. Contributors edit data/<taskId>/; HagiTask maintains the shared package Schema; HagiTask Site reads an exact Community Packages commit, normalizes it, and generates:

/index.json: a lightweight catalog for task discovery.
/tasks/<taskId>.json: a detail document with complete resources and compatibility information.
/packages/<taskId>.zip: an archive for application installation.

These JSON and ZIP files are generated outputs. Do not create or edit them manually in Community Packages. The archive includes the entire data/<taskId>/ directory, so new resources in that directory are shipped with the package.

1. Prepare the Schema and repository

Run this in the Community Packages repository:

git submodule update --init --recursive
npm install

The authoritative shared package Schema is at repos/hagitask/schemas/task-preset-plugin/. Community Packages accesses it through a nested checkout. Do not copy or modify the Schema in Community Packages or HagiTask Site.

2. Create a task package

Put new tasks in data/<taskId>/. The taskId must be stable, unique, and lowercase kebab-case, and must exactly match taskPresetId in manifest.json. Renaming the directory changes the published detail and archive URLs.

Current published canonical IDs include:

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

agentsmd and portytail are human-facing aliases, not protocol task IDs.

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # Only when there is a command catalog
  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, the English and Chinese locale files, both store pages, and prompt templates for every declared language are required. Include commands.json only when the package actually provides a command catalog.

How files affect the catalog

Source file	Published result
`manifest.json` `version`	Version in the catalog and details
`manifest.json` `owner`	Publisher
`manifest.json` `localization`	Locale bundle loaded by the client
`backend/task-preset.json` `requirements`	Task requirements and derived compatibility information
Store page `title` / `summary`	Localized name, summary, and description
English store page `catalog` / `tags`	Category and tags

If the English page has no catalog, the category falls back to the first tag, then to General. Only catalog and tags from the English page are used to generate catalog categories.

3. Reference the Schema and fill in resources

Keep the corresponding $schema in every JSON file, using the public Schema URL:

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

Check hagitask/schemas/task-preset-plugin/ for the mapping between files and Schemas. manifest.json declares the task ID, version, publisher, localization bundles, and frontend/backend resource paths. Locale files must have the same set of keys.

store-page/index.en-US.md and index.zh-CN.md need at least locale, slug, title, and summary in their frontmatter. Put catalog and tags in the English page because the publishing site derives categories and tags from it.

4. Version and validate

Every change to published content must update the version in manifest.json according to semantic versioning. Do not reuse an old version number: doing so makes catalog metadata and package digests ambiguous.

Run the existing validator:

npm run validate

It checks canonical IDs, Schema, resource declarations, localization coverage, prompt templates, and store-page frontmatter. If it fails, fix the source files in data/<taskId>/, not /index.json, /tasks/<taskId>.json, or /packages/<taskId>.zip: those are generated on every HagiTask Site release.

Validation runs on Pull Requests that change package content and on pushes to main; failed validation blocks a merge.

To further verify the publishing contract, run this in the hagitask-site checkout:

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

A site build rechecks normalization and the published Schema. A successful build means the generated catalog and details conform to the community-index-v1 and community-task-detail-v1 contracts.

5. Submit a Pull Request

Open the Pull Request against hagitask-community-packages, not hagitask-site or hagitask. After it is merged, HagiTask Site updates to the exact Community Packages commit and regenerates the index, details, and ZIP archives.

hagitask owns the shared Schema and built-in presets. Propose changes to the package format contract separately in the HagiTask repository. Community Packages owns only the data/ sources; the site publishes only generated output.

If validation fails

Fix the source file in data/<taskId>/ indicated by the error:

Package Schema error: fix the relevant JSON; do not remove $schema or weaken validation.
Missing resource or locale: update the manifest, locale, prompt template, or store page so declarations match actual files.
Catalog detail or archive Schema error: inspect the source package and the site’s normalization input; do not patch generated JSON.

If the Schema contract itself is wrong, propose a contract change in the HagiTask repository rather than copying a Schema into this repository.

Next step: Install HagiTask or use HagiTask.