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

[davidebibm]

Bob 2.0 replaces the command-based workflow with a skills-based layout.

https://bob.ibm.com/blog/bob-v2-release-announcement

Description

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

Very simple code generated by Bob but verified by me

[davidebibm]

@mnriem please review, we need to make this work with new Bob... Thankyou so much

[Copilot]

Pull request overview

This PR updates the built-in IBM Bob integration to align with Bob 2.0’s skills-based layout, switching installation output from command files to speckit-<name>/SKILL.md skills directories and bumping the integration’s catalog version accordingly.

Changes:

• Migrate BobIntegration from MarkdownIntegration to SkillsIntegration and update output paths to .bob/skills/.../SKILL.md.
• Update Bob integration tests to use the shared SkillsIntegrationTests mixin.
• Bump the Bob entry in integrations/catalog.json to 2.0.0 with an updated description.

Show a summary per file

File	Description
src/specify_cli/integrations/bob/__init__.py	Switch Bob to SkillsIntegration and update registrar/config output to .bob/skills + /SKILL.md.
tests/integrations/test_integration_bob.py	Update base test mixin and expected output directories for the skills layout.
integrations/catalog.json	Bump Bob integration version/description to reflect the 2.0.0 skills-based update.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Low

[mnriem]

As this fundamentally changes the layout for any Bob users what is the migration strategy? This will break them once they adopt a new version of Spec Kit so you need to make sure this goes through a deprecation cycle so they can migrate to the new Bob version. E.g make it an opt-in to the new version of Bob first and then in 2 minor releases (X.Y.Z where Y is minor) you can then remove the non-skill variant

[davidebibm]

As this fundamentally changes the layout for any Bob users what is the migration strategy? This will break them once they adopt a new version of Spec Kit so you need to make sure this goes through a deprecation cycle so they can migrate to the new Bob version. E.g make it an opt-in to the new version of Bob first and then in 2 minor releases (X.Y.Z where Y is minor) you can then remove the non-skill variant

Hi @mnriem
this should not break for Bob 1 user cause it was already compatible with skill mode.
Still needed this?

[mnriem]

Thanks @davidebibm — but I think we're talking about two different layers, and this still needs to change before it can land.

Your point is about Bob the tool — that Bob 1.x can already read the skills layout. My concern is about Spec Kit's generated output: this PR changes what specify writes for the bob integration from .bob/commands/*.md to .bob/skills/speckit-<name>/SKILL.md. Any project someone already initialized has .bob/commands/*.md on disk. When they upgrade Spec Kit and re-init or switch, that layout is orphaned/replaced. That's a breaking change in our contract regardless of whether the Bob app happens to read both directories.

A hard cutover isn't acceptable here — we shouldn't catch existing users off guard. This needs to go through a proper deprecation cycle:

1. This release: make skills an opt-in and keep the existing .bob/commands markdown layout as the default. That's real dual-mode — setup() branching between the two layouts, the way Copilot does it — not the --skills flag as written now.
2. Next cycle: flip the default to skills, with the legacy layout still available.
3. Cycle after that: remove the legacy markdown mode.

As it stands the --skills flag is a no-op: BobIntegration is hardwired to SkillsIntegration and the MarkdownIntegration variant is deleted, so --skills=False still emits skills. There's no path that produces the old layout, so it doesn't actually provide the opt-in it implies.

Can you rework it along those lines — genuine dual-mode with skills opt-in first — so we phase this in without breaking anyone?

[davidebibm]

Ok, thankyou @mnriem i'll do that

[davidebibm]

@mnriem Done, hope this is what you are expecting

[Copilot]

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Medium

[mnriem]

Please address Copilot feedback. You will need to update the description to reflect the reality

[davidebibm]

@mnriem Addressed Copilot comments and aligned with main

[Copilot]

Review details

• Files reviewed: 38/38 changed files
• Comments generated: 4
• Review effort level: Medium

[mnriem]

Please address Copilot feedback and resolve conflicts

[davidebibm]

@mnriem Solved Copilot fb and rebased to avoid get Copilot feedback on other devs code 👍

[Copilot]

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed review 4725516805. Pushed as d3408e6.

The comment above resolve_command_refs still described the state-based behavior that the previous round removed ("resolve it from the integration using the project's persisted skills state"). Updated it to describe the output-layout rule register_commands now uses: _sep is derived from the layout this registrar writes — a /SKILL.md scaffold uses the skills separator, any command-layout file uses the command separator — not the persisted ai_skills state. Comment-only change; no behavior change. Full suite: 4555 passed, 5 skipped.

---

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

[Copilot]

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed review 4725829110 in 779eb89.

Extension artifacts — reconciled. When a dual-mode agent (Bob) flips between the legacy commands layout and the skills layout during integration upgrade (--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, whereas extension artifacts live in the extension registry. The upgrade now detects the layout flip (comparing whether the old vs new manifest tracks a /SKILL.md scaffold) and, when it changed, unregisters the agent's extension artifacts via the existing unregister_agent_artifacts() before the existing re-registration — so they're removed from the old layout and recreated in the new one, with the per-agent registry updated. Verified both directions (legacy→skills and skills→legacy), plus that same-layout upgrades don't churn. Regression test added (test_upgrade_bob_layout_change_reconciles_extension_artifacts).

Preset artifacts — documented as a known, pre-existing limitation. There is no agent-scoped preset re-registration mechanism anywhere in the CLI: use / switch / upgrade never reconcile presets for any agent (Copilot included) — presets are only (un)registered at preset install/remove time. Reconciling them on a layout change would require a new cross-cutting PresetManager subsystem affecting every dual-layout agent, which is out of scope for this Bob migration. This is now called out in an in-code comment next to the extension reconciliation, with the workaround (preset remove / preset install to refresh) noted.

Full suite green after merging the latest upstream/main: 4581 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

[Copilot]

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed review 4726193915 in d2321b2.

Took the reviewer's second option — reject the migration with an actionable error — since full preset reconciliation would require a new cross-cutting PresetManager subsystem (no agent-scoped preset re-registration exists anywhere in the CLI).

A layout-changing integration upgrade now checks, before any mutation, whether preset overrides are installed for the agent. It detects the intended layout via is_skills_mode (so a plain, same-layout upgrade is unaffected) and compares it to the installed layout. When the layout would flip while a preset registered command/skill artifacts for the agent, it exits 1 with an actionable message:

Error: Cannot change 'bob' command layout while preset override(s) are installed: my-preset.
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.
Remove the preset(s), run the upgrade, then reinstall them:
  specify preset remove <id>
  specify integration upgrade bob --integration-options "..."
  specify preset add <id>

Because the guard runs before shared-infra install and setup(), the project is never left half-migrated. The extension reconciliation from the previous round still handles the safe (no-preset) case. Verified end-to-end: layout flip + presets → rejected with no mutation; same-layout upgrade + presets → succeeds; layout flip without presets → succeeds and reconciles extensions. Regression test added (test_upgrade_bob_layout_change_rejected_with_presets_installed) and the caveat is documented in the Bob integration reference entry.

Full suite green: 4582 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

[Copilot]

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed review 4726347306 in 9cdc8d0.

Good catch — took the first option and restricted the layout-change reconciliation to the active integration. The unregister-before-register block is now gated on installed_key == key, so it only runs when upgrading the active/default agent.

Rationale: ExtensionManager.unregister_agent_artifacts() treats the unscoped per-extension registered_skills list as belonging to the passed agent and, when that agent's skills dir is absent, falls back to scanning every agent's skills dir — so reconciling a secondary Bob layout flip could delete/untrack the active agent's extension skills, and the follow-up re-registration can't repair it (skill rendering is active-agent-scoped, #2948). Skipping the unregister for secondary agents orphans nothing new: a non-active agent only ever has extension command files, which the existing re-registration rewrites in place regardless of layout.

Added a regression test (test_upgrade_secondary_bob_layout_change_preserves_active_agent_skills): active copilot in skills mode with the git extension skill + secondary Bob (legacy) → flip Bob to skills → the active agent's git skill remains on disk and in the registry. Verified it fails without the gate and passes with it, preserving the invariant at test_upgrade_non_active_agent_preserves_active_agent_skills.

Full suite green: 4583 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

[Copilot]

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 2
• Review effort level: Medium

[mnriem]

Addressed review 4744636079 in 44bc562:

• Preset guard now fails closed (_migrate_commands.py): the helper previously returned an empty "no presets" list when the registry couldn't be read, letting a --force layout-changing upgrade delete preset-overridden command files while their registry state was unknown. It now reads .specify/presets/.registry directly and raises _PresetRegistryUnreadableError on any read/parse failure or malformed structure, rejecting the migration before any mutation. A genuinely absent registry still returns [] (safe to proceed).
• is_skills_mode docstring corrected (bob/__init__.py): removed the inaccurate claim that upgrade doesn't run setup(). It does; disk detection is needed because legacy Bob 1.x installs never persisted a legacy_commands option, so the stored mode is unavailable.
• Tests: added a fail-closed E2E (corrupted registry rejected with no mutation, valid-empty allowed) and a unit test for _installed_presets_affecting_agent covering absent / corrupted / malformed / valid / affecting-agent cases. Full suite: 4585 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

[Copilot]

Review details

Comments suppressed due to low confidence (1)

src/specify_cli/integrations/_migrate_commands.py:115

• The guard claims to fail closed on a corrupted registry, but malformed per-preset metadata is skipped, and a malformed registered_commands value is treated as no matching artifacts. A parseable registry such as {"presets":{"p1":[]}} therefore allows the layout migration even though p1's ownership is unknown, which can delete preset-managed files. Reject malformed entry/registration shapes with _PresetRegistryUnreadableError instead of interpreting them as empty.

    for preset_id, meta in data.get("presets", {}).items():
        if not isinstance(meta, dict):
            continue
        registered_commands = meta.get("registered_commands", {})
        has_commands = (
            isinstance(registered_commands, dict)
            and bool(registered_commands.get(agent_key))
        )
        has_skills = bool(meta.get("registered_skills"))

• Files reviewed: 19/19 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed review 4745191015 in 0aace65:

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 the layout migration even though p1's ownership was unknown — the exact deletion risk the guard exists to prevent.

_installed_presets_affecting_agent now raises _PresetRegistryUnreadableError for a non-dict preset entry, a non-dict registered_commands, or a non-list registered_skills, rejecting the migration before any mutation. Extended the unit test to cover these malformed shapes. Full suite: 4585 passed, 5 skipped.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8), acting autonomously.

[Copilot]

Review details

Comments suppressed due to low confidence (2)

src/specify_cli/integrations/_migrate_commands.py:92

• The unreadable-registry guard does not cover this existence probe. On supported Python versions, Path.exists() may raise PermissionError here before it can be translated into _PresetRegistryUnreadableError; on newer versions that suppress probe errors, it can return False and incorrectly treat an inaccessible registry as absent. Probe with stat() inside the protected path, distinguishing only FileNotFoundError from other OSErrors, so permission failures consistently fail closed with the actionable CLI error.

    if not registry_path.exists():

src/specify_cli/integrations/bob/init.py:59

• This migration guidance is inaccurate for auto-detected Bob 1.x projects: a plain integration upgrade bob already omits --legacy-commands, but is_skills_mode() deliberately preserves the on-disk command layout. Such users must explicitly pass --integration-options "--skills"; distinguish new-project behavior from the migration command so the warning provides an action that actually changes layouts.

        "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/).",

• Files reviewed: 19/19 changed files
• Comments generated: 0 new
• Review effort level: Medium

[mnriem]

Thank you!