Agent Skill · cast

validate-galaxy-workflow

Run terminal gxwf validation on an assembled Galaxy workflow and classify workflow-level failures.

Install with Claude Code

/plugin marketplace add galaxyproject/foundry
/plugin install foundry-skills@galaxy-workflow-foundry

Then invoke as:

/foundry-skills:validate-galaxy-workflow

Install with Codex

codex plugin marketplace add galaxyproject/foundry
codex plugin add foundry-skills@galaxy-workflow-foundry

Then select with /skills or invoke explicitly as:

$validate-galaxy-workflow

Install with Antigravity

git clone https://github.com/galaxyproject/foundry
agy plugin install foundry/casts/claude

Then select with /skills or invoke explicitly as:

/validate-galaxy-workflow

Skill Bundle

/ packaged cast

attached files: 3
upfront: 0
on demand: 3
cast rev: n/a
validated: 0

Produces: 1 artifact.

Artifact Contract

/ skill handoff

Produces

galaxy-workflow-validation-result

Terminal gxwf validation handoff: the exact command run, a pass/fail/not-run status, the classified workflow-level diagnostics, and the residual runtime risks static validation cannot settle.

jsongalaxy-workflow-validation-result.json

Raw artifact contract

{
  "id": "galaxy-workflow-validation-result",
  "kind": "json",
  "default_filename": "galaxy-workflow-validation-result.json",
  "description": "Terminal gxwf validation handoff: the exact command run, a pass/fail/not-run status, the classified workflow-level diagnostics, and the residual runtime risks static validation cannot settle."
}

Attached Files

/ runtime references

Load on demand

cli-command

gxwf validate

packaged

Validate the assembled gxformat2 workflow before runtime testing.

Trigger: After all Galaxy steps and workflow tests have been assembled.

on-demand runtime sidecar hypothesis deterministic 5.5 KB

bundle: references/cli/validate.json
source: content/cli/gxwf/validate.md

Preview json

{
  "type": "cli-command",
  "tool": "gxwf",
  "command": "validate",
  "summary": "Validate Galaxy workflow structure, tool state, and optional connection compatibility before runtime execution.",
  "source_path": "content/cli/gxwf/validate.md",
  "source_revision": 3,
  "package": "@galaxy-tool-util/cli",
  "description": "Validate Galaxy workflow files (structure + optional tool state)",
  "synopsis": "gxwf validate [options] <file>",
  "args": [
    {
      "raw": "file",
      "name": "file",
      "required": true,
      "variadic": false,
      "description": "Workflow file (.ga, .gxwf.yml)"
    }
  ],
  "options": [
    {
      "flags": "--format <fmt>",
      "name": "format",
      "description": "Force format: native or format2 (auto-detected by default)",
      "takesArgument": true,
      "argumentPlaceholder": "<fmt>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--no-tool-state",
      "name": "toolState",
      "description": "Skip tool state validation",
      "takesArgument": false,
      "optionalArgument": false,
      "negatable": true
    },
    {
      "flags": "--cache-dir <dir>",
      "name": "cacheDir",
      "description": "Tool cache directory",
      "takesArgument": true,
      "argumentPlaceholder": "<dir>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--offline",
      "name": "offline",
      "description": "Do not fetch uncached tools; read only the local cache (uncached tools are skipped)",
      "takesArgument": false,
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--galaxy-url <url>",
      "name": "galaxyUrl",
      "description": "Galaxy instance to try as a tool source after the ToolShed when fetching uncached tools",
      "takesArgument": true,
      "argumentPlaceholder": "<url>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--mode <mode>",
      "name": "mode",
      "description": "Validation backend: effect (default) or json-schema",
      "takesArgument": true,
      "argumentPlaceholder": "<mode>",
      "optionalArgument": false,
      "negatable": false,
      "defaultValue": "effect"
    },
    {
      "flags": "--tool-schema-dir <dir>",
      "name": "toolSchemaDir",
      "description": "Directory of pre-exported per-tool JSON Schemas (for of
...

research

galaxy-workflow-invocation-failure-reference

packaged

Keep static workflow validation findings distinct from Galaxy invocation/runtime failure surfaces.

Trigger: When a workflow passes gxwf validation but still has likely runtime risks around invocation scheduling, outputs, conditionals, or collection population.

on-demand runtime verbatim corpus-observed deterministic 7.6 KB

bundle: references/notes/galaxy-workflow-invocation-failure-reference.md
source: content/research/galaxy-workflow-invocation-failure-reference/index.md

Preview md

---
type: research
title: "Galaxy workflow invocation failure reference"
tags:
  - target/galaxy
status: draft
created: 2026-05-02
revised: 2026-05-02
revision: 1
related_notes:
  - "[[galaxy-tool-job-failure-reference]]"
  - "[[planemo-workflow-test-architecture]]"
  - "[[galaxy-collection-semantics]]"
related_molds:
  - "[[run-workflow-test]]"
  - "[[debug-galaxy-workflow-output]]"
  - "[[validate-galaxy-workflow]]"
sources:
  - "~/projects/repositories/galaxy/lib/galaxy/schema/invocation.py"
  - "~/projects/repositories/galaxy/lib/galaxy/workflow/run.py"
  - "~/projects/repositories/galaxy/lib/galaxy/workflow/modules.py"
  - "~/projects/repositories/galaxy/lib/galaxy/webapps/galaxy/api/workflows.py"
summary: "Reference for Galaxy workflow invocation states, messages, failure reasons, and invocation API surfaces."
---

# Galaxy Workflow Invocation Failure Reference

This note describes workflow-level failure surfaces in Galaxy. It is separate from [[galaxy-tool-job-failure-reference]] because invocation state answers whether Galaxy could schedule and drive the workflow, while job state answers whether individual tool jobs succeeded.

## Invocation Versus Job Failure

Important distinction:

- Invocation state says whether Galaxy scheduled, cancelled, failed, or completed the workflow invocation.
- Job state says whether jobs produced by invocation steps succeeded or failed.
- Invocation messages explain scheduler/evaluation/cancellation problems.
- Step states usually describe scheduling progress, not actual job success, unless a legacy serialization mode substitutes job state.

A robust workflow test reference should inspect both invocation APIs and job APIs.

## Invocation States

Galaxy invocation states are defined in `~/projects/repositories/galaxy/lib/galaxy/sch
...

research

galaxy-workflow-testability-design

packaged

Classify validation or pre-test findings that indicate missing labels, omitted workflow outputs, or untestable checkpoint structure.

Trigger: When terminal validation passes but workflow-level outputs, labels, or collection shapes look likely to break future workflow tests.

on-demand runtime verbatim corpus-observed deterministic 7.8 KB

bundle: references/notes/galaxy-workflow-testability-design.md
source: content/research/galaxy-workflow-testability-design/index.md

Preview md

---
type: research
tags:
  - target/galaxy
status: draft
created: 2026-05-03
revised: 2026-09-23
revision: 3
related_notes:
  - "[[iwc-workflow-testability-survey]]"
  - "[[iwc-test-data-conventions]]"
  - "[[planemo-asserts-idioms]]"
  - "[[iwc-shortcuts-anti-patterns]]"
  - "[[planemo-workflow-test-architecture]]"
  - "[[implement-galaxy-workflow-test]]"
  - "[[gxformat2-schema]]"
  - "[[gxformat2-workflow-inputs]]"
  - "[[galaxy-datatypes-conf]]"
summary: "Design guidance for Galaxy workflow inputs, outputs, and checkpoints that make IWC-style workflow tests possible."
---

# Design a Galaxy workflow that can be tested

Choose the workflow's public inputs and outputs while designing the analysis, before writing its `-tests.yml`. A workflow test supplies `job:` values by input name and checks `outputs:` by output name. It can only check results the workflow exposes. A good interface gives the test a reproducible input, an addressable result, and at least one assertion that would catch a meaningful wrong result.

This note concerns workflow design. [[iwc-test-data-conventions]] covers the test file's input fixtures, [[planemo-asserts-idioms]] covers assertion syntax, and [[iwc-shortcuts-anti-patterns]] explains when a smoke check is enough. [[iwc-workflow-testability-survey]] holds the broader corpus evidence.

## Name the public interface before writing tests

Give each input and promoted output a stable, descriptive public name. In an exported gxformat2 workflow this is commonly the entry's `id`. The structural [[gxformat2-schema]] also permits `label`. Check the **effective name in the workflow being tested** instead of assuming a step label, generated dataset name, or array position will become the test key. In the pinned [Scanpy workflow](https://github.com/galaxy
...

SKILL.md


# validate-galaxy-workflow

Follow the procedure below and use the artifact/reference sections as the runtime contract.

## When To Use

- Run terminal gxwf validation on an assembled Galaxy workflow and classify workflow-level failures.

## Inputs

- No upstream artifact inputs declared. See the procedure for user-supplied runtime inputs.

## Outputs

- Write artifact `galaxy-workflow-validation-result` as `galaxy-workflow-validation-result.json`. Format: `json`. Terminal gxwf validation handoff: the exact command run, a pass/fail/not-run status, the classified workflow-level diagnostics, and the residual runtime risks static validation cannot settle.

## Required Tools

- **`gxwf`** (gxwf). `npm install -g '@galaxy-tool-util/cli@^1.8.1'`.
  Ephemeral run: `npx --yes --package @galaxy-tool-util/cli@1.8.1 gxwf`.
  Check: `gxwf --help | grep -q draft-validate`.
  Docs: https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli

## Load Upfront

- None declared.

## Load On Demand

- `references/cli/validate.json`: CLI command reference packaged as a sidecar. Validate the assembled gxformat2 workflow before runtime testing. Use when: after all Galaxy steps and workflow tests have been assembled.
- `references/notes/galaxy-workflow-invocation-failure-reference.md`: Research note copied verbatim into the bundle. Keep static workflow validation findings distinct from Galaxy invocation/runtime failure surfaces. Use when: a workflow passes gxwf validation but still has likely runtime risks around invocation scheduling, outputs, conditionals, or collection population.
- `references/notes/galaxy-workflow-testability-design.md`: Research note copied verbatim into the bundle. Classify validation or pre-test findings that indicate missing labels, omitted workflow outputs, or untestable checkpoint structure. Use when: terminal validation passes but workflow-level outputs, labels, or collection shapes look likely to break future workflow tests.

## Validation

- None declared.

## Procedure

Validate the assembled Galaxy workflow before runtime testing. The skill owns the terminal validation pass: run gxwf validate, classify workflow-level diagnostics, and route failures back to the responsible authoring phase when possible.

This is separate from advance-galaxy-draft-step (which runs `gxwf draft-validate --concrete` inside the per-step loop) because terminal validation no longer has only one fresh step in scope and should reason over cross-step workflow structure.

### Emit the result

Write `galaxy-workflow-validation-result.json` on every run — clean or failing — so a downstream reviewer can cite what was actually checked rather than re-deriving it:

- `command` — the exact gxwf validate invocation, including flags (prefer `--json`);
- `workflow_path` — the file validated;
- `status` — `pass`, `fail`, or `not-run`, with a `not_run_reason` whenever validation could not execute;
- `diagnostics[]` — one entry per finding: severity, message, the step or field it addresses, and the authoring phase it routes back to;
- `residual_runtime_risks[]` — for a clean run, the risks static validation cannot settle and the runtime artifact that would prove or disprove each.

A `not-run` status is never reported as a pass.

## Feedback Mode

- Feedback mode is off unless the caller explicitly enables `--feedback` or supplies a feedback-ledger path.
- When enabled, read `_feedback.md` before doing the work and use its registered `foundry-feedback.ledger.yml` protocol.
- Preserve harness-owned run and phase state. Append only concrete observations about a canonical Foundry source asset or a related project that this run showed to be at fault; do not put ordinary workflow requirements in this ledger.
- Before reporting completion, make one explicit pass over the work you just did. Do not ask yourself whether anything was unclear — recall what happened: where you guessed at something the instructions should have settled, needed information this bundle does not carry, hit an instruction that contradicted another or contradicted the artifacts in front of you, used a packaged reference that did not cover your case, or did something the procedure never describes.
- Append an entry for each such event that clears the protocol's bar. If none do, append nothing and report `no feedback` explicitly. Silence and a clean pass are not the same thing, and nothing downstream can tell them apart unless you say which one it was.
- Pass the same ledger path to any subagent used for this work, and merge updates serially so one writer cannot overwrite another.

## Runtime Notes

- Do not read Foundry source files at runtime; use only files packaged in this skill bundle and user-supplied artifacts.
- Preserve declared artifact filenames unless the user or harness supplies explicit paths.
- Carry unresolved assumptions into the output artifact instead of silently inventing missing source evidence.