docs(workflows): sync the reference copy with the shipped workflow (#4424)

docs/reference/workflows.md introduces its YAML block as the workflow that
ships with Spec Kit, so a reader is entitled to treat it as the real
definition. It had drifted on four points:

  version           1.0.0                      -> 1.0.1
  speckit_version   >=0.7.2                    -> >=0.8.5
  integrations.any  copilot, claude, gemini    -> also alquimia, opencode
  integration       default "copilot"          -> default "auto"

The last is the most user-visible: the guide stated the default integration
was copilot, when it is auto, resolved from the project's initialized
integration. Someone reading the guide to learn what they get by default was
being told the wrong thing.

Adds a guard so this cannot drift again. It compares parsed YAML rather than
text, so the guide stays free to format lists however reads best and only the
content has to agree. Verified it fails against the pre-sync copy, reporting
all four differences, and passes after.

Follow-up to #4384 / #4398, at the maintainer's suggestion.

Author: Yash-Chindam

docs/reference/workflows.md

@@ -431,14 +431,19 @@ schema_version: "1.0"
 workflow:
   id: "speckit"
   name: "Full SDD Cycle"
-  version: "1.0.0"
+  version: "1.0.1"
   author: "GitHub"
   description: "Runs specify → plan → tasks → implement with review gates"
 
 requires:
-  speckit_version: ">=0.7.2"
+  speckit_version: ">=0.8.5"
   integrations:
-    any: ["copilot", "claude", "gemini"]
+    any:
+      - "alquimia"
+      - "claude"
+      - "copilot"
+      - "gemini"
+      - "opencode"
 
 inputs:
   spec:
@@ -447,8 +452,8 @@ inputs:
     prompt: "Describe what you want to build"
   integration:
     type: string
-    default: "copilot"
-    prompt: "Integration to use (e.g. claude, copilot, gemini)"
+    default: "auto"
+    prompt: "Integration to use (e.g. claude, copilot, gemini; 'auto' uses the project's initialized integration)"
 
 steps:
   - id: specify

tests/workflows/test_bundled_speckit_workflow.py

@@ -8,9 +8,19 @@
 
 from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow
 
-BUNDLED = (
-    Path(__file__).resolve().parents[2] / "workflows" / "speckit" / "workflow.yml"
-)
+REPO_ROOT = Path(__file__).resolve().parents[2]
+BUNDLED = REPO_ROOT / "workflows" / "speckit" / "workflow.yml"
+REFERENCE_DOC = REPO_ROOT / "docs" / "reference" / "workflows.md"
+DOC_INTRO = "Here is the built-in **Full SDD Cycle** workflow that ships with Spec Kit:"
+
+
+def _documented_workflow() -> object:
+    """Return the workflow YAML the reference guide claims is the shipped one."""
+    text = REFERENCE_DOC.read_text(encoding="utf-8")
+    intro = text.index(DOC_INTRO)
+    start = text.index("```yaml", intro) + len("```yaml")
+    end = text.index("```", start)
+    return yaml.safe_load(text[start:end])
 
 
 def test_bundled_speckit_workflow_has_no_unused_scope_input() -> None:
@@ -30,3 +40,19 @@ def test_bundled_speckit_workflow_has_no_unused_scope_input() -> None:
         if args is None:
             continue
         assert "inputs.scope" not in str(args)
+
+
+def test_reference_doc_matches_the_shipped_workflow() -> None:
+    """The reference guide reproduces this workflow, so it must not drift from it.
+
+    ``docs/reference/workflows.md`` introduces its YAML block as the workflow
+    that ships with Spec Kit, so a reader is entitled to treat it as the real
+    definition. It had drifted on four points -- a stale ``version`` and
+    ``speckit_version``, a short ``integrations.any`` list, and an
+    ``integration`` default of ``copilot`` where the shipped default is
+    ``auto`` -- which is exactly the sort of thing nothing else would catch.
+
+    The comparison is on parsed YAML, not text, so the guide stays free to
+    format lists however reads best; only the content has to agree.
+    """
+    assert _documented_workflow() == yaml.safe_load(BUNDLED.read_text(encoding="utf-8"))