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

[One-TheOnly]

Summary

Enable specify workflow run to dispatch the cursor-agent CLI headlessly end-to-end on Windows, matching the way it already dispatches claude / codex / gemini. Existing in-IDE skill flow (via .cursor/skills/speckit-*/SKILL.md) is preserved exactly — this PR only adds the CLI dispatch path on top.

Fixes #2629.

Problem

Before this PR, specify workflow run speckit --input integration=cursor-agent ... fails immediately with:

Cannot dispatch command 'speckit.specify': integration 'cursor-agent' CLI not found or not installed.
Install the CLI tool or check 'specify integration list'.

even when cursor-agent is installed and healthy (cursor-agent --version returns 2026.05.16-0338208).

Three separate gaps each independently block the headless path; this PR fixes all three.

Three commits, three gaps

1) 1c55988 fix(cursor-agent): enable CLI dispatch via -p --trust headless mode

CursorAgentIntegration had requires_cli: False and did not override build_exec_args, so SkillsIntegration.build_exec_args returned None, the dispatcher in workflows/steps/command/__init__.py::_try_dispatch returned None, and the misleading CLI-missing error was surfaced. The CLI is actually fully headless-capable:

• -p / --print — print mode, "Has access to all tools, including write and shell"
• --output-format text | json | stream-json
• --model <name>
• --trust — "Trust the current workspace without prompting (only works with --print/headless mode)"

Without --trust, the CLI exits non-zero with ⚠ Workspace Trust Required.

This commit:

• config["requires_cli"]: False → True
• config["install_url"]: None → https://docs.cursor.com/en/cli/overview
• Override build_exec_args to emit [self.key, "-p", "--trust", prompt, …].

2) 454d3d0 fix(integrations): resolve .cmd/.bat shims before subprocess.run

After commit (1), the dispatcher still failed on Windows with FileNotFoundError [WinError 2]. Root cause:

• shutil.which("cursor-agent") returns cursor-agent.CMD (honoring PATHEXT).
• subprocess.run(["cursor-agent", ...]) calls CreateProcess, which does not consult PATHEXT, so the bare command name fails to launch.

The same bug affects every .cmd/.bat-wrapped CLI on Windows (verified for codex as well; only .exe CLIs like claude were unaffected).

Fix in IntegrationBase.dispatch_command: resolve exec_args[0] via shutil.which before subprocess.run. No-op on POSIX (no PATHEXT to consult); transparent fix on Windows.

3) 595bcab fix(cursor-agent): inject --approve-mcps --force for headless MCP/tool access

After commits (1)+(2), subprocess.run succeeds and cursor-agent starts, but the first MCP call (e.g. to read a DingTalk PRD) fails with The tool call was rejected. I can't retrieve the document name without permission to call the tool. Two more flags are needed:

• --approve-mcps — without it, every MCP server stays not loaded (needs approval) and tool calls are silently dropped.
• --force — without it, the agent halts on the first tool-call approval prompt; the workflow returns a misleading non-zero exit. With it, cursor-agent matches the implicit "trusted environment" semantics that claude -p and codex --exec already have by default — the right semantics for an unattended specify workflow run.

Final argv after all three commits:

args = [self.key, "-p", "--trust", "--approve-mcps", "--force", prompt]
if model: args.extend(["--model", model])
if output_json: args.extend(["--output-format", "json"])

End-to-end verification (real DingTalk PRD, just a URL as input)

Repro on Windows 10 + cursor-agent 2026.05.16-0338208:

cd D:\Code\MBM\MBM-Backend     # real Maven multi-module Java project
specify workflow run speckit `
  --input "spec=https://alidocs.dingtalk.com/i/nodes/<dingtalk-prd-node>" `
  --input "integration=cursor-agent" `
  --input "scope=full"

Two independent runs (df8c4b9b, 388d3c15) both reach the review-spec gate:

specify step:
  dispatched=true, exit_code=0, status=completed, duration ~156s / ~147s

agent behaviour (autonomously, from a URL-only spec input):
  - calls dingtalk-doc MCP get_document_content to fetch the PRD
  - reads project constitution + existing specs/ layout
  - decides specs/ subpath itself (e.g. specs/tooling/mold-assembly/202605/<feature>/)
  - produces spec.md (31.5 KB) + checklists/requirements.md
  - updates .specify/feature.json and specs/menu-dictionary.md
  - marks 3 [NEEDS CLARIFICATION] items for Gate 1 review

next step (review-spec gate):
  (gate started; status would be `paused` on a normal completion)

(Both runs above were eventually cancelled by Ctrl+C while the gate step was just starting, which surfaced an [Errno 22] Invalid argument from the interrupted subprocess.run. That was an artifact of my cancellation, not a gate-step bug — review-spec is a gate step and its designed terminal status is paused. Independent of this PR either way.)

Backward compatibility

• In-IDE skill flow (.cursor/skills/speckit-*/SKILL.md, --skills default) — unchanged.
• multi_install_safe, context_file, registrar_config, options() — unchanged.
• POSIX behaviour — shutil.which lookup is a no-op for already-absolute exec_args[0], and the --approve-mcps --force flags exist on Linux/macOS cursor-agent identically.
• catalog.json, workflow.yml, templates — untouched.
• Other integrations (claude, codex, gemini) — their build_exec_args paths are not touched; the only shared change is base.py::dispatch_command adding the shutil.which shim resolution, which only takes effect when shutil.which returns a different path than the input (i.e. .cmd/.bat shim case on Windows).

Testing

$ uv run python -m pytest tests/integrations/test_integration_cursor_agent.py -v
============================= 43 passed in 3.72s ==============================

$ uv run python -m pytest -q
========== 12 failed, 2867 passed, 109 skipped in 372.85s (0:06:12) ===========

• 43 cursor-agent integration tests pass (34 pre-existing + 9 new across all three commits).
• New tests pin:
  • requires_cli is True and install_url points at cursor.com
  • Exact argv layout [cursor-agent, -p, --trust, --approve-mcps, --force, …] (default + text-output + with-model variants)
  • All four mandatory headless flags are always present together
  • Hyphenated skill invocation (/speckit-plan not /speckit.plan)
  • .cmd shim resolution: subprocess receives full cursor-agent.CMD path, not bare cursor-agent
  • Passthrough when shutil.which returns None
• Existing tests/test_workflows.py::TestCommandStep::test_dispatch_with_mock_cli and test_dispatch_failure_returns_failed_status updated to patch shutil.which at the base.py layer (was previously only patching the dispatcher layer, which made the test environment-sensitive — passed on CI with no claude on PATH, failed locally with claude installed).
• Full repo: 2867 passed, 0 regressions from this PR. The 12 remaining pre-existing failures are unrelated Windows symlink privilege issues (WinError 1314) requiring elevated runner — not introduced or affected by this PR.

Out of scope (deliberately)

• The misleading "CLI not found or not installed. Install the CLI tool." error message itself (it conflates 5 distinct dispatch failure modes into one). Worth a separate PR to split per-failure-mode messages — happy to do that as a follow-up if maintainers want.
• Adding cursor-agent to bundled speckit workflow's requires.integrations.any list (currently ["copilot", "claude", "gemini"]). Not strictly required — specify workflow run does not enforce that list strictly today — but worth a follow-up so specify workflow info speckit is consistent with the actual support matrix.
• docs/reference/integrations.md page for cursor-agent (none exists today; happy to add if wanted).
• Adding a speckit.git.feature step to speckit workflow.yml (current workflow doesn't auto-create feature branches; that's by design but worth surfacing as an opt-in for teams that want branch-per-feature).

[Copilot]

Pull request overview

Enables specify workflow run to dispatch the cursor-agent integration via its CLI in a fully headless mode (including Windows .cmd/.bat shim support), aligning Cursor’s workflow-runner behavior with existing CLI-driven integrations.

Changes:

• Add explicit headless CLI argv construction for cursor-agent (-p --trust --approve-mcps --force, plus optional --model / JSON output).
• Fix Windows CLI dispatch by resolving .cmd/.bat shims via shutil.which() before calling subprocess.run().
• Update and add tests to pin the new behavior and make workflow dispatch tests environment-independent.

Show a summary per file

File	Description
src/specify_cli/integrations/cursor_agent/__init__.py	Adds cursor-agent CLI dispatch support and config updates (install URL / requires_cli).
src/specify_cli/integrations/base.py	Resolves executable via shutil.which() prior to subprocess.run() for Windows shim compatibility.
tests/integrations/test_integration_cursor_agent.py	Adds coverage for cursor-agent CLI argv shape and .cmd shim resolution behavior.
tests/test_workflows.py	Updates command-step tests to patch shutil.which at the new resolution layer and assert resolved executable path.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 4/4 changed files
• Comments generated: 1

[mnriem]

Please address Copilot feedback

[mnriem]

Please address code scanning resulsts

[One-TheOnly]

Thanks for the review! I've addressed both points in ff07cc0 + 422b250:

• Copilot (requires_cli): reverted requires_cli to False so specify init no longer hard-fails for IDE-only users. Dispatch support is now expressed by overriding build_exec_args() (same shape as CopilotIntegration), and the requires_cli guard in build_exec_args() is removed.
• CodeQL (URL substring): replaced the "cursor.com" in url substring check with an exact urlparse(...).hostname comparison, plus a regression test.

pytest tests/integrations/test_integration_cursor_agent.py is green (44 passed) and ruff check src/ is clean. Could you re-run the workflows when you get a chance?

[Copilot]

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 1

[mnriem]

Please address Copilot feedback

[One-TheOnly]

This autofix suggestion was applied.