gh-workflow-run-headless

name	gh-workflow-run-headless
description	Run a v2 workflow non-interactively under its headless policy. ASKs are recorded, withheld mutations become proposed_actions, notable items become typed findings; writes workflow-run-result.yaml (kind: workflow-run). Zero prompts; explicit inputs only. Use when: a scheduler runs a workflow unattended, an orchestrator needs a workflow's findings as data. Trigger phrases: "headless workflow run", "run workflow headless", "scheduled workflow".
inputs	{"workspace_path":"required — absolute path to the workspace root (directory containing .hiivmind/github/)","workflow":"required — workflow name; resolved to {workspace_path}/.hiivmind/github/workflows/{workflow}.yaml","workflow_path":"optional — explicit YAML path, overriding name resolution (e.g. a repo-overlay workflow)","params":"optional — parameter values as a YAML/JSON map; params with default: null and no value here abort the run","repo":"optional — owner/name repo scope recorded in the result and passed to the executor context","result_path":"optional — default: {workspace_path}/.hiivmind/github/workflow-run-result.yaml","ignore_cooldown":"optional — skip the cooldown check (default: false)","mode":"optional — actor mode recorded in the result: interactive | scheduled (default: scheduled)"}
outputs	{"result_file":"workflow-run-result.yaml conforming to lib/patterns/headless-contract.md (kind: workflow-run)"}
author	hiivmind

Headless Workflow Run

Execute one v2 workflow with no user present. This skill is a thin caller: it builds the execution context and delegates to the executor (lib/patterns/workflow-execution.md — read the Headless Execution section in full before executing). The workflow definition is untouched — the same YAML serves interactive runs.

Path Convention

{PLUGIN_ROOT} = plugin root (where plugin.json lives).

Contract

• Zero prompts. Explicit inputs only (D4). Every exit writes a result file — including cooldown skips (outcome: skipped-cooldown) and aborts (outcome: aborted).
• The operation blocklist is absolute regardless of the workflow's on_mutation policy.

State

computed:
  CONFIG_DIR   = {workspace_path}/.hiivmind/github
  WF_PATH      = {workflow_path input, or CONFIG_DIR/workflows/{workflow}.yaml}
  RESULT_PATH  = {result_path input, or CONFIG_DIR/workflow-run-result.yaml}
  RUN_AT       = $(date -u +%Y-%m-%dT%H:%M:%SZ)
  LOGIN        = yq -r '.workspace.login' CONFIG_DIR/config.yaml
  GH_LOGIN     = $(gh api user --jq .login)   ("unknown" on failure, + errors[] entry)
  MACHINE      = $(hostname -s)
  MODE         = {mode input, default "scheduled"}
  RUN_ID       = {UTC date}-{GH_LOGIN}-{UTC HHMMSS}   e.g. 2026-07-10-octocat-093012
  OUTCOME      = success | failure | skipped-cooldown | aborted
  FINDINGS, PROPOSED_ACTIONS, ASKS_RECORDED, ERRORS = []   (accumulated by the executor)

Phase 1: VALIDATE

Outputs: loaded workflow, policy.

1. workspace_path or workflow missing → ABORT "missing required input: {name}".
2. CONFIG_DIR/config.yaml missing or lacking ^workspace: → ABORT "not a workspace root: {workspace_path}".
3. WF_PATH missing → ABORT "workflow not found: {WF_PATH}".
4. Load the YAML. No workflow: field (v1 or malformed) → ABORT "v1 workflows have no headless projection" / "invalid workflow YAML".
5. headless.enabled not true → ABORT "workflow not headless-enabled: {workflow}".
6. enabled: false on the workflow itself → ABORT "workflow disabled: {workflow}".
7. Resolve params: merge the input over the workflow's declared defaults. Any param left at → append its name to ASKS_RECORDED, ABORT (outcome: aborted — the contract's designed behavior for unanswerable required params).