fix(cursor-agent): enable headless CLI dispatch end-to-end (-p --trust --approve-mcps --force + Windows .cmd shim resolution)

src/specify_cli/integrations/base.py

@@ -202,6 +202,16 @@ def dispatch_command(
             )
             raise NotImplementedError(msg)
 
+        # Windows: ``subprocess.run`` calls ``CreateProcess`` which does not
+        # consult ``PATHEXT``, so a bare command name like ``cursor-agent``
+        # that resolves to ``cursor-agent.cmd`` fails with ``WinError 2``.
+        # Resolve via ``shutil.which`` (which does honor ``PATHEXT``) so
+        # ``.cmd``/``.bat`` shims work transparently.  On POSIX this is a
+        # no-op for absolute paths and a harmless lookup otherwise.
+        resolved = shutil.which(exec_args[0])
+        if resolved:
+            exec_args = [resolved, *exec_args[1:]]
+
         cwd = str(project_root) if project_root else None
 
         if stream:

src/specify_cli/integrations/cursor_agent/__init__.py

@@ -2,6 +2,10 @@
 
 Cursor Agent uses the ``.cursor/skills/speckit-<name>/SKILL.md`` layout.
 Commands are deprecated; ``--skills`` defaults to ``True``.
+
+CLI dispatch via ``cursor-agent -p --trust <prompt>`` is supported so
+``specify workflow run`` can drive cursor-agent headlessly, in addition
+to the existing in-IDE skill flow.
 """
 
 from __future__ import annotations
@@ -15,8 +19,8 @@ class CursorAgentIntegration(SkillsIntegration):
         "name": "Cursor",
         "folder": ".cursor/",
         "commands_subdir": "skills",
-        "install_url": None,
-        "requires_cli": False,
+        "install_url": "https://docs.cursor.com/en/cli/overview",
+        "requires_cli": True,
     }
     registrar_config = {
         "dir": ".cursor/skills",
@@ -28,6 +32,45 @@ class CursorAgentIntegration(SkillsIntegration):
     context_file = ".cursor/rules/specify-rules.mdc"
     multi_install_safe = True
 
+    def build_exec_args(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        output_json: bool = True,
+    ) -> list[str] | None:
+        """Build CLI arguments for non-interactive ``cursor-agent`` execution.
+
+        Mandatory headless flags:
+
+        * ``-p`` — print/headless mode (access to all tools)
+        * ``--trust`` — bypass Workspace Trust prompt (CLI exits non-zero
+          otherwise)
+        * ``--approve-mcps`` — auto-approve MCP server loading (otherwise
+          MCP servers stay ``not loaded (needs approval)`` and tool calls
+          to them are silently dropped)
+        * ``--force`` — auto-approve tool invocations (shell/write/MCP),
+          matching the implicit "trusted environment" semantics that other
+          integrations (``claude -p``, ``codex --exec``) get by default
+
+        Together these are the minimum set required to make
+        ``specify workflow run speckit --input integration=cursor-agent``
+        behave the same way as it does for ``claude`` / ``codex``.
+        Verified locally: with ``--approve-mcps --force`` the agent can
+        call any configured MCP server (e.g. ``dingtalk-doc``) and write
+        files during ``/speckit-*`` skill execution; without them the run
+        either drops tool calls or exits non-zero on the first approval
+        prompt.
+        """
+        if not self.config or not self.config.get("requires_cli"):
+            return None
+        args = [self.key, "-p", "--trust", "--approve-mcps", "--force", prompt]
+        if model:
+            args.extend(["--model", model])
+        if output_json:
+            args.extend(["--output-format", "json"])
+        return args
+
     @classmethod
     def options(cls) -> list[IntegrationOption]:
         return [

tests/integrations/test_integration_cursor_agent.py

@@ -106,3 +106,127 @@ def test_ai_cursor_agent_without_ai_skills_auto_promotes(self, tmp_path):
         assert result.exit_code == 0, f"init --ai cursor-agent failed: {result.output}"
         assert (target / ".cursor" / "skills" / "speckit-plan" / "SKILL.md").exists()
 
+
+class TestCursorAgentCliDispatch:
+    """Verify the CLI dispatch path for cursor-agent (issue #2629).
+
+    The ``cursor-agent`` CLI supports headless execution via ``-p`` (with
+    full tool access including write/shell) and requires ``--trust`` to
+    bypass the Workspace Trust prompt.  These tests pin the exact argv
+    shape that the workflow runner will use.
+    """
+
+    def test_requires_cli_is_true(self):
+        i = get_integration("cursor-agent")
+        assert i.config.get("requires_cli") is True
+
+    def test_install_url_is_set(self):
+        i = get_integration("cursor-agent")
+        url = i.config.get("install_url")
+        assert url is not None
+        assert "cursor.com" in url
+
+    def test_build_exec_args_default_includes_headless_flags_and_json(self):
+        """Default argv emits the full headless flag set: -p --trust
+        --approve-mcps --force, then prompt, then --output-format json.
+        """
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args("/speckit-specify some-feature")
+        assert args == [
+            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
+            "/speckit-specify some-feature",
+            "--output-format", "json",
+        ]
+
+    def test_build_exec_args_text_output_omits_format(self):
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args("/speckit-plan", output_json=False)
+        assert args == [
+            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
+            "/speckit-plan",
+        ]
+
+    def test_build_exec_args_with_model(self):
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args(
+            "/speckit-specify", model="sonnet-4-thinking", output_json=False
+        )
+        assert args == [
+            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
+            "/speckit-specify",
+            "--model", "sonnet-4-thinking",
+        ]
+
+    def test_build_exec_args_contains_mandatory_headless_flags(self):
+        """The four headless flags must always appear together.
+
+        ``--approve-mcps`` is required so MCP servers (e.g. dingtalk-doc)
+        actually load in headless mode; ``--force`` is required so the
+        agent doesn't block on tool-call approval prompts during the
+        speckit workflow.  Together with ``-p`` and ``--trust`` they
+        bring cursor-agent's headless behaviour in line with
+        ``claude -p`` / ``codex --exec`` from spec-kit's perspective.
+        """
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args("/speckit-implement", output_json=False)
+        for flag in ("-p", "--trust", "--approve-mcps", "--force"):
+            assert flag in args, f"missing mandatory headless flag: {flag}"
+
+    def test_build_command_invocation_uses_hyphenated_skill_name(self):
+        """SkillsIntegration: /speckit-plan (not /speckit.plan)."""
+        i = get_integration("cursor-agent")
+        assert i.build_command_invocation("speckit.plan", "feature-x") == "/speckit-plan feature-x"
+        assert i.build_command_invocation("plan") == "/speckit-plan"
+
+    def test_dispatch_command_resolves_cmd_shim_for_subprocess(self):
+        """``.cmd`` shims must be resolved to their full path before ``subprocess.run``.
+
+        ``cursor-agent`` (and other npm-installed CLIs on Windows) ship as
+        ``cursor-agent.cmd`` wrappers.  ``shutil.which`` honors ``PATHEXT``
+        and finds them, but Python's ``subprocess.run`` calls
+        ``CreateProcess`` which does **not** consult ``PATHEXT`` and fails
+        with ``WinError 2`` on a bare ``["cursor-agent", ...]`` argv.  The
+        fix in ``base.py::dispatch_command`` resolves ``exec_args[0]`` via
+        ``shutil.which`` so the full ``.cmd`` path is what reaches
+        ``CreateProcess``.
+        """
+        from unittest.mock import patch, MagicMock
+        i = get_integration("cursor-agent")
+
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = "ok"
+        mock_result.stderr = ""
+
+        fake_path = r"C:\Users\foo\AppData\Local\cursor-agent\cursor-agent.CMD"
+        with patch(
+            "specify_cli.integrations.base.shutil.which", return_value=fake_path
+        ), patch("subprocess.run", return_value=mock_result) as mock_run:
+            result = i.dispatch_command(
+                "speckit.plan", args="feature-x", stream=False, timeout=5
+            )
+
+        assert result["exit_code"] == 0
+        argv = mock_run.call_args[0][0]
+        assert argv[0] == fake_path, f"expected resolved .CMD path, got: {argv[0]!r}"
+        assert argv[1:6] == ["-p", "--trust", "--approve-mcps", "--force", "/speckit-plan feature-x"]
+
+    def test_dispatch_command_passthrough_when_shutil_which_finds_nothing(self):
+        """If ``shutil.which`` returns ``None``, leave argv unchanged so the
+        existing ``FileNotFoundError`` path remains observable to callers."""
+        from unittest.mock import patch, MagicMock
+        i = get_integration("cursor-agent")
+
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = ""
+        mock_result.stderr = ""
+
+        with patch(
+            "specify_cli.integrations.base.shutil.which", return_value=None
+        ), patch("subprocess.run", return_value=mock_result) as mock_run:
+            i.dispatch_command("speckit.plan", stream=False, timeout=5)
+
+        argv = mock_run.call_args[0][0]
+        assert argv[0] == "cursor-agent"
+

tests/test_workflows.py

@@ -555,15 +555,18 @@ def test_dispatch_with_mock_cli(self, tmp_path, monkeypatch):
         mock_result.stderr = ""
 
         with patch("specify_cli.workflows.steps.command.shutil.which", return_value="/usr/local/bin/claude"), \
+             patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \
              patch("subprocess.run", return_value=mock_result) as mock_run:
             result = step.execute(config, ctx)
 
         assert result.status == StepStatus.COMPLETED
         assert result.output["dispatched"] is True
         assert result.output["exit_code"] == 0
-        # Verify the CLI was called with -p and the skill invocation
+        # Verify the CLI was called with the resolved path (via shutil.which,
+        # which honors PATHEXT for ``.cmd``/``.bat`` shims on Windows), then
+        # ``-p`` and the skill invocation.
         call_args = mock_run.call_args
-        assert call_args[0][0][0] == "claude"
+        assert call_args[0][0][0] == "/usr/local/bin/claude"
         assert call_args[0][0][1] == "-p"
         # Claude is a SkillsIntegration so uses /speckit-specify
         assert "/speckit-specify login" in call_args[0][0][2]
@@ -592,6 +595,7 @@ def test_dispatch_failure_returns_failed_status(self, tmp_path):
         mock_result.stderr = "API error"
 
         with patch("specify_cli.workflows.steps.command.shutil.which", return_value="/usr/local/bin/claude"), \
+             patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \
              patch("subprocess.run", return_value=mock_result):
             result = step.execute(config, ctx)