refactor(bob): resolve skills mode via base-class hooks + fix command-ref separators

Rework the dual-mode handling introduced for Bob 2.0 so an integration's
internal representation never leaks into shared init/install/upgrade code,
and fix the legacy command-reference separator surfaced in review.

Base-class contract:
- Add IntegrationBase.is_skills_mode(parsed_options) — the single hook the
  shared machinery consults to decide whether to persist ai_skills and render
  skill invocations. SkillsIntegration returns True; Copilot honors --skills /
  self._skills_mode; Bob returns `not legacy_commands`.
- Add IntegrationBase.invoke_separator_for_mode(skills_enabled) — resolves the
  command-ref separator from a project's persisted mode for registration paths
  that only have the ai_skills flag (no CLI parsed_options). Default is
  behavior-preserving; Bob maps skills->"-", legacy->".".
- BobIntegration stays on IntegrationBase (mirroring Copilot, the other
  dual-mode agent) and delegates setup() to internal _BobSkillsHelper /
  _BobMarkdownHelper. Removes the _skills_mode method and all
  isinstance(SkillsIntegration) / callable(_skills_mode) probing from
  _helpers.py and init.py.

Fix legacy separator (review feedback): CommandRegistrar.register_commands and
PresetManager._resolve_skill_command_refs previously read the single static
AGENT_CONFIGS[key]["invoke_separator"], so legacy .bob/commands/ extension and
preset command refs rendered /speckit-<cmd> instead of Bob 1.x /speckit.<cmd>.
Both now resolve the separator per project mode via invoke_separator_for_mode.

Tests: add regression coverage for the is_skills_mode / invoke_separator_for_mode
hooks and legacy extension command-ref separators; normalize a width-sensitive
workflow assertion to match its siblings. Full suite green.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf

Author: mnriem

src/specify_cli/agents.py

@@ -637,6 +637,23 @@ def register_commands(
         is_cline_ext = agent_name == "cline" and source_id != "core"
         source_root = source_dir.resolve()
 
+        # Resolve the command-reference separator once for this agent/project.
+        # Dual-layout agents (e.g. Bob) use different separators for their
+        # skills vs command layouts, so we ask the integration to map the
+        # project's persisted skills state to the correct separator rather than
+        # relying on the single static AGENT_CONFIGS value.
+        _sep = agent_config.get("invoke_separator", ".")
+        try:
+            from specify_cli.integrations import get_integration  # noqa: PLC0415
+
+            _integ = get_integration(agent_name)
+            if _integ is not None:
+                _sep = _integ.invoke_separator_for_mode(
+                    is_ai_skills_enabled(load_init_options(project_root))
+                )
+        except Exception:
+            pass
+
         for cmd_info in commands:
             cmd_name = cmd_info["name"]
             aliases = cmd_info.get("aliases", [])
@@ -709,13 +726,15 @@ def register_commands(
             )
 
             # Resolve __SPECKIT_COMMAND_*__ tokens using the agent's invoke separator.
-            # The separator is sourced from agent_config (populated by _build_agent_configs,
-            # which propagates each integration's invoke_separator class attribute).
+            # For dual-layout agents (e.g. Bob) the separator differs between the
+            # skills and command layouts, so a single static AGENT_CONFIGS value is
+            # insufficient. Resolve it from the integration using the project's
+            # persisted skills state; single-layout agents fall back to the static
+            # AGENT_CONFIGS value unchanged (invoke_separator_for_mode default).
             # Deferred import of IntegrationBase avoids a circular import at module load
             # (base.py itself imports CommandRegistrar lazily).
             from specify_cli.integrations.base import IntegrationBase  # noqa: PLC0415
 
-            _sep = agent_config.get("invoke_separator", ".")
             body = IntegrationBase.resolve_command_refs(body, _sep)
 
             output_name = self._compute_output_name(agent_name, cmd_name, agent_config)

src/specify_cli/commands/init.py

@@ -532,18 +532,9 @@ def init(
                     "feature_numbering": "sequential",
                     "speckit_version": get_speckit_version(),
                 }
-                from ..integrations.base import SkillsIntegration as _SkillsPersist
-
-                _legacy_commands = bool(
-                    (integration_parsed_options or {}).get("legacy_commands")
-                )
-                _skills_mode_attr = getattr(resolved_integration, "_skills_mode", None)
-                _is_skills = (
-                    isinstance(resolved_integration, _SkillsPersist)
-                    or (callable(_skills_mode_attr) and _skills_mode_attr(integration_parsed_options))
-                    or (not callable(_skills_mode_attr) and bool(_skills_mode_attr))
-                )
-                if _is_skills and not _legacy_commands:
+                if resolved_integration.is_skills_mode(
+                    integration_parsed_options or None
+                ):
                     init_opts["ai_skills"] = True
                 save_init_options(project_path, init_opts)
 
@@ -690,13 +681,8 @@ def init(
             steps_lines.append("1. You're already in the project directory!")
             step_num = 2
 
-        from ..integrations.base import SkillsIntegration as _SkillsInt
-
-        _skills_mode_attr = getattr(resolved_integration, "_skills_mode", None)
-        _is_skills_integration = (
-            isinstance(resolved_integration, _SkillsInt)
-            or (callable(_skills_mode_attr) and _skills_mode_attr(integration_parsed_options))
-            or (not callable(_skills_mode_attr) and bool(_skills_mode_attr))
+        _is_skills_integration = resolved_integration.is_skills_mode(
+            integration_parsed_options or None
         )
 
         codex_skill_mode = selected_ai == "codex" and _is_skills_integration
@@ -705,7 +691,6 @@ def init(
         kimi_skill_mode = selected_ai == "kimi"
         agy_skill_mode = selected_ai == "agy" and _is_skills_integration
         trae_skill_mode = selected_ai == "trae"
-        bob_skill_mode = selected_ai == "bob" and _is_skills_integration
         cursor_agent_skill_mode = (
             selected_ai == "cursor-agent" and _is_skills_integration
         )
@@ -714,19 +699,20 @@ def init(
         zed_skill_mode = selected_ai == "zed" and _is_skills_integration
         grok_skill_mode = selected_ai == "grok" and _is_skills_integration
         cline_skill_mode = selected_ai == "cline"
+        bob_skill_mode = selected_ai == "bob" and _is_skills_integration
         native_skill_mode = (
             codex_skill_mode
             or zcode_skill_mode
             or claude_skill_mode
             or kimi_skill_mode
             or agy_skill_mode
             or trae_skill_mode
-            or bob_skill_mode
             or cursor_agent_skill_mode
             or copilot_skill_mode
             or devin_skill_mode
             or zed_skill_mode
             or grok_skill_mode
+            or bob_skill_mode
         )
 
         if codex_skill_mode:
@@ -764,6 +750,11 @@ def init(
                 f"{step_num}. Start Grok Build in this project directory; spec-kit skills were installed to [cyan].grok/skills[/cyan]"
             )
             step_num += 1
+        if bob_skill_mode:
+            steps_lines.append(
+                f"{step_num}. Start Bob in this project directory; spec-kit skills were installed to [cyan].bob/skills[/cyan]"
+            )
+            step_num += 1
         usage_label = "skills" if native_skill_mode else "slash commands"
 
         from .._invocation_style import (

src/specify_cli/integrations/_helpers.py

@@ -272,28 +272,19 @@ def _update_init_options_for_integration(
         load_init_options,
         save_init_options,
     )
-    from .base import SkillsIntegration
     opts = load_init_options(project_root)
     opts["integration"] = integration.key
     opts["ai"] = integration.key
     opts["speckit_version"] = _get_speckit_version()
     if script_type:
         opts["script"] = script_type
-    # Skills mode is either intrinsic (SkillsIntegration), derived from
-    # parsed_options via a callable _skills_mode method (e.g. Bob), set on
-    # the instance during setup() as a bool attribute (e.g. Copilot), or
-    # requested via parsed options (e.g. Copilot's --skills, persisted as
-    # parsed_options["skills"]). The latter is the only signal available on
-    # the `use` path, where no setup() runs and a fresh integration instance
-    # has _skills_mode == False (issue #3550).
-    _skills_mode_attr = getattr(integration, "_skills_mode", None)
-    skills_mode = (
-        isinstance(integration, SkillsIntegration)
-        or (callable(_skills_mode_attr) and _skills_mode_attr(parsed_options))
-        or (not callable(_skills_mode_attr) and bool(_skills_mode_attr))
-        or bool((parsed_options or {}).get("skills"))
-    )
-    if skills_mode:
+    # Whether skills mode is active is owned by each integration via the
+    # ``is_skills_mode`` hook (base default honors ``--skills``;
+    # SkillsIntegration returns True; skills-first integrations with a legacy
+    # opt-out such as Bob override it). This keeps shared code free of
+    # ``isinstance`` / ``_skills_mode`` probing. Passing parsed_options lets it
+    # work on the ``use``/``install`` path where no setup() runs (issue #3550).
+    if integration.is_skills_mode(parsed_options):
         opts["ai_skills"] = True
     else:
         opts.pop("ai_skills", None)

src/specify_cli/integrations/_install_commands.py

@@ -159,7 +159,10 @@ def integration_install(
         _write_integration_json(project_root, new_default, new_installed, settings)
         if new_default == integration.key:
             _update_init_options_for_integration(
-                project_root, integration, script_type=selected_script, parsed_options=parsed_options
+                project_root,
+                integration,
+                script_type=selected_script,
+                parsed_options=parsed_options,
             )
         else:
             _refresh_init_options_speckit_version(project_root)

src/specify_cli/integrations/_migrate_commands.py

@@ -464,7 +464,10 @@ def integration_upgrade(
         _write_integration_json(project_root, installed_key, installed_keys, settings)
         if installed_key == key:
             _update_init_options_for_integration(
-                project_root, integration, script_type=selected_script, parsed_options=parsed_options
+                project_root,
+                integration,
+                script_type=selected_script,
+                parsed_options=parsed_options,
             )
         else:
             _refresh_init_options_speckit_version(project_root)

src/specify_cli/integrations/base.py

@@ -171,6 +171,43 @@ def effective_invoke_separator(
         """
         return self.invoke_separator
 
+    def invoke_separator_for_mode(self, skills_enabled: bool) -> str:
+        """Command-ref separator given the project's *resolved* skills state.
+
+        Registration paths (extension / preset command rendering) have no CLI
+        ``parsed_options`` — only the persisted ``ai_skills`` flag — so they
+        resolve the command-reference separator through this hook rather than
+        the static ``AGENT_CONFIGS[key]["invoke_separator"]`` value, which
+        cannot represent an agent whose separator differs between its skills
+        and command layouts.
+
+        The default is mode-independent and returns exactly what
+        ``_build_agent_configs`` would place in ``AGENT_CONFIGS`` (the
+        ``registrar_config`` override if present, else the class-level
+        ``invoke_separator``), so single-layout agents are unaffected.
+        Dual-mode agents whose separator depends on the layout (e.g. Bob:
+        ``-`` for skills, ``.`` for legacy commands) override this.
+        """
+        cfg = self.registrar_config or {}
+        return cfg.get("invoke_separator", self.invoke_separator)
+
+    def is_skills_mode(self, parsed_options: dict[str, Any] | None = None) -> bool:
+        """Return whether this integration scaffolds skills for these options.
+
+        This is the single, well-defined hook the shared init/install/upgrade
+        machinery consults to decide whether to persist ``ai_skills=True`` and
+        render skill invocations.  It replaces ad-hoc ``isinstance`` /
+        ``getattr(self, "_skills_mode", ...)`` probing so an integration's
+        internal representation never has to leak into shared dispatch code.
+
+        The default (command-first integrations, e.g. Copilot's default
+        layout) is skills mode only when ``--skills`` was requested.
+        ``SkillsIntegration`` overrides this to return ``True`` by default;
+        skills-first integrations that expose a legacy opt-out (e.g. Bob)
+        override it to honor their own flag.
+        """
+        return bool((parsed_options or {}).get("skills"))
+
     def build_exec_args(
         self,
         prompt: str,
@@ -1376,6 +1413,10 @@ class SkillsIntegration(IntegrationBase):
 
     invoke_separator = "-"
 
+    def is_skills_mode(self, parsed_options: dict[str, Any] | None = None) -> bool:
+        """Skills-native integrations scaffold skills unconditionally."""
+        return True
+
     def build_exec_args(
         self,
         prompt: str,