Appearance

Workflow Authoring Capability ​

New in v0.37. agents-fleet ships a bundled workflow-authoring skill and fleet-workflow-architect role so agents can author, validate, and iterate on .workflow.md files with the full format spec in-context.

For the exhaustive workflow format reference, see Building Workflows. This page documents the authoring capability — the skill, role, validation command, scaffolding, saving, and recommended workflow.

What ships ​

workflow-authoring skill ​

A composable knowledge pack containing the complete .workflow.md authoring guide: file anatomy, all frontmatter and stage fields, the 5 runner types with a choice table, conditional edges (next:), forEach fan-out/fan-in, postChecks, completion, prompt-file conventions, the autopilot sub-coord dispatch ceremony, and the author → validate → fix loop.

Compose it into any role that needs to write workflows:

yaml
# in a .role.md or crew agent
skills: [workflow-authoring]

Or reference it in a workflow's requiredSkills::

yaml
requiredSkills: [workflow-authoring]

fleet-workflow-architect role ​

A coder-type agent persona that composes the workflow-authoring skill and enforces the author → validate → fix loop. It discovers reusable roles and skills via list_features before authoring, uses the workflow and gate references for validation requirements, always runs /wf validate on its output, and follows the autopilot dispatch ceremony for sub-coord workflows.

Spawn it explicitly:

/spawn fleet-workflow-architect "Design a release-prep autopilot workflow"

Or use it as an agents: entry in a workflow stage:

yaml
stages:
  - name: design-workflow
    agents: [fleet-workflow-architect]
    artifact: release-prep.workflow.md

Scaffolding ​

/wf scaffold <shape> <name> generates a lint-clean .workflow.md template for the given shape. All scaffolded files pass /wf validate by construction — no manual fixup required.

ShapeDescription
autopilotCanonical autopilot template with sub-coord dispatch ceremony
sequentialLinear multi-stage pipeline (explore → implement → verify)
conditionalA stage with conditional next edges (ifArtifact/ifResult → goto, else)
parallelFan-out/fan-in pattern (dispatch → analyze-a ‖ analyze-b → merge via after: [...])

Usage:

/wf scaffold sequential data-pipeline
/wf scaffold conditional triage-router
/wf scaffold parallel multi-repo-audit

The generated file is written to <cwd>/.fleet/workflows/<name>.workflow.md.

Saving authored workflows ​

The save_workflow coordinator tool accepts the full authored Markdown (frontmatter, stages, and body) in its content argument. It lints that content with lintWorkflow, refuses to write when error-severity diagnostics exist, then writes accepted content verbatim to <name>.workflow.md in the project or user tier. It does not serialize a workflow object or reformat the Markdown. Call reload_registry (or /wf reload) afterward so subsequent invocations use the saved definition; in-flight runs retain their dispatched snapshot.

The author → validate → fix loop ​

The recommended authoring cycle:

  1. Scaffold — /wf scaffold <shape> <name> generates a canonical template.
  2. Edit — fill in stages, params, edges, completion contract.
  3. Validate — /wf validate <file> runs the structural validator on the file. It checks frontmatter fields, stage shapes, edge predicates, forEach item sources, postCheck exclusivity, cycles/maxStageVisits consistency, and more.
  4. Fix — address every reported error, then re-run /wf validate.
  5. Reload — /wf reload hot-loads the workflow into the registry.
  6. Test — invoke the synthesized command and verify end-to-end.

Discovering reusable components ​

Before authoring, use the coordinator tools to discover what's available:

ToolPurpose
list_features --kind roleRoles to use as agents: entries
list_features --kind skillSkills to compose via requiredSkills:
Gate reference and /wf validateVerify names used by requiredGates: or stage gates:
describe_feature <name>Inspect a discovered role or skill in detail

/wf validate command ​

Syntax: /wf validate <file>

Runs the structural validator on a .workflow.md file without loading it into the registry. Reports all errors — frontmatter shape, stage field types, edge predicate validity, forEach/gather consistency, postCheck/postChecks mutual exclusion, cycles/maxStageVisits pairing, and reserved command names.

Dispatch-coherence lint ​

/wf validate also flags incoherent subcoord-dispatch wiring:

DiagnosticSeverityMeaning
dispatch-usage-missing-flagWARNINGA subcoord-dispatch member's command_usage omits --legacy-workflow-dispatch
dispatch-flag-without-membershipWARNINGA stage advertises --legacy-workflow-dispatch without being a subcoord-dispatch member

These warn about mismatches between the dispatch membership list and the flags advertised in each stage's command usage — helping catch copy-paste errors that silently break the bridged sub-coord path.

See the Commands Reference for the full /wf subcommand table.

Cross-references ​