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

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

* fix: remove unused variable flagged by ruff (F841)

* fix: address PR review — integration-type-aware deprecation messages and early generic validation

- --ai-skills deprecation message now distinguishes SkillsIntegration
  ("skills are the default") from command-based integrations ("has no effect")
- --ai-commands-dir validation for generic runs even when auto-promoted,
  giving clear CLI error instead of late ValueError from setup()
- Resolves review comments from #2052

* fix: address PR review round 2

- Remove unused SKILL_DESCRIPTIONS dict from base.py (dead code after
  switching to template descriptions for ZIP parity)
- Narrow YAML parse catch from Exception to yaml.YAMLError
- Remove unused shutil import from test_integration_kimi.py
- Remove unused _REGISTRAR_EXEMPT class attr from test_registry.py
- Reword --ai-commands-dir deprecation to be actionable
- Update generic validation error to mention both --ai and --integration

* fix: address PR review round 3

- Clarify parsed_options forwarding is intentional (all options passed,
  integrations decide what to use)
- Extract _strip_ansi() helper in test_extensions.py and test_presets.py
- Remove unused pytest import (test_cli.py), unused locals (test_integration_base_skills.py)
- Reword --ai-commands-dir deprecation to be actionable without referencing
  the not-yet-implemented --integration-options

* fix: address PR review round 4

- Reorder kimi migration: run super().setup() first so hyphenated
  targets exist, then migrate dotted dirs (prevents user content loss)
- Move _strip_ansi() to shared tests/conftest.py, import from there
  in test_extensions.py, test_presets.py, test_ai_skills.py
- Remove now-unused re imports from all three test files

* fix: address PR review round 5

- Use write_bytes() for LF-only newlines (no CRLF on Windows)
- Add --integration-options CLI parameter — raw string passed through
  to the integration via opts['raw_options']; the integration owns
  parsing of its own options
- GenericIntegration.setup() reads --commands-dir from raw_options
  when not in parsed_options (supports --integration-options="...")
- Skip early --ai-commands-dir validation when --integration-options
  is provided (integration validates in its own setup())
- Remove parse_integration_options from core — integrations parse
  their own options

* fix: address PR review round 6

- GenericIntegration is now stateless: removed self._commands_dir
  instance state, overrides setup() directly to compute destination
  from parsed_options/raw_options on the stack
- commands_dest() raises by design (stateless singleton)
- _quote() in SkillsIntegration now escapes backslashes and double
  quotes to produce valid YAML even with special characters

* fix: address PR review round 7

- Support --commands-dir=value form in raw_options parsing (not just
  --commands-dir value with space separator)
- Normalize CRLF to LF in write_file_and_record() before encoding
- Persist ai_skills=True in init-options.json when using a
  SkillsIntegration, so extensions/presets emit SKILL.md overrides
  correctly even without explicit --ai-skills flag

tests/integrations/test_cli.py

@@ -3,26 +3,24 @@
 import json
 import os
 
-import pytest
-
 
 class TestInitIntegrationFlag:
-    def test_integration_and_ai_mutually_exclusive(self):
+    def test_integration_and_ai_mutually_exclusive(self, tmp_path):
         from typer.testing import CliRunner
         from specify_cli import app
         runner = CliRunner()
         result = runner.invoke(app, [
-            "init", "test-project", "--ai", "claude", "--integration", "copilot",
+            "init", str(tmp_path / "test-project"), "--ai", "claude", "--integration", "copilot",
         ])
         assert result.exit_code != 0
         assert "mutually exclusive" in result.output
 
-    def test_unknown_integration_rejected(self):
+    def test_unknown_integration_rejected(self, tmp_path):
         from typer.testing import CliRunner
         from specify_cli import app
         runner = CliRunner()
         result = runner.invoke(app, [
-            "init", "test-project", "--integration", "nonexistent",
+            "init", str(tmp_path / "test-project"), "--integration", "nonexistent",
         ])
         assert result.exit_code != 0
         assert "Unknown integration" in result.output

tests/integrations/test_integration_agy.py

@@ -0,0 +1,25 @@
+"""Tests for AgyIntegration (Antigravity)."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestAgyIntegration(SkillsIntegrationTests):
+    KEY = "agy"
+    FOLDER = ".agent/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".agent/skills"
+    CONTEXT_FILE = "AGENTS.md"
+
+
+class TestAgyAutoPromote:
+    """--ai agy auto-promotes to integration path."""
+
+    def test_ai_agy_without_ai_skills_auto_promotes(self, tmp_path):
+        """--ai agy (without --ai-skills) should auto-promote to integration."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path / "test-proj"), "--ai", "agy"])
+
+        assert "--integration agy" in result.output

tests/integrations/test_integration_base_skills.py

@@ -0,0 +1,402 @@
+"""Reusable test mixin for standard SkillsIntegration subclasses.
+
+Each per-agent test file sets ``KEY``, ``FOLDER``, ``COMMANDS_SUBDIR``,
+``REGISTRAR_DIR``, and ``CONTEXT_FILE``, then inherits all verification
+logic from ``SkillsIntegrationTests``.
+
+Mirrors ``MarkdownIntegrationTests`` / ``TomlIntegrationTests`` closely,
+adapted for the ``speckit-<name>/SKILL.md`` skills layout.
+"""
+
+import os
+
+import yaml
+
+from specify_cli.integrations import INTEGRATION_REGISTRY, get_integration
+from specify_cli.integrations.base import SkillsIntegration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class SkillsIntegrationTests:
+    """Mixin — set class-level constants and inherit these tests.
+
+    Required class attrs on subclass::
+
+        KEY: str              — integration registry key
+        FOLDER: str           — e.g. ".agents/"
+        COMMANDS_SUBDIR: str  — e.g. "skills"
+        REGISTRAR_DIR: str    — e.g. ".agents/skills"
+        CONTEXT_FILE: str     — e.g. "AGENTS.md"
+    """
+
+    KEY: str
+    FOLDER: str
+    COMMANDS_SUBDIR: str
+    REGISTRAR_DIR: str
+    CONTEXT_FILE: str
+
+    # -- Registration -----------------------------------------------------
+
+    def test_registered(self):
+        assert self.KEY in INTEGRATION_REGISTRY
+        assert get_integration(self.KEY) is not None
+
+    def test_is_skills_integration(self):
+        assert isinstance(get_integration(self.KEY), SkillsIntegration)
+
+    # -- Config -----------------------------------------------------------
+
+    def test_config_folder(self):
+        i = get_integration(self.KEY)
+        assert i.config["folder"] == self.FOLDER
+
+    def test_config_commands_subdir(self):
+        i = get_integration(self.KEY)
+        assert i.config["commands_subdir"] == self.COMMANDS_SUBDIR
+
+    def test_registrar_config(self):
+        i = get_integration(self.KEY)
+        assert i.registrar_config["dir"] == self.REGISTRAR_DIR
+        assert i.registrar_config["format"] == "markdown"
+        assert i.registrar_config["args"] == "$ARGUMENTS"
+        assert i.registrar_config["extension"] == "/SKILL.md"
+
+    def test_context_file(self):
+        i = get_integration(self.KEY)
+        assert i.context_file == self.CONTEXT_FILE
+
+    # -- Setup / teardown -------------------------------------------------
+
+    def test_setup_creates_files(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        assert len(created) > 0
+        skill_files = [f for f in created if "scripts" not in f.parts]
+        for f in skill_files:
+            assert f.exists()
+            assert f.name == "SKILL.md"
+            assert f.parent.name.startswith("speckit-")
+
+    def test_setup_writes_to_correct_directory(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        expected_dir = i.skills_dest(tmp_path)
+        assert expected_dir.exists(), f"Expected directory {expected_dir} was not created"
+        skill_files = [f for f in created if "scripts" not in f.parts]
+        assert len(skill_files) > 0, "No skill files were created"
+        for f in skill_files:
+            # Each SKILL.md is in speckit-<name>/ under the skills directory
+            assert f.resolve().parent.parent == expected_dir.resolve(), (
+                f"{f} is not under {expected_dir}"
+            )
+
+    def test_skill_directory_structure(self, tmp_path):
+        """Each command produces speckit-<name>/SKILL.md."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        skill_files = [f for f in created if "scripts" not in f.parts]
+
+        expected_commands = {
+            "analyze", "checklist", "clarify", "constitution",
+            "implement", "plan", "specify", "tasks", "taskstoissues",
+        }
+
+        # Derive command names from the skill directory names
+        actual_commands = set()
+        for f in skill_files:
+            skill_dir_name = f.parent.name  # e.g. "speckit-plan"
+            assert skill_dir_name.startswith("speckit-")
+            actual_commands.add(skill_dir_name.removeprefix("speckit-"))
+
+        assert actual_commands == expected_commands
+
+    def test_skill_frontmatter_structure(self, tmp_path):
+        """SKILL.md must have name, description, compatibility, metadata."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        skill_files = [f for f in created if "scripts" not in f.parts]
+
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            assert content.startswith("---\n"), f"{f} missing frontmatter"
+            parts = content.split("---", 2)
+            fm = yaml.safe_load(parts[1])
+            assert "name" in fm, f"{f} frontmatter missing 'name'"
+            assert "description" in fm, f"{f} frontmatter missing 'description'"
+            assert "compatibility" in fm, f"{f} frontmatter missing 'compatibility'"
+            assert "metadata" in fm, f"{f} frontmatter missing 'metadata'"
+            assert fm["metadata"]["author"] == "github-spec-kit"
+            assert "source" in fm["metadata"]
+
+    def test_skill_uses_template_descriptions(self, tmp_path):
+        """SKILL.md should use the original template description for ZIP parity."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        skill_files = [f for f in created if "scripts" not in f.parts]
+
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            parts = content.split("---", 2)
+            fm = yaml.safe_load(parts[1])
+            # Description must be a non-empty string (from the template)
+            assert isinstance(fm["description"], str)
+            assert len(fm["description"]) > 0, f"{f} has empty description"
+
+    def test_templates_are_processed(self, tmp_path):
+        """Skill body must have placeholders replaced, not raw templates."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        skill_files = [f for f in created if "scripts" not in f.parts]
+        assert len(skill_files) > 0
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            assert "{SCRIPT}" not in content, f"{f.name} has unprocessed {{SCRIPT}}"
+            assert "__AGENT__" not in content, f"{f.name} has unprocessed __AGENT__"
+            assert "{ARGS}" not in content, f"{f.name} has unprocessed {{ARGS}}"
+
+    def test_skill_body_has_content(self, tmp_path):
+        """Each SKILL.md body should contain template content after the frontmatter."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        skill_files = [f for f in created if "scripts" not in f.parts]
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            # Body is everything after the second ---
+            parts = content.split("---", 2)
+            body = parts[2].strip() if len(parts) >= 3 else ""
+            assert len(body) > 0, f"{f} has empty body"
+
+    def test_all_files_tracked_in_manifest(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        for f in created:
+            rel = f.resolve().relative_to(tmp_path.resolve()).as_posix()
+            assert rel in m.files, f"{rel} not tracked in manifest"
+
+    def test_install_uninstall_roundtrip(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.install(tmp_path, m)
+        assert len(created) > 0
+        m.save()
+        for f in created:
+            assert f.exists()
+        removed, skipped = i.uninstall(tmp_path, m)
+        assert len(removed) == len(created)
+        assert skipped == []
+
+    def test_modified_file_survives_uninstall(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.install(tmp_path, m)
+        m.save()
+        modified_file = created[0]
+        modified_file.write_text("user modified this", encoding="utf-8")
+        removed, skipped = i.uninstall(tmp_path, m)
+        assert modified_file.exists()
+        assert modified_file in skipped
+
+    def test_pre_existing_skills_not_removed(self, tmp_path):
+        """Pre-existing non-speckit skills should be left untouched."""
+        i = get_integration(self.KEY)
+        skills_dir = i.skills_dest(tmp_path)
+        foreign_dir = skills_dir / "other-tool"
+        foreign_dir.mkdir(parents=True)
+        (foreign_dir / "SKILL.md").write_text("# Foreign skill\n")
+
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+
+        assert (foreign_dir / "SKILL.md").exists(), "Foreign skill was removed"
+
+    # -- Scripts ----------------------------------------------------------
+
+    def test_setup_installs_update_context_scripts(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        scripts_dir = tmp_path / ".specify" / "integrations" / self.KEY / "scripts"
+        assert scripts_dir.is_dir(), f"Scripts directory not created for {self.KEY}"
+        assert (scripts_dir / "update-context.sh").exists()
+        assert (scripts_dir / "update-context.ps1").exists()
+
+    def test_scripts_tracked_in_manifest(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        script_rels = [k for k in m.files if "update-context" in k]
+        assert len(script_rels) >= 2
+
+    def test_sh_script_is_executable(self, tmp_path):
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        sh = tmp_path / ".specify" / "integrations" / self.KEY / "scripts" / "update-context.sh"
+        assert os.access(sh, os.X_OK)
+
+    # -- CLI auto-promote -------------------------------------------------
+
+    def test_ai_flag_auto_promotes(self, tmp_path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / f"promote-{self.KEY}"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--ai", self.KEY, "--script", "sh", "--no-git",
+                "--ignore-agent-tools",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init --ai {self.KEY} failed: {result.output}"
+        assert f"--integration {self.KEY}" in result.output
+
+    def test_integration_flag_creates_files(self, tmp_path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / f"int-{self.KEY}"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--integration", self.KEY, "--script", "sh", "--no-git",
+                "--ignore-agent-tools",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init --integration {self.KEY} failed: {result.output}"
+        i = get_integration(self.KEY)
+        skills_dir = i.skills_dest(project)
+        assert skills_dir.is_dir(), f"Skills directory {skills_dir} not created"
+
+    # -- IntegrationOption ------------------------------------------------
+
+    def test_options_include_skills_flag(self):
+        i = get_integration(self.KEY)
+        opts = i.options()
+        skills_opts = [o for o in opts if o.name == "--skills"]
+        assert len(skills_opts) == 1
+        assert skills_opts[0].is_flag is True
+
+    # -- Complete file inventory ------------------------------------------
+
+    _SKILL_COMMANDS = [
+        "analyze", "checklist", "clarify", "constitution",
+        "implement", "plan", "specify", "tasks", "taskstoissues",
+    ]
+
+    def _expected_files(self, script_variant: str) -> list[str]:
+        """Build the full expected file list for a given script variant."""
+        i = get_integration(self.KEY)
+        skills_prefix = i.config["folder"].rstrip("/") + "/" + i.config.get("commands_subdir", "skills")
+
+        files = []
+        # Skill files
+        for cmd in self._SKILL_COMMANDS:
+            files.append(f"{skills_prefix}/speckit-{cmd}/SKILL.md")
+        # Integration metadata
+        files += [
+            ".specify/init-options.json",
+            ".specify/integration.json",
+            f".specify/integrations/{self.KEY}.manifest.json",
+            f".specify/integrations/{self.KEY}/scripts/update-context.ps1",
+            f".specify/integrations/{self.KEY}/scripts/update-context.sh",
+            ".specify/integrations/speckit.manifest.json",
+            ".specify/memory/constitution.md",
+        ]
+        # Script variant
+        if script_variant == "sh":
+            files += [
+                ".specify/scripts/bash/check-prerequisites.sh",
+                ".specify/scripts/bash/common.sh",
+                ".specify/scripts/bash/create-new-feature.sh",
+                ".specify/scripts/bash/setup-plan.sh",
+                ".specify/scripts/bash/update-agent-context.sh",
+            ]
+        else:
+            files += [
+                ".specify/scripts/powershell/check-prerequisites.ps1",
+                ".specify/scripts/powershell/common.ps1",
+                ".specify/scripts/powershell/create-new-feature.ps1",
+                ".specify/scripts/powershell/setup-plan.ps1",
+                ".specify/scripts/powershell/update-agent-context.ps1",
+            ]
+        # Templates
+        files += [
+            ".specify/templates/agent-file-template.md",
+            ".specify/templates/checklist-template.md",
+            ".specify/templates/constitution-template.md",
+            ".specify/templates/plan-template.md",
+            ".specify/templates/spec-template.md",
+            ".specify/templates/tasks-template.md",
+        ]
+        return sorted(files)
+
+    def test_complete_file_inventory_sh(self, tmp_path):
+        """Every file produced by specify init --integration <key> --script sh."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / f"inventory-sh-{self.KEY}"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", self.KEY,
+                "--script", "sh", "--no-git", "--ignore-agent-tools",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init failed: {result.output}"
+        actual = sorted(
+            p.relative_to(project).as_posix()
+            for p in project.rglob("*") if p.is_file()
+        )
+        expected = self._expected_files("sh")
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )
+
+    def test_complete_file_inventory_ps(self, tmp_path):
+        """Every file produced by specify init --integration <key> --script ps."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / f"inventory-ps-{self.KEY}"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", self.KEY,
+                "--script", "ps", "--no-git", "--ignore-agent-tools",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init failed: {result.output}"
+        actual = sorted(
+            p.relative_to(project).as_posix()
+            for p in project.rglob("*") if p.is_file()
+        )
+        expected = self._expected_files("ps")
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )

tests/integrations/test_integration_codex.py

@@ -0,0 +1,25 @@
+"""Tests for CodexIntegration."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestCodexIntegration(SkillsIntegrationTests):
+    KEY = "codex"
+    FOLDER = ".agents/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".agents/skills"
+    CONTEXT_FILE = "AGENTS.md"
+
+
+class TestCodexAutoPromote:
+    """--ai codex auto-promotes to integration path."""
+
+    def test_ai_codex_without_ai_skills_auto_promotes(self, tmp_path):
+        """--ai codex (without --ai-skills) should auto-promote to integration."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path / "test-proj"), "--ai", "codex"])
+
+        assert "--integration codex" in result.output

tests/integrations/test_integration_generic.py

@@ -0,0 +1,311 @@
+"""Tests for GenericIntegration."""
+
+import os
+
+import pytest
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.base import MarkdownIntegration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class TestGenericIntegration:
+    """Tests for GenericIntegration — requires --commands-dir option."""
+
+    # -- Registration -----------------------------------------------------
+
+    def test_registered(self):
+        from specify_cli.integrations import INTEGRATION_REGISTRY
+        assert "generic" in INTEGRATION_REGISTRY
+
+    def test_is_markdown_integration(self):
+        assert isinstance(get_integration("generic"), MarkdownIntegration)
+
+    # -- Config -----------------------------------------------------------
+
+    def test_config_folder_is_none(self):
+        i = get_integration("generic")
+        assert i.config["folder"] is None
+
+    def test_config_requires_cli_false(self):
+        i = get_integration("generic")
+        assert i.config["requires_cli"] is False
+
+    def test_context_file_is_none(self):
+        i = get_integration("generic")
+        assert i.context_file is None
+
+    # -- Options ----------------------------------------------------------
+
+    def test_options_include_commands_dir(self):
+        i = get_integration("generic")
+        opts = i.options()
+        assert len(opts) == 1
+        assert opts[0].name == "--commands-dir"
+        assert opts[0].required is True
+        assert opts[0].is_flag is False
+
+    # -- Setup / teardown -------------------------------------------------
+
+    def test_setup_requires_commands_dir(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        with pytest.raises(ValueError, match="--commands-dir is required"):
+            i.setup(tmp_path, m, parsed_options={})
+
+    def test_setup_requires_nonempty_commands_dir(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        with pytest.raises(ValueError, match="--commands-dir is required"):
+            i.setup(tmp_path, m, parsed_options={"commands_dir": ""})
+
+    def test_setup_writes_to_correct_directory(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        created = i.setup(
+            tmp_path, m,
+            parsed_options={"commands_dir": ".myagent/commands"},
+        )
+        expected_dir = tmp_path / ".myagent" / "commands"
+        assert expected_dir.exists(), f"Expected directory {expected_dir} was not created"
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) > 0, "No command files were created"
+        for f in cmd_files:
+            assert f.resolve().parent == expected_dir.resolve(), (
+                f"{f} is not under {expected_dir}"
+            )
+
+    def test_setup_creates_md_files(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        created = i.setup(
+            tmp_path, m,
+            parsed_options={"commands_dir": ".custom/cmds"},
+        )
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) > 0
+        for f in cmd_files:
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".md")
+
+    def test_templates_are_processed(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        created = i.setup(
+            tmp_path, m,
+            parsed_options={"commands_dir": ".custom/cmds"},
+        )
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        for f in cmd_files:
+            content = f.read_text(encoding="utf-8")
+            assert "{SCRIPT}" not in content, f"{f.name} has unprocessed {{SCRIPT}}"
+            assert "__AGENT__" not in content, f"{f.name} has unprocessed __AGENT__"
+            assert "{ARGS}" not in content, f"{f.name} has unprocessed {{ARGS}}"
+
+    def test_all_files_tracked_in_manifest(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        created = i.setup(
+            tmp_path, m,
+            parsed_options={"commands_dir": ".custom/cmds"},
+        )
+        for f in created:
+            rel = f.resolve().relative_to(tmp_path.resolve()).as_posix()
+            assert rel in m.files, f"{rel} not tracked in manifest"
+
+    def test_install_uninstall_roundtrip(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        created = i.install(
+            tmp_path, m,
+            parsed_options={"commands_dir": ".custom/cmds"},
+        )
+        assert len(created) > 0
+        m.save()
+        for f in created:
+            assert f.exists()
+        removed, skipped = i.uninstall(tmp_path, m)
+        assert len(removed) == len(created)
+        assert skipped == []
+
+    def test_modified_file_survives_uninstall(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        created = i.install(
+            tmp_path, m,
+            parsed_options={"commands_dir": ".custom/cmds"},
+        )
+        m.save()
+        modified = created[0]
+        modified.write_text("user modified this", encoding="utf-8")
+        removed, skipped = i.uninstall(tmp_path, m)
+        assert modified.exists()
+        assert modified in skipped
+
+    def test_different_commands_dirs(self, tmp_path):
+        """Generic should work with various user-specified paths."""
+        for path in [".agent/commands", "tools/ai-cmds", ".custom/prompts"]:
+            project = tmp_path / path.replace("/", "-")
+            project.mkdir()
+            i = get_integration("generic")
+            m = IntegrationManifest("generic", project)
+            created = i.setup(
+                project, m,
+                parsed_options={"commands_dir": path},
+            )
+            expected = project / path
+            assert expected.is_dir(), f"Dir {expected} not created for {path}"
+            cmd_files = [f for f in created if "scripts" not in f.parts]
+            assert len(cmd_files) > 0
+
+    # -- Scripts ----------------------------------------------------------
+
+    def test_setup_installs_update_context_scripts(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        scripts_dir = tmp_path / ".specify" / "integrations" / "generic" / "scripts"
+        assert scripts_dir.is_dir(), "Scripts directory not created for generic"
+        assert (scripts_dir / "update-context.sh").exists()
+        assert (scripts_dir / "update-context.ps1").exists()
+
+    def test_scripts_tracked_in_manifest(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        script_rels = [k for k in m.files if "update-context" in k]
+        assert len(script_rels) >= 2
+
+    def test_sh_script_is_executable(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        sh = tmp_path / ".specify" / "integrations" / "generic" / "scripts" / "update-context.sh"
+        assert os.access(sh, os.X_OK)
+
+    # -- CLI --------------------------------------------------------------
+
+    def test_cli_generic_without_commands_dir_fails(self, tmp_path):
+        """--integration generic without --ai-commands-dir should fail."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        runner = CliRunner()
+        result = runner.invoke(app, [
+            "init", str(tmp_path / "test-generic"), "--integration", "generic",
+            "--script", "sh", "--no-git",
+        ])
+        # Generic requires --commands-dir / --ai-commands-dir
+        # The integration path validates via setup()
+        assert result.exit_code != 0
+
+    def test_complete_file_inventory_sh(self, tmp_path):
+        """Every file produced by specify init --integration generic --ai-commands-dir ... --script sh."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "inventory-generic-sh"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "generic",
+                "--ai-commands-dir", ".myagent/commands",
+                "--script", "sh", "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init failed: {result.output}"
+        actual = sorted(
+            p.relative_to(project).as_posix()
+            for p in project.rglob("*") if p.is_file()
+        )
+        expected = sorted([
+            ".myagent/commands/speckit.analyze.md",
+            ".myagent/commands/speckit.checklist.md",
+            ".myagent/commands/speckit.clarify.md",
+            ".myagent/commands/speckit.constitution.md",
+            ".myagent/commands/speckit.implement.md",
+            ".myagent/commands/speckit.plan.md",
+            ".myagent/commands/speckit.specify.md",
+            ".myagent/commands/speckit.tasks.md",
+            ".myagent/commands/speckit.taskstoissues.md",
+            ".specify/init-options.json",
+            ".specify/integration.json",
+            ".specify/integrations/generic.manifest.json",
+            ".specify/integrations/generic/scripts/update-context.ps1",
+            ".specify/integrations/generic/scripts/update-context.sh",
+            ".specify/integrations/speckit.manifest.json",
+            ".specify/memory/constitution.md",
+            ".specify/scripts/bash/check-prerequisites.sh",
+            ".specify/scripts/bash/common.sh",
+            ".specify/scripts/bash/create-new-feature.sh",
+            ".specify/scripts/bash/setup-plan.sh",
+            ".specify/scripts/bash/update-agent-context.sh",
+            ".specify/templates/agent-file-template.md",
+            ".specify/templates/checklist-template.md",
+            ".specify/templates/constitution-template.md",
+            ".specify/templates/plan-template.md",
+            ".specify/templates/spec-template.md",
+            ".specify/templates/tasks-template.md",
+        ])
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )
+
+    def test_complete_file_inventory_ps(self, tmp_path):
+        """Every file produced by specify init --integration generic --ai-commands-dir ... --script ps."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "inventory-generic-ps"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "generic",
+                "--ai-commands-dir", ".myagent/commands",
+                "--script", "ps", "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init failed: {result.output}"
+        actual = sorted(
+            p.relative_to(project).as_posix()
+            for p in project.rglob("*") if p.is_file()
+        )
+        expected = sorted([
+            ".myagent/commands/speckit.analyze.md",
+            ".myagent/commands/speckit.checklist.md",
+            ".myagent/commands/speckit.clarify.md",
+            ".myagent/commands/speckit.constitution.md",
+            ".myagent/commands/speckit.implement.md",
+            ".myagent/commands/speckit.plan.md",
+            ".myagent/commands/speckit.specify.md",
+            ".myagent/commands/speckit.tasks.md",
+            ".myagent/commands/speckit.taskstoissues.md",
+            ".specify/init-options.json",
+            ".specify/integration.json",
+            ".specify/integrations/generic.manifest.json",
+            ".specify/integrations/generic/scripts/update-context.ps1",
+            ".specify/integrations/generic/scripts/update-context.sh",
+            ".specify/integrations/speckit.manifest.json",
+            ".specify/memory/constitution.md",
+            ".specify/scripts/powershell/check-prerequisites.ps1",
+            ".specify/scripts/powershell/common.ps1",
+            ".specify/scripts/powershell/create-new-feature.ps1",
+            ".specify/scripts/powershell/setup-plan.ps1",
+            ".specify/scripts/powershell/update-agent-context.ps1",
+            ".specify/templates/agent-file-template.md",
+            ".specify/templates/checklist-template.md",
+            ".specify/templates/constitution-template.md",
+            ".specify/templates/plan-template.md",
+            ".specify/templates/spec-template.md",
+            ".specify/templates/tasks-template.md",
+        ])
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )

tests/integrations/test_integration_kimi.py

@@ -0,0 +1,149 @@
+"""Tests for KimiIntegration — skills integration with legacy migration."""
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.kimi import _migrate_legacy_kimi_dotted_skills
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestKimiIntegration(SkillsIntegrationTests):
+    KEY = "kimi"
+    FOLDER = ".kimi/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".kimi/skills"
+    CONTEXT_FILE = "KIMI.md"
+
+
+class TestKimiOptions:
+    """Kimi declares --skills and --migrate-legacy options."""
+
+    def test_migrate_legacy_option(self):
+        i = get_integration("kimi")
+        opts = i.options()
+        migrate_opts = [o for o in opts if o.name == "--migrate-legacy"]
+        assert len(migrate_opts) == 1
+        assert migrate_opts[0].is_flag is True
+        assert migrate_opts[0].default is False
+
+
+class TestKimiLegacyMigration:
+    """Test Kimi dotted → hyphenated skill directory migration."""
+
+    def test_migrate_dotted_to_hyphenated(self, tmp_path):
+        skills_dir = tmp_path / ".kimi" / "skills"
+        legacy = skills_dir / "speckit.plan"
+        legacy.mkdir(parents=True)
+        (legacy / "SKILL.md").write_text("# Plan Skill\n")
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 1
+        assert removed == 0
+        assert not legacy.exists()
+        assert (skills_dir / "speckit-plan" / "SKILL.md").exists()
+
+    def test_skip_when_target_exists_different_content(self, tmp_path):
+        skills_dir = tmp_path / ".kimi" / "skills"
+        legacy = skills_dir / "speckit.plan"
+        legacy.mkdir(parents=True)
+        (legacy / "SKILL.md").write_text("# Old\n")
+
+        target = skills_dir / "speckit-plan"
+        target.mkdir(parents=True)
+        (target / "SKILL.md").write_text("# New (different)\n")
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 0
+        assert removed == 0
+        assert legacy.exists()
+        assert target.exists()
+
+    def test_remove_when_target_exists_same_content(self, tmp_path):
+        skills_dir = tmp_path / ".kimi" / "skills"
+        content = "# Identical\n"
+        legacy = skills_dir / "speckit.plan"
+        legacy.mkdir(parents=True)
+        (legacy / "SKILL.md").write_text(content)
+
+        target = skills_dir / "speckit-plan"
+        target.mkdir(parents=True)
+        (target / "SKILL.md").write_text(content)
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 0
+        assert removed == 1
+        assert not legacy.exists()
+        assert target.exists()
+
+    def test_preserve_legacy_with_extra_files(self, tmp_path):
+        skills_dir = tmp_path / ".kimi" / "skills"
+        content = "# Same\n"
+        legacy = skills_dir / "speckit.plan"
+        legacy.mkdir(parents=True)
+        (legacy / "SKILL.md").write_text(content)
+        (legacy / "extra.md").write_text("user file")
+
+        target = skills_dir / "speckit-plan"
+        target.mkdir(parents=True)
+        (target / "SKILL.md").write_text(content)
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 0
+        assert removed == 0
+        assert legacy.exists()
+
+    def test_nonexistent_dir_returns_zeros(self, tmp_path):
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(
+            tmp_path / ".kimi" / "skills"
+        )
+        assert migrated == 0
+        assert removed == 0
+
+    def test_setup_with_migrate_legacy_option(self, tmp_path):
+        """KimiIntegration.setup() with --migrate-legacy migrates dotted dirs."""
+        i = get_integration("kimi")
+
+        skills_dir = tmp_path / ".kimi" / "skills"
+        legacy = skills_dir / "speckit.oldcmd"
+        legacy.mkdir(parents=True)
+        (legacy / "SKILL.md").write_text("# Legacy\n")
+
+        m = IntegrationManifest("kimi", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"migrate_legacy": True})
+
+        assert not legacy.exists()
+        assert (skills_dir / "speckit-oldcmd" / "SKILL.md").exists()
+        # New skills from templates should also exist
+        assert (skills_dir / "speckit-specify" / "SKILL.md").exists()
+
+
+class TestKimiNextSteps:
+    """CLI output tests for kimi next-steps display."""
+
+    def test_next_steps_show_skill_invocation(self, tmp_path):
+        """Kimi next-steps guidance should display /skill:speckit-* usage."""
+        import os
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "kimi-next-steps"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--ai", "kimi", "--no-git",
+                "--ignore-agent-tools", "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0
+        assert "/skill:speckit-constitution" in result.output
+        assert "/speckit.constitution" not in result.output
+        assert "Optional skills that you can use for your specs" in result.output

tests/integrations/test_integration_kiro_cli.py

@@ -1,5 +1,7 @@
 """Tests for KiroCliIntegration."""
 
+import os
+
 from .test_integration_base_markdown import MarkdownIntegrationTests
 
 
@@ -9,3 +11,30 @@ class TestKiroCliIntegration(MarkdownIntegrationTests):
     COMMANDS_SUBDIR = "prompts"
     REGISTRAR_DIR = ".kiro/prompts"
     CONTEXT_FILE = "AGENTS.md"
+
+
+class TestKiroAlias:
+    """--ai kiro alias normalizes to kiro-cli and auto-promotes."""
+
+    def test_kiro_alias_normalized_to_kiro_cli(self, tmp_path):
+        """--ai kiro should normalize to canonical kiro-cli and auto-promote."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        target = tmp_path / "kiro-alias-proj"
+        target.mkdir()
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(target)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--ai", "kiro",
+                "--ignore-agent-tools", "--script", "sh", "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0
+        assert "--integration kiro-cli" in result.output
+        assert (target / ".kiro" / "prompts" / "speckit.plan.md").exists()

tests/integrations/test_registry.py

@@ -11,13 +11,17 @@ from specify_cli.integrations.base import MarkdownIntegration
 from .conftest import StubIntegration
 
 
-# Every integration key that must be registered (Stage 2 + Stage 3).
+# Every integration key that must be registered (Stage 2 + Stage 3 + Stage 4 + Stage 5).
 ALL_INTEGRATION_KEYS = [
     "copilot",
     # Stage 3 — standard markdown integrations
     "claude", "qwen", "opencode", "junie", "kilocode", "auggie",
     "roo", "codebuddy", "qodercli", "amp", "shai", "bob", "trae",
     "pi", "iflow", "kiro-cli", "windsurf", "vibe", "cursor-agent",
+    # Stage 4 — TOML integrations
+    "gemini", "tabnine",
+    # Stage 5 — skills, generic & option-driven integrations
+    "codex", "kimi", "agy", "generic",
 ]
 
 
@@ -61,9 +65,16 @@ class TestRegistryCompleteness:
 
 
 class TestRegistrarKeyAlignment:
-    """Every integration key must have a matching AGENT_CONFIGS entry."""
+    """Every integration key must have a matching AGENT_CONFIGS entry.
 
-    @pytest.mark.parametrize("key", ALL_INTEGRATION_KEYS)
+    ``generic`` is excluded because it has no fixed directory — its
+    output path comes from ``--commands-dir`` at runtime.
+    """
+
+    @pytest.mark.parametrize(
+        "key",
+        [k for k in ALL_INTEGRATION_KEYS if k != "generic"],
+    )
     def test_integration_key_in_registrar(self, key):
         from specify_cli.agents import CommandRegistrar
         assert key in CommandRegistrar.AGENT_CONFIGS, (