kind: workflow
Defines a named, multi-step procedure compiled to provider-native workflow output or lowered to skill primitives per provider.
Defines a named, reusable multi-step procedure. All registered providers compile workflow resources; the output format depends on each provider's native workflow support and the active lowering strategy. Codex does not support kind: workflow — xcaffold emits a RENDERER_KIND_UNSUPPORTED fidelity note and produces no workflow output for that target.
Required:
kind,version,name
Source Directory
xcaf/workflows/<name>/workflow.xcafEach workflow is a directory-per-resource under xcaf/workflows/. The .xcaf file contains pure YAML fields for that workflow — there is no body section.
Example Usage
Basic workflow (inline instructions)
kind: workflow
version: "1.0"
name: run-component-audit
description: Audit all React components against conventions.
steps:
- name: audit
instructions: |
Run `xcaffold list --kind agent` to confirm the react-developer agent is active.
Then scan every file under `src/components/` and check:
1. All components use functional component syntax.
2. All components have a co-located `.test.tsx` file.
3. All props use `type`, not `interface`.
Report: "Audited <N> components. Found <M> violations."Multi-step workflow with skill references
kind: workflow
version: "1.0"
name: ship-feature
description: End-to-end workflow for shipping a new React component.
activation: always
steps:
- name: implement
skill: component-patterns
description: Build the component using the patterns skill.
- name: review
instructions: |
1. Run `pnpm lint` — zero ESLint errors.
2. Check every new component has a `.test.tsx`.
3. Confirm no `any` types appear in props.
- name: pr
instructions: |
1. Commit with: `feat(ui): add <ComponentName> component`
2. Push the branch and open a PR targeting `main`.Field Reference
Required Fields
| Field | Type | Description |
|---|---|---|
kind | string | Resource type. Must be workflow. |
version | string | File format version. Must be "1.0". |
name | string | Unique workflow identifier. Must match [a-z0-9-]+. |
Optional Fields
| Field | Type | Description |
|---|---|---|
activation | string | Controls rule generation. Set to "always" to emit an always-active rule, or provide a list of path globs. Omit for basic lowering (no rule). |
description | string | Human-readable description of what this workflow accomplishes. |
steps | []WorkflowStep | Ordered procedural steps. |
targets | map[string]TargetOverride | Per-provider overrides for compilation behavior. Does not restrict which providers compile this resource; to exclude a provider, set skip-synthesis: true within that provider's entry. |
steps entry
Each entry in steps supports:
| Field | Type | Description |
|---|---|---|
name | string | (Required) Step identifier. Used as a heading in the compiled output. |
description | string | (Optional) One-line step summary placed beneath the step heading in the compiled output. |
instructions | string | (Optional) Inline step content. Provide either instructions or skill, not both. |
skill | string | (Optional) Reference to an existing skill by name. The skill's compiled content is used as the step body. Provide either skill or instructions, not both. |
targets entry
Each entry in targets supports:
| Field | Type | Description |
|---|---|---|
skip-synthesis | bool | When true, excludes this provider from compilation entirely. |
suppress-fidelity-warnings | bool | When true, silences fidelity notes for this provider. |
provider | map[string]any | Opaque pass-through map for provider-specific directives. |
provider directives
The provider map accepts provider-specific keys. xcaffold recognizes:
| Key | Valid Values | Description |
|---|---|---|
lowering-strategy | prompt-file, custom-command, rule-plus-skill | Overrides the structure-inferred lowering strategy for this provider. |
promote-rules-to-workflows | true / false | Emits native workflow output instead of lowering to skill primitives. Used by Antigravity. |
Lowering Strategies
When a provider has no native workflow runtime, xcaffold lowers the workflow to compatible output files. The default lowering strategy is inferred from the workflow's structure:
- If any step references a
skill:→ orchestrator mode: a main skill plus one sub-skill per step. - If all steps use inline
instructions:→ basic mode: a single skill file with each step as a##-headed section.
When activation: is set, an additional rule primitive is emitted alongside the skill output.
| Strategy | Value | Applies To |
|---|---|---|
| Basic (default, all instructions) | (structure-inferred) | Claude, Cursor, Copilot, Gemini |
| Orchestrator (any skill ref) | (structure-inferred) | Claude, Cursor, Copilot, Gemini |
| Rule + skill (explicit) | rule-plus-skill | Claude, Cursor, Copilot, Gemini |
| Prompt file | prompt-file | Copilot |
| Custom command | custom-command | Gemini |
| Native (no lowering) | (always) | Antigravity (deprecated), Antigravity 2 |
| Unsupported | (fidelity note) | Codex |
To override the inferred strategy for a provider, set lowering-strategy inside targets.<provider>.provider:
targets:
copilot:
provider:
lowering-strategy: prompt-file
gemini:
provider:
lowering-strategy: custom-commandCompiled Output
Claude
Default strategy: basic mode (single skill with ##-headed step sections)
Output path (example: run-component-audit):
skills/run-component-audit/SKILL.md
When activation: is set, a rule is also emitted:
rules/run-component-audit-workflow.md— activation rule
workflow lowered to skill
Cursor
Default strategy: basic mode (single skill with ##-headed step sections)
Output path (example: run-component-audit):
skills/run-component-audit/SKILL.md
When activation: is set, a rule is also emitted:
rules/run-component-audit-workflow.mdc— activation rule
workflow lowered to skill
Copilot
Default strategy: basic mode (single skill with ##-headed step sections)
Output path (example: run-component-audit):
.github/skills/run-component-audit/SKILL.md
When activation: is set, a rule is also emitted:
.github/instructions/run-component-audit-workflow.instructions.md— activation rule
workflow lowered to skill
With lowering-strategy: prompt-file:
Output path: .github/prompts/run-component-audit.prompt.md
---
mode: agent
x-xcaffold:
compiled-from: workflow
workflow-name: run-component-audit
api-version: workflow/v1
---
...step instructions concatenated...Gemini
Default strategy: basic mode (single skill with ##-headed step sections)
Output paths (example: run-component-audit):
.gemini/skills/run-component-audit/SKILL.mdGEMINI.md— receives an@-import line referencing the skill
When activation: is set, a rule is also emitted:
.gemini/rules/run-component-audit-workflow.md— activation rule
workflow lowered to skill
With lowering-strategy: custom-command:
Output path: .gemini/commands/run-component-audit.md
...step instructions concatenated with blank lines between them...Antigravity (deprecated)
Deprecated. Antigravity (v1) is superseded by Antigravity 2. New projects should target
antigravity2. The v1 target remains supported for backwards compatibility.
Default output path: .agents/workflows/run-component-audit.md
Antigravity v1 always renders native workflow output. Steps are concatenated under ## <step-name> headers (level-2, no numbering).
## implement
...step instructions...
## review
...step instructions...
## pr
...step instructions...Antigravity 2
Default output path: .agents/workflows/run-component-audit.md
Antigravity 2 always renders native workflow output — no lowering occurs. Steps are concatenated under ## <step-name> headers (level-2, no numbering). A YAML frontmatter block is emitted with a description field derived from the workflow's description or name.
---
description: End-to-end workflow for shipping a new React component.
---
## implement
...step instructions...
## review
...step instructions...
## pr
...step instructions...When a step references a skill:, xcaffold emits Invoke /<skill-name>. as the step body. The runtime registers each workflow as a slash command.