Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

4.9 KB
Raw Blame
"""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