Turn a freeform source summary and selected scope into a Workflow Brief without Galaxy design assumptions.
/plugin marketplace add galaxyproject/foundry
/plugin install foundry-skills@galaxy-workflow-foundryThen invoke as:
/foundry-skills:freeform-summary-to-workflow-briefcodex plugin marketplace add galaxyproject/foundry
codex plugin add foundry-skills@galaxy-workflow-foundryThen select with /skills or invoke explicitly as:
$freeform-summary-to-workflow-briefgit clone https://github.com/galaxyproject/foundry
agy plugin install foundry/casts/claudeThen select with /skills or invoke explicitly as:
/freeform-summary-to-workflow-briefProduces: 1 artifact.
Consumes: 1 artifact.
Expert-editable workflow intent and agent environment, with optional details and explicit workflow or environment blockers.
{
"id": "workflow-brief",
"kind": "markdown",
"default_filename": "workflow-brief.md",
"schema": "[[workflow-brief-schema]]",
"description": "Expert-editable workflow intent and agent environment, with optional details and explicit workflow or environment blockers."
}Source evidence supplied by the preceding summarizer; preserve uncertainty and the caller’s selected scope.
{
"id": "freeform-summary",
"description": "Source evidence supplied by the preceding summarizer; preserve uncertainty and the caller’s selected scope.",
"producers": [
"interview-to-freeform-summary",
"summarize-paper"
]
}Apply the brief boundaries: evidence and expert intent, no inferred Galaxy design, and separate workflow/environment blockers.
references/notes/workflow-brief-design.mdcontent/research/workflow-brief-design/index.md---
type: research
title: "Workflow Brief"
tags:
- meta
status: draft
created: 2026-09-17
revised: 2026-09-20
revision: 5
summary: "Markdown Workflow Brief definition and section contract for scope, constraints, agent environment, and explicit blockers."
---
# Workflow Brief
A Workflow Brief is an expert-editable document describing what a workflow should achieve, what it should leave out, and the constraints under which an agent will build and run it. It is an input to design and implementation. The draft workflow captures the proposed steps, wiring, and tool state.
## Document shape
The brief is Markdown with a title and two sections: `## Workflow` and `## Agent Environment`. The workflow needs an objective; most details are optional. The agent environment must contain a description, which can explicitly record what still needs to be checked.
The `workflowBriefSchema` declaration uses the shared engine described in [[markdown-document-contract]] and lives in `packages/gxwf-foundry/src/workflow-brief.ts`. An illustrative document lives in `packages/gxwf-foundry/test/fixtures/workflow-brief/read-alignment.md`.
| Heading | Required | Content |
| --- | --- | --- |
| `## Workflow` | Yes | Scientific intent and scope. |
| `### Objective` | Yes, under Workflow | Scientific goal and desired outcome. |
| `### Sources` | No | Papers, interviews, repositories, relevant source pins, and evidence availability. |
| `### Scope` | No | Optional `#### Included` and `#### Excluded` describe selected work and boundaries. |
| `### Inputs and outputs` | No | Scientific roles and source-supported formats or organization. |
| `### Requirements and preferences` | No | Expert or source requirements, their strength, rationale, and evidence. |
| `### Acceptance criteria` | No | High-lev
...Carry the Markdown section declaration and its structural validator.
references/schemas/workflow-brief-schema.schema.jsonpackage://@galaxy-foundry/gxwf-foundry#workflowBriefSchema{
"name": "Workflow Brief",
"title": "required",
"sections": [
{
"heading": "Workflow",
"min": 1,
"max": 1,
"content": true,
"sections": [
{
"heading": "Objective",
"min": 1,
"max": 1,
"content": true
},
{
"heading": "Sources",
"max": 1,
"content": true
},
{
"heading": "Scope",
"max": 1,
"content": true,
"sections": [
{
"heading": "Included",
"max": 1,
"content": true
},
{
"heading": "Excluded",
"max": 1,
"content": true
}
]
},
{
"heading": "Inputs and outputs",
"max": 1,
"content": true
},
{
"heading": "Requirements and preferences",
"max": 1,
"content": true
},
{
"heading": "Acceptance criteria",
"max": 1,
"content": true
},
{
"heading": "Open questions",
"max": 1,
"content": true
},
{
"heading": "Decisions",
"max": 1,
"content": true
},
{
"heading": "Related artifacts",
"max": 1,
"content": true
},
{
"heading": "Blockers",
"max": 1
}
]
},
{
"heading": "Agent Environment",
"min": 1,
"max": 1,
"content": true,
"sections": [
{
"heading": "Tooling",
"max": 1,
"content": true
},
{
"heading": "Constraints",
"max": 1,
"content": true
},
{
"heading": "Containerization",
"max": 1,
"content": true
},
{
"heading": "Blockers",
"max": 1
}
]
}
]
}
Report declared blockers separately from structural validity.
Trigger: After structural validation and before reporting whether the brief is clear of declared blockers.
references/cli/check-workflow-brief.jsoncontent/cli/foundry/check-workflow-brief.md{
"type": "cli-command",
"tool": "foundry",
"command": "check-workflow-brief",
"summary": "Check Workflow Brief structure and stop on explicit workflow or agent environment blockers.",
"source_path": "content/cli/foundry/check-workflow-brief.md",
"source_revision": 1,
"package": "@galaxy-foundry/gxwf-foundry",
"description": "Check Workflow Brief structure and explicit workflow/environment blockers.",
"synopsis": "foundry check-workflow-brief [options] <brief.md>",
"args": [
{
"raw": "brief.md",
"name": "brief.md",
"required": true,
"variadic": false
}
],
"options": [
{
"flags": "--json",
"name": "json",
"description": "Emit machine-readable structure and blocker diagnostics",
"takesArgument": false,
"optionalArgument": false,
"negatable": false,
"defaultValue": false
}
],
"body": "# `foundry check-workflow-brief`\n\nRead a [[workflow-brief-design]] document and check its structure and declared blockers.\n\n## Output\n\nExit `0` means structurally valid with no declared blockers. Structural failure exits `3`; a valid brief with nonempty Blockers under Workflow or Agent Environment exits `4`. Input read failures exit `1`.\n\nWithout `--json`, ready status prints on stdout; errors and blockers print on stderr. With `--json`, stdout contains `valid`, `ready`, `errors`, and `blockers`. Blockers identify their parent section, heading line, and Markdown body. Input read errors still print on stderr.\n\n## Examples\n\n```sh\nfoundry check-workflow-brief workflow-brief.md\nfoundry check-workflow-brief workflow-brief.md --json\n```\n\n## Gotchas\n\n- Any content in `### Blockers` blocks work, including “none”. Omit or leave the section empty when there are no blockers. Comments and separators alone are empty.\n- The two Blockers sections are scoped to their respective Workflow and Agent Environment parents.\n- A clear check establishes document shape and absence of declared blockers. Expert review, semantic completeness, and observed tooling/container availability still need their own checks.\n- This command reads the document without editing it."
}
Validate the emitted brief before returning it.
Trigger: After writing workflow-brief.md.
references/cli/validate-workflow-brief.jsoncontent/cli/foundry/validate-workflow-brief.md{
"type": "cli-command",
"tool": "foundry",
"command": "validate-workflow-brief",
"summary": "Validate the title and required sections of a Markdown Workflow Brief.",
"source_path": "content/cli/foundry/validate-workflow-brief.md",
"source_revision": 3,
"package": "@galaxy-foundry/gxwf-foundry",
"description": "Validate a Workflow Brief Markdown document (experimental RFC).",
"synopsis": "foundry validate-workflow-brief <brief.md>",
"args": [
{
"raw": "brief.md",
"name": "brief.md",
"required": true,
"variadic": false
}
],
"options": [],
"body": "# `foundry validate-workflow-brief`\n\nValidate a Markdown document against the section contract described in [[workflow-brief-design]].\n\n## Output\n\nPrints `<path>: valid` to stdout on success (exit `0`). Missing, duplicate, or empty required sections produce diagnostics on stderr and exit `3`. Input read failures exit `1`.\n\n## Examples\n\n```sh\nfoundry validate-workflow-brief workflow-brief.md\n```\n\n## Gotchas\n\n- This checks the document title, required sections, their content, and parent-scoped subsections. It does not verify semantic completeness, expert approval, or environment readiness.\n- Headings inside code fences, block quotes, and HTML comments do not satisfy section requirements.\n- A valid brief may contain blockers. Use `foundry check-workflow-brief` to stop on workflow or environment blockers.\n- Additional sections, prose, tables, and explicit unknowns are allowed. Heading case and section order are flexible."
}
# freeform-summary-to-workflow-brief
Follow the procedure below and use the artifact/reference sections as the runtime contract.
## When To Use
- Turn a freeform source summary and selected scope into a Workflow Brief without Galaxy design assumptions.
## Inputs
- Read artifact `freeform-summary`. Produced by `interview-to-freeform-summary`, `summarize-paper`. Source evidence supplied by the preceding summarizer; preserve uncertainty and the caller’s selected scope.
## Outputs
- Write artifact `workflow-brief` as `workflow-brief.md`. Format: `markdown`. Schema: workflow-brief-schema. Expert-editable workflow intent and agent environment, with optional details and explicit workflow or environment blockers.
## Required Tools
- **`foundry`** (foundry). `npm install -g @galaxy-foundry/gxwf-foundry`.
Ephemeral run: `npx --package @galaxy-foundry/gxwf-foundry foundry`.
Check: `foundry --help`.
Docs: https://github.com/galaxyproject/foundry/blob/main/packages/gxwf-foundry/README.md
## Load Upfront
- `references/notes/workflow-brief-design.md`: Research note copied verbatim into the bundle. Apply the brief boundaries: evidence and expert intent, no inferred Galaxy design, and separate workflow/environment blockers.
- `references/schemas/workflow-brief-schema.schema.json`: Schema file copied verbatim into the bundle. Carry the Markdown section declaration and its structural validator.
## Load On Demand
- `references/cli/check-workflow-brief.json`: CLI command reference packaged as a sidecar. Report declared blockers separately from structural validity. Use when: after structural validation and before reporting whether the brief is clear of declared blockers.
- `references/cli/validate-workflow-brief.json`: CLI command reference packaged as a sidecar. Validate the emitted brief before returning it. Use when: after writing workflow-brief.md.
## Validation
- Validate `workflow-brief.md` before returning it: run `foundry validate-workflow-brief workflow-brief.md` from `@galaxy-foundry/gxwf-foundry`. If the command is not on PATH, run `npx --package @galaxy-foundry/gxwf-foundry foundry validate-workflow-brief workflow-brief.md`. This checks artifact `workflow-brief` against the workflow-brief-schema schema.
## Procedure
Read the narrative or interview-derived `freeform-summary` and emit a Workflow Brief for expert review.
### Evidence and scope
Read the source summary and the caller's stated objective and selection. Identify which scientific work is included and excluded; do not copy every source analysis into scope. If the selection is too ambiguous to proceed, state that uncertainty explicitly in Workflow/Blockers rather than choosing an analysis for the expert.
Write `workflow-brief.md` with `## Workflow`, `### Objective`, and `## Agent Environment`. Add optional subsections only when evidence or expert intent supports them. Identify the source and caller instructions, distinguish source facts from expert requirements, and keep scientific inputs, outputs, and acceptance criteria high-level. Missing optional detail does not require filler sections.
The writing agent must not infer Galaxy datatypes, collections, interface labels, available tools, or wrapper versions. It must not write step graphs, concrete tool states, or final test declarations. Named source tools and formats are evidence, not Galaxy choices. Explicit expert-provided Galaxy requirements may be recorded with attribution.
### Agent environment
Use supplied environment evidence or harmless availability/version probes to describe expected `gxwf`, `foundry`, and `planemo` tooling, agent constraints, container preferences, and Docker/Singularity/Apptainer usability. Distinguish requested requirements, observed facts, and unknowns. Do not claim a container engine works based only on an executable being on PATH. Do not install tools or change the environment as part of brief production.
Place known issues preventing work in `### Blockers` under the appropriate parent. Put nonblocking questions in Workflow/Open questions. Omit or leave Blockers empty when there are none; any text there, including “none”, is blocking.
### Validate and hand off
Run `foundry validate-workflow-brief workflow-brief.md`. Fix structural failures without inventing scientific intent. Run `foundry check-workflow-brief workflow-brief.md --json` and retain its result in the run report. Exit `4` means a valid but blocked brief: return that brief and its blockers for expert/environment resolution. Do not suppress the blockers to obtain a clear check.
Return the brief for expert editing and review. Producing a brief does not authorize Galaxy design or implementation, and a clear static check does not replace review or environment preflight. Keep source evidence available to the later consumer.
## 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.