feat: Add library:// URI syntax and --prompt alias for run command

- Add library:// URI syntax for running agents from built-in library
  Format: library://domain/agent-name
  Example: aofctl run agent library://kubernetes/pod-doctor --prompt "debug CrashLoopBackOff"
- Add --prompt as an alias for --input (more intuitive for LLM interactions)
- Provide helpful error messages when agent not found, showing available agents
- Updated CLI reference documentation with examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: gouravjshah

CHANGELOG.md

@@ -19,6 +19,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Displays domain (category), agent name, status, and model
   - Supports filtering by agent name: `aofctl get agents pod-doctor --library`
   - Supports JSON/YAML output formats
+- `library://` URI syntax for running agents from the built-in library
+  - Format: `library://domain/agent-name`
+  - Example: `aofctl run agent library://kubernetes/pod-doctor --prompt "debug CrashLoopBackOff"`
+  - Helpful error messages showing available agents when agent not found
+- `--prompt` as an alias for `--input` in the run command
+  - More intuitive for LLM-style interactions
 
 ### Fixed
 - Script node YAML field naming (`scriptConfig` camelCase)

crates/aofctl/src/cli.rs

@@ -34,10 +34,11 @@ pub enum Commands {
         resource_type: String,
 
         /// Resource name or configuration file
+        /// Supports library:// URIs: library://kubernetes/pod-doctor
         name_or_config: String,
 
-        /// Input/query for the agent
-        #[arg(short, long)]
+        /// Input/query for the agent (alias: --prompt)
+        #[arg(short, long, visible_alias = "prompt")]
         input: Option<String>,
 
         /// Output format (json, yaml, text)

crates/aofctl/src/commands/run.rs

@@ -233,6 +233,90 @@ pub async fn execute(
     }
 }
 
+/// Resolve a library:// URI to the actual file path
+/// Format: library://domain/agent-name (e.g., library://kubernetes/pod-doctor)
+fn resolve_library_uri(uri: &str) -> Result<std::path::PathBuf> {
+    // Parse library://domain/agent-name
+    let path = uri.strip_prefix("library://")
+        .ok_or_else(|| anyhow!("Invalid library URI: {}", uri))?;
+
+    let parts: Vec<&str> = path.split('/').collect();
+    if parts.len() != 2 {
+        return Err(anyhow!(
+            "Invalid library URI format: {}\nExpected: library://domain/agent-name\nExample: library://kubernetes/pod-doctor",
+            uri
+        ));
+    }
+
+    let domain = parts[0];
+    let agent_name = parts[1];
+
+    // Find the library directory
+    let library_path = find_library_path()?;
+
+    // Try both .yaml and .yml extensions
+    for ext in &["yaml", "yml"] {
+        let agent_path = library_path.join(domain).join(format!("{}.{}", agent_name, ext));
+        if agent_path.exists() {
+            return Ok(agent_path);
+        }
+    }
+
+    // Agent not found - provide helpful error
+    let available = list_library_agents(&library_path, domain);
+    Err(anyhow!(
+        "Agent '{}' not found in library domain '{}'\n\nAvailable agents in '{}':\n  {}\n\nRun 'aofctl get agents --library' to see all available agents.",
+        agent_name, domain, domain,
+        available.join(", ")
+    ))
+}
+
+/// Find the library directory
+fn find_library_path() -> Result<std::path::PathBuf> {
+    let candidates = [
+        std::path::PathBuf::from("library"),
+        std::path::PathBuf::from("./library"),
+        std::env::current_exe()
+            .ok()
+            .and_then(|p| p.parent().map(|p| p.join("library")))
+            .unwrap_or_default(),
+        std::env::current_exe()
+            .ok()
+            .and_then(|p| p.parent().and_then(|p| p.parent()).map(|p| p.join("library")))
+            .unwrap_or_default(),
+    ];
+
+    for candidate in candidates {
+        if candidate.exists() && candidate.is_dir() {
+            return Ok(candidate);
+        }
+    }
+
+    Err(anyhow!(
+        "Library directory not found. Make sure you're running from the project root or the library is installed."
+    ))
+}
+
+/// List available agents in a library domain
+fn list_library_agents(library_path: &std::path::Path, domain: &str) -> Vec<String> {
+    let domain_path = library_path.join(domain);
+    let mut agents = Vec::new();
+
+    if let Ok(entries) = std::fs::read_dir(&domain_path) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.extension().map_or(false, |e| e == "yaml" || e == "yml") {
+                if let Some(stem) = path.file_stem() {
+                    agents.push(stem.to_string_lossy().to_string());
+                }
+            }
+        }
+    }
+
+    agents.sort();
+    agents
+}
+
 /// Run an agent with configuration
 async fn run_agent(
     config: &str,
@@ -241,15 +325,23 @@ async fn run_agent(
     schema: Option<OutputSchema>,
     context: Option<&AofContext>,
 ) -> Result<()> {
+    // Resolve library:// URIs to actual file paths
+    let config_path = if config.starts_with("library://") {
+        resolve_library_uri(config)?
+    } else {
+        std::path::PathBuf::from(config)
+    };
+    let config_str = config_path.to_string_lossy();
+
     // Check if interactive mode should be enabled (when no input provided and stdin is a TTY)
     let interactive = input.is_none() && io::stdin().is_terminal();
 
     if interactive {
         // Load agent configuration
-        let config_content = fs::read_to_string(config)
-            .with_context(|| format!("Failed to read config file: {}", config))?;
+        let config_content = fs::read_to_string(&config_path)
+            .with_context(|| format!("Failed to read config file: {}", config_str))?;
 
-        let agent_config = parse_agent_config(&config_content, config)?;
+        let agent_config = parse_agent_config(&config_content, &config_str)?;
 
         let agent_name = agent_config.name.clone();
 
@@ -266,18 +358,18 @@ async fn run_agent(
     }
 
     // Non-interactive mode: normal logging to console
-    info!("Loading agent config from: {}", config);
+    info!("Loading agent config from: {}", config_str);
     if let Some(ctx) = context {
         info!("Context: {} (approval required: {})",
             ctx.name(),
             ctx.spec.approval.as_ref().map(|a| a.required).unwrap_or(false)
         );
     }
 
-    let config_content = fs::read_to_string(config)
-        .with_context(|| format!("Failed to read config file: {}", config))?;
+    let config_content = fs::read_to_string(&config_path)
+        .with_context(|| format!("Failed to read config file: {}", config_str))?;
 
-    let agent_config = parse_agent_config(&config_content, config)?;
+    let agent_config = parse_agent_config(&config_content, &config_str)?;
 
     let agent_name = agent_config.name.clone();
     info!("Agent loaded: {}", agent_name);

docs/reference/aofctl.md

@@ -185,21 +185,42 @@ aofctl run <resource_type> <name_or_file> [flags]
 ```
 
 **Flags:**
-- `-i, --input string` - Input/query for the agent
+- `-i, --input string` - Input/query for the agent (alias: `--prompt`)
 - `-o, --output string` - Output format: json|yaml|text (default: text)
 
+**Agent Sources:**
+- **File path**: `aofctl run agent my-agent.yaml`
+- **Library URI**: `aofctl run agent library://domain/agent-name`
+
 **Examples:**
 ```bash
-# Interactive mode
+# Interactive mode (opens REPL)
 aofctl run agent my-agent.yaml
 
-# With query
-aofctl run agent my-agent.yaml -i "Show me all pods"
+# With query (non-interactive)
+aofctl run agent my-agent.yaml --input "Show me all pods"
+
+# Using --prompt alias
+aofctl run agent my-agent.yaml --prompt "Show me all pods"
+
+# Run agent from library
+aofctl run agent library://kubernetes/pod-doctor --prompt "Debug CrashLoopBackOff in namespace production"
+
+# Run library agent with JSON output
+aofctl run agent library://incident/rca-agent --prompt "Analyze high latency" -o json
 
 # Run workflow
 aofctl run workflow incident-response.yaml
 ```
 
+**Library Domains:**
+- `kubernetes` - Pod diagnostics, resource optimization
+- `incident` - RCA, incident command, postmortems
+- `cicd` - Pipeline troubleshooting, builds
+- `security` - Vulnerability scanning, compliance
+- `observability` - Alerts, logging, tracing
+- `cloud` - Cost optimization, drift detection
+
 **Example Output:**
 ```bash
 $ aofctl run agent k8s-helper.yaml --input "Show me all pods"