workflow-authoring

Workflow authoring (Harn workflow bundles)

You are authoring a portable workflow bundle — a JSON file Harn validates, previews, and runs locally. Hosts (IDE TUI/GUI, cloud-platform importers) consume the same bundle without rewriting.

Read prompting.md in this directory before composing a response. It defines the response sections, JSON envelope, and small-model rules. Every recipe under recipes/ is a worked, validated example you can crib from.

What good output looks like

1. A single <bundle> block containing valid JSON for a WorkflowBundle.

2. A short <rationale> block (≤ 5 bullets) explaining the trigger, the waitpoints, and the connector requirements.

3. A <verify> block listing the exact commands the user should run:

   harn workflow validate --bundle out.bundle.json --json
   harn workflow preview  --bundle out.bundle.json --json
   harn workflow run      --bundle out.bundle.json --json
   

If validation fails, read the diagnostic, edit the bundle, and re-validate. Do not invent fields or kinds — the validator's enum lists are the source of truth.

Bundle skeleton

{
  "schema_version": 2,
  "entrypoint": "workflows/<kebab-case-id>.harn",
  "transitive_modules": [
    {
      "path": "workflows/<kebab-case-id>.harn",
      "source_hash_blake3": "blake3:<64 lowercase hex digits>",
      "harnbc_hash_blake3": "blake3:<64 lowercase hex digits>"
    }
  ],
  "stdlib_version": "<harn stdlib version>",
  "harn_version": "<harn version>",
  "provider_catalog_hash": "blake3:<64 lowercase hex digits>",
  "tool_manifest": [],
  "sbom": {
    "format": "spdx-lite",
    "version": "2.3",
    "packages": [],
    "relationships": []
  },
  "signature": null,
  "parent_trust_record_id": null,
  "id": "<kebab-case-id>",
  "name": "<human label>",
  "version": "1.0.0",
  "triggers": [
    { "id": "<trigger-id>", "kind": "github|cron|delay|webhook|mcp|manual",
      "provider": "github", "events": ["pull_request.opened"],
      "node_id": "<entry-node-id>" }
  ],
  "workflow": {
    "_type": "workflow_graph",
    "id": "<graph-id>",
    "version": 1,
    "entry": "<entry-node-id>",
    "nodes": {
      "<node-id>": { "id": "<node-id>", "kind": "action|waitpoint|notification",
                     "task_label": "<short label>" }
    },
    "edges": [ { "from": "<from-node-id>", "to": "<to-node-id>" } ]
  },
  "prompt_capsules": {
    "<capsule-id>": { "id": "<capsule-id>", "node_id": "<node-id>",
                      "trigger_id": "<trigger-id>",
                      "prompt": "<self-contained continuation prompt>" }
  },
  "policy": {
    "autonomy_tier": "shadow|suggest|act_with_approval|act_auto",
    "retry":   { "max_attempts": 2, "backoff": "exponential" },
    "catchup": { "mode": "none|latest|all", "max_events": 1 }
  },
  "connectors": [
    { "id": "github", "provider_id": "github",
      "scopes": ["pull_requests:read", "checks:read"],
      "setup_required": true, "status_required": true }
  ],
  "environment": {
    "repo_setup_profile": "default",
    "worktree_policy": "reuse_current|new_worktree|host_managed",
    "command_gates": ["make test"]
  }
}