[Feature]: Enable CLI dispatch for cursor-agent integration so 'specify workflow run' can drive Cursor headlessly

[One-TheOnly]

Summary

specify workflow run should be able to drive the cursor-agent CLI headlessly — the same way it already drives claude, codex, gemini, etc. — so that the full speckit workflow (specify → plan → tasks → implement) can run end-to-end against Cursor from the command line, in addition to the existing in-IDE skill flow.

Today this fails: the cursor-agent integration is configured with requires_cli: False and does not override build_exec_args, so the workflow dispatcher returns None and surfaces a misleading "CLI not found or not installed" error even when the CLI is installed and working.

A focused PR implementing this is open as #2631 (#2631).

Problem

When running:

specify workflow run speckit `
  --input "spec=some feature description" `
  --input "integration=cursor-agent" `
  --input "scope=full"

The first step fails with:

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

But:

1. cursor-agent CLI is installed and on PATH (cursor-agent --version → 2026.05.16-0338208, executable at C:\Users\eman\AppData\Local\cursor-agent\cursor-agent.cmd).
2. The CLI fully supports non-interactive / headless execution — cursor-agent --help shows -p / --print ("Has access to all tools, including write and shell"), --output-format text|json|stream-json, --model, --workspace, and --trust (mandatory in headless contexts).
3. cursor-agent -p --trust --output-format text "Say only the word OK" returns OK with exit code 0 in ~23 s on this machine.

Root cause

src/specify_cli/integrations/cursor_agent/__init__.py declares:

config = {
    ...,
    "install_url": None,
    "requires_cli": False,
}

and does not override build_exec_args. In src/specify_cli/workflows/steps/command/__init__.py, the dispatcher's _try_dispatch checks impl.build_exec_args("test") is None (line ~130) and returns None for cursor-agent, which the caller surfaces as the generic "CLI not found or not installed" message — even though the actual CLI is healthy.

In src/specify_cli/integrations/base.py, SkillsIntegration.build_exec_args only emits args when config["requires_cli"] is truthy, so flipping the flag alone is not quite enough — cursor-agent requires --trust for headless execution (without it the CLI exits non-zero with a "Workspace Trust Required" prompt), which the default [<key>, -p, <prompt>] template does not provide.

Expected behavior

specify workflow run should dispatch cursor-agent the same way it dispatches claude:

[cursor-agent, -p, --trust, /speckit-<name> <args>, --output-format json]

or, for streamed text output:

[cursor-agent, -p, --trust, /speckit-<name> <args>]

That argv shape is verified working against the current cursor-agent CLI release (2026.05.16-0338208).

Proposed fix (single-file, ~30 LOC)

In src/specify_cli/integrations/cursor_agent/__init__.py:

1. Set config["requires_cli"] = True.

2. Point config["install_url"] at https://docs.cursor.com/en/cli/overview.

3. Override build_exec_args to inject --trust after -p:

   def build_exec_args(self, prompt, *, model=None, output_json=True):
       if not self.config or not self.config.get("requires_cli"):
           return None
       args = [self.key, "-p", "--trust", prompt]
       if model:
           args.extend(["--model", model])
       if output_json:
           args.extend(["--output-format", "json"])
       return args

This is a strict addition: the existing in-IDE skill flow (via .cursor/skills/speckit-*/SKILL.md) continues to work unchanged, and the 34 existing test_integration_cursor_agent.py tests still pass.

A PR with the change plus 6 new tests that pin the argv shape, requires_cli, install_url, and the hyphenated /speckit-<name> skill invocation form is in flight.

Environment

• OS: Windows 10 (10.0.26200), PowerShell 7
• spec-kit (specify CLI): 0.8.7 and 0.8.11 (both reproduce; specify self upgrade did not fix)
• cursor-agent: 2026.05.16-0338208
• Workflow: bundled speckit (Full SDD Cycle v1.0.0)
• Python: 3.12.13 (under the specify-cli uv tool venv)

Why this matters

Cursor is one of the most prominent agent options users select with specify init --integration cursor-agent (auto-promoted from --ai cursor-agent). Today, every such user who tries specify workflow run hits a dead end with an error message that tells them to "install the CLI" — which is wrong (the CLI is already installed) and doesn't hint at the underlying integration-level limitation.

Enabling CLI dispatch closes the loop, makes the bundled speckit workflow usable end-to-end with Cursor from the terminal (mirroring the claude/codex/gemini story), and removes the misleading error.

Background context

PR #2156 (feat(cursor-agent): migrate commands to skills under .cursor/skills) intentionally moved cursor-agent commands into .cursor/skills/ as IDE skills, which is the right call for in-IDE usage. This change does not undo that — the SKILL.md install path is preserved exactly. It only adds a CLI dispatch path on top, so the same integration can be driven from inside the IDE or from specify workflow run, depending on what the user wants.