feat(agents): add Goose AI agent support (#2015)

* feat(integrations): add YamlIntegration base class for YAML recipe agents Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * feat(integrations): add Goose integration subpackage with YAML recipe support Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * feat(integrations): register GooseIntegration in the integration registry Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * feat(agents): add YAML format support to CommandRegistrar for extension/preset commands Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * feat(scripts): add goose agent type to bash update-agent-context script Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * feat(scripts): add goose agent type to PowerShell update-agent-context script Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * docs(agents): add Goose to supported agents table and integration notes Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * docs(readme): add Goose to supported agents table Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * test(integrations): add YamlIntegrationTests base mixin for YAML agent testing Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * test(integrations): add Goose integration tests Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * test(consistency): add Goose consistency checks for config, registrar, and scripts Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * docs(agents): move Goose to YAML Format section in Command File Formats Goose uses YAML recipes, not Markdown. Remove it from the Markdown Format list and add a dedicated YAML Format subsection with a representative recipe example showing prompt: | and {{args}} placeholders. * refactor(agents): delegate render_yaml_command to YamlIntegration Remove the duplicate header dict, yaml.safe_dump call, body indentation, and _human_title logic from CommandRegistrar.render_yaml_command(). Delegate to YamlIntegration._render_yaml() and _human_title() so YAML recipe output stays consistent across the init-time generation and command-registration code paths. * fix(agents): guard alias output path against directory traversal Validate that alias_file resolves within commands_dir before writing. Uses the same resolve().relative_to() pattern already established in extensions.py for ZIP path containment checks. * docs(agents): add Goose to Multi-Agent Support comment list in update-agent-context.sh * fix(agents): add goose to print_summary Usage line in bash context script The print_summary() function listed all supported agents in its Usage output but omitted goose, making it inconsistent with the header docs and the error message in update_specific_agent(). Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * fix(agents): add goose to Print-Summary Usage line in PowerShell context script The Print-Summary function listed all supported agents in its Usage output but omitted goose, making it inconsistent with the ValidateSet and the header documentation. Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * fix(agents): normalize description and title types in YamlIntegration.setup() YAML frontmatter can contain non-string types (null, list, int). Add isinstance checks matching TomlIntegration._extract_description() to ensure Goose recipes always receive valid string fields. Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * fix(agents): validate shared script exists before exec in Goose bash wrapper Add Forge-style check that the shared update-agent-context.sh is present and executable, producing a clear error instead of a cryptic shell exec failure when the shared script is missing. Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * fix(agents): validate shared script exists before invoke in Goose PowerShell wrapper Add Forge-style Test-Path check that the shared update-agent-context.ps1 exists, producing a clear error instead of a cryptic PowerShell failure when the shared script is missing. Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * fix(agents): normalize title and description types in render_yaml_command() Extension/preset frontmatter can contain non-string types. Add isinstance checks matching the normalization in YamlIntegration.setup() so both code paths produce valid Goose recipe fields. Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * fix(agents): replace $ARGUMENTS with arg_placeholder in process_template() Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * test(agents): assert $ARGUMENTS absent from generated YAML recipes Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * test(agents): assert $ARGUMENTS absent from generated TOML commands Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> * fix(tests): rewrite docstring to avoid embedded triple-quote in TOML test Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com> --------- Signed-off-by: Furkan Köykıran <furkankoykiran@gmail.com>
2026-07-07 22:56:57 +08:00 · 2026-04-13 15:55:44 +03:00
parent 52ed84d723
commit b67b2856b1
14 changed files with 1227 additions and 141 deletions
--- a/src/specify_cli/integrations/init.py
+++ b/src/specify_cli/integrations/init.py
@@ -36,6 +36,7 @@ def get_integration(key: str) -> IntegrationBase | None:

 # -- Register built-in integrations --------------------------------------

+
 def _register_builtins() -> None:
    """Register all built-in integrations.

@@ -58,6 +59,7 @@ def _register_builtins() -> None:
    from .forge import ForgeIntegration
    from .gemini import GeminiIntegration
    from .generic import GenericIntegration
+    from .goose import GooseIntegration
    from .iflow import IflowIntegration
    from .junie import JunieIntegration
    from .kilocode import KilocodeIntegration
@@ -87,6 +89,7 @@ def _register_builtins() -> None:
    _register(ForgeIntegration())
    _register(GeminiIntegration())
    _register(GenericIntegration())
+    _register(GooseIntegration())
    _register(IflowIntegration())
    _register(JunieIntegration())
    _register(KilocodeIntegration())
--- a/src/specify_cli/integrations/base.py
+++ b/src/specify_cli/integrations/base.py
@@ -28,6 +28,7 @@ if TYPE_CHECKING:
 # IntegrationOption
 # ---------------------------------------------------------------------------

+
@dataclass(frozen=True)
 class IntegrationOption:
    """Declares an option that an integration accepts via ``--integration-options``.
@@ -51,6 +52,7 @@ class IntegrationOption:
 # IntegrationBase — abstract base class
 # ---------------------------------------------------------------------------

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

@@ -275,7 +277,7 @@ class IntegrationBase(ABC):
        2. Replace ``{SCRIPT}`` with the extracted script command
        3. Extract ``agent_scripts.<script_type>`` and replace ``{AGENT_SCRIPT}``
        4. Strip ``scripts:`` and ``agent_scripts:`` sections from frontmatter
-        5. Replace ``{ARGS}`` with *arg_placeholder*
+        5. Replace ``{ARGS}`` and ``$ARGUMENTS`` with *arg_placeholder*
        6. Replace ``__AGENT__`` with *agent_name*
        7. Rewrite paths: ``scripts/`` → ``.specify/scripts/`` etc.
        """
@@ -348,8 +350,9 @@ class IntegrationBase(ABC):
            output_lines.append(line)
        content = "".join(output_lines)

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

        # 6. Replace __AGENT__
        content = content.replace("__AGENT__", agent_name)
@@ -358,6 +361,7 @@ class IntegrationBase(ABC):
        #    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)

        return content
@@ -433,9 +437,7 @@ class IntegrationBase(ABC):
        **opts: Any,
    ) -> list[Path]:
        """High-level install — calls ``setup()`` and returns created files."""
-        return self.setup(
-            project_root, manifest, parsed_options=parsed_options, **opts
-        )
+        return self.setup(project_root, manifest, parsed_options=parsed_options, **opts)

    def uninstall(
        self,
@@ -452,6 +454,7 @@ class IntegrationBase(ABC):
 # MarkdownIntegration — covers ~20 standard agents
 # ---------------------------------------------------------------------------

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

@@ -492,12 +495,18 @@ class MarkdownIntegration(IntegrationBase):
        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"
+        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)
+            processed = self.process_template(
+                raw, self.key, script_type, arg_placeholder
+            )
            dst_name = self.command_filename(src_file.stem)
            dst_file = self.write_file_and_record(
                processed, dest / dst_name, project_root, manifest
@@ -512,6 +521,7 @@ class MarkdownIntegration(IntegrationBase):
 # TomlIntegration — TOML-format agents (Gemini, Tabnine)
 # ---------------------------------------------------------------------------

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

@@ -603,13 +613,17 @@ class TomlIntegration(IntegrationBase):
        if "'''" not in value and not value.endswith("'"):
            return "'''\n" + value + "'''"

-        return '"' + (
-            value.replace("\\", "\\\\")
-            .replace('"', '\\"')
-            .replace("\n", "\\n")
-            .replace("\r", "\\r")
-            .replace("\t", "\\t")
-        ) + '"'
+        return (
+            '"'
+            + (
+                value.replace("\\", "\\\\")
+                .replace('"', '\\"')
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                .replace("\t", "\\t")
+            )
+            + '"'
+        )

    @staticmethod
    def _render_toml(description: str, body: str) -> str:
@@ -628,7 +642,9 @@ class TomlIntegration(IntegrationBase):
        toml_lines: list[str] = []

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

        body = body.rstrip("\n")
@@ -665,13 +681,19 @@ class TomlIntegration(IntegrationBase):
        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}}"
+        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)
+            processed = self.process_template(
+                raw, self.key, script_type, arg_placeholder
+            )
            _, body = self._split_frontmatter(processed)
            toml_content = self._render_toml(description, body)
            dst_name = self.command_filename(src_file.stem)
@@ -684,6 +706,188 @@ class TomlIntegration(IntegrationBase):
        return created


+# ---------------------------------------------------------------------------
+# YamlIntegration — YAML-format agents (Goose)
+# ---------------------------------------------------------------------------
+
+
+class YamlIntegration(IntegrationBase):
+    """Concrete base for integrations that use YAML recipe format.
+
+    Mirrors ``TomlIntegration`` closely: subclasses only need to set
+    ``key``, ``config``, ``registrar_config`` (and optionally
+    ``context_file``).  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."""
+        import yaml
+
+        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()
+
+    @staticmethod
+    def _render_yaml(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 the prompt content.  Uses ``yaml.safe_dump()`` for the
+        header fields to ensure proper escaping.
+        """
+        import yaml
+
+        header = {
+            "version": "1.0.0",
+            "title": title,
+            "description": description,
+            "author": {"contact": "spec-kit"},
+            "extensions": [{"type": "builtin", "name": "developer"}],
+            "activities": ["Spec-Driven Development"],
+        }
+
+        header_yaml = yaml.safe_dump(
+            header,
+            sort_keys=False,
+            allow_unicode=True,
+            default_flow_style=False,
+        ).strip()
+
+        # Indent each line for YAML block scalar
+        indented = "\n".join(f"  {line}" for line in body.split("\n"))
+
+        lines = [header_yaml, "prompt: |", 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
+            )
+            _, 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)
+
+        created.extend(self.install_scripts(project_root, manifest))
+        return created
+
+
 # ---------------------------------------------------------------------------
 # SkillsIntegration — skills-format agents (Codex, Kimi, Agy)
 # ---------------------------------------------------------------------------
@@ -713,9 +917,7 @@ class SkillsIntegration(IntegrationBase):
        Raises ``ValueError`` when ``config`` or ``folder`` is missing.
        """
        if not self.config:
-            raise ValueError(
-                f"{type(self).__name__}.config is not set."
-            )
+            raise ValueError(f"{type(self).__name__}.config is not set.")
        folder = self.config.get("folder")
        if not folder:
            raise ValueError(
--- a/src/specify_cli/integrations/goose/init.py
+++ b/src/specify_cli/integrations/goose/init.py
@@ -0,0 +1,21 @@
+"""Goose integration — Block's open source AI agent."""
+
+from ..base import YamlIntegration
+
+
+class GooseIntegration(YamlIntegration):
+    key = "goose"
+    config = {
+        "name": "Goose",
+        "folder": ".goose/",
+        "commands_subdir": "recipes",
+        "install_url": "https://block.github.io/goose/docs/getting-started/installation",
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".goose/recipes",
+        "format": "yaml",
+        "args": "{{args}}",
+        "extension": ".yaml",
+    }
+    context_file = "AGENTS.md"
--- a/src/specify_cli/integrations/goose/scripts/update-context.ps1
+++ b/src/specify_cli/integrations/goose/scripts/update-context.ps1
@@ -0,0 +1,33 @@
+# update-context.ps1 — Goose integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+# Activated in Stage 7 when the shared script uses integration.json dispatch.
+#
+# Until then, this delegates to the shared script as a subprocess.
+
+$ErrorActionPreference = 'Stop'
+
+# Derive repo root from script location (walks up to find .specify/)
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
+# If git did not return a repo root, or the git root does not contain .specify,
+# fall back to walking up from the script directory to find the initialized project root.
+if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+    $repoRoot = $scriptDir
+    $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot)
+    while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+        $repoRoot = Split-Path -Parent $repoRoot
+    }
+}
+
+$sharedScript = "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1"
+
+# Always delegate to the shared updater; fail clearly if it is unavailable.
+if (-not (Test-Path $sharedScript)) {
+    Write-Error "Error: shared agent context updater not found: $sharedScript"
+    Write-Error "Goose integration requires support in scripts/powershell/update-agent-context.ps1."
+    exit 1
+}
+
+& $sharedScript -AgentType goose
+exit $LASTEXITCODE
--- a/src/specify_cli/integrations/goose/scripts/update-context.sh
+++ b/src/specify_cli/integrations/goose/scripts/update-context.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# update-context.sh — Goose integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+# Activated in Stage 7 when the shared script uses integration.json dispatch.
+#
+# Until then, this delegates to the shared script as a subprocess.
+
+set -euo pipefail
+
+# Derive repo root from script location (walks up to find .specify/)
+_script_dir="$(cd "$(dirname "$0")" && pwd)"
+_root="$_script_dir"
+while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done
+if [ -z "${REPO_ROOT:-}" ]; then
+  if [ -d "$_root/.specify" ]; then
+    REPO_ROOT="$_root"
+  else
+    git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then
+      REPO_ROOT="$git_root"
+    else
+      REPO_ROOT="$_root"
+    fi
+  fi
+fi
+
+shared_script="$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh"
+
+# Always delegate to the shared updater; fail clearly if it is unavailable.
+if [ ! -x "$shared_script" ]; then
+  echo "Error: shared agent context updater not found or not executable:" >&2
+  echo "  $shared_script" >&2
+  echo "Goose integration requires support in scripts/bash/update-agent-context.sh." >&2
+  exit 1
+fi
+
+exec "$shared_script" goose