fix: address review — integration defaults, integration_options, engine-owned dirs

- Apply DEFAULT_INIT_INTEGRATION fallback when neither step config nor
  workflow context provides an integration, so output.integration always
  reflects the actual integration used.
- Add integration_options config field to support --integration-options
  passthrough (required for generic integration and --skills mode).
- Exclude .specify/ from the non-empty directory fast-fail check so that
  here: true works when the engine has already created its run-state
  directory before steps execute.
- Note: mix_stderr=False is not needed — Click 8.2+ captures stderr
  separately by default and the existing try/except handles access.

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

Author: mnriem

src/specify_cli/workflows/steps/init/__init__.py

@@ -11,12 +11,19 @@
 import os
 from typing import Any
 
+from specify_cli._agent_config import DEFAULT_INIT_INTEGRATION
 from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
 from specify_cli.workflows.expressions import evaluate_expression
 
 #: Valid ``script`` values, mirroring ``specify init --script``.
 VALID_SCRIPT_TYPES = ("sh", "ps")
 
+#: Directories the workflow engine may create before steps run.
+#: These are excluded from the "non-empty directory" fast-fail check so
+#: that ``here: true`` works without requiring ``force: true`` when the
+#: only pre-existing content is engine run-state.
+_ENGINE_OWNED_DIRS = {".specify"}
+
 
 class InitStep(StepBase):
     """Bootstrap a project, equivalent to running ``specify init``.
@@ -47,7 +54,10 @@ class InitStep(StepBase):
         Initialize in the target directory instead of creating a new one.
     ``integration``
         Integration key (e.g. ``copilot``).  Defaults to the workflow's
-        default integration.
+        default integration, then to ``DEFAULT_INIT_INTEGRATION``.
+    ``integration_options``
+        Extra options for the integration (e.g. ``"--skills"`` or
+        ``"--commands-dir .myagent/cmds"``).
     ``script``
         Script type, ``sh`` or ``ps``.
     ``force``
@@ -67,7 +77,14 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
 
         integration = config.get("integration") or context.default_integration
         integration = self._resolve(integration, context)
+        # Apply the same default that specify init uses in non-interactive mode
+        # so that output.integration reflects the actual integration used.
+        if not integration:
+            integration = DEFAULT_INIT_INTEGRATION
 
+        integration_options = self._resolve(
+            config.get("integration_options"), context
+        )
         script = self._resolve(config.get("script"), context)
         preset = self._resolve(config.get("preset"), context)
 
@@ -95,7 +112,10 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             base = context.project_root or os.getcwd()
             try:
                 with os.scandir(base) as it:
-                    not_empty = any(it)
+                    not_empty = any(
+                        entry for entry in it
+                        if entry.name not in _ENGINE_OWNED_DIRS
+                    )
             except OSError:
                 not_empty = False
             if not_empty:
@@ -110,6 +130,7 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
                         "project": project,
                         "here": here,
                         "integration": integration,
+                        "integration_options": integration_options,
                         "script": script,
                         "exit_code": 1,
                         "stdout": "",
@@ -120,6 +141,8 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
 
         if integration:
             argv.extend(["--integration", str(integration)])
+        if integration_options:
+            argv.extend(["--integration-options", str(integration_options)])
         if script:
             argv.extend(["--script", str(script)])
         if preset:
@@ -136,6 +159,7 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             "project": project,
             "here": here,
             "integration": integration,
+            "integration_options": integration_options,
             "script": script,
             "exit_code": exit_code,
             "stdout": stdout,

tests/test_workflows.py

@@ -1072,6 +1072,62 @@ def test_non_empty_current_dir_without_force_fails_fast(self, tmp_path):
         assert "force: true" in (result.error or "")
         assert not (tmp_path / ".specify").exists()
 
+    def test_engine_owned_dirs_do_not_trigger_non_empty_check(self, tmp_path):
+        from specify_cli.workflows.steps.init import InitStep
+        from specify_cli.workflows.base import StepContext, StepStatus
+
+        # Simulate the engine creating its run-state directory before steps run
+        (tmp_path / ".specify" / "workflows" / "runs" / "abc123").mkdir(
+            parents=True
+        )
+
+        step = InitStep()
+        ctx = StepContext(
+            project_root=str(tmp_path), default_integration="copilot"
+        )
+        result = step.execute(
+            {"id": "bootstrap", "here": True, "script": "sh", "force": True},
+            ctx,
+        )
+        assert result.status == StepStatus.COMPLETED
+
+    def test_default_integration_when_none_provided(self, tmp_path):
+        from specify_cli.workflows.steps.init import InitStep
+        from specify_cli.workflows.base import StepContext, StepStatus
+
+        step = InitStep()
+        # No default_integration on context either
+        ctx = StepContext(project_root=str(tmp_path))
+        result = step.execute(
+            {"id": "bootstrap", "here": True, "script": "sh"},
+            ctx,
+        )
+        assert result.status == StepStatus.COMPLETED
+        assert result.output["integration"] == "copilot"
+
+    def test_integration_options_passed_through(self, tmp_path):
+        from specify_cli.workflows.steps.init import InitStep
+        from specify_cli.workflows.base import StepContext, StepStatus
+
+        step = InitStep()
+        ctx = StepContext(
+            project_root=str(tmp_path), default_integration="copilot"
+        )
+        result = step.execute(
+            {
+                "id": "bootstrap",
+                "here": True,
+                "script": "sh",
+                "integration": "copilot",
+                "integration_options": "--skills",
+            },
+            ctx,
+        )
+        assert result.status == StepStatus.COMPLETED
+        assert "--integration-options" in result.output["argv"]
+        assert "--skills" in result.output["argv"]
+        assert result.output["integration_options"] == "--skills"
+
     def test_validate_rejects_bad_script(self):
         from specify_cli.workflows.steps.init import InitStep
 

workflows/README.md

@@ -126,6 +126,7 @@ and resolves the integration from the step config or the workflow default:
   type: init
   here: true                 # or: project: my-project
   integration: copilot       # Optional: defaults to workflow integration
+  integration_options: "--skills"  # Optional: extra options for the integration
   script: sh                 # Optional: sh or ps
   force: true                # Optional: required to merge into a non-empty directory
   preset: healthcare-compliance   # Optional preset ID