[mnriem]

Description

Consolidates workflow documentation under docs/workflows/, following the preset documentation consolidation in #5223. Adds canonical overview, CLI, developing, API, steps, expressions, overlays, catalogs, and publishing pages, with site navigation and inbound links updated together.

Removes docs/reference/workflows.md, workflows/ARCHITECTURE.md, and workflows/PUBLISHING.md without forwarding stubs. Keeps workflows/README.md as a directory guide and retains contributor step-design guidance and the community step listing in their existing locations.

Consolidates duplicated guidance and corrects stale descriptions of workflow sources, validation, fan-out concurrency, execution internals, and catalog configuration. Preserves workflow-versus-step publishing paths, source-vetting guidance, JSON contracts, and resume semantics.

This is documentation-only, including documentation build configuration, source comments/docstrings, and documentation-test reference updates. Runtime behavior, bundled workflow definitions, catalogs, core prompts/templates, and submission automation are unchanged.

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

Validation:

• uv run specify --help — passed.
• LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests/test_catalog_trust_docs.py tests/test_workflows.py tests/workflows tests/specify_cli/workflows tests/contract/test_wheel_bundled_workflows.py -q — 2,362 passed, 29 skipped.
• LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests/test_catalog_trust_docs.py tests/workflows/test_bundled_speckit_workflow.py tests/test_workflow_step_submission.py -q — 281 passed.
• npx --no-install markdownlint-cli2 'docs/workflows/*.md' docs/README.md docs/community/workflow-steps.md docs/guides/customization.md docs/index.md docs/integrations/cli.md docs/integrations/docker-agent.md docs/reference/bundles.md docs/reference/catalogs.md docs/reference/overview.md — passed, no issues.
• docfx docs/docfx.json (session-local DocFX installation) — passed with the same three pre-existing warnings as the baseline.
• git diff --check — passed.

Also checked generated navigation and local links/anchors, parsed YAML/JSON examples, preserved the existing bundled-workflow parity and catalog-trust assertions, and confirmed executable Python statements are unchanged.

The full test suite and a sample-project agent process were not run for this documentation-only change.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Authored with GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), in autonomous agent mode with runtime-default reasoning settings and human-directed scope. AI assistance covered the approved documentation consolidation, source comparison, documentation corrections, navigation and reference updates, validation, commit preparation, and PR preparation. No runtime behavior was changed.

[Copilot]

🟡 Changes recommended

The catalog documentation inaccurately describes lookup, fetch-failure, and malformed-structure handling, which could mislead users about actual merge behavior and trust boundaries.

1 open issue

• Document catalog merge behavior and handling of malformed entries · New

What changed in this PR

Consolidates workflow documentation under docs/workflows/, updates navigation and inbound references, and removes superseded documentation. Runtime behavior remains unchanged.

Changes:

• Adds canonical workflow overview, CLI, API, steps, expressions, overlays, catalogs, development, and publishing guides.
• Updates DocFX configuration, repository links, source documentation references, design guidance, and documentation tests.
• Removes obsolete workflow architecture, publishing, and reference pages.

File	Description
workflows/​README.md	Reduced to a bundled workflow and catalog directory guide.
workflows/​PUBLISHING.md	Removed superseded publishing documentation.
workflows/​ARCHITECTURE.md	Removed superseded architecture documentation.
tests/​workflows/​test_bundled_speckit_workflow.py	Points workflow parity checks to the canonical developing guide.
tests/​test_workflows.py	Updates the documented error-handling contract reference.
tests/​test_catalog_trust_docs.py	Updates catalog trust documentation paths.
src/​specify_cli/​workflows/​overlay/​operations.py	Updates the overlay precedence documentation link.
src/​specify_cli/​workflows/​expressions/​filters.py	Updates the shell-safety documentation link.
src/​specify_cli/​workflows/​expressions/​engine.py	Updates the expression documentation link.
README.md	Repoints workflow, overlay, and custom-step links.
docs/​workflows/​steps.md	Adds step configuration, output, shell-safety, fan-out, and composition reference.
docs/​workflows/​publishing.md	Adds workflow and custom-step publishing guidance.
docs/​workflows/​overview.md	Adds the canonical workflow user guide and run/resume overview.
docs/​workflows/​overlays.md	Adds overlay composition, precedence, slots, and lifecycle documentation.
docs/​workflows/​expressions.md	Adds expression syntax, runtime context, typed values, and shell-safety guidance.
docs/​workflows/​developing.md	Adds workflow and custom-step authoring and validation guidance.
docs/​workflows/​cli.md	Adds workflow, overlay, step, and catalog CLI reference.
docs/​workflows/​catalogs.md	Adds catalog configuration, release, cache, and trust guidance.
docs/​workflows/​api.md	Adds YAML schema, step API, execution, persistence, resume, and error contracts.
docs/​toc.yml	Adds the consolidated workflow documentation section and removes the old reference entry.
docs/​reference/​workflows.md	Removes the superseded workflow reference page.
docs/​reference/​overview.md	Repoints workflow overview and CLI links.
docs/​reference/​catalogs.md	Repoints workflow catalog and publishing references.
docs/​reference/​bundles.md	Repoints shell-execution review guidance.
docs/​README.md	Lists the new workflow documentation pages.
docs/​integrations/​docker-agent.md	Repoints per-step integration configuration guidance.
docs/​integrations/​cli.md	Repoints workflow integration configuration guidance.
docs/​index.md	Repoints the main workflow documentation link.
docs/​guides/​customization.md	Repoints custom-step and workflow guidance.
docs/​docfx.json	Includes workflow pages in documentation builds.
docs/​community/​workflow-steps.md	Repoints custom-step authoring and installation references.
design/​workflow-step.md	Repoints workflow API, overview, and step-reference guidance.

_{Review effort: Lite (auto)}

[mnriem]

On behalf of @mnriem: corrected the workflow and step catalog guidance in commit c997a32 to describe merging all active catalogs for exact lookups, cache/fetch fallback, ignored malformed collections and entries, and the winning-source trust boundary. Added a documentation regression guard; runtime behavior is unchanged. Generated by GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), autonomous mode with runtime-default reasoning settings; AI assistance covered the documentation correction, regression test, validation, and this summary.

[Copilot]

🔵 Needs a closer look

Reviewer coverage is incomplete because one or more reviewers stopped when their runtime budget was exhausted.

No open issues 🎉

1 resolved since last review

• Document catalog merge behavior and handling of malformed entries

_{Review effort: Lite (auto)}

[Copilot]

🔵 Needs a closer look

The review cannot be considered complete because at least one reviewer was stopped by a runtime budget limit, leaving verification incomplete.

No open issues 🎉

_{Review effort: Lite (auto)}