Stage 5: Skills, Generic & Option-Driven Integrations (#1924)

Add SkillsIntegration base class and migrate codex, kimi, agy, and
generic to the integration system.

Integrations:
- SkillsIntegration(IntegrationBase) in base.py — creates
  speckit-<name>/SKILL.md layout matching release ZIP output byte-for-byte
- CodexIntegration — .agents/skills/, --skills default=True
- KimiIntegration — .kimi/skills/, --skills + --migrate-legacy options,
  dotted→hyphenated skill directory migration
- AgyIntegration — .agent/skills/, skills-only (commands deprecated v1.20.5)
- GenericIntegration — user-specified --commands-dir, MarkdownIntegration
- All four have update-context.sh/.ps1 scripts
- All four registered in INTEGRATION_REGISTRY

CLI changes:
- --ai <agent> auto-promotes to integration path for all registered agents
- Interactive agent selection also auto-promotes (bug fix)
- --ai-skills and --ai-commands-dir show deprecation notices on integration path
- Next-steps display shows correct skill invocation syntax for skills integrations
- agy added to CommandRegistrar.AGENT_CONFIGS

Tests:
- test_integration_base_skills.py — reusable mixin with setup, frontmatter,
  directory structure, scripts, CLI auto-promote, and complete file inventory
  (sh+ps) tests
- Per-agent test files: test_integration_{codex,kimi,agy,generic}.py
- Kimi legacy migration tests, generic --commands-dir validation
- Registry updated with Stage 5 keys
- Removed 9 dead-mock tests, moved 4 integration tests to proper locations
- Fixed all bare project-name tests to use tmp_path
- Fixed 6 pre-existing ANSI escape code test failures in test_extensions.py
  and test_presets.py

1524 tests pass, 0 failures.

Author: mnriem

src/specify_cli/__init__.py

@@ -1997,6 +1997,19 @@ def init(
                 f"--ai {ai_assistant}. The --ai flag will be deprecated in a future release.[/dim]"
             )
 
+    # Deprecation warnings for --ai-skills and --ai-commands-dir when using integration path
+    if use_integration:
+        if ai_skills:
+            console.print(
+                "[dim]Note: --ai-skills is not needed with --integration; "
+                "skills are the default for this integration.[/dim]"
+            )
+        if ai_commands_dir:
+            console.print(
+                "[dim]Note: --ai-commands-dir is deprecated with --integration; "
+                "use --integration generic with parsed options instead.[/dim]"
+            )
+
     if project_name == ".":
         here = True
         project_name = None  # Clear project_name to use existing validation logic
@@ -2062,8 +2075,18 @@ def init(
             "copilot"
         )
 
+    # Auto-promote interactively selected agents to the integration path
+    # when a matching integration is registered (same behavior as --ai).
+    if not use_integration:
+        from .integrations import get_integration as _get_int
+        _resolved = _get_int(selected_ai)
+        if _resolved:
+            use_integration = True
+            resolved_integration = _resolved
+
     # Agents that have moved from explicit commands/prompts to agent skills.
-    if selected_ai in AGENT_SKILLS_MIGRATIONS and not ai_skills:
+    # Skip this check when using the integration path — skills are the default.
+    if not use_integration and selected_ai in AGENT_SKILLS_MIGRATIONS and not ai_skills:
         # If selected interactively (no --ai provided), automatically enable
         # ai_skills so the agent remains usable without requiring an extra flag.
         # Preserve fail-fast behavior only for explicit '--ai <agent>' without skills.
@@ -2073,15 +2096,16 @@ def init(
             ai_skills = True
             console.print(f"\n[yellow]Note:[/yellow] {AGENT_SKILLS_MIGRATIONS[selected_ai]['interactive_note']}")
 
-    # Validate --ai-commands-dir usage
-    if selected_ai == "generic":
-        if not ai_commands_dir:
-            console.print("[red]Error:[/red] --ai-commands-dir is required when using --ai generic")
-            console.print("[dim]Example: specify init my-project --ai generic --ai-commands-dir .myagent/commands/[/dim]")
+    # Validate --ai-commands-dir usage (legacy path only)
+    if not use_integration:
+        if selected_ai == "generic":
+            if not ai_commands_dir:
+                console.print("[red]Error:[/red] --ai-commands-dir is required when using --ai generic")
+                console.print("[dim]Example: specify init my-project --ai generic --ai-commands-dir .myagent/commands/[/dim]")
+                raise typer.Exit(1)
+        elif ai_commands_dir:
+            console.print(f"[red]Error:[/red] --ai-commands-dir can only be used with --ai generic (not '{selected_ai}')")
             raise typer.Exit(1)
-    elif ai_commands_dir:
-        console.print(f"[red]Error:[/red] --ai-commands-dir can only be used with --ai generic (not '{selected_ai}')")
-        raise typer.Exit(1)
 
     current_dir = Path.cwd()
 
@@ -2210,8 +2234,17 @@ def init(
                 manifest = IntegrationManifest(
                     resolved_integration.key, project_path, version=get_speckit_version()
                 )
+
+                # Build parsed_options from legacy CLI flags for Stage 5 integrations
+                integration_parsed_options: dict[str, Any] = {}
+                if ai_commands_dir:
+                    integration_parsed_options["commands_dir"] = ai_commands_dir
+                if ai_skills:
+                    integration_parsed_options["skills"] = True
+
                 resolved_integration.setup(
                     project_path, manifest,
+                    parsed_options=integration_parsed_options or None,
                     script_type=selected_script,
                 )
                 manifest.save()
@@ -2268,7 +2301,7 @@ def init(
                         shutil.rmtree(project_path)
                     raise typer.Exit(1)
             # For generic agent, rename placeholder directory to user-specified path
-            if selected_ai == "generic" and ai_commands_dir:
+            if not use_integration and selected_ai == "generic" and ai_commands_dir:
                 placeholder_dir = project_path / ".speckit" / "commands"
                 target_dir = project_path / ai_commands_dir
                 if placeholder_dir.is_dir():
@@ -2284,18 +2317,19 @@ def init(
             ensure_constitution_from_template(project_path, tracker=tracker)
 
             # Determine skills directory and migrate any legacy Kimi dotted skills.
+            # (Legacy path only — integration path handles skills in setup().)
             migrated_legacy_kimi_skills = 0
             removed_legacy_kimi_skills = 0
             skills_dir: Optional[Path] = None
-            if selected_ai in NATIVE_SKILLS_AGENTS:
+            if not use_integration and selected_ai in NATIVE_SKILLS_AGENTS:
                 skills_dir = _get_skills_dir(project_path, selected_ai)
                 if selected_ai == "kimi" and skills_dir.is_dir():
                     (
                         migrated_legacy_kimi_skills,
                         removed_legacy_kimi_skills,
                     ) = _migrate_legacy_kimi_dotted_skills(skills_dir)
 
-            if ai_skills:
+            if not use_integration and ai_skills:
                 if selected_ai in NATIVE_SKILLS_AGENTS:
                     bundled_found = _has_bundled_skills(project_path, selected_ai)
                     if bundled_found:
@@ -2484,17 +2518,27 @@ def init(
         steps_lines.append("1. You're already in the project directory!")
         step_num = 2
 
-    if selected_ai == "codex" and ai_skills:
-        steps_lines.append(f"{step_num}. Start Codex in this project directory; spec-kit skills were installed to [cyan].agents/skills[/cyan]")
-        step_num += 1
+    # Determine skill display mode for the next-steps panel.
+    # Skills integrations (codex, kimi, agy) should show skill invocation syntax
+    # regardless of whether --ai-skills was explicitly passed.
+    _is_skills_integration = False
+    if use_integration:
+        from .integrations.base import SkillsIntegration as _SkillsInt
+        _is_skills_integration = isinstance(resolved_integration, _SkillsInt)
 
-    codex_skill_mode = selected_ai == "codex" and ai_skills
+    codex_skill_mode = selected_ai == "codex" and (ai_skills or _is_skills_integration)
     kimi_skill_mode = selected_ai == "kimi"
-    native_skill_mode = codex_skill_mode or kimi_skill_mode
+    agy_skill_mode = selected_ai == "agy" and _is_skills_integration
+    native_skill_mode = codex_skill_mode or kimi_skill_mode or agy_skill_mode
+
+    if codex_skill_mode and not ai_skills:
+        # Integration path installed skills; show the helpful notice
+        steps_lines.append(f"{step_num}. Start Codex in this project directory; spec-kit skills were installed to [cyan].agents/skills[/cyan]")
+        step_num += 1
     usage_label = "skills" if native_skill_mode else "slash commands"
 
     def _display_cmd(name: str) -> str:
-        if codex_skill_mode:
+        if codex_skill_mode or agy_skill_mode:
             return f"$speckit-{name}"
         if kimi_skill_mode:
             return f"/skill:speckit-{name}"

src/specify_cli/agents.py

@@ -168,6 +168,12 @@ class CommandRegistrar:
             "format": "markdown",
             "args": "$ARGUMENTS",
             "extension": ".md"
+        },
+        "agy": {
+            "dir": ".agent/skills",
+            "format": "markdown",
+            "args": "$ARGUMENTS",
+            "extension": "/SKILL.md",
         }
     }
 

src/specify_cli/integrations/__init__.py

@@ -46,17 +46,21 @@ def _register_builtins() -> None:
     users install and invoke.
     """
     # -- Imports (alphabetical) -------------------------------------------
+    from .agy import AgyIntegration
     from .amp import AmpIntegration
     from .auggie import AuggieIntegration
     from .bob import BobIntegration
     from .claude import ClaudeIntegration
+    from .codex import CodexIntegration
     from .codebuddy import CodebuddyIntegration
     from .copilot import CopilotIntegration
     from .cursor_agent import CursorAgentIntegration
     from .gemini import GeminiIntegration
+    from .generic import GenericIntegration
     from .iflow import IflowIntegration
     from .junie import JunieIntegration
     from .kilocode import KilocodeIntegration
+    from .kimi import KimiIntegration
     from .kiro_cli import KiroCliIntegration
     from .opencode import OpencodeIntegration
     from .pi import PiIntegration
@@ -70,17 +74,21 @@ def _register_builtins() -> None:
     from .windsurf import WindsurfIntegration
 
     # -- Registration (alphabetical) --------------------------------------
+    _register(AgyIntegration())
     _register(AmpIntegration())
     _register(AuggieIntegration())
     _register(BobIntegration())
     _register(ClaudeIntegration())
+    _register(CodexIntegration())
     _register(CodebuddyIntegration())
     _register(CopilotIntegration())
     _register(CursorAgentIntegration())
     _register(GeminiIntegration())
+    _register(GenericIntegration())
     _register(IflowIntegration())
     _register(JunieIntegration())
     _register(KilocodeIntegration())
+    _register(KimiIntegration())
     _register(KiroCliIntegration())
     _register(OpencodeIntegration())
     _register(PiIntegration())

src/specify_cli/integrations/agy/__init__.py

@@ -0,0 +1,41 @@
+"""Antigravity (agy) integration — skills-based agent.
+
+Antigravity uses ``.agent/skills/speckit-<name>/SKILL.md`` layout.
+Explicit command support was deprecated in version 1.20.5;
+``--skills`` defaults to ``True``.
+"""
+
+from __future__ import annotations
+
+from ..base import IntegrationOption, SkillsIntegration
+
+
+class AgyIntegration(SkillsIntegration):
+    """Integration for Antigravity IDE."""
+
+    key = "agy"
+    config = {
+        "name": "Antigravity",
+        "folder": ".agent/",
+        "commands_subdir": "skills",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".agent/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = "AGENTS.md"
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=True,
+                help="Install as agent skills (default for Antigravity since v1.20.5)",
+            ),
+        ]

src/specify_cli/integrations/agy/scripts/update-context.ps1

@@ -0,0 +1,17 @@
+# update-context.ps1 — Antigravity (agy) integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
+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
+    }
+}
+
+& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType agy

src/specify_cli/integrations/agy/scripts/update-context.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# update-context.sh — Antigravity (agy) integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+set -euo pipefail
+
+_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
+
+exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" agy