add mofa framework usage standards to claude rules

Author: Nixxx19

.claude/mofa-framework-usage.md

@@ -0,0 +1,298 @@
+# MoFA Framework Integration Standards
+
+This codebase uses the **MoFA framework** (`mofa-sdk` crate) as the foundation for LLM interactions, agent management, and tool execution. All new code should integrate with MoFA components to ensure standardization and reusability.
+
+## Core MoFA Components
+
+### 1. LLM Provider Setup
+
+**Always use MoFA's provider abstractions:**
+
+```rust
+use mofa_sdk::llm::openai::{OpenAIConfig, OpenAIProvider};
+use std::sync::Arc;
+
+// Create provider using MoFA's standardized config
+let openai_config = OpenAIConfig::new(&api_key)
+    .with_model(&model)
+    .with_base_url(api_base);  // Works with OpenRouter, vLLM, etc.
+let provider = Arc::new(OpenAIProvider::with_config(openai_config));
+```
+
+**Do NOT:**
+- Create custom HTTP clients for LLM calls
+- Use provider-specific APIs directly
+- Bypass MoFA's provider abstraction
+
+### 2. Agent Creation
+
+**Always use `LLMAgentBuilder` for agent creation:**
+
+```rust
+use mofa_sdk::llm::LLMAgentBuilder;
+use std::sync::Arc;
+
+// Build system prompt first
+let system_prompt = context.build_system_prompt(None).await?;
+
+// Create LLMAgent with tools and executor
+let llm_agent = Arc::new(
+    LLMAgentBuilder::new()
+        .with_id("agent-id")
+        .with_name("Agent Name")
+        .with_provider(provider.clone())
+        .with_system_prompt(system_prompt)
+        .with_tool_executor(tool_executor)  // Use ToolRegistryExecutor
+        .build_async()
+        .await,
+);
+```
+
+**Pattern:**
+- Use `LLMAgentBuilder` builder pattern
+- Always provide `with_id`, `with_name`, `with_provider`, `with_system_prompt`
+- Use `ToolRegistryExecutor` to bridge mofaclaw tools with MoFA agents
+- Use `build_async()` for async construction
+
+### 3. Tool Integration
+
+**Bridge mofaclaw tools with MoFA using `ToolRegistryExecutor`:**
+
+```rust
+use mofaclaw_core::tools::{ToolRegistry, ToolRegistryExecutor};
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+// Create tool registry
+let tools = Arc::new(RwLock::new(ToolRegistry::new()));
+
+// Register tools
+let mut tools_guard = tools.write().await;
+AgentLoop::register_default_tools(&mut tools_guard, &workspace, brave_api_key, bus.clone());
+drop(tools_guard);
+
+// Create executor for MoFA
+let tool_executor = Arc::new(ToolRegistryExecutor::new(tools.clone()));
+```
+
+**Pattern:**
+- Use `ToolRegistry` for tool management
+- Use `ToolRegistryExecutor` to make tools available to MoFA agents
+- Register tools before creating the agent
+
+### 4. Agent Loop Integration
+
+**Use `AgentLoop::with_agent_and_tools` for full integration:**
+
+```rust
+use mofaclaw_core::AgentLoop;
+
+let agent = Arc::new(
+    AgentLoop::with_agent_and_tools(
+        &config,
+        llm_agent,        // From LLMAgentBuilder
+        provider,         // MoFA provider
+        bus.clone(),
+        sessions.clone(),
+        tools.clone(),    // ToolRegistry
+    )
+    .await?,
+);
+```
+
+**For custom configurations (role-based agents):**
+
+```rust
+let agent = Arc::new(
+    AgentLoop::with_agent_and_tools_custom(
+        &config,
+        llm_agent,
+        provider,
+        bus.clone(),
+        sessions.clone(),
+        tools.clone(),
+        max_iterations_override,  // Optional: role-specific limits
+        temperature_override,      // Optional: role-specific temperature
+    )
+    .await?,
+);
+```
+
+### 5. Task Orchestration (Subagents)
+
+**Use MoFA's `TaskOrchestrator` for parallel task execution:**
+
+```rust
+use mofa_sdk::llm::task_orchestrator::{TaskOrchestrator, TaskOrigin};
+
+// TaskOrchestrator is created internally by AgentLoop
+// Access via agent's task_orchestrator field when needed
+```
+
+**Pattern:**
+- `TaskOrchestrator` is automatically created in `AgentLoop`
+- Use for spawning subagents and parallel task execution
+- Follow MoFA's task origin patterns
+
+### 6. Skills Management
+
+**Use MoFA's `SkillsManager` when working with skills:**
+
+```rust
+use mofa_sdk::skills::SkillsManager;
+
+// SkillsManager handles skill loading and execution
+// Skills are defined in workspace/skills/ or bundled in skills/
+```
+
+## Standard Patterns
+
+### Complete Agent Setup Pattern
+
+```rust
+// 1. Load config
+let config = load_config().await?;
+
+// 2. Create MoFA provider
+let openai_config = OpenAIConfig::new(&api_key)
+    .with_model(&model)
+    .with_base_url(api_base);
+let provider = Arc::new(OpenAIProvider::with_config(openai_config));
+
+// 3. Create infrastructure
+let bus = MessageBus::new();
+let sessions = Arc::new(SessionManager::new(&config));
+let tools = Arc::new(RwLock::new(ToolRegistry::new()));
+
+// 4. Register tools
+{
+    let mut tools_guard = tools.write().await;
+    AgentLoop::register_default_tools(&mut tools_guard, &workspace, brave_api_key, bus.clone());
+}
+
+// 5. Create tool executor
+let tool_executor = Arc::new(ToolRegistryExecutor::new(tools.clone()));
+
+// 6. Build system prompt
+let context = ContextBuilder::new(&config);
+let system_prompt = context.build_system_prompt(None).await?;
+
+// 7. Create LLMAgent using MoFA
+let llm_agent = Arc::new(
+    LLMAgentBuilder::new()
+        .with_id("agent-id")
+        .with_name("Agent Name")
+        .with_provider(provider.clone())
+        .with_system_prompt(system_prompt)
+        .with_tool_executor(tool_executor)
+        .build_async()
+        .await,
+);
+
+// 8. Create AgentLoop
+let agent = Arc::new(
+    AgentLoop::with_agent_and_tools(
+        &config,
+        llm_agent,
+        provider,
+        bus.clone(),
+        sessions.clone(),
+        tools.clone(),
+    )
+    .await?,
+);
+```
+
+## Import Standards
+
+**Always import MoFA components from `mofa_sdk`:**
+
+```rust
+// LLM components
+use mofa_sdk::llm::{
+    LLMAgent, LLMAgentBuilder, LLMProvider,
+    openai::{OpenAIConfig, OpenAIProvider},
+    task_orchestrator::{TaskOrchestrator, TaskOrigin},
+};
+
+// Skills
+use mofa_sdk::skills::SkillsManager;
+
+// Re-exported types (use from mofaclaw_core when available)
+use mofaclaw_core::provider::{OpenAIConfig, OpenAIProvider};  // Re-exported
+```
+
+## Benefits of Standardization
+
+1. **Reusability**: Code using MoFA components can be reused across different projects
+2. **Consistency**: All agents follow the same patterns and interfaces
+3. **Maintainability**: Changes to MoFA framework propagate automatically
+4. **Interoperability**: Agents can work together seamlessly
+5. **Future-proofing**: New MoFA features become available automatically
+
+## Anti-Patterns to Avoid
+
+❌ **Don't create custom LLM clients:**
+```rust
+// BAD
+let client = reqwest::Client::new();
+let response = client.post("https://api.openai.com/v1/chat/completions")...
+```
+
+✅ **Use MoFA providers:**
+```rust
+// GOOD
+let provider = Arc::new(OpenAIProvider::with_config(openai_config));
+```
+
+❌ **Don't bypass AgentLoop:**
+```rust
+// BAD
+let response = llm_agent.call_llm_directly(...);
+```
+
+✅ **Use AgentLoop for message processing:**
+```rust
+// GOOD
+let response = agent.process_direct(&message, &session).await?;
+```
+
+❌ **Don't create custom tool execution:**
+```rust
+// BAD
+match tool_name {
+    "read_file" => read_file_manually(...),
+    ...
+}
+```
+
+✅ **Use ToolRegistry and ToolRegistryExecutor:**
+```rust
+// GOOD
+let tool_executor = Arc::new(ToolRegistryExecutor::new(tools.clone()));
+```
+
+## Multi-Agent Collaboration
+
+When creating multi-agent systems:
+
+1. **Each agent should use MoFA components:**
+   - Create agents using `LLMAgentBuilder`
+   - Use `AgentLoop::with_agent_and_tools` or `with_agent_and_tools_custom`
+   - Share `ToolRegistry` instances when appropriate
+
+2. **Standardize agent creation:**
+   - Use consistent patterns for all agents in a team
+   - Apply role-specific overrides via `with_agent_and_tools_custom`
+   - Ensure all agents use the same provider configuration
+
+3. **Tool sharing:**
+   - Share `ToolRegistry` across agents when they need the same tools
+   - Use `ToolRegistryExecutor` for each agent's tool execution
+
+## References
+
+- MoFA SDK: `mofa-sdk` crate (version 0.1.0)
+- Core integration: `core/src/agent/loop_.rs`
+- Provider abstraction: `core/src/provider/mod.rs`
+- Example usage: `cli/src/main.rs` (see `command_gateway` and `command_agent`)