feat(targets): add IBM Bob support

[Ching Wei Kang (WilliamK112)]

Description

Adds IBM Bob as a stable native APM target, closing the Skills/Hooks/MCP gap described in #2736.

The implementation follows IBM Bob's documented contracts:

• Agent Skills: .bob/skills/<name>/SKILL.md and ~/.bob/skills/<name>/SKILL.md
• lifecycle hooks: .bob/settings.json and ~/.bob/settings/settings.json, preserving user-authored settings and hooks
• MCP: .bob/mcp.json and ~/.bob/mcp.json under mcpServers, with Bob-native STDIO, Streamable HTTP, and legacy SSE shapes
• compiled instructions: project-root AGENTS.md, which Bob loads automatically

bob is available through --target bob, participates in --target all, auto-detects from .bob/, supports project/user scope, and is wired through cleanup, dropped-target reconciliation, ownership, governance, CLI help, and the target documentation.

Bob's MCP docs do not promise runtime environment-variable interpolation, so the adapter uses APM's install-time resolution path and keeps the generated config private (0600). Unsupported Bob hook events are skipped with a warning rather than writing a schema Bob cannot consume.

Official references:

• https://bob.ibm.com/docs/ide/features/skills
• https://bob.ibm.com/docs/ide/configuration/lifecycle-hooks
• https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob

Fixes #2736

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• Added tests for new functionality
• ruff check and ruff format --check across src/, tests/, and architecture scripts
• pylint duplicate-code and architecture/auth boundary lint gates
• Bob adapter/target, catalog, scope, hook/MCP cleanup, dropped-target, and CLI lifecycle tests
• CLI docs contract and rendered-command verification
• Astro docs production build (124 pages, 1,031 relative links)

Spec conformance (OpenAPM v0.1)

• N/A -- this adds a harness integration target and does not change an existing OpenAPM v0.1 normative requirement.

[Copilot]

🟡 Changes recommended

The new CHANGELOG entry is wrapped across multiple lines, but the repo’s changelog rules require one concise line per PR entry.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds IBM Bob as a first-class APM target, wiring it into the target catalog/detection pipeline and implementing Bob-native deployment for Agent Skills, lifecycle hooks, MCP configuration, and AGENTS.md compilation. The PR also updates docs and expands unit coverage to characterize the new target across registry, scope, and adapter behavior.

Changes:

• Add the bob target capability/profile (in all, auto-detect via .bob/, compile family agents) and plumb it through target detection, catalogs, and uninstall/cleanup paths.
• Implement IBM Bob MCP configuration support via a new BobClientAdapter, including config merge semantics and private-file permissions.
• Update documentation (targets matrix, CLI reference, schema docs, integrations) and add/extend unit tests for Bob target behavior.

File summaries

File	Description
tests/unit/integration/test_targets_registry_completeness.py	Adds BobClientAdapter to adapter registry completeness coverage.
tests/unit/integration/test_bob_target.py	New acceptance-style unit tests for Bob target detection, skills, hooks merge/cleanup, and dropped-target reconciliation.
tests/unit/core/test_target_catalog.py	Characterizes bob in known target sets and native profile snapshot expectations.
tests/unit/core/test_target_catalog_owner_invariant.py	Adds bob to the catalog owner invariant test set.
tests/unit/core/test_scope.py	Ensures bob is present in known targets for scope-related tests.
tests/unit/adapters/test_bob_client_adapter.py	New unit tests for Bob MCP adapter paths, merge behavior, transports, and stale cleanup.
src/apm_cli/policy/policy_checks.py	Includes .bob in script policy checks’ known directories.
src/apm_cli/models/dependency/host_virtual.py	Includes .bob in virtual host directory allow-list/set.
src/apm_cli/integration/targets.py	Adds Bob TargetProfile; introduces is_user_scope to support scope-aware hook config paths.
src/apm_cli/integration/mcp_integrator.py	Extends MCP stale-removal to also clean Bob’s .bob/mcp.json.
src/apm_cli/integration/mcp_integrator_install.py	Adds Bob runtime discovery signals for project/user scope.
src/apm_cli/integration/hook_integrator.py	Adds Bob hook event mapping, scope-specific config filename support, and unsupported-event skipping.
src/apm_cli/integration/hook_file_routing.py	Registers Bob for hook-file routing.
src/apm_cli/integration/_hook_dropped_targets.py	Uses scope-aware hook config filename/sidecar location for dropped-target reconciliation.
src/apm_cli/install/manifest_reconcile.py	Updates hook merge projection specs to support nested (scope-specific) config filenames.
src/apm_cli/factory.py	Registers BobClientAdapter in the client factory MCP registry.
src/apm_cli/core/target_detection.py	Adds Bob to auto-detection, agents alias sets, compile decision, and target descriptions.
src/apm_cli/core/target_catalog.py	Adds Bob capability to the canonical target catalog (in all).
src/apm_cli/core/errors.py	Updates empty-targets teaching message to include .bob/.
src/apm_cli/core/deployment_ledger.py	Maps .bob/ to the bob target for deployment ledger normalization.
src/apm_cli/compilation/context_optimizer.py	Includes .bob in context optimizer’s known harness directories.
src/apm_cli/commands/uninstall/engine.py	Updates native-hook state detection to use scope-aware hook config filename/sidecar path.
src/apm_cli/adapters/client/bob.py	New IBM Bob MCP client adapter implementation.
README.md	Lists IBM Bob among supported harnesses in the README intro section.
docs/src/content/docs/reference/targets-matrix.md	Adds Bob to the targets matrix and documents Bob-specific conventions.
docs/src/content/docs/reference/manifest-schema.md	Adds bob to documented manifest target values and target restriction docs.
docs/src/content/docs/reference/cli/uninstall.md	Notes .bob/settings.json hook merge cleanup in uninstall behavior.
docs/src/content/docs/reference/cli/targets.md	Adds Bob to apm targets sample output and detection table.
docs/src/content/docs/reference/cli/install.md	Adds Bob to --target docs and documents Bob MCP env-var handling + permissions.
docs/src/content/docs/reference/cli/init.md	Adds Bob to apm init --target docs.
docs/src/content/docs/reference/cli/deps.md	Adds Bob to apm deps update --target docs.
docs/src/content/docs/reference/cli/compile.md	Adds Bob to compile recommendations and output table.
docs/src/content/docs/integrations/ide-tool-integration.md	Documents Bob MCP config paths and compile usage in the integrations guide.
docs/src/content/docs/consumer/install-mcp-servers.md	Adds Bob to the MCP config path matrix and global-write behavior description.
docs/src/content/docs/concepts/primitives-and-targets.md	Adds Bob to the targets list and compatibility matrix.
CHANGELOG.md	Adds an Unreleased entry announcing stable IBM Bob target support.

Review details

• Files reviewed: 36/36 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Ching Wei Kang (WilliamK112)]

Addressed the changelog formatting recommendation in f59b8181: the #2909 entry is now a single concise line, matching the repository convention.

[Jan Kacik (Consek)]

Ching Wei Kang (@WilliamK112) Sorry for jumping into this PR but I might have some info on bob that could be useful your PR.

Regarding MCPs support:

• global mcp configuration lives under ~/.bob/settings/mcp.json instead of ~/.bob/mcp.json even though docs might say otherwise
• variable substitution in mcp config only works in headers field and only in ${env:VARIABLE} format, no env field extrapolation supported from what I noticed

If it's possible agent support would also be a great addition. They live in ~/.bob/agents and are in standard markdown format. Extra things that need consideration:

• all extra fields need to be removed, eg. model, permissions or allowedTools (if shares agents with kiro); only name, description and tools are allowed. All should be added to the resulting file if present in source as I saw missing name blocking discovery
• tools field needs translation, seems that things starting with @ can break some things so "@mcp" should be translated to mcp (without quotes); write also should be translated to edit as that is the convention used in Bob; better to strip all non-standard tools to prevent any issues (only read, edit, command, browser, mcp seems supported)

Would be happy to test the changes locally after they are implemented and provide feedback regarding any issues.

[Ching Wei Kang (WilliamK112)]

Thanks for jumping in—hands-on Bob testing would be very useful.

I rechecked the current IBM documentation before changing the adapter. The MCP page explicitly says that Edit Global MCP opens ~/.bob/mcp.json, while project configuration is .bob/mcp.json: https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob. That matches this PR. Could you share the Bob version you tested and, ideally, what path Edit Global MCP opens there? If the shipped application differs from the docs, I would like to capture that as a version-specific compatibility case rather than guessing.

The current adapter intentionally resolves environment references at install time because the MCP documentation does not define general runtime interpolation. Your observation that ${env:VARIABLE} works specifically in headers is helpful; testing the generated configuration from this branch would help establish whether preserving that syntax is safe across current Bob versions.

Agent personas also look worthwhile. The current docs confirm project/user .bob/agents/ locations and the name, description, and tools fields. However, #2736 and its accepted first-cut scope explicitly call for Skills, Hooks, and MCP, so I would prefer to keep personas as a focused follow-up instead of expanding this already substantial PR. I would be happy to work from your test feedback on that follow-up.