Agent 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 with Claude Code

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

Then invoke as:

/foundry-skills:advance-galaxy-draft-step

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:

$advance-galaxy-draft-step

Install with Antigravity

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

Then select with /skills or invoke explicitly as:

/advance-galaxy-draft-step

Skill Bundle

/ packaged cast

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

Produces: 3 artifacts.

Consumes: 2 artifacts.

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."
}

galaxy-workflow

Concrete gxformat2 workflow (`class: GalaxyWorkflow`) extracted from the fully-concretized draft at loop endstate via [[draft-extract]]: drafty steps dropped, `_plan_*` planning fields stripped, class promoted. The runnable, testable artifact that downstream Molds ([[implement-galaxy-workflow-test]], [[validate-galaxy-workflow]], [[run-workflow-test]]) consume.

yamlgalaxy-workflow.gxwf.yml

Raw artifact contract

{
  "id": "galaxy-workflow",
  "kind": "yaml",
  "default_filename": "galaxy-workflow.gxwf.yml",
  "description": "Concrete gxformat2 workflow (`class: GalaxyWorkflow`) extracted from the fully-concretized draft at loop endstate via [[draft-extract]]: drafty steps dropped, `_plan_*` planning fields stripped, class promoted. The runnable, testable artifact that downstream Molds ([[implement-galaxy-workflow-test]], [[validate-galaxy-workflow]], [[run-workflow-test]]) consume."
}

open-requirements-ledger

Carried obligations ledger re-emitted by this step: entries it appended or closed updated, every other entry passed through with its provenance intact.

yamlopen-requirements.ledger.yml

Raw artifact contract

{
  "id": "open-requirements-ledger",
  "kind": "yaml",
  "default_filename": "open-requirements.ledger.yml",
  "description": "Carried obligations ledger re-emitted by this step: entries it appended or closed updated, every other entry passed through with its provenance intact."
}

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",
    "apply-galaxy-workflow-changeset",
    "cwl-summary-to-galaxy-template",
    "freeform-summary-to-galaxy-template",
    "implement-galaxy-tool-step",
    "nextflow-summary-to-galaxy-template",
    "repair-galaxy-draft-topology",
    "workflow-brief-to-galaxy-template"
  ]
}

open-requirements-ledger

Carried obligations ledger [[open-requirements-ledger]]: the run's open, resolved, and surrendered entries with their provenance. Absent on the first Mold of a run; start an empty one.

Raw artifact contract

{
  "id": "open-requirements-ledger",
  "description": "Carried obligations ledger [[open-requirements-ledger]]: the run's open, resolved, and surrendered entries with their provenance. Absent on the first Mold of a run; start an empty one.",
  "producers": [
    "advance-galaxy-draft-step",
    "apply-galaxy-workflow-changeset",
    "compare-against-iwc-exemplar",
    "cwl-summary-to-galaxy-data-flow",
    "cwl-summary-to-galaxy-interface",
    "cwl-summary-to-galaxy-template",
    "freeform-summary-to-galaxy-data-flow",
    "freeform-summary-to-galaxy-interface",
    "freeform-summary-to-galaxy-template",
    "implement-galaxy-tool-step",
    "interview-to-galaxy-workflow-changeset",
    "mature-galaxy-workflow-for-iwc",
    "nextflow-summary-to-galaxy-data-flow",
    "nextflow-summary-to-galaxy-interface",
    "nextflow-summary-to-galaxy-reference-data",
    "nextflow-summary-to-galaxy-template",
    "repair-galaxy-draft-topology",
    "workflow-brief-to-galaxy-data-flow",
    "workflow-brief-to-galaxy-interface",
    "workflow-brief-to-galaxy-template"
  ]
}

Attached Files

/ runtime references

Load upfront

cli-command

draft-next-step

packaged

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 3.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,
  "package": "@galaxy-tool-util/cli",
  "description": "Pick the next step a downstream agent should work on (or report no remaining work)",
  "synopsis": "gxwf draft-next-step [options] <file>",
  "args": [
    {
      "raw": "file",
      "name": "file",
      "required": true,
      "variadic": false,
      "description": "Draft workflow file (.gxwf.yml)"
    }
  ],
  "options": [
    {
      "flags": "--format <fmt>",
      "name": "format",
      "description": "Force input format: format2 (default; native is rejected)",
      "takesArgument": true,
      "argumentPlaceholder": "<fmt>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--output-format <fmt>",
      "name": "outputFormat",
      "description": "Output format: json (default) or markdown",
      "takesArgument": true,
      "argumentPlaceholder": "<fmt>",
      "optionalArgument": false,
      "negatable": false,
      "defaultValue": "json"
    }
  ],
  "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 
...

research

open-requirements-ledger

packaged

Read the ledger for an open blocking entry against the picked step, or any open blocking entry once no drafty step is left, count the open blocking entries the convergence gate reads, and maintain the topology_repair escalation budget the loop's termination guard depends on.

upfront runtime verbatim hypothesis deterministic 21.3 KB

bundle: references/notes/open-requirements-ledger.md
source: content/research/open-requirements-ledger/index.md

Preview md

---
type: research
title: "Open-requirements ledger"
tags:
  - target/galaxy
status: draft
created: 2026-06-16
revised: 2026-11-06
revision: 6
related_notes:
  - "[[galaxy-workflow-draft-format]]"
related_molds:
  - "[[advance-galaxy-draft-step]]"
  - "[[repair-galaxy-draft-topology]]"
  - "[[implement-galaxy-tool-step]]"
summary: "Carried workflow-run knowledge artifact for obligations, discoveries, decisions, brief-change recommendations, and convergence state."
---

# Open-requirements ledger

The `open-requirements-ledger` is the carried workflow-run knowledge artifact threaded through the source→Galaxy pipeline. It records **obligations the pipeline has taken on but not yet met** — a declared output with no producer, a parameter whose value the source never pinned, a tool with no corpus exemplar — and **source work it decided not to carry**. It also records evidence discovered during implementation, decisions made within the approved scope, and recommended changes to an immutable Workflow Brief. Each Mold that surfaces an obligation **appends** it; each Mold whose decision closes one **marks it resolved**; the terminal path **surrenders** whatever remains open, explicitly, into the final artifact.

This ledger is about the workflow being built. It is distinct from the opt-in `foundry-feedback-ledger`, which records actionable defects or friction in the Foundry assets building it. It is also not the harness's phase-progress tracker: execution status belongs to harness state, checkpoints, and reports rather than requirement entries.

## Framing: obligations the pipeline discharges, not questions a human answers

This is deliberately *not* an "open questions for the user" list. The pipeline is autonomous — no human-in-the-loop gate is assumed. The ledger's consumers a
...

schema

galaxy-workflow-draft

packaged

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 63.5 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/Shared18"
        },
        "tool_version": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "string"
            }
          ]
        },
        "errors": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "string"
            }
          ]
        },
        "uuid": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "string"
            }
          ]
        },
        "in": {
          "$ref": "#/$defs/Shared19"
        },
        "out": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/Shared4"
          
...

Load on demand

cli-command

add

packaged

Cache the resolved wrapper for summarization and validation, using its confirmed tool version.

Trigger: After resolving the wrapper and version, if the shared cache lacks that pin.

on-demand runtime sidecar corpus-observed deterministic 4.0 KB

bundle: references/cli/add.json
source: content/cli/galaxy-tool-cache/add.md

Preview json

{
  "type": "cli-command",
  "tool": "galaxy-tool-cache",
  "command": "add",
  "summary": "Fetch a tool from the Tool Shed (shed-path or bare/stock id) and cache its ParsedTool locally for later summarize/schema.",
  "source_path": "content/cli/galaxy-tool-cache/add.md",
  "source_revision": 2,
  "package": "@galaxy-tool-util/cli",
  "description": "Fetch a tool from the ToolShed (shed-path or bare/stock ID) and cache it",
  "synopsis": "galaxy-tool-cache add [options] <tool_id>",
  "args": [
    {
      "raw": "tool_id",
      "name": "tool_id",
      "required": true,
      "variadic": false,
      "description": "Tool ID: shed path (owner/repo/tool), TRS ID, or bare/stock ID (e.g. Filter1)"
    }
  ],
  "options": [
    {
      "flags": "--tool-version <ver>",
      "name": "toolVersion",
      "description": "Tool version",
      "takesArgument": true,
      "argumentPlaceholder": "<ver>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--cache-dir <dir>",
      "name": "cacheDir",
      "description": "Cache directory",
      "takesArgument": true,
      "argumentPlaceholder": "<dir>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--galaxy-url <url>",
      "name": "galaxyUrl",
      "description": "Alternate Galaxy source, tried after the ToolShed",
      "takesArgument": true,
      "argumentPlaceholder": "<url>",
      "optionalArgument": false,
      "negatable": false
    }
  ],
  "body": "# `galaxy-tool-cache add`\n\nFetch a single tool by id from the Tool Shed and cache its parsed wrapper into the local cache directory. This is the cache-population precondition for [[summarize-galaxy-tool]]: `summarize` reads an already-cached pin and fails if the entry is missing, so `add` runs first.\n\n`<tool_id>` is a full Tool Shed path (e.g. `toolshed.g2.bx.psu.edu/repos/iuc/staramr/staramr_search`), a TRS id, **or a bare/stock id** for a built-in Galaxy tool (`Filter1`, `sort1`, `Cut1`, `Show beginning1`, collection ops). The Tool Shed serves stock tools too, so bare ids resolve against the same shed source — there is no separate Galaxy lookup in the default path. Pin the exact wrapper with `--tool-version` so the cache key matches the discovery pin from [[discover-shed-tool]].\n\nTo cache every tool a draft references in one pass instead of pin-by-pin, use `populate-workflow`
...

cli-command

draft-extract

packaged

At loop endstate, extract the concrete gxformat2 workflow from the fully-concretized draft — drop drafty steps, strip `_plan_*` fields, promote `class` to `GalaxyWorkflow` — and write it as the runnable `galaxy-workflow.gxwf.yml`.

Trigger: When [[draft-next-step]] reports `draft: false` (no remaining drafty steps).

on-demand runtime sidecar hypothesis deterministic 4.5 KB

bundle: references/cli/draft-extract.json
source: content/cli/gxwf/draft-extract.md

Preview json

{
  "type": "cli-command",
  "tool": "gxwf",
  "command": "draft-extract",
  "summary": "Extract the concrete subset of a draft workflow: trim drafty steps, strip `_plan_*`, promote class when fully resolved.",
  "source_path": "content/cli/gxwf/draft-extract.md",
  "source_revision": 1,
  "package": "@galaxy-tool-util/cli",
  "description": "Extract the concrete subset of a draft workflow (drop drafty steps, strip _plan_* fields, promote class when fully concrete)",
  "synopsis": "gxwf draft-extract [options] <file>",
  "args": [
    {
      "raw": "file",
      "name": "file",
      "required": true,
      "variadic": false,
      "description": "Draft workflow file (.gxwf.yml)"
    }
  ],
  "options": [
    {
      "flags": "-o, --output <file>",
      "name": "output",
      "short": "-o",
      "description": "Write extracted workflow to file (default: stdout)",
      "takesArgument": true,
      "argumentPlaceholder": "<file>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--report-json [file]",
      "name": "reportJson",
      "description": "Write extraction report JSON (drops, rewrites, class flip) — to file or stdout if omitted",
      "takesArgument": true,
      "argumentPlaceholder": "[file]",
      "optionalArgument": true,
      "negatable": false
    },
    {
      "flags": "--format <fmt>",
      "name": "format",
      "description": "Force input format: format2 (default; native is rejected)",
      "takesArgument": true,
      "argumentPlaceholder": "<fmt>",
      "optionalArgument": false,
      "negatable": false
    }
  ],
  "body": "# `gxwf draft-extract`\n\nTransform a draft workflow into its already-concretized subset. Pipes three operations from `@galaxy-tool-util/schema` in order:\n\n1. `extractConcreteSubset` — drop steps that still carry `TODO_*` or `_plan_*`; cascade through dead `in:` deps; rewrite multi-source inputs to the surviving subset; fall back to `default:` when a single source dies; recurse into draft subworkflows; drop orphan workflow outputs.\n2. `stripPlanFields` — remove `_plan_*` planning fields from every surviving step and from the workflow root.\n3. `promoteFullyConcreteDrafts` — flip `class: GalaxyWorkflowDraft` → `class: GalaxyWorkflow` on any (sub)workflow now carrying zero TODOs and zero `_plan_*`. Inner draft with remaining work blocks outer promotion.\n\nNative (
...

cli-command

draft-validate

packaged

Validate the draft and its concrete subset with --concrete --strict-state --json; skipped tool-state checks must fail the gate.

Trigger: After implementing or modifying the chosen step in the draft.

on-demand runtime sidecar hypothesis deterministic 8.6 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,
  "package": "@galaxy-tool-util/cli",
  "description": "Validate a draft Galaxy workflow (class: GalaxyWorkflowDraft)",
  "synopsis": "gxwf draft-validate [options] <file>",
  "args": [
    {
      "raw": "file",
      "name": "file",
      "required": true,
      "variadic": false,
      "description": "Draft workflow file (.gxwf.yml)"
    }
  ],
  "options": [
    {
      "flags": "--format <fmt>",
      "name": "format",
      "description": "Force format: format2 (native is rejected for drafts)",
      "takesArgument": true,
      "argumentPlaceholder": "<fmt>",
      "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]",
      "optionalArgument": true,
      "negatable": false
    },
    {
      "flags": "--report-markdown [file]",
      "name": "reportMarkdown",
      "description": "Write Markdown report to file (or stdout if omitted)",
      "takesArgument": true,
      "argumentPlaceholder": "[file]",
      "optionalArgument": true,
      "negatable": false
    },
    {
      "flags": "--concrete",
      "name": "concrete",
      "description": "Additionally extract the concrete subset and run the regular `gxwf validate` checks on it",
      "takesArgument": false,
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--cache-dir <dir>",
      "name": "cacheDir",
      "description": "Tool cache directory (for --concrete tool-state validation)",
      "takesArgument": true,
      "argumentPlaceholder": "<dir>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--offline",
      "name": "offline",
      "description": "Do not fetch uncached tools; read only the lo
...

cli-command

list

packaged

Read a stock tool's cached version when the step plan has no version pin.

Trigger: In step 2, when the chosen step's tool is a bare/stock id and its concrete version isn't already known from a step-plan pin.

on-demand runtime sidecar corpus-observed deterministic 2.6 KB

bundle: references/cli/list.json
source: content/cli/galaxy-tool-cache/list.md

Preview json

{
  "type": "cli-command",
  "tool": "galaxy-tool-cache",
  "command": "list",
  "summary": "Enumerate the tools in a cache directory with their resolved versions; the surface for confirming which stock/shed pin got cached.",
  "source_path": "content/cli/galaxy-tool-cache/list.md",
  "source_revision": 1,
  "package": "@galaxy-tool-util/cli",
  "description": "List cached tools with their resolved versions",
  "synopsis": "galaxy-tool-cache list [options]",
  "args": [],
  "options": [
    {
      "flags": "--json",
      "name": "json",
      "description": "Output as JSON",
      "takesArgument": false,
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--cache-dir <dir>",
      "name": "cacheDir",
      "description": "Cache directory",
      "takesArgument": true,
      "argumentPlaceholder": "<dir>",
      "optionalArgument": false,
      "negatable": false
    }
  ],
  "body": "# `galaxy-tool-cache list`\n\nEnumerate the entries in a `--cache-dir` with their resolved versions, ids, and provenance. Read-only — `list` never fetches; it reports what `add` / `populate-workflow` already cached.\n\nThis is the version-confirmation surface for the cache: after `add` resolves a pin, `list` shows the concrete `tool_version` it stored — including for **stock/built-in** ids, whose version is otherwise hard to confirm while the shed's TRS version-list endpoint is down (see [[add]]). Discovery of a not-yet-cached stock version still depends on a populated cache or a known pin; `list` reports an empty array for an empty cache, it does not synthesize the shed's catalogue.\n\n## Output\n\nHuman-readable rows by default; `--json` emits an array of cache entries. Per-entry JSON fields: `cache_key`, `tool_id`, `tool_version`, `source` (`api` for shed-fetched, `local` for a pre-seeded tree), `source_url`, `cached_at`. For a stock tool the `tool_id` carries the shed `readableId` form (e.g. `toolshed.g2.bx.psu.edu/repos/Filter1`) while the bare id still selects it in `summarize` / `schema`.\n\n## Examples\n\n```bash\ngalaxy-tool-cache list --json --cache-dir ~/.cache/gxwf\n# [ { \"tool_id\": \"toolshed.g2.bx.psu.edu/repos/Filter1\", \"tool_version\": \"1.1.1\",\n#     \"source\": \"api\", \"source_url\": \".../api/tools/Filter1/versions/1.1.1\", ... } ]\n```\n\n## Gotchas\n\n- `list` only sees the `--cache-dir` it is pointed at. A versio
...

cli-command

summarize

packaged

Regenerate the [[galaxy-tool-summary]] for a pin reused from a sibling step, from the populated cache, without re-running discovery.

Trigger: In step 3, when step 2 reused a sibling's `tool_id`/`tool_version` and no summary file for that pin is at hand.

on-demand runtime sidecar corpus-observed deterministic 3.6 KB

bundle: references/cli/summarize.json
source: content/cli/galaxy-tool-cache/summarize.md

Preview json

{
  "type": "cli-command",
  "tool": "galaxy-tool-cache",
  "command": "summarize",
  "summary": "Emit a deterministic galaxy-tool-summary manifest (cache provenance + embedded ParsedTool + generated input JSON Schemas) for a cached tool.",
  "source_path": "content/cli/galaxy-tool-cache/summarize.md",
  "source_revision": 2,
  "package": "@galaxy-tool-util/cli",
  "description": "Emit a deterministic summary manifest for a cached Galaxy tool",
  "synopsis": "galaxy-tool-cache summarize [options] <tool_id>",
  "args": [
    {
      "raw": "tool_id",
      "name": "tool_id",
      "required": true,
      "variadic": false,
      "description": "Tool ID"
    }
  ],
  "options": [
    {
      "flags": "--tool-version <ver>",
      "name": "toolVersion",
      "description": "Tool version",
      "takesArgument": true,
      "argumentPlaceholder": "<ver>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--output <file>",
      "name": "output",
      "description": "Output file (default: stdout)",
      "takesArgument": true,
      "argumentPlaceholder": "<file>",
      "optionalArgument": false,
      "negatable": false
    },
    {
      "flags": "--cache-dir <dir>",
      "name": "cacheDir",
      "description": "Cache directory",
      "takesArgument": true,
      "argumentPlaceholder": "<dir>",
      "optionalArgument": false,
      "negatable": false
    }
  ],
  "body": "# `galaxy-tool-cache summarize`\n\nEmit a deterministic summary manifest for a tool already in the cache. This is the command [[summarize-galaxy-tool]] invokes: it does not hand-author the manifest, it runs `summarize` against a cache populated for the pin (see `add`). The cache entry must exist — `summarize` does not re-fetch; cache the pin with `add` first.\n\n`<tool_id>` plus `--tool-version` select the cached entry; they must match the pin used at `add` time and the cache key, or the wrong wrapper is summarized. `<tool_id>` accepts a full Tool Shed path, a TRS id, or a **bare/stock id** for built-in tools (`Show beginning1`, `Cut1`, …) — the same id form used at `add` time. A cache miss reports `Tool not found in cache: <id>. Run 'galaxy-tool-cache add' first.`\n\n## Output\n\nA single JSON document conforming to [[galaxy-tool-summary]]. Top-level fields: `schema_version`, `tool_id`, `tool_version`, `cache_key`, `source`, `artifacts`, `parsed_too
...

research

galaxy-tool-job-failure-reference

packaged

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

bundle: references/notes/galaxy-tool-job-failure-reference.md
source: content/research/galaxy-tool-job-failure-reference/index.md

Preview md

---
type: research
title: "Galaxy tool and job failure reference"
tags:
  - target/galaxy
status: draft
created: 2026-05-02
revised: 2026-09-26
revision: 3
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:
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/tool_util/parser/xml.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/tool_util/parser/stdio.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/tool_util/output_checker.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/jobs/command_factory.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/jobs/__init__.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/jobs/runners/__init__.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/model/__init__.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/schema/schema.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/schema/jobs.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/webapps/galaxy/api/jobs.py"
  - "https://github.com/galaxyproject/galaxy/blob/a63da1dfd1960360f4aa2fddc6a75396954d750a/lib/galaxy/webapps/galaxy/services/jobs.py"
  - "
...

research

galaxy-user-tool-workflow-binding

packaged

Pass an authored `GalaxyUserTool` straight to implementation.

Trigger: When step 2 falls through to [[author-galaxy-tool-wrapper]], or when the draft already contains a step whose `run:` is a `GalaxyUserTool`.

on-demand runtime verbatim hypothesis deterministic 5.7 KB

bundle: references/notes/galaxy-user-tool-workflow-binding.md
source: content/research/galaxy-user-tool-workflow-binding/index.md

Preview md

---
type: research
title: "Binding a workflow step to a user-defined tool"
tags:
  - target/galaxy
status: draft
created: 2026-09-24
revised: 2026-10-23
revision: 4
related_notes:
  - "[[galaxy-user-tool-authoring-help]]"
  - "[[galaxy-user-tool-authoring]]"
  - "[[galaxy-workflow-draft-format]]"
  - "[[gxformat2-schema]]"
related_molds:
  - "[[author-galaxy-tool-wrapper]]"
  - "[[implement-galaxy-tool-step]]"
  - "[[advance-galaxy-draft-step]]"
sources:
  - "https://github.com/galaxyproject/galaxy/blob/5af1d03c929748006dd53ad451e5cb1fd140399a/client/src/components/Tool/authoringHelp.yml"
  - "https://github.com/galaxyproject/galaxy/blob/5af1d03c929748006dd53ad451e5cb1fd140399a/lib/galaxy/managers/tools.py"
  - "https://github.com/galaxyproject/galaxy/blob/5af1d03c929748006dd53ad451e5cb1fd140399a/lib/galaxy/webapps/galaxy/api/dynamic_tools.py"
  - "https://github.com/galaxyproject/galaxy/blob/5af1d03c929748006dd53ad451e5cb1fd140399a/lib/galaxy_test/workflow/inline_user_defined_tool.gxwf.yml"
summary: "How a workflow step uses an authored GalaxyUserTool: embedded under run:, never by tool_uuid, tool_id or content_id; registering via /api/unprivileged_tools."
---

A gxformat2 step that uses an authored `GalaxyUserTool` carries the whole tool definition under its `run:` key. That is the only way the Foundry binds a step to a user-defined tool.

A step never names a user-defined tool by `tool_uuid`, `tool_id`, or `content_id` alone. The tool is not in a server's toolbox, so a `tool_id` does not resolve to it, even when the string matches the tool's `id`. A `uuid` identifies one registered copy of the tool, for its owner, on one server. Galaxy's workflow editor and its exports write any such references themselves, and Galaxy rejects a `tool_uuid` step without an embedded def
...

schema

galaxy-tool-summary

packaged

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 `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/gxwf-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/gxwf-foundry/src/schemas/galaxy-tool-summary/galaxy-tool-summary.schema.json in galaxyproject/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",
        
...

schema

parsed-tool

packaged

Field-level shape of the `ParsedTool` payload under the summary's `parsed_tool`, which [[galaxy-tool-summary]] leaves as a placeholder: port names, datatypes, and a conditional's `whens[]` (`discriminator`, `is_default_when`) in declaration order.

Trigger: When reading a field of `parsed_tool`, including a conditional's case index or default case.

on-demand runtime verbatim corpus-observed deterministic 28.0 KB

bundle: references/schemas/parsed-tool.schema.json
source: package://@galaxy-tool-util/schema#parsedToolSchema

Preview json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "id",
    "version",
    "name",
    "description",
    "inputs",
    "outputs",
    "citations",
    "license",
    "profile",
    "edam_operations",
    "edam_topics",
    "xrefs"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "type": "string"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "inputs": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "outputs": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "required": [
              "name",
              "label",
              "hidden",
              "type",
              "format",
              "format_source",
              "metadata_source",
              "discover_datasets",
              "from_work_dir",
              "precreate_directory"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "label": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "hidden": {
                "type": "boolean"
              },
              "type": {
                "type": "string",
                "enum": [
                  "data"
                ]
              },
              "format": {
                "type": "string"
              },
              "format_source": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "metadata_source": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "discover_datasets": {
        
...

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`, `apply-galaxy-workflow-changeset`, `cwl-summary-to-galaxy-template`, `freeform-summary-to-galaxy-template`, `implement-galaxy-tool-step`, `nextflow-summary-to-galaxy-template`, `repair-galaxy-draft-topology`, `workflow-brief-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.
- Read artifact `open-requirements-ledger`. Produced by `advance-galaxy-draft-step`, `apply-galaxy-workflow-changeset`, `compare-against-iwc-exemplar`, `cwl-summary-to-galaxy-data-flow`, `cwl-summary-to-galaxy-interface`, `cwl-summary-to-galaxy-template`, `freeform-summary-to-galaxy-data-flow`, `freeform-summary-to-galaxy-interface`, `freeform-summary-to-galaxy-template`, `implement-galaxy-tool-step`, `interview-to-galaxy-workflow-changeset`, `mature-galaxy-workflow-for-iwc`, `nextflow-summary-to-galaxy-data-flow`, `nextflow-summary-to-galaxy-interface`, `nextflow-summary-to-galaxy-reference-data`, `nextflow-summary-to-galaxy-template`, `repair-galaxy-draft-topology`, `workflow-brief-to-galaxy-data-flow`, `workflow-brief-to-galaxy-interface`, `workflow-brief-to-galaxy-template`. Carried obligations ledger open-requirements-ledger: the run's open, resolved, and surrendered entries with their provenance. Absent on the first Mold of a run; start an empty one.

## 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.
- Write artifact `galaxy-workflow` as `galaxy-workflow.gxwf.yml`. Format: `yaml`. Concrete gxformat2 workflow (`class: GalaxyWorkflow`) extracted from the fully-concretized draft at loop endstate via draft-extract: drafty steps dropped, `_plan_*` planning fields stripped, class promoted. The runnable, testable artifact that downstream Molds (implement-galaxy-workflow-test, validate-galaxy-workflow, run-workflow-test) consume.
- Write artifact `open-requirements-ledger` as `open-requirements.ledger.yml`. Format: `yaml`. Carried obligations ledger re-emitted by this step: entries it appended or closed updated, every other entry passed through with its provenance intact.

## Required Tools

- **`galaxy-tool-cache`** (galaxy-tool-cache). `npm install -g '@galaxy-tool-util/cli@^1.15.0'`.
  Ephemeral run: `npx --yes --package @galaxy-tool-util/cli@1.15.0 galaxy-tool-cache`.
  Check: `galaxy-tool-cache --help | grep -q summarize`.
  Docs: https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli
- **`gxwf`** (gxwf). `npm install -g '@galaxy-tool-util/cli@^1.15.0'`.
  Ephemeral run: `npx --yes --package @galaxy-tool-util/cli@1.15.0 gxwf`.
  Check: `gxwf --help | grep -q draft-validate`.
  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/notes/open-requirements-ledger.md`: Research note copied verbatim into the bundle. Read the ledger for an open blocking entry against the picked step, or any open blocking entry once no drafty step is left, count the open blocking entries the convergence gate reads, and maintain the topology_repair escalation budget the loop's termination guard depends on.
- `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/add.json`: CLI command reference packaged as a sidecar. Cache the resolved wrapper for summarization and validation, using its confirmed tool version. Use when: after resolving the wrapper and version, if the shared cache lacks that pin.
- `references/cli/draft-extract.json`: CLI command reference packaged as a sidecar. At loop endstate, extract the concrete gxformat2 workflow from the fully-concretized draft — drop drafty steps, strip `_plan_*` fields, promote `class` to `GalaxyWorkflow` — and write it as the runnable `galaxy-workflow.gxwf.yml`. Use when: draft-next-step reports `draft: false` (no remaining drafty steps).
- `references/cli/draft-validate.json`: CLI command reference packaged as a sidecar. Validate the draft and its concrete subset with --concrete --strict-state --json; skipped tool-state checks must fail the gate. Use when: after implementing or modifying the chosen step in the draft.
- `references/cli/list.json`: CLI command reference packaged as a sidecar. Read a stock tool's cached version when the step plan has no version pin. Use when: in step 2, when the chosen step's tool is a bare/stock id and its concrete version isn't already known from a step-plan pin.
- `references/cli/summarize.json`: CLI command reference packaged as a sidecar. Regenerate the galaxy-tool-summary for a pin reused from a sibling step, from the populated cache, without re-running discovery. Use when: in step 3, when step 2 reused a sibling's `tool_id`/`tool_version` and no summary file for that pin is at hand.
- `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/notes/galaxy-user-tool-workflow-binding.md`: Research note copied verbatim into the bundle. Pass an authored `GalaxyUserTool` straight to implementation. Use when: step 2 falls through to author-galaxy-tool-wrapper, or when the draft already contains a step whose `run:` is a `GalaxyUserTool`.
- `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 `state` shape. Use when: after a wrapper has been resolved for the chosen step and before implementing it.
- `references/schemas/parsed-tool.schema.json`: Schema file copied verbatim into the bundle. Field-level shape of the `ParsedTool` payload under the summary's `parsed_tool`, which galaxy-tool-summary leaves as a placeholder: port names, datatypes, and a conditional's `whens[]` (`discriminator`, `is_default_when`) in declaration order. Use when: reading a field of `parsed_tool`, including a conditional's case index or default case.

## 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 call that leaves no drafty step (or a call that finds none) extracts the concrete `galaxy-workflow.gxwf.yml` (via draft-extract) — that promoted-class workflow, not the `-draft` file, is what downstream skills test and run — and the harness then drops out of the loop and proceeds to terminal validation via validate-galaxy-workflow.

### Sequence

Choose a writable tool-cache directory for the run. Pass the same `--cache-dir <dir>` to cache commands, wrapper summarization, and validation.

1. **Pick.** Run draft-next-step. If `draft: false`, the loop is done: apply step 5 to any `open` blocking entry, then run draft-extract to emit the concrete `galaxy-workflow.gxwf.yml` (drafty steps dropped, `_plan_*` stripped, `class` promoted to `GalaxyWorkflow`), then return. Otherwise carry the chosen step id forward. If an `open` blocking entry against it already records the wrapper as confirmed absent, the author branch as ruled out, or why its wired inputs can't supply the step, go to step 5. Tool Shed misses and a tool version missing from a cache don't record that.
2. **Resolve a wrapper.** First check for an existing pin:
   - **Already resolved in this draft** — find a concrete step with the `tool_id` named by the chosen step's `_plan_*` context or identity pin. Reuse its `tool_id` and `tool_version`, skipping discover-shed-tool for Tool Shed wrappers or cache/version lookup for stock tools. An embedded user-defined tool has no `tool_id`: match a sibling whose `run:` carries the authored definition the plan calls for, by its `id` and `version`, and reuse that definition instead of authoring it again. Continue to step 3.

   Otherwise, split on whether the step's tool is a **built-in / stock** Galaxy tool — a bare id with no `owner/repo` path (`Filter1`, `sort1`, `Cut1`, `Show beginning1`, collection ops, `__APPLY_RULES__`):
   - **Built-in / stock** — the bare id *is* the wrapper identity; it does **not** route through discover-shed-tool (Tool Shed search) or author-galaxy-tool-wrapper. Only its concrete version needs resolving: the shed serves stock tools by bare id, but its TRS version-list endpoint can't auto-resolve the version, so read it from a populated cache via `galaxy-tool-cache list` or take a known pin from the step plan — never hand-guess a stock version. summarize-galaxy-tool then performs the bare-id `add`/`summarize` with that explicit `--tool-version`.
   - **Tool Shed wrapper** — branch on whether the template already pinned wrapper identity (see the tiers in galaxy-workflow-draft-format):
     - **Identity-pinned** — `tool_id` is concrete and `tool_version` is `TODO`. Treat the pin as a strong seed: confirm it via discover-shed-tool and resolve the changeset, correcting the `tool_id` only if discovery contradicts the pin (a pinned id is high-confidence template evidence, not a guess to re-derive from scratch).
     - **Deferred** — `tool_id` is `TODO`. Search fresh: run discover-shed-tool against the step's `_plan_*` context.

     Either way, if no acceptable shed candidate emerges, fall through to author-galaxy-tool-wrapper.

   If the resolved pin is absent from the cache, run add `<tool_id> --tool-version <v> --cache-dir <dir>` before summarization. In `@galaxy-tool-util/cli` 1.10.0, validation also fetches and caches missing metadata unless `--offline` is set; offline validation requires a populated cache.
3. **Summarize the wrapper.** If step 2 reused a sibling's pin, reuse that pin's galaxy-tool-summary: use the file an earlier iteration wrote, or regenerate it from the cache with `galaxy-tool-cache` summarize `<tool_id> --tool-version <v> --cache-dir <dir> --output <file>`. If step 2 fell through to author-galaxy-tool-wrapper or reused an embedded definition, skip summarization: the authored `galaxy-user-tool.yml` is not in any toolbox or cache, and its own `inputs` and `outputs` are the port contract. Otherwise, invoke summarize-galaxy-tool to produce the summary.
4. **Implement.** Invoke implement-galaxy-tool-step with the summary, or the authored `galaxy-user-tool.yml`, and the draft. It resolves the chosen step's remaining `TODO_*` / `_plan_*` slots into a concrete `tool_id` (confirming or correcting any pinned identity), `tool_version`, `state`, and wrapper-determined port names. For an authored tool it embeds the definition under the step's `run:` instead, as galaxy-user-tool-workflow-binding describes.
5. **Check the ledger.** Inspect the open-requirements-ledger for an `open` blocking entry against this step: one that implement-galaxy-tool-step appended, or one an earlier call or skill raised. Once no drafty step is left, any `open` blocking entry counts, including one on a realized step or with no `step`. draft-validate cannot catch a computability gap: the connection graph knows ports connect, not what they carry, so the draft validates green even though the step can't run. If such an entry is present, escalate to repair-galaxy-draft-topology for a bounded structural edit, then update the ledger's `topology_repair` budget as the ledger note directs — each repair must leave fewer open blocking entries than it found, under a hard cap, and surrender rather than retry once the cap is reached. Then run draft-next-step: if it reports `draft: false`, the repair removed the last drafty step, so continue at step 6, which validates and extracts. Otherwise return — the next iteration resumes the loop, realizing any draft-tier steps the repair inserted. With no such entry, continue to validation.
6. **Validate.** Run draft-validate `<draft> --concrete --strict-state --json --cache-dir <dir>`. `--strict-state` makes skipped tool-state checks fail validation; draft structure and topology checks still run. If metadata is unavailable, resolve the cache or fetch error and retry. On exit 0, run draft-next-step again: if it now reports `draft: false`, no drafty step is left, so apply step 5 to any `open` blocking entry, then run draft-extract to emit `galaxy-workflow.gxwf.yml` before returning, because a `while draft` harness never invokes the skill again. Route other failures using the JSON diagnostics and the rules below.

### Failure routing

`draft-validate --concrete --strict-state --json` failures, after resolving metadata availability, fall into three buckets:

- **Local to the just-implemented step** (sentinel violation, wrong port name, malformed `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) — when a structural edit closes it, append a blocking entry naming the defect and escalate as in step 5. Otherwise flag it to the user. The orchestrator does not unwind prior iterations on its own.

These are red-`draft-validate` buckets. The fourth escalation path — a step output uncomputable from its wired inputs — is **not** one of them: the draft validates green there, so it is detected from the ledger in step 5 above, not from a validation failure.

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.

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