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: 16/16 changed files
• Comments generated: 2
• Review effort level: Medium

[mnriem]

Addressed review 4723782860 in 13db5f3.

Comment 1 (setup() drops project context on upgrade) — valid. 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 despite the preservation contract. Now setup() passes project_root into is_skills_mode, so the same managed-artifact detection used by use also governs upgrades. Verified end-to-end: upgrade bob on a stripped legacy install keeps .bob/commands/ and creates no .bob/skills/.

Comment 2 (skill post-processing inconsistency) — valid. 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. Repeated the no-op (delegating to the skills helper) on the registered class so every Bob skill-generation path stays consistent with intent-activated core Bob skills.

Added regression tests for both (upgrade preservation + post-processing no-op). Full suite green: 4536 passed, 5 skipped.

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

[Copilot]

Review details

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

[mnriem]

Addressed review 4724160183 and resolved the merge conflict with main. Pushed as ba6655c.

Comment 1 — no migration path from legacy → skills. Added an explicit --skills opt-in to the Bob integration. It forces the skills layout over on-disk auto-detection, so a legacy Bob 1.x install now has a supported migration: specify integration upgrade bob --integration-options="--skills" scaffolds .bob/skills/ and the upgrade's stale-file pass removes the old .bob/commands/*.md. --skills and --legacy-commands are mutually exclusive (clean error). Disk auto-detection is unchanged when neither flag is passed, so use/switch still won't silently migrate a legacy project.

Comment 2 — active-agent separator ignored the output layout. CommandRegistrar.register_commands now derives 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-*. Bob and Copilot write their skills via their own setup()/skills path, so register_commands only ever emits their command-layout files — the stale-.bob/commands case now renders correctly.

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

While validating the migration end-to-end I found a latent bug it surfaces: 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) 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.

Added regression tests for each of the above (opt-in, mutual exclusion, corrected active-agent separator, remove_manifest=False, and an end-to-end legacy → skills migration asserting the manifest survives and the project stays upgradeable). 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 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