even more help with context

lmajano · lmajano · commit b2b28ea47aae · 2026-04-20T23:20:08.000+02:00
diff --git a/commands/coldbox/ai/install.cfc b/commands/coldbox/ai/install.cfc
@@ -88,14 +88,7 @@ component extends="coldbox-cli.models.BaseAICommand" {
 				print.line()
 			}
 
-			printInfo( "Agents configured:" );
-
-			if ( arguments.verbose ) {
-				result.agents.each( ( agent ) => {
-					print.indentedLine( "  • #agent#" )
-				} )
-				print.line()
-			}
+			printInfo( "Agents configured: #result.agents.toList()#" )
 
 			// Show MCP servers
 			var totalMcpServers = result.mcpServers.core.len() + result.mcpServers.module.len()
diff --git a/commands/coldbox/ai/refresh.cfc b/commands/coldbox/ai/refresh.cfc
@@ -82,6 +82,15 @@ component extends="coldbox-cli.models.BaseAICommand" {
 		if ( !totalAdded && !totalUpdated && !totalRemoved ) {
 			printInfo( "No changes detected. Everything is up to date!" )
 		}
+
+		// Show regenerated agent files
+		if ( structKeyExists( result, "agents" ) && result.agents.len() ) {
+			print.cyanLine( "Agent files regenerated (#result.agents.len()#):" )
+			result.agents.each( ( agent ) => {
+				print.indentedCyanLine( "  ↻ #agent#" )
+			} )
+			print.line()
+		}
 	}
 
 }
diff --git a/models/AIService.cfc b/models/AIService.cfc
@@ -155,7 +155,8 @@ component singleton {
 				"updated" : [],
 				"removed" : []
 			},
-			"mcpServers" : { "added" : [], "removed" : [] }
+			"mcpServers" : { "added" : [], "removed" : [] },
+			"agents"     : []
 		};
 
 		// Load existing manifest
@@ -228,6 +229,7 @@ component singleton {
 			var language = manifest.language ?: "boxlang";
 			manifest.agents.each( ( agent ) => {
 				variables.agentRegistry.configureAgent( directory, agent, language );
+				result.agents.append( agent );
 			} );
 		}
 
diff --git a/models/AgentRegistry.cfc b/models/AgentRegistry.cfc
@@ -384,6 +384,28 @@ component singleton {
 			"all"
 		)
 
+		// Add guidelines inventory (module and additional guidelines only)
+		// Language-specific guideline file and description
+		var languageGuidelineFile = "`.ai/guidelines/core/boxlang.md`"
+		var languageGuidelineDesc = "BoxLang syntax and patterns"
+		if ( arguments.language == "cfml" ) {
+			languageGuidelineFile = "`.ai/guidelines/core/cfml.md`"
+			languageGuidelineDesc = "CFML syntax and patterns"
+		} else if ( arguments.language == "hybrid" ) {
+			languageGuidelineFile = "`.ai/guidelines/core/boxlang.md`"
+			languageGuidelineDesc = "BoxLang/CFML syntax and patterns (or `cfml.md` for CFML-only)"
+		}
+		content = replaceNoCase( content, "|LANGUAGE_GUIDELINE_FILE|", languageGuidelineFile, "all" )
+		content = replaceNoCase( content, "|LANGUAGE_GUIDELINE_DESC|", languageGuidelineDesc, "all" )
+
+		// Generate installed modules content
+		var installedModulesContent = generateInstalledModulesContent( arguments.directory, boxJson )
+		content                     = replaceNoCase( content, "|INSTALLED_MODULES|", installedModulesContent, "all" )
+
+		// Generate handlers snapshot
+		var handlersSnapshotContent = generateHandlersSnapshot( arguments.directory, arguments.templateType )
+		content                     = replaceNoCase( content, "|HANDLERS_SNAPSHOT|", handlersSnapshotContent, "all" )
+
 		// Add guidelines inventory (module and additional guidelines only)
 		var guidelinesContent = generateGuidelinesContent(
 			arguments.directory,
@@ -757,4 +779,116 @@ component singleton {
 		return content.toList( chr( 10 ) )
 	}
 
+	/**
+	 * Generate a list of installed project modules (excluding framework packages)
+	 *
+	 * @directory The project directory
+	 * @boxJson   The parsed box.json struct
+	 *
+	 * @return Formatted markdown bullet list of installed modules
+	 */
+	private function generateInstalledModulesContent(
+		required string directory,
+		required struct boxJson
+	){
+		// Packages to skip — framework internals that aren't actionable for the AI
+		var frameworkPackages = [
+			"coldbox",
+			"testbox",
+			"wirebox",
+			"cachebox",
+			"logbox"
+		]
+
+		var dependencies = arguments.boxJson.dependencies ?: {}
+		var lines        = []
+
+		for ( var pkg in dependencies ) {
+			// Skip framework packages and commandbox-* infrastructure packages
+			if ( frameworkPackages.findNoCase( pkg ) || pkg.startsWith( "commandbox-" ) ) {
+				continue;
+			}
+			var version = dependencies[ pkg ]
+			lines.append( "- **#pkg#** (#version#)" )
+		}
+
+		if ( !lines.len() ) {
+			return "No additional modules installed yet."
+		}
+
+		lines.sort( "textnocase" )
+		return lines.toList( chr( 10 ) )
+	}
+
+	/**
+	 * Generate a snapshot of existing handlers and their public actions
+	 *
+	 * @directory    The project directory
+	 * @templateType "modern" or "flat"
+	 *
+	 * @return Formatted markdown bullet list of handlers and their actions
+	 */
+	private function generateHandlersSnapshot(
+		required string directory,
+		required string templateType
+	){
+		var handlersRoot = arguments.templateType == "modern"
+		 ? "#arguments.directory#/app/handlers"
+		 : "#arguments.directory#/handlers"
+
+		if ( !directoryExists( handlersRoot ) ) {
+			return "No handlers found."
+		}
+
+		// Lifecycle / framework methods to exclude from the action list
+		var lifecycleMethods = [
+			"init",
+			"onmissingaction",
+			"onerror",
+			"onrequeststart",
+			"onrequestend",
+			"onapplicationstart",
+			"onsessionstart",
+			"onsessionend",
+			"onapplicationend"
+		]
+
+		// Use a Java regex to extract public function names
+		var pattern = createObject( "java", "java.util.regex.Pattern" ).compile(
+			"(?i)(?:^|\s)(?:public\s+)?(?:\w+\s+)?function\s+(\w+)\s*\("
+		)
+
+		var handlerFiles = directoryList( handlersRoot, false, "path", "*.cfc|*.bx" )
+		var lines        = []
+
+		for ( var handlerFile in handlerFiles ) {
+			var handlerName = listFirst( getFileFromPath( handlerFile ), "." )
+			var source      = fileRead( handlerFile )
+			var matcher     = pattern.matcher( source )
+			var actions     = []
+
+			while ( matcher.find() ) {
+				var fnName = matcher.group( 1 )
+				if ( !lifecycleMethods.findNoCase( fnName ) ) {
+					if ( !actions.findNoCase( fnName ) ) {
+						actions.append( fnName )
+					}
+				}
+			}
+
+			if ( actions.len() ) {
+				lines.append( "- **#handlerName#**: #actions.toList( ', ' )#" )
+			} else {
+				lines.append( "- **#handlerName#**: _(no public actions)_" )
+			}
+		}
+
+		if ( !lines.len() ) {
+			return "No handlers found."
+		}
+
+		lines.sort( "textnocase" )
+		return lines.toList( chr( 10 ) )
+	}
+
 }
diff --git a/templates/ai/agents/agent-flat-instructions.md b/templates/ai/agents/agent-flat-instructions.md
@@ -37,12 +37,24 @@ This is a ColdBox HMVC application using the **flat template structure** where a
 
 ## Framework Knowledge
 
-Core ColdBox and |LANGUAGE_MODE| guidelines are installed in `.ai/guidelines/core/`. Supported tools
+Core ColdBox and language guidelines are installed in `.ai/guidelines/core/`. Supported tools
 (e.g., VS Code Copilot) load them automatically via file attachments. For other agents, load them
 explicitly when you need framework fundamentals:
 
 - `read_file` on `.ai/guidelines/core/coldbox.md` — ColdBox conventions, handlers, routing, DI reference
-- `read_file` on `.ai/guidelines/core/boxlang.md` — BoxLang syntax and patterns (or `cfml.md` for CFML projects)
+- `read_file` on |LANGUAGE_GUIDELINE_FILE| — |LANGUAGE_GUIDELINE_DESC|
+
+## Installed Modules
+
+The following ColdBox modules are installed in this project. Use these when generating code, checking available services, and suggesting relevant skills or guidelines:
+
+|INSTALLED_MODULES|
+
+## Handlers Snapshot
+
+Current event handlers and their public actions (auto-updated on `coldbox ai refresh`):
+
+|HANDLERS_SNAPSHOT|
 
 ## AI Integration & Resources
 
@@ -177,5 +189,37 @@ This project has access to the following Model Context Protocol (MCP) documentat
 <!-- COLDBOX-CLI:END -->
 
 <!-- ℹ️ YOUR PROJECT DOCUMENTATION — Add your custom details below. ColdBox CLI will NOT overwrite this section. -->
-<!-- 📝 TODO: Describe your business domain, key services, auth approach, and project-specific conventions. -->
-<!-- Suggested sections: Business Domain, Key Services/Models, Authentication/Security, API Endpoints, Database, Deployment -->
+
+## About This Application
+
+> ⚠️ Fill in this section to give your AI assistant context about your specific application.
+
+### Business Domain
+
+<!-- Describe what this application does and its primary purpose -->
+
+### Key Services & Models
+
+<!-- List important services and their responsibilities, e.g.:
+- UserService — authentication, registration, profile management
+- OrderService — cart, checkout, order lifecycle
+-->
+
+### Authentication & Security
+
+<!-- Describe authentication approach, e.g., cbSecurity + JWT, session-based, etc. -->
+
+### API Endpoints
+
+<!-- Document REST API routes if applicable, e.g.:
+- GET /api/v1/users — list users
+- POST /api/v1/users — create user
+-->
+
+### Database
+
+<!-- Document database setup, ORM entities, migrations if applicable -->
+
+### Deployment
+
+<!-- Document deployment process, environments, CI/CD pipeline -->
diff --git a/templates/ai/agents/agent-modern-instructions.md b/templates/ai/agents/agent-modern-instructions.md
@@ -64,12 +64,24 @@ This is a ColdBox HMVC application using the **modern template structure** with
 
 ## Framework Knowledge
 
-Core ColdBox and |LANGUAGE_MODE| guidelines are installed in `.ai/guidelines/core/`. Supported tools
+Core ColdBox and language guidelines are installed in `.ai/guidelines/core/`. Supported tools
 (e.g., VS Code Copilot) load them automatically via file attachments. For other agents, load them
 explicitly when you need framework fundamentals:
 
 - `read_file` on `.ai/guidelines/core/coldbox.md` — ColdBox conventions, handlers, routing, DI reference
-- `read_file` on `.ai/guidelines/core/boxlang.md` — BoxLang syntax and patterns (or `cfml.md` for CFML projects)
+- `read_file` on |LANGUAGE_GUIDELINE_FILE| — |LANGUAGE_GUIDELINE_DESC|
+
+## Installed Modules
+
+The following ColdBox modules are installed in this project. Use these when generating code, checking available services, and suggesting relevant skills or guidelines:
+
+|INSTALLED_MODULES|
+
+## Handlers Snapshot
+
+Current event handlers and their public actions (auto-updated on `coldbox ai refresh`):
+
+|HANDLERS_SNAPSHOT|
 
 ## AI Integration & Resources
 
@@ -216,5 +228,37 @@ This project has access to the following Model Context Protocol (MCP) documentat
 <!-- COLDBOX-CLI:END -->
 
 <!-- ℹ️ YOUR PROJECT DOCUMENTATION — Add your custom details below. ColdBox CLI will NOT overwrite this section. -->
-<!-- 📝 TODO: Describe your business domain, key services, auth approach, and project-specific conventions. -->
-<!-- Suggested sections: Business Domain, Key Services/Models, Authentication/Security, API Endpoints, Database, Deployment -->
+
+## About This Application
+
+> ⚠️ Fill in this section to give your AI assistant context about your specific application.
+
+### Business Domain
+
+<!-- Describe what this application does and its primary purpose -->
+
+### Key Services & Models
+
+<!-- List important services and their responsibilities, e.g.:
+- UserService — authentication, registration, profile management
+- OrderService — cart, checkout, order lifecycle
+-->
+
+### Authentication & Security
+
+<!-- Describe authentication approach, e.g., cbSecurity + JWT, session-based, etc. -->
+
+### API Endpoints
+
+<!-- Document REST API routes if applicable, e.g.:
+- GET /api/v1/users — list users
+- POST /api/v1/users — create user
+-->
+
+### Database
+
+<!-- Document database setup, ORM entities, migrations if applicable -->
+
+### Deployment
+
+<!-- Document deployment process, environments, CI/CD pipeline -->

Original file line number	Diff line number	Diff line change
`@@ -82,6 +82,15 @@ component extends="coldbox-cli.models.BaseAICommand" {`
`82`	`82`	`if ( !totalAdded && !totalUpdated && !totalRemoved ) {`
`83`	`83`	`printInfo( "No changes detected. Everything is up to date!" )`
`84`	`84`	`}`
	`85`	`+`
	`86`	`+ // Show regenerated agent files`
	`87`	`+ if ( structKeyExists( result, "agents" ) && result.agents.len() ) {`
	`88`	`+ print.cyanLine( "Agent files regenerated (#result.agents.len()#):" )`
	`89`	`+ result.agents.each( ( agent ) => {`
	`90`	`+ print.indentedCyanLine( " ↻ #agent#" )`
	`91`	`+ } )`
	`92`	`+ print.line()`
	`93`	`+ }`
`85`	`94`	`}`
`86`	`95`
`87`	`96`	`}`