# 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:

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

Plan a run without writing outputs:

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

Run and write outputs:

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

JSON/YAML output is available for agents:

```text
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 `${...}`:

```yaml
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:

```yaml
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.