Skip to content

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

75.5 KB
Raw Blame
"""Base classes for AI-assistant integrations.

Provides:
- ``IntegrationOption`` β€” declares a CLI option an integration accepts.
- ``IntegrationBase`` β€” abstract base every integration must implement.
- ``MarkdownIntegration`` β€” concrete base for standard Markdown-format
  integrations (the common case β€” subclass, set three class attrs, done).
- ``TomlIntegration`` β€” concrete base for TOML-format integrations
  (Gemini, Tabnine β€” subclass, set three class attrs, done).
- ``SkillsIntegration`` β€” concrete base for integrations that install
  commands as agent skills (``speckit-<name>/SKILL.md`` layout).
"""

from __future__ import annotations

import os
import platform
import re
import shlex
import shutil
import subprocess
import sys
from abc import ABC
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, Any

import yaml

from .._invocation_style import get_invocation_prefix, is_dollar_skills_agent
from .._toml_string import escape_toml_basic as _escape_toml_basic
from .._toml_string import has_illegal_toml_control as _has_illegal_toml_control
from ..events import install_integration_events, remove_integration_events
from ._capture import run_captured

if TYPE_CHECKING:
    from .manifest import IntegrationManifest

_HOOK_COMMAND_NOTE = (
    "- When constructing command invocations from hook command names, "
    "replace dots (`.`) with hyphens (`-`). "
    "For example, `speckit.git.commit` β†’ `/speckit-git-commit`.\n"
)

_CORE_COMMAND_TEMPLATE_ORDER = (
    "analyze",
    "clarify",
    "constitution",
    "implement",
    "converge",
    "plan",
    "checklist",
    "specify",
    "tasks",
    "taskstoissues",
)
_CORE_COMMAND_TEMPLATE_RANK = {
    command: index for index, command in enumerate(_CORE_COMMAND_TEMPLATE_ORDER)
}


def yaml_quote(value: str) -> str:
    """Emit *value* as a double-quoted YAML scalar on a single line.

    A hand-rolled quote cannot carry raw newlines (YAML folds them to
    spaces) or control characters (the reader rejects them), so let the
    YAML emitter produce the escapes.
    """
    return yaml.safe_dump(
        str(value), default_style='"', allow_unicode=True, width=sys.maxsize
    ).strip()


def resolve_registrar_config(integration: IntegrationBase) -> dict[str, Any]:
    """Resolve static registrar overrides and integration-class defaults."""
    config = dict(integration.registrar_config or {})
    config.setdefault("invoke_separator", integration.invoke_separator)
    if integration.dev_no_symlink:
        config["dev_no_symlink"] = True
    return config


# ---------------------------------------------------------------------------
# IntegrationOption
# ---------------------------------------------------------------------------


@dataclass(frozen=True)
class IntegrationOption:
    """Declares an option that an integration accepts via ``--integration-options``.

    Attributes:
        name:      The flag name (e.g. ``"--commands-dir"``).
        is_flag:   ``True`` for boolean flags (``--skills``).
        required:  ``True`` if the option must be supplied.
        default:   Default value when not supplied (``None`` β†’ no default).
        help:      One-line description shown in ``specify integrate info``.
    """

    name: str
    is_flag: bool = False
    required: bool = False
    default: Any = None
    help: str = ""


# ---------------------------------------------------------------------------
# IntegrationBase β€” abstract base class
# ---------------------------------------------------------------------------


class IntegrationBase(ABC):
    """Abstract base class every integration must implement.

    Subclasses must set the following class-level attributes:

    * ``key``              β€” unique identifier, matches actual CLI tool name
    * ``config``           β€” dict compatible with ``AGENT_CONFIG`` entries
    * ``registrar_config`` β€” dict compatible with ``CommandRegistrar.AGENT_CONFIGS``

    And may optionally set:

    * ``invoke_separator`` β€” slash-command separator (defaults to ``"."``)
    * ``multi_install_safe`` β€” declare the integration safe to install
      alongside others (defaults to ``False``)
    """

    # -- Must be set by every subclass ------------------------------------

    key: str = ""
    """Unique integration key β€” should match the actual CLI tool name."""

    config: dict[str, Any] | None = None
    """Metadata dict matching the ``AGENT_CONFIG`` shape."""

    registrar_config: dict[str, Any] | None = None
    """Registration dict matching ``CommandRegistrar.AGENT_CONFIGS`` shape."""

    # -- Optional ---------------------------------------------------------

    invoke_separator: str = "."
    """Separator used in slash-command invocations (``"."`` β†’ ``/speckit.plan``)."""

    dev_no_symlink: bool = False
    """Whether dev-mode registration should write files instead of symlinks."""

    multi_install_safe: bool = False
    """Whether this integration is declared safe to install alongside others.

    Safe integrations must emit no files or use a static, unique agent root
    and command directory. Registry tests enforce these invariants.
    """

    legacy_flat_command_dir: str | None = None
    """Previous flat command directory retired after skill replacements exist."""

    legacy_flat_command_extension: str | None = None
    """File extension used by commands in ``legacy_flat_command_dir``."""

    def post_process_command_content(self, content: str) -> str:
        """Transform command content after format rendering.

        Called by ``register_commands()`` for non-skills format types
        (Markdown, TOML, YAML) after the command has been rendered into
        its target format and before writing to disk.  Skills-format
        agents use ``post_process_skill_content()`` instead.

        Subclasses may override to inject agent-specific content.
        The default implementation returns *content* unchanged.
        """
        return content

    # -- Public API -------------------------------------------------------

    @classmethod
    def options(cls) -> list[IntegrationOption]:
        """Return options this integration accepts. Default: none."""
        opts = []
        if bool(getattr(cls, "CANONICAL_TO_NATIVE", None) and getattr(cls, "events_config_file", None)):
            opts.append(
                IntegrationOption(
                    "--events",
                    is_flag=False,
                    default="true",
                    help="Enable/disable runtime events (true|false, default: true)",
                )
            )
        return opts

    def effective_invoke_separator(
        self,
        parsed_options: dict[str, Any] | None = None,
        project_root: Path | None = None,
    ) -> str:
        """Return the invoke separator for the given options.

        Subclasses whose separator depends on runtime options (e.g.
        Copilot in ``--skills`` mode) should override this method.
        The default implementation ignores *parsed_options* and
        *project_root* and returns the class-level ``invoke_separator``.
        """
        return self.invoke_separator

    def invoke_separator_for_mode(self, skills_enabled: bool) -> str:
        """Command-ref separator given the project's *resolved* skills state.

        Registration paths (extension / preset command rendering) have no CLI
        ``parsed_options`` β€” only the persisted ``ai_skills`` flag β€” so they
        resolve the command-reference separator through this hook rather than
        the static ``AGENT_CONFIGS[key]["invoke_separator"]`` value, which
        cannot represent an agent whose separator differs between its skills
        and command layouts.

        The default is mode-independent and returns exactly what
        ``_build_agent_configs`` would place in ``AGENT_CONFIGS`` (the
        ``registrar_config`` override if present, else the class-level
        ``invoke_separator``), so single-layout agents are unaffected.
        Dual-mode agents whose separator depends on the layout (e.g. Bob:
        ``-`` for skills, ``.`` for legacy commands) override this.
        """
        cfg = self.registrar_config or {}
        return cfg.get("invoke_separator", self.invoke_separator)

    def is_skills_mode(
        self,
        parsed_options: dict[str, Any] | None = None,
        project_root: Path | None = None,
    ) -> bool:
        """Return whether this integration scaffolds skills for these options.

        This is the single, well-defined hook the shared init/install/upgrade
        machinery consults to decide whether to persist ``ai_skills=True`` and
        render skill invocations.  It replaces ad-hoc ``isinstance`` /
        ``getattr(self, "_skills_mode", ...)`` probing so an integration's
        internal representation never has to leak into shared dispatch code.

        *project_root* is optional context for the ``use`` / ``switch`` /
        ``upgrade`` path, where no ``setup()`` runs and *parsed_options* may be
        empty: dual-mode integrations can consult the already-installed
        on-disk layout to avoid silently migrating an existing project to a
        different mode.  The default ignores it.

        The default for command-first integrations is skills mode only when
        ``--skills`` was requested.
        ``SkillsIntegration`` overrides this to return ``True`` by default;
        skills-first integrations that expose a legacy opt-out (e.g. Bob)
        override it to honor their own flag.
        """
        return bool((parsed_options or {}).get("skills"))

    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 execution.

        Returns a list of command-line tokens that will execute *prompt*
        non-interactively using this integration's CLI tool, or ``None``
        if the integration does not support CLI dispatch.

        Subclasses for CLI-based integrations should override this.
        """
        self.validate_runtime_config(integration_args, integration_options)
        return None

    def validate_runtime_config(
        self,
        integration_args: Sequence[str] | None = None,
        integration_options: Mapping[str, Any] | None = None,
    ) -> None:
        """Validate per-step CLI configuration for this integration.

        Runtime configuration is deliberately separate from :meth:`options`,
        which describes install-time ``--integration-options`` accepted by
        ``specify init`` and the integration management commands. Integrations
        opt in by overriding this hook and translating the validated values in
        :meth:`build_exec_args` (or a custom :meth:`dispatch_command`).

        The default accepts empty configuration for backward compatibility and
        rejects non-empty values instead of silently ignoring a misspelled or
        unsupported runtime option.
        """
        if integration_args:
            raise ValueError(
                f"Integration {self.key!r} does not support per-step "
                "'integration_args'."
            )
        if integration_options:
            option_names = ", ".join(sorted(str(key) for key in integration_options))
            raise ValueError(
                f"Integration {self.key!r} does not support per-step "
                f"'integration_options' ({option_names})."
            )

    def _resolve_executable(self) -> str:
        """Return the executable for this integration's CLI tool.

        Checks ``SPECKIT_INTEGRATION_<KEY>_EXECUTABLE`` first, allowing
        operators to override the binary path without modifying the
        integration configuration β€” useful when the tool is installed in
        a non-standard location or a specific version must be pinned.
        Hyphens in the integration key are replaced with underscores and
        the key is uppercased so that, for example, ``kiro-cli`` maps to
        ``SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE``.

        Falls back to ``self.key`` when the env var is unset or
        whitespace-only so existing behaviour is unchanged.

        See issue #2596.
        """
        env_name = (
            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXECUTABLE"
        )
        override = os.environ.get(env_name, "").strip()
        return override if override else self.key

    def _apply_extra_args_env_var(self, args: list[str]) -> None:
        """Append `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` env-var value to *args*.

        Operators can inject extra CLI flags into the spawned agent
        subprocess by setting an env var named for the integration key,
        e.g. `SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions"`.
        The `INTEGRATION` segment scopes the variable to this subsystem
        so it does not collide with other Spec Kit env-var namespaces.
        Hyphens in the integration key are replaced with underscores
        and the key is uppercased
        (e.g. `kiro-cli` β†’ `SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS`).

        Useful in CI / non-interactive contexts where the spawned agent
        needs flags that change its prompt-handling behaviour.
        Default behaviour (env var unset or whitespace-only) is a no-op
        β€” *args* is unchanged. Multi-token values are parsed via
        `shlex.split`.

        See issue #2595.
        """
        env_name = (
            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXTRA_ARGS"
        )
        extra = os.environ.get(env_name, "").strip()
        if not extra:
            return
        try:
            tokens = shlex.split(extra)
        except ValueError as exc:
            raise ValueError(
                f"{env_name} is not parseable as a POSIX-quoted command line "
                f"(value: {extra!r}). shlex reported: {exc}. "
                f"Use single or double quotes to group multi-word values, e.g. "
                f'{env_name}=\'--flag "value with spaces"\'.'
            ) from exc
        args.extend(tokens)

    def build_command_invocation(self, command_name: str, args: str = "") -> str:
        """Build the native slash-command invocation for a Spec Kit command.

        The CLI tools discover and execute commands from installed files
        on disk.  This method builds the invocation string the CLI
        expects β€” e.g. ``"/speckit.specify my-feature"`` for markdown
        agents or ``"/speckit-specify my-feature"`` for skills agents.

        *command_name* may be a full dotted name like
        ``"speckit.specify"``, an extension command like
        ``"speckit.git.commit"``, or a bare stem like ``"specify"``.
        """
        stem = command_name
        if stem.startswith("speckit."):
            stem = stem[len("speckit."):]

        invocation = f"/speckit.{stem}"
        if args:
            invocation = f"{invocation} {args}"
        return invocation

    def _build_dispatch_prompt(
        self,
        command_name: str,
        args: str,
        project_root: Path | None,
    ) -> str:
        """Return the dispatch prompt, given the target *project_root*.

        Seam for integrations whose invocation depends on the project's
        on-disk layout.  ``build_command_invocation()`` is a two-argument
        contract implemented by every integration, so widening it to carry a
        *project_root* would change a broad public surface for the sake of
        the one caller that needs it.  Dispatch is that caller: it alone
        knows which project the command is being run against, so dual-mode
        integrations (e.g. Bob) resolve the layout here instead.

        The default ignores *project_root* and preserves the previous
        behaviour exactly.

        See issue #4491.
        """
        return self.build_command_invocation(command_name, args)

    def dispatch_command(
        self,
        command_name: str,
        args: str = "",
        *,
        project_root: Path | None = None,
        model: str | None = None,
        timeout: int = 600,
        stream: bool = True,
        integration_args: Sequence[str] | None = None,
        integration_options: Mapping[str, Any] | None = None,
        output_json: bool | None = None,
        capture_max_bytes: int | None = None,
    ) -> dict[str, Any]:
        """Dispatch a Spec Kit command through this integration's CLI.

        By default this builds a slash-command invocation with
        ``_build_dispatch_prompt()`` -- which defers to
        ``build_command_invocation()`` unless the integration needs the
        *project_root* to decide -- and passes that prompt to
        ``build_exec_args()`` to construct the CLI command line.
        Integrations with custom dispatch behavior can override
        ``build_command_invocation()``, ``_build_dispatch_prompt()``,
        ``build_exec_args()``, or ``dispatch_command()`` directly.

        When *stream* is ``True`` (the default), stdout and stderr are
        piped directly to the terminal so the user sees live output.
        When ``False``, output is captured and returned in the dict.

        *output_json* selects the CLI's output format independently of
        *stream*. ``None`` (the default) keeps the historical coupling:
        text when streaming, structured output when capturing. Pass
        ``False`` with ``stream=False`` to capture the CLI's textual
        stdout.

        *capture_max_bytes* selects bounded capture and requires
        ``stream=False``: each stream is capped at that many raw bytes
        (``-1`` for no cap) and decoded as UTF-8. The result then also
        carries ``stdout_truncated``, ``stderr_truncated``, ``timed_out``,
        and ``interrupted``, and a timeout or interruption is reported
        there with the output read so far instead of being raised.
        ``None`` (the default) keeps the unbounded capture, which raises
        ``subprocess.TimeoutExpired``.

        Returns a dict with ``exit_code``, ``stdout``, and ``stderr``.
        Raises ``NotImplementedError`` if the integration does not
        support CLI dispatch.
        """
        import subprocess

        if stream and capture_max_bytes is not None:
            raise ValueError("capture_max_bytes requires stream=False.")

        self.validate_runtime_config(integration_args, integration_options)
        prompt = self._build_dispatch_prompt(command_name, args, project_root)
        # When streaming to the terminal, request text output so the
        # user sees readable output instead of raw JSONL events.
        if output_json is None:
            output_json = not stream
        exec_args = self.build_exec_args(
            prompt,
            model=model,
            output_json=output_json,
            integration_args=integration_args,
            integration_options=integration_options,
            project_root=project_root,
        )

        if exec_args is None:
            msg = (
                f"Integration {self.key!r} does not support CLI dispatch. "
                f"Override build_exec_args() to enable it."
            )
            raise NotImplementedError(msg)

        # Windows: ``subprocess.run`` calls ``CreateProcess`` which does not
        # consult ``PATHEXT``, so a bare command name like ``cursor-agent``
        # that resolves to ``cursor-agent.cmd`` fails with ``WinError 2``.
        # Resolve via ``shutil.which`` (which does honor ``PATHEXT``) so
        # ``.cmd``/``.bat`` shims work transparently.  On POSIX this is a
        # no-op for absolute paths and a harmless lookup otherwise.
        resolved = shutil.which(exec_args[0])
        if resolved:
            exec_args = [resolved, *exec_args[1:]]

        cwd = str(project_root) if project_root else None

        if stream:
            # No timeout when streaming β€” the user sees live output and
            # can Ctrl+C at any time.  The timeout parameter is only
            # applied in the captured (non-streaming) branch below.
            try:
                result = subprocess.run(
                    exec_args,
                    text=True,
                    cwd=cwd,
                )
            except KeyboardInterrupt:
                return {
                    "exit_code": 130,
                    "stdout": "",
                    "stderr": "Interrupted by user",
                }
            return {
                "exit_code": result.returncode,
                "stdout": "",
                "stderr": "",
            }

        if capture_max_bytes is not None:
            return run_captured(
                exec_args,
                cwd=cwd,
                timeout=timeout,
                max_bytes=capture_max_bytes,
            ).as_dispatch_result()

        result = subprocess.run(
            exec_args,
            capture_output=True,
            text=True,
            cwd=cwd,
            timeout=timeout,
        )
        return {
            "exit_code": result.returncode,
            "stdout": result.stdout,
            "stderr": result.stderr,
        }

    # -- Primitives β€” building blocks for setup() -------------------------

    def shared_commands_dir(self) -> Path | None:
        """Return path to the shared command templates directory.

        Checks ``core_pack/commands/`` (wheel install) first, then
        ``templates/commands/`` (source checkout).  Returns ``None``
        if neither exists.
        """
        import inspect

        pkg_dir = Path(inspect.getfile(IntegrationBase)).resolve().parent.parent
        for candidate in [
            pkg_dir / "core_pack" / "commands",
            pkg_dir.parent.parent / "templates" / "commands",
        ]:
            if candidate.is_dir():
                return candidate
        return None

    def shared_templates_dir(self) -> Path | None:
        """Return path to the shared page templates directory.

        Contains ``vscode-settings.json``, ``spec-template.md``, etc.
        Checks ``core_pack/templates/`` then ``templates/``.
        """
        import inspect

        pkg_dir = Path(inspect.getfile(IntegrationBase)).resolve().parent.parent
        for candidate in [
            pkg_dir / "core_pack" / "templates",
            pkg_dir.parent.parent / "templates",
        ]:
            if candidate.is_dir():
                return candidate
        return None

    def list_command_templates(self) -> list[Path]:
        """Return ordered list of command template files from the shared directory."""
        cmd_dir = self.shared_commands_dir()
        if not cmd_dir or not cmd_dir.is_dir():
            return []
        return sorted(
            (f for f in cmd_dir.iterdir() if f.is_file() and f.suffix == ".md"),
            key=lambda f: (
                _CORE_COMMAND_TEMPLATE_RANK.get(
                    f.stem, len(_CORE_COMMAND_TEMPLATE_ORDER)
                ),
                f.name,
            ),
        )

    def command_filename(self, template_name: str) -> str:
        """Return the destination filename for a command template.

        *template_name* is the stem of the source file (e.g. ``"plan"``).
        Default: ``speckit.{template_name}.md``.  Subclasses override
        to change the extension or naming convention.
        """
        return f"speckit.{template_name}.md"

    def stale_cleanup_exclusions(self) -> set[str]:
        """Return project-relative paths that upgrade must never stale-delete.

        During ``integration upgrade``, files recorded in a previous manifest
        but absent from the freshly written one are treated as stale and
        removed.  Conditionally-tracked files (e.g. a settings file that the
        integration merges into when it already exists, and therefore stops
        tracking) would otherwise be deleted even though they are still
        managed.  Subclasses list such paths here to protect them.
        """
        exclusions = set()
        if self.supports_events():
            from ..events import events_stale_exclusions
            exclusions.update(events_stale_exclusions(self.key))
        return exclusions

    def commands_dest(self, project_root: Path) -> Path:
        """Return the absolute path to the commands output directory.

        Derived from ``config["folder"]`` and ``config["commands_subdir"]``.
        Raises ``ValueError`` if ``config`` or ``folder`` is missing.
        """
        if not self.config:
            raise ValueError(
                f"{type(self).__name__}.config is not set; integration "
                "subclasses must define a non-empty 'config' mapping."
            )
        folder = self.config.get("folder")
        if not folder:
            raise ValueError(
                f"{type(self).__name__}.config is missing required 'folder' entry."
            )
        subdir = self.config.get("commands_subdir", "commands")
        return project_root / folder / subdir

    # -- File operations β€” granular primitives for setup() ----------------

    @staticmethod
    def copy_command_to_directory(
        src: Path,
        dest_dir: Path,
        filename: str,
    ) -> Path:
        """Copy a command template to *dest_dir* with the given *filename*.

        Creates *dest_dir* if needed.  Returns the absolute path of the
        written file.  The caller can post-process the file before
        recording it in the manifest.
        """
        dst = dest_dir / filename
        from ._file_changes import after_file_change, before_file_change

        before_file_change(dst)
        dest_dir.mkdir(parents=True, exist_ok=True)
        shutil.copy2(src, dst)
        after_file_change(dst)
        return dst

    @staticmethod
    def record_file_in_manifest(
        file_path: Path,
        project_root: Path,
        manifest: IntegrationManifest,
    ) -> None:
        """Hash *file_path* and record it in *manifest*.

        *file_path* must be inside *project_root*.
        """
        rel = file_path.resolve().relative_to(project_root.resolve())
        manifest.record_existing(rel)

    @staticmethod
    def write_file_and_record(
        content: str,
        dest: Path,
        project_root: Path,
        manifest: IntegrationManifest,
    ) -> Path:
        """Write *content* to *dest*, hash it, and record in *manifest*.

        Creates parent directories as needed.  Writes bytes directly to
        avoid platform newline translation (CRLF on Windows).  Any
        ``\r\n`` sequences in *content* are normalised to ``\n`` before
        writing.  Returns *dest*.
        """
        normalized = content.replace("\r\n", "\n")
        from ._file_changes import after_file_change, before_file_change

        before_file_change(dest)
        dest.parent.mkdir(parents=True, exist_ok=True)
        dest.write_bytes(normalized.encode("utf-8"))
        after_file_change(dest)
        rel = dest.resolve().relative_to(project_root.resolve())
        manifest.record_existing(rel)
        return dest

    def integration_scripts_dir(self) -> Path | None:
        """Return path to this integration's bundled ``scripts/`` directory.

        Looks for a ``scripts/`` sibling of the module that defines the
        concrete subclass (not ``IntegrationBase`` itself).
        Returns ``None`` if the directory doesn't exist.
        """
        import inspect

        cls_file = inspect.getfile(type(self))
        scripts = Path(cls_file).resolve().parent / "scripts"
        return scripts if scripts.is_dir() else None

    def install_scripts(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
    ) -> list[Path]:
        """Copy integration-specific scripts into the project.

        Copies files from this integration's ``scripts/`` directory to
        ``.specify/integrations/<key>/scripts/`` in the project.  Shell
        (``.sh``) and Python (``.py``) scripts are made executable.  All
        copied files are recorded in *manifest*.

        Returns the list of files created.
        """
        scripts_src = self.integration_scripts_dir()
        if not scripts_src:
            return []

        from ._file_changes import before_file_change

        created: list[Path] = []
        scripts_dest = project_root / ".specify" / "integrations" / self.key / "scripts"

        for src_script in sorted(scripts_src.iterdir()):
            if not src_script.is_file():
                continue
            dst_script = scripts_dest / src_script.name
            before_file_change(dst_script)
            scripts_dest.mkdir(parents=True, exist_ok=True)
            shutil.copy2(src_script, dst_script)
            if dst_script.suffix in (".sh", ".py"):
                dst_script.chmod(dst_script.stat().st_mode | 0o111)
            self.record_file_in_manifest(dst_script, project_root, manifest)
            created.append(dst_script)

        return created

    @staticmethod
    def resolve_command_refs(
        content: str, separator: str = ".", prefix: str = "/"
    ) -> str:
        """Replace ``__SPECKIT_COMMAND_<NAME>__`` placeholders with invocations.

        Each placeholder encodes a command name in upper-case with
        underscores (e.g. ``__SPECKIT_COMMAND_PLAN__``,
        ``__SPECKIT_COMMAND_GIT_COMMIT__``).  The replacement uses
        *separator* to join the segments:

        * ``separator="."`` β†’ ``/speckit.plan``, ``/speckit.git.commit``
        * ``separator="-"`` β†’ ``/speckit-plan``, ``/speckit-git-commit``

        A hyphen belongs to the segment it sits in rather than separating
        segments, so ``__SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__`` resolves to
        ``/speckit.agent-context.update``.

        *prefix* defaults to ``"/"`` but may be ``"$"`` for agents whose
        native skills invocation uses dollar-prefixed chat commands.
        """
        return re.sub(
            r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_-]*)__",
            lambda m: prefix
            + "speckit"
            + separator
            + m.group(1).lower().replace("_", separator),
            content,
        )

    @staticmethod
    def resolve_python_interpreter(project_root: Path | None = None) -> str:
        """Resolve a portable Python interpreter command for ``{SCRIPT}``.

        Used to build the invocation string for the ``py`` script type so
        that ``.py`` workflow scripts run consistently across platforms
        (notably Windows, where ``.py`` files are not directly executable).

        Resolution order:

        1. A project virtual environment (``.venv``) interpreter, if one
           exists under *project_root* (POSIX ``bin/python`` or Windows
           ``Scripts/python.exe``).  The returned path is **relative to the
           project root** (e.g. ``.venv/bin/python``) so generated
           ``{SCRIPT}`` invocations stay portable and runnable from the
           repo root regardless of where the project lives.
        2. ``python3`` on ``PATH``.
        3. ``python`` on ``PATH``.

        Falls back to the running interpreter (``sys.executable``) when
        ``PATH`` resolution fails so the generated command is guaranteed
        to work in the current environment, and finally to ``"python3"``
        if even that is unavailable.
        """
        if project_root is not None:
            # (existence check path, repo-root-relative invocation string)
            venv_candidates = (
                (project_root / ".venv" / "bin" / "python", ".venv/bin/python"),
                (
                    project_root / ".venv" / "Scripts" / "python.exe",
                    ".venv/Scripts/python.exe",
                ),
            )
            for candidate, relative in venv_candidates:
                if candidate.exists():
                    return relative
        for name in ("python3", "python"):
            found = shutil.which(name)
            if not found:
                continue
            # On Windows, python3/python on PATH may be the Microsoft
            # Store App Execution Alias stub: it exists but only prints
            # an installer hint and exits non-zero, so existence is not
            # enough (see #3304 for the same defect in the sh scripts).
            if sys.platform == "win32" and not IntegrationBase._interpreter_runs(
                found
            ):
                continue
            return name
        return sys.executable or "python3"

    @staticmethod
    def build_python_invocation(
        script_command: str, project_root: Path | None = None
    ) -> str:
        """Build a Python script command for the current platform shell."""
        interpreter = IntegrationBase.resolve_python_interpreter(project_root)
        if os.name == "nt" and not re.fullmatch(r"[A-Za-z0-9_./:\\-]+", interpreter):
            quoted_interpreter = interpreter.replace("'", "''")
            interpreter = f"& '{quoted_interpreter}'"
        elif os.name != "nt":
            interpreter = shlex.quote(interpreter)
        return f"{interpreter} {script_command}"

    @staticmethod
    def select_script_variant(
        requested: object, script_commands: dict[str, str]
    ) -> str:
        """Select the requested variant or a runnable platform fallback."""
        if isinstance(requested, str) and requested in script_commands:
            return requested

        platform_variant = (
            "ps" if platform.system().lower().startswith("win") else "sh"
        )
        secondary_variant = "sh" if platform_variant == "ps" else "ps"
        fallbacks = (
            (platform_variant, "py")
            if requested == "py"
            else (platform_variant, secondary_variant, "py")
        )
        for candidate in fallbacks:
            if candidate in script_commands:
                return candidate

        available = ", ".join(sorted(script_commands)) or "none"
        raise ValueError(
            "No runnable script variant for this platform: "
            f"requested {requested!r}; available: {available}"
        )

    @staticmethod
    def _interpreter_runs(path: str) -> bool:
        """Return True when *path* executes as a Python interpreter.

        Runs isolated (``-I``) without ``site`` (``-S``) and discards
        I/O so the probe is a fast liveness check that cannot trigger
        ``sitecustomize``/user startup hooks.
        """
        try:
            return (
                subprocess.run(
                    [path, "-I", "-S", "-c", ""],
                    stdin=subprocess.DEVNULL,
                    stdout=subprocess.DEVNULL,
                    stderr=subprocess.DEVNULL,
                    timeout=15,
                ).returncode
                == 0
            )
        except (OSError, subprocess.SubprocessError):
            return False

    @staticmethod
    def process_template(
        content: str,
        agent_name: str,
        script_type: str,
        arg_placeholder: str = "$ARGUMENTS",
        invoke_separator: str = ".",
        project_root: Path | None = None,
    ) -> str:
        """Process a raw command template into agent-ready content.

        Performs the same transformations as the release script:
        1. Select ``scripts.<script_type>`` from YAML frontmatter, falling
           back to a runnable platform shell or Python variant when unavailable
        2. Replace ``{SCRIPT}`` with the extracted script command
        3. Strip ``scripts:`` section from frontmatter
        4. Replace ``{ARGS}`` and ``$ARGUMENTS`` with *arg_placeholder*
        5. Replace ``__AGENT__`` with *agent_name*
        6. Rewrite paths: ``scripts/`` β†’ ``.specify/scripts/`` etc.
        7. Replace ``__SPECKIT_COMMAND_<NAME>__`` with invocation strings
        """
        # 1. Extract script command from frontmatter
        script_commands: dict[str, str] = {}
        script_pattern = re.compile(r"^\s*([A-Za-z0-9_-]+):\s*(.+)$")
        # Find the scripts: block
        in_frontmatter = False
        in_scripts = False
        for line in content.splitlines():
            if line == "---":
                if in_frontmatter:
                    break
                in_frontmatter = True
                continue
            if not in_frontmatter:
                continue
            if line == "scripts:":
                in_scripts = True
                continue
            if in_scripts and line and not line[0].isspace():
                break
            if in_scripts:
                m = script_pattern.match(line)
                if m:
                    script_commands[m.group(1)] = m.group(2).strip()

        selected_script_type = (
            IntegrationBase.select_script_variant(script_type, script_commands)
            if script_commands
            else ""
        )

        script_command = script_commands.get(selected_script_type, "")

        # 2. Replace {SCRIPT}
        if script_command:
            # For the Python script type, prefix the resolved interpreter so
            # the command is portable (``.py`` files are not directly
            # executable on Windows).
            if selected_script_type == "py":
                script_command = IntegrationBase.build_python_invocation(
                    script_command, project_root
                )
            content = content.replace("{SCRIPT}", script_command)

        # 3. Strip scripts: section from frontmatter
        lines = content.splitlines(keepends=True)
        output_lines: list[str] = []
        in_frontmatter = False
        skip_section = False
        dash_count = 0
        for line in lines:
            stripped = line.rstrip("\n\r")
            if stripped == "---":
                dash_count += 1
                if dash_count == 1:
                    in_frontmatter = True
                else:
                    in_frontmatter = False
                skip_section = False
                output_lines.append(line)
                continue
            if in_frontmatter:
                if stripped == "scripts:":
                    skip_section = True
                    continue
                if skip_section:
                    if line[0:1].isspace():
                        continue  # skip indented content under scripts
                    skip_section = False
            output_lines.append(line)
        content = "".join(output_lines)

        # 4. Replace {ARGS} and $ARGUMENTS
        content = content.replace("{ARGS}", arg_placeholder)
        content = content.replace("$ARGUMENTS", arg_placeholder)

        # 5. Replace __AGENT__
        content = content.replace("__AGENT__", agent_name)

        # 6. Rewrite paths β€” delegate to the shared implementation in
        #    CommandRegistrar so extension-local paths are preserved and
        #    boundary rules stay consistent across the codebase.
        from specify_cli.agents import CommandRegistrar

        content = CommandRegistrar.rewrite_project_relative_paths(content)

        # 8. Replace __SPECKIT_COMMAND_<NAME>__ with invocation strings
        invocation_prefix = get_invocation_prefix(
            agent_name, invoke_separator == "-"
        )
        content = IntegrationBase.resolve_command_refs(
            content, invoke_separator, invocation_prefix
        )

        return content

    def setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        """Install integration command files into *project_root*.

        Returns the list of files created.  Copies raw templates without
        processing.  Integrations that need placeholder replacement
        (e.g. ``{SCRIPT}``, ``__AGENT__``) should override ``setup()``
        and call ``process_template()`` in their own loop β€” see
        ``CopilotIntegration`` for an example.
        """
        templates = self.list_command_templates()
        if not templates:
            return []

        project_root_resolved = project_root.resolve()
        if manifest.project_root != project_root_resolved:
            raise ValueError(
                f"manifest.project_root ({manifest.project_root}) does not match "
                f"project_root ({project_root_resolved})"
            )

        dest = self.commands_dest(project_root).resolve()
        try:
            dest.relative_to(project_root_resolved)
        except ValueError as exc:
            raise ValueError(
                f"Integration destination {dest} escapes "
                f"project root {project_root_resolved}"
            ) from exc

        created: list[Path] = []

        for src_file in templates:
            dst_name = self.command_filename(src_file.stem)
            dst_file = self.copy_command_to_directory(src_file, dest, dst_name)
            self.record_file_in_manifest(dst_file, project_root, manifest)
            created.append(dst_file)


        return created

    def teardown(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        *,
        force: bool = False,
    ) -> tuple[list[Path], list[Path]]:
        """Uninstall integration files from *project_root*.

        Delegates to ``manifest.uninstall()`` which only removes files
        whose hash still matches the recorded value (unless *force*).

        Returns ``(removed, skipped)`` file lists.
        """
        import inspect

        remove_events = self.remove_events
        try:
            inspect.signature(remove_events).bind(project_root, manifest, force=force)
        except TypeError:
            remove_events(project_root, manifest)
        else:
            remove_events(project_root, manifest, force=force)
        return manifest.uninstall(project_root, force=force)

    def emit_events(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        events: dict[str, dict[str, Any]] | None = None,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        """Emit native event configuration for this integration."""
        return install_integration_events(
            self, project_root, manifest, events or {}, force=opts.get("force", False)
        )

    def remove_events(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        *,
        force: bool = False,
    ) -> None:
        """Remove Specify-authored event entries from native config."""
        remove_integration_events(self, project_root, manifest, force=force)

    def supports_events(self) -> bool:
        """Return True if this integration supports agent-native events."""
        return bool(getattr(self, "CANONICAL_TO_NATIVE", None) and getattr(self, "events_config_file", None))

    # Context-injection envelope for hook stdout, keyed by canonical event
    # (with "*" as the fallback). Not every agent injects a hook's plain-text
    # stdout as model context: Gemini/Tabnine/Qwen/Devin are JSON-only
    # protocols (plain text becomes user-facing noise), Copilot discards
    # non-JSON stdout, and Cursor parses stdout as JSON. Values:
    #   "hookSpecificOutput" β†’ {"hookSpecificOutput": {"additionalContext": ...}}
    #   "additionalContext"  β†’ {"additionalContext": ...}   (top-level, Copilot)
    #   "additional_context" β†’ {"additional_context": ...}  (top-level, Cursor)
    #   "suppress"           β†’ emit nothing (strict-JSON agents on events whose
    #                          output can't be used)
    # Absent (no matching key and no "*") β†’ plain stdout passthrough
    # (Claude/Codex inject plain stdout; opencode injects via its TS plugin).
    events_context_envelope: dict[str, str] = {}

    # -- Convenience helpers for subclasses -------------------------------

    def install(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        """High-level install β€” calls ``setup()`` and returns created files."""
        return self.setup(project_root, manifest, parsed_options=parsed_options, **opts)

    def uninstall(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        *,
        force: bool = False,
    ) -> tuple[list[Path], list[Path]]:
        """High-level uninstall β€” calls ``teardown()``."""
        return self.teardown(project_root, manifest, force=force)


# ---------------------------------------------------------------------------
# MarkdownIntegration β€” covers ~20 standard agents
# ---------------------------------------------------------------------------


class MarkdownIntegration(IntegrationBase):
    """Concrete base for integrations that use standard Markdown commands.

    Subclasses only need to set ``key``, ``config``, ``registrar_config``.
    Everything else is inherited.

    ``setup()`` processes command templates (replacing ``{SCRIPT}``,
    ``{ARGS}``, ``__AGENT__``, rewriting paths).
    """

    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:
        self.validate_runtime_config(integration_args, integration_options)
        if not self.config or not self.config.get("requires_cli"):
            return None
        args = [self._resolve_executable(), "-p", prompt]
        self._apply_extra_args_env_var(args)
        if model:
            args.extend(["--model", model])
        if output_json:
            args.extend(["--output-format", "json"])
        return args

    def setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        templates = self.list_command_templates()
        if not templates:
            return []

        project_root_resolved = project_root.resolve()
        if manifest.project_root != project_root_resolved:
            raise ValueError(
                f"manifest.project_root ({manifest.project_root}) does not match "
                f"project_root ({project_root_resolved})"
            )

        dest = self.commands_dest(project_root).resolve()
        try:
            dest.relative_to(project_root_resolved)
        except ValueError as exc:
            raise ValueError(
                f"Integration destination {dest} escapes "
                f"project root {project_root_resolved}"
            ) from exc
        dest.mkdir(parents=True, exist_ok=True)

        script_type = opts.get("script_type", "sh")
        arg_placeholder = (
            self.registrar_config.get("args", "$ARGUMENTS")
            if self.registrar_config
            else "$ARGUMENTS"
        )
        created: list[Path] = []

        for src_file in templates:
            raw = src_file.read_text(encoding="utf-8")
            processed = self.process_template(
                raw, self.key, script_type, arg_placeholder,
                project_root=project_root,
            )
            dst_name = self.command_filename(src_file.stem)
            dst_file = self.write_file_and_record(
                processed, dest / dst_name, project_root, manifest
            )
            created.append(dst_file)


        # Install agent runtime events
        event_files = self.emit_events(
            project_root, manifest, events=opts.get("events"), parsed_options=parsed_options,
            force=opts.get("force", False),
        )
        created.extend(event_files)

        return created


# ---------------------------------------------------------------------------
# TomlIntegration β€” TOML-format agents (Gemini, Tabnine)
# ---------------------------------------------------------------------------


class TomlIntegration(IntegrationBase):
    """Concrete base for integrations that use TOML command format.

    Mirrors ``MarkdownIntegration`` closely: subclasses only need to set
    ``key``, ``config``, ``registrar_config``.  Everything else is inherited.

    ``setup()`` processes command templates through the same placeholder
    pipeline as ``MarkdownIntegration``, then converts the result to
    TOML format (``description`` key + ``prompt`` multiline string).
    """

    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:
        self.validate_runtime_config(integration_args, integration_options)
        if not self.config or not self.config.get("requires_cli"):
            return None
        args = [self._resolve_executable(), "-p", prompt]
        self._apply_extra_args_env_var(args)
        if model:
            args.extend(["-m", model])
        if output_json:
            args.extend(["--output-format", "json"])
        return args

    def command_filename(self, template_name: str) -> str:
        """TOML commands use ``.toml`` extension."""
        return f"speckit.{template_name}.toml"

    @staticmethod
    def _extract_description(content: str) -> str:
        """Extract the ``description`` value from YAML frontmatter.

        Parses the YAML frontmatter so block scalar descriptions (``|``
        and ``>``) keep their YAML semantics instead of being treated as
        raw text.
        """

        frontmatter_text, _ = TomlIntegration._split_frontmatter(content)
        if not frontmatter_text:
            return ""
        try:
            frontmatter = yaml.safe_load(frontmatter_text) or {}
        except yaml.YAMLError:
            return ""

        if not isinstance(frontmatter, dict):
            return ""

        description = frontmatter.get("description", "")
        if isinstance(description, str):
            return description
        return ""

    @staticmethod
    def _split_frontmatter(content: str) -> tuple[str, str]:
        """Split YAML frontmatter from the remaining content.

        Returns ``("", content)`` when no complete frontmatter block is
        present. The body is preserved exactly as written so prompt text
        keeps its intended formatting.
        """
        if not content.startswith("---"):
            return "", content

        lines = content.splitlines(keepends=True)
        if not lines or lines[0].rstrip("\r\n") != "---":
            return "", content

        frontmatter_end = -1
        for i, line in enumerate(lines[1:], start=1):
            if line.rstrip("\r\n") == "---":
                frontmatter_end = i
                break

        if frontmatter_end == -1:
            return "", content

        frontmatter = "".join(lines[1:frontmatter_end])
        body = "".join(lines[frontmatter_end + 1 :])
        return frontmatter, body

    # Control-char detection and basic-string escaping are shared with the
    # extension/preset renderer in ``specify_cli.agents`` via
    # ``specify_cli._toml_string`` so the two never drift apart.
    _has_illegal_toml_control = staticmethod(_has_illegal_toml_control)
    _escape_toml_basic = staticmethod(_escape_toml_basic)

    @staticmethod
    def _render_toml_string(value: str) -> str:
        """Render *value* as a TOML string literal.

        Uses a basic string for single-line values, multiline basic
        strings for values containing newlines, and falls back to a
        literal string or escaped basic string when delimiters appear in
        the content.
        """
        # Control characters other than tab/newline (and a bare CR) cannot
        # appear literally in any TOML string; route them to a fully-escaped
        # basic string so the generated file stays parseable.
        if TomlIntegration._has_illegal_toml_control(value):
            return TomlIntegration._escape_toml_basic(value)

        if "\n" not in value and "\r" not in value:
            escaped = value.replace("\\", "\\\\").replace('"', '\\"')
            return f'"{escaped}"'

        escaped = value.replace("\\", "\\\\")
        if '"""' not in escaped:
            if escaped.endswith('"'):
                return '"""\n' + escaped + '\\\n"""'
            return '"""\n' + escaped + '"""'
        if "'''" not in value and not value.endswith("'"):
            return "'''\n" + value + "'''"

        return TomlIntegration._escape_toml_basic(value)

    @staticmethod
    def _render_toml(description: str, body: str) -> str:
        """Render a TOML command file from description and body.

        Uses multiline basic strings (``\"\"\"``) with backslashes
        escaped, matching the output of the release script.  Falls back
        to multiline literal strings (``'''``) if the body contains
        ``\"\"\"``, then to an escaped basic string as a last resort.

        The body is ``rstrip("\\n")``'d before rendering, so the TOML
        value preserves content without forcing a trailing newline. As a
        result, multiline delimiters appear on their own line only when
        the rendered value itself ends with a newline.
        """
        toml_lines: list[str] = []

        if description:
            toml_lines.append(
                f"description = {TomlIntegration._render_toml_string(description)}"
            )
            toml_lines.append("")

        body = body.rstrip("\n")
        toml_lines.append(f"prompt = {TomlIntegration._render_toml_string(body)}")

        return "\n".join(toml_lines) + "\n"

    def setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        templates = self.list_command_templates()
        if not templates:
            return []

        project_root_resolved = project_root.resolve()
        if manifest.project_root != project_root_resolved:
            raise ValueError(
                f"manifest.project_root ({manifest.project_root}) does not match "
                f"project_root ({project_root_resolved})"
            )

        dest = self.commands_dest(project_root).resolve()
        try:
            dest.relative_to(project_root_resolved)
        except ValueError as exc:
            raise ValueError(
                f"Integration destination {dest} escapes "
                f"project root {project_root_resolved}"
            ) from exc
        dest.mkdir(parents=True, exist_ok=True)

        script_type = opts.get("script_type", "sh")
        arg_placeholder = (
            self.registrar_config.get("args", "{{args}}")
            if self.registrar_config
            else "{{args}}"
        )
        created: list[Path] = []

        for src_file in templates:
            raw = src_file.read_text(encoding="utf-8")
            description = self._extract_description(raw)
            processed = self.process_template(
                raw, self.key, script_type, arg_placeholder,
                project_root=project_root,
            )
            _, body = self._split_frontmatter(processed)
            toml_content = self._render_toml(description, body)
            dst_name = self.command_filename(src_file.stem)
            dst_file = self.write_file_and_record(
                toml_content, dest / dst_name, project_root, manifest
            )
            created.append(dst_file)


        # Install agent runtime events
        event_files = self.emit_events(
            project_root, manifest, events=opts.get("events"), parsed_options=parsed_options,
            force=opts.get("force", False),
        )
        created.extend(event_files)

        return created


# ---------------------------------------------------------------------------
# YamlIntegration β€” YAML-format agents (Goose)
# ---------------------------------------------------------------------------

# Characters a YAML literal block scalar cannot carry: C0 controls other
# than tab/LF (a bare CR acts as a line break inside the scalar), DEL, the
# C1 range, lone UTF-16 surrogates, and the non-characters U+FFFE/U+FFFF.
# NEL (U+0085) is YAML-printable but, like LS/PS (U+2028/U+2029), YAML 1.1
# treats it as a line break, which corrupts the block scalar's structure
# just the same, so all three are included.
_YAML_BLOCK_SCALAR_UNSAFE = re.compile(
    r"[\x00-\x08\x0b-\x1f\x7f-\x9f\u2028\u2029\ud800-\udfff\ufffe\uffff]"
)


class YamlIntegration(IntegrationBase):
    """Concrete base for integrations that use YAML recipe format.

    Mirrors ``TomlIntegration`` closely: subclasses only need to set
    ``key``, ``config``, ``registrar_config``.  Everything else is inherited.

    ``setup()`` processes command templates through the same placeholder
    pipeline as ``MarkdownIntegration``, then converts the result to
    YAML recipe format (version, title, description, prompt block scalar).
    """

    def command_filename(self, template_name: str) -> str:
        """YAML commands use ``.yaml`` extension."""
        return f"speckit.{template_name}.yaml"

    @staticmethod
    def _extract_frontmatter(content: str) -> dict[str, Any]:
        """Extract frontmatter as a dict from YAML frontmatter block."""

        if not content.startswith("---"):
            return {}

        lines = content.splitlines(keepends=True)
        if not lines or lines[0].rstrip("\r\n") != "---":
            return {}

        frontmatter_end = -1
        for i, line in enumerate(lines[1:], start=1):
            if line.rstrip("\r\n") == "---":
                frontmatter_end = i
                break

        if frontmatter_end == -1:
            return {}

        frontmatter_text = "".join(lines[1:frontmatter_end])
        try:
            fm = yaml.safe_load(frontmatter_text) or {}
        except yaml.YAMLError:
            return {}

        return fm if isinstance(fm, dict) else {}

    @staticmethod
    def _split_frontmatter(content: str) -> tuple[str, str]:
        """Split YAML frontmatter from the remaining body content."""
        if not content.startswith("---"):
            return "", content

        lines = content.splitlines(keepends=True)
        if not lines or lines[0].rstrip("\r\n") != "---":
            return "", content

        frontmatter_end = -1
        for i, line in enumerate(lines[1:], start=1):
            if line.rstrip("\r\n") == "---":
                frontmatter_end = i
                break

        if frontmatter_end == -1:
            return "", content

        frontmatter = "".join(lines[1:frontmatter_end])
        body = "".join(lines[frontmatter_end + 1 :])
        return frontmatter, body

    @staticmethod
    def _human_title(identifier: str) -> str:
        """Convert an identifier to a human-readable title.

        Strips a leading ``speckit.`` prefix and replaces ``.``, ``-``,
        and ``_`` with spaces before title-casing.
        """
        text = identifier
        if text.startswith("speckit."):
            text = text[len("speckit.") :]
        return text.replace(".", " ").replace("-", " ").replace("_", " ").title()


    @classmethod
    def _build_yaml_header(cls, title: str, description: str) -> dict[str, Any]:
        """Build the base YAML header."""
        header = {
            "version": "1.0.0",
            "title": title,
            "description": description,
            "author": {"contact": "spec-kit"},
            "parameters": [
                {
                    "key": "args",
                    "input_type": "string",
                    "requirement": "optional",
                    "default": "",
                    "description": "User input passed to the command.",
                }
            ],
            "extensions": [{"type": "builtin", "name": "developer"}],
            "activities": ["Spec-Driven Development"],
        }
        return header

    @classmethod
    def _render_yaml(cls, title: str, description: str, body: str, source_id: str) -> str:
        """Render a YAML recipe file from title, description, and body.

        Produces a Goose-compatible recipe with a literal block scalar for
        normal prompt content, or an escaped quoted scalar when control
        characters require it. Uses ``yaml.safe_dump()`` for the header fields.
        """
        header = cls._build_yaml_header(title, description)

        header_yaml = yaml.safe_dump(
            header,
            sort_keys=False,
            allow_unicode=True,
            default_flow_style=False,
        ).strip()

        # YAML forbids C0 control characters (except tab and newline) and
        # DEL in every scalar form, and a bare CR acts as a line break
        # inside a block scalar. A literal block scalar emits such bytes
        # verbatim, producing a recipe the YAML parser rejects, so fall
        # back to an escaped double-quoted scalar for those bodies.
        if _YAML_BLOCK_SCALAR_UNSAFE.search(body):
            prompt_yaml = yaml.safe_dump(
                {"prompt": body}, allow_unicode=True, default_style='"', width=sys.maxsize
            ).strip()
            lines = [
                header_yaml,
                prompt_yaml,
                "",
                f"# Source: {source_id}",
            ]
            return "\n".join(lines) + "\n"

        # Indent the body for YAML block scalar. Use an explicit indentation
        # indicator ("|2") rather than a bare "|": YAML infers a plain block
        # scalar's indentation from its first non-empty line, so a body whose
        # first line is itself indented (e.g. a markdown code block or a nested
        # list item) would make the parser expect that deeper indent for the
        # whole block and reject the later, less-indented lines. Pinning the
        # indent to 2 keeps the recipe parseable whatever the body looks like.
        indented = "\n".join(f"  {line}" for line in body.split("\n"))

        lines = [
            header_yaml,
            "prompt: |2",
            indented,
            "",
            f"# Source: {source_id}",
        ]

        return "\n".join(lines) + "\n"


    def setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        templates = self.list_command_templates()
        if not templates:
            return []

        project_root_resolved = project_root.resolve()
        if manifest.project_root != project_root_resolved:
            raise ValueError(
                f"manifest.project_root ({manifest.project_root}) does not match "
                f"project_root ({project_root_resolved})"
            )

        dest = self.commands_dest(project_root).resolve()
        try:
            dest.relative_to(project_root_resolved)
        except ValueError as exc:
            raise ValueError(
                f"Integration destination {dest} escapes "
                f"project root {project_root_resolved}"
            ) from exc
        dest.mkdir(parents=True, exist_ok=True)

        script_type = opts.get("script_type", "sh")
        arg_placeholder = (
            self.registrar_config.get("args", "{{args}}")
            if self.registrar_config
            else "{{args}}"
        )
        created: list[Path] = []

        for src_file in templates:
            raw = src_file.read_text(encoding="utf-8")
            fm = self._extract_frontmatter(raw)
            description = fm.get("description", "")
            if not isinstance(description, str):
                description = str(description) if description is not None else ""
            title = fm.get("title", "") or fm.get("name", "")
            if not isinstance(title, str):
                title = str(title) if title is not None else ""
            if not title:
                title = self._human_title(src_file.stem)

            processed = self.process_template(
                raw, self.key, script_type, arg_placeholder,
                project_root=project_root,
            )
            _, body = self._split_frontmatter(processed)
            yaml_content = self._render_yaml(
                title, description, body, f"templates/commands/{src_file.name}"
            )
            dst_name = self.command_filename(src_file.stem)
            dst_file = self.write_file_and_record(
                yaml_content, dest / dst_name, project_root, manifest
            )
            created.append(dst_file)


        # Install agent runtime events
        event_files = self.emit_events(
            project_root, manifest, events=opts.get("events"), parsed_options=parsed_options,
            force=opts.get("force", False),
        )
        created.extend(event_files)

        return created


# ---------------------------------------------------------------------------
# SkillsIntegration β€” skills-format agents (Codex, Kimi, Agy)
# ---------------------------------------------------------------------------


class SkillsIntegration(IntegrationBase):
    """Concrete base for integrations that install commands as agent skills.

    Skills use the ``speckit-<name>/SKILL.md`` directory layout following
    the `agentskills.io <https://agentskills.io/specification>`_ spec.

    Subclasses set ``key``, ``config``, ``registrar_config`` like any
    integration.  They may also
    override ``options()`` to declare additional CLI flags (e.g.
    ``--skills``, ``--migrate-legacy``).

    ``setup()`` processes each shared command template into a
    ``speckit-<name>/SKILL.md`` file with skills-oriented frontmatter.
    """

    invoke_separator = "-"

    def is_skills_mode(
        self,
        parsed_options: dict[str, Any] | None = None,
        project_root: Path | None = None,
    ) -> bool:
        """Skills-native integrations scaffold skills unconditionally."""
        return True

    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:
        self.validate_runtime_config(integration_args, integration_options)
        if not self.config or not self.config.get("requires_cli"):
            return None
        args = [self._resolve_executable(), "-p", prompt]
        self._apply_extra_args_env_var(args)
        if model:
            args.extend(["--model", model])
        if output_json:
            args.extend(["--output-format", "json"])
        return args

    def skills_dest(self, project_root: Path) -> Path:
        """Return the absolute path to the skills output directory.

        Derived from ``config["folder"]`` and the configured
        ``commands_subdir`` (defaults to ``"skills"``).

        Raises ``ValueError`` when ``config`` or ``folder`` is missing.
        """
        if not self.config:
            raise ValueError(f"{type(self).__name__}.config is not set.")
        folder = self.config.get("folder")
        if not folder:
            raise ValueError(
                f"{type(self).__name__}.config is missing required 'folder' entry."
            )
        subdir = self.config.get("commands_subdir", "skills")
        return project_root / folder / subdir

    def build_command_invocation(self, command_name: str, args: str = "") -> str:
        """Build the agent's native invocation for a hyphenated skill name."""
        stem = command_name
        if stem.startswith("speckit."):
            stem = stem[len("speckit."):]

        prefix = "$" if is_dollar_skills_agent(self.key, True) else "/"
        invocation = prefix + "speckit-" + stem.replace(".", "-")
        if args:
            invocation = f"{invocation} {args}"
        return invocation

    @staticmethod
    def _inject_hook_command_note(
        content: str, invocation_prefix: str = "/"
    ) -> str:
        """Insert a dot-to-hyphen note before each hook output instruction.

        Targets the line ``- For each executable hook, output the following``
        and inserts the note on the line before it, matching its indentation.
        Skips individual instructions that already have the note immediately
        above them.
        """
        note = _HOOK_COMMAND_NOTE.rstrip("\n")
        if invocation_prefix != "/":
            note = note.replace(
                "`/speckit-git-commit`",
                f"`{invocation_prefix}speckit-git-commit`",
            )

        def repl(m: re.Match[str]) -> str:
            indent = m.group(1)
            instruction = m.group(2)
            previous_lines = content[:m.start()].splitlines()
            if previous_lines and previous_lines[-1] == indent + note:
                return m.group(0)
            # ``eol`` is empty when the regex matched via ``$`` because the
            # instruction was the final line of a file with no trailing
            # newline. Default to ``\n`` so the note never collapses onto
            # the same line as the instruction.
            eol = m.group(3) or "\n"
            return (
                indent
                + note
                + eol
                + indent
                + instruction
                + eol
            )

        return re.sub(
            r"(?m)^([ \t]*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
            repl,
            content,
        )

    def post_process_skill_content(self, content: str) -> str:
        """Post-process a SKILL.md file's content after generation.

        Called by external skill generators (presets, extensions) to let
        the integration inject agent-specific frontmatter or body
        transformations.  The base implementation injects shared skills
        guidance for converting dotted hook command names to the agent-native
        hyphenated command invocation (e.g. ``/speckit-git-commit`` or
        ``$speckit-git-commit``).  Subclasses may override -- see
        ``ClaudeIntegration``.
        """
        invocation_prefix = get_invocation_prefix(self.key, True)
        return self._inject_hook_command_note(content, invocation_prefix)

    def setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        """Install command templates as agent skills.

        Creates ``speckit-<name>/SKILL.md`` for each shared command
        template.  Each SKILL.md has normalised frontmatter containing
        ``name``, ``description``, ``compatibility``, and ``metadata``.
        """

        templates = self.list_command_templates()
        if not templates:
            return []

        project_root_resolved = project_root.resolve()
        if manifest.project_root != project_root_resolved:
            raise ValueError(
                f"manifest.project_root ({manifest.project_root}) does not match "
                f"project_root ({project_root_resolved})"
            )

        skills_dir = self.skills_dest(project_root).resolve()
        try:
            skills_dir.relative_to(project_root_resolved)
        except ValueError as exc:
            raise ValueError(
                f"Skills destination {skills_dir} escapes "
                f"project root {project_root_resolved}"
            ) from exc

        script_type = opts.get("script_type", "sh")
        arg_placeholder = (
            self.registrar_config.get("args", "$ARGUMENTS")
            if self.registrar_config
            else "$ARGUMENTS"
        )
        created: list[Path] = []

        for src_file in templates:
            raw = src_file.read_text(encoding="utf-8")

            # Derive the skill name from the template stem
            command_name = src_file.stem  # e.g. "plan"
            skill_name = f"speckit-{command_name.replace('.', '-')}"

            # Parse frontmatter for description. Locate the closing ``---`` on
            # its own line rather than with ``raw.split("---", 2)`` β€” a bare
            # substring split stops at the first ``---`` *anywhere*, including
            # one inside a value such as ``description: Separate sections
            # with ---``, which truncates the frontmatter and drops later keys.
            # The block between the delimiters is parsed unstripped so trailing
            # newlines in literal (``|``) block scalars survive.
            frontmatter: dict[str, Any] = {}
            if raw.startswith("---"):
                fm_lines = raw.splitlines(keepends=True)
                fm_close = next(
                    (
                        i
                        for i in range(1, len(fm_lines))
                        if fm_lines[i].rstrip() == "---"
                    ),
                    None,
                )
                if fm_close is not None:
                    try:
                        fm = yaml.safe_load("".join(fm_lines[1:fm_close]))
                        if isinstance(fm, dict):
                            frontmatter = fm
                    except yaml.YAMLError:
                        pass

            # Process body through the standard template pipeline
            processed_body = self.process_template(
                raw, self.key, script_type, arg_placeholder,
                project_root=project_root,
                invoke_separator=self.invoke_separator,
            )
            # Strip the processed frontmatter β€” we rebuild it for skills.
            # Preserve leading whitespace in the body to match release ZIP
            # output byte-for-byte (the template body starts with \n after
            # the closing ---). Scan for the closing ``---`` on its own line
            # rather than ``split("---", 2)`` so a ``---`` embedded in a value
            # does not truncate the frontmatter and spill it into the body.
            if processed_body.startswith("---"):
                body_lines = processed_body.splitlines(keepends=True)
                close_idx = next(
                    (
                        i
                        for i in range(1, len(body_lines))
                        if body_lines[i].rstrip() == "---"
                    ),
                    None,
                )
                if close_idx is not None:
                    # Keep whatever trails the ``---`` marker on the closing
                    # line (normally just the newline) so the body stays
                    # byte-for-byte identical to ``split("---", 2)[2]``. The
                    # line-anchored check guarantees ``---`` sits at index 0.
                    processed_body = body_lines[close_idx][3:] + "".join(
                        body_lines[close_idx + 1 :]
                    )

            # Select description β€” use the original template description
            # to stay byte-for-byte identical with release ZIP output.
            description = frontmatter.get("description", "")
            if not description:
                description = f"Spec Kit: {command_name} workflow"

            # Build SKILL.md with manually formatted frontmatter (stable
            # double-quoted values). yaml_quote escapes newlines and control
            # characters that a plain quoted f-string cannot carry.
            skill_content = (
                f"---\n"
                f"name: {yaml_quote(skill_name)}\n"
                f"description: {yaml_quote(description)}\n"
                f"compatibility: {yaml_quote('Requires spec-kit project structure with .specify/ directory')}\n"
                f"metadata:\n"
                f"  author: {yaml_quote('github-spec-kit')}\n"
                f"  source: {yaml_quote('templates/commands/' + src_file.name)}\n"
                f"---\n"
                f"{processed_body}"
            )

            skill_content = self.post_process_skill_content(skill_content)

            # Write speckit-<name>/SKILL.md
            skill_dir = skills_dir / skill_name
            skill_file = skill_dir / "SKILL.md"
            dst = self.write_file_and_record(
                skill_content, skill_file, project_root, manifest
            )
            created.append(dst)


        # Install agent runtime events
        event_files = self.emit_events(
            project_root, manifest, events=opts.get("events"), parsed_options=parsed_options,
            force=opts.get("force", False),
        )
        created.extend(event_files)

        return created