[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.

[kehansama]

This is a sharp bug report — it exposes a fundamental tension in multi-agent tooling: the assumption that "one context file per agent" equals "isolation," without a reconciliation mechanism when agents share the same project state.

The silent divergence you describe is particularly dangerous because it is undetectable from within a single agent's perspective. Each agent reads its own context file and sees a consistent (but stale) view. The inconsistency only manifests at handoff boundaries, which means the failure surface grows combinatorially with the number of installed agents.

A few structural observations:

1. The root cause is architectural, not implementation-level. Having per-agent context files without a shared canonical source means the system has no single source of truth for project state. This is the classic distributed consistency problem — and eventual consistency is not acceptable when the cost of a wrong plan path is wasted agent work.

2. Your fix sketch (iterate all installed integrations and upsert) is the right direction, but it needs a versioning layer. When Agent A updates the context and Agent B reads it later, Agent B needs to know whether it is seeing the latest state or a cached version. A simple monotonic sequence number or content hash in each managed block would make drift detectable.

3. The deprecation of inline context updates (v0.12.0) is an opportunity. Moving to the agent-context extension means you can redesign the data model from scratch. Instead of N context files that must be kept in sync, consider a single shared context store with per-agent view projections. Each agent reads the same underlying data but sees only the slice relevant to its integration.

We encountered this exact multi-agent context synchronization problem while building AgentRelay. The solution was a relay layer that maintains a canonical project state and exposes it through per-agent adapters. Each agent's context file becomes a thin view into the relay's store, and updates flow through the relay rather than directly to individual files. This eliminates the divergence problem by design — there is only one source of truth.

For spec-kit specifically, a practical intermediate step: add a post-plan hook that iterates all registered integrations and runs upsert_context_section on each. This fixes the immediate symptom while you design the proper extension-level solution.

Curious: does the agent-context extension's YAML config already support a list of context files, or is it still a single scalar? If the latter, that might be the first schema change to unblock the fix.

AgentRelay: https://github.com/kehansama/agentrelay