markitect-tool/docs/markdown-workflows.md

Markdown Workflows

Markitect workflows provide declarative orchestration for Markdown-centered document pipelines.

Use them when you want to:

• collect Markdown files, globs, or directories
• extract frontmatter, sections, blocks, metrics, or selector results
• bind named data products into later steps
• run deterministic template/compose/transform/include steps
• define optional assisted-generation boundaries without requiring a provider
• write one or more Markdown outputs with provenance and diagnostics

The workflow definition standard is documented in docs/workflow-definition-standard.md.

Commands

Inspect a workflow definition:

mkt workflow inspect examples/workflows/adr-release-notes.workflow.md

Plan a run without writing outputs:

mkt workflow plan examples/workflows/adr-release-notes.workflow.md

Run and write outputs:

mkt workflow run examples/workflows/adr-release-notes.workflow.md --output-dir build

JSON/YAML output is available for agents:

mkt workflow run workflow.md --format json

Execution Model

The first runner is deterministic and local-first:

1. Load a YAML or Markdown-fenced workflow definition.
2. Validate required ids/kinds and duplicate step ids.
3. Collect inputs from Markdown files, directories, globs, or literal values.
4. Resolve ${...} bindings.
5. Execute steps in dependency order.
6. Render outputs and enforce output path safety.
7. Return diagnostics, provenance, and trace events.

Assisted steps are explicit boundaries. Without an injected generation hook:

• optional assisted steps are skipped with a warning
• required assisted steps fail

This makes workflows useful without provider dependencies.

Supported Step Kinds

Kind	Result
shape	Structured data object.
extract	items, count, and joined text.
query	query matches and count.
template	rendered markdown, variables, missing variables, completion flag.
compose	composed markdown and sources.
transform	transformed markdown, operations, provenance.
include	include-resolved markdown, included paths, provenance.
contract_stub	generated contract stub Markdown.
contract_check	contract diagnostics, metrics, and optional runtime context results.
form_state	field values, origins, dynamic rule results, and diagnostics.
assisted	generated Markdown if a hook is supplied, otherwise skipped/diagnostic.

Data Bindings

Bindings use ${...}:

data:
  decisions: ${sources.adrs.extracts.decisions}
  summary: ${steps.render.markdown}

If the full string is one expression, the native type is preserved. If the expression appears inside a longer string, it is rendered as text.

List projection is supported:

paths: ${sources.adrs.items.path}

Relationship To Extensions

The workflow engine is registered as the built-in extension workflow.markdown-dataflow. It uses the canonical architecture for diagnostics, provenance, trace events, capabilities, and CLI affordance metadata, but workflow files remain business-facing orchestration artifacts.