Map a CWL summary into a Galaxy workflow interface design brief.
/plugin marketplace add jmchilton/foundry
/plugin install foundry-skills@galaxy-workflow-foundryThen invoke as:
/foundry-skills:cwl-summary-to-galaxy-interfaceProduces: 1 artifact.
Consumes: 1 artifact.
Reviewable Markdown brief: Galaxy workflow inputs, outputs, labels, exposed and checkpoint outputs, source provenance, confidence.
{
"id": "cwl-galaxy-interface",
"kind": "markdown",
"default_filename": "cwl-galaxy-interface.md",
"description": "Reviewable Markdown brief: Galaxy workflow inputs, outputs, labels, exposed and checkpoint outputs, source provenance, confidence."
}Structured CWL summary emitted by [[summarize-cwl]]; the source-of-truth JSON for Galaxy interface choices.
{
"id": "summary-cwl",
"description": "Structured CWL summary emitted by [[summarize-cwl]]; the source-of-truth JSON for Galaxy interface choices.",
"inherited_schema": "[[summary-cwl]]",
"producers": [
"summarize-cwl"
]
}Keep source-faithful CWL facts separate from Galaxy-facing interface choices.
references/notes/component-cwl-workflow-anatomy.mdcontent/research/component-cwl-workflow-anatomy.md---
type: research
subtype: component
title: "CWL workflow anatomy"
tags:
- research/component
- source/cwl
status: draft
created: 2026-05-10
revised: 2026-05-10
revision: 1
ai_generated: true
related_notes:
- "[[summary-cwl]]"
- "[[cwl-v1.2-schemas]]"
- "[[galaxy-collection-semantics]]"
related_molds:
- "[[summarize-cwl]]"
- "[[cwl-summary-to-galaxy-interface]]"
- "[[cwl-summary-to-galaxy-data-flow]]"
- "[[cwl-summary-to-galaxy-template]]"
sources:
- "https://www.commonwl.org/v1.2/Workflow.html"
- "https://cwltool.readthedocs.io/en/stable/"
- "https://github.com/common-workflow-language/cwl-utils#normalize-a-cwl-document"
- "https://pypi.org/project/cwl-utils/"
- "https://github.com/common-workflow-language/cwldep"
summary: "CWL structure relevant to summarize-cwl: normalized documents, steps, scatter, conditionals, requirements, and dependency handling."
---
# CWL Workflow Anatomy
CWL is a structured workflow language, not a pipeline framework that must be inferred from ecosystem conventions. The `summarize-cwl` Mold should therefore start from CWL's own validated object model and avoid recreating the heavy Nextflow extraction stack.
## Normalization Posture
Use `cwltool --validate` as the first gate. If validation fails, the summary should emit provenance plus validation diagnostics and stop before producing downstream-looking graph claims.
Use `cwl-normalizer` from `cwl-utils` as the default normalization surface. The cwl-utils README describes it as producing JSON CWL documents with dependencies packed together, upgrading to CWL v1.2 as needed, and optionally refactoring CWL expressions into separate steps. This is the right handoff for `summarize-cwl`: structured enough for extraction, still source-faithful, and not a Galaxy design
...Read CWL workflow inputs, outputs, types, formats, secondary files, scatter, and requirement evidence before choosing the Galaxy interface.
references/schemas/summary-cwl.schema.jsonpackage://@galaxy-foundry/summary-cwl-schema#summaryCwlSchema{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://galaxyproject.org/foundry/schemas/summary-cwl.schema.json",
"$comment": "Canonical source: packages/summary-cwl-schema/src/summary-cwl.schema.json in jmchilton/foundry. Mold frontmatter cites this schema via [[summary-cwl]] wiki-links; the cast pipeline imports the `summaryCwlSchema` runtime export and serializes it into cast bundles.",
"title": "CWL Workflow Summary",
"description": "Structured per-source summary emitted by the summarize-cwl Mold. CWL is already a typed workflow language, so this schema records validated and normalized workflow/tool structure rather than inferred pipeline semantics.",
"type": "object",
"additionalProperties": false,
"required": [
"summary_version",
"source",
"documents",
"workflow_inputs",
"workflow_outputs",
"steps",
"tools",
"graph",
"tests",
"warnings"
],
"properties": {
"summary_version": {
"type": "string",
"enum": [
"1"
],
"description": "Summary schema major version."
},
"source": {
"$ref": "#/$defs/SourceRecord"
},
"documents": {
"$ref": "#/$defs/DocumentSet"
},
"workflow_inputs": {
"type": "array",
"items": {
"$ref": "#/$defs/WorkflowInput"
}
},
"workflow_outputs": {
"type": "array",
"items": {
"$ref": "#/$defs/WorkflowOutput"
}
},
"steps": {
"type": "array",
"items": {
"$ref": "#/$defs/WorkflowStep"
}
},
"tools": {
"type": "array",
"items": {
"$ref": "#/$defs/CommandLineTool"
}
},
"graph": {
"$ref": "#/$defs/WorkflowGraph"
},
"tests": {
"type": "array",
"items": {
"$ref": "#/$defs/TestCase"
}
},
"warnings": {
"type": "array",
"items": {
"$ref": "#/$defs/Warning"
}
}
},
"$defs": {
"SourceRecord": {
"type": "object",
"additionalProperties": false,
"required": [
"ecosystem",
"workflow",
"url",
"version",
"license",
"slug",
"cwl_version",
"entrypoint"
],
"properties": {
"ecosystem": {
"type": "string",
"enum": [
"cwl"
],
"description": "Source ecosy
...Pick among the three honest Galaxy branching translations (paired_or_unpaired input, native pick_value step, sibling workflows) before drafting the interface.
Trigger: When summary-cwl has any steps[].when non-null OR any workflow output uses pickValue.
references/notes/cwl-when-pickvalue-to-galaxy-branching.mdcontent/research/cwl-when-pickvalue-to-galaxy-branching.md---
type: research
subtype: design-spec
title: "CWL when:/pickValue → Galaxy branching translation"
tags:
- research/design-spec
- source/cwl
- target/galaxy
status: draft
created: 2026-05-11
revised: 2026-05-11
revision: 1
ai_generated: true
related_notes:
- "[[cwl-pickvalue-to-galaxy]]"
- "[[galaxy-paired-or-unpaired-collections]]"
- "[[galaxy-collection-semantics]]"
- "[[component-cwl-workflow-anatomy]]"
- "[[galaxy-data-flow-draft-contract]]"
related_molds:
- "[[cwl-summary-to-galaxy-interface]]"
- "[[cwl-summary-to-galaxy-data-flow]]"
- "[[cwl-summary-to-galaxy-template]]"
- "[[compare-against-iwc-exemplar]]"
summary: "CWL `when:`/`pickValue` → Galaxy. Three honest translations (paired_or_unpaired input, native pick_value step, sibling workflows) plus how to pick among them."
---
# CWL `when:`/`pickValue` → Galaxy branching translation
Audience: a Mold author looking at a `summary-cwl.json` whose steps carry `when:` predicates and/or whose workflow outputs use `pickValue`, deciding which Galaxy translation to recommend.
## The three honest translations
CWL has two related branching mechanisms with no 1:1 gxformat2 equivalent (until galaxy#22222 — see `cwl-pickvalue-to-galaxy`):
- **`when:` on a step** — execute conditionally on a JS predicate.
- **`pickValue:` on a step input or workflow output** — fan in N candidate sources and pick `first_non_null` / `the_only_non_null` / `all_non_null`.
Three Galaxy-idiomatic translations are available; each is honest for a different source shape.
### Translation A — `paired_or_unpaired` collection (preferred when the discriminator is paired-vs-single)
When the CWL `when:` predicates discriminate the **paired-vs-single mode of read inputs** (the seqprep-subwf pattern: `single_reads: File?` trigger
...Choose Galaxy collection input shapes from CWL arrays, scatter inputs, records, Directory values, and secondary-file contracts.
Trigger: When CWL types include arrays, records, Directory, secondaryFiles, or scatter over File-like inputs.
references/notes/galaxy-collection-semantics.mdcontent/research/galaxy-collection-semantics.md---
type: research
subtype: component
title: "Galaxy collection semantics"
tags:
- research/component
- target/galaxy
status: draft
created: 2026-04-30
revised: 2026-05-05
revision: 3
ai_generated: false
related_notes:
- "[[galaxy-xsd]]"
- "[[galaxy-collection-tools]]"
- "[[galaxy-apply-rules-dsl]]"
- "[[nextflow-to-galaxy-channel-shape-mapping]]"
- "[[nextflow-operators-to-galaxy-collection-recipes]]"
- "[[galaxy-tool-job-failure-reference]]"
- "[[galaxy-workflow-invocation-failure-reference]]"
- "[[iwc-transformations-survey]]"
sources:
- "https://github.com/galaxyproject/galaxy/blob/7765fae934fbfdee77e3be5f5b235e43735273ae/lib/galaxy/model/dataset_collections/types/collection_semantics.yml"
summary: "Vendored formal spec of Galaxy dataset-collection mapping/reduction semantics, with labeled examples and pinned test references."
---
> **Vendored from upstream**, pinned at SHA `7765fae`. Two files live next to this note:
>
> - `galaxy-collection-semantics.yml` — the structured source. **Agents and casting should consume this.** It carries the `tests:` blocks that pin concrete Galaxy test names; the rendered upstream view drops them.
> - `galaxy-collection-semantics.upstream.myst` — Galaxy's auto-generated MyST/LaTeX rendering of the YAML, vendored only so the human view below has something to render. Sync is manual.
>
> **When to consult:** authoring or reasoning about Molds and patterns that touch `data_collection` inputs, map-over / reduction shape changes, sub-collection mapping, `paired_or_unpaired`, or `sample_sheet`.
```vendored-myst
file: galaxy-collection-semantics.upstream.myst
source: https://github.com/galaxyproject/galaxy/blob/7765fae934fbfdee77e3be5f5b235e43735273ae/doc/source/dev/collection_semantics.md
sha: 7765fae
```
Choose `paired_or_unpaired` (or `list:paired_or_unpaired`) shape when the CWL discriminator is paired-vs-single reads, instead of inventing a workflow-level `reads_mode` select parameter.
Trigger: When summary-cwl declares 2+ optional File? read-like inputs whose step bindings are gated by complementary `when:` predicates, OR workflow outputs use pickValue over branches keyed on input presence, OR an upstream `meta.single_end`-style discriminator surfaces in the summary.
references/notes/galaxy-paired-or-unpaired-collections.mdcontent/research/galaxy-paired-or-unpaired-collections.md---
type: research
subtype: component
title: "Galaxy paired_or_unpaired collection type"
tags:
- research/component
- target/galaxy
status: draft
created: 2026-05-11
revised: 2026-05-11
revision: 1
ai_generated: true
related_notes:
- "[[galaxy-collection-semantics]]"
- "[[component-cwl-workflow-anatomy]]"
related_molds:
- "[[cwl-summary-to-galaxy-interface]]"
- "[[cwl-summary-to-galaxy-data-flow]]"
- "[[nextflow-summary-to-galaxy-interface]]"
summary: "Galaxy's `paired_or_unpaired` collection type: discriminated-union shape for paired-or-single reads, no workflow-level mode switch needed. Galaxy PR #19377."
---
# Galaxy `paired_or_unpaired` collections
Audience: a Mold author shaping a Galaxy workflow interface from an upstream (CWL / Nextflow / paper) source whose reads can be paired-end *or* single-end *or* a mixed batch of both.
## The shape
`paired_or_unpaired` is a Galaxy collection type modeling a **discriminated union of 1 or 2 elements**:
- **Unpaired variant** — one element with identifier `unpaired`.
- **Paired variant** — two elements with identifiers `forward` and `reverse`.
`list:paired_or_unpaired` lifts the same shape to a *heterogeneous* batch where some samples are paired and some are single-end — a representation that did not exist before this type. A `list:paired` forces every sample to be paired; a plain `list` of flat datasets loses pairing structure.
The type and rank `paired_or_unpaired` may occur at any rank within nested types (`list:paired_or_unpaired`, `list:list:paired_or_unpaired`) but **only at the deepest (innermost) rank** — the subtyping logic is implemented at the suffix level. See "Limitation: only deepest rank" below.
## When to reach for it (decision rule for translators)
Reach for `paired_or_unpaired` when the
...Choose stable Galaxy workflow input/output labels and promoted checkpoint outputs.
Trigger: When deciding labels, public outputs, checkpoint outputs, or fixture-compatible collection inputs.
references/notes/galaxy-workflow-testability-design.mdcontent/research/galaxy-workflow-testability-design.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
...
# cwl-summary-to-galaxy-interface
Follow the procedure below and use the artifact/reference sections as the runtime contract.
## When To Use
- Map a CWL summary into a Galaxy workflow interface design brief.
## Inputs
- Read artifact `summary-cwl`. Schema: summary-cwl. Produced by `summarize-cwl`. Structured CWL summary emitted by summarize-cwl; the source-of-truth JSON for Galaxy interface choices.
## Outputs
- Write artifact `cwl-galaxy-interface` as `cwl-galaxy-interface.md`. Format: `markdown`. Reviewable Markdown brief: Galaxy workflow inputs, outputs, labels, exposed and checkpoint outputs, source provenance, confidence.
## Load Upfront
- `references/notes/component-cwl-workflow-anatomy.md`: Research note copied verbatim into the bundle. Keep source-faithful CWL facts separate from Galaxy-facing interface choices.
- `references/schemas/summary-cwl.schema.json`: Schema file copied verbatim into the bundle. Read CWL workflow inputs, outputs, types, formats, secondary files, scatter, and requirement evidence before choosing the Galaxy interface.
## Load On Demand
- `references/notes/cwl-when-pickvalue-to-galaxy-branching.md`: Research note copied verbatim into the bundle. Pick among the three honest Galaxy branching translations (paired_or_unpaired input, native pick_value step, sibling workflows) before drafting the interface. Use when: summary-cwl has any steps[].when non-null OR any workflow output uses pickValue.
- `references/notes/galaxy-collection-semantics.md`: Research note copied verbatim into the bundle. Choose Galaxy collection input shapes from CWL arrays, scatter inputs, records, Directory values, and secondary-file contracts. Use when: cWL types include arrays, records, Directory, secondaryFiles, or scatter over File-like inputs.
- `references/notes/galaxy-paired-or-unpaired-collections.md`: Research note copied verbatim into the bundle. Choose `paired_or_unpaired` (or `list:paired_or_unpaired`) shape when the CWL discriminator is paired-vs-single reads, instead of inventing a workflow-level `reads_mode` select parameter. Use when: summary-cwl declares 2+ optional File? read-like inputs whose step bindings are gated by complementary `when:` predicates, OR workflow outputs use pickValue over branches keyed on input presence, OR an upstream `meta.single_end`-style discriminator surfaces in the summary.
- `references/notes/galaxy-workflow-testability-design.md`: Research note copied verbatim into the bundle. Choose stable Galaxy workflow input/output labels and promoted checkpoint outputs. Use when: deciding labels, public outputs, checkpoint outputs, or fixture-compatible collection inputs.
## Validation
- None declared.
## Procedure
Read a CWL summary and emit a reviewable Markdown interface brief for a Galaxy workflow. Preserve CWL input/output intent while choosing Galaxy-facing labels, data shapes, exposed outputs, checkpoint outputs, provenance, confidence, and open questions.
The output is a design handoff, not gxformat2 and not a rich workflow schema.
Prefer direct mappings when they are honest: CWL scalar inputs become Galaxy parameter inputs, `File` inputs become dataset inputs, `File[]` plus scatter commonly becomes a `list` collection, and declared formats seed Galaxy datatype choices. Surface `Directory`, records, expression-shaped defaults, and secondary-file-heavy outputs as review notes rather than flattening them silently.
## 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.