From 03ed852dd36dedd207f6ad4345e67cf2205fb791 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 11:54:59 +0000 Subject: [PATCH 1/2] Initial plan From 27f53d286b9f1d721eb7d5639b07ef7a8501d194 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 12:01:56 +0000 Subject: [PATCH 2/2] Preserve user content in agent config files during refresh 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 and 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> --- models/AgentRegistry.cfc | 67 +++++++++++++++-- .../ai/agents/agent-flat-instructions.md | 64 +++++++++-------- .../ai/agents/agent-modern-instructions.md | 72 ++++++++++--------- 3 files changed, 139 insertions(+), 64 deletions(-) diff --git a/models/AgentRegistry.cfc b/models/AgentRegistry.cfc index 4c2f516..eff364e 100644 --- a/models/AgentRegistry.cfc +++ b/models/AgentRegistry.cfc @@ -28,7 +28,10 @@ component singleton { "gemini" : "GEMINI.md", "opencode" : "AGENTS.md" } - AGENT_OPTIONS = [ + // Demarcation markers that wrap the ColdBox CLI-managed section + MANAGED_SECTION_START = "" + MANAGED_SECTION_END = "" + AGENT_OPTIONS = [ { display : "Claude (Anthropic) - Recommended for general development", value : "claude" @@ -126,6 +129,61 @@ component singleton { // Private Helpers // ======================================== + /** + * Merges newly generated managed content with any user-authored content from an existing file. + * + * The managed section is delimited by COLDBOX-CLI:START and COLDBOX-CLI:END HTML comment + * markers. On refresh, only the content between those markers is replaced; everything after + * the end marker (i.e. the user's custom documentation) is preserved unchanged. + * + * Behavior: + * - File does not exist → return newContent as-is (first-time write). + * - File exists but has no end marker → return newContent as-is (old format, no user section to preserve). + * - File exists with end marker → replace managed section, keep user section intact. + * + * @filePath Absolute path to the existing agent config file (may not exist yet). + * @newContent Freshly generated content that includes both START and END markers. + * + * @return Combined content with updated managed section and preserved user section. + */ + private string function mergeUserContent( + required string filePath, + required string newContent + ){ + var endMarker = static.MANAGED_SECTION_END + + // Nothing to preserve — first-time write + if ( !fileExists( filePath ) ) { + return newContent + } + + var existingContent = fileRead( filePath ) + + // Find the end marker in the existing file + var endPos = findNoCase( endMarker, existingContent ) + + // Old-format file (no markers) — write fresh content, no user section to preserve + if ( !endPos ) { + return newContent + } + + // Extract user content: everything that comes after the end marker + var userStartPos = endPos + len( endMarker ) + var userContent = mid( existingContent, userStartPos, len( existingContent ) - userStartPos + 1 ) + + // Find the end marker position in the newly generated content + var newEndPos = findNoCase( endMarker, newContent ) + if ( !newEndPos ) { + // New template has no end marker — return new content plus preserved user section + return newContent & userContent + } + + // Slice off the managed portion of the new content (up to and including the end marker) + var managedContent = left( newContent, newEndPos + len( endMarker ) - 1 ) + + return managedContent & userContent + } + /** * Configure a single agent * @@ -156,13 +214,14 @@ component singleton { // For Claude, write the full content to AGENTS.md and make CLAUDE.md point to it if ( arguments.agent == "claude" ) { var agentsFilePath = getDirectoryFromPath( configPath ) & "AGENTS.md" - fileWrite( agentsFilePath, content ) + var mergedContent = mergeUserContent( agentsFilePath, content ) + fileWrite( agentsFilePath, mergedContent ) fileWrite( configPath, "@AGENTS.md" ) return } - // Write agent config file - fileWrite( configPath, content ) + // Write agent config file, preserving any user-authored content outside the managed section + fileWrite( configPath, mergeUserContent( configPath, content ) ) } /** diff --git a/templates/ai/agents/agent-flat-instructions.md b/templates/ai/agents/agent-flat-instructions.md index a735251..124b093 100644 --- a/templates/ai/agents/agent-flat-instructions.md +++ b/templates/ai/agents/agent-flat-instructions.md @@ -1,3 +1,7 @@ + + + + # |PROJECT_NAME| - AI Agent Instructions This is a ColdBox HMVC application using the **flat template structure** where all application code lives in the webroot. Compatible with Adobe ColdFusion 2018+, Lucee 5.x+, and BoxLang 1.0+. @@ -88,34 +92,6 @@ box testbox run /?fwreinit=true ``` -## Custom Application Details - - - -### Business Domain - - - -### Key Services/Models - - - -### Authentication/Security - - - -### API Endpoints - - - -### Deployment - - - -### Third-Party Integrations - - - ## AI Integration This project includes AI-powered development assistance with guidelines, skills, and MCP documentation servers. @@ -195,3 +171,35 @@ This project has access to the following Model Context Protocol (MCP) documentat - ColdBox Docs: https://coldbox.ortusbooks.com - TestBox: https://testbox.ortusbooks.com - WireBox: https://wirebox.ortusbooks.com + + + + + +## Custom Application Details + + + +### Business Domain + + + +### Key Services/Models + + + +### Authentication/Security + + + +### API Endpoints + + + +### Deployment + + + +### Third-Party Integrations + + diff --git a/templates/ai/agents/agent-modern-instructions.md b/templates/ai/agents/agent-modern-instructions.md index ffb4e4a..a6d4ced 100644 --- a/templates/ai/agents/agent-modern-instructions.md +++ b/templates/ai/agents/agent-modern-instructions.md @@ -1,3 +1,7 @@ + + + + # |PROJECT_NAME| - AI Agent Instructions This is a ColdBox HMVC application using the **modern template structure** with application code separated from the public webroot. Compatible with Adobe ColdFusion 2018+, Lucee 5.x+, and BoxLang 1.0+. @@ -125,38 +129,6 @@ docker-compose logs -f - **ORM:** |ORM_ENABLED| - Object-Relational Mapping via CBORM or Quick - **Migrations:** |MIGRATIONS_ENABLED| - Database version control with CommandBox Migrations -## Custom Application Details - - - -### Business Domain - - - -### Key Services/Models - - - -### Authentication/Security - - - -### API Endpoints - - - -### Database - - - -### Deployment - - - -### Third-Party Integrations - - - ## AI Integration This project includes AI-powered development assistance with guidelines, skills, and MCP documentation servers. @@ -238,3 +210,39 @@ This project has access to the following Model Context Protocol (MCP) documentat - ColdBox Docs: https://coldbox.ortusbooks.com - TestBox: https://testbox.ortusbooks.com - WireBox: https://wirebox.ortusbooks.com + + + + + +## Custom Application Details + + + +### Business Domain + + + +### Key Services/Models + + + +### Authentication/Security + + + +### API Endpoints + + + +### Database + + + +### Deployment + + + +### Third-Party Integrations + +