Module markdown_config

Expand description

Markdown Configuration Module

Provides markdown-based definition of agents, modes, and commands with YAML frontmatter. Enables users to create custom configurations using familiar markdown syntax.

§Overview

The markdown configuration module enables users to define custom agents, modes, and commands using markdown files with YAML frontmatter. This approach combines the readability of markdown with the structure of YAML, making configuration files both human-friendly and machine-parseable.

§Configuration File Format

All markdown configuration files follow this structure:

---
name: example-agent
description: Example agent configuration
model: gpt-4
temperature: 0.7
max_tokens: 2000
---

# Example Agent

This is the markdown content that serves as documentation or prompt.

§Configuration Types

§Agent Configuration

Agents are AI-powered components with specific capabilities and parameters.

File Pattern: *.agent.md

Fields:

name (required): Unique identifier for the agent
description (optional): Human-readable description
model (optional): LLM model to use (e.g., “gpt-4”)
temperature (optional): Model temperature (0.0-2.0)
max_tokens (optional): Maximum response tokens
tools (optional): List of available tools

§Mode Configuration

Modes define editor behaviors and keybindings for different workflows.

File Pattern: *.mode.md

Fields:

name (required): Unique identifier for the mode
description (optional): Human-readable description
keybinding (optional): Keyboard shortcut to activate
enabled (optional): Whether the mode is enabled (default: true)

§Command Configuration

Commands define custom operations with parameters and templates.

File Pattern: *.command.md

Fields:

name (required): Unique identifier for the command
description (optional): Human-readable description
template (required): Command template with parameter placeholders
parameters (optional): List of parameter definitions
keybinding (optional): Keyboard shortcut to invoke

§Discovery and Loading

Configuration files are discovered in the following locations (in priority order):

Project-level: projects/ricecoder/.agent/
User-level: ~/.ricecoder/agents/, ~/.ricecoder/modes/, ~/.ricecoder/commands/
System-level: /etc/ricecoder/agents/ (Linux/macOS)

The ConfigurationLoader automatically discovers and loads all configuration files from these locations, validating each file and registering valid configurations with the ConfigRegistry.

§Hot-Reload Support

The FileWatcher monitors configuration directories for changes. When a file is modified:

File is detected within 5 seconds
Configuration is re-parsed and validated
If valid, configuration is updated in the registry
If invalid, error is logged and previous configuration is retained

This enables runtime configuration updates without requiring application restart.

§Usage Examples

§Loading Configurations

use ricecoder_storage::markdown_config::{ConfigurationLoader, ConfigRegistry};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let registry = Arc::new(ConfigRegistry::new());
    let loader = ConfigurationLoader::new(registry.clone());

    // Discover and load configurations
    let paths = vec![
        std::path::PathBuf::from("~/.ricecoder/agents"),
        std::path::PathBuf::from("projects/ricecoder/.agent"),
    ];

    loader.load_all(&paths).await?;

    // Query loaded configurations
    if let Some(agent) = registry.get_agent("code-review") {
        println!("Found agent: {}", agent.name);
    }

    Ok(())
}

§Parsing Markdown Configuration

use ricecoder_storage::markdown_config::{MarkdownParser, YamlParser};

let markdown_content = r#"---
name: example-agent
description: Example agent
model: gpt-4
---

This is the documentation.
"#;

let parser = MarkdownParser::new();
let parsed = parser.parse(markdown_content)?;

println!("Frontmatter: {:?}", parsed.frontmatter);
println!("Content: {}", parsed.content);

§Validating Configuration

use ricecoder_storage::markdown_config::{AgentConfig, validate_agent_config};

let config = AgentConfig {
    name: "code-review".to_string(),
    description: Some("Code review agent".to_string()),
    model: Some("gpt-4".to_string()),
    temperature: Some(0.7),
    max_tokens: Some(2000),
    tools: vec!["syntax-analyzer".to_string()],
};

validate_agent_config(&config)?;
println!("Configuration is valid!");

§Error Handling

The module provides detailed error information for debugging:

Parsing Errors: Include file path and line numbers
Validation Errors: List all validation failures with field paths
Loading Errors: Indicate which files failed and why

Invalid configurations are logged but don’t prevent loading of other files, enabling graceful degradation when some configurations are malformed.

§Configuration File Locations

§Project-Level Configuration

Place configuration files in projects/ricecoder/.agent/:

projects/ricecoder/
└── .agent/
    ├── examples/
    │   ├── code-review.agent.md
    │   ├── focus.mode.md
    │   └── test.command.md
    ├── custom-agent.agent.md
    └── custom-mode.mode.md

§User-Level Configuration

Place configuration files in ~/.ricecoder/:

~/.ricecoder/
├── agents/
│   ├── my-agent.agent.md
│   └── code-review.agent.md
├── modes/
│   ├── focus.mode.md
│   └── debug.mode.md
└── commands/
    ├── test.command.md
    └── build.command.md

§Best Practices

Use Descriptive Names: Choose names that clearly indicate purpose
Document Configurations: Include markdown documentation explaining usage
Validate Early: Use the validation functions to catch errors early
Organize Files: Group related configurations in directories
Version Control: Commit project-level configurations to version control
Test Configurations: Verify configurations work as expected before deploying

§See Also

ConfigurationLoader: Discovers and loads configuration files
ConfigRegistry: Central registry for loaded configurations
FileWatcher: Monitors configuration files for changes
MarkdownParser: Parses markdown files with YAML frontmatter
YamlParser: Parses and validates YAML frontmatter

Re-exports§

pub use error::MarkdownConfigError;
pub use integration::AgentConfigIntegration;
pub use integration::CommandConfigIntegration;
pub use integration::ModeConfigIntegration;
pub use loader::ConfigFile;
pub use loader::ConfigFileType;
pub use loader::ConfigurationLoader;
pub use loader::LoadedConfig;
pub use parser::MarkdownParser;
pub use registry::ConfigRegistry;
pub use types::AgentConfig;
pub use types::CommandConfig;
pub use types::ModeConfig;
pub use types::ParsedMarkdown;
pub use types::Parameter;
pub use validation::validate_agent_config;
pub use validation::validate_command_config;
pub use validation::validate_mode_config;
pub use watcher::FileWatcher;
pub use yaml_parser::YamlParser;

Modules§

error: Error types for markdown configuration parsing and validation
integration: Integration modules for markdown configuration with ricecoder subsystems
loader: Configuration loader for discovering and loading markdown configurations
parser: Markdown parser for extracting YAML frontmatter and content
registry: Configuration registry for storing and retrieving parsed configurations
types: Data types for markdown configuration
validation: Validation functions for markdown configuration
watcher: File watcher for hot-reload of configuration files
yaml_parser: YAML parser for frontmatter validation and deserialization