chore: import upstream snapshot with attribution

tests/integrations/conftest.py

@@ -0,0 +1,58 @@
+"""Shared test helpers for integration tests."""
+
+import pytest
+
+from specify_cli.integrations.base import MarkdownIntegration
+
+
+def _redirect_home(monkeypatch: pytest.MonkeyPatch, home) -> None:
+    """Point HOME/USERPROFILE/XDG env vars at an isolated *home* directory."""
+    for path in (home, home / ".cache", home / ".config", home / ".local" / "share"):
+        path.mkdir(parents=True, exist_ok=True)
+
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
+    monkeypatch.setenv("XDG_CACHE_HOME", str(home / ".cache"))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(home / ".config"))
+    monkeypatch.setenv("XDG_DATA_HOME", str(home / ".local" / "share"))
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _isolate_integration_home_session(tmp_path_factory):
+    """Isolate the user home for setup that runs outside a test function.
+
+    The per-test fixture below re-points HOME for each test, but function-scoped
+    fixtures do not apply to module-/session-scoped fixtures. Some of those (e.g.
+    the ``status_*_template`` fixtures in ``test_integration_subcommand.py``) run
+    ``specify init`` during setup, before any per-test isolation takes effect.
+    A standalone ``MonkeyPatch`` gives them an isolated home too.
+    """
+    monkeypatch = pytest.MonkeyPatch()
+    _redirect_home(monkeypatch, tmp_path_factory.mktemp("session-home"))
+    yield
+    monkeypatch.undo()
+
+
+@pytest.fixture(autouse=True)
+def _isolate_integration_home(monkeypatch: pytest.MonkeyPatch, tmp_path):
+    """Keep integration tests from reading or writing the real user home."""
+    _redirect_home(monkeypatch, tmp_path / "home")
+
+
+class StubIntegration(MarkdownIntegration):
+    """Minimal concrete integration for testing."""
+
+    key = "stub"
+    config = {
+        "name": "Stub Agent",
+        "folder": ".stub/",
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".stub/commands",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".md",
+    }

tests/integrations/test_base.py

@@ -0,0 +1,558 @@
+"""Tests for IntegrationOption, IntegrationBase, MarkdownIntegration, and primitives."""
+
+import sys
+
+import pytest
+
+from specify_cli.integrations.base import (
+    IntegrationBase,
+    IntegrationOption,
+    MarkdownIntegration,
+    SkillsIntegration,
+)
+from specify_cli.integrations.manifest import IntegrationManifest
+from .conftest import StubIntegration
+
+
+class TestIntegrationOption:
+    def test_defaults(self):
+        opt = IntegrationOption(name="--flag")
+        assert opt.name == "--flag"
+        assert opt.is_flag is False
+        assert opt.required is False
+        assert opt.default is None
+        assert opt.help == ""
+
+    def test_flag_option(self):
+        opt = IntegrationOption(name="--skills", is_flag=True, default=True, help="Enable skills")
+        assert opt.is_flag is True
+        assert opt.default is True
+        assert opt.help == "Enable skills"
+
+    def test_required_option(self):
+        opt = IntegrationOption(name="--commands-dir", required=True, help="Dir path")
+        assert opt.required is True
+
+    def test_frozen(self):
+        opt = IntegrationOption(name="--x")
+        with pytest.raises(AttributeError):
+            opt.name = "--y"  # type: ignore[misc]
+
+
+class TestIntegrationBase:
+    def test_key_and_config(self):
+        i = StubIntegration()
+        assert i.key == "stub"
+        assert i.config["name"] == "Stub Agent"
+        assert i.registrar_config["format"] == "markdown"
+
+    def test_options_default_empty(self):
+        assert StubIntegration.options() == []
+
+    def test_shared_commands_dir(self):
+        i = StubIntegration()
+        cmd_dir = i.shared_commands_dir()
+        assert cmd_dir is not None
+        assert cmd_dir.is_dir()
+
+    def test_setup_uses_shared_templates(self, tmp_path):
+        i = StubIntegration()
+        manifest = IntegrationManifest("stub", tmp_path)
+        created = i.setup(tmp_path, manifest)
+        assert len(created) > 0
+        for f in created:
+            assert f.parent == tmp_path / ".stub" / "commands"
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".md")
+
+    def test_setup_copies_templates(self, tmp_path, monkeypatch):
+        tpl = tmp_path / "_templates"
+        tpl.mkdir()
+        (tpl / "plan.md").write_text("plan content", encoding="utf-8")
+        (tpl / "specify.md").write_text("spec content", encoding="utf-8")
+
+        i = StubIntegration()
+        monkeypatch.setattr(type(i), "list_command_templates", lambda self: sorted(tpl.glob("*.md")))
+
+        project = tmp_path / "project"
+        project.mkdir()
+        created = i.setup(project, IntegrationManifest("stub", project))
+        assert len(created) == 2
+        assert (project / ".stub" / "commands" / "speckit.plan.md").exists()
+        assert (project / ".stub" / "commands" / "speckit.specify.md").exists()
+
+    def test_install_delegates_to_setup(self, tmp_path):
+        i = StubIntegration()
+        manifest = IntegrationManifest("stub", tmp_path)
+        result = i.install(tmp_path, manifest)
+        assert len(result) > 0
+
+    def test_uninstall_delegates_to_teardown(self, tmp_path):
+        i = StubIntegration()
+        manifest = IntegrationManifest("stub", tmp_path)
+        removed, skipped = i.uninstall(tmp_path, manifest)
+        assert removed == []
+        assert skipped == []
+
+
+class TestMarkdownIntegration:
+    def test_is_subclass_of_base(self):
+        assert issubclass(MarkdownIntegration, IntegrationBase)
+
+    def test_stub_is_markdown(self):
+        assert isinstance(StubIntegration(), MarkdownIntegration)
+
+
+class TestBasePrimitives:
+    def test_shared_commands_dir_returns_path(self):
+        i = StubIntegration()
+        cmd_dir = i.shared_commands_dir()
+        assert cmd_dir is not None
+        assert cmd_dir.is_dir()
+
+    def test_shared_templates_dir_returns_path(self):
+        i = StubIntegration()
+        tpl_dir = i.shared_templates_dir()
+        assert tpl_dir is not None
+        assert tpl_dir.is_dir()
+
+    def test_list_command_templates_returns_md_files(self):
+        i = StubIntegration()
+        templates = i.list_command_templates()
+        assert len(templates) > 0
+        assert all(t.suffix == ".md" for t in templates)
+
+    def test_list_command_templates_keeps_checklist_after_plan(self):
+        i = StubIntegration()
+        stems = [template.stem for template in i.list_command_templates()]
+        assert stems.index("plan") < stems.index("checklist")
+
+    def test_command_filename_default(self):
+        i = StubIntegration()
+        assert i.command_filename("plan") == "speckit.plan.md"
+
+    def test_commands_dest(self, tmp_path):
+        i = StubIntegration()
+        dest = i.commands_dest(tmp_path)
+        assert dest == tmp_path / ".stub" / "commands"
+
+    def test_commands_dest_no_config_raises(self, tmp_path):
+        class NoConfig(MarkdownIntegration):
+            key = "noconfig"
+        with pytest.raises(ValueError, match="config is not set"):
+            NoConfig().commands_dest(tmp_path)
+
+    def test_copy_command_to_directory(self, tmp_path):
+        src = tmp_path / "source.md"
+        src.write_text("content", encoding="utf-8")
+        dest_dir = tmp_path / "output"
+        result = IntegrationBase.copy_command_to_directory(src, dest_dir, "speckit.plan.md")
+        assert result == dest_dir / "speckit.plan.md"
+        assert result.read_text(encoding="utf-8") == "content"
+
+    def test_record_file_in_manifest(self, tmp_path):
+        f = tmp_path / "f.txt"
+        f.write_text("hello", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        IntegrationBase.record_file_in_manifest(f, tmp_path, m)
+        assert "f.txt" in m.files
+
+    def test_write_file_and_record(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        dest = tmp_path / "sub" / "f.txt"
+        result = IntegrationBase.write_file_and_record("content", dest, tmp_path, m)
+        assert result == dest
+        assert dest.read_text(encoding="utf-8") == "content"
+        assert "sub/f.txt" in m.files
+
+    def test_setup_copies_shared_templates(self, tmp_path):
+        i = StubIntegration()
+        m = IntegrationManifest("stub", tmp_path)
+        created = i.setup(tmp_path, m)
+        assert len(created) > 0
+        for f in created:
+            assert f.parent.name == "commands"
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".md")
+
+
+class TestBuildCommandInvocation:
+    """Tests for build_command_invocation across integration types."""
+
+    def test_base_core_command_dotted(self):
+        i = StubIntegration()
+        assert i.build_command_invocation("speckit.plan") == "/speckit.plan"
+
+    def test_base_core_command_bare(self):
+        i = StubIntegration()
+        assert i.build_command_invocation("plan") == "/speckit.plan"
+
+    def test_base_core_command_with_args(self):
+        i = StubIntegration()
+        assert i.build_command_invocation("plan", "my feature") == "/speckit.plan my feature"
+
+    def test_base_extension_command(self):
+        i = StubIntegration()
+        assert i.build_command_invocation("speckit.git.commit") == "/speckit.git.commit"
+
+    def test_base_extension_command_bare(self):
+        i = StubIntegration()
+        assert i.build_command_invocation("git.commit") == "/speckit.git.commit"
+
+    def test_skills_core_command(self):
+        from specify_cli.integrations import get_integration
+        i = get_integration("codex")
+        assert i.build_command_invocation("speckit.plan") == "/speckit-plan"
+        assert i.build_command_invocation("plan") == "/speckit-plan"
+
+    def test_skills_extension_command(self):
+        from specify_cli.integrations import get_integration
+        i = get_integration("codex")
+        assert i.build_command_invocation("speckit.git.commit") == "/speckit-git-commit"
+        assert i.build_command_invocation("git.commit") == "/speckit-git-commit"
+
+    def test_skills_extension_command_with_args(self):
+        from specify_cli.integrations import get_integration
+        i = get_integration("codex")
+        assert i.build_command_invocation("speckit.git.commit", "fix typo") == "/speckit-git-commit fix typo"
+
+
+class TestResolveCommandRefs:
+    """Tests for __SPECKIT_COMMAND_<NAME>__ placeholder resolution."""
+
+    def test_dot_separator_core_command(self):
+        text = "Run `__SPECKIT_COMMAND_PLAN__` to plan."
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "Run `/speckit.plan` to plan."
+
+    def test_hyphen_separator_core_command(self):
+        text = "Run `__SPECKIT_COMMAND_PLAN__` to plan."
+        result = IntegrationBase.resolve_command_refs(text, "-")
+        assert result == "Run `/speckit-plan` to plan."
+
+    def test_multiple_placeholders(self):
+        text = "__SPECKIT_COMMAND_SPECIFY__ then __SPECKIT_COMMAND_PLAN__ then __SPECKIT_COMMAND_TASKS__"
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "/speckit.specify then /speckit.plan then /speckit.tasks"
+
+    def test_extension_command_dot(self):
+        text = "Run __SPECKIT_COMMAND_GIT_COMMIT__ to commit."
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "Run /speckit.git.commit to commit."
+
+    def test_extension_command_hyphen(self):
+        text = "Run __SPECKIT_COMMAND_GIT_COMMIT__ to commit."
+        result = IntegrationBase.resolve_command_refs(text, "-")
+        assert result == "Run /speckit-git-commit to commit."
+
+    def test_no_placeholders_unchanged(self):
+        text = "No placeholders here."
+        assert IntegrationBase.resolve_command_refs(text, ".") == text
+
+    def test_default_separator_is_dot(self):
+        text = "__SPECKIT_COMMAND_PLAN__"
+        assert IntegrationBase.resolve_command_refs(text) == "/speckit.plan"
+
+    def test_invoke_separator_class_attribute(self):
+        assert IntegrationBase.invoke_separator == "."
+        assert SkillsIntegration.invoke_separator == "-"
+
+    def test_effective_invoke_separator_default(self):
+        """Base classes return invoke_separator regardless of parsed_options."""
+        from .conftest import StubIntegration
+        stub = StubIntegration()
+        assert stub.effective_invoke_separator() == "."
+        assert stub.effective_invoke_separator({"skills": True}) == "."
+
+    def test_process_template_resolves_placeholders(self):
+        content = "---\ndescription: test\n---\nRun __SPECKIT_COMMAND_PLAN__ now."
+        result = IntegrationBase.process_template(
+            content, "test-agent", "sh", invoke_separator="."
+        )
+        assert "/speckit.plan" in result
+        assert "__SPECKIT_COMMAND_" not in result
+
+    def test_process_template_skills_separator(self):
+        content = "---\ndescription: test\n---\nRun __SPECKIT_COMMAND_PLAN__ now."
+        result = IntegrationBase.process_template(
+            content, "test-agent", "sh", invoke_separator="-"
+        )
+        assert "/speckit-plan" in result
+        assert "__SPECKIT_COMMAND_" not in result
+
+    def test_unclosed_placeholder_unchanged(self):
+        text = "Run __SPECKIT_COMMAND_PLAN to plan."
+        assert IntegrationBase.resolve_command_refs(text, ".") == text
+
+    def test_empty_name_not_matched(self):
+        text = "Run __SPECKIT_COMMAND___ to plan."
+        assert IntegrationBase.resolve_command_refs(text, ".") == text
+
+    def test_lowercase_placeholder_not_matched(self):
+        text = "Run __SPECKIT_COMMAND_plan__ to plan."
+        assert IntegrationBase.resolve_command_refs(text, ".") == text
+
+    def test_placeholder_adjacent_to_text(self):
+        text = "foo__SPECKIT_COMMAND_PLAN__bar"
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "foo/speckit.planbar"
+
+    def test_placeholder_with_digits(self):
+        text = "__SPECKIT_COMMAND_V2_PLAN__"
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "/speckit.v2.plan"
+
+
+class TestResolvePythonInterpreter:
+    def test_returns_python_on_path(self, monkeypatch):
+        # Positive: when python3 is on PATH it is preferred over python.
+        # Pin a POSIX platform so the Windows stub probe (tested separately
+        # below) does not reject the fake PATH entries on Windows CI.
+        def fake_which(name):
+            return f"/usr/bin/{name}" if name in ("python3", "python") else None
+
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "linux")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which", fake_which
+        )
+        assert IntegrationBase.resolve_python_interpreter() == "python3"
+
+    def test_falls_back_to_python_when_no_python3(self, monkeypatch):
+        def fake_which(name):
+            return "/usr/bin/python" if name == "python" else None
+
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "linux")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which", fake_which
+        )
+        assert IntegrationBase.resolve_python_interpreter() == "python"
+
+    def test_falls_back_to_sys_executable_when_nothing_found(self, monkeypatch):
+        # Negative: nothing on PATH and no venv -> the running interpreter
+        # (sys.executable) is used so the command works in this environment.
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which", lambda name: None
+        )
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.sys.executable", "/opt/py/bin/python"
+        )
+        assert IntegrationBase.resolve_python_interpreter() == "/opt/py/bin/python"
+
+    def test_falls_back_to_python3_when_no_interpreter_at_all(self, monkeypatch):
+        # Negative edge: neither PATH nor sys.executable resolves.
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which", lambda name: None
+        )
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.sys.executable", ""
+        )
+        assert IntegrationBase.resolve_python_interpreter() == "python3"
+
+    def test_prefers_project_venv_posix(self, monkeypatch, tmp_path):
+        venv_python = tmp_path / ".venv" / "bin" / "python"
+        venv_python.parent.mkdir(parents=True)
+        venv_python.write_text("")
+        # Even if python3 is on PATH, the project venv wins. The returned
+        # path is relative to the project root for portability.
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: "/usr/bin/python3",
+        )
+        result = IntegrationBase.resolve_python_interpreter(tmp_path)
+        assert result == ".venv/bin/python"
+
+    def test_prefers_project_venv_windows(self, monkeypatch, tmp_path):
+        venv_python = tmp_path / ".venv" / "Scripts" / "python.exe"
+        venv_python.parent.mkdir(parents=True)
+        venv_python.write_text("")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which", lambda name: None
+        )
+        result = IntegrationBase.resolve_python_interpreter(tmp_path)
+        assert result == ".venv/Scripts/python.exe"
+
+    def test_ignores_missing_venv(self, monkeypatch, tmp_path):
+        # Negative: no venv directory -> PATH resolution is used instead.
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "linux")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: "/usr/bin/python3" if name == "python3" else None,
+        )
+        assert IntegrationBase.resolve_python_interpreter(tmp_path) == "python3"
+
+    def test_windows_skips_store_alias_stub(self, monkeypatch):
+        # On Windows, python3 on PATH may be the Microsoft Store App
+        # Execution Alias stub: it exists but only prints an installer
+        # hint and exits non-zero. Existence is not enough; the
+        # interpreter must actually run (mirrors #3304 for the CLI).
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "win32")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: f"C:\\WindowsApps\\{name}.exe"
+            if name in ("python3", "python")
+            else None,
+        )
+        monkeypatch.setattr(
+            IntegrationBase, "_interpreter_runs", staticmethod(lambda path: False)
+        )
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.sys.executable", "C:\\Python\\python.exe"
+        )
+        result = IntegrationBase.resolve_python_interpreter()
+        assert result == "C:\\Python\\python.exe"
+
+    def test_windows_keeps_working_interpreter(self, monkeypatch):
+        # Positive: a real python3 on Windows PATH passes the run check.
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "win32")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: f"C:\\Python\\{name}.exe" if name == "python3" else None,
+        )
+        monkeypatch.setattr(
+            IntegrationBase, "_interpreter_runs", staticmethod(lambda path: True)
+        )
+        assert IntegrationBase.resolve_python_interpreter() == "python3"
+
+    def test_windows_stub_python3_falls_through_to_working_python(self, monkeypatch):
+        # python3 is the stub but python is a real install: pick python.
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "win32")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: f"C:\\somewhere\\{name}.exe"
+            if name in ("python3", "python")
+            else None,
+        )
+        monkeypatch.setattr(
+            IntegrationBase,
+            "_interpreter_runs",
+            staticmethod(lambda path: path.endswith("python.exe")),
+        )
+        assert IntegrationBase.resolve_python_interpreter() == "python"
+
+    def test_posix_does_not_spawn_run_check(self, monkeypatch):
+        # Non-Windows platforms have no App Execution Alias; existence
+        # on PATH stays sufficient and no subprocess is spawned.
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "linux")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: "/usr/bin/python3" if name == "python3" else None,
+        )
+
+        def boom(path):
+            raise AssertionError("run check must not execute on POSIX")
+
+        monkeypatch.setattr(
+            IntegrationBase, "_interpreter_runs", staticmethod(boom)
+        )
+        assert IntegrationBase.resolve_python_interpreter() == "python3"
+
+
+class TestProcessTemplatePyScriptType:
+    CONTENT = (
+        "---\n"
+        "scripts:\n"
+        "  sh: scripts/bash/check-prerequisites.sh --json\n"
+        "  ps: scripts/powershell/check-prerequisites.ps1 -Json\n"
+        "  py: scripts/python/check-prerequisites.py --json\n"
+        "---\n"
+        "Run {SCRIPT} now."
+    )
+
+    def test_py_prefixes_interpreter(self, monkeypatch):
+        # Positive: py script type prefixes a resolved interpreter and the
+        # script path is rewritten to the .specify location.
+        monkeypatch.setattr("specify_cli.integrations.base.sys.platform", "linux")
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: "/usr/bin/python3" if name == "python3" else None,
+        )
+        result = IntegrationBase.process_template(self.CONTENT, "agent", "py")
+        assert "python3 .specify/scripts/python/check-prerequisites.py --json" in result
+        # The scripts: frontmatter block is stripped.
+        assert "scripts:" not in result
+
+    def test_sh_does_not_prefix_interpreter(self):
+        # Negative: non-py script types are never prefixed with an interpreter.
+        result = IntegrationBase.process_template(self.CONTENT, "agent", "sh")
+        assert ".specify/scripts/bash/check-prerequisites.sh --json" in result
+        assert "python" not in result
+
+    def test_py_quotes_interpreter_with_spaces(self, monkeypatch):
+        # An interpreter path containing whitespace (e.g. Windows
+        # ``Program Files``) must be quoted so it isn't split into args.
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which", lambda name: None
+        )
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.sys.executable",
+            r"C:\Program Files\Python\python.exe",
+        )
+        result = IntegrationBase.process_template(self.CONTENT, "agent", "py")
+        assert (
+            '"C:\\Program Files\\Python\\python.exe" '
+            ".specify/scripts/python/check-prerequisites.py --json"
+        ) in result
+
+    def test_py_does_not_quote_interpreter_without_spaces(self, monkeypatch):
+        # Negative: a whitespace-free interpreter is left unquoted.
+        monkeypatch.setattr(
+            "specify_cli.integrations.base.shutil.which",
+            lambda name: "/usr/bin/python3" if name == "python3" else None,
+        )
+        result = IntegrationBase.process_template(self.CONTENT, "agent", "py")
+        assert '"' not in result.split("check-prerequisites.py")[0]
+
+    def test_py_uses_project_venv(self, monkeypatch, tmp_path):
+        venv_python = tmp_path / ".venv" / "bin" / "python"
+        venv_python.parent.mkdir(parents=True)
+        venv_python.write_text("")
+        result = IntegrationBase.process_template(
+            self.CONTENT, "agent", "py", project_root=tmp_path
+        )
+        assert ".venv/bin/python .specify/scripts/python/check-prerequisites.py" in result
+
+
+class TestInstallScriptsPython:
+    def _make_integration_with_scripts(self, monkeypatch, tmp_path):
+        scripts_src = tmp_path / "bundled_scripts"
+        scripts_src.mkdir()
+        (scripts_src / "common.py").write_text("print('hi')\n")
+        (scripts_src / "common.sh").write_text("echo hi\n")
+        (scripts_src / "notes.txt").write_text("not executable\n")
+        integration = StubIntegration()
+        monkeypatch.setattr(
+            integration, "integration_scripts_dir", lambda: scripts_src
+        )
+        return integration
+
+    def test_copies_all_script_files(self, monkeypatch, tmp_path):
+        # Cross-platform: every bundled file is copied into the project.
+        integration = self._make_integration_with_scripts(monkeypatch, tmp_path)
+        project_root = tmp_path / "proj"
+        project_root.mkdir()
+        manifest = IntegrationManifest("stub", project_root.resolve())
+
+        created = integration.install_scripts(project_root, manifest)
+        names = {p.name for p in created}
+        assert {"common.py", "common.sh", "notes.txt"} == names
+
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="chmod exec bit not reliable on Windows"
+    )
+    def test_marks_py_and_sh_executable(self, monkeypatch, tmp_path):
+        integration = self._make_integration_with_scripts(monkeypatch, tmp_path)
+        project_root = tmp_path / "proj"
+        project_root.mkdir()
+        manifest = IntegrationManifest("stub", project_root.resolve())
+
+        integration.install_scripts(project_root, manifest)
+
+        dest = project_root / ".specify" / "integrations" / "stub" / "scripts"
+        py_file = dest / "common.py"
+        sh_file = dest / "common.sh"
+        txt_file = dest / "notes.txt"
+        # Positive: .py and .sh are executable.
+        assert py_file.stat().st_mode & 0o111
+        assert sh_file.stat().st_mode & 0o111
+        # Negative: a non-script file is not made executable.
+        assert not (txt_file.stat().st_mode & 0o111)

tests/integrations/test_extra_args.py

@@ -0,0 +1,633 @@
+"""Tests for the per-integration `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` and
+`SPECKIT_INTEGRATION_<KEY>_EXECUTABLE` env-var hooks.
+
+The hooks are implemented in `IntegrationBase._apply_extra_args_env_var` and
+`IntegrationBase._resolve_executable` and wired into every concrete
+`build_exec_args` — `MarkdownIntegration`, `TomlIntegration`,
+`SkillsIntegration`, plus override integrations.
+These tests cover both the shared mechanisms (via `SkillsIntegration` stubs
+near the top of the file) and override integrations end-to-end (further down).
+See issues #2595 and #2596."""
+
+import os
+
+import pytest
+
+from specify_cli.integrations.base import (
+    MarkdownIntegration,
+    SkillsIntegration,
+    TomlIntegration,
+)
+
+
+class _ClaudeStub(SkillsIntegration):
+    """Minimal Claude-like SkillsIntegration for testing."""
+
+    key = "claude"
+    config = {
+        "name": "Claude (test stub)",
+        "folder": ".claude/",
+        "commands_subdir": "skills",
+        "install_url": None,
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".claude/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+
+
+class _KiroCliStub(SkillsIntegration):
+    """SkillsIntegration with a hyphenated key to exercise key
+    normalization (`kiro-cli` → `KIRO_CLI`)."""
+
+    key = "kiro-cli"
+    config = {
+        "name": "Kiro CLI (test stub)",
+        "folder": ".kiro/",
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".kiro/commands",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".md",
+    }
+
+
+class _NoCliStub(SkillsIntegration):
+    """SkillsIntegration with requires_cli=False — build_exec_args
+    must return None and the env-var hook must not fire."""
+
+    key = "no-cli"
+    config = {
+        "name": "No-CLI agent (test stub)",
+        "folder": ".no-cli/",
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".no-cli/commands",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".md",
+    }
+
+
+class _MarkdownAgentStub(MarkdownIntegration):
+    """Bare MarkdownIntegration subclass — does NOT override
+    `build_exec_args`. Locks the base implementation in
+    `MarkdownIntegration.build_exec_args` for the common case
+    (most concrete integrations: Amp, Auggie, Generic, …)."""
+
+    key = "md-agent"
+    config = {
+        "name": "Markdown agent (test stub)",
+        "folder": ".md-agent/",
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".md-agent/commands",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".md",
+    }
+
+
+class _TomlAgentStub(TomlIntegration):
+    """Bare TomlIntegration subclass — does NOT override
+    `build_exec_args`. Locks the base implementation in
+    `TomlIntegration.build_exec_args` (Gemini, Tabnine)."""
+
+    key = "toml-agent"
+    config = {
+        "name": "TOML agent (test stub)",
+        "folder": ".toml-agent/",
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".toml-agent/commands",
+        "format": "toml",
+        "args": "$ARGUMENTS",
+        "extension": ".toml",
+    }
+
+
+@pytest.fixture(autouse=True)
+def _clean_extra_args_env(monkeypatch):
+    """Strip any leaked SPECKIT_INTEGRATION_*_EXTRA_ARGS and
+    SPECKIT_INTEGRATION_*_EXECUTABLE vars from the test env so a
+    developer's shell setting doesn't pollute results."""
+    for key in list(os.environ):
+        if key.startswith("SPECKIT_INTEGRATION_") and (
+            key.endswith("_EXTRA_ARGS") or key.endswith("_EXECUTABLE")
+        ):
+            monkeypatch.delenv(key, raising=False)
+
+
+def test_env_var_unset_byte_identical_argv():
+    """Default behaviour: env var unset → no extra args inserted.
+
+    Locks the backward-compatibility guarantee that existing
+    operators see no change.
+    """
+    args = _ClaudeStub().build_exec_args("hello prompt")
+    assert args == ["claude", "-p", "hello prompt", "--output-format", "json"]
+
+
+def test_env_var_set_flag_inserted_before_model_and_output_format(
+    monkeypatch,
+):
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "--dangerously-skip-permissions"
+    )
+    args = _ClaudeStub().build_exec_args("hello prompt", model="sonnet")
+    assert args == [
+        "claude",
+        "-p",
+        "hello prompt",
+        "--dangerously-skip-permissions",
+        "--model",
+        "sonnet",
+        "--output-format",
+        "json",
+    ]
+
+
+def test_env_var_multi_token_parsed_via_shlex(monkeypatch):
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS",
+        "--dangerously-skip-permissions --max-turns 3",
+    )
+    args = _ClaudeStub().build_exec_args("p")
+    assert args == [
+        "claude",
+        "-p",
+        "p",
+        "--dangerously-skip-permissions",
+        "--max-turns",
+        "3",
+        "--output-format",
+        "json",
+    ]
+
+
+def test_malformed_quoting_raises_actionable_value_error(monkeypatch):
+    """An unmatched quote in the env-var value must surface a clear
+    error naming the offending env var and showing the invalid value,
+    rather than crashing workflow dispatch with a bare shlex traceback."""
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS",
+        '--flag "unterminated',
+    )
+    with pytest.raises(ValueError) as excinfo:
+        _ClaudeStub().build_exec_args("p")
+    msg = str(excinfo.value)
+    assert "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS" in msg
+    assert "--flag \"unterminated" in msg
+
+
+def test_env_var_empty_or_whitespace_is_noop(monkeypatch):
+    """An env var set to '' or '   ' is treated as unset."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "   ")
+    args = _ClaudeStub().build_exec_args("p")
+    assert args == ["claude", "-p", "p", "--output-format", "json"]
+
+
+def test_other_integration_env_var_ignored(monkeypatch):
+    """`SPECKIT_INTEGRATION_GEMINI_EXTRA_ARGS` set must NOT leak into
+    Claude's argv (per-integration scoping)."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_GEMINI_EXTRA_ARGS", "--gemini-only-flag")
+    args = _ClaudeStub().build_exec_args("p")
+    assert args == ["claude", "-p", "p", "--output-format", "json"]
+
+
+def test_key_normalization_hyphen_to_underscore_uppercase(monkeypatch):
+    """`kiro-cli` key looks up `SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS`
+    (hyphens replaced with underscores, then uppercased)."""
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS", "--some-kiro-flag"
+    )
+    args = _KiroCliStub().build_exec_args("p")
+    assert args == [
+        "kiro-cli",
+        "-p",
+        "p",
+        "--some-kiro-flag",
+        "--output-format",
+        "json",
+    ]
+
+
+def test_requires_cli_false_returns_none(monkeypatch):
+    """`requires_cli: False` short-circuits to None — the env-var
+    hook is never reached and no argv is built."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_NO_CLI_EXTRA_ARGS", "--should-not-appear")
+    assert _NoCliStub().build_exec_args("p") is None
+
+
+# ---------------------------------------------------------------------------
+# Base-class coverage
+#
+# Most integrations inherit `build_exec_args` from `MarkdownIntegration`
+# or `TomlIntegration` without overriding it. The tests above use
+# `SkillsIntegration` stubs (which share the same hook mechanism) — these
+# tests exercise the two other base implementations directly so all three
+# concrete bases are covered.
+# ---------------------------------------------------------------------------
+
+
+def test_markdown_integration_base_honours_extra_args(monkeypatch):
+    """A bare `MarkdownIntegration` subclass — which does not override
+    `build_exec_args` — must honour the env var via the base
+    implementation. Covers the most common integration pattern."""
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_MD_AGENT_EXTRA_ARGS", "--debug --max-tokens 100"
+    )
+    args = _MarkdownAgentStub().build_exec_args("p")
+    assert args == [
+        "md-agent",
+        "-p",
+        "p",
+        "--debug",
+        "--max-tokens",
+        "100",
+        "--output-format",
+        "json",
+    ]
+
+
+def test_toml_integration_base_honours_extra_args(monkeypatch):
+    """A bare `TomlIntegration` subclass — which does not override
+    `build_exec_args` — must honour the env var via the base
+    implementation. Covers Gemini/Tabnine-style integrations."""
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_TOML_AGENT_EXTRA_ARGS", "--yolo"
+    )
+    args = _TomlAgentStub().build_exec_args("p", model="gemini-pro")
+    # TomlIntegration uses `-m` for model (vs Markdown's `--model`).
+    assert args == [
+        "toml-agent",
+        "-p",
+        "p",
+        "--yolo",
+        "-m",
+        "gemini-pro",
+        "--output-format",
+        "json",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Override-integration coverage
+#
+# CodexIntegration, DevinIntegration, OpencodeIntegration and
+# CopilotIntegration each override `build_exec_args` rather than using the
+# base implementations. The env-var hook must be wired into every override
+# so the documented behaviour ("works for every requires_cli integration")
+# is honoured. These tests lock that contract per integration.
+# ---------------------------------------------------------------------------
+
+
+def test_codex_integration_honours_extra_args(monkeypatch):
+    from specify_cli.integrations.codex import CodexIntegration
+
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
+    args = CodexIntegration().build_exec_args("p", model="gpt-5")
+    assert args == [
+        "codex",
+        "exec",
+        "p",
+        "--sandbox",
+        "read-only",
+        "--model",
+        "gpt-5",
+        "--json",
+    ]
+
+
+def test_devin_integration_honours_extra_args(monkeypatch):
+    from specify_cli.integrations.devin import DevinIntegration
+
+    monkeypatch.setenv("SPECKIT_INTEGRATION_DEVIN_EXTRA_ARGS", "--no-confirm")
+    args = DevinIntegration().build_exec_args("p")
+    assert args == ["devin", "-p", "p", "--no-confirm"]
+
+
+def test_opencode_integration_honours_extra_args(monkeypatch):
+    from specify_cli.integrations.opencode import OpencodeIntegration
+
+    monkeypatch.setenv("SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS", "--quiet")
+    args = OpencodeIntegration().build_exec_args("p")
+    assert args == [
+        "opencode",
+        "run",
+        "--quiet",
+        "--format",
+        "json",
+        "p",
+    ]
+
+
+def test_opencode_extra_args_cannot_clobber_prompt_derived_command(
+    monkeypatch,
+):
+    """Operator-injected extra args must appear BEFORE the prompt-derived
+    ``--command <X>`` so that Spec Kit's command selection wins under
+    repeated-flag CLI semantics (last value typically takes precedence).
+
+    Locks against the regression where an operator setting
+    ``SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS="--command malicious"`` could redirect
+    a slash-prefixed prompt to a different command.
+    """
+    from specify_cli.integrations.opencode import OpencodeIntegration
+
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS", "--command operator-override"
+    )
+    args = OpencodeIntegration().build_exec_args("/speckit body text")
+    # Prompt-derived "--command speckit" appears AFTER the
+    # operator-injected one, so a CLI that resolves repeated flags
+    # last-wins will honour Spec Kit's choice.
+    assert args == [
+        "opencode",
+        "run",
+        "--command",
+        "operator-override",
+        "--command",
+        "speckit",
+        "--format",
+        "json",
+        "body text",
+    ]
+
+
+def test_copilot_integration_honours_extra_args(monkeypatch):
+    from specify_cli.integrations.copilot import (
+        CopilotIntegration,
+        _copilot_executable,
+    )
+
+    # Disable --yolo so the argv shape stays deterministic.
+    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
+    )
+    args = CopilotIntegration().build_exec_args("p")
+    # `_copilot_executable()` returns "copilot.cmd" on Windows and
+    # "copilot" elsewhere; the test must mirror that to stay portable.
+    assert args == [
+        _copilot_executable(),
+        "-p",
+        "p",
+        "--allow-tool",
+        "shell(echo)",
+        "--output-format",
+        "json",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# `dispatch_command` end-to-end coverage
+#
+# Workflow execution calls `impl.dispatch_command(...)`, not
+# `build_exec_args` directly. `IntegrationBase.dispatch_command` delegates
+# to `build_exec_args` (so the override fixes above flow through), but
+# `CopilotIntegration` overrides `dispatch_command` and constructs
+# `cli_args` inline — the hook must be invoked there too or the env var
+# is silently ignored at workflow runtime. These tests monkeypatch
+# `subprocess.run` and assert the env-var args reach the executed argv.
+# ---------------------------------------------------------------------------
+
+
+class _RunCapture:
+    """Test double that captures argv passed to subprocess.run."""
+
+    def __init__(self):
+        self.captured_args: list[str] | None = None
+
+    def __call__(self, args, **kwargs):
+        self.captured_args = list(args)
+
+        class _Result:
+            returncode = 0
+            stdout = ""
+            stderr = ""
+
+        return _Result()
+
+
+def test_copilot_dispatch_command_includes_extra_args(monkeypatch):
+    """Locks the bypass fix: `CopilotIntegration.dispatch_command`
+    must honour `SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS`, not just `build_exec_args`.
+    """
+    import subprocess
+
+    from specify_cli.integrations.copilot import CopilotIntegration
+
+    capture = _RunCapture()
+    monkeypatch.setattr(subprocess, "run", capture)
+    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
+    )
+
+    CopilotIntegration().dispatch_command(
+        "speckit.plan", args="body", stream=False
+    )
+
+    assert capture.captured_args is not None
+    # Hook inserted between `-p prompt` and the canonical Copilot flags.
+    p_idx = capture.captured_args.index("-p")
+    agent_idx = capture.captured_args.index("--agent")
+    extra_idx = capture.captured_args.index("--allow-tool")
+    assert p_idx < extra_idx < agent_idx
+    assert "shell(echo)" in capture.captured_args
+
+
+def test_codex_dispatch_command_includes_extra_args(monkeypatch):
+    """Lock the inherited `IntegrationBase.dispatch_command` path:
+    Codex (and by transitivity Devin, Opencode) flow through
+    `build_exec_args`, so the env var must reach argv at workflow
+    runtime.
+    """
+    import subprocess
+
+    from specify_cli.integrations.codex import CodexIntegration
+
+    capture = _RunCapture()
+    monkeypatch.setattr(subprocess, "run", capture)
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
+
+    CodexIntegration().dispatch_command(
+        "speckit.plan", args="body", stream=False
+    )
+
+    assert capture.captured_args is not None
+    assert "--sandbox" in capture.captured_args
+    assert "read-only" in capture.captured_args
+
+
+# ---------------------------------------------------------------------------
+# SPECKIT_INTEGRATION_<KEY>_EXECUTABLE tests
+#
+# The `_resolve_executable()` method on `IntegrationBase` checks
+# `SPECKIT_INTEGRATION_<KEY>_EXECUTABLE` and, when set, substitutes that
+# value for `self.key` as the first token in argv.  The tests below lock
+# the behaviour across shared and override integration paths:
+#   - the shared SkillsIntegration/MarkdownIntegration/TomlIntegration bases,
+#   - representative override integrations,
+#   - the hyphen→underscore key normalisation, and
+#   - whitespace/unset no-op guarantee.
+# ---------------------------------------------------------------------------
+
+
+def test_executable_env_var_unset_uses_key():
+    """Default: no override → executable is the integration key."""
+    args = _ClaudeStub().build_exec_args("p")
+    assert args[0] == "claude"
+
+
+def test_executable_env_var_replaces_first_argv_token(monkeypatch):
+    """Setting the env var substitutes the executable name in argv."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude/bin/claude")
+    args = _ClaudeStub().build_exec_args("hello")
+    assert args[0] == "/opt/claude/bin/claude"
+    assert args[1:] == ["-p", "hello", "--output-format", "json"]
+
+
+def test_executable_env_var_whitespace_only_falls_back_to_key(monkeypatch):
+    """Whitespace-only value is treated as unset → falls back to self.key."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "   ")
+    args = _ClaudeStub().build_exec_args("p")
+    assert args[0] == "claude"
+
+
+def test_executable_env_var_key_normalization_hyphen_to_underscore(monkeypatch):
+    """`kiro-cli` key maps to `SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE`."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE", "/usr/local/bin/kiro-cli")
+    args = _KiroCliStub().build_exec_args("p")
+    assert args[0] == "/usr/local/bin/kiro-cli"
+
+
+def test_executable_env_var_other_integration_ignored(monkeypatch):
+    """`SPECKIT_INTEGRATION_GEMINI_EXECUTABLE` must NOT affect Claude."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_GEMINI_EXECUTABLE", "/custom/gemini")
+    args = _ClaudeStub().build_exec_args("p")
+    assert args[0] == "claude"
+
+
+def test_executable_env_var_markdown_integration(monkeypatch):
+    """MarkdownIntegration base honours the executable env var."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_MD_AGENT_EXECUTABLE", "/custom/md-agent")
+    args = _MarkdownAgentStub().build_exec_args("p")
+    assert args[0] == "/custom/md-agent"
+
+
+def test_executable_env_var_toml_integration(monkeypatch):
+    """TomlIntegration base honours the executable env var."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_TOML_AGENT_EXECUTABLE", "/custom/toml-agent")
+    args = _TomlAgentStub().build_exec_args("p")
+    assert args[0] == "/custom/toml-agent"
+
+
+def test_executable_env_var_requires_cli_false_returns_none(monkeypatch):
+    """`requires_cli: False` still returns None even when executable is set."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_NO_CLI_EXECUTABLE", "/custom/no-cli")
+    assert _NoCliStub().build_exec_args("p") is None
+
+
+def test_executable_env_var_codex_integration(monkeypatch):
+    """CodexIntegration honours the executable env var."""
+    from specify_cli.integrations.codex import CodexIntegration
+
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXECUTABLE", "/opt/codex")
+    args = CodexIntegration().build_exec_args("p")
+    assert args[0] == "/opt/codex"
+    assert args[1] == "exec"
+
+
+def test_executable_env_var_devin_integration(monkeypatch):
+    """DevinIntegration honours the executable env var."""
+    from specify_cli.integrations.devin import DevinIntegration
+
+    monkeypatch.setenv("SPECKIT_INTEGRATION_DEVIN_EXECUTABLE", "/opt/devin")
+    args = DevinIntegration().build_exec_args("p")
+    assert args[0] == "/opt/devin"
+
+
+def test_executable_env_var_opencode_integration(monkeypatch):
+    """OpencodeIntegration honours the executable env var."""
+    from specify_cli.integrations.opencode import OpencodeIntegration
+
+    monkeypatch.setenv("SPECKIT_INTEGRATION_OPENCODE_EXECUTABLE", "/opt/opencode")
+    args = OpencodeIntegration().build_exec_args("p")
+    assert args[0] == "/opt/opencode"
+    assert args[1] == "run"
+
+
+def test_executable_env_var_copilot_integration(monkeypatch):
+    """CopilotIntegration honours the executable env var, overriding the
+    platform-specific default from `_copilot_executable()`."""
+    from specify_cli.integrations.copilot import CopilotIntegration
+
+    monkeypatch.setenv("SPECKIT_INTEGRATION_COPILOT_EXECUTABLE", "/opt/copilot")
+    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
+    args = CopilotIntegration().build_exec_args("p")
+    assert args[0] == "/opt/copilot"
+
+
+def test_executable_env_var_copilot_unset_uses_platform_default(monkeypatch):
+    """When `SPECKIT_INTEGRATION_COPILOT_EXECUTABLE` is unset, Copilot
+    falls back to the platform-specific default from `_copilot_executable()`."""
+    from specify_cli.integrations.copilot import CopilotIntegration, _copilot_executable
+
+    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
+    args = CopilotIntegration().build_exec_args("p")
+    assert args[0] == _copilot_executable()
+
+
+def test_executable_env_var_copilot_dispatch_command(monkeypatch):
+    """CopilotIntegration.dispatch_command honours the executable env var."""
+    import subprocess
+
+    from specify_cli.integrations.copilot import CopilotIntegration
+
+    capture = _RunCapture()
+    monkeypatch.setattr(subprocess, "run", capture)
+    monkeypatch.setenv("SPECKIT_INTEGRATION_COPILOT_EXECUTABLE", "/opt/copilot")
+    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
+
+    CopilotIntegration().dispatch_command("speckit.plan", args="body", stream=False)
+
+    assert capture.captured_args is not None
+    assert capture.captured_args[0] == "/opt/copilot"
+
+
+def test_executable_and_extra_args_both_honoured(monkeypatch):
+    """Both the executable override and extra args env vars can be set
+    simultaneously — they are independent hooks."""
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude")
+    monkeypatch.setenv(
+        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "--dangerously-skip-permissions"
+    )
+    args = _ClaudeStub().build_exec_args("hello", model="sonnet")
+    assert args == [
+        "/opt/claude",
+        "-p",
+        "hello",
+        "--dangerously-skip-permissions",
+        "--model",
+        "sonnet",
+        "--output-format",
+        "json",
+    ]

tests/integrations/test_home_isolation.py

@@ -0,0 +1,25 @@
+"""Regression tests for integration-test environment isolation."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def test_integration_tests_use_tmp_home(tmp_path: Path) -> None:
+    home = tmp_path / "home"
+
+    assert Path(os.environ["HOME"]) == home
+    assert Path(os.environ["USERPROFILE"]) == home
+    assert Path(os.environ["XDG_CACHE_HOME"]) == home / ".cache"
+    assert Path(os.environ["XDG_CONFIG_HOME"]) == home / ".config"
+    assert Path(os.environ["XDG_DATA_HOME"]) == home / ".local" / "share"
+
+    # Most integrations resolve the user home via Path.home() (e.g. Hermes,
+    # catalog), so the isolation has to reach that API, not just the env vars.
+    assert Path.home() == home
+
+    assert home.is_dir()
+    assert (home / ".cache").is_dir()
+    assert (home / ".config").is_dir()
+    assert (home / ".local" / "share").is_dir()

tests/integrations/test_integration_agy.py

@@ -0,0 +1,154 @@
+"""Tests for AgyIntegration (Antigravity)."""
+
+from specify_cli.integrations import get_integration
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestAgyIntegration(SkillsIntegrationTests):
+    KEY = "agy"
+    FOLDER = ".agents/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".agents/skills"
+
+    def test_options_include_skills_flag(self):
+        """Override inherited test: AgyIntegration should not expose a --skills flag because .agents/ is its only layout."""
+        i = get_integration(self.KEY)
+        skills_opts = [o for o in i.options() if o.name == "--skills"]
+        assert len(skills_opts) == 0
+
+    def test_requires_cli_is_true(self):
+        """agy is a CLI tool; requires_cli must be True."""
+        i = get_integration(self.KEY)
+        assert i.config["requires_cli"] is True
+
+    def test_install_url_is_set(self):
+        """install_url must point to the official installation page."""
+        i = get_integration(self.KEY)
+        assert i.config["install_url"] == "https://antigravity.google/"
+
+
+class TestAgyInitFlow:
+    """--integration agy creates expected files."""
+
+    def test_integration_agy_creates_skills(self, tmp_path):
+        """--integration agy should create skills directory."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        target = tmp_path / "test-proj"
+        result = runner.invoke(app, ["init", str(target), "--integration", "agy", "--script", "sh", "--ignore-agent-tools"])
+
+        assert result.exit_code == 0, f"init --integration agy failed: {result.output}"
+        assert (target / ".agents" / "skills" / "speckit-plan" / "SKILL.md").exists()
+
+    def test_agy_setup_warning(self, tmp_path):
+        """Agy integration should print a warning about v1.20.5 requirement during setup."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        # Click >= 8.2 separates stdout and stderr natively
+        runner = CliRunner()
+        target = tmp_path / "test-proj2"
+        result = runner.invoke(app, ["init", str(target), "--integration", "agy", "--script", "sh", "--ignore-agent-tools"])
+
+        assert result.exit_code == 0
+        assert "Warning: The .agents/ layout requires Antigravity v1.20.5 or newer" in result.stderr
+
+
+class TestAgyBuildExecArgs:
+    """agy non-interactive execution argument building."""
+
+    def test_build_exec_args_returns_print_command(self):
+        """build_exec_args should return ['agy', '--print', prompt]."""
+        from specify_cli.integrations import get_integration
+        i = get_integration("agy")
+        result = i.build_exec_args("describe my feature")
+        assert result == ["agy", "--print", "describe my feature"]
+
+    def test_build_exec_args_ignores_model(self):
+        """agy does not support --model; model param must be ignored."""
+        from specify_cli.integrations import get_integration
+        i = get_integration("agy")
+        result = i.build_exec_args("my prompt", model="gemini-pro")
+        assert result == ["agy", "--print", "my prompt"]
+
+    def test_build_exec_args_ignores_output_json(self):
+        """agy does not support JSON output; output_json param must be ignored."""
+        from specify_cli.integrations import get_integration
+        i = get_integration("agy")
+        result = i.build_exec_args("my prompt", output_json=False)
+        assert result == ["agy", "--print", "my prompt"]
+
+    def test_build_exec_args_honors_extra_args(self, monkeypatch):
+        """SPECKIT_INTEGRATION_AGY_EXTRA_ARGS must be appended after the prompt.
+
+        agy previously skipped _apply_extra_args_env_var entirely, so the
+        documented per-integration extra-args hook was silently ignored
+        (same class as the merged cursor-agent fix #3265).
+        """
+        from specify_cli.integrations import get_integration
+        monkeypatch.setenv("SPECKIT_INTEGRATION_AGY_EXTRA_ARGS", "--verbose")
+        i = get_integration("agy")
+        assert i.build_exec_args("my prompt") == [
+            "agy", "--print", "my prompt", "--verbose",
+        ]
+
+    def test_build_exec_args_honors_executable_override(self, monkeypatch):
+        from specify_cli.integrations import get_integration
+        monkeypatch.setenv("SPECKIT_INTEGRATION_AGY_EXECUTABLE", "/custom/agy")
+        i = get_integration("agy")
+        assert i.build_exec_args("my prompt")[0] == "/custom/agy"
+
+
+class TestAgyHookCommandNote:
+    """Verify dot-to-hyphen normalization note is injected into hook sections."""
+
+    def test_hook_note_injected_in_skills_with_hooks(self, tmp_path):
+        """Skills with hook sections should contain the normalization note."""
+        from specify_cli.integrations import get_integration
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        i = get_integration("agy")
+        m = IntegrationManifest("agy", tmp_path)
+        i.setup(tmp_path, m, script_type="sh")
+        specify_skill = tmp_path / ".agents/skills/speckit-specify/SKILL.md"
+        assert specify_skill.exists()
+        content = specify_skill.read_text(encoding="utf-8")
+        assert "replace dots" in content, (
+            "speckit-specify should have dot-to-hyphen hook note"
+        )
+
+    def test_hook_note_not_in_skills_without_hooks(self):
+        """Skills without hook sections should not get the note."""
+        from specify_cli.integrations.agy import AgyIntegration
+
+        content = "---\nname: test\ndescription: test\n---\n\nNo hooks here.\n"
+        result = AgyIntegration._inject_hook_command_note(content)
+        assert "replace dots" not in result
+
+    def test_hook_note_idempotent(self):
+        """Injecting the note twice must not duplicate it."""
+        from specify_cli.integrations.agy import AgyIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            "- For each executable hook, output the following based on its flag:\n"
+        )
+        once = AgyIntegration._inject_hook_command_note(content)
+        twice = AgyIntegration._inject_hook_command_note(once)
+        assert once == twice, "Hook note injection should be idempotent"
+
+    def test_hook_note_preserves_indentation(self):
+        """The injected note must match the indentation of the target line."""
+        from specify_cli.integrations.agy import AgyIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            "   - For each executable hook, output the following\n"
+        )
+        result = AgyIntegration._inject_hook_command_note(content)
+        lines = result.splitlines()
+        note_line = [ln for ln in lines if "replace dots" in ln][0]
+        assert note_line.startswith("   "), "Note should preserve indentation"

tests/integrations/test_integration_amp.py

@@ -0,0 +1,10 @@
+"""Tests for AmpIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestAmpIntegration(MarkdownIntegrationTests):
+    KEY = "amp"
+    FOLDER = ".agents/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".agents/commands"

tests/integrations/test_integration_auggie.py

@@ -0,0 +1,10 @@
+"""Tests for AuggieIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestAuggieIntegration(MarkdownIntegrationTests):
+    KEY = "auggie"
+    FOLDER = ".augment/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".augment/commands"

tests/integrations/test_integration_base_markdown.py

@@ -0,0 +1,313 @@
+"""Reusable test mixin for standard MarkdownIntegration subclasses.
+
+Each per-agent test file sets ``KEY``, ``FOLDER``, ``COMMANDS_SUBDIR``,
+and ``REGISTRAR_DIR``, then inherits all verification logic from
+``MarkdownIntegrationTests``.
+"""
+
+import os
+
+from specify_cli.integrations import INTEGRATION_REGISTRY, get_integration
+from specify_cli.integrations.base import MarkdownIntegration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class MarkdownIntegrationTests:
+    """Mixin — set class-level constants and inherit these tests.
+
+    Required class attrs on subclass::
+
+        KEY: str              — integration registry key
+        FOLDER: str           — e.g. ".claude/"
+        COMMANDS_SUBDIR: str  — e.g. "commands"
+        REGISTRAR_DIR: str    — e.g. ".claude/commands"
+    """
+
+    KEY: str
+    FOLDER: str
+    COMMANDS_SUBDIR: str
+    REGISTRAR_DIR: str
+
+    # -- Registration -----------------------------------------------------
+
+    def test_registered(self):
+        assert self.KEY in INTEGRATION_REGISTRY
+        assert get_integration(self.KEY) is not None
+
+    def test_is_markdown_integration(self):
+        assert isinstance(get_integration(self.KEY), MarkdownIntegration)
+
+    # -- 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"] == ".md"
+
+    # -- 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
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        for f in cmd_files:
+            assert f.exists()
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".md")
+
+    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.commands_dest(tmp_path)
+        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_templates_are_processed(self, tmp_path):
+        """Command files must have placeholders replaced, not raw templates."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) > 0
+        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}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{f.name} has unprocessed __SPECKIT_COMMAND_*__"
+            assert "\nscripts:\n" not in content, f"{f.name} has unstripped scripts: block"
+
+    def test_plan_command_has_no_context_placeholder(self, tmp_path):
+        """The generated plan command must not carry a context-file placeholder.
+
+        Agent context files are owned entirely by the opt-in agent-context
+        extension, so the core plan command must not reference one.
+        """
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        plan_file = i.commands_dest(tmp_path) / i.command_filename("plan")
+        assert plan_file.exists(), f"Plan file {plan_file} not created"
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content, (
+            f"Plan command has unprocessed __CONTEXT_FILE__ placeholder in {plan_file.name}"
+        )
+
+    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
+
+    # -- Context file ownership (extension-owned, opt-in) -----------------
+
+    def test_setup_does_not_write_context_section(self, tmp_path):
+        """Setup must not create or manage any agent context file — that is
+        owned entirely by the opt-in agent-context extension."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text, (
+                    f"Setup wrote a managed context section into {path} for {self.KEY}"
+                )
+
+    def test_teardown_leaves_existing_context_file_intact(self, tmp_path):
+        """A user-authored context file must survive setup + teardown untouched."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        ctx_path = tmp_path / "AGENTS.md"
+        original = "# My Rules\n\nUser content.\n"
+        ctx_path.write_text(original, encoding="utf-8")
+        i.setup(tmp_path, m)
+        m.save()
+        i.teardown(tmp_path, m)
+        assert ctx_path.read_text(encoding="utf-8") == original
+
+    # -- CLI integration flag -------------------------------------------------
+
+    def test_integration_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", "--integration", self.KEY, "--script", "sh",
+                "--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)
+        cmd_dir = i.commands_dest(project)
+        assert cmd_dir.is_dir(), f"--integration {self.KEY} did not create commands directory"
+
+    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",
+                "--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)
+        cmd_dir = i.commands_dest(project)
+        assert cmd_dir.is_dir(), f"Commands directory {cmd_dir} not created"
+        commands = sorted(cmd_dir.glob("speckit.*"))
+        assert len(commands) > 0, f"No command files in {cmd_dir}"
+
+
+    # -- Complete file inventory ------------------------------------------
+
+    COMMAND_STEMS = [
+        "analyze", "clarify", "constitution", "converge", "implement",
+        "plan", "checklist", "specify", "tasks", "taskstoissues",
+    ]
+
+    def _expected_files(self, script_variant: str) -> list[str]:
+        """Build the expected file list for this integration + script variant."""
+        i = get_integration(self.KEY)
+        cmd_dir = i.registrar_config["dir"]
+        files = []
+
+        # Command files
+        for stem in self.COMMAND_STEMS:
+            files.append(f"{cmd_dir}/speckit.{stem}.md")
+
+        # Framework files
+        files.append(".specify/integration.json")
+        files.append(".specify/init-options.json")
+        files.append(f".specify/integrations/{self.KEY}.manifest.json")
+        files.append(".specify/integrations/speckit.manifest.json")
+
+        if script_variant == "sh":
+            for name in ["check-prerequisites.sh", "common.sh", "create-new-feature.sh",
+                         "setup-plan.sh", "setup-tasks.sh"]:
+                files.append(f".specify/scripts/bash/{name}")
+        else:
+            for name in ["check-prerequisites.ps1", "common.ps1", "create-new-feature.ps1",
+                         "setup-plan.ps1", "setup-tasks.ps1"]:
+                files.append(f".specify/scripts/powershell/{name}")
+
+        for name in ["checklist-template.md",
+                     "constitution-template.md", "plan-template.md",
+                     "spec-template.md", "tasks-template.md"]:
+            files.append(f".specify/templates/{name}")
+
+        files.append(".specify/memory/constitution.md")
+        # Bundled workflow
+        files.append(".specify/workflows/speckit/workflow.yml")
+        files.append(".specify/workflows/workflow-registry.json")
+
+
+
+        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",
+                "--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() and ".git" not in p.parts)
+        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",
+                "--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() and ".git" not in p.parts)
+        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_base_skills.py

@@ -0,0 +1,488 @@
+"""Reusable test mixin for standard SkillsIntegration subclasses.
+
+Each per-agent test file sets ``KEY``, ``FOLDER``, ``COMMANDS_SUBDIR``,
+and ``REGISTRAR_DIR``, 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"
+    """
+
+    KEY: str
+    FOLDER: str
+    COMMANDS_SUBDIR: str
+    REGISTRAR_DIR: 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"
+
+    # -- 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", "clarify", "constitution", "converge", "implement",
+            "plan", "checklist", "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}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{f.name} has unprocessed __SPECKIT_COMMAND_*__"
+
+    def test_command_refs_use_hyphen_separator(self, tmp_path):
+        """Skills agents must resolve command refs with hyphen separator."""
+        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")
+            # Skills agents must use /speckit-<name>, not /speckit.<name>
+            assert "/speckit." not in content, (
+                f"{f.name} contains dot-notation /speckit. reference; "
+                f"skills agents must use /speckit-<name>"
+            )
+
+    def test_hook_sections_explain_dotted_command_conversion(self, tmp_path):
+        """Generated skills with hook sections must explain dotted command conversion."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        specify_skill = i.skills_dest(tmp_path) / "speckit-specify" / "SKILL.md"
+        assert specify_skill.exists()
+        content = specify_skill.read_text(encoding="utf-8")
+        assert "replace dots" in content, (
+            "speckit-specify should explain dotted hook command conversion"
+        )
+        assert content.count("replace dots") == content.count(
+            "- For each executable hook, output the following"
+        )
+
+    def test_hook_note_injected_for_each_instruction_independently(self):
+        """Existing hook notes should not suppress later missing notes."""
+        content = (
+            "---\n"
+            "name: test\n"
+            "---\n\n"
+            "- When constructing slash commands from hook command names, "
+            "replace dots (`.`) with hyphens (`-`). "
+            "For example, `speckit.git.commit` → `/speckit-git-commit`.\n"
+            "- For each executable hook, output the following first block:\n"
+            "\n"
+            "- For each executable hook, output the following second block:\n"
+        )
+
+        result = SkillsIntegration._inject_hook_command_note(content)
+
+        assert result.count("replace dots (`.`) with hyphens") == 2
+
+    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_plan_skill_has_no_context_placeholder(self, tmp_path):
+        """The generated plan skill must not carry a context-file placeholder.
+
+        Agent context files are owned entirely by the opt-in agent-context
+        extension, so the core plan skill must not reference one.
+        """
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        plan_file = i.skills_dest(tmp_path) / "speckit-plan" / "SKILL.md"
+        assert plan_file.exists(), f"Plan skill {plan_file} not created"
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content, (
+            "Plan skill has unprocessed __CONTEXT_FILE__ placeholder"
+        )
+
+    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"
+
+    # -- Context file ownership (extension-owned, opt-in) -----------------
+
+    def test_setup_does_not_write_context_section(self, tmp_path):
+        """Setup must not create or manage any agent context file — that is
+        owned entirely by the opt-in agent-context extension."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text, (
+                    f"Setup wrote a managed context section into {path} for {self.KEY}"
+                )
+
+    def test_teardown_leaves_existing_context_file_intact(self, tmp_path):
+        """A user-authored context file must survive setup + teardown untouched."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        ctx_path = tmp_path / "AGENTS.md"
+        original = "# My Rules\n\nUser content.\n"
+        ctx_path.write_text(original, encoding="utf-8")
+        i.setup(tmp_path, m)
+        m.save()
+        i.teardown(tmp_path, m)
+        assert ctx_path.read_text(encoding="utf-8") == original
+
+    # -- CLI integration flag -------------------------------------------------
+
+    def test_integration_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", "--integration", self.KEY, "--script", "sh",
+                "--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"--integration {self.KEY} did not create skills directory"
+
+    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",
+                "--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"
+
+    def test_init_does_not_create_agent_context_config(self, tmp_path):
+        """agent-context is opt-in: init must not auto-install the extension
+        or write its config."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / f"opts-{self.KEY}"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", self.KEY, "--script", "sh",
+                "--ignore-agent-tools",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        assert not ext_cfg_path.exists()
+
+    # -- 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", "clarify", "constitution", "converge", "implement",
+        "plan", "checklist", "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 (core commands)
+        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",
+            ".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/setup-tasks.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/setup-tasks.ps1",
+            ]
+        # Templates
+        files += [
+            ".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",
+        ]
+        # Bundled workflow
+        files += [
+            ".specify/workflows/speckit/workflow.yml",
+            ".specify/workflows/workflow-registry.json",
+        ]
+        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",
+                "--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() and ".git" not in p.parts
+        )
+        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",
+                "--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() and ".git" not in p.parts
+        )
+        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_base_toml.py

@@ -0,0 +1,597 @@
+"""Reusable test mixin for standard TomlIntegration subclasses.
+
+Each per-agent test file sets ``KEY``, ``FOLDER``, ``COMMANDS_SUBDIR``,
+and ``REGISTRAR_DIR``, then inherits all verification logic from
+``TomlIntegrationTests``.
+
+Mirrors ``MarkdownIntegrationTests`` closely — same test structure,
+adapted for TOML output format.
+"""
+
+import os
+import tomllib
+
+import pytest
+
+from specify_cli.integrations import INTEGRATION_REGISTRY, get_integration
+from specify_cli.integrations.base import TomlIntegration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class TomlIntegrationTests:
+    """Mixin — set class-level constants and inherit these tests.
+
+    Required class attrs on subclass::
+
+        KEY: str              — integration registry key
+        FOLDER: str           — e.g. ".gemini/"
+        COMMANDS_SUBDIR: str  — e.g. "commands"
+        REGISTRAR_DIR: str    — e.g. ".gemini/commands"
+    """
+
+    KEY: str
+    FOLDER: str
+    COMMANDS_SUBDIR: str
+    REGISTRAR_DIR: str
+
+    # -- Registration -----------------------------------------------------
+
+    def test_registered(self):
+        assert self.KEY in INTEGRATION_REGISTRY
+        assert get_integration(self.KEY) is not None
+
+    def test_is_toml_integration(self):
+        assert isinstance(get_integration(self.KEY), TomlIntegration)
+
+    # -- 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"] == "toml"
+        assert i.registrar_config["args"] == "{{args}}"
+        assert i.registrar_config["extension"] == ".toml"
+
+    # -- 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
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        for f in cmd_files:
+            assert f.exists()
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".toml")
+
+    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.commands_dest(tmp_path)
+        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_templates_are_processed(self, tmp_path):
+        """Command files must have placeholders replaced and be valid TOML."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) > 0
+        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}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{f.name} has unprocessed __SPECKIT_COMMAND_*__"
+
+    def test_toml_has_description(self, tmp_path):
+        """Every TOML command file should have a description key."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        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 'description = "' in content, f"{f.name} missing description key"
+
+    def test_toml_has_prompt(self, tmp_path):
+        """Every TOML command file should have a prompt key."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        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 "prompt = " in content, f"{f.name} missing prompt key"
+
+    def test_toml_uses_correct_arg_placeholder(self, tmp_path):
+        """TOML commands must use {{args}} (from {ARGS} replacement)."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        # At least one file should contain {{args}} from the {ARGS} placeholder
+        has_args = any("{{args}}" in f.read_text(encoding="utf-8") for f in cmd_files)
+        assert has_args, "No TOML command file contains {{args}} placeholder"
+        has_dollar_args = any(
+            "$ARGUMENTS" in f.read_text(encoding="utf-8") for f in cmd_files
+        )
+        assert not has_dollar_args, (
+            "TOML command still contains $ARGUMENTS instead of {{args}}"
+        )
+
+    @pytest.mark.parametrize(
+        ("frontmatter", "expected"),
+        [
+            (
+                "---\ndescription: |\n  First line\n  Second line\n---\nBody\n",
+                "First line\nSecond line\n",
+            ),
+            (
+                "---\ndescription: >\n  First line\n  Second line\n---\nBody\n",
+                "First line Second line\n",
+            ),
+            (
+                "---\ndescription: |-\n  First line\n  Second line\n---\nBody\n",
+                "First line\nSecond line",
+            ),
+            (
+                "---\ndescription: >-\n  First line\n  Second line\n---\nBody\n",
+                "First line Second line",
+            ),
+        ],
+    )
+    def test_toml_extract_description_supports_block_scalars(
+        self, frontmatter, expected
+    ):
+        assert TomlIntegration._extract_description(frontmatter) == expected
+
+    def test_split_frontmatter_ignores_indented_delimiters(self):
+        content = "---\ndescription: |\n  line one\n  ---\n  line two\n---\nBody\n"
+
+        frontmatter, body = TomlIntegration._split_frontmatter(content)
+
+        assert "line two" in frontmatter
+        assert body == "Body\n"
+
+    def test_toml_prompt_excludes_frontmatter(self, tmp_path, monkeypatch):
+        i = get_integration(self.KEY)
+        template = tmp_path / "sample.md"
+        template.write_text(
+            "---\n"
+            "description: Summary line one\n"
+            "scripts:\n"
+            "  sh: scripts/bash/example.sh\n"
+            "---\n"
+            "Body line one\n"
+            "Body line two\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setattr(i, "list_command_templates", lambda: [template])
+
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) == 1
+
+        generated = cmd_files[0].read_text(encoding="utf-8")
+        parsed = tomllib.loads(generated)
+
+        assert parsed["description"] == "Summary line one"
+        assert parsed["prompt"] == "Body line one\nBody line two"
+        assert "description:" not in parsed["prompt"]
+        assert "scripts:" not in parsed["prompt"]
+        assert "---" not in parsed["prompt"]
+
+    def test_toml_no_ambiguous_closing_quotes(self, tmp_path, monkeypatch):
+        """Multiline body ending with a double quote must not produce an ambiguous TOML multiline-string closing delimiter (#2113)."""
+        i = get_integration(self.KEY)
+        template = tmp_path / "sample.md"
+        template.write_text(
+            "---\n"
+            "description: Test\n"
+            "scripts:\n"
+            "  sh: echo ok\n"
+            "---\n"
+            "Check the following:\n"
+            '- Correct: "Is X clearly specified?"\n',
+            encoding="utf-8",
+        )
+        monkeypatch.setattr(i, "list_command_templates", lambda: [template])
+
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) == 1
+
+        raw = cmd_files[0].read_text(encoding="utf-8")
+        assert '""""' not in raw, "closing delimiter must not merge with body quote"
+        assert '"""\n' in raw, "body must use multiline basic string"
+        parsed = tomllib.loads(raw)
+        assert parsed["prompt"].endswith('specified?"')
+        assert not parsed["prompt"].endswith("\n"), (
+            "parsed value must not gain a trailing newline"
+        )
+
+    def test_toml_triple_double_and_single_quote_ending(self, tmp_path, monkeypatch):
+        """Body containing `\"\"\"` and ending with `'` falls back to escaped basic string."""
+        i = get_integration(self.KEY)
+        template = tmp_path / "sample.md"
+        template.write_text(
+            "---\n"
+            "description: Test\n"
+            "scripts:\n"
+            "  sh: echo ok\n"
+            "---\n"
+            'Use """triple""" quotes\n'
+            "and end with 'single'\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setattr(i, "list_command_templates", lambda: [template])
+
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) == 1
+
+        raw = cmd_files[0].read_text(encoding="utf-8")
+        assert "''''" not in raw, (
+            "literal string must not produce ambiguous closing quotes"
+        )
+        parsed = tomllib.loads(raw)
+        assert parsed["prompt"].endswith("'single'")
+        assert '"""triple"""' in parsed["prompt"]
+        assert not parsed["prompt"].endswith("\n"), (
+            "parsed value must not gain a trailing newline"
+        )
+
+    def test_toml_closing_delimiter_inline_when_safe(self, tmp_path, monkeypatch):
+        """Body NOT ending with `"` keeps closing `\"\"\"` inline (no extra newline)."""
+        i = get_integration(self.KEY)
+        template = tmp_path / "sample.md"
+        template.write_text(
+            "---\n"
+            "description: Test\n"
+            "scripts:\n"
+            "  sh: echo ok\n"
+            "---\n"
+            "Line one\n"
+            "Plain body content\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setattr(i, "list_command_templates", lambda: [template])
+
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) == 1
+
+        raw = cmd_files[0].read_text(encoding="utf-8")
+        parsed = tomllib.loads(raw)
+        assert parsed["prompt"] == "Line one\nPlain body content"
+        assert raw.rstrip().endswith('content"""'), (
+            "closing delimiter should be inline when body does not end with a quote"
+        )
+
+    def test_toml_string_escapes_control_characters(self):
+        """A value with control chars / a bare CR must render as parseable TOML.
+
+        TOML forbids literal control characters (U+0000–U+001F except tab and
+        newline, plus U+007F) in every string form, and a bare CR that is not
+        part of a CRLF pair. The renderer used to emit these raw into a basic or
+        ``\"\"\"`` multiline string, producing a config file that fails to parse."""
+        value = "start\x00null\x01ctrl\x1besc\x7fdel\rlone-cr end"
+        rendered = TomlIntegration._render_toml_string(value)
+        parsed = tomllib.loads(f"prompt = {rendered}")
+        assert parsed["prompt"] == value
+
+    def test_toml_is_valid(self, tmp_path):
+        """Every generated TOML file must parse without errors."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        for f in cmd_files:
+            raw = f.read_bytes()
+            try:
+                parsed = tomllib.loads(raw.decode("utf-8"))
+            except Exception as exc:
+                raise AssertionError(f"{f.name} is not valid TOML: {exc}") from exc
+            assert "prompt" in parsed, f"{f.name} parsed TOML has no 'prompt' key"
+
+    def test_plan_command_has_no_context_placeholder(self, tmp_path):
+        """The generated plan command must not carry a context-file placeholder.
+
+        Agent context files are owned entirely by the opt-in agent-context
+        extension, so the core plan command must not reference one.
+        """
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        plan_file = i.commands_dest(tmp_path) / i.command_filename("plan")
+        assert plan_file.exists(), f"Plan file {plan_file} not created"
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content, (
+            f"Plan command has unprocessed __CONTEXT_FILE__ placeholder in {plan_file.name}"
+        )
+
+    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
+
+    # -- Context file ownership (extension-owned, opt-in) -----------------
+
+    def test_setup_does_not_write_context_section(self, tmp_path):
+        """Setup must not create or manage any agent context file — that is
+        owned entirely by the opt-in agent-context extension."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text, (
+                    f"Setup wrote a managed context section into {path} for {self.KEY}"
+                )
+
+    def test_teardown_leaves_existing_context_file_intact(self, tmp_path):
+        """A user-authored context file must survive setup + teardown untouched."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        ctx_path = tmp_path / "AGENTS.md"
+        original = "# My Rules\n\nUser content.\n"
+        ctx_path.write_text(original, encoding="utf-8")
+        i.setup(tmp_path, m)
+        m.save()
+        i.teardown(tmp_path, m)
+        assert ctx_path.read_text(encoding="utf-8") == original
+
+    # -- CLI integration flag -------------------------------------------------
+
+    def test_integration_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",
+                    "--integration",
+                    self.KEY,
+                    "--script",
+                    "sh",
+                    "--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)
+        cmd_dir = i.commands_dest(project)
+        assert cmd_dir.is_dir(), f"--integration {self.KEY} did not create commands directory"
+
+    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",
+                    "--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)
+        cmd_dir = i.commands_dest(project)
+        assert cmd_dir.is_dir(), f"Commands directory {cmd_dir} not created"
+        commands = sorted(cmd_dir.glob("speckit.*.toml"))
+        assert len(commands) > 0, f"No command files in {cmd_dir}"
+
+
+    # -- Complete file inventory ------------------------------------------
+
+    COMMAND_STEMS = [
+        "analyze",
+        "clarify",
+        "constitution",
+        "converge",
+        "implement",
+        "plan",
+        "checklist",
+        "specify",
+        "tasks",
+        "taskstoissues",
+    ]
+
+    def _expected_files(self, script_variant: str) -> list[str]:
+        """Build the expected file list for this integration + script variant."""
+        i = get_integration(self.KEY)
+        cmd_dir = i.registrar_config["dir"]
+        files = []
+
+        # Command files (.toml)
+        for stem in self.COMMAND_STEMS:
+            files.append(f"{cmd_dir}/speckit.{stem}.toml")
+
+        # Framework files
+        files.append(".specify/integration.json")
+        files.append(".specify/init-options.json")
+        files.append(f".specify/integrations/{self.KEY}.manifest.json")
+        files.append(".specify/integrations/speckit.manifest.json")
+
+        if script_variant == "sh":
+            for name in [
+                "check-prerequisites.sh",
+                "common.sh",
+                "create-new-feature.sh",
+                "setup-plan.sh",
+                "setup-tasks.sh",
+            ]:
+                files.append(f".specify/scripts/bash/{name}")
+        else:
+            for name in [
+                "check-prerequisites.ps1",
+                "common.ps1",
+                "create-new-feature.ps1",
+                "setup-plan.ps1",
+                "setup-tasks.ps1",
+            ]:
+                files.append(f".specify/scripts/powershell/{name}")
+
+        for name in [
+            "checklist-template.md",
+            "constitution-template.md",
+            "plan-template.md",
+            "spec-template.md",
+            "tasks-template.md",
+        ]:
+            files.append(f".specify/templates/{name}")
+
+        files.append(".specify/memory/constitution.md")
+        # Bundled workflow
+        files.append(".specify/workflows/speckit/workflow.yml")
+        files.append(".specify/workflows/workflow-registry.json")
+
+
+
+        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",
+                    "--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() and ".git" not in p.parts
+        )
+        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",
+                    "--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() and ".git" not in p.parts
+        )
+        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_base_yaml.py

@@ -0,0 +1,481 @@
+"""Reusable test mixin for standard YamlIntegration subclasses.
+
+Each per-agent test file sets ``KEY``, ``FOLDER``, ``COMMANDS_SUBDIR``,
+and ``REGISTRAR_DIR``, then inherits all verification logic from
+``YamlIntegrationTests``.
+
+Mirrors ``TomlIntegrationTests`` closely — same test structure,
+adapted for YAML recipe output format.
+"""
+
+import os
+
+import yaml
+
+from specify_cli.integrations import INTEGRATION_REGISTRY, get_integration
+from specify_cli.integrations.base import YamlIntegration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class YamlIntegrationTests:
+    """Mixin — set class-level constants and inherit these tests.
+
+    Required class attrs on subclass::
+
+        KEY: str              — integration registry key
+        FOLDER: str           — e.g. ".goose/"
+        COMMANDS_SUBDIR: str  — e.g. "recipes"
+        REGISTRAR_DIR: str    — e.g. ".goose/recipes"
+    """
+
+    KEY: str
+    FOLDER: str
+    COMMANDS_SUBDIR: str
+    REGISTRAR_DIR: str
+
+    # -- Registration -----------------------------------------------------
+
+    def test_registered(self):
+        assert self.KEY in INTEGRATION_REGISTRY
+        assert get_integration(self.KEY) is not None
+
+    def test_is_yaml_integration(self):
+        assert isinstance(get_integration(self.KEY), YamlIntegration)
+
+    # -- 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"] == "yaml"
+        assert i.registrar_config["args"] == "{{args}}"
+        assert i.registrar_config["extension"] == ".yaml"
+
+    # -- 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
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        for f in cmd_files:
+            assert f.exists()
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".yaml")
+
+    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.commands_dest(tmp_path)
+        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_templates_are_processed(self, tmp_path):
+        """Command files must have placeholders replaced."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) > 0
+        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}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{f.name} has unprocessed __SPECKIT_COMMAND_*__"
+
+    def test_yaml_has_title(self, tmp_path):
+        """Every YAML recipe should have a title field."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        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 "title:" in content, f"{f.name} missing title field"
+
+    def test_yaml_has_prompt(self, tmp_path):
+        """Every YAML recipe should have a prompt block scalar."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        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 "prompt: |" in content, f"{f.name} missing prompt block scalar"
+
+    def test_yaml_uses_correct_arg_placeholder(self, tmp_path):
+        """YAML recipes must use {{args}} placeholder."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        has_args = any("{{args}}" in f.read_text(encoding="utf-8") for f in cmd_files)
+        assert has_args, "No YAML recipe contains {{args}} placeholder"
+        has_dollar_args = any(
+            "$ARGUMENTS" in f.read_text(encoding="utf-8") for f in cmd_files
+        )
+        assert not has_dollar_args, (
+            "YAML recipe still contains $ARGUMENTS instead of {{args}}"
+        )
+
+    def test_yaml_is_valid(self, tmp_path):
+        """Every generated YAML file must parse without errors."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        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")
+            # Strip trailing source comment before parsing
+            lines = content.split("\n")
+            yaml_lines = [ln for ln in lines if not ln.startswith("# Source:")]
+            try:
+                parsed = yaml.safe_load("\n".join(yaml_lines))
+            except Exception as exc:
+                raise AssertionError(f"{f.name} is not valid YAML: {exc}") from exc
+            assert "prompt" in parsed, f"{f.name} parsed YAML has no 'prompt' key"
+            assert "title" in parsed, f"{f.name} parsed YAML has no 'title' key"
+
+    def test_yaml_prompt_excludes_frontmatter(self, tmp_path, monkeypatch):
+        i = get_integration(self.KEY)
+        template = tmp_path / "sample.md"
+        template.write_text(
+            "---\n"
+            "description: Summary line one\n"
+            "scripts:\n"
+            "  sh: scripts/bash/example.sh\n"
+            "---\n"
+            "Body line one\n"
+            "Body line two\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setattr(i, "list_command_templates", lambda: [template])
+
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        assert len(cmd_files) == 1
+
+        content = cmd_files[0].read_text(encoding="utf-8")
+        # Strip source comment for parsing
+        lines = content.split("\n")
+        yaml_lines = [ln for ln in lines if not ln.startswith("# Source:")]
+        parsed = yaml.safe_load("\n".join(yaml_lines))
+
+        assert "description:" not in parsed["prompt"]
+        assert "scripts:" not in parsed["prompt"]
+        assert "---" not in parsed["prompt"]
+
+    def test_yaml_prompt_with_indented_first_line_stays_valid(self):
+        """A body whose first line is indented must still parse.
+
+        A bare ``|`` block scalar infers its indentation from the first
+        non-empty line, so a body starting with an indented line (e.g. a
+        markdown code block or nested list item) made the parser expect that
+        deeper indent for the whole block and reject the later, shallower
+        lines. The explicit ``|2`` indicator pins the indent so it parses."""
+        body = "    indented first line\nback to normal\n    indented again"
+        rendered = YamlIntegration._render_yaml("Title", "Desc", body, "src")
+
+        yaml_lines = [
+            ln for ln in rendered.split("\n") if not ln.startswith("# Source:")
+        ]
+        parsed = yaml.safe_load("\n".join(yaml_lines))
+        assert parsed["prompt"].rstrip("\n") == body
+
+    def test_plan_command_has_no_context_placeholder(self, tmp_path):
+        """The generated plan command must not carry a context-file placeholder.
+
+        Agent context files are owned entirely by the opt-in agent-context
+        extension, so the core plan command must not reference one.
+        """
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        plan_file = i.commands_dest(tmp_path) / i.command_filename("plan")
+        assert plan_file.exists(), f"Plan file {plan_file} not created"
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content, (
+            f"Plan command has unprocessed __CONTEXT_FILE__ placeholder in {plan_file.name}"
+        )
+
+    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
+
+    # -- Context file ownership (extension-owned, opt-in) -----------------
+
+    def test_setup_does_not_write_context_section(self, tmp_path):
+        """Setup must not create or manage any agent context file — that is
+        owned entirely by the opt-in agent-context extension."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text, (
+                    f"Setup wrote a managed context section into {path} for {self.KEY}"
+                )
+
+    def test_teardown_leaves_existing_context_file_intact(self, tmp_path):
+        """A user-authored context file must survive setup + teardown untouched."""
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        ctx_path = tmp_path / "AGENTS.md"
+        original = "# My Rules\n\nUser content.\n"
+        ctx_path.write_text(original, encoding="utf-8")
+        i.setup(tmp_path, m)
+        m.save()
+        i.teardown(tmp_path, m)
+        assert ctx_path.read_text(encoding="utf-8") == original
+
+    # -- CLI integration flag -------------------------------------------------
+
+    def test_integration_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",
+                    "--integration",
+                    self.KEY,
+                    "--script",
+                    "sh",
+                    "--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)
+        cmd_dir = i.commands_dest(project)
+        assert cmd_dir.is_dir(), f"--integration {self.KEY} did not create commands directory"
+
+    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",
+                    "--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)
+        cmd_dir = i.commands_dest(project)
+        assert cmd_dir.is_dir(), f"Commands directory {cmd_dir} not created"
+        commands = sorted(cmd_dir.glob("speckit.*.yaml"))
+        assert len(commands) > 0, f"No command files in {cmd_dir}"
+
+
+    # -- Complete file inventory ------------------------------------------
+
+    COMMAND_STEMS = [
+        "analyze",
+        "clarify",
+        "constitution",
+        "converge",
+        "implement",
+        "plan",
+        "checklist",
+        "specify",
+        "tasks",
+        "taskstoissues",
+    ]
+
+    def _expected_files(self, script_variant: str) -> list[str]:
+        """Build the expected file list for this integration + script variant."""
+        i = get_integration(self.KEY)
+        cmd_dir = i.registrar_config["dir"]
+        files = []
+
+        # Command files (.yaml)
+        for stem in self.COMMAND_STEMS:
+            files.append(f"{cmd_dir}/speckit.{stem}.yaml")
+
+        # Framework files
+        files.append(".specify/integration.json")
+        files.append(".specify/init-options.json")
+        files.append(f".specify/integrations/{self.KEY}.manifest.json")
+        files.append(".specify/integrations/speckit.manifest.json")
+
+        if script_variant == "sh":
+            for name in [
+                "check-prerequisites.sh",
+                "common.sh",
+                "create-new-feature.sh",
+                "setup-plan.sh",
+                "setup-tasks.sh",
+            ]:
+                files.append(f".specify/scripts/bash/{name}")
+        else:
+            for name in [
+                "check-prerequisites.ps1",
+                "common.ps1",
+                "create-new-feature.ps1",
+                "setup-plan.ps1",
+                "setup-tasks.ps1",
+            ]:
+                files.append(f".specify/scripts/powershell/{name}")
+
+        for name in [
+            "checklist-template.md",
+            "constitution-template.md",
+            "plan-template.md",
+            "spec-template.md",
+            "tasks-template.md",
+        ]:
+            files.append(f".specify/templates/{name}")
+
+        files.append(".specify/memory/constitution.md")
+        # Bundled workflow
+        files.append(".specify/workflows/speckit/workflow.yml")
+        files.append(".specify/workflows/workflow-registry.json")
+
+
+
+        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",
+                    "--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() and ".git" not in p.parts
+        )
+        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",
+                    "--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() and ".git" not in p.parts
+        )
+        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_bob.py

@@ -0,0 +1,10 @@
+"""Tests for BobIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestBobIntegration(MarkdownIntegrationTests):
+    KEY = "bob"
+    FOLDER = ".bob/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".bob/commands"

tests/integrations/test_integration_claude.py

@@ -0,0 +1,869 @@
+"""Tests for ClaudeIntegration."""
+
+import json
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import yaml
+
+from specify_cli.integrations import INTEGRATION_REGISTRY, get_integration
+from specify_cli.integrations.base import IntegrationBase, SkillsIntegration
+from specify_cli.integrations.claude import ARGUMENT_HINTS, FORK_CONTEXT_COMMANDS
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class TestClaudeIntegration:
+    def test_registered(self):
+        assert "claude" in INTEGRATION_REGISTRY
+        assert get_integration("claude") is not None
+
+    def test_is_base_integration(self):
+        assert isinstance(get_integration("claude"), IntegrationBase)
+
+    def test_config_uses_skills(self):
+        integration = get_integration("claude")
+        assert integration.config["folder"] == ".claude/"
+        assert integration.config["commands_subdir"] == "skills"
+
+    def test_registrar_config_uses_skill_layout(self):
+        integration = get_integration("claude")
+        assert integration.registrar_config["dir"] == ".claude/skills"
+        assert integration.registrar_config["format"] == "markdown"
+        assert integration.registrar_config["args"] == "$ARGUMENTS"
+        assert integration.registrar_config["extension"] == "/SKILL.md"
+
+    def test_setup_creates_skill_files(self, tmp_path):
+        integration = get_integration("claude")
+        manifest = IntegrationManifest("claude", tmp_path)
+        created = integration.setup(tmp_path, manifest, script_type="sh")
+
+        skill_files = [path for path in created if path.name == "SKILL.md"]
+        assert skill_files
+
+        skills_dir = tmp_path / ".claude" / "skills"
+        assert skills_dir.is_dir()
+
+        plan_skill = skills_dir / "speckit-plan" / "SKILL.md"
+        assert plan_skill.exists()
+
+        content = plan_skill.read_text(encoding="utf-8")
+        assert "{SCRIPT}" not in content
+        assert "{ARGS}" not in content
+        assert "__AGENT__" not in content
+        assert "__SPECKIT_COMMAND_" not in content, "unprocessed __SPECKIT_COMMAND_*__"
+        assert "/speckit." not in content, "skills agent must use /speckit-<name> not /speckit.<name>"
+
+        parts = content.split("---", 2)
+        parsed = yaml.safe_load(parts[1])
+        assert parsed["name"] == "speckit-plan"
+        assert parsed["user-invocable"] is True
+        assert parsed["disable-model-invocation"] is False
+        assert parsed["metadata"]["source"] == "templates/commands/plan.md"
+
+    def test_render_skill_unicode(self):
+        """Test rendering a skill preserves non-ASCII characters."""
+        integration = get_integration("claude")
+        rendered = integration._render_skill(
+            "constitution",
+            {"description": "Prüfe Konformität der Implementierung"},
+            "Body",
+        )
+        assert "Prüfe Konformität" in rendered
+
+    def test_setup_does_not_write_context_section(self, tmp_path):
+        """The CLI no longer manages the agent context file — that is owned by
+        the opt-in agent-context extension. Setup must not create or touch it."""
+        integration = get_integration("claude")
+        manifest = IntegrationManifest("claude", tmp_path)
+        integration.setup(tmp_path, manifest, script_type="sh")
+
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text
+
+    def test_teardown_does_not_touch_existing_context_file(self, tmp_path):
+        """A user-authored context file is left intact on teardown."""
+        integration = get_integration("claude")
+        ctx_path = tmp_path / "CLAUDE.md"
+        original = "# CLAUDE.md\n\nUser content.\n"
+        ctx_path.write_text(original, encoding="utf-8")
+
+        manifest = IntegrationManifest("claude", tmp_path)
+        integration.setup(tmp_path, manifest, script_type="sh")
+        integration.teardown(tmp_path, manifest)
+
+        assert ctx_path.read_text(encoding="utf-8") == original
+
+    def test_integration_flag_creates_skill_files_cli(self, tmp_path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "claude-promote"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(
+                app,
+                [
+                    "init",
+                    "--here",
+                    "--integration",
+                    "claude",
+                    "--script",
+                    "sh",
+                    "--ignore-agent-tools",
+                ],
+                catch_exceptions=False,
+            )
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0, result.output
+        assert (project / ".claude" / "skills" / "speckit-plan" / "SKILL.md").exists()
+        assert not (project / ".claude" / "commands").exists()
+
+        init_options = json.loads(
+            (project / ".specify" / "init-options.json").read_text(encoding="utf-8")
+        )
+        assert init_options["ai"] == "claude"
+        assert init_options["ai_skills"] is True
+        assert init_options["integration"] == "claude"
+
+    def test_integration_flag_creates_skill_files(self, tmp_path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "claude-integration"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(
+                app,
+                [
+                    "init",
+                    "--here",
+                    "--integration",
+                    "claude",
+                    "--script",
+                    "sh",
+                    "--ignore-agent-tools",
+                ],
+                catch_exceptions=False,
+            )
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0, result.output
+        assert (project / ".claude" / "skills" / "speckit-specify" / "SKILL.md").exists()
+        assert (project / ".specify" / "integrations" / "claude.manifest.json").exists()
+
+    def test_interactive_claude_selection_uses_integration_path(self, tmp_path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "claude-interactive"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            with (
+                patch("specify_cli.commands.init._stdin_is_interactive", return_value=True),
+                patch("specify_cli.commands.init.select_with_arrows", return_value="claude"),
+            ):
+                result = runner.invoke(
+                    app,
+                    [
+                        "init",
+                        "--here",
+                        "--script",
+                        "sh",
+                        "--ignore-agent-tools",
+                    ],
+                    catch_exceptions=False,
+                )
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0, result.output
+        assert (project / ".specify" / "integration.json").exists()
+        assert (project / ".specify" / "integrations" / "claude.manifest.json").exists()
+
+        skill_file = project / ".claude" / "skills" / "speckit-plan" / "SKILL.md"
+        assert skill_file.exists()
+        skill_content = skill_file.read_text(encoding="utf-8")
+        assert "user-invocable: true" in skill_content
+        assert "disable-model-invocation: false" in skill_content
+
+        init_options = json.loads(
+            (project / ".specify" / "init-options.json").read_text(encoding="utf-8")
+        )
+        assert init_options["ai"] == "claude"
+        assert init_options["ai_skills"] is True
+        assert init_options["integration"] == "claude"
+
+    def test_claude_init_remains_usable_when_converter_fails(self, tmp_path):
+        """Claude init should succeed even without install_skills."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        target = tmp_path / "fail-proj"
+
+        result = runner.invoke(
+            app,
+            ["init", str(target), "--integration", "claude", "--script", "sh", "--ignore-agent-tools"],
+        )
+
+        assert result.exit_code == 0
+        assert (target / ".claude" / "skills" / "speckit-specify" / "SKILL.md").exists()
+
+    def test_claude_hooks_render_skill_invocation(self, tmp_path):
+        from specify_cli.extensions import HookExecutor
+
+        project = tmp_path / "claude-hooks"
+        project.mkdir()
+        init_options = project / ".specify" / "init-options.json"
+        init_options.parent.mkdir(parents=True, exist_ok=True)
+        init_options.write_text(json.dumps({"ai": "claude", "ai_skills": True}))
+
+        hook_executor = HookExecutor(project)
+        message = hook_executor.format_hook_message(
+            "before_plan",
+            [
+                {
+                    "extension": "test-ext",
+                    "command": "speckit.plan",
+                    "optional": False,
+                }
+            ],
+        )
+
+        assert "Executing: `/speckit-plan`" in message
+        assert "EXECUTE_COMMAND: speckit.plan" in message
+        assert "EXECUTE_COMMAND_INVOCATION: /speckit-plan" in message
+
+    def test_claude_preset_creates_new_skill_without_commands_dir(self, tmp_path):
+        from specify_cli import save_init_options
+        from specify_cli.presets import PresetManager
+
+        project = tmp_path / "claude-preset-skill"
+        project.mkdir()
+        save_init_options(project, {"ai": "claude", "ai_skills": True, "script": "sh"})
+
+        skills_dir = project / ".claude" / "skills"
+        skills_dir.mkdir(parents=True, exist_ok=True)
+
+        preset_dir = tmp_path / "claude-skill-command"
+        preset_dir.mkdir()
+        (preset_dir / "commands").mkdir()
+        (preset_dir / "commands" / "speckit.research.md").write_text(
+            "---\n"
+            "description: Research workflow\n"
+            "---\n\n"
+            "preset:claude-skill-command\n"
+        )
+        manifest_data = {
+            "schema_version": "1.0",
+            "preset": {
+                "id": "claude-skill-command",
+                "name": "Claude Skill Command",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "templates": [
+                    {
+                        "type": "command",
+                        "name": "speckit.research",
+                        "file": "commands/speckit.research.md",
+                    }
+                ]
+            },
+        }
+        with open(preset_dir / "preset.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+
+        manager = PresetManager(project)
+        manager.install_from_directory(preset_dir, "0.1.5")
+
+        skill_file = skills_dir / "speckit-research" / "SKILL.md"
+        assert skill_file.exists()
+        content = skill_file.read_text(encoding="utf-8")
+        assert "preset:claude-skill-command" in content
+        assert "name: speckit-research" in content
+        assert "user-invocable: true" in content
+        assert "disable-model-invocation: false" in content
+
+        metadata = manager.registry.get("claude-skill-command")
+        assert "speckit-research" in metadata.get("registered_skills", [])
+
+
+class TestClaudeArgumentHints:
+    """Verify that argument-hint frontmatter is injected for Claude skills."""
+
+    def test_converge_has_no_argument_hint(self):
+        """Converge should not advertise unsupported feature-name arguments."""
+        assert "converge" not in ARGUMENT_HINTS
+
+    def test_all_skills_have_hints(self, tmp_path):
+        """Every skill with a configured hint must contain an argument-hint line."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert len(skill_files) > 0
+        for f in skill_files:
+            stem = f.parent.name
+            if stem.startswith("speckit-"):
+                stem = stem[len("speckit-"):]
+            content = f.read_text(encoding="utf-8")
+            if stem in ARGUMENT_HINTS:
+                assert "argument-hint:" in content, (
+                    f"{f.parent.name}/SKILL.md is missing argument-hint frontmatter"
+                )
+            else:
+                assert "argument-hint:" not in content, (
+                    f"{f.parent.name}/SKILL.md unexpectedly has argument-hint frontmatter"
+                )
+
+    def test_hints_match_expected_values(self, tmp_path):
+        """Each skill's argument-hint must match the expected text."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        for f in skill_files:
+            # Extract stem: speckit-plan -> plan
+            stem = f.parent.name
+            if stem.startswith("speckit-"):
+                stem = stem[len("speckit-"):]
+            expected_hint = ARGUMENT_HINTS.get(stem)
+            content = f.read_text(encoding="utf-8")
+            if expected_hint is None:
+                assert "argument-hint:" not in content, (
+                    f"{f.parent.name}/SKILL.md unexpectedly has argument-hint frontmatter"
+                )
+            else:
+                assert f'argument-hint: "{expected_hint}"' in content, (
+                    f"{f.parent.name}/SKILL.md: expected hint '{expected_hint}' not found"
+                )
+
+    def test_hint_is_inside_frontmatter(self, tmp_path):
+        """argument-hint must appear between the --- delimiters, not in the body."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            parts = content.split("---", 2)
+            assert len(parts) >= 3, f"No frontmatter in {f.parent.name}/SKILL.md"
+            frontmatter = parts[1]
+            body = parts[2]
+            stem = f.parent.name
+            if stem.startswith("speckit-"):
+                stem = stem[len("speckit-"):]
+            if stem in ARGUMENT_HINTS:
+                assert "argument-hint:" in frontmatter, (
+                    f"{f.parent.name}/SKILL.md: argument-hint not in frontmatter section"
+                )
+                assert "argument-hint:" not in body, (
+                    f"{f.parent.name}/SKILL.md: argument-hint leaked into body"
+                )
+            else:
+                assert "argument-hint:" not in content, (
+                    f"{f.parent.name}/SKILL.md unexpectedly has argument-hint frontmatter"
+                )
+
+    def test_hint_appears_after_description(self, tmp_path):
+        """argument-hint must immediately follow the description line."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            lines = content.splitlines()
+            stem = f.parent.name
+            if stem.startswith("speckit-"):
+                stem = stem[len("speckit-"):]
+            if stem not in ARGUMENT_HINTS:
+                assert "argument-hint:" not in content, (
+                    f"{f.parent.name}/SKILL.md unexpectedly has argument-hint frontmatter"
+                )
+                continue
+            found_description = False
+            for idx, line in enumerate(lines):
+                if line.startswith("description:"):
+                    found_description = True
+                    assert idx + 1 < len(lines), (
+                        f"{f.parent.name}/SKILL.md: description is last line"
+                    )
+                    assert lines[idx + 1].startswith("argument-hint:"), (
+                        f"{f.parent.name}/SKILL.md: argument-hint does not follow description"
+                    )
+                    break
+            assert found_description, (
+                f"{f.parent.name}/SKILL.md: no description: line found in output"
+            )
+
+    def test_inject_argument_hint_only_in_frontmatter(self):
+        """inject_argument_hint must not modify description: lines in the body."""
+        from specify_cli.integrations.claude import ClaudeIntegration
+
+        content = (
+            "---\n"
+            "description: My command\n"
+            "---\n"
+            "\n"
+            "description: this is body text\n"
+        )
+        result = ClaudeIntegration.inject_argument_hint(content, "Test hint")
+        lines = result.splitlines()
+        hint_count = sum(1 for ln in lines if ln.startswith("argument-hint:"))
+        assert hint_count == 1, (
+            f"Expected exactly 1 argument-hint line, found {hint_count}"
+        )
+
+    def test_inject_argument_hint_skips_if_already_present(self):
+        """inject_argument_hint must not duplicate if argument-hint already exists."""
+        from specify_cli.integrations.claude import ClaudeIntegration
+
+        content = (
+            "---\n"
+            "description: My command\n"
+            'argument-hint: "Existing hint"\n'
+            "---\n"
+            "\n"
+            "Body text\n"
+        )
+        result = ClaudeIntegration.inject_argument_hint(content, "New hint")
+        assert result == content, "Content should be unchanged when hint already exists"
+        lines = result.splitlines()
+        hint_count = sum(1 for ln in lines if ln.startswith("argument-hint:"))
+        assert hint_count == 1
+
+
+class TestClaudeDisableModelInvocation:
+    """Verify disable-model-invocation is false for Claude skills."""
+
+    def test_setup_sets_disable_model_invocation_false(self, tmp_path):
+        """Generated SKILL.md files must have disable-model-invocation: false."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert len(skill_files) > 0
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            parts = content.split("---", 2)
+            parsed = yaml.safe_load(parts[1])
+            assert parsed["disable-model-invocation"] is False, (
+                f"{f.parent.name}: expected disable-model-invocation: false"
+            )
+
+    def test_disable_model_invocation_not_true(self, tmp_path):
+        """No Claude skill should have disable-model-invocation: true."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        for f in created:
+            if f.name != "SKILL.md":
+                continue
+            content = f.read_text(encoding="utf-8")
+            assert "disable-model-invocation: true" not in content, (
+                f"{f.parent.name}: must not have disable-model-invocation: true"
+            )
+
+    def test_non_claude_agents_lack_disable_model_invocation(self, tmp_path):
+        """Non-Claude skill agents should not get disable-model-invocation."""
+        from specify_cli.agents import CommandRegistrar
+
+        fm = CommandRegistrar.build_skill_frontmatter(
+            "codex", "speckit-plan", "desc", "templates/commands/plan.md"
+        )
+        assert "disable-model-invocation" not in fm
+        assert "user-invocable" not in fm
+
+    def test_skills_default_post_process_preserves_content_without_hooks(self, tmp_path):
+        """SkillsIntegration agents without an override preserve non-hook content."""
+        # ``agy`` is a plain SkillsIntegration with no post-process override,
+        # so it stands in for the base-class default behavior.
+        agy = get_integration("agy")
+        if agy is None:
+            return  # agy not registered in this build
+        content = "---\nname: test\n---\nBody"
+        assert agy.post_process_skill_content(content) == content
+
+
+class TestClaudeForkContext:
+    """Verify context: fork is injected only for commands listed in FORK_CONTEXT_COMMANDS."""
+
+    def test_no_commands_fork_by_default(self):
+        """FORK_CONTEXT_COMMANDS is empty: no command opts into context: fork.
+
+        ``analyze`` was removed (#3185) because its verbose report defeated the
+        purpose of forking and compounded context overhead across repeated runs.
+        """
+        assert FORK_CONTEXT_COMMANDS == {}
+
+    def test_analyze_skill_does_not_fork(self, tmp_path):
+        """speckit-analyze must run in the main session, not a forked subagent (#3185)."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        i.setup(tmp_path, m, script_type="sh")
+        analyze_skill = tmp_path / ".claude/skills/speckit-analyze/SKILL.md"
+        assert analyze_skill.exists()
+        content = analyze_skill.read_text(encoding="utf-8")
+        parts = content.split("---", 2)
+        parsed = yaml.safe_load(parts[1])
+        assert "context" not in parsed
+        assert "agent" not in parsed
+
+    def test_no_skills_fork(self, tmp_path):
+        """Skills not in FORK_CONTEXT_COMMANDS must not get context: fork."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        for f in skill_files:
+            stem = f.parent.name
+            if stem.startswith("speckit-"):
+                stem = stem[len("speckit-"):]
+            if stem in FORK_CONTEXT_COMMANDS:
+                continue
+            content = f.read_text(encoding="utf-8")
+            parts = content.split("---", 2)
+            parsed = yaml.safe_load(parts[1])
+            assert "context" not in parsed, (
+                f"{f.parent.name}: must not have context frontmatter"
+            )
+            assert "agent" not in parsed, (
+                f"{f.parent.name}: must not have agent frontmatter"
+            )
+
+    def test_post_process_no_fork_for_skills(self):
+        """With FORK_CONTEXT_COMMANDS empty, post_process must not add context/agent."""
+        i = get_integration("claude")
+        for name in ("speckit-analyze", "speckit-plan"):
+            content = f'---\nname: "{name}"\ndescription: "x"\n---\n\nBody\n'
+            result = i.post_process_skill_content(content)
+            parsed = yaml.safe_load(result.split("---", 2)[1])
+            assert "context" not in parsed
+            assert "agent" not in parsed
+
+    def test_fork_mechanism_injects_when_configured(self, monkeypatch):
+        """The injection mechanism still works for any command added to
+        FORK_CONTEXT_COMMANDS, even though none ships enabled by default."""
+        import specify_cli.integrations.claude as claude_mod
+
+        monkeypatch.setitem(
+            claude_mod.FORK_CONTEXT_COMMANDS,
+            "analyze",
+            {"context": "fork", "agent": "general-purpose"},
+        )
+        i = get_integration("claude")
+        content = '---\nname: "speckit-analyze"\ndescription: "x"\n---\n\nBody\n'
+        result = i.post_process_skill_content(content)
+        parts = result.split("---", 2)
+        parsed = yaml.safe_load(parts[1])
+        assert parsed.get("context") == "fork"
+        assert parsed.get("agent") == "general-purpose"
+        # Flags must land in the frontmatter, not the body.
+        assert "context: fork" in parts[1]
+        assert "context: fork" not in parts[2]
+        # Re-running must not duplicate the injected keys.
+        twice = i.post_process_skill_content(result)
+        assert result == twice
+        assert twice.count("context: fork") == 1
+        assert twice.count("agent: general-purpose") == 1
+
+
+class TestClaudeHookCommandNote:
+    """Verify dot-to-hyphen normalization note is injected in hook sections."""
+
+    def test_hook_note_injected_in_skills_with_hooks(self, tmp_path):
+        """Skills that have hook sections should get the normalization note."""
+        i = get_integration("claude")
+        m = IntegrationManifest("claude", tmp_path)
+        i.setup(tmp_path, m, script_type="sh")
+        specify_skill = tmp_path / ".claude/skills/speckit-specify/SKILL.md"
+        assert specify_skill.exists()
+        content = specify_skill.read_text(encoding="utf-8")
+        # specify.md has hook sections
+        assert "replace dots" in content, (
+            "speckit-specify should have dot-to-hyphen hook note"
+        )
+
+    def test_hook_note_not_in_skills_without_hooks(self, tmp_path):
+        """Skills without hook sections should not get the note."""
+        content = "---\nname: test\ndescription: test\n---\n\nNo hooks here.\n"
+        result = SkillsIntegration._inject_hook_command_note(content)
+        assert "replace dots" not in result
+
+    def test_hook_note_idempotent(self, tmp_path):
+        """Injecting the note twice should not duplicate it."""
+        content = (
+            "---\nname: test\n---\n\n"
+            "- For each executable hook, output the following based on its flag:\n"
+        )
+        once = SkillsIntegration._inject_hook_command_note(content)
+        twice = SkillsIntegration._inject_hook_command_note(once)
+        assert once == twice, "Hook note injection should be idempotent"
+
+    def test_hook_note_fills_missing_repeated_instructions(self, tmp_path):
+        """Already-noted hook sections should not suppress later sections."""
+        from specify_cli.integrations.base import _HOOK_COMMAND_NOTE
+
+        content = (
+            "---\nname: test\n---\n\n"
+            f"{_HOOK_COMMAND_NOTE}"
+            "- For each executable hook, output the following based on its flag:\n"
+            "\n"
+            "  - For each executable hook, output the following based on its flag:\n"
+        )
+        result = SkillsIntegration._inject_hook_command_note(content)
+        assert result.count("replace dots (`.`) with hyphens") == 2
+
+    def test_hook_note_not_suppressed_by_unrelated_phrase(self, tmp_path):
+        """Unrelated text should not trip the hook-note idempotence guard."""
+        content = (
+            "---\nname: test\n---\n\n"
+            "This paragraph says replace dots in a different context.\n"
+            "- For each executable hook, output the following based on its flag:\n"
+        )
+        result = SkillsIntegration._inject_hook_command_note(content)
+        assert "This paragraph says replace dots in a different context." in result
+        assert result.count("replace dots (`.`) with hyphens") == 1
+
+    def test_hook_note_preserves_indentation(self, tmp_path):
+        """The injected note should match the indentation of the target line."""
+        content = (
+            "---\nname: test\n---\n\n"
+            "   - For each executable hook, output the following\n"
+        )
+        result = SkillsIntegration._inject_hook_command_note(content)
+        lines = result.splitlines()
+        note_line = [line for line in lines if "replace dots" in line][0]
+        assert note_line.startswith("   "), "Note should preserve indentation"
+
+    def test_post_process_injects_all_claude_flags(self):
+        """post_process_skill_content should inject all Claude-specific fields."""
+        i = get_integration("claude")
+        content = (
+            "---\nname: test\ndescription: test\n---\n\n"
+            "- For each executable hook, output the following\n"
+        )
+        result = i.post_process_skill_content(content)
+        assert "user-invocable: true" in result
+        assert "disable-model-invocation: false" in result
+        assert "replace dots" in result
+
+
+class TestSpeckitManifestRecordsSkippedFiles:
+    """Regression test for issue #2107.
+
+    ``install_shared_infra`` must record every shared-infrastructure file
+    under ``.specify/`` in ``speckit.manifest.json``, including files that
+    were *skipped* because they already existed on disk and ``force=False``.
+
+    Before the fix, the skip branches in the scripts and templates loops
+    appended to ``skipped_files`` without calling ``manifest.record_existing``.
+    So when ``install_shared_infra`` ran with a fresh (or lost) manifest
+    against an already-populated ``.specify/`` tree, every file went down the
+    skip path, ``planned_copies`` and ``planned_templates`` stayed empty, and
+    ``manifest.save()`` wrote an empty ``files`` field — leaving the
+    integration believing nothing was installed.
+
+    Reproduction (without the fix) using ``install_shared_infra`` directly:
+
+        install_shared_infra(p, "sh", ..., force=False)   # 1st run → 10 files
+        (p / ".specify/integrations/speckit.manifest.json").unlink()
+        install_shared_infra(p, "sh", ..., force=False)   # 2nd run → 0 files
+                                                          # ^^ BUG: empty
+    """
+
+    def _read_manifest_files(self, project_path: Path) -> dict:
+        manifest_path = (
+            project_path / ".specify" / "integrations" / "speckit.manifest.json"
+        )
+        assert manifest_path.exists(), (
+            f"speckit.manifest.json not written at {manifest_path}"
+        )
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        # ``IntegrationManifest.save`` serialises a ``files`` dict — assert
+        # the schema explicitly so a regression to a different key (e.g.
+        # the internal ``_files`` attribute name) fails loudly instead of
+        # being masked by a silent fallback.
+        assert isinstance(data, dict), (
+            f"manifest root is not a dict, got {type(data).__name__}"
+        )
+        assert "files" in data, (
+            f"manifest missing 'files' key, got keys: {sorted(data.keys())}"
+        )
+        files = data["files"]
+        assert isinstance(files, dict), (
+            f"manifest 'files' is not a dict, got {type(files).__name__}"
+        )
+        return files
+
+    def test_install_shared_infra_records_skipped_files(self, tmp_path):
+        """With ``force=False`` and ``.specify/`` already populated, the
+        manifest must still record every file — the skip branches are not
+        allowed to drop files from the manifest."""
+        from rich.console import Console
+        from specify_cli.shared_infra import install_shared_infra
+
+        # Resolve the project's own packaged sources by walking up from this
+        # test file to the repo root (which contains ``scripts/`` and
+        # ``templates/`` that ``shared_scripts_source`` looks for).
+        repo_root = Path(__file__).resolve().parents[2]
+        console = Console(quiet=True)
+
+        # First run — fresh project, manifest gets populated normally.
+        install_shared_infra(
+            tmp_path,
+            "sh",
+            version="0.0.0",
+            core_pack=None,
+            repo_root=repo_root,
+            console=console,
+            force=False,
+        )
+        first_files = self._read_manifest_files(tmp_path)
+        assert first_files, "first install produced an empty manifest"
+
+        # Simulate a lost manifest while ``.specify/`` is still on disk
+        # (e.g. the manifest was deleted, corrupted, or the layout was
+        # extracted out-of-band).
+        manifest_path = (
+            tmp_path / ".specify" / "integrations" / "speckit.manifest.json"
+        )
+        manifest_path.unlink()
+
+        # Second run — every file already exists, so every iteration takes
+        # the skip branch. With the fix, those files are still recorded.
+        install_shared_infra(
+            tmp_path,
+            "sh",
+            version="0.0.0",
+            core_pack=None,
+            repo_root=repo_root,
+            console=console,
+            force=False,
+        )
+        second_files = self._read_manifest_files(tmp_path)
+        assert second_files, (
+            "speckit.manifest.json files dict is empty after install with "
+            "skipped files (issue #2107) — every file went down the skip "
+            "branch but none were recorded"
+        )
+
+        # The recovered manifest must cover everything the first run tracked.
+        missing = set(first_files) - set(second_files)
+        assert not missing, (
+            f"these files were tracked on the first install but missing after "
+            f"the skipped-files re-install: {sorted(missing)[:5]}"
+        )
+
+    def test_install_shared_infra_handles_directory_at_script_destination(
+        self, tmp_path
+    ):
+        """A non-file (directory) at a script's destination must NOT crash
+        ``install_shared_infra`` and must NOT be recorded in the manifest —
+        the path still appears in the user-visible skipped-paths warning.
+        """
+        from io import StringIO
+        from rich.console import Console
+        from specify_cli.shared_infra import install_shared_infra
+
+        repo_root = Path(__file__).resolve().parents[2]
+        output = StringIO()
+        console = Console(file=output, force_terminal=False, width=200)
+
+        # Pre-create the .specify/scripts/bash tree, then plant a directory
+        # where a script file is expected so the skip branch hits a
+        # non-regular-file path.
+        bash_dir = tmp_path / ".specify" / "scripts" / "bash"
+        bash_dir.mkdir(parents=True)
+        (bash_dir / "common.sh").mkdir()  # collision: dir where file expected
+
+        # Must not crash.
+        install_shared_infra(
+            tmp_path,
+            "sh",
+            version="0.0.0",
+            core_pack=None,
+            repo_root=repo_root,
+            console=console,
+            force=False,
+        )
+
+        files = self._read_manifest_files(tmp_path)
+        assert ".specify/scripts/bash/common.sh" not in files, (
+            "directory at script dst must not be recorded in the manifest"
+        )
+        text = output.getvalue()
+        assert "common.sh" in text, (
+            "directory-at-script-dst path must surface in the skipped warning"
+        )
+
+    def test_install_shared_infra_handles_directory_at_template_destination(
+        self, tmp_path
+    ):
+        """Symmetric coverage for the templates loop: a directory at a
+        template's destination must NOT crash install nor be recorded."""
+        from io import StringIO
+        from rich.console import Console
+        from specify_cli.shared_infra import install_shared_infra
+
+        repo_root = Path(__file__).resolve().parents[2]
+        output = StringIO()
+        console = Console(file=output, force_terminal=False, width=200)
+
+        templates_dir = tmp_path / ".specify" / "templates"
+        templates_dir.mkdir(parents=True)
+
+        src_templates = repo_root / "templates"
+        real_template = next(
+            (
+                p.name
+                for p in src_templates.iterdir()
+                if p.is_file()
+                and not p.name.startswith(".")
+                and p.name != "vscode-settings.json"
+            ),
+            None,
+        )
+        assert real_template, (
+            "no real template found in repo to collide against"
+        )
+        (templates_dir / real_template).mkdir()  # collision
+
+        install_shared_infra(
+            tmp_path,
+            "sh",
+            version="0.0.0",
+            core_pack=None,
+            repo_root=repo_root,
+            console=console,
+            force=False,
+        )
+
+        files = self._read_manifest_files(tmp_path)
+        template_rel = f".specify/templates/{real_template}"
+        assert template_rel not in files, (
+            "directory at template dst must not be recorded in manifest"
+        )
+        text = output.getvalue()
+        assert real_template in text, (
+            "directory-at-template-dst path must surface in the skipped warning"
+        )

tests/integrations/test_integration_cline.py

@@ -0,0 +1,222 @@
+"""Tests for ClineIntegration."""
+
+import os
+import pytest
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.cline import format_cline_command_name
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestClineCommandNameFormatter:
+    """Test the Cline command name formatter."""
+
+    def test_simple_name_without_prefix(self):
+        """Test formatting a simple name without 'speckit.' prefix."""
+        assert format_cline_command_name("plan") == "speckit-plan"
+        assert format_cline_command_name("tasks") == "speckit-tasks"
+        assert format_cline_command_name("specify") == "speckit-specify"
+
+    def test_name_with_speckit_prefix(self):
+        """Test formatting a name that already has 'speckit.' prefix."""
+        assert format_cline_command_name("speckit.plan") == "speckit-plan"
+        assert format_cline_command_name("speckit.tasks") == "speckit-tasks"
+
+    def test_extension_command_name(self):
+        """Test formatting extension command names with dots."""
+        assert (
+            format_cline_command_name("speckit.my-extension.example")
+            == "speckit-my-extension-example"
+        )
+        assert (
+            format_cline_command_name("my-extension.example")
+            == "speckit-my-extension-example"
+        )
+
+    def test_idempotent_already_hyphenated(self):
+        """Test that already-hyphenated names are returned unchanged (idempotent)."""
+        assert format_cline_command_name("speckit-plan") == "speckit-plan"
+        assert (
+            format_cline_command_name("speckit-my-extension-example")
+            == "speckit-my-extension-example"
+        )
+
+
+class TestClineIntegration(MarkdownIntegrationTests):
+    KEY = "cline"
+    FOLDER = ".clinerules/"
+    COMMANDS_SUBDIR = "workflows"
+    REGISTRAR_DIR = ".clinerules/workflows"
+
+    @pytest.mark.parametrize(
+        "cmd_name, expected_filename",
+        [
+            ("plan", "speckit-plan.md"),
+            ("speckit.plan", "speckit-plan.md"),
+            ("speckit.git.commit", "speckit-git-commit.md"),
+            ("speckit", "speckit-speckit.md"),
+            ("speckitfoo", "speckit-speckitfoo.md"),
+        ],
+    )
+    def test_cline_command_filename(self, cmd_name, expected_filename):
+        """Verify Cline uses hyphenated filenames."""
+        cline = get_integration("cline")
+        assert cline.command_filename(cmd_name) == expected_filename
+
+    def test_cline_invoke_separator(self):
+        """Verify Cline uses hyphen as invoke separator."""
+        cline = get_integration("cline")
+        assert cline.invoke_separator == "-"
+        assert cline.registrar_config["invoke_separator"] == "-"
+
+    def test_cline_name_injection_and_formatting(self):
+        """Verify Cline has inject_name and format_name configured."""
+        cline = get_integration("cline")
+        assert cline.registrar_config["inject_name"] is True
+        assert cline.registrar_config["format_name"] == format_cline_command_name
+
+    def test_cline_handoff_rewrite(self):
+        """Verify Cline rewrites agent: speckit.foo to agent: speckit-foo."""
+        cline = get_integration("cline")
+        content = "---\nagent: speckit.plan\n---\n"
+        rewritten = cline._rewrite_handoff_references(content)
+        assert rewritten == "---\nagent: speckit-plan\n---\n"
+
+    def test_cline_hook_instruction_injection(self):
+        """Verify Cline injects the dot-to-hyphen note for hooks."""
+        cline = get_integration("cline")
+        content = "- For each executable hook, output the following:\n"
+        injected = cline._inject_hook_command_note(content)
+        assert "replace dots (`.`) with hyphens (`-`)" in injected
+        assert "- For each executable hook, output the following:" in injected
+
+    def test_cline_hook_instruction_injection_no_trailing_newline(self):
+        """Note must not collapse onto the instruction line when the
+        instruction is the final line with no trailing newline.
+
+        The injection regex matches the end-of-line via ``(\\r\\n|\\n|$)``, so
+        the captured ``eol`` is empty on a file's last line that lacks a
+        trailing newline. Without an ``or "\\n"`` fallback the note text and
+        the instruction are emitted on the same line.
+        """
+        cline = get_integration("cline")
+        content = "- For each executable hook, output the following:"  # no trailing \n
+        injected = cline._inject_hook_command_note(content)
+        assert "replace dots (`.`) with hyphens (`-`)" in injected
+        # Instruction stays on its own line rather than being mashed onto the note.
+        assert "\n- For each executable hook, output the following:" in injected
+
+    # -- Overrides for MarkdownIntegrationTests ---------------------------
+
+    def test_setup_creates_files(self, tmp_path):
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        assert len(created) > 0
+        cmd_files = [
+            f
+            for f in created
+            if "scripts" not in f.parts
+            and f.suffix == ".md"
+        ]
+        for f in cmd_files:
+            assert f.exists()
+            assert f.name.startswith("speckit-")
+            assert f.name.endswith(".md")
+
+        specify_file = next(
+            (f for f in cmd_files if f.name == "speckit-specify.md"), None
+        )
+        assert specify_file is not None
+        specify_contents = specify_file.read_text(encoding="utf-8")
+        assert "/speckit-plan" in specify_contents
+        assert "/speckit.plan" not in specify_contents
+
+    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",
+                    "--ignore-agent-tools",
+                ],
+                catch_exceptions=False,
+            )
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        i = get_integration(self.KEY)
+        cmd_dir = i.commands_dest(project)
+        assert cmd_dir.is_dir()
+        commands = sorted(cmd_dir.glob("speckit-*"))
+        assert len(commands) > 0
+
+    def _expected_files(self, script_variant: str) -> list[str]:
+        """Override to expect hyphenated speckit- prefix."""
+        i = get_integration(self.KEY)
+        cmd_dir = i.registrar_config["dir"]
+        files = []
+
+        # Command files
+        for stem in (
+            self.COMMANDS_SUBDIR_STEMS
+            if hasattr(self, "COMMANDS_SUBDIR_STEMS")
+            else self.COMMAND_STEMS
+        ):
+            files.append(f"{cmd_dir}/speckit-{stem.replace('.', '-')}.md")
+
+        # Framework files
+        files.append(".specify/integration.json")
+        files.append(".specify/init-options.json")
+        files.append(f".specify/integrations/{self.KEY}.manifest.json")
+        files.append(".specify/integrations/speckit.manifest.json")
+
+        if script_variant == "sh":
+            for name in [
+                "check-prerequisites.sh",
+                "common.sh",
+                "create-new-feature.sh",
+                "setup-plan.sh",
+                "setup-tasks.sh",
+            ]:
+                files.append(f".specify/scripts/bash/{name}")
+        else:
+            for name in [
+                "check-prerequisites.ps1",
+                "common.ps1",
+                "create-new-feature.ps1",
+                "setup-plan.ps1",
+                "setup-tasks.ps1",
+            ]:
+                files.append(f".specify/scripts/powershell/{name}")
+
+        for name in [
+            "checklist-template.md",
+            "constitution-template.md",
+            "plan-template.md",
+            "spec-template.md",
+            "tasks-template.md",
+        ]:
+            files.append(f".specify/templates/{name}")
+
+        files.append(".specify/memory/constitution.md")
+        # Bundled workflow
+        files.append(".specify/workflows/speckit/workflow.yml")
+        files.append(".specify/workflows/workflow-registry.json")
+
+        return sorted(files)

tests/integrations/test_integration_codebuddy.py

@@ -0,0 +1,21 @@
+"""Tests for CodebuddyIntegration."""
+
+from specify_cli.integrations import get_integration
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestCodebuddyIntegration(MarkdownIntegrationTests):
+    KEY = "codebuddy"
+    FOLDER = ".codebuddy/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".codebuddy/commands"
+
+    def test_install_url_points_to_official_cli_install_docs(self):
+        integration = get_integration(self.KEY)
+        assert integration is not None
+
+        assert (
+            integration.config["install_url"]
+            == "https://www.codebuddy.cn/docs/cli/installation"
+        )

tests/integrations/test_integration_codex.py

@@ -0,0 +1,192 @@
+"""Tests for CodexIntegration."""
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestCodexIntegration(SkillsIntegrationTests):
+    KEY = "codex"
+    FOLDER = ".agents/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".agents/skills"
+
+
+class TestCodexInitFlow:
+    """--integration codex creates expected files."""
+
+    def test_integration_codex_creates_skills(self, tmp_path):
+        """--integration codex should create skills in .agents/skills."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        target = tmp_path / "test-proj"
+        result = runner.invoke(app, ["init", str(target), "--integration", "codex", "--ignore-agent-tools", "--script", "sh"])
+
+        assert result.exit_code == 0, f"init --integration codex failed: {result.output}"
+        assert (target / ".agents" / "skills" / "speckit-plan" / "SKILL.md").exists()
+
+    def test_plan_skill_has_no_context_placeholder(self, tmp_path):
+        """The core plan skill must not carry a context-file placeholder —
+        agent context files are owned by the opt-in agent-context extension."""
+        target = tmp_path / "test-proj"
+        target.mkdir()
+
+        integration = get_integration("codex")
+        manifest = IntegrationManifest("codex", target)
+        integration.setup(target, manifest, script_type="sh")
+
+        plan_skill = target / ".agents" / "skills" / "speckit-plan" / "SKILL.md"
+        content = plan_skill.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content
+
+    def test_plan_skill_ignores_extension_config(self, tmp_path):
+        """The extension config must not influence rendered commands: the CLI
+        no longer reads any context-file metadata when rendering."""
+        import yaml
+
+        target = tmp_path / "test-proj"
+        target.mkdir()
+        ext_cfg = (
+            target
+            / ".specify"
+            / "extensions"
+            / "agent-context"
+            / "agent-context-config.yml"
+        )
+        ext_cfg.parent.mkdir(parents=True, exist_ok=True)
+        ext_cfg.write_text(
+            yaml.safe_dump(
+                {
+                    "context_file": "FROM_CONFIG.md",
+                    "context_files": ["FROM_CONFIG.md", "ALSO_CONFIG.md"],
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        integration = get_integration("codex")
+        manifest = IntegrationManifest("codex", target)
+        integration.setup(target, manifest, script_type="sh")
+
+        plan_skill = target / ".agents" / "skills" / "speckit-plan" / "SKILL.md"
+        content = plan_skill.read_text(encoding="utf-8")
+        assert "FROM_CONFIG.md" not in content
+        assert "ALSO_CONFIG.md" not in content
+        assert "__CONTEXT_FILE__" not in content
+
+
+class TestCodexHookCommandNote:
+    """Verify dot-to-hyphen normalization note is injected in hook sections.
+
+    Hook commands in ``extensions.yml`` use dotted ids like
+    ``speckit.git.commit`` but Codex skills are named with hyphens
+    (``speckit-git-commit``). Without this note, Codex emits
+    ``/speckit.git.commit``, which does not resolve.
+    """
+
+    def test_hook_note_injected_in_skills_with_hooks(self, tmp_path):
+        """Skills that have hook sections should get the normalization note."""
+        i = get_integration("codex")
+        m = IntegrationManifest("codex", tmp_path)
+        i.setup(tmp_path, m, script_type="sh")
+        specify_skill = tmp_path / ".agents/skills/speckit-specify/SKILL.md"
+        assert specify_skill.exists()
+        content = specify_skill.read_text(encoding="utf-8")
+        assert "replace dots" in content, (
+            "speckit-specify should have dot-to-hyphen hook note"
+        )
+
+    def test_hook_note_not_in_skills_without_hooks(self):
+        """Skills without hook sections should not get the note."""
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = "---\nname: test\ndescription: test\n---\n\nNo hooks here.\n"
+        result = CodexIntegration._inject_hook_command_note(content)
+        assert "replace dots" not in result
+
+    def test_hook_note_idempotent(self):
+        """Injecting the note twice should not duplicate it."""
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            "- For each executable hook, output the following based on its flag:\n"
+        )
+        once = CodexIntegration._inject_hook_command_note(content)
+        twice = CodexIntegration._inject_hook_command_note(once)
+        assert once == twice, "Hook note injection should be idempotent"
+
+    def test_hook_note_fills_missing_repeated_instructions(self):
+        """Already-noted hook sections should not suppress later sections."""
+        from specify_cli.integrations.base import _HOOK_COMMAND_NOTE
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            f"{_HOOK_COMMAND_NOTE}"
+            "- For each executable hook, output the following based on its flag:\n"
+            "\n"
+            "  - For each executable hook, output the following based on its flag:\n"
+        )
+        result = CodexIntegration._inject_hook_command_note(content)
+        assert result.count("replace dots (`.`) with hyphens") == 2
+
+    def test_hook_note_not_suppressed_by_unrelated_phrase(self):
+        """Unrelated text should not trip the hook-note idempotence guard."""
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            "This paragraph says replace dots in a different context.\n"
+            "- For each executable hook, output the following based on its flag:\n"
+        )
+        result = CodexIntegration._inject_hook_command_note(content)
+        assert "This paragraph says replace dots in a different context." in result
+        assert result.count("replace dots (`.`) with hyphens") == 1
+
+    def test_hook_note_preserves_indentation(self):
+        """The injected note should match the indentation of the target line."""
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            "   - For each executable hook, output the following\n"
+        )
+        result = CodexIntegration._inject_hook_command_note(content)
+        lines = result.splitlines()
+        note_line = [line for line in lines if "replace dots" in line][0]
+        assert note_line.startswith("   "), "Note should preserve indentation"
+
+    def test_hook_note_when_instruction_is_final_line_without_newline(self):
+        """Note must not collapse onto the instruction line when the file
+        ends without a trailing newline and the preceding line is not blank.
+        """
+        from specify_cli.integrations.codex import CodexIntegration
+
+        # No blank line before the instruction and no trailing newline:
+        # this is the case where the captured ``eol`` is empty and the
+        # captured indent is also empty, so a missing line separator would
+        # cause the note and instruction to collapse onto one line.
+        content = (
+            "---\nname: test\n---\n"
+            "Body line\n"
+            "- For each executable hook, output the following"
+        )
+        result = CodexIntegration._inject_hook_command_note(content)
+        lines = result.splitlines()
+        note_line_idx = next(
+            i for i, line in enumerate(lines) if "replace dots" in line
+        )
+        instruction_line_idx = next(
+            i for i, line in enumerate(lines)
+            if line.lstrip().startswith("- For each executable hook")
+        )
+        assert note_line_idx < instruction_line_idx, (
+            "Note must appear before the instruction"
+        )
+        assert "For each executable hook" not in lines[note_line_idx], (
+            "Note and instruction must not be on the same line"
+        )

tests/integrations/test_integration_copilot.py

@@ -0,0 +1,827 @@
+"""Tests for CopilotIntegration."""
+
+import json
+import os
+import warnings
+
+import pytest
+import yaml
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class TestCopilotIntegration:
+    def test_copilot_key_and_config(self):
+        copilot = get_integration("copilot")
+        assert copilot is not None
+        assert copilot.key == "copilot"
+        assert copilot.config["folder"] == ".github/"
+        assert copilot.config["commands_subdir"] == "agents"
+        assert copilot.registrar_config["extension"] == ".agent.md"
+
+    def test_command_filename_agent_md(self):
+        copilot = get_integration("copilot")
+        assert copilot.command_filename("plan") == "speckit.plan.agent.md"
+
+    def test_setup_creates_agent_md_files(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        assert len(created) > 0
+        agent_files = [f for f in created if ".agent." in f.name]
+        assert len(agent_files) > 0
+        for f in agent_files:
+            assert f.parent == tmp_path / ".github" / "agents"
+            assert f.name.endswith(".agent.md")
+
+    def test_setup_warns_legacy_markdown_default_is_deprecated(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+
+        with pytest.warns(UserWarning, match="Copilot legacy markdown mode is deprecated"):
+            created = copilot.setup(tmp_path, m)
+
+        assert any(f.name.endswith(".agent.md") for f in created)
+
+    def test_skills_setup_does_not_warn_about_legacy_default(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            created = copilot.setup(tmp_path, m, parsed_options={"skills": True})
+
+        assert not any(
+            "Copilot legacy markdown mode is deprecated" in str(item.message)
+            for item in caught
+        )
+        assert any(f.name == "SKILL.md" for f in created)
+
+    def test_setup_creates_companion_prompts(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        prompt_files = [f for f in created if f.parent.name == "prompts"]
+        assert len(prompt_files) > 0
+        for f in prompt_files:
+            assert f.name.endswith(".prompt.md")
+            content = f.read_text(encoding="utf-8")
+            assert content.startswith("---\nagent: speckit.")
+
+    def test_agent_and_prompt_counts_match(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        agents = [f for f in created if ".agent.md" in f.name]
+        prompts = [f for f in created if ".prompt.md" in f.name]
+        assert len(agents) == len(prompts)
+
+    def test_setup_creates_vscode_settings_new(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        assert copilot._vscode_settings_path() is not None
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        settings = tmp_path / ".vscode" / "settings.json"
+        assert settings.exists()
+        assert settings in created
+        assert any("settings.json" in k for k in m.files)
+
+    def test_setup_merges_existing_vscode_settings(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        vscode_dir = tmp_path / ".vscode"
+        vscode_dir.mkdir(parents=True)
+        existing = {"editor.fontSize": 14, "custom.setting": True}
+        (vscode_dir / "settings.json").write_text(json.dumps(existing, indent=4), encoding="utf-8")
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        settings = tmp_path / ".vscode" / "settings.json"
+        data = json.loads(settings.read_text(encoding="utf-8"))
+        assert data["editor.fontSize"] == 14
+        assert data["custom.setting"] is True
+        assert settings not in created
+        assert not any("settings.json" in k for k in m.files)
+
+    def test_all_created_files_tracked_in_manifest(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        for f in created:
+            rel = f.resolve().relative_to(tmp_path.resolve()).as_posix()
+            assert rel in m.files, f"Created file {rel} not tracked in manifest"
+
+    def test_install_uninstall_roundtrip(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.install(tmp_path, m)
+        assert len(created) > 0
+        m.save()
+        for f in created:
+            assert f.exists()
+        removed, skipped = copilot.uninstall(tmp_path, m)
+        assert len(removed) == len(created)
+        assert skipped == []
+
+    def test_modified_file_survives_uninstall(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.install(tmp_path, m)
+        m.save()
+        modified_file = created[0]
+        modified_file.write_text("user modified this", encoding="utf-8")
+        removed, skipped = copilot.uninstall(tmp_path, m)
+        assert modified_file.exists()
+        assert modified_file in skipped
+
+    def test_directory_structure(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        copilot.setup(tmp_path, m)
+        agents_dir = tmp_path / ".github" / "agents"
+        assert agents_dir.is_dir()
+        agent_files = sorted(agents_dir.glob("speckit.*.agent.md"))
+        assert len(agent_files) == 10
+        expected_commands = {
+            "analyze", "clarify", "constitution", "converge", "implement",
+            "plan", "checklist", "specify", "tasks", "taskstoissues",
+        }
+        actual_commands = {f.name.removeprefix("speckit.").removesuffix(".agent.md") for f in agent_files}
+        assert actual_commands == expected_commands
+
+    def test_templates_are_processed(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        copilot.setup(tmp_path, m)
+        agents_dir = tmp_path / ".github" / "agents"
+        for agent_file in agents_dir.glob("speckit.*.agent.md"):
+            content = agent_file.read_text(encoding="utf-8")
+            assert "{SCRIPT}" not in content, f"{agent_file.name} has unprocessed {{SCRIPT}}"
+            assert "__AGENT__" not in content, f"{agent_file.name} has unprocessed __AGENT__"
+            assert "{ARGS}" not in content, f"{agent_file.name} has unprocessed {{ARGS}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{agent_file.name} has unprocessed __SPECKIT_COMMAND_*__"
+            assert "\nscripts:\n" not in content
+
+    def test_specify_agent_resolves_active_spec_template(self, tmp_path):
+        """Generated specify agent must not hardcode the core spec template."""
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        copilot.setup(tmp_path, m)
+
+        specify_file = tmp_path / ".github" / "agents" / "speckit.specify.agent.md"
+        content = specify_file.read_text(encoding="utf-8")
+
+        assert "specify preset resolve spec-template" in content
+        assert "resolved active `spec-template`" in content
+        assert "Copy `.specify/templates/spec-template.md`" not in content
+        assert "Load `.specify/templates/spec-template.md`" not in content
+
+    def test_plan_command_has_no_context_placeholder(self, tmp_path):
+        """The core plan command must not carry a context-file placeholder —
+        agent context files are owned by the opt-in agent-context extension."""
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        copilot.setup(tmp_path, m)
+        plan_file = tmp_path / ".github" / "agents" / "speckit.plan.agent.md"
+        assert plan_file.exists()
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content
+
+    def test_complete_file_inventory_sh(self, tmp_path):
+        """Every file produced by specify init --integration copilot --script sh."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "inventory-sh"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "copilot", "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        actual = sorted(p.relative_to(project).as_posix() for p in project.rglob("*") if p.is_file() and ".git" not in p.parts)
+        expected = sorted([
+            ".github/agents/speckit.analyze.agent.md",
+            ".github/agents/speckit.checklist.agent.md",
+            ".github/agents/speckit.clarify.agent.md",
+            ".github/agents/speckit.constitution.agent.md",
+            ".github/agents/speckit.converge.agent.md",
+            ".github/agents/speckit.implement.agent.md",
+            ".github/agents/speckit.plan.agent.md",
+            ".github/agents/speckit.specify.agent.md",
+            ".github/agents/speckit.tasks.agent.md",
+            ".github/agents/speckit.taskstoissues.agent.md",
+            ".github/prompts/speckit.analyze.prompt.md",
+            ".github/prompts/speckit.checklist.prompt.md",
+            ".github/prompts/speckit.clarify.prompt.md",
+            ".github/prompts/speckit.constitution.prompt.md",
+            ".github/prompts/speckit.converge.prompt.md",
+            ".github/prompts/speckit.implement.prompt.md",
+            ".github/prompts/speckit.plan.prompt.md",
+            ".github/prompts/speckit.specify.prompt.md",
+            ".github/prompts/speckit.tasks.prompt.md",
+            ".github/prompts/speckit.taskstoissues.prompt.md",
+            ".vscode/settings.json",
+            ".specify/integration.json",
+            ".specify/init-options.json",
+            ".specify/integrations/copilot.manifest.json",
+            ".specify/integrations/speckit.manifest.json",
+            ".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/setup-tasks.sh",
+            ".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",
+            ".specify/memory/constitution.md",
+            ".specify/workflows/speckit/workflow.yml",
+            ".specify/workflows/workflow-registry.json",
+        ])
+        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 copilot --script ps."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "inventory-ps"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "copilot", "--script", "ps",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        actual = sorted(p.relative_to(project).as_posix() for p in project.rglob("*") if p.is_file() and ".git" not in p.parts)
+        expected = sorted([
+            ".github/agents/speckit.analyze.agent.md",
+            ".github/agents/speckit.checklist.agent.md",
+            ".github/agents/speckit.clarify.agent.md",
+            ".github/agents/speckit.constitution.agent.md",
+            ".github/agents/speckit.converge.agent.md",
+            ".github/agents/speckit.implement.agent.md",
+            ".github/agents/speckit.plan.agent.md",
+            ".github/agents/speckit.specify.agent.md",
+            ".github/agents/speckit.tasks.agent.md",
+            ".github/agents/speckit.taskstoissues.agent.md",
+            ".github/prompts/speckit.analyze.prompt.md",
+            ".github/prompts/speckit.checklist.prompt.md",
+            ".github/prompts/speckit.clarify.prompt.md",
+            ".github/prompts/speckit.constitution.prompt.md",
+            ".github/prompts/speckit.converge.prompt.md",
+            ".github/prompts/speckit.implement.prompt.md",
+            ".github/prompts/speckit.plan.prompt.md",
+            ".github/prompts/speckit.specify.prompt.md",
+            ".github/prompts/speckit.tasks.prompt.md",
+            ".github/prompts/speckit.taskstoissues.prompt.md",
+            ".vscode/settings.json",
+            ".specify/integration.json",
+            ".specify/init-options.json",
+            ".specify/integrations/copilot.manifest.json",
+            ".specify/integrations/speckit.manifest.json",
+            ".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/setup-tasks.ps1",
+            ".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",
+            ".specify/memory/constitution.md",
+            ".specify/workflows/speckit/workflow.yml",
+            ".specify/workflows/workflow-registry.json",
+        ])
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )
+
+    def test_default_cli_init_warns_legacy_markdown_is_deprecated(self, tmp_path):
+        """Default Copilot init should warn users about the future skills default."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "default-warning"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            with pytest.warns(
+                UserWarning,
+                match="Copilot legacy markdown mode is deprecated",
+            ):
+                result = CliRunner().invoke(app, [
+                    "init", "--here", "--integration", "copilot", "--script", "sh",
+                ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0, result.output
+
+    def test_skills_cli_init_does_not_warn_about_legacy_markdown(self, tmp_path):
+        """Explicit Copilot skills mode should not warn about the legacy default."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "skills-no-warning"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            with warnings.catch_warnings(record=True) as caught:
+                warnings.simplefilter("always")
+                result = CliRunner().invoke(app, [
+                    "init", "--here", "--integration", "copilot",
+                    "--integration-options", "--skills", "--script", "sh",
+                ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0, result.output
+        assert not any(
+            "Copilot legacy markdown mode is deprecated" in str(item.message)
+            for item in caught
+        )
+
+
+class TestCopilotSkillsMode:
+    """Tests for Copilot integration in --skills mode."""
+
+    _SKILL_COMMANDS = [
+        "analyze", "clarify", "constitution", "converge", "implement",
+        "plan", "checklist", "specify", "tasks", "taskstoissues",
+    ]
+
+    def _make_copilot(self):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        return CopilotIntegration()
+
+    def _setup_skills(self, copilot, tmp_path):
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m, parsed_options={"skills": True})
+        return created, m
+
+    # -- Options ----------------------------------------------------------
+
+    def test_options_include_skills_flag(self):
+        copilot = get_integration("copilot")
+        opts = copilot.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
+        assert skills_opts[0].default is False
+
+    # -- Skills directory structure ---------------------------------------
+
+    def test_skills_creates_skill_files(self, tmp_path):
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        assert len(created) > 0
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert len(skill_files) > 0
+        for f in skill_files:
+            assert f.exists()
+            assert f.parent.name.startswith("speckit-")
+
+    def test_skills_directory_under_github_skills(self, tmp_path):
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        skills_dir = tmp_path / ".github" / "skills"
+        assert skills_dir.is_dir()
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        for f in skill_files:
+            assert f.resolve().parent.parent == skills_dir.resolve(), (
+                f"{f} is not under {skills_dir}"
+            )
+
+    def test_skills_directory_structure(self, tmp_path):
+        """Each command produces speckit-<name>/SKILL.md."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        expected_commands = set(self._SKILL_COMMANDS)
+        actual_commands = set()
+        for f in skill_files:
+            skill_dir_name = f.parent.name
+            assert skill_dir_name.startswith("speckit-")
+            actual_commands.add(skill_dir_name.removeprefix("speckit-"))
+        assert actual_commands == expected_commands
+
+    # -- No companion files in skills mode --------------------------------
+
+    def test_skills_no_prompt_md_companions(self, tmp_path):
+        """Skills mode must not generate .prompt.md companion files."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        prompt_files = [f for f in created if f.name.endswith(".prompt.md")]
+        assert prompt_files == []
+        prompts_dir = tmp_path / ".github" / "prompts"
+        if prompts_dir.exists():
+            assert list(prompts_dir.iterdir()) == []
+
+    def test_skills_no_vscode_settings(self, tmp_path):
+        """Skills mode must not create or merge .vscode/settings.json."""
+        copilot = self._make_copilot()
+        self._setup_skills(copilot, tmp_path)
+        settings = tmp_path / ".vscode" / "settings.json"
+        assert not settings.exists()
+
+    def test_skills_no_agent_md_files(self, tmp_path):
+        """Skills mode must not produce .agent.md files."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        agent_files = [f for f in created if f.name.endswith(".agent.md")]
+        assert agent_files == []
+
+    # -- Frontmatter structure --------------------------------------------
+
+    def test_skill_frontmatter_structure(self, tmp_path):
+        """SKILL.md must have name, description, compatibility, metadata."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        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"
+
+    # -- Copilot-specific post-processing ---------------------------------
+
+    def test_post_process_skill_content_does_not_inject_mode(self):
+        """post_process_skill_content() must NOT inject mode: — VS Code Copilot does not support it."""
+        copilot = self._make_copilot()
+        content = (
+            "---\n"
+            'name: "speckit-plan"\n'
+            'description: "Plan workflow"\n'
+            "---\n"
+            "\nBody content\n"
+        )
+        updated = copilot.post_process_skill_content(content)
+        assert "mode:" not in updated
+
+    def test_post_process_skill_content_injects_hook_note(self):
+        """post_process_skill_content() should inject shared hook guidance but not mode:."""
+        copilot = self._make_copilot()
+        content = (
+            "---\n"
+            'name: "speckit-specify"\n'
+            'description: "Specify workflow"\n'
+            "---\n"
+            "\n- For each executable hook, output the following\n"
+        )
+        updated = copilot.post_process_skill_content(content)
+        assert "replace dots" in updated
+        assert "mode:" not in updated
+
+    def test_post_process_idempotent(self):
+        """post_process_skill_content() must be idempotent."""
+        copilot = self._make_copilot()
+        content = (
+            "---\n"
+            'name: "speckit-plan"\n'
+            'description: "Plan workflow"\n'
+            "---\n"
+            "\nBody content\n"
+        )
+        first = copilot.post_process_skill_content(content)
+        second = copilot.post_process_skill_content(first)
+        assert first == second
+
+    def test_skills_do_not_have_mode_in_frontmatter(self, tmp_path):
+        """Generated SKILL.md files must NOT contain mode: — VS Code Copilot does not support it."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert len(skill_files) > 0
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            parts = content.split("---", 2)
+            fm = yaml.safe_load(parts[1])
+            assert "mode" not in fm, f"{f} frontmatter must not contain unsupported 'mode' field"
+
+    def test_skills_hook_sections_explain_dotted_command_conversion(self, tmp_path):
+        """Generated skills with hook sections should include shared hook guidance."""
+        copilot = self._make_copilot()
+        self._setup_skills(copilot, tmp_path)
+        specify_skill = tmp_path / ".github" / "skills" / "speckit-specify" / "SKILL.md"
+        content = specify_skill.read_text(encoding="utf-8")
+        assert "replace dots" in content
+
+    # -- Template processing ----------------------------------------------
+
+    def test_skills_templates_are_processed(self, tmp_path):
+        """Skill body must have placeholders replaced."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        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}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{f.name} has unprocessed __SPECKIT_COMMAND_*__"
+
+    def test_skills_command_refs_use_hyphen(self, tmp_path):
+        """Copilot skills mode must use /speckit-<name> not /speckit.<name>."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert len(skill_files) > 0
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            assert "/speckit." not in content, (
+                f"{f.name} contains dot-notation /speckit. reference; "
+                f"skills mode must use /speckit-<name>"
+            )
+
+    def test_skills_mode_invoke_separator(self):
+        """Copilot effective_invoke_separator should reflect skills mode."""
+        copilot = self._make_copilot()
+        assert copilot.effective_invoke_separator() == "."
+        assert copilot.effective_invoke_separator({"skills": True}) == "-"
+        assert copilot.effective_invoke_separator({"skills": False}) == "."
+
+    def test_skill_body_has_content(self, tmp_path):
+        """Each SKILL.md body should contain template content."""
+        copilot = self._make_copilot()
+        created, _ = self._setup_skills(copilot, tmp_path)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            parts = content.split("---", 2)
+            body = parts[2].strip() if len(parts) >= 3 else ""
+            assert len(body) > 0, f"{f} has empty body"
+
+    def test_plan_skill_has_no_context_placeholder(self, tmp_path):
+        """The core plan skill must not carry a context-file placeholder —
+        agent context files are owned by the opt-in agent-context extension."""
+        copilot = self._make_copilot()
+        self._setup_skills(copilot, tmp_path)
+        plan_file = tmp_path / ".github" / "skills" / "speckit-plan" / "SKILL.md"
+        assert plan_file.exists()
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content
+
+    # -- Manifest tracking ------------------------------------------------
+
+    def test_all_files_tracked_in_manifest(self, tmp_path):
+        copilot = self._make_copilot()
+        created, m = self._setup_skills(copilot, tmp_path)
+        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"
+
+    # -- Install/uninstall roundtrip --------------------------------------
+
+    def test_install_uninstall_roundtrip(self, tmp_path):
+        copilot = self._make_copilot()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.install(tmp_path, m, parsed_options={"skills": True})
+        assert len(created) > 0
+        m.save()
+        for f in created:
+            assert f.exists()
+        removed, skipped = copilot.uninstall(tmp_path, m)
+        assert len(removed) == len(created)
+        assert skipped == []
+
+    def test_modified_file_survives_uninstall(self, tmp_path):
+        copilot = self._make_copilot()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.install(tmp_path, m, parsed_options={"skills": True})
+        m.save()
+        modified_file = created[0]
+        modified_file.write_text("user modified this", encoding="utf-8")
+        removed, skipped = copilot.uninstall(tmp_path, m)
+        assert modified_file.exists()
+        assert modified_file in skipped
+
+    # -- build_command_invocation -----------------------------------------
+
+    def test_build_command_invocation_skills_mode(self):
+        copilot = self._make_copilot()
+        copilot._skills_mode = True
+        assert copilot.build_command_invocation("speckit.plan") == "/speckit-plan"
+        assert copilot.build_command_invocation("plan") == "/speckit-plan"
+        assert copilot.build_command_invocation("plan", "my args") == "/speckit-plan my args"
+
+    def test_build_command_invocation_skills_extension_command(self):
+        copilot = self._make_copilot()
+        copilot._skills_mode = True
+        assert copilot.build_command_invocation("speckit.git.commit") == "/speckit-git-commit"
+        assert copilot.build_command_invocation("git.commit") == "/speckit-git-commit"
+
+    def test_build_command_invocation_default_mode(self):
+        copilot = self._make_copilot()
+        assert copilot.build_command_invocation("plan", "my args") == "my args"
+        assert copilot.build_command_invocation("plan") == ""
+
+    # -- Context section ---------------------------------------------------
+
+    def test_skills_setup_does_not_write_context_section(self, tmp_path):
+        copilot = self._make_copilot()
+        self._setup_skills(copilot, tmp_path)
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text
+
+    # -- CLI integration test ---------------------------------------------
+
+    def test_init_with_integration_options_skills(self, tmp_path):
+        """specify init --integration copilot --integration-options='--skills' scaffolds skills."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "copilot-skills"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "copilot",
+                "--integration-options", "--skills",
+                "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init failed: {result.output}"
+        skills_dir = project / ".github" / "skills"
+        assert skills_dir.is_dir(), "Skills directory was not created"
+        plan_skill = skills_dir / "speckit-plan" / "SKILL.md"
+        assert plan_skill.exists(), "speckit-plan/SKILL.md not found"
+        # Verify no default-mode artifacts
+        assert not (project / ".github" / "agents").exists()
+        assert not (project / ".github" / "prompts").exists()
+        assert not (project / ".vscode" / "settings.json").exists()
+
+    def test_complete_file_inventory_skills_sh(self, tmp_path):
+        """Every file produced by specify init --integration copilot --integration-options='--skills' --script sh."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "inventory-skills-sh"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "copilot",
+                "--integration-options", "--skills",
+                "--script", "sh",
+            ], 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() and ".git" not in p.parts)
+        expected = sorted([
+            # Skill files (core commands)
+            *[f".github/skills/speckit-{cmd}/SKILL.md" for cmd in self._SKILL_COMMANDS],
+            # Integration metadata
+            ".specify/init-options.json",
+            ".specify/integration.json",
+            ".specify/integrations/copilot.manifest.json",
+            ".specify/integrations/speckit.manifest.json",
+            # Scripts (sh)
+            ".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/setup-tasks.sh",
+            # Templates
+            ".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",
+            ".specify/memory/constitution.md",
+            # Bundled workflow
+            ".specify/workflows/speckit/workflow.yml",
+            ".specify/workflows/workflow-registry.json",
+        ])
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )
+
+    # -- Singleton leak: _skills_mode must reset --------------------------
+
+    def test_skills_mode_resets_on_default_setup(self, tmp_path):
+        """setup() with skills=True then without must reset _skills_mode."""
+        copilot = self._make_copilot()
+
+        # First call: skills mode
+        (tmp_path / "proj1").mkdir()
+        m1 = IntegrationManifest("copilot", tmp_path / "proj1")
+        copilot.setup(tmp_path / "proj1", m1, parsed_options={"skills": True})
+        assert copilot._skills_mode is True
+
+        # Second call: default mode (no skills option)
+        (tmp_path / "proj2").mkdir()
+        m2 = IntegrationManifest("copilot", tmp_path / "proj2")
+        copilot.setup(tmp_path / "proj2", m2)
+        assert copilot._skills_mode is False
+
+        # build_command_invocation must use default (dotted) mode
+        assert copilot.build_command_invocation("plan", "args") == "args"
+
+    # -- Auto-detection must ignore unrelated .github/skills/ -------------
+
+    def test_dispatch_ignores_unrelated_skills_directory(self, tmp_path):
+        """dispatch_command() must not treat unrelated .github/skills/ as skills mode."""
+        copilot = self._make_copilot()
+        # Create a .github/skills/ with non-speckit content (e.g. GitHub Skills training)
+        unrelated = tmp_path / ".github" / "skills" / "introduction-to-github"
+        unrelated.mkdir(parents=True)
+        (unrelated / "README.md").write_text("# GitHub Skills training\n")
+
+        # Should NOT detect skills mode — cli_args should contain --agent
+        import unittest.mock as mock
+        with mock.patch("subprocess.run") as mock_run:
+            mock_run.return_value = mock.Mock(returncode=0, stdout="", stderr="")
+            copilot.dispatch_command("plan", "my args", project_root=tmp_path, stream=False)
+            call_args = mock_run.call_args[0][0]
+            assert "--agent" in call_args, (
+                f"Expected --agent in cli_args but got: {call_args}"
+            )
+            assert "speckit.plan" in call_args
+
+    def test_dispatch_detects_speckit_skills_layout(self, tmp_path):
+        """dispatch_command() detects speckit-*/SKILL.md as skills mode."""
+        copilot = self._make_copilot()
+        skill_dir = tmp_path / ".github" / "skills" / "speckit-plan"
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "SKILL.md").write_text("---\nname: speckit-plan\n---\n")
+
+        import unittest.mock as mock
+        with mock.patch("subprocess.run") as mock_run:
+            mock_run.return_value = mock.Mock(returncode=0, stdout="", stderr="")
+            copilot.dispatch_command("plan", "my args", project_root=tmp_path, stream=False)
+            call_args = mock_run.call_args[0][0]
+            assert "--agent" not in call_args, (
+                f"Skills mode should not use --agent, got: {call_args}"
+            )
+            prompt = call_args[call_args.index("-p") + 1]
+            assert "/speckit-plan" in prompt, (
+                f"Skills mode prompt should invoke /speckit-plan, got: {prompt}"
+            )
+            assert "my args" in prompt, (
+                f"Skills mode prompt should preserve user args, got: {prompt}"
+            )
+
+    # -- Next-steps display for Copilot skills mode -----------------------
+
+    def test_init_skills_next_steps_show_skill_syntax(self, tmp_path):
+        """specify init --integration copilot --integration-options='--skills' shows /speckit-plan not /speckit.plan."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "copilot-nextsteps"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "copilot",
+                "--integration-options", "--skills",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init failed: {result.output}"
+        # Skills mode should show /speckit-plan (hyphenated)
+        assert "/speckit-plan" in result.output, (
+            f"Expected /speckit-plan in next steps but got:\n{result.output}"
+        )
+        # Must NOT show the dotted /speckit.plan form
+        assert "/speckit.plan" not in result.output, (
+            f"Should not show /speckit.plan in skills mode:\n{result.output}"
+        )

tests/integrations/test_integration_cursor_agent.py

@@ -0,0 +1,233 @@
+"""Tests for CursorAgentIntegration."""
+
+from urllib.parse import urlparse
+
+from specify_cli.integrations import get_integration
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestCursorAgentIntegration(SkillsIntegrationTests):
+    KEY = "cursor-agent"
+    FOLDER = ".cursor/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".cursor/skills"
+
+
+class TestCursorAgentInitFlow:
+    """--integration cursor-agent creates expected files."""
+
+    def test_integration_cursor_agent_creates_skills(self, tmp_path):
+        """--integration cursor-agent should create skills in .cursor/skills."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        target = tmp_path / "test-proj"
+        result = runner.invoke(app, ["init", str(target), "--integration", "cursor-agent", "--ignore-agent-tools", "--script", "sh"])
+
+        assert result.exit_code == 0, f"init --integration cursor-agent failed: {result.output}"
+        assert (target / ".cursor" / "skills" / "speckit-plan" / "SKILL.md").exists()
+
+
+class TestCursorAgentCliDispatch:
+    """Verify the CLI dispatch path for cursor-agent (issue #2629).
+
+    The ``cursor-agent`` CLI supports headless execution via ``-p`` (with
+    full tool access including write/shell) and requires ``--trust`` to
+    bypass the Workspace Trust prompt.  These tests pin the exact argv
+    shape that the workflow runner will use.
+    """
+
+    def test_requires_cli_is_false_for_ide_first_flow(self):
+        """``requires_cli`` must stay False so the IDE-only flow keeps working.
+
+        ``specify init --integration cursor-agent`` (without ``--ignore-agent-tools``)
+        treats ``requires_cli=True`` as a hard precheck and fails when the
+        ``cursor-agent`` CLI isn't on PATH — even though the Cursor IDE
+        / skills flow can run without it.  Workflow dispatch support is
+        signalled by overriding ``build_exec_args()`` instead, mirroring
+        ``CopilotIntegration``.
+        """
+        i = get_integration("cursor-agent")
+        assert i.config.get("requires_cli") is False
+
+    def test_install_url_is_set(self):
+        i = get_integration("cursor-agent")
+        url = i.config.get("install_url")
+        assert url is not None
+        # CodeQL: use a hostname comparison instead of a substring check
+        # to avoid the "Incomplete URL substring sanitization" warning
+        # (substring "cursor.com" can also appear in attacker-controlled
+        # positions of an arbitrary URL).
+        host = (urlparse(url).hostname or "").lower()
+        assert host == "cursor.com" or host.endswith(".cursor.com")
+
+    def test_build_exec_args_default_includes_headless_flags_and_json(self):
+        """Default argv emits the full headless flag set: -p --trust
+        --approve-mcps --force, then prompt, then --output-format json.
+        """
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args("/speckit-specify some-feature")
+        assert args == [
+            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
+            "/speckit-specify some-feature",
+            "--output-format", "json",
+        ]
+
+    def test_build_exec_args_text_output_omits_format(self):
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args("/speckit-plan", output_json=False)
+        assert args == [
+            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
+            "/speckit-plan",
+        ]
+
+    def test_build_exec_args_with_model(self):
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args(
+            "/speckit-specify", model="sonnet-4-thinking", output_json=False
+        )
+        assert args == [
+            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
+            "/speckit-specify",
+            "--model", "sonnet-4-thinking",
+        ]
+
+    def test_build_exec_args_contains_mandatory_headless_flags(self):
+        """The four headless flags must always appear together.
+
+        ``--approve-mcps`` is required so MCP servers (e.g. dingtalk-doc)
+        actually load in headless mode; ``--force`` is required so the
+        agent doesn't block on tool-call approval prompts during the
+        speckit workflow.  Together with ``-p`` and ``--trust`` they
+        bring cursor-agent's headless behaviour in line with
+        ``claude -p`` / ``codex --exec`` from spec-kit's perspective.
+        """
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args("/speckit-implement", output_json=False)
+        for flag in ("-p", "--trust", "--approve-mcps", "--force"):
+            assert flag in args, f"missing mandatory headless flag: {flag}"
+
+    def test_build_exec_args_supports_dispatch_without_requires_cli(self):
+        """``build_exec_args`` must return argv even though ``requires_cli``
+        is ``False``.
+
+        ``CursorAgentIntegration`` opts out of the ``requires_cli`` hard
+        precheck (so ``specify init`` doesn't fail when the CLI isn't on
+        PATH) but still supports workflow dispatch.  The presence of a
+        non-``None`` argv from ``build_exec_args()`` is what the engine
+        keys off — pin that invariant.
+        """
+        i = get_integration("cursor-agent")
+        assert i.config.get("requires_cli") is False
+        argv = i.build_exec_args("/speckit-plan", output_json=False)
+        assert argv is not None
+        assert argv[0] == "cursor-agent"
+
+    def test_build_exec_args_honors_executable_override(self, monkeypatch):
+        """``SPECKIT_INTEGRATION_CURSOR_AGENT_EXECUTABLE`` overrides argv[0].
+
+        Every other CLI-dispatch integration (codex, devin, ...) routes
+        argv[0] through ``_resolve_executable()`` so operators can pin a
+        binary path (issue #2596). cursor-agent hardcoded ``self.key`` and
+        silently ignored the documented override.
+        """
+        monkeypatch.setenv(
+            "SPECKIT_INTEGRATION_CURSOR_AGENT_EXECUTABLE", "/custom/cursor"
+        )
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args("/speckit-plan", output_json=False)
+        assert args[0] == "/custom/cursor"
+        # The mandatory headless flags must still be present.
+        for flag in ("-p", "--trust", "--approve-mcps", "--force"):
+            assert flag in args
+
+    def test_build_exec_args_honors_extra_args_override(self, monkeypatch):
+        """``SPECKIT_INTEGRATION_CURSOR_AGENT_EXTRA_ARGS`` flags are injected
+        *before* Spec Kit's canonical ``--model`` / ``--output-format`` flags.
+
+        The ``_apply_extra_args_env_var()`` hook (issue #2595) was never
+        invoked by cursor-agent, so operator-supplied flags were dropped.
+        Insertion order is the real contract: extra args must land after the
+        mandatory headless flags but before ``--model`` / ``--output-format``,
+        so they cannot clobber, displace, or reorder Spec Kit's canonical
+        trailing flags. Exercise with both a model and JSON output so both
+        canonical flags are present to pin against.
+        """
+        monkeypatch.setenv(
+            "SPECKIT_INTEGRATION_CURSOR_AGENT_EXTRA_ARGS", "--foo bar"
+        )
+        i = get_integration("cursor-agent")
+        args = i.build_exec_args(
+            "/speckit-plan", model="sonnet-4-thinking", output_json=True
+        )
+        assert "--foo" in args
+        assert "bar" in args
+        # "bar" is the value of "--foo": the tokens stay adjacent and in order.
+        assert args.index("bar") == args.index("--foo") + 1
+        # Extra args are inserted before the canonical flags, so they cannot
+        # clobber or reorder them (the behavioral contract this test guards).
+        assert args.index("--foo") < args.index("--model")
+        assert args.index("--foo") < args.index("--output-format")
+        # The canonical flags themselves remain intact and correctly paired.
+        assert args[args.index("--model") + 1] == "sonnet-4-thinking"
+        assert args[args.index("--output-format") + 1] == "json"
+
+    def test_build_command_invocation_uses_hyphenated_skill_name(self):
+        """SkillsIntegration: /speckit-plan (not /speckit.plan)."""
+        i = get_integration("cursor-agent")
+        assert i.build_command_invocation("speckit.plan", "feature-x") == "/speckit-plan feature-x"
+        assert i.build_command_invocation("plan") == "/speckit-plan"
+
+    def test_dispatch_command_resolves_cmd_shim_for_subprocess(self):
+        """``.cmd`` shims must be resolved to their full path before ``subprocess.run``.
+
+        ``cursor-agent`` (and other npm-installed CLIs on Windows) ship as
+        ``cursor-agent.cmd`` wrappers.  ``shutil.which`` honors ``PATHEXT``
+        and finds them, but Python's ``subprocess.run`` calls
+        ``CreateProcess`` which does **not** consult ``PATHEXT`` and fails
+        with ``WinError 2`` on a bare ``["cursor-agent", ...]`` argv.  The
+        fix in ``base.py::dispatch_command`` resolves ``exec_args[0]`` via
+        ``shutil.which`` so the full ``.cmd`` path is what reaches
+        ``CreateProcess``.
+        """
+        from unittest.mock import patch, MagicMock
+        i = get_integration("cursor-agent")
+
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = "ok"
+        mock_result.stderr = ""
+
+        fake_path = r"C:\Users\foo\AppData\Local\cursor-agent\cursor-agent.CMD"
+        with patch(
+            "specify_cli.integrations.base.shutil.which", return_value=fake_path
+        ), patch("subprocess.run", return_value=mock_result) as mock_run:
+            result = i.dispatch_command(
+                "speckit.plan", args="feature-x", stream=False, timeout=5
+            )
+
+        assert result["exit_code"] == 0
+        argv = mock_run.call_args[0][0]
+        assert argv[0] == fake_path, f"expected resolved .CMD path, got: {argv[0]!r}"
+        assert argv[1:6] == ["-p", "--trust", "--approve-mcps", "--force", "/speckit-plan feature-x"]
+
+    def test_dispatch_command_passthrough_when_shutil_which_finds_nothing(self):
+        """If ``shutil.which`` returns ``None``, leave argv unchanged so the
+        existing ``FileNotFoundError`` path remains observable to callers."""
+        from unittest.mock import patch, MagicMock
+        i = get_integration("cursor-agent")
+
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = ""
+        mock_result.stderr = ""
+
+        with patch(
+            "specify_cli.integrations.base.shutil.which", return_value=None
+        ), patch("subprocess.run", return_value=mock_result) as mock_run:
+            i.dispatch_command("speckit.plan", stream=False, timeout=5)
+
+        argv = mock_run.call_args[0][0]
+        assert argv[0] == "cursor-agent"

tests/integrations/test_integration_devin.py

@@ -0,0 +1,74 @@
+"""Tests for DevinIntegration."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestDevinIntegration(SkillsIntegrationTests):
+    KEY = "devin"
+    FOLDER = ".devin/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".devin/skills"
+
+
+class TestDevinBuildExecArgs:
+    """Regression tests for DevinIntegration.build_exec_args.
+
+    Devin's CLI has no --output-format flag, so build_exec_args must
+    omit it regardless of the output_json argument. The integration
+    must also remain dispatchable (must not return None, which is the
+    codebase's IDE-only sentinel checked by CommandStep).
+    """
+
+    def test_returns_args_not_none_for_dispatch(self):
+        """Devin is CLI-dispatchable; build_exec_args must not return None."""
+        from specify_cli.integrations.devin import DevinIntegration
+
+        impl = DevinIntegration()
+        args = impl.build_exec_args("test prompt")
+        assert args is not None, (
+            "DevinIntegration.build_exec_args must not return None. "
+            "None is the codebase sentinel for IDE-only integrations "
+            "(see KilocodeIntegration); Devin is dispatchable via 'devin -p'."
+        )
+        assert args[:3] == ["devin", "-p", "test prompt"]
+
+    def test_output_json_does_not_emit_output_format_flag(self):
+        """Devin has no --output-format flag; output_json=True must not add it."""
+        from specify_cli.integrations.devin import DevinIntegration
+
+        impl = DevinIntegration()
+        args_json = impl.build_exec_args("hello", output_json=True)
+        args_text = impl.build_exec_args("hello", output_json=False)
+
+        assert "--output-format" not in args_json
+        assert "json" not in args_json[3:]
+        # The two should be identical: output_json is documented as having
+        # no effect on the command line for Devin (plain-text stdout).
+        assert args_json == args_text
+
+    def test_model_flag_passed_through(self):
+        """--model is supported and should appear when provided."""
+        from specify_cli.integrations.devin import DevinIntegration
+
+        impl = DevinIntegration()
+        args = impl.build_exec_args("hi", model="claude-sonnet-4")
+        assert args == ["devin", "-p", "hi", "--model", "claude-sonnet-4"]
+
+
+class TestDevinInitFlow:
+    """--integration devin creates expected files."""
+
+    def test_integration_devin_creates_skills(self, tmp_path):
+        """--integration devin should create skills directory."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        target = tmp_path / "test-proj"
+        result = runner.invoke(
+            app,
+            ["init", str(target), "--integration", "devin", "--ignore-agent-tools", "--script", "sh"],
+        )
+
+        assert result.exit_code == 0, f"init --integration devin failed: {result.output}"
+        assert (target / ".devin" / "skills" / "speckit-plan" / "SKILL.md").exists()

tests/integrations/test_integration_firebender.py

@@ -0,0 +1,44 @@
+"""Tests for FirebenderIntegration."""
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestFirebenderIntegration(MarkdownIntegrationTests):
+    KEY = "firebender"
+    FOLDER = ".firebender/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".firebender/commands"
+
+    # Firebender reads custom slash commands from ``.firebender/commands/*.mdc``,
+    # so this integration uses the ``.mdc`` extension instead of the ``.md``
+    # default the base mixin assumes. Override the two extension-specific tests.
+    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"] == ".mdc"
+
+    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
+        cmd_files = [f for f in created if "scripts" not in f.parts]
+        for f in cmd_files:
+            assert f.exists()
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".mdc")
+
+    def _expected_files(self, script_variant: str) -> list[str]:
+        # Firebender emits ``.mdc`` command files, so remap the base mixin's
+        # ``.md`` expectations for files under this integration's command dir.
+        cmd_dir = get_integration(self.KEY).registrar_config["dir"]
+        prefix = cmd_dir + "/"
+        return sorted(
+            f[:-3] + ".mdc" if f.startswith(prefix) and f.endswith(".md") else f
+            for f in super()._expected_files(script_variant)
+        )

tests/integrations/test_integration_forge.py

@@ -0,0 +1,477 @@
+"""Tests for ForgeIntegration."""
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+from specify_cli.integrations.forge import format_forge_command_name
+
+
+class TestForgeCommandNameFormatter:
+    """Test the centralized Forge command name formatter."""
+
+    def test_simple_name_without_prefix(self):
+        """Test formatting a simple name without 'speckit.' prefix."""
+        assert format_forge_command_name("plan") == "speckit-plan"
+        assert format_forge_command_name("tasks") == "speckit-tasks"
+        assert format_forge_command_name("specify") == "speckit-specify"
+
+    def test_name_with_speckit_prefix(self):
+        """Test formatting a name that already has 'speckit.' prefix."""
+        assert format_forge_command_name("speckit.plan") == "speckit-plan"
+        assert format_forge_command_name("speckit.tasks") == "speckit-tasks"
+
+    def test_extension_command_name(self):
+        """Test formatting extension command names with dots."""
+        assert format_forge_command_name("speckit.my-extension.example") == "speckit-my-extension-example"
+        assert format_forge_command_name("my-extension.example") == "speckit-my-extension-example"
+
+    def test_complex_nested_name(self):
+        """Test formatting deeply nested command names."""
+        assert format_forge_command_name("speckit.jira.sync-status") == "speckit-jira-sync-status"
+        assert format_forge_command_name("speckit.foo.bar.baz") == "speckit-foo-bar-baz"
+
+    def test_name_with_hyphens_preserved(self):
+        """Test that existing hyphens are preserved."""
+        assert format_forge_command_name("my-extension") == "speckit-my-extension"
+        assert format_forge_command_name("speckit.my-ext.test-cmd") == "speckit-my-ext-test-cmd"
+
+    def test_alias_formatting(self):
+        """Test formatting alias names."""
+        assert format_forge_command_name("speckit.my-extension.example-short") == "speckit-my-extension-example-short"
+
+    def test_idempotent_already_hyphenated(self):
+        """Test that already-hyphenated names are returned unchanged (idempotent)."""
+        assert format_forge_command_name("speckit-plan") == "speckit-plan"
+        assert format_forge_command_name("speckit-my-extension-example") == "speckit-my-extension-example"
+        assert format_forge_command_name("speckit-jira-sync-status") == "speckit-jira-sync-status"
+
+
+class TestForgeIntegration:
+    def test_forge_key_and_config(self):
+        forge = get_integration("forge")
+        assert forge is not None
+        assert forge.key == "forge"
+        assert forge.config["folder"] == ".forge/"
+        assert forge.config["commands_subdir"] == "commands"
+        assert forge.config["requires_cli"] is True
+        assert forge.registrar_config["args"] == "{{parameters}}"
+        assert forge.registrar_config["extension"] == ".md"
+
+    def test_command_filename_md(self):
+        forge = get_integration("forge")
+        assert forge.command_filename("plan") == "speckit.plan.md"
+
+    def test_setup_creates_md_files(self, tmp_path):
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        created = forge.setup(tmp_path, m)
+        assert len(created) > 0
+        # Separate command files from scripts
+        command_files = [f for f in created if f.parent == tmp_path / ".forge" / "commands"]
+        assert len(command_files) > 0
+        for f in command_files:
+            assert f.name.endswith(".md")
+
+    def test_setup_does_not_write_context_section(self, tmp_path):
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text
+
+    def test_all_created_files_tracked_in_manifest(self, tmp_path):
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        created = forge.setup(tmp_path, m)
+        for f in created:
+            rel = f.resolve().relative_to(tmp_path.resolve()).as_posix()
+            assert rel in m.files, f"Created file {rel} not tracked in manifest"
+
+    def test_install_uninstall_roundtrip(self, tmp_path):
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        created = forge.install(tmp_path, m)
+        assert len(created) > 0
+        m.save()
+        for f in created:
+            assert f.exists()
+        removed, skipped = forge.uninstall(tmp_path, m)
+        assert len(removed) == len(created)
+        assert skipped == []
+
+    def test_modified_file_survives_uninstall(self, tmp_path):
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        created = forge.install(tmp_path, m)
+        m.save()
+        # Modify a command file (not a script)
+        command_files = [f for f in created if f.parent == tmp_path / ".forge" / "commands"]
+        modified_file = command_files[0]
+        modified_file.write_text("user modified this", encoding="utf-8")
+        removed, skipped = forge.uninstall(tmp_path, m)
+        assert modified_file.exists()
+        assert modified_file in skipped
+
+    def test_directory_structure(self, tmp_path):
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        commands_dir = tmp_path / ".forge" / "commands"
+        assert commands_dir.is_dir()
+
+        # Derive expected command names from the Forge command templates so the test
+        # stays in sync if templates are added/removed.
+        templates = forge.list_command_templates()
+        expected_commands = {t.stem for t in templates}
+        assert len(expected_commands) > 0, "No command templates found"
+
+        # Check generated files match templates
+        command_files = sorted(commands_dir.glob("speckit.*.md"))
+        assert len(command_files) == len(expected_commands)
+        actual_commands = {f.name.removeprefix("speckit.").removesuffix(".md") for f in command_files}
+        assert actual_commands == expected_commands
+
+    def test_templates_are_processed(self, tmp_path):
+        import re
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        commands_dir = tmp_path / ".forge" / "commands"
+        for cmd_file in commands_dir.glob("speckit.*.md"):
+            content = cmd_file.read_text(encoding="utf-8")
+            # Check standard replacements
+            assert "{SCRIPT}" not in content, f"{cmd_file.name} has unprocessed {{SCRIPT}}"
+            assert "__AGENT__" not in content, f"{cmd_file.name} has unprocessed __AGENT__"
+            assert "{ARGS}" not in content, f"{cmd_file.name} has unprocessed {{ARGS}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{cmd_file.name} has unprocessed __SPECKIT_COMMAND_*__"
+            # Check Forge-specific: $ARGUMENTS should be replaced with {{parameters}}
+            assert "$ARGUMENTS" not in content, f"{cmd_file.name} has unprocessed $ARGUMENTS"
+            # Frontmatter sections should be stripped
+            assert "\nscripts:\n" not in content
+            # Check Forge-specific: command references use hyphen notation, not dot notation
+            assert not re.search(r"/speckit\.[a-z]", content), (
+                f"{cmd_file.name} contains dot-notation command reference (/speckit.<cmd>); "
+                "Forge requires hyphen notation (/speckit-<cmd>) for ZSH compatibility"
+            )
+
+    def test_plan_command_has_no_context_placeholder(self, tmp_path):
+        """The core plan command must not carry a context-file placeholder —
+        agent context files are owned by the opt-in agent-context extension."""
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        plan_file = tmp_path / ".forge" / "commands" / "speckit.plan.md"
+        assert plan_file.exists()
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content
+
+    def test_forge_specific_transformations(self, tmp_path):
+        """Test Forge-specific processing: name injection and handoffs stripping."""
+        from specify_cli.integrations.forge import ForgeIntegration
+        from specify_cli.agents import CommandRegistrar
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        commands_dir = tmp_path / ".forge" / "commands"
+
+        registrar = CommandRegistrar()
+        for cmd_file in commands_dir.glob("speckit.*.md"):
+            content = cmd_file.read_text(encoding="utf-8")
+            frontmatter, _ = registrar.parse_frontmatter(content)
+
+            # Check that name field is injected in frontmatter
+            assert "name" in frontmatter, f"{cmd_file.name} missing injected 'name' field in frontmatter"
+
+            # Check that handoffs frontmatter key is stripped
+            assert "handoffs" not in frontmatter, f"{cmd_file.name} has unstripped 'handoffs' key in frontmatter"
+
+    def test_uses_parameters_placeholder(self, tmp_path):
+        """Verify Forge replaces $ARGUMENTS with {{parameters}} in generated files."""
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+
+        # The registrar_config should specify {{parameters}}
+        assert forge.registrar_config["args"] == "{{parameters}}"
+
+        # Generate files and verify $ARGUMENTS is replaced with {{parameters}}
+        from specify_cli.integrations.manifest import IntegrationManifest
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        commands_dir = tmp_path / ".forge" / "commands"
+
+        # Check all generated command files
+        for cmd_file in commands_dir.glob("speckit.*.md"):
+            content = cmd_file.read_text(encoding="utf-8")
+            # $ARGUMENTS should be replaced with {{parameters}}
+            assert "$ARGUMENTS" not in content, (
+                f"{cmd_file.name} still contains $ARGUMENTS - it should be replaced with {{{{parameters}}}}"
+            )
+            # At least some files should have {{parameters}} (those with user input sections)
+            # We'll check the checklist file specifically as it has a User Input section
+
+        # Verify checklist specifically has {{parameters}} in the User Input section
+        checklist = commands_dir / "speckit.checklist.md"
+        if checklist.exists():
+            content = checklist.read_text(encoding="utf-8")
+            assert "{{parameters}}" in content, (
+                "checklist should contain {{parameters}} in User Input section"
+            )
+
+    def test_command_refs_use_hyphen_notation(self, tmp_path):
+        """Verify all generated Forge command files use /speckit-foo, not /speckit.foo."""
+        import re
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        commands_dir = tmp_path / ".forge" / "commands"
+
+        files_with_refs = []
+        files_with_dot_refs = []
+        for cmd_file in commands_dir.glob("speckit.*.md"):
+            content = cmd_file.read_text(encoding="utf-8")
+            if re.search(r"/speckit-[a-z]", content):
+                files_with_refs.append(cmd_file.name)
+            if re.search(r"/speckit\.[a-z]", content):
+                files_with_dot_refs.append(cmd_file.name)
+
+        assert files_with_dot_refs == [], (
+            f"Files contain dot-notation command references: {files_with_dot_refs}. "
+            "Forge requires hyphen notation (/speckit-<cmd>) for ZSH compatibility."
+        )
+        assert len(files_with_refs) > 0, (
+            "Expected at least one generated Forge command to contain /speckit-<cmd> reference, "
+            "but none were found. Check that __SPECKIT_COMMAND_*__ tokens are being resolved."
+        )
+
+    def test_name_field_uses_hyphenated_format(self, tmp_path):
+        """Verify that injected name fields use hyphenated format (speckit-plan, not speckit.plan)."""
+        from specify_cli.integrations.forge import ForgeIntegration
+        from specify_cli.agents import CommandRegistrar
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        commands_dir = tmp_path / ".forge" / "commands"
+
+        # Check that name fields use hyphenated format
+        registrar = CommandRegistrar()
+        for cmd_file in commands_dir.glob("speckit.*.md"):
+            content = cmd_file.read_text(encoding="utf-8")
+            # Extract the name field from frontmatter using the parser
+            frontmatter, _ = registrar.parse_frontmatter(content)
+            assert "name" in frontmatter, (
+                f"{cmd_file.name} missing injected 'name' field in frontmatter"
+            )
+            name_value = frontmatter["name"]
+            # Name should use hyphens, not dots
+            assert "." not in name_value, (
+                f"{cmd_file.name} has name field with dots: {name_value} "
+                f"(should use hyphens for Forge/ZSH compatibility)"
+            )
+            assert name_value.startswith("speckit-"), (
+                f"{cmd_file.name} name field should start with 'speckit-': {name_value}"
+            )
+
+
+class TestForgeCommandRegistrar:
+    """Test CommandRegistrar's Forge-specific name formatting."""
+
+    def test_registrar_formats_extension_command_names_for_forge(self, tmp_path):
+        """Verify CommandRegistrar converts dot notation to hyphens for Forge."""
+        from specify_cli.agents import CommandRegistrar
+
+        # Create a mock extension command file
+        ext_dir = tmp_path / "extension"
+        ext_dir.mkdir()
+        cmd_dir = ext_dir / "commands"
+        cmd_dir.mkdir()
+
+        # Create a test command with dot notation name
+        cmd_file = cmd_dir / "example.md"
+        cmd_file.write_text(
+            "---\n"
+            "description: Test extension command\n"
+            "---\n\n"
+            "Test content with $ARGUMENTS\n",
+            encoding="utf-8"
+        )
+
+        # Register with Forge
+        registrar = CommandRegistrar()
+        commands = [
+            {
+                "name": "speckit.my-extension.example",
+                "file": "commands/example.md"
+            }
+        ]
+
+        registered = registrar.register_commands(
+            "forge",
+            commands,
+            "test-extension",
+            ext_dir,
+            tmp_path
+        )
+
+        # Verify registration succeeded
+        assert "speckit.my-extension.example" in registered
+
+        # Check the generated file has hyphenated name in frontmatter
+        forge_cmd = tmp_path / ".forge" / "commands" / "speckit-my-extension-example.md"
+        assert forge_cmd.exists()
+
+        content = forge_cmd.read_text(encoding="utf-8")
+        # Parse frontmatter to validate name field precisely
+        frontmatter, _ = registrar.parse_frontmatter(content)
+        assert "name" in frontmatter, "name field should be injected in frontmatter"
+        # Name field should use hyphens, not dots
+        assert frontmatter["name"] == "speckit-my-extension-example"
+
+    def test_registrar_formats_alias_names_for_forge(self, tmp_path):
+        """Verify CommandRegistrar converts alias names to hyphens for Forge."""
+        from specify_cli.agents import CommandRegistrar
+
+        # Create a mock extension command file
+        ext_dir = tmp_path / "extension"
+        ext_dir.mkdir()
+        cmd_dir = ext_dir / "commands"
+        cmd_dir.mkdir()
+
+        cmd_file = cmd_dir / "example.md"
+        cmd_file.write_text(
+            "---\n"
+            "description: Test command with alias\n"
+            "---\n\n"
+            "Test content\n",
+            encoding="utf-8"
+        )
+
+        # Register with Forge including an alias
+        registrar = CommandRegistrar()
+        commands = [
+            {
+                "name": "speckit.my-extension.example",
+                "file": "commands/example.md",
+                "aliases": ["speckit.my-extension.ex"]
+            }
+        ]
+
+        registrar.register_commands(
+            "forge",
+            commands,
+            "test-extension",
+            ext_dir,
+            tmp_path
+        )
+
+        # Check the alias file has hyphenated name in frontmatter
+        alias_file = tmp_path / ".forge" / "commands" / "speckit-my-extension-ex.md"
+        assert alias_file.exists()
+
+        content = alias_file.read_text(encoding="utf-8")
+        # Parse frontmatter to validate alias name field precisely
+        frontmatter, _ = registrar.parse_frontmatter(content)
+        assert "name" in frontmatter, "name field should be injected in alias frontmatter"
+        # Alias name field should also use hyphens
+        assert frontmatter["name"] == "speckit-my-extension-ex"
+
+    def test_registrar_does_not_affect_other_agents(self, tmp_path):
+        """Verify format_name callback is Forge-specific and doesn't affect other agents."""
+        from specify_cli.agents import CommandRegistrar
+
+        # Create a mock extension command file
+        ext_dir = tmp_path / "extension"
+        ext_dir.mkdir()
+        cmd_dir = ext_dir / "commands"
+        cmd_dir.mkdir()
+
+        cmd_file = cmd_dir / "example.md"
+        cmd_file.write_text(
+            "---\n"
+            "description: Test command\n"
+            "---\n\n"
+            "Test content with $ARGUMENTS\n",
+            encoding="utf-8"
+        )
+
+        # Register with Kilo Code (standard markdown agent without inject_name)
+        registrar = CommandRegistrar()
+        commands = [
+            {
+                "name": "speckit.my-extension.example",
+                "file": "commands/example.md"
+            }
+        ]
+
+        registrar.register_commands(
+            "kilocode",
+            commands,
+            "test-extension",
+            ext_dir,
+            tmp_path
+        )
+
+        # Kilo Code uses standard markdown format without name injection.
+        # The format_name callback should not be invoked for non-Forge agents.
+        kilocode_cmd = tmp_path / ".kilocode" / "workflows" / "speckit.my-extension.example.md"
+        assert kilocode_cmd.exists()
+
+        content = kilocode_cmd.read_text(encoding="utf-8")
+        # Kilo Code should NOT have a name field injected
+        assert "name:" not in content, (
+            "Kilo Code should not inject name field - format_name callback should be Forge-only"
+        )
+
+    def test_git_extension_command_uses_hyphen_notation(self, tmp_path):
+        """Verify the git extension's feature command uses /speckit-specify (not /speckit.specify) for Forge."""
+        from pathlib import Path
+        from specify_cli.agents import CommandRegistrar
+
+        # Locate the real git extension command source file
+        repo_root = Path(__file__).resolve().parent.parent.parent
+        ext_dir = repo_root / "extensions" / "git"
+        cmd_source = ext_dir / "commands" / "speckit.git.feature.md"
+        assert cmd_source.exists(), (
+            f"Git extension command source not found at {cmd_source}. "
+            "Ensure extensions/git/commands/speckit.git.feature.md exists."
+        )
+
+        registrar = CommandRegistrar()
+        commands = [
+            {
+                "name": "speckit.git.feature",
+                "file": "commands/speckit.git.feature.md",
+            }
+        ]
+
+        registered = registrar.register_commands(
+            "forge",
+            commands,
+            "git",
+            ext_dir,
+            tmp_path,
+        )
+
+        assert "speckit.git.feature" in registered
+
+        forge_cmd = tmp_path / ".forge" / "commands" / "speckit-git-feature.md"
+        assert forge_cmd.exists(), "Expected Forge command file was not created"
+
+        content = forge_cmd.read_text(encoding="utf-8")
+        assert "/speckit-specify" in content, (
+            "Expected '/speckit-specify' (hyphen) in generated Forge git.feature command body, "
+            "but it was not found. Check that __SPECKIT_COMMAND_SPECIFY__ is resolved correctly."
+        )
+        assert "/speckit.specify" not in content, (
+            "Found '/speckit.specify' (dot notation) in generated Forge git.feature command body. "
+            "Forge requires hyphen notation for ZSH compatibility."
+        )

tests/integrations/test_integration_gemini.py

@@ -0,0 +1,10 @@
+"""Tests for GeminiIntegration."""
+
+from .test_integration_base_toml import TomlIntegrationTests
+
+
+class TestGeminiIntegration(TomlIntegrationTests):
+    KEY = "gemini"
+    FOLDER = ".gemini/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".gemini/commands"

tests/integrations/test_integration_generic.py

@@ -0,0 +1,362 @@
+"""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
+
+    # -- 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}}"
+            assert "__SPECKIT_COMMAND_" not in content, f"{f.name} has unprocessed __SPECKIT_COMMAND_*__"
+
+    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
+
+    # -- Context section ---------------------------------------------------
+
+    def test_setup_does_not_write_context_section(self, tmp_path):
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        for path in tmp_path.rglob("*"):
+            if path.is_file():
+                text = path.read_text(encoding="utf-8", errors="ignore")
+                assert "<!-- SPECKIT START -->" not in text
+
+    def test_plan_command_has_no_context_placeholder(self, tmp_path):
+        """The core plan command must not carry a context-file placeholder —
+        agent context files are owned by the opt-in agent-context extension."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        plan_file = tmp_path / ".custom" / "cmds" / "speckit.plan.md"
+        assert plan_file.exists()
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content
+
+    def test_plan_defines_quickstart_as_validation_guide(self, tmp_path):
+        """The generated plan command should keep quickstart.md out of implementation scope."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        plan_file = tmp_path / ".custom" / "cmds" / "speckit.plan.md"
+        assert plan_file.exists()
+        content = plan_file.read_text(encoding="utf-8")
+
+        assert "Create quickstart validation guide" in content
+        assert "runnable validation scenarios" in content
+        assert "Do not include full implementation code" in content
+        assert "implementation details belong in `tasks.md` and the implementation phase" in content
+
+    def test_implement_loads_constitution_context(self, tmp_path):
+        """The generated implement command should load constitution governance context."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        implement_file = tmp_path / ".custom" / "cmds" / "speckit.implement.md"
+        assert implement_file.exists()
+        content = implement_file.read_text(encoding="utf-8")
+        assert ".specify/memory/constitution.md" in content
+
+    @pytest.mark.parametrize(
+        "command_stem",
+        [
+            "analyze",
+            "clarify",
+            "converge",
+            "implement",
+            "plan",
+            "checklist",
+            "specify",
+            "tasks",
+            "taskstoissues",
+        ],
+    )
+    def test_command_loads_constitution_context(self, tmp_path, command_stem):
+        """Every command except constitution must reference constitution.md."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        cmd_file = tmp_path / ".custom" / "cmds" / f"speckit.{command_stem}.md"
+        assert cmd_file.exists(), f"Command file missing: {cmd_file.name}"
+        content = cmd_file.read_text(encoding="utf-8")
+        assert "constitution.md" in content, (
+            f"speckit.{command_stem}.md must reference constitution.md"
+        )
+
+    def test_constitution_command_exists(self, tmp_path):
+        """The constitution command itself must exist but is not required to load itself."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        cmd_file = tmp_path / ".custom" / "cmds" / "speckit.constitution.md"
+        assert cmd_file.exists()
+
+    # -- CLI --------------------------------------------------------------
+
+    def test_cli_generic_without_commands_dir_fails(self, tmp_path):
+        """--integration generic without --integration-options 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",
+        ])
+        # Generic requires --commands-dir via --integration-options
+        assert result.exit_code != 0
+
+
+    def test_complete_file_inventory_sh(self, tmp_path):
+        """Every file produced by specify init --integration generic --integration-options=--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",
+                "--integration-options=--commands-dir .myagent/commands",
+                "--script", "sh",
+            ], 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() and ".git" not in p.parts
+        )
+        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.converge.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/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/setup-tasks.sh",
+            ".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",
+            ".specify/workflows/speckit/workflow.yml",
+            ".specify/workflows/workflow-registry.json",
+        ])
+        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 --integration-options=--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",
+                "--integration-options=--commands-dir .myagent/commands",
+                "--script", "ps",
+            ], 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() and ".git" not in p.parts
+        )
+        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.converge.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/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/setup-tasks.ps1",
+            ".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",
+            ".specify/workflows/speckit/workflow.yml",
+            ".specify/workflows/workflow-registry.json",
+        ])
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )

tests/integrations/test_integration_goose.py

@@ -0,0 +1,85 @@
+"""Tests for GooseIntegration."""
+
+import yaml
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_yaml import YamlIntegrationTests
+
+
+class TestGooseIntegration(YamlIntegrationTests):
+    KEY = "goose"
+    FOLDER = ".goose/"
+    COMMANDS_SUBDIR = "recipes"
+    REGISTRAR_DIR = ".goose/recipes"
+
+    def test_setup_declares_args_parameter_for_args_prompt(self, tmp_path):
+        # “If a generated Goose recipe uses {{args}} in its prompt, it
+        # must declare a corresponding args parameter.”
+
+        integration = get_integration("goose")
+        assert integration is not None
+
+        manifest = IntegrationManifest("goose", tmp_path)
+        created = integration.setup(tmp_path, manifest, script_type="sh")
+
+        recipe_files = [path for path in created if path.suffix == ".yaml"]
+        assert recipe_files
+
+        for recipe_file in recipe_files:
+            data = yaml.safe_load(recipe_file.read_text(encoding="utf-8"))
+
+            if "{{args}}" not in data["prompt"]:
+                continue
+
+            assert any(
+                param.get("key") == "args"
+                for param in data.get("parameters", [])
+            ), f"{recipe_file} uses {{{{args}}}} but does not declare args"
+
+
+class TestGooseCommandPlaceholderResolution:
+    """register_commands must resolve skill placeholders for the yaml branch.
+
+    The yaml (Goose recipe) branch previously skipped
+    resolve_skill_placeholders / _convert_argument_placeholder that the
+    markdown and toml branches apply, so extension/preset command bodies
+    kept literal {SCRIPT} / __AGENT__ / repo-relative paths.
+    """
+
+    def test_register_commands_resolves_placeholders_in_recipe(self, tmp_path):
+        from specify_cli.agents import CommandRegistrar
+
+        ext_dir = tmp_path / "extension"
+        cmd_dir = ext_dir / "commands"
+        cmd_dir.mkdir(parents=True)
+        cmd_file = cmd_dir / "example.md"
+        cmd_file.write_text(
+            "---\n"
+            "description: Placeholder command\n"
+            "scripts:\n"
+            "  sh: scripts/bash/do.sh\n"
+            "  ps: scripts/powershell/do.ps1\n"
+            "---\n\n"
+            "Run {SCRIPT} for agent __AGENT__ with $ARGUMENTS.\n",
+            encoding="utf-8",
+        )
+
+        registrar = CommandRegistrar()
+        commands = [{"name": "speckit.example", "file": "commands/example.md"}]
+        registrar.register_commands("goose", commands, "test-ext", ext_dir, tmp_path)
+
+        recipe = tmp_path / ".goose" / "recipes" / "speckit.example.yaml"
+        assert recipe.exists(), "goose recipe should be generated"
+        # Parse the recipe and assert the prompt actually got the correct
+        # replacements — not merely that the literal tokens are absent (which
+        # a wrong-but-token-free output could also satisfy).
+        data = yaml.safe_load(recipe.read_text(encoding="utf-8"))
+        prompt = data["prompt"]
+        assert ".specify/scripts/" in prompt  # {SCRIPT} -> resolved script path
+        assert "agent goose" in prompt  # __AGENT__ -> agent name
+        assert "{{args}}" in prompt  # $ARGUMENTS -> goose args token
+        # And the raw placeholders must not survive.
+        assert "{SCRIPT}" not in prompt
+        assert "__AGENT__" not in prompt
+        assert "$ARGUMENTS" not in prompt

tests/integrations/test_integration_hermes.py

@@ -0,0 +1,390 @@
+"""Tests for HermesIntegration.
+
+Hermes is special among SkillsIntegration subclasses: it writes skills
+to ``~/.hermes/skills/`` (global) rather than the project-local
+``.hermes/skills/`` directory.  A project-local marker (empty directory)
+is created so extension commands (e.g. git) can detect Hermes.
+
+All tests that touch ``~/.hermes/`` use ``monkeypatch`` to isolate
+``Path.home()`` to a temp directory so the test suite is hermetic and
+non-destructive to a developer's real Hermes installation.
+"""
+
+from pathlib import Path
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+def _fake_home(tmp_path: Path) -> Path:
+    """Create and return an isolated home directory under *tmp_path*."""
+    home = tmp_path / "home"
+    home.mkdir(exist_ok=True)
+    return home
+
+
+class TestHermesIntegration(SkillsIntegrationTests):
+    KEY = "hermes"
+    FOLDER = ".hermes/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = "~/.hermes/skills"
+
+    # -- Hermes-specific setup: skills go to ~/.hermes/skills/ -------------
+
+    def test_setup_writes_to_global_skills_dir(self, tmp_path, monkeypatch):
+        """Skills are written to ~/.hermes/skills/, not project-local."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        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, "No skill files were created"
+        for f in skill_files:
+            # Every skill file should be under ~/.hermes/skills/speckit-*/
+            expected_prefix = str(home / ".hermes" / "skills")
+            assert str(f).startswith(expected_prefix), (
+                f"{f} is not under ~/.hermes/skills/"
+            )
+
+    def test_local_marker_dir_created(self, tmp_path, monkeypatch):
+        """Project-local .hermes/skills/ should exist but be empty."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        marker = tmp_path / ".hermes" / "skills"
+        assert marker.is_dir(), "Marker directory was not created"
+        # Should be empty (no SKILL.md files)
+        children = list(marker.iterdir())
+        assert children == [], f"Marker directory should be empty, got: {children}"
+
+    # -- Override shared tests that assume project-local skills ------------
+
+    def test_setup_writes_to_correct_directory(self, tmp_path, monkeypatch):
+        """Override: Hermes writes to global, not project-local."""
+        self.test_setup_writes_to_global_skills_dir(tmp_path, monkeypatch)
+
+    def test_plan_skill_has_no_context_placeholder(self, tmp_path, monkeypatch):
+        """The core plan skill must not carry a context-file placeholder —
+        agent context files are owned by the opt-in agent-context extension."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        # Find the plan skill in global ~/.hermes/skills/
+        plan_file = home / ".hermes" / "skills" / "speckit-plan" / "SKILL.md"
+        assert plan_file.exists(), f"Plan skill {plan_file} not created globally"
+        content = plan_file.read_text(encoding="utf-8")
+        assert "__CONTEXT_FILE__" not in content, (
+            "Plan skill has unprocessed __CONTEXT_FILE__ placeholder"
+        )
+
+    def test_all_files_tracked_in_manifest(self, tmp_path, monkeypatch):
+        """Override: Hermes does not track skills in the project manifest
+        since they live globally.  Only project-local files (scripts,
+        templates, context) are tracked."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+        for f in created:
+            # Global files (in ~/.hermes/) are not tracked in manifest
+            if str(f).startswith(str(home)):
+                continue
+            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, monkeypatch):
+        """Override: Hermes uninstall removes global skills + local marker."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.install(tmp_path, m)
+        assert len(created) > 0
+        m.save()
+        # All SKILL.md files should exist globally
+        for f in created:
+            if "SKILL.md" in str(f):
+                assert f.exists(), f"{f} does not exist"
+        # Global skills are removed on teardown without needing force
+        removed, skipped = i.teardown(tmp_path, m, force=False)
+        for f in created:
+            if "SKILL.md" in str(f):
+                assert not f.exists(), f"{f} should have been removed"
+        # Local marker should be gone
+        assert not (tmp_path / ".hermes" / "skills").exists()
+
+    def test_modified_file_survives_uninstall(self, tmp_path, monkeypatch):
+        """Override: Hermes global skills are ALWAYS removed on uninstall
+        (they live outside the project root and aren't hash-tracked in the
+        manifest), so a modified global skill is still removed — matching
+        the standard behaviour where all integration files are cleaned up."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.install(tmp_path, m)
+        m.save()
+        # Pick a global skill file
+        skill_files = [f for f in created if "SKILL.md" in str(f)]
+        assert len(skill_files) > 0
+        modified_file = skill_files[0]
+        modified_file.write_text("user modified this", encoding="utf-8")
+        removed, skipped = i.uninstall(tmp_path, m)
+        assert not modified_file.exists(), (
+            "Modified global skill should be removed on teardown (standard behaviour)"
+        )
+
+    def test_modified_global_skill_removed_on_teardown(self, tmp_path, monkeypatch):
+        """Override: Hermes global skills are removed on uninstall regardless
+        of the force flag, matching standard integration behaviour."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.install(tmp_path, m)
+        m.save()
+        # Pick a global skill file
+        skill_files = [f for f in created if "SKILL.md" in str(f)]
+        assert len(skill_files) > 0
+        modified_file = skill_files[0]
+        modified_file.write_text("user modified this", encoding="utf-8")
+        # Global skills are removed on teardown regardless of force flag
+        removed, skipped = i.teardown(tmp_path, m, force=False)
+        assert not modified_file.exists(), (
+            "Modified global skill should be removed on teardown (standard behaviour)"
+        )
+
+    def test_pre_existing_skills_not_removed(self, tmp_path, monkeypatch):
+        """Pre-existing non-speckit global skills should survive Hermes uninstall."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        # Create a foreign skill in the global dir first
+        global_skills_dir = i._hermes_home_skills_dir()
+        foreign_dir = global_skills_dir / "other-tool"
+        foreign_dir.mkdir(parents=True, exist_ok=True)
+        (foreign_dir / "SKILL.md").write_text("# Foreign skill\n")
+
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+
+        # Run teardown to verify foreign skill survives uninstall
+        i.teardown(tmp_path, m)
+
+        assert (foreign_dir / "SKILL.md").exists(), (
+            "Foreign skill was removed by teardown"
+        )
+
+    def test_hook_sections_explain_dotted_command_conversion(self, tmp_path, monkeypatch):
+        """Override: Hermes skills live in global ~/.hermes/skills/."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        i.setup(tmp_path, m)
+        specify_skill = home / ".hermes" / "skills" / "speckit-specify" / "SKILL.md"
+        assert specify_skill.exists()
+        content = specify_skill.read_text(encoding="utf-8")
+        assert "replace dots" in content, (
+            "speckit-specify should explain dotted hook command conversion"
+        )
+        assert content.count("replace dots") == content.count(
+            "- For each executable hook, output the following"
+        )
+
+    def test_complete_file_inventory_sh(self, tmp_path, monkeypatch):
+        """Override: Hermes init produces no local SKILL.md files,
+        only the empty .hermes/skills/ marker."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / f"inventory-sh-{self.KEY}"
+        project.mkdir()
+        old_cwd = Path.cwd()
+        import os
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", self.KEY,
+                "--script", "sh", "--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()
+        )
+        # Ensure no core .hermes/skills/speckit-*/SKILL.md in project dir
+        # (extension-installed skills like agent-context-update may appear)
+        hermes_skill_files = [
+            f for f in actual
+            if f.startswith(".hermes/skills/speckit-")
+            and "agent-context" not in f
+        ]
+        assert hermes_skill_files == [], (
+            f"Expected no local core SKILL.md files, found: {hermes_skill_files}"
+        )
+        # Ensure the marker exists (empty dir won't appear in file listing)
+        assert (project / ".hermes" / "skills").is_dir()
+
+    def test_complete_file_inventory_ps(self, tmp_path, monkeypatch):
+        """Override: Same as sh variant but for PowerShell script type."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / f"inventory-ps-{self.KEY}"
+        project.mkdir()
+        old_cwd = Path.cwd()
+        import os
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", self.KEY,
+                "--script", "ps", "--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()
+        )
+        # Ensure no core .hermes/skills/speckit-*/SKILL.md in project dir
+        # (extension-installed skills like agent-context-update may appear)
+        hermes_skill_files = [
+            f for f in actual
+            if f.startswith(".hermes/skills/speckit-")
+            and "agent-context" not in f
+        ]
+        assert hermes_skill_files == [], (
+            f"Expected no local core SKILL.md files, found: {hermes_skill_files}"
+        )
+        assert (project / ".hermes" / "skills").is_dir()
+
+    def test_install_uninstall_cleanup(self, tmp_path, monkeypatch):
+        """Verify global skills are cleaned and local marker is removed."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        i = get_integration(self.KEY)
+        m = IntegrationManifest(self.KEY, tmp_path)
+        created = i.setup(tmp_path, m)
+
+        # Verify global skills exist
+        global_skills = [
+            f for f in created
+            if "SKILL.md" in str(f)
+            and str(f).startswith(str(home / ".hermes"))
+        ]
+        assert len(global_skills) > 0
+        for f in global_skills:
+            assert f.exists()
+
+        # Verify local marker exists
+        assert (tmp_path / ".hermes" / "skills").is_dir()
+
+        # Teardown — global skills removed without needing force=True
+        removed, skipped = i.teardown(tmp_path, m, force=False)
+
+        # Global skills removed
+        for f in global_skills:
+            assert not f.exists(), f"{f} should have been removed"
+
+        # Local marker removed
+        assert not (tmp_path / ".hermes" / "skills").exists(), (
+            "Local marker should be removed on teardown"
+        )
+
+
+class TestHermesInitFlow:
+    """--integration hermes creates expected files."""
+
+    def test_integration_hermes_creates_global_skills(self, tmp_path, monkeypatch):
+        """--integration hermes should create global skills and a local marker."""
+        home = _fake_home(tmp_path)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        target = tmp_path / "test-proj"
+        result = runner.invoke(app, [
+            "init", str(target),
+            "--integration", "hermes",
+            "--ignore-agent-tools",
+            "--script", "sh",
+        ])
+
+        assert result.exit_code == 0, f"init --integration hermes failed: {result.output}"
+        # Skills should be in global ~/.hermes/skills/
+        assert (home / ".hermes" / "skills" / "speckit-plan" / "SKILL.md").exists()
+        # Local marker should exist
+        assert (target / ".hermes" / "skills").is_dir()
+        # No core SKILL.md files in project-local dir
+        # (extension-installed skills like agent-context-update may appear)
+        local_skills = [
+            d for d in (target / ".hermes" / "skills").iterdir()
+            if "agent-context" not in d.name
+        ]
+        assert local_skills == [], f"Local skills dir should be empty, got: {local_skills}"
+
+
+class TestHermesBuildExecArgs:
+    """CLI dispatch argv, including the operator extra-args env hook."""
+
+    def test_build_exec_args_default_shape(self):
+        i = get_integration("hermes")
+        assert i.build_exec_args("/speckit-plan hi", output_json=True) == [
+            "hermes", "chat", "-Q", "--json", "-s", "speckit-plan", "-q", "hi",
+        ]
+
+    def test_build_exec_args_honors_extra_args(self, monkeypatch):
+        """SPECKIT_INTEGRATION_HERMES_EXTRA_ARGS is injected before the
+        canonical -m/--json/-s/-q flags (same env hook as codex/opencode/
+        devin; hermes previously skipped _apply_extra_args_env_var entirely).
+        """
+        monkeypatch.setenv(
+            "SPECKIT_INTEGRATION_HERMES_EXTRA_ARGS", "--temperature 0.2"
+        )
+        i = get_integration("hermes")
+        args = i.build_exec_args("/speckit-plan hi", output_json=True)
+        assert args == [
+            "hermes", "chat", "-Q", "--temperature", "0.2",
+            "--json", "-s", "speckit-plan", "-q", "hi",
+        ]
+        # Injected before the canonical flags so it can't displace them.
+        assert args.index("--temperature") < args.index("--json")
+        assert args.index("--temperature") < args.index("-s")
+
+    def test_build_exec_args_honors_executable_override(self, monkeypatch):
+        monkeypatch.setenv(
+            "SPECKIT_INTEGRATION_HERMES_EXECUTABLE", "/custom/hermes"
+        )
+        i = get_integration("hermes")
+        assert i.build_exec_args("/speckit-plan hi")[0] == "/custom/hermes"

tests/integrations/test_integration_junie.py

@@ -0,0 +1,10 @@
+"""Tests for JunieIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestJunieIntegration(MarkdownIntegrationTests):
+    KEY = "junie"
+    FOLDER = ".junie/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".junie/commands"

tests/integrations/test_integration_kilocode.py

@@ -0,0 +1,10 @@
+"""Tests for KilocodeIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestKilocodeIntegration(MarkdownIntegrationTests):
+    KEY = "kilocode"
+    FOLDER = ".kilocode/"
+    COMMANDS_SUBDIR = "workflows"
+    REGISTRAR_DIR = ".kilocode/workflows"

tests/integrations/test_integration_kimi.py

@@ -0,0 +1,386 @@
+"""Tests for KimiIntegration — skills integration with legacy migration."""
+
+from pathlib import Path
+
+import pytest
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.kimi import (
+    _migrate_legacy_kimi_dotted_skills,
+    _migrate_legacy_kimi_skills_dir,
+)
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+def _symlink_or_skip(
+    link: Path, target: Path, *, target_is_directory: bool = False
+) -> None:
+    """Create *link* pointing at *target*, skipping the test if unsupported.
+
+    Symlink creation fails on Windows without the create-symlink privilege and
+    in some restricted CI sandboxes. The symlink-safety tests below assert
+    behavior that only matters when symlinks exist, so skip (rather than error)
+    when the platform cannot create them.
+    """
+    try:
+        link.symlink_to(target, target_is_directory=target_is_directory)
+    except (OSError, NotImplementedError) as exc:
+        pytest.skip(f"symlinks unavailable: {exc}")
+
+
+class TestKimiIntegration(SkillsIntegrationTests):
+    KEY = "kimi"
+    FOLDER = ".kimi-code/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".kimi-code/skills"
+
+
+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_migrate_legacy_moves_old_skills_dir(self, tmp_path):
+        """--migrate-legacy moves hyphenated skills from .kimi/skills to .kimi-code/skills."""
+        i = get_integration("kimi")
+
+        old_skills_dir = tmp_path / ".kimi" / "skills"
+        new_skills_dir = tmp_path / ".kimi-code" / "skills"
+        legacy = old_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 not old_skills_dir.exists()
+        assert (new_skills_dir / "speckit-oldcmd" / "SKILL.md").exists()
+        # New skills from templates should also exist
+        assert (new_skills_dir / "speckit-specify" / "SKILL.md").exists()
+
+    def test_setup_with_migrate_legacy_option(self, tmp_path):
+        """KimiIntegration.setup() with --migrate-legacy migrates dotted dirs."""
+        i = get_integration("kimi")
+
+        old_skills_dir = tmp_path / ".kimi" / "skills"
+        new_skills_dir = tmp_path / ".kimi-code" / "skills"
+        legacy = old_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 (new_skills_dir / "speckit-oldcmd" / "SKILL.md").exists()
+        # New skills from templates should also exist
+        assert (new_skills_dir / "speckit-specify" / "SKILL.md").exists()
+
+
+class TestKimiTeardownLegacyCleanup:
+    """teardown() removes leftover legacy .kimi/skills/ directories."""
+
+    def test_teardown_removes_legacy_speckit_skills(self, tmp_path):
+        i = get_integration("kimi")
+
+        legacy_skill = tmp_path / ".kimi" / "skills" / "speckit-plan" / "SKILL.md"
+        legacy_skill.parent.mkdir(parents=True)
+        legacy_skill.write_text(
+            "---\n"
+            "name: \"speckit-plan\"\n"
+            "description: \"Plan workflow\"\n"
+            "metadata:\n"
+            "  author: \"github-spec-kit\"\n"
+            "  source: \"templates/commands/plan.md\"\n"
+            "---\n"
+        )
+
+        m = IntegrationManifest("kimi", tmp_path)
+        i.teardown(tmp_path, m)
+
+        assert not legacy_skill.exists()
+        assert not (tmp_path / ".kimi" / "skills").exists()
+
+    def test_teardown_preserves_user_skills_in_legacy_dir(self, tmp_path):
+        i = get_integration("kimi")
+
+        user_skill = tmp_path / ".kimi" / "skills" / "my-custom" / "SKILL.md"
+        user_skill.parent.mkdir(parents=True)
+        user_skill.write_text("# My custom skill\n")
+
+        m = IntegrationManifest("kimi", tmp_path)
+        i.teardown(tmp_path, m)
+
+        assert user_skill.exists()
+
+
+class TestKimiCommandInvocation:
+    """Kimi dispatch must use the native ``/skill:`` slash command."""
+
+    def test_build_command_invocation_uses_skill_prefix(self):
+        i = get_integration("kimi")
+        assert i.build_command_invocation("specify") == "/skill:speckit-specify"
+        assert i.build_command_invocation("speckit.plan") == "/skill:speckit-plan"
+
+    def test_build_command_invocation_dotted_extension(self):
+        i = get_integration("kimi")
+        assert (
+            i.build_command_invocation("speckit.git.commit")
+            == "/skill:speckit-git-commit"
+        )
+
+    def test_build_command_invocation_appends_args(self):
+        i = get_integration("kimi")
+        assert (
+            i.build_command_invocation("specify", "my feature")
+            == "/skill:speckit-specify my feature"
+        )
+
+
+class TestKimiLegacySymlinkSafety:
+    """Legacy migration/cleanup must not follow symlinks out of the project."""
+
+    def test_migrate_skips_symlinked_legacy_skills_dir(self, tmp_path):
+        # An attacker-controlled directory outside the project root. Use a
+        # non-template skill name so a successful migration would be visible
+        # (the bundled templates never create "speckit-evillegacy").
+        outside = tmp_path / "outside"
+        (outside / "speckit-evillegacy").mkdir(parents=True)
+        (outside / "speckit-evillegacy" / "SKILL.md").write_text("# evil\n")
+
+        project = tmp_path / "project"
+        (project / ".kimi").mkdir(parents=True)
+        # .kimi/skills is a symlink to the outside directory.
+        _symlink_or_skip(
+            project / ".kimi" / "skills", outside, target_is_directory=True
+        )
+
+        i = get_integration("kimi")
+        m = IntegrationManifest("kimi", project)
+        i.setup(project, m, parsed_options={"migrate_legacy": True})
+
+        # Outside content must be untouched (not moved into .kimi-code).
+        assert (outside / "speckit-evillegacy" / "SKILL.md").exists()
+        assert not (
+            project / ".kimi-code" / "skills" / "speckit-evillegacy"
+        ).exists()
+
+    def test_teardown_skips_symlinked_legacy_skills_dir(self, tmp_path):
+        outside = tmp_path / "outside"
+        outside.mkdir()
+        keep = outside / "keep.txt"
+        keep.write_text("important\n")
+
+        project = tmp_path / "project"
+        (project / ".kimi").mkdir(parents=True)
+        _symlink_or_skip(
+            project / ".kimi" / "skills", outside, target_is_directory=True
+        )
+
+        i = get_integration("kimi")
+        m = IntegrationManifest("kimi", project)
+        i.teardown(project, m)
+
+        # The symlink target and its contents must survive teardown.
+        assert keep.exists()
+
+    def test_migrate_skips_symlinked_legacy_parent_dir(self, tmp_path):
+        # `.kimi` is itself a symlink to the project root, so `.kimi/skills`
+        # resolves to `./skills` — an unrelated in-tree directory. Even though
+        # the resolved path stays inside the project, migration must not
+        # operate on it because a path component is a symlink.
+        project = tmp_path / "project"
+        unrelated = project / "skills" / "speckit-evillegacy"
+        unrelated.mkdir(parents=True)
+        (unrelated / "SKILL.md").write_text("# unrelated\n")
+        # .kimi -> project root, so .kimi/skills == ./skills.
+        _symlink_or_skip(project / ".kimi", project, target_is_directory=True)
+
+        i = get_integration("kimi")
+        m = IntegrationManifest("kimi", project)
+        i.setup(project, m, parsed_options={"migrate_legacy": True})
+
+        # The unrelated ./skills content must be untouched.
+        assert (unrelated / "SKILL.md").exists()
+        assert not (
+            project / ".kimi-code" / "skills" / "speckit-evillegacy"
+        ).exists()
+
+    def test_teardown_skips_symlinked_legacy_parent_dir(self, tmp_path):
+        project = tmp_path / "project"
+        project.mkdir()
+        # Looks Speckit-generated, so only the symlink check protects it.
+        unrelated = project / "skills" / "speckit-evillegacy"
+        unrelated.mkdir(parents=True)
+        (unrelated / "SKILL.md").write_text(
+            "---\nmetadata:\n  author: github-spec-kit\n---\n# x\n"
+        )
+        _symlink_or_skip(project / ".kimi", project, target_is_directory=True)
+
+        i = get_integration("kimi")
+        m = IntegrationManifest("kimi", project)
+        i.teardown(project, m)
+
+        # The unrelated ./skills content must survive teardown.
+        assert (unrelated / "SKILL.md").exists()
+
+    def test_setup_rejects_symlinked_destination_before_writing(self, tmp_path):
+        # `.kimi-code` is a symlink to the project root, so the skills
+        # destination `.kimi-code/skills` resolves to `./skills` — an
+        # unintended in-tree location. base setup() only rejects a
+        # destination that escapes the project root, so without the
+        # pre-check it would write SKILL.md files into `./skills`. setup()
+        # must refuse before any write occurs.
+        project = tmp_path / "project"
+        project.mkdir()
+        _symlink_or_skip(project / ".kimi-code", project, target_is_directory=True)
+
+        i = get_integration("kimi")
+        m = IntegrationManifest("kimi", project)
+        with pytest.raises(ValueError, match="symlinked"):
+            i.setup(project, m)
+
+        # Nothing was written into the unintended `./skills` location.
+        assert not (project / "skills").exists()
+
+    def test_migrate_skips_symlinked_target_dir(self, tmp_path):
+        # The destination `.kimi-code/skills/speckit-foo` already exists but is
+        # a symlink to a directory outside the project. Migration compares
+        # SKILL.md bytes to decide whether to drop the legacy copy; it must not
+        # follow the symlinked target dir to read SKILL.md from outside.
+        outside = tmp_path / "outside"
+        outside.mkdir()
+        (outside / "SKILL.md").write_text("# shared\n")
+
+        project = tmp_path / "project"
+        legacy = project / ".kimi" / "skills" / "speckit-foo"
+        legacy.mkdir(parents=True)
+        # Identical bytes: without the symlink guard the legacy dir would be
+        # removed after following the link out of the project.
+        (legacy / "SKILL.md").write_text("# shared\n")
+
+        target = project / ".kimi-code" / "skills" / "speckit-foo"
+        target.parent.mkdir(parents=True)
+        _symlink_or_skip(target, outside, target_is_directory=True)
+
+        _migrate_legacy_kimi_skills_dir(
+            project / ".kimi" / "skills", project / ".kimi-code" / "skills"
+        )
+
+        # Legacy copy is preserved (migration refused to follow the symlink),
+        # and the outside target is untouched.
+        assert (legacy / "SKILL.md").exists()
+        assert (outside / "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", "--integration", "kimi",
+                "--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

@@ -0,0 +1,148 @@
+"""Tests for KiroCliIntegration."""
+
+import os
+import re
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.kiro_cli import _KIRO_ARG_FALLBACK
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+# Regex shapes that indicate a value is a placeholder token, not prose.
+# Covers Bash ($VAR, ${VAR}, ${VAR:-default}), Mustache/Handlebars/Jinja
+# ({{var}}, {{{var}}}), Liquid/Jinja control ({% ... %}), Python str.format /
+# .NET ({var}, {0}), angle-bracket (<var>), and Windows-style (%VAR%).
+# Anchored to the FULL STRING so legitimate prose mentioning a placeholder
+# (e.g. "the {{magic}} of placeholders") is not flagged. The Liquid pattern
+# is anchored to the START so multi-tag templates fire while mid-sentence
+# {%-quotation does not.
+_PLACEHOLDER_TOKEN_PATTERNS = (
+    re.compile(r"^\$\w+$"),                                  # $ARGUMENTS, $args
+    re.compile(r"^\$\{\w+(?:[:\-+?][^}]*)?\}$"),             # ${ARGS}, ${ARGS:-default}
+    re.compile(r"^\{\{\{?\s*\w+(\s*[|.][^}]*)?\s*\}?\}\}$"), # {{var}} {{{var}}} {{x|y}}
+    re.compile(r"^\{%"),                                     # {% if x %}{{ x }}{% endif %}
+    re.compile(r"^<\w+>$"),                                  # <args>
+    re.compile(r"^%\w+%$"),                                  # %USERNAME%
+    re.compile(r"^\{(?:\d+|[a-zA-Z_]\w*)(?:[.\[][^}]*)?(?:![rsa])?(?::[^}]*)?\}$"),  # {0}, {var}, {0:>5}
+)
+
+
+def _looks_like_placeholder_token(value: str) -> bool:
+    """Return True if *value* matches a known placeholder-token shape."""
+    if not value:
+        return False
+    return any(p.search(value) for p in _PLACEHOLDER_TOKEN_PATTERNS)
+
+
+class TestKiroCliIntegration(MarkdownIntegrationTests):
+    KEY = "kiro-cli"
+    FOLDER = ".kiro/"
+    COMMANDS_SUBDIR = "prompts"
+    REGISTRAR_DIR = ".kiro/prompts"
+
+    def test_registrar_config(self):
+        """Override base assertion: kiro-cli uses a prose fallback for args
+        because Kiro CLI file-based prompts do not natively substitute
+        ``$ARGUMENTS`` (see issue #1926 / kirodotdev/Kiro#4141). The
+        regression-guard load is carried by the two layer tests below
+        (exact-fallback + placeholder-shape rejection)."""
+        i = get_integration(self.KEY)
+        assert i.registrar_config["dir"] == self.REGISTRAR_DIR
+        assert i.registrar_config["format"] == "markdown"
+        assert i.registrar_config["extension"] == ".md"
+
+    def test_registrar_config_args_is_exact_prose_fallback(self):
+        """Layer 1 — pin the exact fallback so wording drift requires a
+        deliberate paired commit (production constant + test update)."""
+        i = get_integration(self.KEY)
+        assert i.registrar_config["args"] == _KIRO_ARG_FALLBACK, (
+            f"args drifted from the pinned fallback constant. "
+            f"Got: {i.registrar_config['args']!r}; expected: {_KIRO_ARG_FALLBACK!r}. "
+            f"If the wording change is intentional, update _KIRO_ARG_FALLBACK and "
+            f"this test together."
+        )
+
+    def test_registrar_config_args_does_not_look_like_a_placeholder_token(self):
+        """Layer 2 — independent regression guard: even if someone bypasses
+        layer-1 by changing both constant and test, the value still must not
+        look like ANY placeholder token shape ($X, ${X}, {{X}}, <X>, %X%, {0},
+        {% %}). Catches the class of regression Copilot called out: a swap
+        from $ARGUMENTS to $INPUT or {{userMessage}} would fail this test
+        even if it accidentally passed layer 1."""
+        i = get_integration(self.KEY)
+        args = i.registrar_config["args"]
+        assert not _looks_like_placeholder_token(args), (
+            f"registrar_config['args'] = {args!r} matches a known placeholder-"
+            f"token shape — Kiro CLI does not substitute placeholders so this "
+            f"would reach the model verbatim and break the prompt (issue #1926). "
+            f"Use a prose fallback instead."
+        )
+
+    def test_rendered_prompts_do_not_contain_raw_arguments(self, tmp_path):
+        """Rendered Kiro prompt files must NOT contain the raw ``$ARGUMENTS``
+        token — Kiro CLI does not substitute it, so the literal would reach
+        the model and break the prompt (issue #1926)."""
+        integration = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        integration.setup(tmp_path, manifest, script_type="sh")
+
+        prompts_dir = tmp_path / self.REGISTRAR_DIR
+        rendered = list(prompts_dir.glob("*.md"))
+        assert rendered, "expected at least one rendered prompt file"
+
+        offenders = [
+            p.name for p in rendered if "$ARGUMENTS" in p.read_text(encoding="utf-8")
+        ]
+        assert offenders == [], (
+            f"these rendered prompts still contain the raw $ARGUMENTS token: {offenders}"
+        )
+
+    def test_rendered_prompts_contain_kiro_arg_placeholder(self, tmp_path):
+        """The chosen kiro-cli args fallback string must end up in at least
+        one rendered prompt (proves substitution actually fired, not just
+        that $ARGUMENTS was removed). Imports the fallback constant directly
+        instead of reading the field back so the test stays independent of
+        the integration's own config — even if the registrar_config['args']
+        regresses, this test still verifies the FALLBACK STRING is in the
+        rendered output."""
+        integration = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        integration.setup(tmp_path, manifest, script_type="sh")
+
+        expected = _KIRO_ARG_FALLBACK
+        prompts_dir = tmp_path / self.REGISTRAR_DIR
+        contents = "\n".join(
+            p.read_text(encoding="utf-8") for p in prompts_dir.glob("*.md")
+        )
+        assert expected in contents, (
+            f"none of the rendered prompts contain the configured args fallback "
+            f"({expected!r})"
+        )
+
+
+class TestKiroIntegration:
+    """--integration kiro-cli creates expected files."""
+
+    def test_integration_kiro_cli_creates_files(self, tmp_path):
+        """--integration kiro-cli should create files in .kiro/prompts."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        target = tmp_path / "kiro-proj"
+        target.mkdir()
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(target)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--integration", "kiro-cli",
+                "--ignore-agent-tools", "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0
+        assert (target / ".kiro" / "prompts" / "speckit.plan.md").exists()

tests/integrations/test_integration_lingma.py

@@ -0,0 +1,10 @@
+"""Tests for LingmaIntegration."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestLingmaIntegration(SkillsIntegrationTests):
+    KEY = "lingma"
+    FOLDER = ".lingma/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".lingma/skills"

tests/integrations/test_integration_omp.py

@@ -0,0 +1,30 @@
+"""Tests for OmpIntegration."""
+
+from specify_cli.integrations import get_integration
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestOmpIntegration(MarkdownIntegrationTests):
+    KEY = "omp"
+    FOLDER = ".omp/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".omp/commands"
+
+    def test_build_exec_args_uses_omp_json_mode(self):
+        i = get_integration(self.KEY)
+
+        args = i.build_exec_args(
+            "/speckit.specify Build auth",
+            model="gpt-5",
+        )
+
+        assert args == [
+            "omp",
+            "--print",
+            "--model",
+            "gpt-5",
+            "--mode",
+            "json",
+            "/speckit.specify Build auth",
+        ]

tests/integrations/test_integration_opencode.py

@@ -0,0 +1,199 @@
+"""Tests for OpencodeIntegration."""
+
+import warnings
+
+from specify_cli.agents import CommandRegistrar
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestOpencodeIntegration(MarkdownIntegrationTests):
+    KEY = "opencode"
+    FOLDER = ".opencode/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".opencode/commands"
+
+    def test_build_exec_args_uses_run_command_dispatch(self):
+        integration = get_integration(self.KEY)
+
+        args = integration.build_exec_args(
+            "/speckit.specify build a login page",
+            output_json=False,
+        )
+
+        assert args == [
+            "opencode",
+            "run",
+            "--command",
+            "speckit.specify",
+            "build a login page",
+        ]
+        assert "-p" not in args
+        assert "--output-format" not in args
+
+    def test_build_exec_args_maps_model_and_json_flags(self):
+        integration = get_integration(self.KEY)
+
+        args = integration.build_exec_args(
+            "/speckit.plan add OAuth",
+            model="anthropic/claude-sonnet-4",
+            output_json=True,
+        )
+
+        assert args == [
+            "opencode",
+            "run",
+            "--command",
+            "speckit.plan",
+            "-m",
+            "anthropic/claude-sonnet-4",
+            "--format",
+            "json",
+            "add OAuth",
+        ]
+
+    def test_build_exec_args_keeps_plain_prompt_dispatch(self):
+        integration = get_integration(self.KEY)
+
+        args = integration.build_exec_args("explain this repository", output_json=False)
+
+        assert args == ["opencode", "run", "explain this repository"]
+
+    def test_registrar_config_has_legacy_dir(self):
+        integration = get_integration(self.KEY)
+        assert integration.registrar_config["legacy_dir"] == ".opencode/command"
+
+    def test_legacy_dir_extension_registration(self, tmp_path):
+        """Extensions register in legacy .opencode/command/ with a warning."""
+        # Seed a legacy project with only .opencode/command/
+        legacy_dir = tmp_path / ".opencode" / "command"
+        legacy_dir.mkdir(parents=True)
+        (legacy_dir / "speckit.specify.md").write_text("# existing", encoding="utf-8")
+
+        # Create a source command file for the registrar
+        src_dir = tmp_path / "_ext_src"
+        src_dir.mkdir()
+        (src_dir / "myext.md").write_text(
+            "---\ndescription: test\n---\n# ext command", encoding="utf-8",
+        )
+
+        registrar = CommandRegistrar()
+        commands = [{"name": "speckit.myext", "file": "myext.md"}]
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            results = registrar.register_commands_for_all_agents(
+                commands, "test-ext", src_dir, tmp_path,
+            )
+
+        # Should have registered in the legacy directory
+        assert "opencode" in results
+        assert (legacy_dir / "speckit.myext.md").exists()
+        # Canonical directory should NOT have been created
+        assert not (tmp_path / ".opencode" / "commands").exists()
+        # Should have emitted a deprecation warning
+        opencode_warnings = [
+            w for w in caught
+            if "legacy" in str(w.message) and "opencode" in str(w.message)
+        ]
+        assert len(opencode_warnings) == 1, (
+            f"Expected exactly 1 legacy-dir warning, got {len(opencode_warnings)}"
+        )
+        assert "specify integration upgrade" in str(opencode_warnings[0].message)
+
+    def test_legacy_dir_unregister(self, tmp_path):
+        """Unregister finds commands in legacy .opencode/command/ dir."""
+        legacy_dir = tmp_path / ".opencode" / "command"
+        legacy_dir.mkdir(parents=True)
+        cmd_file = legacy_dir / "speckit.myext.md"
+        cmd_file.write_text("# ext command", encoding="utf-8")
+
+        registrar = CommandRegistrar()
+
+        with warnings.catch_warnings(record=True):
+            warnings.simplefilter("always")
+            registrar.unregister_commands(
+                {"opencode": ["speckit.myext"]}, tmp_path,
+            )
+
+        assert not cmd_file.exists()
+
+    def test_unregister_cleans_legacy_when_both_dirs_exist(self, tmp_path):
+        """Unregister removes files from legacy dir even when canonical exists."""
+        # Set up both canonical and legacy dirs
+        canonical_dir = tmp_path / ".opencode" / "commands"
+        canonical_dir.mkdir(parents=True)
+        legacy_dir = tmp_path / ".opencode" / "command"
+        legacy_dir.mkdir(parents=True)
+
+        # Place a command file in the legacy dir (orphaned after upgrade)
+        legacy_cmd = legacy_dir / "speckit.myext.md"
+        legacy_cmd.write_text("# orphaned ext command", encoding="utf-8")
+        # Place the same command in the canonical dir (current)
+        canonical_cmd = canonical_dir / "speckit.myext.md"
+        canonical_cmd.write_text("# ext command", encoding="utf-8")
+
+        registrar = CommandRegistrar()
+
+        with warnings.catch_warnings(record=True):
+            warnings.simplefilter("always")
+            registrar.unregister_commands(
+                {"opencode": ["speckit.myext"]}, tmp_path,
+            )
+
+        # Both files should be removed
+        assert not canonical_cmd.exists(), (
+            "Command file in canonical dir should be removed"
+        )
+        assert not legacy_cmd.exists(), (
+            "Orphaned command file in legacy dir should also be removed"
+        )
+
+    def test_canonical_dir_preferred_over_legacy(self, tmp_path):
+        """When both dirs exist, canonical .opencode/commands/ is used."""
+        legacy_dir = tmp_path / ".opencode" / "command"
+        legacy_dir.mkdir(parents=True)
+        canonical_dir = tmp_path / ".opencode" / "commands"
+        canonical_dir.mkdir(parents=True)
+        (canonical_dir / "speckit.specify.md").write_text("# cmd", encoding="utf-8")
+
+        # Create a source command file for the registrar
+        src_dir = tmp_path / "_ext_src"
+        src_dir.mkdir()
+        (src_dir / "myext.md").write_text(
+            "---\ndescription: test\n---\n# ext command", encoding="utf-8",
+        )
+
+        registrar = CommandRegistrar()
+        commands = [{"name": "speckit.myext", "file": "myext.md"}]
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            results = registrar.register_commands_for_all_agents(
+                commands, "test-ext", src_dir, tmp_path,
+            )
+
+        # Should register in canonical dir, not legacy
+        assert "opencode" in results
+        assert (canonical_dir / "speckit.myext.md").exists()
+        assert not (legacy_dir / "speckit.myext.md").exists()
+        # No legacy warning when canonical dir exists
+        opencode_warnings = [
+            w for w in caught
+            if "legacy" in str(w.message) and "opencode" in str(w.message)
+        ]
+        assert len(opencode_warnings) == 0
+
+    def test_setup_writes_to_canonical_dir(self, tmp_path):
+        """New installs always write to .opencode/commands/ (plural)."""
+        integration = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        integration.setup(tmp_path, manifest)
+
+        canonical = tmp_path / ".opencode" / "commands"
+        legacy = tmp_path / ".opencode" / "command"
+        assert canonical.is_dir()
+        assert not legacy.exists()
+        assert any(canonical.glob("speckit.*.md"))

tests/integrations/test_integration_pi.py

@@ -0,0 +1,10 @@
+"""Tests for PiIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestPiIntegration(MarkdownIntegrationTests):
+    KEY = "pi"
+    FOLDER = ".pi/"
+    COMMANDS_SUBDIR = "prompts"
+    REGISTRAR_DIR = ".pi/prompts"

tests/integrations/test_integration_qodercli.py

@@ -0,0 +1,10 @@
+"""Tests for QodercliIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestQodercliIntegration(MarkdownIntegrationTests):
+    KEY = "qodercli"
+    FOLDER = ".qoder/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".qoder/commands"

tests/integrations/test_integration_qwen.py

@@ -0,0 +1,10 @@
+"""Tests for QwenIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestQwenIntegration(MarkdownIntegrationTests):
+    KEY = "qwen"
+    FOLDER = ".qwen/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".qwen/commands"

tests/integrations/test_integration_rovodev.py

@@ -0,0 +1,295 @@
+"""Tests for RovodevIntegration."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+import yaml
+from click.testing import Result
+from typer.testing import CliRunner
+
+from specify_cli import app
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+def _run_init(project, *flags: str) -> Result:
+    """Run ``specify init --here`` in *project* with the given extra flags.
+
+    Centralises the cwd-management boilerplate so individual tests just
+    declare the flags they care about.
+    """
+    old_cwd = os.getcwd()
+    try:
+        os.chdir(project)
+        return CliRunner().invoke(
+            app,
+            ["init", "--here", *flags, "--script", "sh", "--ignore-agent-tools"],
+            catch_exceptions=False,
+        )
+    finally:
+        os.chdir(old_cwd)
+
+
+@pytest.fixture
+def rovodev_init_project(tmp_path):
+    """Run ``specify init --integration rovodev`` once and return the project root.
+
+    Shared across the slow init-inventory tests so we pay the full-CLI cost
+    only once instead of three times.
+    """
+    project = tmp_path / "rovodev-init"
+    project.mkdir()
+    result = _run_init(project, "--integration", "rovodev")
+    assert result.exit_code == 0, result.output
+    return project
+
+
+class TestRovodevIntegration:
+    """Rovodev-specific tests (not inherited from SkillsIntegrationTests because
+    rovodev's setup() emits prompt wrappers + prompts.yml in addition to skills,
+    which violates the base mixin's pure-skills assumptions)."""
+
+    KEY = "rovodev"
+
+    # -- ACLI dispatch -----------------------------------------------------
+
+    def test_build_exec_args(self):
+        impl = get_integration(self.KEY)
+        args = impl.build_exec_args("/speckit.plan add OAuth")
+        assert args[0:3] == ["acli", "rovodev", "run"]
+        assert args[3] == "/speckit.plan add OAuth"
+        assert "--output-schema" in args
+
+    def test_build_exec_args_without_json(self):
+        impl = get_integration(self.KEY)
+        args = impl.build_exec_args("/speckit.plan add OAuth", output_json=False)
+        assert args == ["acli", "rovodev", "run", "/speckit.plan add OAuth"]
+
+    def test_build_exec_args_executable_env_override(self, monkeypatch):
+        """SPECKIT_INTEGRATION_ROVODEV_EXECUTABLE overrides the binary path.
+
+        Lets operators pin a specific ``acli`` build or relocate the binary
+        without modifying the integration. Mirrors codex/devin/claude/etc.
+        """
+        monkeypatch.setenv("SPECKIT_INTEGRATION_ROVODEV_EXECUTABLE", "/opt/atl/bin/acli")
+        impl = get_integration(self.KEY)
+        args = impl.build_exec_args("hello", output_json=False)
+        assert args == ["/opt/atl/bin/acli", "rovodev", "run", "hello"]
+
+    def test_build_exec_args_executable_env_blank_falls_back(self, monkeypatch):
+        """Whitespace/empty env override is treated as unset → default ``acli``."""
+        monkeypatch.setenv("SPECKIT_INTEGRATION_ROVODEV_EXECUTABLE", "   ")
+        impl = get_integration(self.KEY)
+        args = impl.build_exec_args("hello", output_json=False)
+        assert args[0] == "acli"
+
+    def test_build_exec_args_extra_args_env_injection(self, monkeypatch):
+        """SPECKIT_INTEGRATION_ROVODEV_EXTRA_ARGS injects extra CLI flags.
+
+        Useful for CI or non-interactive contexts that need to pass flags
+        the integration doesn't expose. Mirrors the contract on every other
+        CLI integration (claude, codex, devin, …).
+        """
+        monkeypatch.setenv("SPECKIT_INTEGRATION_ROVODEV_EXTRA_ARGS", "--quiet --no-color")
+        impl = get_integration(self.KEY)
+        args = impl.build_exec_args("hello", output_json=False)
+        assert args == [
+            "acli", "rovodev", "run", "hello", "--quiet", "--no-color",
+        ]
+
+    # -- Setup-level: prompt wrappers + prompts.yml ------------------------
+
+    def test_setup_creates_prompts_and_manifest(self, tmp_path):
+        impl = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        created = impl.setup(tmp_path, manifest)
+
+        prompts_manifest = tmp_path / ".rovodev" / "prompts.yml"
+        assert prompts_manifest in created
+        assert prompts_manifest.exists()
+
+        prompts_dir = tmp_path / ".rovodev" / "prompts"
+        skills_dir = tmp_path / ".rovodev" / "skills"
+        assert prompts_dir.is_dir()
+        assert skills_dir.is_dir()
+
+        templates = impl.list_command_templates()
+        prompt_files = sorted(prompts_dir.glob("speckit-*.prompt.md"))
+        skill_dirs = sorted(d for d in skills_dir.iterdir() if d.is_dir() and d.name.startswith("speckit-"))
+        assert len(prompt_files) == len(templates)
+        assert len(skill_dirs) == len(templates)
+        for skill_dir in skill_dirs:
+            assert (skill_dir / "SKILL.md").exists()
+
+    def test_prompts_manifest_entries_well_formed(self, tmp_path):
+        impl = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        impl.setup(tmp_path, manifest)
+
+        prompts_manifest = tmp_path / ".rovodev" / "prompts.yml"
+        data = yaml.safe_load(prompts_manifest.read_text(encoding="utf-8"))
+        assert list(data) == ["prompts"]
+        entries = data["prompts"]
+        assert entries
+        for entry in entries:
+            assert entry["name"].startswith("speckit-")
+            assert entry["description"]
+            content_file = tmp_path / ".rovodev" / entry["content_file"]
+            assert content_file.exists(), f"Missing prompt file {content_file}"
+
+    def test_prompt_wrapper_format(self, tmp_path):
+        """Every prompt wrapper delegates to its paired skill via 'use skill ...'."""
+        impl = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        impl.setup(tmp_path, manifest)
+
+        prompts_dir = tmp_path / ".rovodev" / "prompts"
+        prompt_files = sorted(prompts_dir.glob("speckit-*.prompt.md"))
+        assert prompt_files
+        for prompt_file in prompt_files:
+            skill_name = prompt_file.name.removesuffix(".prompt.md")
+            content = prompt_file.read_text(encoding="utf-8")
+            assert content == f"use skill {skill_name} $ARGUMENTS\n", (
+                f"{prompt_file} has unexpected wrapper format"
+            )
+
+    def test_prompts_manifest_merge_preserves_user_entries(self, tmp_path):
+        impl = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+
+        prompts_manifest = tmp_path / ".rovodev" / "prompts.yml"
+        prompts_manifest.parent.mkdir(parents=True, exist_ok=True)
+        user_entry = {
+            "name": "my-custom-prompt",
+            "description": "User-added prompt",
+            "content_file": "prompts/my-custom-prompt.md",
+        }
+        prompts_manifest.write_text(
+            yaml.safe_dump({"prompts": [user_entry]}, sort_keys=False),
+            encoding="utf-8",
+        )
+
+        impl.setup(tmp_path, manifest)
+
+        data = yaml.safe_load(prompts_manifest.read_text(encoding="utf-8"))
+        names = {entry.get("name") for entry in data.get("prompts", [])}
+        assert "my-custom-prompt" in names
+        assert "speckit-plan" in names
+
+    def test_modified_prompts_yml_survives_uninstall(self, tmp_path):
+        impl = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        impl.install(tmp_path, manifest)
+        manifest.save()
+        modified = tmp_path / ".rovodev" / "prompts.yml"
+        modified.write_text("user modified this", encoding="utf-8")
+        _, skipped = impl.uninstall(tmp_path, manifest)
+        assert modified.exists()
+        assert modified in skipped
+
+    # -- Full-CLI init: skills + prompts integration with extensions -------
+
+    def test_init_inventory(self, rovodev_init_project):
+        """Rovodev + extensions produce the expected skill / prompt set.
+
+        Contract:
+          - Rovodev.setup() emits one SKILL.md + one .prompt.md per core template.
+          - Extensions install additional SKILL.md directories with NO prompt wrapper.
+        """
+        project = rovodev_init_project
+        impl = get_integration(self.KEY)
+        core_skill_names = {
+            f"speckit-{t.stem.replace('.', '-')}"
+            for t in impl.list_command_templates()
+        }
+
+        prompt_files = sorted((project / ".rovodev" / "prompts").glob("speckit-*.prompt.md"))
+        prompt_stems = {p.name.removesuffix(".prompt.md") for p in prompt_files}
+
+        skills_dir = project / ".rovodev" / "skills"
+        skill_names = {
+            d.name for d in skills_dir.iterdir()
+            if d.is_dir() and d.name.startswith("speckit-")
+        }
+
+        # Prompts: exactly the core template set.
+        assert prompt_stems == core_skill_names
+
+        # Skills: exactly the core template set (no extension auto-install).
+        assert skill_names == core_skill_names
+
+        # prompts.yml mirrors the prompt files exactly.
+        prompts_manifest = project / ".rovodev" / "prompts.yml"
+        data = yaml.safe_load(prompts_manifest.read_text(encoding="utf-8"))
+        assert {e["name"] for e in data["prompts"]} == core_skill_names
+
+    def test_init_skill_files_well_formed(self, rovodev_init_project):
+        """Every speckit-* SKILL.md from full init has valid frontmatter +
+        processed body, including extension-installed skills."""
+        project = rovodev_init_project
+        skills_dir = project / ".rovodev" / "skills"
+        skill_dirs = sorted(
+            d for d in skills_dir.iterdir()
+            if d.is_dir() and d.name.startswith("speckit-")
+        )
+        assert skill_dirs
+
+        for skill_dir in skill_dirs:
+            skill_file = skill_dir / "SKILL.md"
+            assert skill_file.exists(), f"Missing {skill_file}"
+            content = skill_file.read_text(encoding="utf-8")
+
+            # Frontmatter delimited by leading '---\n' ... '\n---\n'
+            assert content.startswith("---\n"), f"{skill_file} missing frontmatter"
+            fm_end = content.find("\n---\n", 4)
+            assert fm_end != -1, f"{skill_file} has unterminated frontmatter"
+            fm = yaml.safe_load(content[4:fm_end])
+            body = content[fm_end + len("\n---\n"):]
+
+            assert fm.get("name") == skill_dir.name
+            assert fm.get("description")
+            assert body.strip(), f"{skill_file} has empty body"
+
+            for placeholder in ("{SCRIPT}", "__AGENT__", "__CONTEXT_FILE__", "__SPECKIT_COMMAND_"):
+                assert placeholder not in body, (
+                    f"{skill_file} body contains unprocessed placeholder {placeholder!r}"
+                )
+            # Skills agents must use hyphen-style refs in body.
+            assert "/speckit." not in body, (
+                f"{skill_file} body contains dot-notation /speckit. reference"
+            )
+
+    # -- Full-CLI init: integration metadata -------------------------------
+
+    def test_init_writes_integration_manifest_and_options(self, rovodev_init_project):
+        """Full init must produce an integration manifest and well-formed
+        init-options.json — used by extensions, presets, and uninstall."""
+        import json
+
+        project = rovodev_init_project
+
+        manifest_path = project / ".specify" / "integrations" / "rovodev.manifest.json"
+        speckit_manifest = project / ".specify" / "integrations" / "speckit.manifest.json"
+        assert manifest_path.exists(), "rovodev integration manifest missing"
+        assert speckit_manifest.exists(), "speckit shared manifest missing"
+
+        init_options = json.loads(
+            (project / ".specify" / "init-options.json").read_text(encoding="utf-8")
+        )
+        assert init_options["integration"] == self.KEY
+        assert init_options["ai"] == self.KEY
+        # Rovodev is a SkillsIntegration, so ai_skills is auto-set.
+        assert init_options.get("ai_skills") is True
+        assert init_options.get("script") == "sh"
+
+    def test_integration_flag_creates_expected_files(self, tmp_path):
+        """``--integration rovodev`` should create all expected rovodev files."""
+        project = tmp_path / "rovodev-int"
+        project.mkdir()
+        result = _run_init(project, "--integration", "rovodev")
+        assert result.exit_code == 0, result.output
+        assert (project / ".rovodev" / "skills" / "speckit-plan" / "SKILL.md").exists()
+        assert (project / ".rovodev" / "prompts.yml").exists()
+        assert (project / ".specify" / "integrations" / "rovodev.manifest.json").exists()

tests/integrations/test_integration_scaffold.py

@@ -0,0 +1,238 @@
+"""Tests for integration scaffolding commands."""
+
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli import app
+from specify_cli.integration_scaffold import scaffold_integration
+from tests.conftest import strip_ansi
+
+
+runner = CliRunner()
+
+
+def _repo_root(tmp_path: Path) -> Path:
+    root = tmp_path / "spec-kit"
+    (root / "src" / "specify_cli" / "integrations").mkdir(parents=True)
+    (root / "tests" / "integrations").mkdir(parents=True)
+    (root / "pyproject.toml").write_text("[project]\nname = \"specify-cli\"\n", encoding="utf-8")
+    (root / "src" / "specify_cli" / "__init__.py").write_text("", encoding="utf-8")
+    (root / "src" / "specify_cli" / "integrations" / "__init__.py").write_text(
+        "",
+        encoding="utf-8",
+    )
+    return root
+
+
+def test_integration_scaffold_creates_markdown_files(tmp_path, monkeypatch):
+    root = _repo_root(tmp_path)
+    monkeypatch.chdir(root)
+
+    result = runner.invoke(app, [
+        "integration", "scaffold", "my-agent",
+        "--type", "markdown",
+    ], catch_exceptions=False)
+
+    output = strip_ansi(result.output)
+    integration_file = root / "src" / "specify_cli" / "integrations" / "my_agent" / "__init__.py"
+    test_file = root / "tests" / "integrations" / "test_integration_my_agent.py"
+
+    assert result.exit_code == 0
+    assert integration_file.exists()
+    assert test_file.exists()
+    assert "Created integration scaffold: my-agent" in output
+    assert "Register MyAgentIntegration" in output
+
+    content = integration_file.read_text(encoding="utf-8")
+    assert "class MyAgentIntegration(MarkdownIntegration):" in content
+    assert 'key = "my-agent"' in content
+    assert '"folder": ".my-agent/"' in content
+    assert '"extension": ".md"' in content
+    assert "multi_install_safe = False" in content
+
+    test_content = test_file.read_text(encoding="utf-8")
+    assert "from specify_cli.integrations.my_agent import MyAgentIntegration" in test_content
+    assert 'assert integration.registrar_config["dir"] == ".my-agent/commands"' in test_content
+    assert "assert integration.multi_install_safe is False" in test_content
+
+
+@pytest.mark.parametrize(
+    ("integration_type", "base_class", "commands_subdir", "args", "extension"),
+    [
+        ("markdown", "MarkdownIntegration", "commands", "$ARGUMENTS", ".md"),
+        ("toml", "TomlIntegration", "commands", "{{args}}", ".toml"),
+        ("yaml", "YamlIntegration", "recipes", "{{args}}", ".yaml"),
+        ("skills", "SkillsIntegration", "skills", "$ARGUMENTS", "/SKILL.md"),
+    ],
+)
+def test_scaffold_type_templates(
+    tmp_path,
+    integration_type,
+    base_class,
+    commands_subdir,
+    args,
+    extension,
+):
+    root = _repo_root(tmp_path)
+
+    result = scaffold_integration(root, f"{integration_type}-agent", integration_type)
+
+    content = result.integration_file.read_text(encoding="utf-8")
+    assert f"class {result.class_name}({base_class}):" in content
+    assert f'"commands_subdir": "{commands_subdir}"' in content
+    assert f'"args": "{args}"' in content
+    assert f'"extension": "{extension}"' in content
+    assert "multi_install_safe = False" in content
+
+
+def test_integration_scaffold_rejects_unknown_type_before_scaffolding(tmp_path, monkeypatch):
+    root = _repo_root(tmp_path)
+    monkeypatch.chdir(root)
+
+    result = runner.invoke(app, [
+        "integration", "scaffold", "my-agent",
+        "--type", "xml",
+    ])
+
+    output = strip_ansi(result.output)
+    assert result.exit_code == 2
+    assert "Invalid value for '--type'" in output
+    assert not (root / "src" / "specify_cli" / "integrations" / "my_agent").exists()
+
+
+def test_integration_scaffold_reports_filesystem_errors_cleanly(tmp_path, monkeypatch):
+    root = _repo_root(tmp_path)
+    monkeypatch.chdir(root)
+
+    import specify_cli.integration_scaffold as scaffold_module
+
+    def boom(*args, **kwargs):
+        raise PermissionError("Permission denied: read-only checkout")
+
+    monkeypatch.setattr(scaffold_module, "scaffold_integration", boom)
+
+    result = runner.invoke(app, [
+        "integration", "scaffold", "my-agent",
+        "--type", "markdown",
+    ], catch_exceptions=False)
+
+    output = strip_ansi(result.output)
+    assert result.exit_code == 1
+    assert "Error:" in output
+    assert "Permission denied" in output
+
+
+def test_scaffold_refuses_invalid_key(tmp_path):
+    root = _repo_root(tmp_path)
+
+    with pytest.raises(ValueError, match="lowercase kebab-case"):
+        scaffold_integration(root, "Bad_Key", "markdown")
+
+
+def test_scaffold_refuses_unknown_type(tmp_path):
+    root = _repo_root(tmp_path)
+
+    with pytest.raises(ValueError, match="Unsupported integration type 'xml'"):
+        scaffold_integration(root, "my-agent", " XML ")
+
+
+def test_scaffold_refuses_overwrite(tmp_path):
+    root = _repo_root(tmp_path)
+    scaffold_integration(root, "my-agent", "markdown")
+
+    with pytest.raises(FileExistsError, match="Refusing to overwrite"):
+        scaffold_integration(root, "my-agent", "markdown")
+
+
+def test_scaffold_rolls_back_partial_files_on_write_failure(tmp_path, monkeypatch):
+    root = _repo_root(tmp_path)
+    integration_dir = root / "src" / "specify_cli" / "integrations" / "my_agent"
+    integration_file = integration_dir / "__init__.py"
+    test_file = root / "tests" / "integrations" / "test_integration_my_agent.py"
+    original_write_text = Path.write_text
+
+    def fail_test_write(path, *args, **kwargs):
+        if path == test_file:
+            raise PermissionError("simulated test file write failure")
+        return original_write_text(path, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "write_text", fail_test_write)
+
+    with pytest.raises(PermissionError, match="simulated test file write failure"):
+        scaffold_integration(root, "my-agent", "markdown")
+
+    assert not integration_file.exists()
+    assert not integration_dir.exists()
+    assert not test_file.exists()
+
+
+def test_scaffold_creates_only_leaf_integration_directory(tmp_path, monkeypatch):
+    root = _repo_root(tmp_path)
+    original_mkdir = Path.mkdir
+    mkdir_calls = []
+
+    def record_mkdir(path, *args, **kwargs):
+        mkdir_calls.append((path, args, kwargs))
+        return original_mkdir(path, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "mkdir", record_mkdir)
+
+    scaffold_integration(root, "my-agent", "markdown")
+
+    assert any(
+        path == root / "src" / "specify_cli" / "integrations" / "my_agent"
+        for path, _args, _kwargs in mkdir_calls
+    )
+    assert all(not kwargs.get("parents", False) for _path, _args, kwargs in mkdir_calls)
+
+
+def test_scaffold_requires_repo_root(tmp_path):
+    with pytest.raises(ValueError, match="Spec Kit repository root"):
+        scaffold_integration(tmp_path, "my-agent", "markdown")
+
+
+def test_scaffold_requires_integration_registry_file(tmp_path):
+    root = _repo_root(tmp_path)
+    (root / "src" / "specify_cli" / "integrations" / "__init__.py").unlink()
+
+    with pytest.raises(ValueError, match="Spec Kit repository root"):
+        scaffold_integration(root, "my-agent", "markdown")
+
+
+def test_scaffold_refuses_symlinked_target_directory(tmp_path):
+    root = _repo_root(tmp_path)
+    # `outside` carries its own __init__.py so the repo-root heuristic still
+    # passes through the symlink, isolating the symlink guard under test.
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    (outside / "__init__.py").write_text("", encoding="utf-8")
+    integrations = root / "src" / "specify_cli" / "integrations"
+    (integrations / "__init__.py").unlink()
+    integrations.rmdir()
+    try:
+        integrations.symlink_to(outside, target_is_directory=True)
+    except OSError as exc:
+        pytest.skip(f"symlinks unavailable: {exc}")
+
+    with pytest.raises(ValueError, match="symlinked path"):
+        scaffold_integration(root, "my-agent", "markdown")
+
+    assert not (outside / "my_agent").exists()
+
+
+def test_integration_scaffold_accepts_uppercase_type(tmp_path, monkeypatch):
+    root = _repo_root(tmp_path)
+    monkeypatch.chdir(root)
+
+    result = runner.invoke(app, [
+        "integration", "scaffold", "my-agent",
+        "--type", "YAML",
+    ], catch_exceptions=False)
+
+    assert result.exit_code == 0, strip_ansi(result.output)
+    content = (
+        root / "src" / "specify_cli" / "integrations" / "my_agent" / "__init__.py"
+    ).read_text(encoding="utf-8")
+    assert "class MyAgentIntegration(YamlIntegration):" in content

tests/integrations/test_integration_shai.py

@@ -0,0 +1,10 @@
+"""Tests for ShaiIntegration."""
+
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestShaiIntegration(MarkdownIntegrationTests):
+    KEY = "shai"
+    FOLDER = ".shai/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".shai/commands"

tests/integrations/test_integration_state.py

@@ -0,0 +1,86 @@
+"""Tests for integration state normalization helpers."""
+
+import json
+
+from specify_cli.integration_state import (
+    INTEGRATION_JSON,
+    default_integration_key,
+    integration_setting,
+    normalize_integration_state,
+    write_integration_json,
+)
+
+
+def test_normalize_integration_state_strips_default_key_without_duplicates():
+    state = normalize_integration_state(
+        {
+            "default_integration": " claude ",
+            "integration": " claude ",
+            "installed_integrations": ["claude"],
+        }
+    )
+
+    assert state["integration"] == "claude"
+    assert state["default_integration"] == "claude"
+    assert state["installed_integrations"] == ["claude"]
+
+
+def test_normalize_integration_state_strips_legacy_key_fallback():
+    state = normalize_integration_state(
+        {
+            "integration": " codex ",
+            "installed_integrations": [],
+        }
+    )
+
+    assert state["integration"] == "codex"
+    assert state["default_integration"] == "codex"
+    assert state["installed_integrations"] == ["codex"]
+
+
+def test_normalize_integration_state_preserves_newer_schema():
+    state = normalize_integration_state(
+        {
+            "integration_state_schema": 99,
+            "integration": "claude",
+            "installed_integrations": ["claude"],
+            "future_field": {"keep": True},
+        }
+    )
+
+    assert state["integration_state_schema"] == 99
+    assert state["future_field"] == {"keep": True}
+
+
+def test_default_integration_key_strips_raw_state_values():
+    assert default_integration_key({"default_integration": " claude "}) == "claude"
+    assert default_integration_key({"integration": " codex "}) == "codex"
+
+
+def test_integration_settings_strip_invoke_separator():
+    setting = integration_setting(
+        {
+            "integration_settings": {
+                "claude": {
+                    "invoke_separator": " - ",
+                }
+            }
+        },
+        "claude",
+    )
+
+    assert setting["invoke_separator"] == "-"
+
+
+def test_write_integration_json_strips_integration_key(tmp_path):
+    write_integration_json(
+        tmp_path,
+        version="1.2.3",
+        integration_key=" claude ",
+        installed_integrations=["claude"],
+    )
+
+    state = json.loads((tmp_path / INTEGRATION_JSON).read_text(encoding="utf-8"))
+    assert state["integration"] == "claude"
+    assert state["default_integration"] == "claude"
+    assert state["installed_integrations"] == ["claude"]

tests/integrations/test_integration_tabnine.py

@@ -0,0 +1,10 @@
+"""Tests for TabnineIntegration."""
+
+from .test_integration_base_toml import TomlIntegrationTests
+
+
+class TestTabnineIntegration(TomlIntegrationTests):
+    KEY = "tabnine"
+    FOLDER = ".tabnine/agent/"
+    COMMANDS_SUBDIR = "commands"
+    REGISTRAR_DIR = ".tabnine/agent/commands"

tests/integrations/test_integration_trae.py

@@ -0,0 +1,10 @@
+"""Tests for TraeIntegration."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestTraeIntegration(SkillsIntegrationTests):
+    KEY = "trae"
+    FOLDER = ".trae/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".trae/skills"

tests/integrations/test_integration_vibe.py

@@ -0,0 +1,37 @@
+"""Tests for VibeIntegration."""
+
+import yaml
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestVibeIntegration(SkillsIntegrationTests):
+    KEY = "vibe"
+    FOLDER = ".vibe/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".vibe/skills"
+
+
+class TestVibeUserInvocable:
+    def test_all_skills_have_user_invocable(self, tmp_path):
+        i = get_integration("vibe")
+        m = IntegrationManifest("vibe", tmp_path)
+        created = i.setup(tmp_path, m, script_type="sh")
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert skill_files
+        for f in skill_files:
+            content = f.read_text(encoding="utf-8")
+            assert content.startswith("---"), (
+                f"{f.parent.name}/SKILL.md is missing the opening frontmatter delimiter '---'"
+            )
+            parts = content.split("---", 2)
+            assert len(parts) >= 3, (
+                f"{f.parent.name}/SKILL.md has malformed frontmatter; expected a '--- ... ---' block"
+            )
+            parsed = yaml.safe_load(parts[1])
+            assert parsed.get("user-invocable") is True, (
+                f"{f.parent.name}/SKILL.md is missing user-invocable: true in frontmatter"
+            )

tests/integrations/test_integration_zcode.py

@@ -0,0 +1,37 @@
+"""Tests for ZcodeIntegration — skills-based integration (Z.AI)."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestZcodeIntegration(SkillsIntegrationTests):
+    KEY = "zcode"
+    FOLDER = ".zcode/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".zcode/skills"
+
+
+class TestZcodeInvocation:
+    """ZCode renders $speckit-* chat invocations (like Codex)."""
+
+    def test_next_steps_show_dollar_skill_invocation(self, tmp_path):
+        """ZCode next-steps guidance should display $speckit-* usage."""
+        import os
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "zcode-next-steps"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--integration", "zcode",
+                "--ignore-agent-tools", "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0
+        assert "$speckit-constitution" in result.output
+        assert "/speckit.constitution" not in result.output

tests/integrations/test_integration_zed.py

@@ -0,0 +1,163 @@
+"""Tests for ZedIntegration."""
+
+import json
+
+import pytest
+
+from specify_cli.integrations import get_integration
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestZedIntegration(SkillsIntegrationTests):
+    KEY = "zed"
+    FOLDER = ".agents/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".agents/skills"
+
+    def test_options_include_skills_flag(self):
+        """Not applicable to Zed — Zed is always skills-based with no --skills flag."""
+        pytest.skip("Zed is always skills-based and does not expose a --skills option")
+
+    def test_options_do_not_include_skills_flag(self):
+        """Zed is always skills-based; no --skills option is exposed."""
+        i = get_integration(self.KEY)
+        assert i is not None
+        opts = i.options()
+        skills_opts = [o for o in opts if o.name == "--skills"]
+        assert len(skills_opts) == 0, (
+            "Zed is always skills-based and should not expose a --skills option"
+        )
+
+    def test_requires_cli_is_false(self):
+        """Zed is IDE-based; requires_cli must remain False."""
+        i = get_integration(self.KEY)
+        assert i is not None
+        assert i.config is not None
+        assert i.config["requires_cli"] is False
+
+
+class TestZedHookInvocations:
+    """Zed hook messages should reference slash-invokable skills."""
+
+    def test_hooks_render_skill_invocation(self, tmp_path):
+        """Zed is always skills-based: renders /speckit-plan even with ai_skills=False."""
+        from specify_cli.extensions import HookExecutor
+
+        project = tmp_path / "zed-hooks"
+        project.mkdir()
+        init_options = project / ".specify" / "init-options.json"
+        init_options.parent.mkdir(parents=True, exist_ok=True)
+        init_options.write_text(json.dumps({"ai": "zed", "ai_skills": False}))
+
+        hook_executor = HookExecutor(project)
+        message = hook_executor.format_hook_message(
+            "before_plan",
+            [
+                {
+                    "extension": "test-ext",
+                    "command": "speckit.plan",
+                    "optional": False,
+                }
+            ],
+        )
+
+        assert "EXECUTE_COMMAND_INVOCATION: /speckit-plan" in message
+
+    def test_init_persists_ai_skills_for_zed(self, tmp_path, monkeypatch):
+        """specify init --integration zed must persist ai_skills: true,
+        so HookExecutor renders slash-skill invocations without manual
+        init-options manipulation."""
+        from typer.testing import CliRunner
+
+        from specify_cli import app
+        from specify_cli.extensions import HookExecutor
+
+        project = tmp_path / "zed-init-test"
+        project.mkdir()
+        monkeypatch.chdir(project)
+        runner = CliRunner()
+        result = runner.invoke(
+            app,
+            [
+                "init",
+                "--here",
+                "--integration",
+                "zed",
+                "--script",
+                "sh",
+                "--ignore-agent-tools",
+            ],
+            catch_exceptions=False,
+        )
+
+        assert result.exit_code == 0, f"init failed: {result.output}"
+
+        opts_path = project / ".specify" / "init-options.json"
+        assert opts_path.exists()
+        opts = json.loads(opts_path.read_text(encoding="utf-8"))
+        assert opts.get("ai") == "zed"
+        assert opts.get("ai_skills") is True, (
+            f"init must persist ai_skills=true for Zed, got: {opts.get('ai_skills')}"
+        )
+
+        hook_executor = HookExecutor(project)
+        message = hook_executor.format_hook_message(
+            "before_plan",
+            [
+                {
+                    "extension": "test-ext",
+                    "command": "speckit.plan",
+                    "optional": False,
+                }
+            ],
+        )
+        assert "Executing: `/speckit-plan`" in message, (
+            "Hook rendering must produce /speckit-plan for Zed without hint injection"
+        )
+        assert "EXECUTE_COMMAND_INVOCATION: /speckit-plan" in message
+
+
+class TestSlashSkillsSets:
+    """Parameterized coverage for ALWAYS_SLASH_AGENTS / CONDITIONAL_SLASH_AGENTS."""
+
+    @staticmethod
+    def _render_invocation(project_path, ai: str, ai_skills: bool) -> str:
+        """Return the rendered invocation for ``speckit.plan`` via HookExecutor."""
+        from specify_cli.extensions import HookExecutor
+
+        init_options = project_path / ".specify" / "init-options.json"
+        init_options.parent.mkdir(parents=True, exist_ok=True)
+        init_options.write_text(json.dumps({"ai": ai, "ai_skills": ai_skills}))
+        hook_executor = HookExecutor(project_path)
+        result = hook_executor.execute_hook(
+            {"extension": "test-ext", "command": "speckit.plan", "optional": False}
+        )
+        return result.get("invocation", "")
+
+    @pytest.mark.parametrize(
+        ("ai", "ai_skills", "expected"),
+        [
+            # ALWAYS_SLASH_AGENTS — unconditional on ai_skills
+            ("devin", True, "/speckit-plan"),
+            ("devin", False, "/speckit-plan"),
+            ("trae", True, "/speckit-plan"),
+            ("trae", False, "/speckit-plan"),
+            ("zed", True, "/speckit-plan"),
+            ("zed", False, "/speckit-plan"),
+            # CONDITIONAL_SLASH_AGENTS — only when ai_skills is enabled
+            ("agy", True, "/speckit-plan"),
+            ("agy", False, "/speckit.plan"),
+            ("claude", True, "/speckit-plan"),
+            ("claude", False, "/speckit.plan"),
+            ("copilot", True, "/speckit-plan"),
+            ("copilot", False, "/speckit.plan"),
+            ("cursor-agent", True, "/speckit-plan"),
+            ("cursor-agent", False, "/speckit.plan"),
+        ],
+    )
+    def test_hook_invocation_format(self, tmp_path, ai, ai_skills, expected):
+        result = self._render_invocation(tmp_path, ai, ai_skills)
+        assert result == expected, (
+            f"{ai} (ai_skills={ai_skills}): expected {expected!r}, got {result!r}"
+        )

tests/integrations/test_manifest.py

@@ -0,0 +1,520 @@
+"""Tests for IntegrationManifest — record, hash, save, load, uninstall, modified detection."""
+
+import hashlib
+import json
+import sys
+
+import pytest
+
+from specify_cli.integrations.manifest import IntegrationManifest, _sha256
+
+
+class TestManifestRecordFile:
+    def test_record_file_writes_and_hashes(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        content = "hello world"
+        abs_path = m.record_file("a/b.txt", content)
+        assert abs_path == tmp_path / "a" / "b.txt"
+        assert abs_path.read_text(encoding="utf-8") == content
+        expected_hash = hashlib.sha256(content.encode()).hexdigest()
+        assert m.files["a/b.txt"] == expected_hash
+
+    def test_record_file_bytes(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        data = b"\x00\x01\x02"
+        abs_path = m.record_file("bin.dat", data)
+        assert abs_path.read_bytes() == data
+        assert m.files["bin.dat"] == hashlib.sha256(data).hexdigest()
+
+    def test_record_existing(self, tmp_path):
+        f = tmp_path / "existing.txt"
+        f.write_text("content", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("existing.txt")
+        assert m.files["existing.txt"] == _sha256(f)
+
+
+class TestManifestRecordExistingErrors:
+    """Error-case coverage for ``record_existing`` symlink + non-file guards.
+
+    Added in #2483 — Copilot review flagged these as un-tested regressions
+    after the ``is_symlink``/``is_file`` guards were introduced.
+    """
+
+    def test_rejects_symlink_target(self, tmp_path):
+        target = tmp_path / "target.txt"
+        target.write_text("target content", encoding="utf-8")
+        link = tmp_path / "link.txt"
+        link.symlink_to(target)
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="symlinked"):
+            m.record_existing("link.txt")
+
+    def test_rejects_dangling_symlink(self, tmp_path):
+        # A symlink pointing nowhere should still be rejected before the
+        # ``is_file()`` check (which would itself be False on a dangler).
+        link = tmp_path / "dangler.txt"
+        link.symlink_to(tmp_path / "no-such-target.txt")
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="symlinked"):
+            m.record_existing("dangler.txt")
+
+    def test_rejects_directory_path(self, tmp_path):
+        (tmp_path / "a_dir").mkdir()
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="not a regular file"):
+            m.record_existing("a_dir")
+
+    def test_rejects_missing_path(self, tmp_path):
+        # ``is_file()`` is False for non-existent paths too; the same error
+        # surface keeps callers from having to distinguish "missing" from
+        # "wrong kind" — both mean "cannot hash this".
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="not a regular file"):
+            m.record_existing("never-existed.txt")
+
+    def test_lexical_prevalidation_for_absolute_path(self, tmp_path):
+        # ``record_existing`` must reject absolute paths via the lexical
+        # pre-check, NOT via the filesystem-touching ``is_symlink()`` call.
+        # Verified by passing an absolute path that points to a directory
+        # outside the project root — the canonical "Absolute paths" error
+        # must surface before any stat on the absolute path.
+        m = IntegrationManifest("test", tmp_path)
+        abs_path = "C:\\tmp\\escape.txt" if sys.platform == "win32" else "/tmp/escape.txt"
+        with pytest.raises(ValueError, match="Absolute paths"):
+            m.record_existing(abs_path)
+
+
+class TestManifestPathTraversal:
+    def test_record_file_rejects_parent_traversal(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="outside"):
+            m.record_file("../escape.txt", "bad")
+
+    def test_record_file_rejects_absolute_path(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        abs_path = "C:\\tmp\\escape.txt" if sys.platform == "win32" else "/tmp/escape.txt"
+        with pytest.raises(ValueError, match="Absolute paths"):
+            m.record_file(abs_path, "bad")
+
+    def test_record_existing_rejects_parent_traversal(self, tmp_path):
+        escape = tmp_path.parent / "escape.txt"
+        escape.write_text("evil", encoding="utf-8")
+        try:
+            m = IntegrationManifest("test", tmp_path)
+            with pytest.raises(ValueError, match="outside"):
+                m.record_existing("../escape.txt")
+        finally:
+            escape.unlink(missing_ok=True)
+
+    def test_uninstall_skips_traversal_paths(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("safe.txt", "good")
+        m._files["../outside.txt"] = "fakehash"
+        m.save()
+        removed, skipped = m.uninstall()
+        assert len(removed) == 1
+        assert removed[0].name == "safe.txt"
+
+    def test_remove_drops_entry_and_is_noop_second_time(self, tmp_path):
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt")
+        assert "f.txt" in m.files
+        assert m.remove("f.txt") is True
+        assert "f.txt" not in m.files
+        assert m.remove("f.txt") is False  # already gone → no-op
+
+    def test_remove_rejects_absolute_path(self, tmp_path):
+        # Matches record_existing/is_recovered: an absolute key can never be a
+        # canonical manifest key, so remove() rejects it lexically and leaves
+        # the tracked entry untouched.
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt")
+        import sys
+        abs_input = "C:\\tmp\\f.txt" if sys.platform == "win32" else "/tmp/f.txt"
+        assert m.remove(abs_input) is False
+        assert "f.txt" in m.files
+
+    def test_remove_rejects_parent_traversal(self, tmp_path):
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt")
+        assert m.remove("../f.txt") is False
+        assert "f.txt" in m.files
+
+
+class TestManifestCheckModified:
+    def test_unmodified_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        assert m.check_modified() == []
+
+    def test_modified_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        (tmp_path / "f.txt").write_text("changed", encoding="utf-8")
+        assert m.check_modified() == ["f.txt"]
+
+    def test_deleted_file_not_reported(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        (tmp_path / "f.txt").unlink()
+        assert m.check_modified() == []
+
+    def test_symlink_treated_as_modified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        target = tmp_path / "target.txt"
+        target.write_text("target", encoding="utf-8")
+        (tmp_path / "f.txt").unlink()
+        (tmp_path / "f.txt").symlink_to(target)
+        assert m.check_modified() == ["f.txt"]
+
+
+class TestManifestUninstall:
+    def test_removes_unmodified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("d/f.txt", "content")
+        m.save()
+        removed, skipped = m.uninstall()
+        assert len(removed) == 1
+        assert not (tmp_path / "d" / "f.txt").exists()
+        assert not (tmp_path / "d").exists()
+        assert skipped == []
+
+    def test_skips_modified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        (tmp_path / "f.txt").write_text("modified", encoding="utf-8")
+        removed, skipped = m.uninstall()
+        assert removed == []
+        assert len(skipped) == 1
+        assert (tmp_path / "f.txt").exists()
+
+    def test_force_removes_modified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        (tmp_path / "f.txt").write_text("modified", encoding="utf-8")
+        removed, skipped = m.uninstall(force=True)
+        assert len(removed) == 1
+        assert skipped == []
+
+    def test_already_deleted_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "content")
+        m.save()
+        (tmp_path / "f.txt").unlink()
+        removed, skipped = m.uninstall()
+        assert removed == []
+        assert skipped == []
+
+    def test_removes_manifest_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path, version="1.0")
+        m.record_file("f.txt", "content")
+        m.save()
+        assert m.manifest_path.exists()
+        m.uninstall()
+        assert not m.manifest_path.exists()
+
+    def test_cleans_empty_parent_dirs(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("a/b/c/f.txt", "content")
+        m.save()
+        m.uninstall()
+        assert not (tmp_path / "a").exists()
+
+    def test_preserves_nonempty_parent_dirs(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("a/b/tracked.txt", "content")
+        (tmp_path / "a" / "b" / "other.txt").write_text("keep", encoding="utf-8")
+        m.save()
+        m.uninstall()
+        assert not (tmp_path / "a" / "b" / "tracked.txt").exists()
+        assert (tmp_path / "a" / "b" / "other.txt").exists()
+
+    def test_symlink_skipped_without_force(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        target = tmp_path / "target.txt"
+        target.write_text("target", encoding="utf-8")
+        (tmp_path / "f.txt").unlink()
+        (tmp_path / "f.txt").symlink_to(target)
+        removed, skipped = m.uninstall()
+        assert removed == []
+        assert len(skipped) == 1
+
+    def test_symlink_removed_with_force(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        target = tmp_path / "target.txt"
+        target.write_text("target", encoding="utf-8")
+        (tmp_path / "f.txt").unlink()
+        (tmp_path / "f.txt").symlink_to(target)
+        removed, skipped = m.uninstall(force=True)
+        assert len(removed) == 1
+        assert target.exists()
+
+
+class TestManifestPersistence:
+    def test_save_and_load_roundtrip(self, tmp_path):
+        m = IntegrationManifest("myagent", tmp_path, version="2.0.1")
+        m.record_file("dir/file.md", "# Hello")
+        m.save()
+        loaded = IntegrationManifest.load("myagent", tmp_path)
+        assert loaded.key == "myagent"
+        assert loaded.version == "2.0.1"
+        assert loaded.files == m.files
+
+    def test_manifest_path(self, tmp_path):
+        m = IntegrationManifest("copilot", tmp_path)
+        assert m.manifest_path == tmp_path / ".specify" / "integrations" / "copilot.manifest.json"
+
+    def test_load_missing_raises(self, tmp_path):
+        with pytest.raises(FileNotFoundError):
+            IntegrationManifest.load("nonexistent", tmp_path)
+
+    def test_save_creates_directories(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "content")
+        path = m.save()
+        assert path.exists()
+        data = json.loads(path.read_text(encoding="utf-8"))
+        assert data["integration"] == "test"
+
+    def test_save_preserves_installed_at(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "content")
+        m.save()
+        first_ts = m._installed_at
+        m.save()
+        assert m._installed_at == first_ts
+
+
+class TestManifestLoadValidation:
+    def test_load_non_dict_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text('"just a string"', encoding="utf-8")
+        with pytest.raises(ValueError, match="JSON object"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_bad_files_type_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({"files": ["not", "a", "dict"]}), encoding="utf-8")
+        with pytest.raises(ValueError, match="mapping"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_bad_files_values_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({"files": {"a.txt": 123}}), encoding="utf-8")
+        with pytest.raises(ValueError, match="mapping"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_invalid_json_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text("{not valid json", encoding="utf-8")
+        with pytest.raises(ValueError, match="invalid JSON"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_filters_recovered_files_not_in_files(self, tmp_path):
+        # Finding B (Round-9): a recovered_files entry referencing a path
+        # not present in files indicates an internally-inconsistent manifest
+        # (e.g. external edit). load() filters those entries silently so the
+        # manifest self-heals on next save(); is_recovered then returns the
+        # truthful False for the orphan.
+        path = tmp_path / ".specify" / "integrations" / "test.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({
+            "integration": "test",
+            "files": {"kept.txt": "abc123"},
+            "recovered_files": ["kept.txt", "orphan.txt"],
+        }), encoding="utf-8")
+        m = IntegrationManifest.load("test", tmp_path)
+        assert m.recovered_files == {"kept.txt"}
+        assert m.is_recovered("kept.txt") is True
+        assert m.is_recovered("orphan.txt") is False
+
+
+class TestManifestRecoveredFiles:
+    """Coverage for the ``recovered_files`` channel added in #2483.
+
+    When ``shared_infra`` skips an existing file (because the user already has
+    it on disk) it now records the file with ``recovered=True``. The path
+    appears in ``manifest.recovered_files`` and ``is_recovered(path)`` returns
+    True. ``refresh_managed`` (out of scope for this PR) consults this list
+    before treating the recorded hash as a managed baseline, defending against
+    silent overwrite of user customizations after manifest loss.
+    """
+
+    def test_record_existing_default_is_not_recovered(self, tmp_path):
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt")
+        assert m.is_recovered("f.txt") is False
+        assert m.recovered_files == set()
+
+    def test_record_existing_with_recovered_flag(self, tmp_path):
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt", recovered=True)
+        assert m.is_recovered("f.txt") is True
+        assert m.recovered_files == {"f.txt"}
+        # File still hashed normally so check_modified/uninstall keep working
+        assert m.files["f.txt"] == _sha256(tmp_path / "f.txt")
+
+    def test_recovered_files_round_trips_through_save_load(self, tmp_path):
+        (tmp_path / "a.txt").write_text("aaa", encoding="utf-8")
+        (tmp_path / "b.txt").write_text("bbb", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path, version="9.9")
+        m.record_existing("a.txt", recovered=True)
+        m.record_existing("b.txt")  # not recovered
+        m.save()
+        loaded = IntegrationManifest.load("test", tmp_path)
+        assert loaded.is_recovered("a.txt") is True
+        assert loaded.is_recovered("b.txt") is False
+        assert loaded.recovered_files == {"a.txt"}
+
+    def test_save_omits_empty_recovered_files(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "x")
+        path = m.save()
+        data = json.loads(path.read_text(encoding="utf-8"))
+        assert "recovered_files" not in data
+
+    def test_load_rejects_non_list_recovered_files(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(
+            json.dumps({"files": {}, "recovered_files": "not-a-list"}),
+            encoding="utf-8",
+        )
+        with pytest.raises(ValueError, match="recovered_files"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_is_recovered_absolute_path_returns_false(self, tmp_path):
+        # Copilot round-5 finding: passing an absolute path silently returned
+        # False because the stored keys are relative POSIX strings. Round-7
+        # made this explicit: ``is_recovered`` now rejects absolute paths
+        # up front via a lexical ``rel.is_absolute()`` guard and returns
+        # False without calling ``_validate_rel_path`` at all — matching
+        # ``record_existing``'s canonical-key guard so the two methods
+        # agree on which inputs can ever be stored keys.
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt", recovered=True)
+        import sys
+        abs_input = "C:\\tmp\\f.txt" if sys.platform == "win32" else "/tmp/f.txt"
+        assert m.is_recovered(abs_input) is False
+
+    def test_is_recovered_escaping_path_returns_false(self, tmp_path):
+        # A relative path containing ``..`` segments cannot be a stored key:
+        # Round-7 added the same lexical ``".." in rel.parts`` guard to
+        # ``is_recovered`` that ``record_existing`` already enforces, so the
+        # method returns False immediately without reaching
+        # ``_validate_rel_path``. The try/except around ``_validate_rel_path``
+        # remains as defense-in-depth for paths that pass the lexical guard
+        # but still resolve outside the project root via a symlinked
+        # ancestor.
+        m = IntegrationManifest("test", tmp_path)
+        # Don't record anything — the path is impossible to record anyway.
+        assert m.is_recovered("../escape.txt") is False
+
+    def test_record_existing_clears_recovered_when_false(self, tmp_path):
+        # Finding A: re-recording the same path with recovered=False must
+        # drop the prior recovered marker (transition to managed baseline).
+        f = tmp_path / "x.txt"
+        f.write_text("v1", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("x.txt", recovered=True)
+        assert m.is_recovered("x.txt") is True
+        m.record_existing("x.txt", recovered=False)
+        assert m.is_recovered("x.txt") is False
+
+    def test_record_file_clears_recovered(self, tmp_path):
+        # Finding A: record_file writes produced content; the path can no
+        # longer be considered "merely observed" once we wrote bytes.
+        (tmp_path / "y.txt").write_text("observed", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("y.txt", recovered=True)
+        assert m.is_recovered("y.txt") is True
+        m.record_file("y.txt", "produced")
+        assert m.is_recovered("y.txt") is False
+
+    def test_is_recovered_rejects_dotdot_segment(self, tmp_path):
+        # Finding B: record_existing rejects ``..`` segments via the lexical
+        # pre-check; is_recovered must match that behavior and return False
+        # without raising, mirroring the canonicalization guard.
+        (tmp_path / "z.txt").write_text("v1", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("z.txt", recovered=True)
+        # Same file via dotdot-normalizing path — must be False, not raise.
+        assert m.is_recovered("subdir/../z.txt") is False
+
+
+class TestRecordExistingNewGuards:
+    """Coverage for the two new guards added by Copilot's 2026-05-18 review."""
+
+    def test_rejects_symlinked_ancestor(self, tmp_path):
+        real_dir = tmp_path / "real_dir"
+        real_dir.mkdir()
+        (real_dir / "file.txt").write_text("payload", encoding="utf-8")
+        (tmp_path / "linked_dir").symlink_to(real_dir, target_is_directory=True)
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="symlinked"):
+            m.record_existing("linked_dir/file.txt")
+
+    def test_rejects_inside_root_dotdot_with_explicit_message(self, tmp_path):
+        # ``dir/../file.txt`` normalizes inside root, so the old "escapes
+        # project root" message was misleading. The new message names the
+        # actual reason: canonicalization.
+        (tmp_path / "dir").mkdir()
+        (tmp_path / "file.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match=r"canonical|'\.\.' segments"):
+            m.record_existing("dir/../file.txt")
+
+
+class TestManifestUnreadableFile:
+    """A managed file that is unreadable (e.g. PermissionError) must not crash
+    check_modified()/uninstall() — the CLI handlers surfaced a raw traceback."""
+
+    def _mk(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("sub/f.md", "content")
+        return m
+
+    def test_check_modified_treats_unreadable_as_modified(self, tmp_path, monkeypatch):
+        m = self._mk(tmp_path)
+
+        def raise_perm(_path):
+            raise PermissionError("unreadable")
+
+        monkeypatch.setattr(
+            "specify_cli.integrations.manifest._sha256", raise_perm
+        )
+        # Before the fix this raised PermissionError.
+        assert m.check_modified() == ["sub/f.md"]
+
+    def test_uninstall_preserves_unreadable_file(self, tmp_path, monkeypatch):
+        m = self._mk(tmp_path)
+
+        def raise_perm(_path):
+            raise PermissionError("unreadable")
+
+        monkeypatch.setattr(
+            "specify_cli.integrations.manifest._sha256", raise_perm
+        )
+        removed, skipped = m.uninstall(force=False)
+        # Can't verify ownership => preserve, don't crash and don't delete.
+        assert removed == []
+        assert (tmp_path / "sub" / "f.md") in skipped
+        assert (tmp_path / "sub" / "f.md").exists()

tests/integrations/test_registry.py

@@ -0,0 +1,296 @@
+"""Tests for INTEGRATION_REGISTRY — mechanics, completeness, and registrar alignment."""
+
+import json
+import os
+from pathlib import PurePosixPath
+
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli import app
+from specify_cli.integrations import (
+    INTEGRATION_REGISTRY,
+    _register,
+    get_integration,
+)
+from specify_cli.integrations.base import MarkdownIntegration
+from .conftest import StubIntegration
+
+
+# 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",
+    "rovodev", "codebuddy", "qodercli", "amp", "shai", "bob", "trae",
+    "pi", "kiro-cli", "vibe", "cursor-agent", "firebender",
+    # Stage 4 — TOML integrations
+    "gemini", "tabnine",
+    # Stage 5 — skills, generic & option-driven integrations
+    "codex", "kimi", "agy", "zed", "generic",
+]
+
+
+def _multi_install_safe_keys() -> list[str]:
+    return sorted(
+        key
+        for key, integration in INTEGRATION_REGISTRY.items()
+        if integration.multi_install_safe
+    )
+
+
+def _multi_install_safe_pairs() -> list[tuple[str, str]]:
+    safe_keys = _multi_install_safe_keys()
+    return [
+        (safe_keys[left], safe_keys[right])
+        for left in range(len(safe_keys))
+        for right in range(left + 1, len(safe_keys))
+    ]
+
+
+def _multi_install_safe_orders() -> list[list[str]]:
+    safe_keys = _multi_install_safe_keys()
+    if len(safe_keys) < 2:
+        return [safe_keys]
+    return [safe_keys[index:] + safe_keys[:index] for index in range(len(safe_keys))]
+
+
+def _multi_install_safe_order_id(ordered_keys: list[str]) -> str:
+    if not ordered_keys:
+        return "no-safe-integrations"
+    return f"init-{ordered_keys[0]}"
+
+
+def _posix_path(value: str | None) -> str | None:
+    if not value:
+        return None
+    return PurePosixPath(value).as_posix()
+
+
+def _integration_root_dir(key: str) -> str | None:
+    integration = INTEGRATION_REGISTRY[key]
+    cfg = integration.config if isinstance(integration.config, dict) else {}
+    return _posix_path(cfg.get("folder"))
+
+
+def _integration_commands_dir(key: str) -> str | None:
+    integration = INTEGRATION_REGISTRY[key]
+    cfg = integration.config if isinstance(integration.config, dict) else {}
+    folder = cfg.get("folder")
+    if not folder:
+        return None
+    subdir = cfg.get("commands_subdir", "commands")
+    return (PurePosixPath(folder) / subdir).as_posix()
+
+
+def _paths_overlap(first: str | None, second: str | None) -> bool:
+    if not first or not second:
+        return False
+    left = PurePosixPath(first)
+    right = PurePosixPath(second)
+    try:
+        left.relative_to(right)
+        return True
+    except ValueError:
+        pass
+    try:
+        right.relative_to(left)
+        return True
+    except ValueError:
+        return False
+
+
+class TestRegistry:
+    def test_registry_is_dict(self):
+        assert isinstance(INTEGRATION_REGISTRY, dict)
+
+    def test_register_and_get(self):
+        stub = StubIntegration()
+        _register(stub)
+        try:
+            assert get_integration("stub") is stub
+        finally:
+            INTEGRATION_REGISTRY.pop("stub", None)
+
+    def test_get_missing_returns_none(self):
+        assert get_integration("nonexistent-xyz") is None
+
+    def test_register_empty_key_raises(self):
+        class EmptyKey(MarkdownIntegration):
+            key = ""
+        with pytest.raises(ValueError, match="empty key"):
+            _register(EmptyKey())
+
+    def test_register_duplicate_raises(self):
+        stub = StubIntegration()
+        _register(stub)
+        try:
+            with pytest.raises(KeyError, match="already registered"):
+                _register(StubIntegration())
+        finally:
+            INTEGRATION_REGISTRY.pop("stub", None)
+
+
+class TestRegistryCompleteness:
+    """Every expected integration must be registered."""
+
+    @pytest.mark.parametrize("key", ALL_INTEGRATION_KEYS)
+    def test_key_registered(self, key):
+        assert key in INTEGRATION_REGISTRY, f"{key} missing from registry"
+
+
+class TestRegistrarKeyAlignment:
+    """Every integration key must have a matching AGENT_CONFIGS entry.
+
+    ``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, (
+            f"Integration '{key}' is registered but has no AGENT_CONFIGS entry"
+        )
+
+    def test_no_stale_cursor_shorthand(self):
+        """The old 'cursor' shorthand must not appear in AGENT_CONFIGS."""
+        from specify_cli.agents import CommandRegistrar
+        assert "cursor" not in CommandRegistrar.AGENT_CONFIGS
+
+
+class TestMultiInstallSafeContracts:
+    """Declared safe integrations must stay isolated from each other."""
+
+    def test_safe_install_orders_rotate_each_integration_through_init(self):
+        safe_keys = _multi_install_safe_keys()
+        orders = _multi_install_safe_orders()
+
+        assert len(safe_keys) >= 2
+        assert [order[0] for order in orders] == safe_keys
+        assert len({tuple(order) for order in orders}) == len(safe_keys)
+        assert all(sorted(order) == safe_keys for order in orders)
+
+    @pytest.mark.parametrize("key", _multi_install_safe_keys())
+    def test_safe_integrations_have_static_isolated_paths(self, key):
+        assert _integration_root_dir(key), (
+            f"{key} is declared multi-install safe but has no static root directory"
+        )
+        assert _integration_commands_dir(key), (
+            f"{key} is declared multi-install safe but has no static commands directory"
+        )
+
+    @pytest.mark.parametrize(("first", "second"), _multi_install_safe_pairs())
+    def test_safe_integrations_have_distinct_agent_roots(self, first, second):
+        assert not _paths_overlap(_integration_root_dir(first), _integration_root_dir(second)), (
+            f"{first} and {second} are declared multi-install safe but have "
+            f"overlapping agent roots {_integration_root_dir(first)!r} and "
+            f"{_integration_root_dir(second)!r}"
+        )
+
+    @pytest.mark.parametrize(("first", "second"), _multi_install_safe_pairs())
+    def test_safe_integrations_have_distinct_command_dirs(self, first, second):
+        assert not _paths_overlap(_integration_commands_dir(first), _integration_commands_dir(second)), (
+            f"{first} and {second} are declared multi-install safe but have "
+            f"overlapping command directories {_integration_commands_dir(first)!r} and "
+            f"{_integration_commands_dir(second)!r}"
+        )
+
+    @pytest.mark.parametrize(
+        "ordered_keys",
+        _multi_install_safe_orders(),
+        ids=_multi_install_safe_order_id,
+    )
+    def test_safe_integrations_have_disjoint_manifests(
+        self,
+        tmp_path,
+        ordered_keys,
+    ):
+        # The pairwise disjointness contract is only meaningful with at least
+        # two safe integrations. Guard so a shrunken registry fails loudly here
+        # rather than passing vacuously (or tripping over ordered_keys[0] below).
+        assert len(ordered_keys) >= 2, (
+            f"expected at least two multi-install-safe integrations, got {ordered_keys}"
+        )
+
+        project_root = tmp_path / "project"
+        project_root.mkdir()
+        runner = CliRunner()
+
+        # Install every safe integration once into a single project, then assert
+        # pairwise manifest isolation. Each safe integration writes only to its
+        # own (disjoint) directories and always records what it writes, so a
+        # manifest's contents are independent of install order and of which other
+        # integrations are co-installed. The parametrized rotations keep the
+        # aggregate setup while placing each safe integration first once, so each
+        # one still exercises the `specify init --integration ...` path.
+        original_cwd = os.getcwd()
+        try:
+            os.chdir(project_root)
+            init_result = runner.invoke(
+                app,
+                [
+                    "init",
+                    "--here",
+                    "--integration",
+                    ordered_keys[0],
+                    "--script",
+                    "sh",
+                    "--ignore-agent-tools",
+                ],
+                catch_exceptions=False,
+            )
+            assert init_result.exit_code == 0, init_result.output
+
+            for key in ordered_keys[1:]:
+                install_result = runner.invoke(
+                    app,
+                    ["integration", "install", key, "--script", "sh"],
+                    catch_exceptions=False,
+                )
+                assert install_result.exit_code == 0, install_result.output
+        finally:
+            os.chdir(original_cwd)
+
+        integrations_dir = project_root / ".specify" / "integrations"
+        manifests = {}
+        for key in ordered_keys:
+            manifest = json.loads(
+                (integrations_dir / f"{key}.manifest.json").read_text(encoding="utf-8")
+            )
+            files = manifest.get("files", {})
+            assert isinstance(files, dict), f"{key} manifest files must be an object"
+            manifests[key] = set(files.keys())
+
+        for first, second in _multi_install_safe_pairs():
+            overlap = manifests[first] & manifests[second]
+            assert not overlap, (
+                f"{first} and {second} are declared multi-install safe but both manage "
+                f"these files: {sorted(overlap)}"
+            )
+
+
+class TestCatalogParity:
+    """The discovery catalog must list every registered integration."""
+
+    def test_every_registered_integration_is_in_catalog(self):
+        """``integrations/catalog.json`` must cover every registry key.
+
+        The catalog is the discovery manifest; an integration that is
+        registered, registrar-aligned and registry-tested but missing from
+        the catalog is undiscoverable through it. ``generic`` is exempt —
+        it is the no-fixed-directory fallback, not a catalogued agent.
+        """
+        from pathlib import Path
+
+        repo_root = Path(__file__).resolve().parents[2]
+        catalog = json.loads(
+            (repo_root / "integrations" / "catalog.json").read_text(encoding="utf-8")
+        )
+        catalogued = set(catalog["integrations"])
+        registered = set(INTEGRATION_REGISTRY) - {"generic"}
+        missing = sorted(registered - catalogued)
+        assert not missing, f"integrations missing from catalog.json: {missing}"

tests/integrations/test_skill_frontmatter_quoting.py

@@ -0,0 +1,111 @@
+"""Regression tests for SKILL.md frontmatter quoting (#3391).
+
+The skills setup path builds SKILL.md frontmatter by hand with
+double-quoted values. A double-quoted YAML scalar cannot carry a raw
+newline (the parser folds it to a space) or a control character (the
+reader rejects the document), so descriptions taken from template
+frontmatter must be escaped by the YAML emitter.
+"""
+
+from pathlib import Path
+
+import yaml
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.base import yaml_quote
+from specify_cli.integrations.manifest import IntegrationManifest
+
+MULTILINE = "first line\nsecond line\n"
+CONTROL = "ding\aling"
+
+HOSTILE_TEMPLATE = """---
+description: |
+  first line
+  second line
+---
+
+Body of the command.
+"""
+
+CONTROL_TEMPLATE = """---
+description: "ding\\aling"
+---
+
+Body of the command.
+"""
+
+
+def _parse_frontmatter(skill_file: Path) -> dict:
+    content = skill_file.read_text(encoding="utf-8")
+    assert content.startswith("---\n")
+    return yaml.safe_load(content.split("---", 2)[1])
+
+
+def _fake_templates(tmp_path: Path, body: str) -> Path:
+    templates = tmp_path / "templates"
+    templates.mkdir(exist_ok=True)
+    (templates / "plan.md").write_text(body, encoding="utf-8")
+    return templates
+
+
+class TestYamlQuote:
+    def test_simple_value_keeps_plain_double_quoted_form(self):
+        assert yaml_quote("speckit-plan") == '"speckit-plan"'
+        assert yaml_quote('say "hi"') == '"say \\"hi\\""'
+        assert yaml_quote("back\\slash") == '"back\\\\slash"'
+
+    def test_multiline_value_round_trips(self):
+        quoted = yaml_quote(MULTILINE)
+        assert "\n" not in quoted
+        assert yaml.safe_load(quoted) == MULTILINE
+
+    def test_control_character_round_trips(self):
+        quoted = yaml_quote(CONTROL)
+        assert "\a" not in quoted
+        assert yaml.safe_load(quoted) == CONTROL
+
+
+class TestSkillFrontmatterQuoting:
+    def _generate(self, tmp_path, monkeypatch, template: str) -> Path:
+        integration = get_integration("agy")
+        monkeypatch.setattr(
+            integration,
+            "shared_commands_dir",
+            lambda: _fake_templates(tmp_path, template),
+        )
+        manifest = IntegrationManifest("agy", tmp_path)
+        created = integration.setup(tmp_path, manifest)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert len(skill_files) == 1
+        return skill_files[0]
+
+    def test_multiline_description_survives(self, tmp_path, monkeypatch):
+        skill_file = self._generate(tmp_path, monkeypatch, HOSTILE_TEMPLATE)
+        fm = _parse_frontmatter(skill_file)
+        assert fm["description"] == MULTILINE
+
+    def test_control_character_description_parses(self, tmp_path, monkeypatch):
+        skill_file = self._generate(tmp_path, monkeypatch, CONTROL_TEMPLATE)
+        fm = _parse_frontmatter(skill_file)
+        assert fm["description"] == CONTROL
+
+
+class TestHermesSkillFrontmatterQuoting:
+    def test_multiline_description_survives(self, tmp_path, monkeypatch):
+        home = tmp_path / "home"
+        home.mkdir(exist_ok=True)
+        monkeypatch.setattr(Path, "home", lambda: home)
+
+        integration = get_integration("hermes")
+        monkeypatch.setattr(
+            integration,
+            "shared_commands_dir",
+            lambda: _fake_templates(tmp_path, HOSTILE_TEMPLATE),
+        )
+        manifest = IntegrationManifest("hermes", tmp_path)
+        created = integration.setup(tmp_path, manifest)
+        skill_files = [f for f in created if f.name == "SKILL.md"]
+        assert len(skill_files) == 1
+
+        fm = _parse_frontmatter(skill_files[0])
+        assert fm["description"] == MULTILINE