docs: consolidate and correct workflow documentation (#5225)

* docs: consolidate and correct workflow documentation

Move workflow documentation into nine canonical docs/workflows pages, update navigation and inbound links, and preserve documentation regression assertions. Remove superseded pages without forwarding stubs; runtime behavior is unchanged.

Assisted-by: GitHub Copilot App (model: GPT-6.1 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs: correct workflow catalog merge and failure guidance

Describe full-catalog merging for exact lookups, fetch fallback, malformed entry handling, and winning-source trust boundaries. Add a documentation regression guard without changing runtime behavior.

Assisted-by: GitHub Copilot App (model: GPT-6.1 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: mnriem

README.md

@@ -49,9 +49,9 @@ Spec Kit combines ready-to-use processes with composable mechanisms:
 | Adapt templates, commands, terminology, or methodology | [Preset](https://github.github.io/spec-kit/presets/overview.html) |
 | Enforce organizational or regulatory standards | [Preset](https://github.github.io/spec-kit/presets/overview.html) |
 | Override a template for one project | [Project-local override](https://github.github.io/spec-kit/guides/customization.html#project-local-overrides-and-resolution) |
-| Automate prompts, commands, gates, and shell tasks | [Workflow](https://github.github.io/spec-kit/reference/workflows.html) |
-| Modify an installed workflow without forking it | [Workflow overlay](https://github.github.io/spec-kit/reference/workflows.html#workflow-overlays) |
-| Add reusable executable behavior to workflows | [Workflow step](https://github.github.io/spec-kit/reference/workflows.html#custom-step-packages) |
+| Automate prompts, commands, gates, and shell tasks | [Workflow](https://github.github.io/spec-kit/workflows/overview.html) |
+| Modify an installed workflow without forking it | [Workflow overlay](https://github.github.io/spec-kit/workflows/overlays.html) |
+| Add reusable executable behavior to workflows | [Workflow step](https://github.github.io/spec-kit/workflows/developing.html#custom-step-packages) |
 | Install a curated setup for a role or team | [Bundle](https://github.github.io/spec-kit/reference/bundles.html) |
 | Discover community components | [Catalog](https://github.github.io/spec-kit/reference/catalogs.html) |
 | Host a private catalog of approved components | [Catalog](https://github.github.io/spec-kit/reference/catalogs.html) |

design/workflow-step.md

@@ -4,8 +4,8 @@ A workflow step type defines what a `type:` in workflow YAML does. This is an
 extension point of the workflow engine, distinct from an agent integration:
 integrations dispatch work to an agent; steps validate and execute workflow
 behavior. For the overall engine, see
-[Workflow System Architecture](../workflows/ARCHITECTURE.md); for YAML usage,
-see [Workflows](../docs/reference/workflows.md).
+[Workflow API and execution model](https://github.github.io/spec-kit/workflows/api.html); for YAML usage,
+see [Workflows](https://github.github.io/spec-kit/workflows/overview.html).
 
 ## Delivery and registration
 
@@ -92,6 +92,6 @@ thread-safe, with per-run data in `config` and `context`, not on `self`.
    resume or nested/concurrent execution when relevant. Registry and engine
    coverage lives in `tests/test_workflows.py`; focused step suites may live
    under `tests/workflows/`.
-3. Update the [workflow reference](../docs/reference/workflows.md) when a
+3. Update the [workflow step reference](https://github.github.io/spec-kit/workflows/steps.html) when a
    built-in step changes the YAML users can write. Keep agent-specific CLI
    dispatch in integrations rather than duplicating it in step types.

docs/README.md

@@ -45,6 +45,15 @@ To build the documentation locally:
 - `presets/api.md` - Manifest, composition, and lifecycle reference
 - `presets/catalogs.md` - Preset catalog configuration, schemas, and trust
 - `presets/publishing.md` - Preset publishing and catalog submission guide
+- `workflows/overview.md` - Workflow user guide and run/review/resume walkthrough
+- `workflows/cli.md` - Workflow, overlay, step, and catalog CLI reference
+- `workflows/developing.md` - Workflow and custom-step authoring guide
+- `workflows/api.md` - YAML, step API, execution, and persisted-state contracts
+- `workflows/steps.md` - Built-in step configuration and outputs
+- `workflows/expressions.md` - Expression language, runtime context, and shell safety
+- `workflows/overlays.md` - Workflow composition through overlays and slots
+- `workflows/catalogs.md` - Workflow and step catalogs, releases, and trust
+- `workflows/publishing.md` - Workflow publishing and catalog submission guide
 - `community/extensions.md` - Community extension listing
 - `integrations/index.md` - Integration directory and shared setup guidance
 - `integrations/cli.md` - Shared integration management CLI reference

docs/community/workflow-steps.md

@@ -87,8 +87,9 @@ The package must satisfy the current installer and loader contract:
 - `.git`, `__pycache__`, and `.DS_Store` are excluded from installation;
   submission automation rejects case-insensitive aliases of these components.
 
-See [Custom step packages](../reference/workflows.md#custom-step-packages) for
-the complete install, validation, and runtime behavior.
+See [Custom step packages](../workflows/developing.md#custom-step-packages) for
+package validation and runtime behavior, and the
+[step installation reference](../workflows/cli.md#step-management) for installation.
 
 ## Submission Contract
 

docs/docfx.json

@@ -11,6 +11,7 @@
           "guides/*.md",
           "integrations/*.md",
           "presets/*.md",
+          "workflows/*.md",
           "reference/*.md",
           "install/*.md"
         ]

docs/guides/customization.md

@@ -26,8 +26,9 @@ agents and setup, or [contributing integrations](../integrations/contributing.md
 to develop an adapter.
 
 Workflow step packages extend the step types available to workflows. See
-[custom step packages](../reference/workflows.md#custom-step-packages) for
-installation and execution, and
+[custom step packages](../workflows/developing.md#custom-step-packages) for
+authoring and execution, the [step CLI](../workflows/cli.md#step-management)
+for installation, and
 [community workflow steps](../community/workflow-steps.md) for discovery and
 contribution guidance. Review executable packages before installing or using them.
 
@@ -117,4 +118,4 @@ for product manager, business analyst, security researcher, and developer setups
 Community components are independently maintained. Review source code before
 installation and use it at your own discretion. Visit the
 [community guide](../community/overview.md) to discover components or publish your
-own, and the [workflow reference](../reference/workflows.md) to automate a process.
+own, and the [workflow guide](../workflows/overview.md) to automate a process.

docs/index.md

@@ -78,7 +78,7 @@ Including entirely different processes:
 
 <a href="presets/overview.md" class="pillar-link">Presets →</a>&nbsp;&nbsp;
 <a href="extensions/overview.md" class="pillar-link">Extensions →</a>&nbsp;&nbsp;
-<a href="reference/workflows.md" class="pillar-link">Workflows →</a>&nbsp;&nbsp;
+<a href="workflows/overview.md" class="pillar-link">Workflows →</a>&nbsp;&nbsp;
 <a href="reference/bundles.md" class="pillar-link">Bundles →</a>
 
 </div>

docs/integrations/cli.md

@@ -480,7 +480,7 @@ parsed using POSIX shell quoting. Placement and duplicate-flag behavior differ
 by adapter; see the agent guide, especially for Docker Agent and Goose.
 
 Setup `--integration-options` are separate from workflow
-[`integration_args` and `integration_options`](../reference/workflows.md#per-step-integration-configuration).
+[`integration_args` and `integration_options`](../workflows/steps.md#per-step-integration-configuration).
 Adapters reject non-empty per-step configuration unless they implement it;
 Docker Agent currently exposes structured agent/safety configuration.
 Headless approval flags, model forwarding, and structured-output support are

docs/integrations/docker-agent.md

@@ -62,4 +62,4 @@ variable remains supported when no per-step reference is supplied. A per-step
 reference overrides the entire legacy value, including any flags it contains.
 Dispatch uses `run --exec`, adds requested `--json` and `--model` flags, and
 places the prompt after `--` so prompt text cannot become CLI options.
-See [per-step integration configuration](../reference/workflows.md#per-step-integration-configuration).
+See [per-step integration configuration](../workflows/steps.md#per-step-integration-configuration).

docs/reference/bundles.md

@@ -338,7 +338,7 @@ non-default source.
 For workflow components, inspect shell `run` and `env` fields and their
 referenced code, including changes introduced by active overlays. This applies
 even to `strict: true` steps: environment bindings can change executable lookup
-or runtime loading. See [Reviewing shell execution](workflows.md#reviewing-shell-execution).
+or runtime loading. See [Reviewing shell execution](../workflows/steps.md#reviewing-shell-execution).
 
 ### List the Catalog Stack