π« Toolkit to help you get started with SDD or any other process!
"""Cursor IDE integration.
Cursor Agent uses the ``.cursor/skills/speckit-<name>/SKILL.md`` layout.
Commands are deprecated; ``--skills`` defaults to ``True``.
The IDE/skills flow is the primary path and works without the
``cursor-agent`` CLI being installed (``requires_cli=False``). Workflow
dispatch via ``cursor-agent -p --trust --approve-mcps --force <prompt>``
is offered as an opt-in capability β the presence of ``build_exec_args()``
is what indicates dispatch support, mirroring ``CopilotIntegration``.
"""
from __future__ import annotations
from pathlib import Path
from collections.abc import Mapping, Sequence
from typing import Any
from ..base import IntegrationOption, SkillsIntegration
class CursorAgentIntegration(SkillsIntegration):
key = "cursor-agent"
config = {
"name": "Cursor",
"folder": ".cursor/",
"commands_subdir": "skills",
"install_url": "https://docs.cursor.com/en/cli/overview",
# IDE-first integration: ``specify init --integration cursor-agent`` must
# work without the ``cursor-agent`` CLI installed (the IDE flow
# uses skills directly). Workflow dispatch additionally requires
# the CLI on PATH, but that's enforced at dispatch time via
# ``shutil.which`` rather than as a hard ``specify init`` precheck.
"requires_cli": False,
}
registrar_config = {
"dir": ".cursor/skills",
"format": "markdown",
"args": "$ARGUMENTS",
"extension": "/SKILL.md",
}
multi_install_safe = True
CANONICAL_TO_NATIVE = {
"session_start": "sessionStart",
"pre_tool_use": "preToolUse",
"post_tool_use": "postToolUse",
"session_end": "sessionEnd",
"user_prompt_submit": "beforeSubmitPrompt",
"stop": "stop",
}
events_config_file = ".cursor/hooks.json"
events_format = "json-flat"
# Cursor sessionStart injects a top-level additional_context (snake_case)
# field (C13). beforeSubmitPrompt has no context output field (block/allow
# only), and plain text on any hook fails Cursor's JSON parse β suppress
# everything else.
events_context_envelope = {
"*": "suppress",
"session_start": "additional_context",
}
def build_exec_args(
self,
prompt: str,
*,
model: str | None = None,
output_json: bool = True,
integration_args: Sequence[str] | None = None,
integration_options: Mapping[str, Any] | None = None,
project_root: Path | None = None,
) -> list[str] | None:
"""Build CLI arguments for non-interactive ``cursor-agent`` execution.
Always returns argv (no ``requires_cli`` guard) so workflow
dispatch is supported even though the integration's ``config``
sets ``requires_cli=False`` to keep the IDE-only flow unblocked.
This mirrors ``CopilotIntegration``: dispatch support is signalled
by overriding ``build_exec_args()``, not by the ``requires_cli``
flag (which is reserved for the ``specify init`` precheck).
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.
"""
self.validate_runtime_config(integration_args, integration_options)
args = [
self._resolve_executable(),
"-p",
"--trust",
"--approve-mcps",
"--force",
prompt,
]
self._apply_extra_args_env_var(args)
if model:
args.extend(["--model", model])
if output_json:
args.extend(["--output-format", "json"])
return args
@classmethod
def options(cls) -> list[IntegrationOption]:
opts = super().options()
opts.append(
IntegrationOption(
"--skills",
is_flag=True,
default=True,
help="Install as agent skills (recommended for Cursor)",
)
)
return opts