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, skills, and gates via list_features before authoring, 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 persists an authored .workflow.md after validating it via the internal lintWorkflow function. The tool refuses to write when there are error-severity diagnostics — only warnings or clean output allows the save to proceed.

Under the hood, the tool uses the serializeWorkflow serializer (object → markdown) which covers all common workflow and stage fields. It is wired into SkillRegistry.saveWorkflow and is the recommended path for programmatic workflow persistence (as opposed to raw file writes that skip validation).

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:
list_features --kind gateGates for requiredGates: or stage gates:
describe_feature <name>Inspect any role/skill/gate 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 ​