Claude skill · cast advance-galaxy-draft-step
Advance the gxformat2 draft by one step: pick the next drafty step, resolve a wrapper, implement the step, and validate.
← All cast skills · Source mold →
Install
/plugin marketplace add galaxyproject/foundry
/plugin install foundry-skills@galaxy-workflow-foundry
Then invoke as:
/foundry-skills:advance-galaxy-draft-step
Skill Bundle
/ packaged cast
- attached files
- 5
- upfront
- 2
- on demand
- 3
- cast rev
- n/a
- validated
- 0
Produces: 1 artifact.
Consumes: 1 artifact.
Artifact Contract
/ skill handoff Produces
galaxy-workflow-draft
Same draft with one additional step concretized (one loop iteration). Once every step is concrete, [[draft-next-step]] reports `draft: false` and the harness exits the loop.
yamlgalaxy-workflow-draft.gxwf.yml[[galaxy-workflow-draft]]
Raw artifact contract
{
"id": "galaxy-workflow-draft",
"kind": "yaml",
"default_filename": "galaxy-workflow-draft.gxwf.yml",
"schema": "[[galaxy-workflow-draft]]",
"description": "Same draft with one additional step concretized (one loop iteration). Once every step is concrete, [[draft-next-step]] reports `draft: false` and the harness exits the loop."
}
Consumes
galaxy-workflow-draft
gxformat2 draft (see [[galaxy-workflow-draft-format]]) mutated in-place across iterations; topology is fully concrete, individual tool steps may still carry `TODO_*` sentinels and `_plan_*` planning fields.
Raw artifact contract
{
"id": "galaxy-workflow-draft",
"description": "gxformat2 draft (see [[galaxy-workflow-draft-format]]) mutated in-place across iterations; topology is fully concrete, individual tool steps may still carry `TODO_*` sentinels and `_plan_*` planning fields.",
"inherited_schema": "[[galaxy-workflow-draft]]",
"producers": [
"advance-galaxy-draft-step",
"cwl-summary-to-galaxy-template",
"freeform-summary-to-galaxy-template",
"implement-galaxy-tool-step",
"nextflow-summary-to-galaxy-template"
]
}
Attached Files
/ runtime references Load upfront
Deterministically pick the next drafty step (or report no remaining work). The orchestrator owns the loop oracle so the harness reduces to `while draft: invoke skill`.
Trigger: At the start of every iteration, before any per-step work.
upfront runtime sidecar hypothesis deterministic 2.9 KB
- bundle
references/cli/draft-next-step.json- source
content/cli/gxwf/draft-next-step.md
Preview json
{
"type": "cli-command",
"tool": "gxwf",
"command": "draft-next-step",
"summary": "Pick the next drafty step a harness should work on, or report no remaining work; deterministic topological + alphabetical tiebreak.",
"source_path": "content/cli/gxwf/draft-next-step.md",
"source_revision": 1,
"body": "# `gxwf draft-next-step`\n\nDeterministic next-step picker for the per-step authoring loop. Wraps `nextDraftStep` from `@galaxy-tool-util/schema`. Native (.ga) input is rejected — drafts are format2-only.\n\nThe harness loop reads as: `while (next = gxwf draft-next-step <wf>).draft: invoke per-step skill on next.step`.\n\n## Output\n\nDefault output is pretty JSON — the agent-loop wire format. Same input → byte-identical output. `--output-format markdown` renders a human-glance checklist instead.\n\nJSON fields:\n\n- `draft` (bool) — `true` while a drafty step remains, `false` at the terminal cases below.\n- `step` (string array) — the picked step's **path**: a single id at top level (`[\"merge assembled transcripts\"]`), or the full path through containing subworkflow steps when the pick is nested. The leaf (last element) is the step to work on.\n- `work` (string array) — the chosen step's remaining `TODO[...]` sentinels followed by its `_plan_*` fields, in checklist order.\n\nAt the terminal cases the object is just `{ \"draft\": false }` — no `step` or `work` keys.\n\nTwo terminal cases both surface as `draft: false`:\n\n- The workflow's class is already `GalaxyWorkflow` (concretization complete, class promoted).\n- The class is still `GalaxyWorkflowDraft` but every step is fully resolved (no `TODO_*`, no `_plan_*`). The harness's next move is [[draft-extract]] (which calls `promoteFullyConcreteDrafts` to flip the class) followed by terminal [[validate]].\n\n## Examples\n\n```bash\ngxwf draft-next-step workflow.gxwf.yml\ngxwf draft-next-step workflow.gxwf.yml --output-format markdown\n```\n\nHarness loop sketch:\n\n```bash\nwhile [ \"$(gxwf draft-next-step workflow.gxwf.yml | jq -r .draft)\" = \"true\" ]; do\n step=$(gxwf draft-next-step workflow.gxwf.yml | jq -r '.step | last')\n # invoke per-step skill on step, which mutates workflow.gxwf.yml in place\ndone\n```\n\n## Gotchas\n\n- Pick order is **topological** (a step waits until its `in:` sources are concretized) with **alphabetical tiebreak** on step id at the same level. Same input across
...
In/out contract: the draft this Mold reads and mutates one step per iteration conforms to [[galaxy-workflow-draft]]. Cast bundles the JSON Schema alongside the [[draft-validate]] CLI checks.
upfront runtime verbatim cast-validated deterministic 58.6 KB
- bundle
references/schemas/galaxy-workflow-draft.schema.json- source
package://@galaxy-tool-util/schema#galaxyWorkflowDraftJsonSchema
Preview json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"WorkflowStepSchema": {
"type": "object",
"required": [],
"properties": {
"id": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"label": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"doc": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"position": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"top",
"left"
],
"properties": {
"top": {
"type": "number"
},
"left": {
"type": "number"
}
},
"additionalProperties": false
}
]
},
"tool_id": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"tool_shed_repository": {
"$ref": "#/$defs/Shared15"
},
"tool_version": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"errors": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"uuid": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"in": {
"$ref": "#/$defs/Shared16"
},
"out": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/$defs/Shared4"
...
Load on demand
Validate the mutated draft against draft-contract rules and, with --concrete, also gate the extracted concrete subset (including the step just implemented) against full gxformat2.
Trigger: After implementing or modifying the chosen step in the draft.
on-demand runtime sidecar hypothesis deterministic 4.7 KB
- bundle
references/cli/draft-validate.json- source
content/cli/gxwf/draft-validate.md
Preview json
{
"type": "cli-command",
"tool": "gxwf",
"command": "draft-validate",
"summary": "Validate a `class: GalaxyWorkflowDraft` workflow against draft-contract rules; with --concrete, also validate the extracted concrete subset.",
"source_path": "content/cli/gxwf/draft-validate.md",
"source_revision": 1,
"body": "# `gxwf draft-validate`\n\nValidate a draft Galaxy workflow against the **draft contract**: sentinel form, dangling edge references, top-level `_plan_*` placement, `_plan_*` on fully-resolved tool steps, and recursive draft subworkflows. Native (.ga) input is rejected — drafts are format2-only.\n\nDistinct from [[validate]], which validates a fully concrete `class: GalaxyWorkflow` and would reject the draft relaxations outright. Use `draft-validate` during the per-step authoring loop; use `validate` at the terminal pass once `promoteFullyConcreteDrafts` has flipped the class.\n\n## Output\n\nDefault output is human-readable: counted buckets for structure / topology / semantic errors and warnings, plus a one-line survey (TODO sentinel count, paths carrying `_plan_*`). `--json` emits a `SingleDraftValidationReport`; `--report-html` and `--report-markdown` write the same data as a self-contained HTML page or templated Markdown. With `--concrete`, the report carries an optional `concrete: ConcreteValidationReport` whose buckets (`structure_errors`, `strict_structure_errors`, `strict_encoding_errors`, `strict_state_errors`, `tool_state`, `connection_report`) are **absent when the corresponding check did not run** — readers should treat absence as \"not run,\" not as \"passed.\"\n\n## Flags\n\n`--concrete` runs the extract+promote pipeline (`extractConcreteSubset` → `stripPlanFields` → `promoteFullyConcreteDrafts`) and applies the full concrete `gxformat2` validation surface to the result. The following pass-through flags only take effect under `--concrete`; passing them without it prints a stderr warning and no-ops:\n\n- `--cache-dir <dir>` — tool cache for tool-state lookups.\n- `--no-tool-state` — skip tool-state validation on the concrete pass. Combined with `--strict-state`, the strict flag warns + no-ops (there's no state to be strict about).\n- `--connections` — run connection validation on the concrete subset.\n- `--strict` — escalate every strict bucket (structure, encoding, state) to error.\n- `--strict-structure` / `--strict-encoding` /
...
Classify [[draft-validate]] diagnostics against wrapper-defined runtime failure semantics so the iteration routes back to the right authoring surface (implementation vs. wrapper choice).
Trigger: When draft-validate fails after a step has been implemented, or when a selected wrapper has explicit failure semantics that may surface at runtime.
on-demand runtime verbatim corpus-observed deterministic 7.3 KB
- bundle
references/notes/galaxy-tool-job-failure-reference.md- source
content/research/galaxy-tool-job-failure-reference.md
Preview md
---
type: research
subtype: component
title: "Galaxy tool and job 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-workflow-invocation-failure-reference]]"
- "[[planemo-workflow-test-architecture]]"
- "[[galaxy-collection-semantics]]"
related_molds:
- "[[implement-galaxy-tool-step]]"
- "[[debug-galaxy-workflow-output]]"
sources:
- "~/projects/repositories/galaxy/lib/galaxy/tools/__init__.py"
- "~/projects/repositories/galaxy/lib/galaxy/tool_util/parser/xml.py"
- "~/projects/repositories/galaxy/lib/galaxy/tool_util/output_checker.py"
- "~/projects/repositories/galaxy/lib/galaxy/jobs"
- "~/projects/repositories/galaxy/lib/galaxy/webapps/galaxy/api/jobs.py"
summary: "Reference for Galaxy tool stdio rules, job failure detection, job states, and job API failure surfaces."
---
# Galaxy Tool And Job Failure Reference
This is reference material, not a debug recipe. Use it to understand what Galaxy can know about a failed tool job and which API surfaces preserve that evidence.
## Model
Galaxy tool failure handling is layered:
- The tool wrapper defines expected failure semantics through `detect_errors`, `<stdio>`, exit-code checks, regex checks, and command strictness.
- The job runner executes the command and captures exit code plus tool/job stdout and stderr streams.
- Galaxy evaluates configured failure rules and records structured `job_messages`.
- The job reaches a terminal state, output datasets may become `error`, and dependent jobs may pause or fail later.
- Workflow invocation APIs summarize those jobs, but job APIs preserve the most detailed tool-level evidence.
## Tool Wrapper Failure Controls
Important wrapper con
...
Bind the chosen step against the deterministic tool summary manifest emitted by [[summarize-galaxy-tool]] — read `parsed_tool` for ports/datatypes and `input_schemas.workflow_step_linked` for valid step `tool_state` shape.
Trigger: After a wrapper has been resolved for the chosen step and before implementing it.
on-demand runtime verbatim corpus-observed deterministic 7.6 KB
- bundle
references/schemas/galaxy-tool-summary.schema.json- source
package://@galaxy-foundry/foundry#galaxyToolSummarySchema
Preview json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://galaxyproject.org/foundry/schemas/galaxy-tool-summary.schema.json",
"$comment": "Canonical source: packages/foundry/src/schemas/galaxy-tool-summary/galaxy-tool-summary.schema.json in jmchilton/foundry. Mold frontmatter cites this as `content/schemas/galaxy-tool-summary.schema.json` for stability; the cast pipeline and Astro site resolve that ref back to this file at build time. The `$defs.ParsedTool` definition is a placeholder that the AJV validator replaces at compile time with the upstream `parsedToolSchema` from `@galaxy-tool-util/schema`. Static consumers that do not use the validator should consult `[[parsed-tool]]` for the upstream definition.",
"title": "Galaxy Tool Summary",
"description": "Deterministic per-tool manifest emitted by `galaxy-tool-cache summarize`. Bundles cache provenance, the upstream `ParsedTool` payload, and per-representation input JSON Schemas so downstream Molds can bind a single workflow step against a Galaxy tool wrapper without re-parsing XML.",
"$ref": "#/$defs/GalaxyToolSummary",
"$defs": {
"GalaxyToolSummary": {
"title": "GalaxyToolSummary",
"description": "Top-level shape. Every Galaxy tool summary is exactly this object.",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"tool_id",
"tool_version",
"cache_key",
"source",
"artifacts",
"parsed_tool",
"input_schemas",
"warnings"
],
"properties": {
"schema_version": {
"type": "integer",
"const": 1,
"description": "Manifest schema version. v1 is the shape emitted by `galaxy-tool-cache summarize` in `@galaxy-tool-util/cli@1.3.x`."
},
"tool_id": {
"type": "string",
"minLength": 1,
"description": "Tool id as it appears in the cached `ParsedTool`. For Tool Shed wrappers this is the short XML id, not the fully qualified `toolshed.g2.bx.psu.edu/repos/...` form."
},
"tool_version": {
"type": [
"string",
"null"
],
"description": "Tool version from the cached `ParsedTool`. Null only when the wrapper itself omits a version."
},
"cache_key": {
"type": "string",
"minLen
...
SKILL.md
# advance-galaxy-draft-step
Follow the procedure below and use the artifact/reference sections as the runtime contract.
## When To Use
- Advance the gxformat2 draft by one step: pick the next drafty step, resolve a wrapper, implement the step, and validate.
## Inputs
- Read artifact `galaxy-workflow-draft`. Schema: galaxy-workflow-draft. Produced by `advance-galaxy-draft-step`, `cwl-summary-to-galaxy-template`, `freeform-summary-to-galaxy-template`, `implement-galaxy-tool-step`, `nextflow-summary-to-galaxy-template`. gxformat2 draft (see galaxy-workflow-draft-format) mutated in-place across iterations; topology is fully concrete, individual tool steps may still carry `TODO_*` sentinels and `_plan_*` planning fields.
## Outputs
- Write artifact `galaxy-workflow-draft` as `galaxy-workflow-draft.gxwf.yml`. Format: `yaml`. Schema: galaxy-workflow-draft. Same draft with one additional step concretized (one loop iteration). Once every step is concrete, draft-next-step reports `draft: false` and the harness exits the loop.
## Required Tools
- **`gxwf`** (gxwf). `npm install -g @galaxy-tool-util/cli`.
Ephemeral run: `npx --package @galaxy-tool-util/cli gxwf`.
Check: `gxwf --version`.
Docs: https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli
## Load Upfront
- `references/cli/draft-next-step.json`: CLI command reference packaged as a sidecar. Deterministically pick the next drafty step (or report no remaining work). The orchestrator owns the loop oracle so the harness reduces to `while draft: invoke skill`. Use when: at the start of every iteration, before any per-step work.
- `references/schemas/galaxy-workflow-draft.schema.json`: Schema file copied verbatim into the bundle. In/out contract: the draft this Mold reads and mutates one step per iteration conforms to galaxy-workflow-draft. Cast bundles the JSON Schema alongside the draft-validate CLI checks.
## Load On Demand
- `references/cli/draft-validate.json`: CLI command reference packaged as a sidecar. Validate the mutated draft against draft-contract rules and, with --concrete, also gate the extracted concrete subset (including the step just implemented) against full gxformat2. Use when: after implementing or modifying the chosen step in the draft.
- `references/notes/galaxy-tool-job-failure-reference.md`: Research note copied verbatim into the bundle. Classify draft-validate diagnostics against wrapper-defined runtime failure semantics so the iteration routes back to the right authoring surface (implementation vs. wrapper choice). Use when: draft-validate fails after a step has been implemented, or when a selected wrapper has explicit failure semantics that may surface at runtime.
- `references/schemas/galaxy-tool-summary.schema.json`: Schema file copied verbatim into the bundle. Bind the chosen step against the deterministic tool summary manifest emitted by summarize-galaxy-tool — read `parsed_tool` for ports/datatypes and `input_schemas.workflow_step_linked` for valid step `tool_state` shape. Use when: after a wrapper has been resolved for the chosen step and before implementing it.
## Validation
- Validate `galaxy-workflow-draft.gxwf.yml` for artifact `galaxy-workflow-draft` against the galaxy-workflow-draft schema when a validator is available.
## Procedure
Orchestrator skill for the per-step Galaxy authoring loop. One invocation advances the gxformat2 draft by **one** step: pick → resolve a wrapper → summarize the wrapper → implement the step → validate. The harness loop reduces to `while (gxwf draft-next-step <wf>).draft: invoke skill`.
This skill is **single-entry, single-exit**: it owns the loop oracle (draft-next-step) and the per-step validator (draft-validate `--concrete`). Iterations terminate when the draft has no remaining drafty steps; the harness then drops out of the loop and proceeds to terminal validation via validate-galaxy-workflow.
### Sequence
1. **Pick.** Run draft-next-step. If `draft: false`, return — the loop is done. Otherwise carry the chosen step id forward.
2. **Resolve a wrapper.** Try discover-shed-tool against the step's `_plan_*` context; if no acceptable shed candidate emerges, fall through to author-galaxy-tool-wrapper.
3. **Summarize the wrapper.** Invoke summarize-galaxy-tool on the resolved wrapper to produce a galaxy-tool-summary for the next phase.
4. **Implement.** Invoke implement-galaxy-tool-step with the summary and the draft; it replaces the chosen step's `TODO_*` / `_plan_*` slots with concrete `tool_id`, `tool_state`, and wrapper-determined port names.
5. **Validate.** Run draft-validate `--concrete` over the mutated draft. On green, return; the next iteration starts at step 1. On red, route per the failure-routing rules below.
### Failure routing
`draft-validate --concrete` failures fall into three buckets:
- **Local to the just-implemented step** (sentinel violation, wrong port name, malformed `tool_state`) — re-enter implement-galaxy-tool-step with the diagnostic.
- **Wrapper-choice mismatch** (selected wrapper cannot satisfy the step's `_plan_*` contract — wrong datatype, missing parameter, incompatible collection shape) — back out to step 2 and pick a different wrapper, either via discover-shed-tool with refined criteria or by escalating to author-galaxy-tool-wrapper.
- **Earlier-step defect surfaced by the growing concrete projection** (e.g. a connection that looked fine in isolation breaks once a downstream step pulls a previously-deferred port into scope) — flag to the user. The orchestrator does not unwind prior iterations on its own; cross-step rework belongs at the harness level. *Open question: at what threshold should this skill attempt to re-enter implement-galaxy-tool-step for an earlier step versus always escalating?*
Consult galaxy-tool-job-failure-reference when the wrapper has explicit failure semantics that affect routing — strict-shell behavior, dynamic outputs, or non-default stdio rules can present as wrapper-choice mismatches even when the static shape validates.
### Why orchestrator-shaped
Prior pipelines expressed the iteration as four entries: a `discover-or-author` branch plus `summarize-galaxy-tool`, `implement-galaxy-tool-step`, and `validate-galaxy-step`. Collapsing them into one orchestrator keeps the per-iteration narrative — including the discover-or-author branch and the failure-routing rules — in a single procedural surface that the skill can render coherently. Leaf skills stay independently castable for ad-hoc invocation; only the pipeline shape changes.
## 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.