Claude skill · cast

validate-galaxy-workflow

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

Install

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

Then invoke as:

/foundry-skills:validate-galaxy-workflow

Skill Bundle

/ packaged cast

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

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 4.9 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": "--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 offline json-schema mode)",
      "takesArgument": true,
      "argumentPlaceholder": "<dir>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--json",
      "name": "json",
      "description": "Output structured JSON report",
      "takesArgument": false,
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--report-html [file]",
      "name": "reportHtml",
      "description": "Write HTML report to file (or stdout if omitted)",
      "takesArgument": true,
      "argumentPlaceholder": "[file]",
  
...

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.7 KB

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

Preview md

---
type: research
subtype: component
title: "Galaxy workflow invocation failure reference"
tags:
  - research/component
  - target/galaxy
status: draft
created: 2026-05-02
revised: 2026-05-02
revision: 1
ai_generated: true
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 
...

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 11.4 KB

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

Preview md

---
type: research
subtype: component
tags:
  - research/component
  - target/galaxy
status: draft
created: 2026-05-03
revised: 2026-05-06
revision: 2
ai_generated: true
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."
---

# Galaxy workflow testability design

Use this note when authoring or translating a Galaxy workflow **before** the `-tests.yml` file exists. It covers workflow structure choices that make later IWC-style tests meaningful: labels, promoted checkpoints, collection identifiers, and fixture-compatible inputs.

This is not a `content/patterns/` page. It is cross-cutting design guidance for Molds that need testable Galaxy workflows. Assertion syntax lives in [[planemo-asserts-idioms]]. Test YAML fixture shapes live in [[iwc-test-data-conventions]]. Accepted shortcut vs smell calls live in [[iwc-shortcuts-anti-patterns]]. Corpus evidence trail lives in [[iwc-workflow-testability-survey]].

## 1. Treat labels as API

Workflow input and output labels are not cosmetic. Planemo and IWC tests address workflow inputs and outputs by label, and the survey found exact label matches for every asserted output across 114 matched workflow/test pairs. A generated workflow should therefore pick stable, descriptive labels before test authoring starts.

Rules:

- Label every output that may need a test assertion.
- Treat input/output renames as breaking changes
...

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

- None declared.

## 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.

## 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.