github/github-spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-08-03 06:26:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: update Bob integration to skills-based layout for Bob 2.0 (#3415)

Browse Source 
* feat: update Bob integration to skills-based layout for Bob 2.0

Bob 2.0 replaces the command-based workflow (.bob/commands/*.md) with
a skills-based layout (.bob/skills/speckit-<name>/SKILL.md), matching
the pattern used by Claude Code, Codex, and other skills-first agents.

- Switch BobIntegration from MarkdownIntegration to SkillsIntegration
- Update folder/dir from .bob/commands to .bob/skills
- Change extension from .md to /SKILL.md (skills layout)
- Add --skills option (default: True) consistent with Codex pattern
- Update tests to inherit from SkillsIntegrationTests (28 tests pass)
- Bump catalog entry to version 2.0.0 with updated description

Assisted-by: IBM Bob (model: claude-sonnet-4-5, autonomous)

* PR comments fix: keep old Bob 1 commands till next release

* Copilot suggested change

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* feat(bob): address copilot comments, make skills layout default, demote legacy commands to opt-in

* fix(bob): honor legacy_commands in ai_skills persistence and add bob to ALWAYS_SLASH_AGENTS

- init.py: suppress ai_skills=True when --legacy-commands is passed so
  extensions and presets target .bob/commands, not .bob/skills
- _invocation_style.py: add 'bob' to ALWAYS_SLASH_AGENTS so init next-steps
  and hook invocations always show /speckit-<name> (skills is the default
  layout; no ai_skills flag required)

* Copilot suggestion

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix(bob): extend IntegrationBase directly to avoid false isinstance(SkillsIntegration)

- bob/__init__.py: switch BobIntegration base from SkillsIntegration to
  IntegrationBase; add _BobSkillsHelper for skills-mode delegation; set
  invoke_separator='-' explicitly; set _skills_mode flag in setup() so
  consumers can derive the effective mode without isinstance checks
- _helpers.py: replace isinstance(integration, SkillsIntegration) guard
  with getattr(_skills_mode) so legacy-commands mode does not persist
  ai_skills=True
- _invocation_style.py: remove 'bob' from ALWAYS_SLASH_AGENTS — Bob 2.0
  skills are invoked via natural language, not /skill-name slash commands
- integrations/catalog.json: advance updated_at to 2026-07-15

* fix(lint): remove unused SkillsIntegration import from _helpers.py

* Copilot suggested change

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* feat(bob): add bob skills integration with registrar-based mode detection

* address 3 comments from copilot

* feat(bob): update registrar config to use legacy commands layout

* fix lint

* Suggested fix from Copilot

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix pr comment

* fix pr comment

* fix pr comment

* 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

* fix(bob,copilot): address review — preserve legacy layout, dual-mode separators, extension-skill token resolution

Addresses PR review 4716036212 (3 comments):

1. Bob legacy-install regression: `use`/`switch`/`upgrade` on an existing
   Bob 1.x project (only `.bob/commands/` on disk, no stored
   `legacy_commands`) called `is_skills_mode(None)` -> True and rewrote
   `ai_skills=True`, silently switching extension/command-reference handling
   to the skills layout. `is_skills_mode` now takes an optional `project_root`;
   Bob preserves an already-installed legacy layout until an explicit upgrade
   creates `.bob/skills/`. A fresh project still defaults to skills.

2. Copilot dual-mode separator: `invoke_separator_for_mode` was inherited
   from the base (mode-independent) and returned Copilot's static `.`, so
   preset/extension command refs in a Copilot skills project rendered
   `/speckit.<name>` instead of `/speckit-<name>`. Override it on Copilot to
   track the persisted `ai_skills` state, consistent with
   `build_command_invocation` and `effective_invoke_separator`.

3. Bob extension-skill command-ref tokens: verified that merging main's
   generic `_resolve_command_ref_tokens` (#3544) resolves Bob's tokens via
   the `CONDITIONAL_SLASH_AGENTS` path (`/speckit-<name>`); added Bob to the
   command-ref regression parametrize plus dedicated Bob use-path tests.

All tests pass (full suite green; merged with current main incl. #3544).

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

* fix(bob): resolve command-ref separator with project-aware mode before shared-infra refresh (review #3415)

The `use`/`switch` paths refresh shared infrastructure via
`_with_integration_setting()` / `_invoke_separator_for_integration()`,
which previously resolved the invoke separator through
`effective_invoke_separator` / `is_skills_mode` WITHOUT a project_root.
For a pre-PR Bob 1.x project (.bob/commands/ on disk, no stored options),
this defaulted to the skills "-" separator and rewrote rendered
shared-template command refs to /speckit-*, even though ai_skills stayed
false. Thread project_root through effective_invoke_separator, the two
runtime helpers, and every call site so Bob's on-disk legacy detection
governs the separator before shared infra is refreshed.

Add a rendered-shared-template regression test covering `use --force`.

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

* fix(bob): scope persisted ai_skills flag to active agent when resolving command-ref separator (review #3415)

`register_commands` runs once per detected agent, but the persisted
`ai_skills` flag describes only the active integration (`opts["ai"]`).
When another agent (e.g. Copilot) is active in skills mode while a
legacy `.bob/commands` layout is also present, the previous code passed
that global `True` to Bob's `invoke_separator_for_mode`, rewriting Bob
1.x command refs to `/speckit-*` instead of `/speckit.*`.

Only consult the persisted flag for the agent it describes
(`opts["ai"] == agent_name`); otherwise resolve the separator from the
agent's own project-aware `effective_invoke_separator(None, project_root)`.

Add regression tests covering the mismatched-active-agent case and a
control for Bob-active skills mode.

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

* fix(bob): detect Spec Kit layout from managed artifacts, not any skills dir (review #3415)

Two related mis-detections from review 4723246468:

1. `BobIntegration.is_skills_mode` treated the mere presence of a
   `.bob/skills/` directory as proof the project is skills-based. A legacy
   Spec Kit install (managed `.bob/commands/speckit.*.md`) that also carried
   unrelated Bob 2 skills would be misclassified as skills, so
   `integration use bob` persisted `ai_skills` and rewrote shared refs.
   Now the layout is inferred from managed Spec Kit artifacts: legacy/command
   mode only when managed `speckit.*.md` command files exist and no managed
   `speckit-*` skill dirs do.

2. The `register_commands` separator for an inactive agent used a disk-based
   `effective_invoke_separator(None, project_root)` fallback that could pick
   the skills separator even though the registrar writes the static command
   layout (`.bob/commands/*.md`). Inactive agents now resolve the separator
   from the registrar's actual output layout (`extension == "/SKILL.md"`),
   so command-layout files keep `/speckit.*` refs regardless of sibling dirs.

Update the affected hook/E2E tests to use managed artifacts and add
regression tests for the mixed-layout and inactive-registrar scenarios.

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

* fix(bob): apply managed-artifact detection on upgrade + consistent skill post-processing (review #3415)

Two issues from review 4723782860:

1. `BobIntegration.setup()` resolved the layout via `is_skills_mode(parsed_options)`
   WITHOUT `project_root`, so `integration upgrade bob` on a Bob 1.x install
   (managed `.bob/commands/speckit.*.md`, no stored options) ignored the
   existing command files, generated skills, and stale-deleted the legacy
   commands — silently migrating the project. Pass `project_root` so the same
   managed-artifact detection used by `use` also governs upgrades.

2. Only `_BobSkillsHelper` overrode `post_process_skill_content` to suppress
   the shared slash-command hook note. Preset/extension skill generators call
   that hook on the registered `BobIntegration`, which inherited
   `IntegrationBase`'s note-injecting default. Repeat the no-op (delegating to
   the skills helper) on the registered class so every Bob skill-generation
   path is consistent with intent-activated core Bob skills.

Add regression tests for the upgrade-preservation and post-processing paths.

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

* feat(bob): add --skills migration opt-in; fix separator + manifest loss (review #3415)

Address review #3415 (4724160183):

- Comment 1: Add an explicit `--skills` opt-in to BobIntegration. It forces
  the skills layout over on-disk auto-detection, giving legacy Bob 1.x
  installs a supported migration path
  (`integration upgrade bob --integration-options="--skills"`). `--skills`
  and `--legacy-commands` are mutually exclusive (clean exit-1 error).

- Comment 2: In CommandRegistrar.register_commands, derive the command-ref
  separator from the output layout (agent_config["extension"]) for the
  active agent too, not the persisted ai_skills flag. A command-layout file
  (.bob/commands/*.md, .github/agents/*.agent.md) always renders /speckit.*;
  only a /SKILL.md scaffold uses /speckit-*. Dual-layout agents (Bob,
  Copilot) write skills via their own setup()/skills path, so
  register_commands only ever emits their command-layout files.

- Comment 3: Update docs/reference/integrations.md Bob entry to document the
  skills-based default (.bob/skills/), the deprecated --legacy-commands
  opt-out, and the --skills migration path.

Also fix a latent manifest-loss bug surfaced by the migration path: the
upgrade Phase 2 stale-file cleanup built a throwaway manifest sharing the
integration key and called uninstall(), which always deleted
{key}.manifest.json. Any layout-shrinking upgrade (e.g. legacy->skills)
thus wiped the freshly-saved manifest, leaving the project untracked and
un-upgradeable. uninstall() now takes remove_manifest (default True); the
stale-cleanup pass passes False.

Adds regression tests for the --skills opt-in, mutual exclusion, corrected
active-agent separator, remove_manifest=False, and an end-to-end
legacy->skills migration that verifies the manifest survives and the
project remains upgradeable. Full suite: 4555 passed, 5 skipped.

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

* docs(agents): align token-resolution comment with output-layout separator rule (review #3415)

Address review #3415 (4725516805). The comment above resolve_command_refs
still described the removed state-based behavior ("resolve it from the
integration using the project's persisted skills state"). Update it to
describe the output-layout rule that register_commands now uses: _sep is
derived from the layout this registrar writes (a /SKILL.md scaffold uses the
skills separator; a command-layout file uses the command separator), not the
persisted ai_skills state. Comment-only change; no behavior change.

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

* fix(bob): reconcile extension artifacts on layout change (review #3415)

When a dual-mode agent (Bob) flips between the legacy commands layout and
the skills layout during `integration upgrade` (via `--skills` /
`--legacy-commands`), the old layout's extension command/skill files were
left orphaned: Phase 2 stale cleanup only removes files tracked by the
*integration* manifest, while extension artifacts are tracked in the
extension registry. Detect the layout flip by comparing whether the old vs
new manifest tracks a `/SKILL.md` scaffold, and when it changed, unregister
the agent's extension artifacts before the existing re-registration so they
are recreated in the new layout (and the per-agent registry is updated).

Preset artifacts are documented as a known, pre-existing cross-cutting gap:
no agent-scoped preset re-registration exists in use/switch/upgrade for any
agent, so reconciling them is out of scope for this Bob migration.

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

* fix(bob): reject layout migration when preset overrides are installed (review #3415)

A command↔skills layout change during `integration upgrade` cannot reconcile
preset artifacts: presets track their command/skill files in per-preset
`registered_commands`/`registered_skills` metadata, and there is no
agent-scoped preset re-registration anywhere in the CLI. Migrating would
delete a preset's old-layout files without recreating them in the new layout
and leave the preset registry claiming artifacts that no longer exist.

Detect the intended layout via `is_skills_mode` (so a plain same-layout
upgrade is unaffected) and, when it flips while preset overrides are
installed for the agent, reject the upgrade *before any mutation* with an
actionable error pointing at the remove → upgrade → reinstall workaround.
Extension artifacts are still reconciled for the safe (no-preset) case.

Adds a regression test and documents the migration caveat in the Bob
integration reference entry.

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

* fix(bob): restrict layout reconciliation to the active integration (review #3415)

`integration_upgrade` supports upgrading a secondary (non-active) integration,
but the layout-change extension reconciliation was unsafe there.
`ExtensionManager.unregister_agent_artifacts()` treats the unscoped
per-extension `registered_skills` list as belonging to the passed agent and,
when that agent's skills directory is absent, falls back to scanning every
agent's skills directory — so reconciling a secondary Bob layout flip could
delete or untrack the *active* agent's extension skills. The subsequent
re-registration cannot repair that because extension skill rendering is
intentionally scoped to the active agent (#2948).

Gate the unregister-before-register reconciliation on `installed_key == key`
so it only runs for the active integration. Secondary agents only ever have
extension command files (skills are active-agent-only), which the existing
re-registration rewrites in place, so skipping the unregister orphans nothing
new. Adds a regression test asserting a secondary Bob layout change leaves the
active agent's extension skill intact on disk and in the registry.

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

* fix(bob): fail closed when preset registry is unreadable (review #3415)

Address review 4744636079:

- _migrate_commands: the preset guard previously failed *open* — a
  registry read/parse error returned an empty "no presets" list, so a
  --force layout-changing upgrade could delete preset-overridden command
  files while their registry state was unknown. Read the registry file
  directly and raise _PresetRegistryUnreadableError on any read/parse
  failure or malformed structure, rejecting the migration before any
  mutation. A genuinely absent registry still returns [] (safe).

- bob: correct the is_skills_mode docstring — upgrade *does* run setup();
  disk detection is needed because legacy Bob 1.x installs never persisted
  a legacy_commands option, so the stored mode is unavailable.

- tests: add fail-closed E2E (corrupted registry rejected, valid-empty
  allowed) plus a unit test for _installed_presets_affecting_agent covering
  absent / corrupted / malformed / valid / affecting-agent cases.

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

* fix(bob): fail closed on malformed preset entries too (review #3415)

Address review 4745191015: the preset guard read a parseable registry but
silently skipped malformed per-preset metadata and treated a malformed
registered_commands value as "no matching artifacts". A registry such as
{"presets":{"p1":[]}} therefore allowed a layout migration even though p1's
ownership is unknown, risking deletion of preset-managed files. Now raise
_PresetRegistryUnreadableError for a non-dict preset entry, a non-dict
registered_commands, or a non-list registered_skills. Extend the unit test
to cover these malformed shapes.

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

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Davide Barletta
2026-07-21 16:20:20 +02:00
committed by GitHub
parent 7f97f1f1f8
commit 74662cffad
19 changed files with 2018 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
src/specify_cli/integrations/_helpers.py
View File

@@ -272,24 +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), set on the instance
# during setup() (_skills_mode), 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 = (
isinstance(integration, SkillsIntegration)
or getattr(integration, "_skills_mode", False)
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, project_root=project_root):
opts["ai_skills"] = True
else:
opts.pop("ai_skills", None)
@@ -325,6 +320,7 @@ def _set_default_integration(
script_type=resolved_script,
raw_options=raw_options,
parsed_options=parsed_options,
project_root=project_root,
)
if refresh_templates:
@@ -333,7 +329,8 @@ def _set_default_integration(
project_root,
resolved_script,
invoke_separator=_invoke_separator_for_integration(
integration, {"integration_settings": settings}, key, parsed_options
integration, {"integration_settings": settings}, key, parsed_options,
project_root=project_root,
),
force=refresh_templates_force,
refresh_managed=True,

11
src/specify_cli/integrations/_install_commands.py
View File

@@ -127,7 +127,8 @@ def integration_install(
project_root,
selected_script,
invoke_separator=_invoke_separator_for_integration(
infra_integration, current, infra_key, infra_parsed
infra_integration, current, infra_key, infra_parsed,
project_root=project_root,
),
)
if os.name != "nt":
@@ -155,10 +156,16 @@ def integration_install(
script_type=selected_script,
raw_options=raw_options,
parsed_options=parsed_options,
project_root=project_root,
)
_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)
_update_init_options_for_integration(
project_root,
integration,
script_type=selected_script,
parsed_options=parsed_options,
)
else:
_refresh_init_options_speckit_version(project_root)

216
src/specify_cli/integrations/_migrate_commands.py
View File

@@ -1,8 +1,9 @@
"""specify integration switch / upgrade command handlers."""
from __future__ import annotations
import json
import os
from pathlib import PurePath
from pathlib import Path, PurePath
import typer
@@ -40,6 +41,93 @@ from ._helpers import (
)
def _manifest_tracks_skill_layout(manifest) -> bool:
"""Return True when *manifest* tracks any skills-layout artifact.
A skill scaffold is written as ``.../speckit-<name>/SKILL.md``, so a
manifest whose tracked files include a ``/SKILL.md`` key is in the skills
layout; otherwise it is in the command layout. Used by ``upgrade`` to
detect a dual-mode agent (e.g. Bob) flipping between the legacy commands
layout and the skills layout so orphaned extension artifacts from the old
layout can be reconciled.
"""
return any(str(rel).endswith("/SKILL.md") for rel in manifest.files)
class _PresetRegistryUnreadableError(Exception):
"""Raised when an existing preset registry cannot be read or parsed.
Distinct from a *genuinely absent* registry (no presets installed): an
unreadable registry means we cannot verify whether preset overrides would
be orphaned by a layout change, so the migration must be rejected rather
than proceeding on a false "no presets" assumption.
"""
def _installed_presets_affecting_agent(project_root, agent_key: str) -> list[str]:
"""Return IDs of installed presets with artifacts registered for *agent_key*.
Presets register command overrides for every detected agent and mirror
skills for the active skills agent, tracking the result in each preset's
``registered_commands`` / ``registered_skills`` metadata. There is no
agent-scoped preset re-registration mechanism, so a command↔skills *layout
change* cannot reconcile those artifacts (see ``integration_upgrade``).
Callers use this to detect the unsafe case and reject the migration rather
than silently orphaning preset files / leaving stale registry entries.
Fails **closed**: a genuinely absent registry (no presets ever installed)
returns an empty list, but if the registry file exists and cannot be read
or parsed (e.g. a permission error or corruption) this raises
:class:`_PresetRegistryUnreadableError`. Reporting "no presets" in that
case would let a ``--force`` layout-changing upgrade delete
preset-overridden files while their registry state can't be reconciled —
the exact inconsistency the guard exists to prevent.
"""
from ..presets import PresetRegistry
registry_path = (
Path(project_root) / ".specify" / "presets" / PresetRegistry.REGISTRY_FILE
)
# Genuinely absent registry → no presets installed → safe to proceed.
if not registry_path.exists():
return []
# The registry exists: any failure to read or parse it must surface as an
# error, not be swallowed into an empty ("no presets") result.
try:
data = json.loads(registry_path.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise _PresetRegistryUnreadableError(str(exc)) from exc
if not isinstance(data, dict) or not isinstance(data.get("presets", {}), dict):
raise _PresetRegistryUnreadableError(
"preset registry structure is malformed"
)
affected: list[str] = []
for preset_id, meta in data.get("presets", {}).items():
# A malformed entry means we cannot verify whether this preset owns
# artifacts for the agent, so fail closed rather than skip it.
if not isinstance(meta, dict):
raise _PresetRegistryUnreadableError(
f"preset '{preset_id}' entry is malformed"
)
registered_commands = meta.get("registered_commands", {})
if not isinstance(registered_commands, dict):
raise _PresetRegistryUnreadableError(
f"preset '{preset_id}' registered_commands is malformed"
)
registered_skills = meta.get("registered_skills", [])
if not isinstance(registered_skills, (list, tuple)):
raise _PresetRegistryUnreadableError(
f"preset '{preset_id}' registered_skills is malformed"
)
has_commands = bool(registered_commands.get(agent_key))
has_skills = bool(registered_skills)
if has_commands or has_skills:
affected.append(preset_id)
return affected
@integration_app.command("switch")
def integration_switch(
target: str = typer.Argument(help="Integration key to switch to"),
@@ -236,7 +324,8 @@ def integration_switch(
force=refresh_shared_infra,
refresh_managed=True,
invoke_separator=_invoke_separator_for_integration(
target_integration, current, target, parsed_options
target_integration, current, target, parsed_options,
project_root=project_root,
),
refresh_hint=(
"To overwrite customizations, re-run with "
@@ -398,6 +487,56 @@ def integration_upgrade(
integration, current, key, integration_options
)
# Guard: reject a command↔skills layout change while preset overrides are
# installed for this agent (review #3415). A dual-mode agent (e.g. Bob)
# can flip layout across an upgrade (``--skills`` / ``--legacy-commands``).
# Extension artifacts are reconciled after the flip (see below), but preset
# artifacts cannot be: there is no agent-scoped preset re-registration
# anywhere in the CLI, so migrating would delete a preset's old-layout
# files without recreating them in the new layout and leave the preset
# registry claiming artifacts that no longer exist. Detect the intended
# layout (``is_skills_mode`` reflects the resolved flags/disk state, so a
# plain same-layout upgrade is unaffected) and bail out *before* any
# mutation with an actionable error so the project is never left in a
# half-migrated, inconsistent state.
if _manifest_tracks_skill_layout(old_manifest) != integration.is_skills_mode(
parsed_options, project_root
):
try:
affected_presets = _installed_presets_affecting_agent(project_root, key)
except _PresetRegistryUnreadableError as exc:
console.print(
f"[red]Error:[/red] Cannot change '{key}' command layout: the "
f"preset registry could not be read to verify installed presets."
)
console.print(f"[dim]Details:[/dim] {_cli_error_detail(exc)}")
console.print(
"A layout change cannot reconcile preset artifacts, so the "
"migration is refused while the preset registry state is "
"unknown. Fix or restore "
"[cyan].specify/presets/.registry[/cyan] and retry."
)
raise typer.Exit(1)
if affected_presets:
preset_list = ", ".join(sorted(affected_presets))
console.print(
f"[red]Error:[/red] Cannot change '{key}' command layout while "
f"preset override(s) are installed: [bold]{preset_list}[/bold]."
)
console.print(
"Preset artifacts cannot yet be reconciled across a command↔skills "
"layout change, so the migration would orphan their files and leave "
"the preset registry inconsistent."
)
console.print(
"Remove the preset(s), run the upgrade, then reinstall them:\n"
f" [cyan]specify preset remove <id>[/cyan]\n"
f" [cyan]specify integration upgrade {key} "
f"--integration-options \"...\"[/cyan]\n"
f" [cyan]specify preset add <id>[/cyan]"
)
raise typer.Exit(1)
# Ensure shared infrastructure is up to date; --force overwrites existing files.
infra_integration = integration
infra_key = key
@@ -415,7 +554,8 @@ def integration_upgrade(
selected_script,
force=force,
invoke_separator=_invoke_separator_for_integration(
infra_integration, current, infra_key, infra_parsed
infra_integration, current, infra_key, infra_parsed,
project_root=project_root,
),
)
if os.name != "nt":
@@ -441,6 +581,7 @@ def integration_upgrade(
script_type=selected_script,
raw_options=raw_options,
parsed_options=parsed_options,
project_root=project_root,
)
if installed_key == key:
try:
@@ -448,7 +589,8 @@ def integration_upgrade(
project_root,
selected_script,
invoke_separator=_invoke_separator_for_integration(
integration, {"integration_settings": settings}, key, parsed_options
integration, {"integration_settings": settings}, key, parsed_options,
project_root=project_root,
),
force=force,
refresh_managed=True,
@@ -463,7 +605,12 @@ def integration_upgrade(
new_manifest.save()
_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)
_update_init_options_for_integration(
project_root,
integration,
script_type=selected_script,
parsed_options=parsed_options,
)
else:
_refresh_init_options_speckit_version(project_root)
except Exception as exc:
@@ -487,7 +634,15 @@ def integration_upgrade(
if stale_keys:
stale_manifest = IntegrationManifest(key, project_root, version="stale-cleanup")
stale_manifest._files = {k: old_files[k] for k in stale_keys}
stale_removed, _ = stale_manifest.uninstall(project_root, force=True)
# remove_manifest=False: this throwaway manifest shares ``key`` with the
# real one just saved above (new_manifest.save()). Letting uninstall()
# delete ``{key}.manifest.json`` would wipe the freshly-written manifest
# whenever an upgrade shrinks the tracked file set (e.g. Bob migrating
# from the legacy commands layout to skills), leaving the integration
# untracked and un-upgradeable.
stale_removed, _ = stale_manifest.uninstall(
project_root, force=True, remove_manifest=False
)
if stale_removed:
console.print(f" Removed {len(stale_removed)} stale file(s) from previous install")
@@ -497,6 +652,55 @@ def integration_upgrade(
# Done after the upgrade has fully settled (Phase 2 included) and outside
# the try/except above so this best-effort step cannot affect upgrade
# success.
#
# Layout-change reconciliation: a dual-mode agent (e.g. Bob) can flip
# between the legacy commands layout and the skills layout across an
# upgrade (``upgrade bob --integration-options "--skills"`` / reverse
# ``--legacy-commands``). Phase 2 above only removes stale files tracked by
# the *integration* manifest (core commands); extension artifacts are
# tracked separately in the extension registry, so the old layout's
# extension command/skill files would otherwise linger as orphans. When the
# layout actually changed, first unregister the agent's extension artifacts
# (removing old-layout files and clearing per-agent registry entries) so the
# re-registration below recreates them in the new layout. ``upgrade``s that
# don't change layout skip this to avoid needless remove/re-add churn.
#
# Only the *active* integration is reconciled this way (``installed_key ==
# key``). ``ExtensionManager.unregister_agent_artifacts`` treats the
# per-extension ``registered_skills`` list as belonging to the passed agent
# and, when that agent's skills directory is absent, falls back to scanning
# every agent's skills directory — so running it for a *secondary*
# (non-active) agent could delete or untrack the *active* agent's extension
# skills. The subsequent re-registration cannot repair that because
# extension skill rendering is intentionally scoped to the active agent
# (#2948). Extension skills only ever exist for the active agent, so
# skipping the unregister for a secondary agent orphans nothing new: a
# secondary agent only has extension *command* files, which the
# re-registration below rewrites in place regardless of layout.
#
# Known limitation: preset command/skill artifacts are NOT reconciled on a
# layout change. There is no agent-scoped preset re-registration mechanism
# anywhere in the CLI — ``use`` / ``switch`` / ``upgrade`` never reconcile
# presets for any agent (presets are only (un)registered at preset
# install/remove time). Rather than silently orphan them, the guard near
# the top of this function rejects a layout-changing upgrade while preset
# overrides are installed, so control only reaches here (with a changed
# layout) when no preset artifacts are at stake. Full preset reconciliation
# would require a new cross-cutting PresetManager subsystem affecting every
# dual-layout agent, which is out of scope for this Bob migration.
if (
installed_key == key
and _manifest_tracks_skill_layout(old_manifest)
!= _manifest_tracks_skill_layout(new_manifest)
):
_unregister_extensions_for_agent(
project_root,
key,
continuing=(
"The integration layout changed, but old-layout extension "
"artifacts may need manual cleanup."
),
)
_register_extensions_for_agent(
project_root,
key,

63
src/specify_cli/integrations/base.py
View File

@@ -160,17 +160,66 @@ class IntegrationBase(ABC):
return []
def effective_invoke_separator(
self, parsed_options: dict[str, Any] | None = None
self,
parsed_options: dict[str, Any] | None = None,
project_root: Path | None = None,
) -> str:
"""Return the invoke separator for the given options.
Subclasses whose separator depends on runtime options (e.g.
Copilot in ``--skills`` mode) should override this method.
The default implementation ignores *parsed_options* and returns
the class-level ``invoke_separator``.
The default implementation ignores *parsed_options* and
*project_root* and returns the class-level ``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,
project_root: Path | 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.
*project_root* is optional context for the ``use`` / ``switch`` /
``upgrade`` path, where no ``setup()`` runs and *parsed_options* may be
empty: dual-mode integrations can consult the already-installed
on-disk layout to avoid silently migrating an existing project to a
different mode. The default ignores it.
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 +1425,14 @@ class SkillsIntegration(IntegrationBase):
invoke_separator = "-"
def is_skills_mode(
self,
parsed_options: dict[str, Any] | None = None,
project_root: Path | None = None,
) -> bool:
"""Skills-native integrations scaffold skills unconditionally."""
return True
def build_exec_args(
self,
prompt: str,

269
src/specify_cli/integrations/bob/__init__.py
View File

@@ -1,10 +1,140 @@
"""IBM Bob integration."""
"""IBM Bob integration.
from ..base import MarkdownIntegration
Bob 2.0 uses the ``.bob/skills/speckit-<name>/SKILL.md`` layout by default.
The legacy ``.bob/commands/*.md`` layout (Bob 1.x) remains available as an
opt-in via ``--integration-options "--legacy-commands"``.
Bob is a *dual-mode* integration: whether it scaffolds skills or commands is
a per-project **configuration** decision (the ``--legacy-commands`` option,
persisted as ``ai_skills`` in init-options), not a property of the class.
It therefore extends :class:`IntegrationBase` (like Copilot, the other
dual-mode agent) and resolves the mode through the ``is_skills_mode`` hook,
delegating the actual scaffolding to a per-layout helper.
Deprecation cycle:
This release: Skills layout is the default; legacy ``.bob/commands/`` is
opt-in via ``--legacy-commands``.
Next cycle: ``--legacy-commands`` flag removed.
"""
from __future__ import annotations
import warnings
from pathlib import Path
from typing import Any
import typer
from ..base import (
IntegrationBase,
IntegrationOption,
MarkdownIntegration,
SkillsIntegration,
)
from ..manifest import IntegrationManifest
class BobIntegration(MarkdownIntegration):
def _validate_mode_options(parsed_options: dict[str, Any] | None) -> None:
"""Reject ``--skills`` and ``--legacy-commands`` used together.
The two flags select opposite layouts, so combining them is ambiguous.
Fail fast with the same clean exit-1 UX as other bad-option paths rather
than silently letting one win.
"""
opts = parsed_options or {}
if opts.get("skills") and opts.get("legacy_commands"):
from ..._console import console
console.print(
"[red]Error:[/red] --skills and --legacy-commands are mutually "
"exclusive; pass only one."
)
raise typer.Exit(1)
def _warn_legacy_commands_deprecated() -> None:
warnings.warn(
"Bob legacy commands mode (.bob/commands/) is deprecated and will be "
"removed in a future Spec Kit release. Omit --legacy-commands to use "
"the default skills layout (.bob/skills/).",
UserWarning,
stacklevel=3,
)
class _BobSkillsHelper(SkillsIntegration):
"""Default-mode helper: ``.bob/skills/speckit-<name>/SKILL.md``.
Not registered in the integration registry — used only as a delegate by
:class:`BobIntegration` for skills-mode ``setup()``.
"""
key = "bob"
config = {
"name": "IBM Bob",
"folder": ".bob/",
"commands_subdir": "skills",
"install_url": None,
"requires_cli": False,
}
registrar_config = {
"dir": ".bob/skills",
"format": "markdown",
"args": "$ARGUMENTS",
"extension": "/SKILL.md",
}
def post_process_skill_content(self, content: str) -> str:
"""Bob skills are intent-activated; no slash-command note is needed."""
return content
class _BobMarkdownHelper(MarkdownIntegration):
"""Legacy-mode helper: ``.bob/commands/speckit.<name>.md`` (Bob 1.x).
Not registered in the integration registry — used only as a delegate by
:class:`BobIntegration` when ``--legacy-commands`` is passed. Declares
``invoke_separator="."`` so command-reference tokens render as Bob 1.x
``/speckit.<name>`` invocations.
"""
key = "bob"
invoke_separator = "."
config = {
"name": "IBM Bob",
"folder": ".bob/",
"commands_subdir": "commands",
"install_url": None,
"requires_cli": False,
}
registrar_config = {
"dir": ".bob/commands",
"format": "markdown",
"args": "$ARGUMENTS",
"extension": ".md",
"invoke_separator": ".",
}
class BobIntegration(IntegrationBase):
"""Integration for IBM Bob IDE (dual-mode; skills by default).
Whether a project uses the skills or the legacy commands layout is a
configuration choice resolved by :meth:`is_skills_mode`, not the class
hierarchy. ``setup()`` delegates to the matching helper.
``registrar_config`` mirrors the *commands* layout (``extension: ".md"``,
``dir: ".bob/commands"``) — the same pattern Copilot uses — so that
``CommandRegistrar.AGENT_CONFIGS["bob"]`` drives extension/preset
registration into ``.bob/commands/`` for legacy-mode projects, while
skills-mode projects have that command registration transparently skipped
(``skills_mode_active`` becomes ``True`` because ``ai_skills=True`` and
``extension != "/SKILL.md"``) and receive extension skills instead.
``invoke_separator = "-"`` matches the default (skills) layout.
"""
key = "bob"
invoke_separator = "-"
config = {
"name": "IBM Bob",
"folder": ".bob/",
@@ -18,3 +148,136 @@ class BobIntegration(MarkdownIntegration):
"args": "$ARGUMENTS",
"extension": ".md",
}
@classmethod
def options(cls) -> list[IntegrationOption]:
return [
IntegrationOption(
"--skills",
is_flag=True,
default=False,
help=(
"Force the default skills layout (.bob/skills/), overriding "
"on-disk auto-detection. Use this to migrate a legacy "
"commands install to skills, e.g. "
"`integration upgrade bob --integration-options \"--skills\"`"
),
),
IntegrationOption(
"--legacy-commands",
is_flag=True,
default=False,
help=(
"Scaffold commands as legacy .bob/commands/*.md files "
"(Bob 1.x layout, deprecated) instead of the default "
"skills layout"
),
),
]
def is_skills_mode(
self,
parsed_options: dict[str, Any] | None = None,
project_root: Path | None = None,
) -> bool:
"""Bob is skills-first; ``--legacy-commands`` opts out.
Precedence:
1. Explicit ``--skills`` wins — it *forces* skills mode regardless of
what is already on disk. This is the supported migration / opt-in
path: ``integration upgrade bob --integration-options "--skills"``
converts a legacy commands install to the skills layout (setup()
scaffolds ``.bob/skills`` and the upgrade's stale-file pass removes
the old ``.bob/commands`` files).
2. Explicit ``--legacy-commands`` opts out to the Bob 1.x layout.
3. Otherwise, when a *project_root* is supplied, the layout is inferred
from **managed Spec Kit artifacts** (see below).
4. A fresh project (no managed artifacts, no flags) defaults to skills.
The disk-detection fallback exists because on ``use`` / ``switch`` /
``upgrade`` (without an explicit ``--skills`` / ``--legacy-commands``)
*parsed_options* is typically empty: no flag was passed, and existing
Bob 1.x installs never persisted a ``legacy_commands`` option to
recover. This is independent of whether ``setup()`` runs — ``upgrade``
*does* call :meth:`setup` (see ``_migrate_commands.integration_upgrade``),
but it passes those same empty *parsed_options*, so without disk
detection the mode would resolve to the skills default. Defaulting to
skills there would rewrite such a project's ``ai_skills`` flag to
``True`` even though it still only contains a command layout, silently
switching its extension / command-reference handling. So the layout is
inferred from managed Spec Kit artifacts, not the mere presence of a
``.bob/skills/`` directory: a user may keep unrelated Bob 2 skills in
``.bob/skills/`` while their Spec Kit commands still live in
``.bob/commands/speckit.*.md``. We therefore treat the project as
legacy (command) mode only when managed Spec Kit command files exist
and no managed Spec Kit skills (``speckit-*`` skill dirs) do. Passing
``--skills`` overrides this so users are never trapped in legacy mode.
"""
opts = parsed_options or {}
_validate_mode_options(opts)
if opts.get("skills", False):
return True
if opts.get("legacy_commands", False):
return False
if project_root is not None:
bob_dir = Path(project_root) / ".bob"
has_managed_skills = any((bob_dir / "skills").glob("speckit-*"))
has_managed_commands = any((bob_dir / "commands").glob("speckit.*.md"))
if has_managed_commands and not has_managed_skills:
return False
return True
def effective_invoke_separator(
self,
parsed_options: dict[str, Any] | None = None,
project_root: Path | None = None,
) -> str:
"""``"."`` for the legacy commands layout, ``"-"`` for skills.
*project_root* lets the ``use`` / ``switch`` / ``upgrade`` path — which
refreshes shared infrastructure *before* persisting init-options —
detect an already-installed legacy layout, so core command references
are rendered with the correct separator instead of defaulting to the
skills ``-``.
"""
return "-" if self.is_skills_mode(parsed_options, project_root) else "."
def invoke_separator_for_mode(self, skills_enabled: bool) -> str:
"""Resolve the command-ref separator from a project's persisted mode.
Skills projects render ``/speckit-<cmd>``; legacy command projects
render Bob 1.x ``/speckit.<cmd>``. Extension/preset registration
consults this (via the persisted ``ai_skills`` flag) so both layouts
get the correct separator despite sharing one static ``AGENT_CONFIGS``
entry.
"""
return "-" if skills_enabled else "."
def post_process_skill_content(self, content: str) -> str:
"""Bob skills are intent-activated; no slash-command note is injected.
Preset/extension skill generators call this on the *registered*
``BobIntegration`` instance, not on :class:`_BobSkillsHelper`, so the
no-op must be repeated here (delegating to the helper) — otherwise
those paths would inherit ``IntegrationBase``'s default and inject
``/speckit-*`` hook guidance that core Bob skills intentionally omit.
"""
return _BobSkillsHelper().post_process_skill_content(content)
def setup(
self,
project_root: Path,
manifest: IntegrationManifest,
parsed_options: dict[str, Any] | None = None,
**opts: Any,
) -> list[Path]:
parsed_options = parsed_options or {}
if self.is_skills_mode(parsed_options, project_root):
return _BobSkillsHelper().setup(
project_root, manifest, parsed_options, **opts
)
_warn_legacy_commands_deprecated()
return MarkdownIntegration.setup(
_BobMarkdownHelper(), project_root, manifest, parsed_options, **opts
)

31
src/specify_cli/integrations/copilot/__init__.py
View File

@@ -122,7 +122,9 @@ class CopilotIntegration(IntegrationBase):
_skills_mode: bool = False
def effective_invoke_separator(
self, parsed_options: dict[str, Any] | None = None
self,
parsed_options: dict[str, Any] | None = None,
project_root: Path | None = None,
) -> str:
"""Return ``"-"`` when skills mode is requested, ``"."`` otherwise."""
if parsed_options and parsed_options.get("skills"):
@@ -131,6 +133,33 @@ class CopilotIntegration(IntegrationBase):
return "-"
return self.invoke_separator
def is_skills_mode(
self,
parsed_options: dict[str, Any] | None = None,
project_root: Path | None = None,
) -> bool:
"""Copilot is skills mode when ``--skills`` was requested.
On the init path ``setup()`` has already recorded the choice in
``self._skills_mode``; on the ``use``/``install`` path (where no
``setup()`` runs) the signal comes from *parsed_options* (#3550), which
round-trips because ``--skills`` is persisted in the stored options.
"""
if parsed_options and parsed_options.get("skills"):
return True
return self._skills_mode
def invoke_separator_for_mode(self, skills_enabled: bool) -> str:
"""Skills projects render ``/speckit-<cmd>``; default markdown ``.``.
Copilot is dual-layout, so — like Bob — the command-reference
separator depends on the persisted ``ai_skills`` state rather than a
single static value. This keeps preset/extension command refs in a
Copilot skills project consistent with ``build_command_invocation``
(which emits ``/speckit-<stem>``).
"""
return "-" if skills_enabled else self.invoke_separator
@classmethod
def options(cls) -> list[IntegrationOption]:
return [

12
src/specify_cli/integrations/manifest.py
View File

@@ -327,12 +327,18 @@ class IntegrationManifest:
project_root: Path | None = None,
*,
force: bool = False,
remove_manifest: bool = True,
) -> tuple[list[Path], list[Path]]:
"""Remove tracked files whose hash still matches.
Parameters:
project_root: Override for the project root.
force: If ``True``, remove files even if modified.
project_root: Override for the project root.
force: If ``True``, remove files even if modified.
remove_manifest: If ``True`` (default), also delete this
integration's ``{key}.manifest.json``. Set ``False`` for
*partial* cleanups (e.g. the upgrade stale-file pass, which
builds a throwaway manifest over a subset of files) so the
real, freshly-saved manifest for the same key is not destroyed.
Returns:
``(removed, skipped)`` — absolute paths.
@@ -393,7 +399,7 @@ class IntegrationManifest:
# Remove the manifest file itself
manifest = root / ".specify" / "integrations" / f"{self.key}.manifest.json"
if manifest.exists():
if remove_manifest and manifest.exists():
manifest.unlink()
parent = manifest.parent
while parent != root: