Skip to content

Preserve user content in agent config files on coldbox ai refresh#43

Merged
lmajano merged 2 commits intodevelopmentfrom
copilot/fix-claude-file-overwrite-issue
Mar 28, 2026
Merged

Preserve user content in agent config files on coldbox ai refresh#43
lmajano merged 2 commits intodevelopmentfrom
copilot/fix-claude-file-overwrite-issue

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 28, 2026

coldbox ai refresh blindly overwrites agent config files (e.g. CLAUDE.md / AGENTS.md), destroying any user or AI-agent customizations on every run.

Approach

Introduce <!-- COLDBOX-CLI:START --> / <!-- COLDBOX-CLI:END --> demarcation markers in the generated files. On refresh, only the content between those markers is replaced; everything after the end marker is preserved.

Changes

Templates (agent-modern-instructions.md, agent-flat-instructions.md)

  • Wrap all framework-managed content in COLDBOX-CLI:START / COLDBOX-CLI:END markers
  • Move "Custom Application Details" user section to after the end marker with an explanatory comment
  • Restructure modern template so all managed content is contiguous above the user section

AgentRegistry.cfc

  • Add MANAGED_SECTION_START / MANAGED_SECTION_END static constants
  • Add mergeUserContent(filePath, newContent) — extracts the user section from an existing file and re-appends it after the refreshed managed block:
    • No existing file → write as-is (first install)
    • Existing file without end marker → overwrite (old format, no user section to preserve)
    • Existing file with end marker → replace managed section, keep everything after it
  • Wire mergeUserContent() into configureAgent() for all agent types (including Claude's AGENTS.md)

Example of resulting file structure:

<!-- COLDBOX-CLI:START -->
<!-- ⚡ Managed by ColdBox CLI — refreshed on `coldbox ai refresh`. Do not edit between markers. -->

# MyApp - AI Agent Instructions
... framework-generated content ...

<!-- COLDBOX-CLI:END -->

<!-- ℹ️ YOUR PROJECT DOCUMENTATION — ColdBox CLI will NOT overwrite this section. -->

## Custom Application Details
... user/AI-authored content survives refresh ...

⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS or Windows machine with Raycast.

Copilot AI linked an issue Mar 28, 2026 that may be closed by this pull request
@lmajano lmajano marked this pull request as ready for review March 28, 2026 11:59
Copilot AI review requested due to automatic review settings March 28, 2026 11:59
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot wasn't able to review any files in this pull request.

Add COLDBOX-CLI:START/END markers to agent instruction templates so
that `coldbox ai refresh` only updates the managed framework section
while leaving user-authored documentation intact.

- Add <!-- COLDBOX-CLI:START --> and <!-- COLDBOX-CLI:END --> markers to
  both agent-modern-instructions.md and agent-flat-instructions.md
- Restructure templates: all managed content (guidelines, skills, MCP,
  project info) sits inside the markers; Custom Application Details
  moves to after the end marker with a note that it won't be overwritten
- Add MANAGED_SECTION_START/END static constants to AgentRegistry.cfc
- Add private mergeUserContent() helper that extracts the user section
  from an existing file and appends it to the refreshed managed section
- Update configureAgent() to call mergeUserContent() for all agents
  (including AGENTS.md for Claude) instead of blindly overwriting

Agent-Logs-Url: https://github.com/ColdBox/coldbox-cli/sessions/2b2dc668-9136-4fc3-9cec-b1d19209c61b

Co-authored-by: lmajano <137111+lmajano@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix CLAUDE.md file overwritten when AI refreshed Preserve user content in agent config files on coldbox ai refresh Mar 28, 2026
Copilot AI requested a review from lmajano March 28, 2026 12:02
@lmajano lmajano merged commit ce91d29 into development Mar 28, 2026
1 check passed
@lmajano lmajano deleted the copilot/fix-claude-file-overwrite-issue branch March 28, 2026 12:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLAUDE.md File Overwritten When AI Refreshed

3 participants