fix: prevent duplicate updates when multiple agents share the same file

[carlo42]

This PR was created with the help of Cursor

Problem Summary

The update_all_existing_agents() function in .specify/scripts/bash/update-agent-context.sh processes the same file multiple times when multiple variables point to the same file path. This can cause the "Recent Changes" section in agent context files to be incorrect.

Root Cause

Multiple Variables Point to Same File

The following variables all point to the same file ($REPO_ROOT/AGENTS.md):

AGENTS_FILE="$REPO_ROOT/AGENTS.md"  # Line 67
AMP_FILE="$REPO_ROOT/AGENTS.md"     # Line 73
Q_FILE="$REPO_ROOT/AGENTS.md"      # Line 75
BOB_FILE="$REPO_ROOT/AGENTS.md"    # Line 76

Function Processes File Multiple Times

In update_all_existing_agents() (lines 640-719), the function checks each variable independently:

if [[ -f "$AGENTS_FILE" ]]; then
    update_agent_file "$AGENTS_FILE" "Codex/opencode"
    found_agent=true
fi

# ... later ...

if [[ -f "$Q_FILE" ]]; then
    update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
    found_agent=true
fi

# ... later ...

if [[ -f "$BOB_FILE" ]]; then
    update_agent_file "$BOB_FILE" "IBM Bob"
    found_agent=true
fi

Since all three variables point to the same file, when AGENTS.md exists, it gets processed three times in a single function call.

Impact

Data Loss

• May lead to incorrect AGENTS.md file

Functional Impact

• Code generation may still work: Active Technologies, Commands, and Code Style sections are protected by grep checks
• AI agents get confused: Corrupted AGENTS.md file may lead to misleading context about what each feature added
• Project history becomes unreliable: Can't trust the change log to understand technology additions over time

Affected Files

• AGENTS.md - processed 3 times
• Any other file that multiple variables point to (currently only AGENTS.md)

How the Fix Works

1. file_already_processed helper function: Checks if a file has been processed
2. Result: Each file is processed exactly once, regardless of how many variables point to it

Testing

Tested by setting up a minimum test environment with dummy AGENTS.md and plan.md files and ran the update_all_existing_agents() function to verify the contents of the AGENTS.md update

[Copilot]

Pull request overview

This PR adds duplicate prevention logic to the update_all_existing_agents() function to prevent multiple updates when different agent variables point to the same physical file. The implementation uses a bash associative array to track which files have already been processed.

Key changes:

• Introduced processed_files associative array to track updated files
• Added duplicate check conditions to all agent file update blocks
• Marked each processed file in the tracking array after update

---

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

[Copilot]

The update_all_existing_agents() function is missing a check for AMP_FILE. According to the update_specific_agent() function (line 620-621), "amp" is a valid agent type that uses $AMP_FILE which points to $REPO_ROOT/AGENTS.md (same as AGENTS_FILE, Q_FILE, and BOB_FILE).

While the duplicate prevention logic will handle the case where multiple variables point to the same file, the function should still include a check for AMP_FILE for completeness and consistency with the update_specific_agent() function. The check should be added after the CODEBUDDY_FILE check and before the SHAI_FILE check to maintain alphabetical ordering:

if [[ -f "$AMP_FILE" ]] && [[ -z "${processed_files[$AMP_FILE]}" ]]; then
    update_agent_file "$AMP_FILE" "Amp"
    processed_files["$AMP_FILE"]=1
    found_agent=true
fi

Suggested change

	if [[ -f "$AMP_FILE" ]] && [[ -z "${processed_files[$AMP_FILE]}" ]]; then
	update_agent_file "$AMP_FILE" "Amp"
	processed_files["$AMP_FILE"]=1
	found_agent=true
	fi

[carlo42]

I didn't introduce the issue of the missing check for AMP_FILE - it was already missing in the existing code (and I wouldn't know whether that omission was intentional or not)

[localden]

Thanks for the recommendation here, @carlo42 - we're going to take a different approach here, consolidating the AGENTS.md file as just one variable.