fairladyz625/harness-anything/preset-creator

Preset Creator

Use the current contract

Treat packages/preset/src/preset.contract.ts as the contract and packages/preset/assets/software-coding/presets/standard-task/preset.json as the minimal bundled example. Presets are declaration-first packages. Keep preset-specific behavior in package assets or scripts; never add a CLI core branch keyed by preset id, title, or action name.

A self-contained package contains:

<preset-id>/
  preset.json
  PRESET.md
  policy.json       # only when policyPath declares it
  scripts/          # only when an entrypoint declares a script

PRESET.md uses this frontmatter:

---
schema: preset-document/v1
description: One sentence describing the supplied workflow or shape.
whenToUse: One sentence naming the triggering situation.
---

Manifest v3

Use schema: "preset-manifest/v3". Required top-level keys are exactly:

• schema, id, title, vertical, version, kind, and outputShape
• kernelVersionRange and capabilityImports
• profiles and defaultProfile

Optional top-level keys are extends, policyPath, entrypoints, and completion. No other top-level key is accepted. kind is template-content or process-action; outputShape is a required non-empty string.

Each profile requires id, title, completionGates, and templateSelections; it may add capabilityImports, closeoutOverrides, and archiveOnComplete. completionGates is an array of gate ids declared by the vertical or preset, including an explicit empty array when there are no gates. defaultProfile must name one declared profile. closeoutOverrides accepts boolean values for review, consent, fact, and factDisposition; archiveOnComplete is a boolean. These are task-creation choices, not a way to change an existing task's frozen profile.

The vertical owns domain-wide completion.sources, completion.gates, and completion.closeoutDefaults. A preset may declare additional completion sources or gates in its top-level completion object. The runtime merges both declarations and rejects duplicate source ids, duplicate gate ids, invalid references, and profile selections that do not resolve. Keep the shared domain contract in the vertical and use profiles only to select gate ids.

Each template selection is exactly:

{
  "slot": "task.plan",
  "templateRef": "template://planning/task-plan@1",
  "materializeAs": "task_plan.md",
  "localePolicy": { "prefer": "project", "fallback": "en-US" }
}

localePolicy.prefer is project, preset, or explicit; fallback is zh-CN or en-US.

Top-level capabilityImports items require id, kind, version, and a boolean required. Profile and entrypoint capability items use id, kind, and version, with an optional boolean required. Valid kinds are checker, scaffold, projection, command, template, and raw-fs.

Minimal valid package

Use this manifest shape:

{
  "schema": "preset-manifest/v3",
  "id": "example-note",
  "title": "Example Note",
  "vertical": "software/coding",
  "version": "1.0.0",
  "kind": "template-content",
  "outputShape": "repository-diff",
  "kernelVersionRange": { "min": "1.0.0", "maxExclusive": "2.0.0" },
  "capabilityImports": [],
  "profiles": [
    {
      "id": "baseline",
      "title": "Baseline",
      "completionGates": ["ci"],
      "templateSelections": []
    }
  ],
  "defaultProfile": "baseline"
}

Validate the package directory, not an individual manifest file:

ha preset validate --source /path/to/example-note --json

Continue only when the report has "valid": true and an empty issues array.

Select a declared completion gate

A profile selects gate ids; it does not repeat source schemas or gate contracts:

{
  "id": "experiment",
  "title": "Experiment",
  "completionGates": ["version-pinned"],
  "templateSelections": []
}

The selected id must exist in the merged vertical and preset declarations. For a full CSV, PNG, and experiment.json example—including a command entrypoint, a required seed, artifact binding, task submit, rejection, and repair—follow gate-customization. Completion gates govern task completion; use the repository's separate delivery pre-review gate when preparing a submission for review.

Script entrypoints

A v3 entrypoint is a named object with exactly these fields:

{
  "type": "script",
  "intent": "Produce a bounded preset result.",
  "inputs": [
    { "name": "title", "type": "string", "required": true }
  ],
  "requires": [
    { "id": "capability:input/v1", "kind": "command", "version": "1" }
  ],
  "produces": [
    { "id": "capability:result/v1", "kind": "projection", "version": "1" }
  ],
  "sideEffects": [],
  "command": "scripts/run.mjs"
}

Input types are string, number, boolean, or json. intent is a plain string. requires, produces, and sideEffects are flat capability-ref arrays. The command path must name a regular package-local file. Ordinary entrypoints receive their declared context through HARNESS_PRESET_CONTEXT. A command completion source names an entrypoint as <preset-id>/<entrypoint-id>, declares the completion-witness checker capability in both capabilityImports and produces, and reads the frozen witness input through HA_PRESET_INPUT. The script cannot choose its task, execution, source identity, or accepted artifact set.

Migrating v2 packages

Do not relabel a v2 object and leave its fields in place. Apply these mappings:

• Add the required top-level outputShape when absent.
• Keep profile ids, titles, string completion-gate ids, and valid current

template selections.

• Convert script inputs from an object/map to the v3 array of

{name,type,required} only when the types and requiredness are explicit.

• Convert a structured/object intent to one plain string only when its exact

user-visible meaning is present.

• Replace nested capability selectors with flat requires, produces, and

sideEffects refs only when current providers are explicitly known.

• Discard v2 raw-filesystem reads and writes path-glob fields. They have no

v3 manifest counterpart. A raw-fs capability ref names a provider; it does not restore those old path scopes.

• Remove any entrypoint whose authority or input meaning cannot be expressed

without guessing. Preserve its user-visible procedure in PRESET.md and report the removed behavior to the owner.

• Delete all unknown v2 keys. Validation is exact-field and fails closed.

Template assets

Preset manifests select templates; the vertical template catalog owns template metadata and Markdown assets own bodies. Use template://<id>@<version> references. Do not inline template bodies in the manifest. Run ha template list to discover current builtin declarations and validate that every selected slot, path, locale policy, and required anchor resolves.

Workflow

1. State the preset job in one sentence and choose template-content or

process-action.

1. Read the v3 contract and a nearby bundled manifest; do not copy a v2 schema.
2. Create preset.json and PRESET.md, then add only declared completion,

policy, template, or script files.

1. Run ha preset validate --source <package-directory> --json.
2. Run ha preset install --source <package-directory> --dry-run --json before

installation and inspect its issues.

1. Run ha vertical validate --source <vertical-directory> --preset <installed-preset-id>

to check the combined completion catalog.

1. Add resolver, materialization, permission, or execution tests at the tier

matching the behavior. Put exactly one // harness-test-tier: declaration on the first line of every new Node test file.

Review checklist

• The schema is preset-manifest/v3; outputShape is present.
• Top-level, profile, selection, capability, input, and entrypoint fields are

exact current-contract fields.

• profiles is non-empty and defaultProfile resolves.
• Every selected gate id resolves in the merged vertical/preset declaration;

template selections use the current nested locale policy.

• Command sources point at an installed entrypoint that declares the

completion-witness checker capability.

• No v2 reads, writes, object input/intent, or nested capability selector

survives.

• PRESET.md has valid preset-document/v1 frontmatter.
• Package validation reports valid with no issues.
• No preset-specific behavior was added to generic CLI dispatch.