fix(integrations): defer extension registration until use

Author: PascalThuet

src/specify_cli/integrations/_helpers.py

@@ -386,7 +386,7 @@ def _set_default_integration_or_exit(*args: Any, **kwargs: Any) -> None:
 
 
 # ---------------------------------------------------------------------------
-# Extension (un)registration helpers (shared by switch / install / upgrade)
+# Extension (un)registration helpers (shared by use / switch / upgrade)
 # ---------------------------------------------------------------------------
 
 def _best_effort_extension_op(
@@ -423,21 +423,23 @@ def _register_extensions_for_agent(
 ) -> None:
     """Register all enabled extensions' commands/skills for ``agent_key``.
 
-    ``switch`` has always re-registered enabled extensions for the agent it
-    activates; ``install`` and ``upgrade`` call this so a newly added (or
-    refreshed) agent reaches command-registration parity. See issue #2886.
+    ``use`` / ``switch`` re-register enabled extensions for the agent they
+    activate; ``upgrade`` backfills them for the refreshed agent. Plain
+    ``install`` deliberately does not call this helper so adding a secondary
+    integration has no extension side effects until it is selected or upgraded.
+    See issue #2886.
 
     Known limitation: extension *skill* rendering is scoped to the active
     agent (init-options track a single ``ai`` / ``ai_skills`` pair). A
     skills-mode agent registered while it is *not* the active agent (e.g.
-    Copilot ``--skills`` installed as a secondary integration) therefore
+    Copilot ``--skills`` registered while non-active) therefore
     receives command files rather than skills here — matching ``extension
-    add``'s multi-agent behavior. ``switch`` avoids this only because it makes
-    the target the active agent first. Per-agent skills parity is tracked in
+    add``'s multi-agent behavior. ``use`` / ``switch`` avoid this because they
+    make the target the active agent first. Per-agent skills parity is tracked in
     #2948.
 
     Best-effort: never aborts the surrounding integration operation. Callers
-    invoke it *after* the install/upgrade/switch transaction has committed so a
+    invoke it *after* the use/upgrade/switch transaction has committed so a
     failure here cannot trigger a rollback.
     """
     _best_effort_extension_op(

src/specify_cli/integrations/_install_commands.py

@@ -26,7 +26,6 @@
     _get_speckit_version,
     _read_integration_json,
     _refresh_init_options_speckit_version,
-    _register_extensions_for_agent,
     _remove_integration_json,
     _resolve_integration_options,
     _resolve_script_type,
@@ -189,18 +188,6 @@ def integration_install(
         )
         raise typer.Exit(1)
 
-    # Register enabled extensions for the newly installed agent so it gets the
-    # same extension commands the existing agents already have for command
-    # registration parity with switch; otherwise a second integration silently
-    # lacks the first agent's extension commands. See #2886. Done after the
-    # try/except (the install has committed) so this best-effort step can never
-    # trigger the rollback above.
-    _register_extensions_for_agent(
-        project_root,
-        integration.key,
-        continuing="The integration was installed, but installed extensions may need re-registration.",
-    )
-
     name = (integration.config or {}).get("name", key)
     console.print(f"\n[green]✓[/green] Integration '{name}' installed successfully")
     if default_key:

src/specify_cli/integrations/_query_commands.py

@@ -17,6 +17,7 @@
 from ._commands import integration_app, integration_catalog_app
 from ._helpers import (
     _read_integration_json,
+    _register_extensions_for_agent,
     _resolve_integration_options,
     _set_default_integration_or_exit,
 )
@@ -242,6 +243,11 @@ def integration_use(
             f"[cyan]specify integration use {key} --force[/cyan]."
         ),
     )
+    _register_extensions_for_agent(
+        project_root,
+        key,
+        continuing="The integration was selected, but installed extensions may need re-registration.",
+    )
     console.print(f"[green]✓[/green] Default integration set to [bold]{key}[/bold].")
 
 

tests/integrations/test_integration_subcommand.py

@@ -1240,15 +1240,13 @@ def test_install_bare_project_gets_shared_infra(self, tmp_path):
         assert "/speckit-specify" in script_content
         assert "/speckit.specify" not in script_content
 
-    def test_install_registers_extension_commands_for_new_agent(self, tmp_path):
-        """Installing a second integration registers enabled extensions for it.
-
-        Regression for #2886: only ``switch`` used to register extension
-        commands for the newly active agent, so a second integration added via
-        ``install`` was silently missing the extension commands the first agent
-        had. ``install`` must reach command-registration parity with
-        ``switch``; active-agent-scoped extension skill rendering remains
-        tracked in #2948.
+    def test_install_defers_extension_commands_until_use(self, tmp_path):
+        """Installing a second integration does not register enabled extensions.
+
+        Maintainer-requested behavior for #2886: extension command back-fill is
+        limited to ``integration use`` / ``switch`` / ``upgrade``. Plain
+        ``install`` only adds the integration; selecting it with ``use`` then
+        registers the enabled extensions for that agent.
         """
         project = _init_project(tmp_path, "claude")
 
@@ -1268,15 +1266,24 @@ def test_install_registers_extension_commands_for_new_agent(self, tmp_path):
         ])
         assert result.exit_code == 0, result.output
 
-        # The new agent now carries the git extension's commands too, and the
-        # existing agent's registration is preserved.
+        # Install alone does not back-fill the git extension for the secondary
+        # agent.
         registered = json.loads(registry_path.read_text(encoding="utf-8"))[
             "extensions"
         ]["git"]["registered_commands"]
         assert "claude" in registered, "existing agent registration preserved"
-        assert "codex" in registered, "new agent should receive extension commands (#2886)"
+        assert "codex" not in registered
+        assert not (
+            project / ".agents" / "skills" / "speckit-git-feature" / "SKILL.md"
+        ).exists()
 
-        # codex renders command-derived artifacts as skills (.agents/skills).
+        result = _run_in_project(project, ["integration", "use", "codex"])
+        assert result.exit_code == 0, result.output
+
+        registered = json.loads(registry_path.read_text(encoding="utf-8"))[
+            "extensions"
+        ]["git"]["registered_commands"]
+        assert "codex" in registered, "use should register extension commands (#2886)"
         assert (
             project / ".agents" / "skills" / "speckit-git-feature" / "SKILL.md"
         ).exists()
@@ -1306,18 +1313,12 @@ def test_install_does_not_register_disabled_extensions(self, tmp_path):
             project / ".agents" / "skills" / "speckit-git-feature" / "SKILL.md"
         ).exists()
 
-    def test_install_skills_mode_secondary_agent_registers_commands(self, tmp_path):
-        """A non-active skills-mode agent gets extension *commands*, not skills.
-
-        Pins a known, system-wide limitation (tracked in #2948): extension
-        skill rendering is scoped to the active agent — init-options track a
-        single ``ai`` / ``ai_skills`` pair — so a skills-mode agent installed
-        as a *non-active* secondary integration (Copilot ``--skills``) receives
-        ``.github/agents/*.agent.md`` command files rather than
-        ``.github/skills/.../SKILL.md``. This matches what ``extension add``
-        already does across multiple agents; ``install`` (the #2886 fix) stays
-        consistent with it. ``switch`` differs only because it makes the target
-        the active agent before registering.
+    def test_install_skills_mode_secondary_agent_defers_extension_artifacts(self, tmp_path):
+        """A non-active skills-mode agent gets extension artifacts only on use.
+
+        Plain ``install`` has no extension side effects. Once the secondary
+        Copilot ``--skills`` integration is selected with ``use``, it becomes the
+        active agent and receives extension skills.
         """
         project = _init_project(tmp_path, "claude")
 
@@ -1340,21 +1341,36 @@ def test_install_skills_mode_secondary_agent_registers_commands(self, tmp_path):
             project / ".github" / "skills" / "speckit-specify" / "SKILL.md"
         ).exists(), "precondition: copilot installed in skills mode"
 
+        # The git extension is not registered for the non-active copilot agent
+        # during install.
         git_meta = json.loads(
             (project / ".specify" / "extensions" / ".registry").read_text(encoding="utf-8")
         )["extensions"]["git"]
-        # The git extension is still registered as commands for the non-active
-        # copilot agent...
-        assert "copilot" in git_meta["registered_commands"]
-        assert (
+        assert "copilot" not in git_meta["registered_commands"]
+        assert not (
             project / ".github" / "agents" / "speckit.git.feature.agent.md"
         ).exists()
-        # ...and does NOT follow copilot's core commands into skills, because
-        # skill rendering is scoped to the active agent (claude here); #2948.
         assert not (
             project / ".github" / "skills" / "speckit-git-feature" / "SKILL.md"
         ).exists()
 
+        result = _run_in_project(project, ["integration", "use", "copilot"])
+        assert result.exit_code == 0, result.output
+
+        git_meta = json.loads(
+            (project / ".specify" / "extensions" / ".registry").read_text(encoding="utf-8")
+        )["extensions"]["git"]
+        # `use` makes copilot active, so extension artifacts follow copilot's
+        # skills-mode layout.
+        assert "copilot" not in git_meta["registered_commands"]
+        assert "speckit-git-feature" in git_meta["registered_skills"]
+        assert not (
+            project / ".github" / "agents" / "speckit.git.feature.agent.md"
+        ).exists()
+        assert (
+            project / ".github" / "skills" / "speckit-git-feature" / "SKILL.md"
+        ).exists()
+
 
 # ── uninstall ────────────────────────────────────────────────────────
 
@@ -2494,8 +2510,8 @@ def test_upgrade_non_active_agent_preserves_active_agent_skills(self, tmp_path):
         """Upgrading a non-active agent must not touch the active agent's skills.
 
         Regression for the #2886 wiring: extension skill rendering is
-        active-agent-scoped, so routing install/upgrade of a *secondary* agent
-        through ``register_enabled_extensions_for_agent`` used to re-render the
+        active-agent-scoped, so routing upgrade of a *secondary* agent through
+        ``register_enabled_extensions_for_agent`` used to re-render the
         *active* skills-mode agent's extension skills as a side effect —
         resurrecting skill files the user had deliberately deleted. The skills
         pass is now gated on the target being the active agent. (Skills parity