generated from coulomb/repo-seed
104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# 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.
|