[Bug]: Multi-agent installs update only one agent-context file; the others go stale with no sync

[PascalThuet]

Bug Description

With two coexisting integrations installed in one project (e.g. claude + codex, both multi_install_safe = True), each integration's generated plan command points at a different agent-context file — CLAUDE.md for Claude, AGENTS.md for Codex. Running the plan command as one agent updates only that agent's file. The other file is never touched, so its <!-- SPECKIT START -->…<!-- SPECKIT END --> block keeps pointing at an old plan path. The drift grows on every plan cycle, and nothing surfaces it.

This is by design, not an accident: there is one shared command template (templates/commands/plan.md) with a __CONTEXT_FILE__ placeholder that is substituted per integration at install time, and the update routine only ever writes to a single file. No code path mirrors the managed block across the installed integrations' context files.

Steps to Reproduce

1. specify init --here --integration claude
2. specify integration install codex
3. Run the plan command (/speckit.plan) as Claude on a new feature. Note that CLAUDE.md's managed block is updated to the new plan path.
4. Open AGENTS.md — its managed block still references the previous plan (or is empty), and running the plan command as Codex now updates AGENTS.md but leaves CLAUDE.md stale.

Expected Behavior

One of:

• The context-update path updates all installed integrations' context files, or
• Context lives in a single shared file that every integration's command references, or
• The docs explicitly state that multi-agent context files must be synced manually.

Actual Behavior

Only the running agent's context file is updated. The other installed agents' context files diverge and point at a stale plan path. An agent (or human) reading the un-updated file is sent to the wrong plan. No error is raised — the failure is silent divergence.

Specify CLI Version

0.10.0 (reproduced on main @ 7106858)

AI Agent

Claude Code

Additional Context

Source references on main (@ 7106858):

• templates/commands/plan.md:158 — single template instructs updating the block in __CONTEXT_FILE__; line 70 also tells the agent to update context via the agent script.
• src/specify_cli/integrations/base.py:938 — __CONTEXT_FILE__ is substituted per integration at install time.
• src/specify_cli/integrations/claude/__init__.py:45 → context_file = "CLAUDE.md"; src/specify_cli/integrations/codex/__init__.py:29 → context_file = "AGENTS.md"; both multi_install_safe = True.
• src/specify_cli/integrations/base.py:709 — upsert_context_section writes only project_root / self.context_file; no other integration's file is considered.
• extensions/agent-context/agent-context-config.yml — context_file is a single scalar; extensions/agent-context/scripts/bash/update-agent-context.sh updates only that one file. The value is overwritten when the default integration changes, so it can even point at a different file than the agent currently running the command.
• tests/integrations/test_registry.py (test_safe_integrations_have_distinct_context_files) enforces that multi-install-safe integrations have distinct context files — isolation is intentional, but no reconciliation exists.

Note: inline agent-context updates during integration setup are deprecated for removal in v0.12.0 (deprecation notice at base.py:671), with context management moving to the agent-context extension. A fix should target the extension's config/script so it covers the future code path rather than the deprecated inline one — e.g. make context_file a list derived from the installed-integration registry, or centralize the managed block in one shared file.

Possible fix sketch: iterate the installed-integration registry and upsert the managed block into each integration's context_file, or introduce a single shared context source that all per-agent files reference. Happy to open a PR if maintainers agree on the direction.

[mnriem]

Closing as won't fix.

Multi-agent installs are allowed but come with caveats like this — each integration maintains its own context file, and no reconciliation exists between them. This is a known trade-off of running multiple agents in the same project.

For a stable experience not prone to these multi-install edge cases, use specify integration switch to swap between agents. This ensures a single active integration with clean context at all times.

Additionally, core Spec Kit commands are moving away from relying on agent-context file updates altogether (deprecated inline updates will be removed in v0.12.0), which eliminates this drift problem at the source.