[Bug]: specify workflow run reports 'CLI not found' for cursor-agent integration which is IDE-only by design - misleading error message

[One-TheOnly]

Bug Description

When running specify workflow run speckit --input integration=cursor-agent ... (or with cursor-agent as the project's default integration), the runner 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'.

The message is misleading on two counts:

1. The cursor-agent CLI is installed (cursor-agent --version returns 2026.05.16-0338208 at C:\Users\eman\AppData\Local\cursor-agent\cursor-agent.cmd, and is on PATH).
2. After PR feat(cursor-agent): migrate commands to skills under .cursor/skills #2156 ("feat(cursor-agent): migrate commands to skills under .cursor/skills", merged 2026-04-10), the cursor-agent integration was redesigned to be IDE-only: the Cursor Agent inside the IDE reads .cursor/skills/speckit-*.md directly, and is not intended to be spawned by the CLI workflow runner.

specify integration list already marks cursor-agent as CLI Required = no (IDE), which is consistent with the new design. The runner's error message, however, still tells the user to "install the CLI tool", which is both wrong (already installed) and unhelpful (installing more CLIs cannot fix an integration that is IDE-only by design).

Steps to Reproduce

1. Install Spec Kit and initialize a project with the cursor-agent integration:

   uv tool install specify-cli --from "git+https://github.com/github/spec-kit.git@v0.8.11"
   specify init --here --integration cursor-agent

2. Verify the cursor-agent CLI is present and runnable:

   cursor-agent --version
   # 2026.05.16-0338208

3. Run the bundled speckit workflow with cursor-agent as the integration:

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

4. The first step speckit.specify fails immediately, and the workflow stops with Status: failed.

5. Inspect .specify/workflows/runs/<run_id>/log.jsonl:

   {
     "event": "step_failed",
     "step_id": "specify",
     "error": "Cannot dispatch command 'speckit.specify': integration 'cursor-agent' CLI not found or not installed. Install the CLI tool or check 'specify integration list'.",
     "timestamp": "..."
   }

Expected Behavior

When the requested integration is classified as CLI Required = no (IDE), the runner should produce a design-consistent, actionable error such as:

The 'cursor-agent' integration is IDE-only (per PR #2156) and cannot be dispatched by `specify workflow run`.
To use this workflow with cursor-agent, run the steps inside Cursor IDE by invoking the corresponding skill:
  - /speckit-specify
  - /speckit-plan
  - /speckit-tasks
  - /speckit-implement
Alternatively, install a CLI-capable integration (e.g. `claude`, `codex`, `gemini`) and pass `--input integration=<name>`.

Additionally, specify workflow info speckit (or a pre-flight check on specify workflow run) could surface that the project's default integration (cursor-agent) is not in the workflow's declared requires.integrations.any: ["copilot", "claude", "gemini"].

Actual Behavior

The runner fails with the misleading "CLI not found or not installed. Install the CLI tool" message above. There is no mention that cursor-agent is IDE-only, no mention of the /speckit-* skill alternative, and no hint of the requires.integrations.any mismatch.

To rule out a runner-wide problem, I installed the claude integration and re-ran the same workflow. The runner correctly dispatched claude CLI (the only failure was the actual CLI's own stderr, Credit balance is too low, which has nothing to do with dispatch). This confirms the workflow runner's dispatch chain is healthy for CLI Required = yes integrations; the failure is specific to the IDE-only classification of cursor-agent.

Specify CLI Version

0.8.7 and 0.8.11 — both reproduce. specify self upgrade 0.8.7 → 0.8.11 did not change the behavior, so the issue is present on the latest release at the time of writing.

AI Agent

Cursor

(cursor-agent CLI v2026.05.16-0338208, but per the new design the IDE Agent itself is the consumer of the speckit-* skills.)

Operating System

Windows 10 (10.0.26200), PowerShell 7

Python Version

Python 3.12.13 (installed by uv tool for the specify-cli virtualenv)

Error Logs

$ specify workflow run speckit --input "integration=cursor-agent" --input "spec=..." --input "scope=full"
Running workflow: Full SDD Cycle (speckit)
Version: 1.0.0
  ▸  speckit.specify …
Status: failed
Run ID: <id>

# .specify/workflows/runs/<id>/log.jsonl
{"event":"step_failed","step_id":"specify","error":"Cannot dispatch command 'speckit.specify': integration 'cursor-agent' CLI not found or not installed. Install the CLI tool or check 'specify integration list'.","timestamp":"..."}

Additional Context

Suggested fixes

1. Error message — When the requested integration has CLI Required = no (IDE), return the IDE-only message above instead of "CLI not found / install the CLI tool".

2. Documentation — In docs/reference/integrations.md, explicitly state that IDE-only integrations (currently cursor-agent, and presumably any future IDE-only ones) cannot be used with specify workflow run, and link to the manual /speckit-* skill flow.

3. workflow info / pre-flight — Show a compatibility note when the workflow's declared requires.integrations.any does not include the project's default integration. For speckit:

   requires:
     speckit_version: ">=0.7.2"
     integrations:
       any: ["copilot", "claude", "gemini"]

   cursor-agent is not listed, which is consistent with the IDE-only design post-feat(cursor-agent): migrate commands to skills under .cursor/skills #2156. A pre-flight warning would let users discover the mismatch before hitting the misleading dispatch error.

Related PRs / issues

• feat(cursor-agent): migrate commands to skills under .cursor/skills #2156 (feat(cursor-agent): migrate commands to skills under .cursor/skills) — the design decision behind this behavior.
• Slash‑commands ignored / arguments dropped when using Cursor CLI (cursor‑agent) — /speckit.* commands only send the command name #1264 (Slash-commands ignored / arguments dropped when using Cursor CLI) — a different downstream issue (not this one).
• Unable to init with cursor-agent #830, /speckit.specify error with cursor-agent #1094, spec-kit slash commands unavailable in cursor-agent #320, BUG - Cursor CLI - I understand the instructions, but I still don't see the actual feature description that should replace $ARGUMENTS. #798 — historical init / $ARGUMENTS issues, not related.

Importance

Users picking cursor-agent as the default integration (a prominent choice in the Cursor IDE) hit a dead end on their very first specify workflow run. The current error message actively misleads troubleshooting toward "install the CLI", which is both factually wrong and design-wise unhelpful.

[One-TheOnly]

Duplicate of #2629 — accidentally created by gh issue create --web racing the URL-too-long check (the API call succeeded before gh aborted on URL length). The same content was retained on #2629, which has since been reframed as a Feature Request, and the implementation is in PR #2631. Closing this one to avoid confusion.