Add support for loading agent configurations from markdown files Implement MarkdownAgentParser utility to parse YAML frontmatter from markdown agent files, replacing JSON-based configuration. Update AgentManager to load .md files instead of .json files, with full frontmatter parsing and validation. Adds comprehensive test coverage for markdown parsing including edge cases and real-world agent file examples. Fixes #91

Author: acreeger

src/lib/AgentManager.test.ts

@@ -2,6 +2,7 @@ import { readFile } from 'fs/promises'
 import { accessSync } from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
+import { MarkdownAgentParser } from '../utils/MarkdownAgentParser.js'
 import { logger } from '../utils/logger.js'
 
 // Agent schema interface
@@ -53,34 +54,37 @@ export class AgentManager {
 	}
 
 	/**
-	 * Load all agent configuration files
+	 * Load all agent configuration files from markdown (.md) format
 	 * Throws error if agents directory doesn't exist or files are malformed
 	 */
 	async loadAgents(): Promise<AgentConfigs> {
-		// Load all .json files from the agents directory
+		// Load all .md files from the agents directory
 		const { readdir } = await import('fs/promises')
 		const files = await readdir(this.agentDir)
-		const agentFiles = files.filter(file => file.endsWith('.json'))		
+		const agentFiles = files.filter(file => file.endsWith('.md'))
 
 		const agents: AgentConfigs = {}
 
 		for (const filename of agentFiles) {
 			const agentPath = path.join(this.agentDir, filename)
-			const agentName = path.basename(filename, '.json')
 
 			try {
 				const content = await readFile(agentPath, 'utf-8')
-				const agentConfig = JSON.parse(content) as AgentConfig
+
+				// Parse markdown with frontmatter
+				const parsed = this.parseMarkdownAgent(content, filename)
+				const agentConfig = parsed.config
+				const agentName = parsed.name
 
 				// Validate required fields
 				this.validateAgentConfig(agentConfig, agentName)
 
 				agents[agentName] = agentConfig
 				logger.debug(`Loaded agent: ${agentName}`)
 			} catch (error) {
-				logger.error(`Failed to load agent ${agentName}`, { error })
+				logger.error(`Failed to load agent from ${filename}`, { error })
 				throw new Error(
-					`Failed to load agent ${agentName}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+					`Failed to load agent from ${filename}: ${error instanceof Error ? error.message : 'Unknown error'}`,
 				)
 			}
 		}
@@ -105,6 +109,63 @@ export class AgentManager {
 		}
 	}
 
+	/**
+	 * Parse markdown agent file with YAML frontmatter
+	 * @param content - Raw markdown file content
+	 * @param filename - Original filename for error messages
+	 * @returns Parsed agent config and name
+	 */
+	private parseMarkdownAgent(content: string, filename: string): { config: AgentConfig; name: string } {
+		try {
+			// Parse frontmatter using custom parser
+			const { data, content: markdownBody } = MarkdownAgentParser.parse(content)
+
+			// Validate frontmatter has required fields
+			if (!data.name) {
+				throw new Error('Missing required field: name')
+			}
+			if (!data.description) {
+				throw new Error('Missing required field: description')
+			}
+			if (!data.tools) {
+				throw new Error('Missing required field: tools')
+			}
+			if (!data.model) {
+				throw new Error('Missing required field: model')
+			}
+
+			// Parse tools from comma-separated string to array
+			const tools = data.tools
+				.split(',')
+				.map((tool: string) => tool.trim())
+				.filter((tool: string) => tool.length > 0)
+
+			// Validate model and warn if non-standard
+			const validModels = ['sonnet', 'opus', 'haiku']
+			if (!validModels.includes(data.model)) {
+				logger.warn(
+					`Agent ${data.name} uses model "${data.model}" which may not be recognized by Claude CLI, and your workflow may fail or produce unexpected results. ` +
+						`Valid values are: ${validModels.join(', ')}`
+				)
+			}
+
+			// Construct AgentConfig
+			const config: AgentConfig = {
+				description: data.description,
+				prompt: markdownBody.trim(),
+				tools,
+				model: data.model,
+				...(data.color && { color: data.color }),
+			}
+
+			return { config, name: data.name }
+		} catch (error) {
+			throw new Error(
+				`Failed to parse markdown agent ${filename}: ${error instanceof Error ? error.message : 'Unknown error'}`
+			)
+		}
+	}
+
 	/**
 	 * Format loaded agents for Claude CLI --agents flag
 	 * Returns object suitable for JSON.stringify