From 8dfe6a8356b6b1022abc2dabc18375283c82d972 Mon Sep 17 00:00:00 2001
From: m3tm3re <p@m3ta.dev>
Date: Fri, 10 Apr 2026 16:47:55 +0200
Subject: [PATCH] feat(lib): add agents.nix with loadCanonical and renderer
 stubs

---
 lib/agents.nix  | 82 +++++++++++++++++++++++++++++++++++++++++++++++++
 lib/default.nix |  3 ++
 2 files changed, 85 insertions(+)
 create mode 100644 lib/agents.nix

diff --git a/lib/agents.nix b/lib/agents.nix
new file mode 100644
index 0000000..d059726
--- /dev/null
+++ b/lib/agents.nix
@@ -0,0 +1,82 @@
+# Harness-agnostic agent management utilities
+#
+# This module provides functions to load canonical agent definitions and
+# render them for different AI coding tools (OpenCode, Claude Code, Pi).
+#
+# Usage in your configuration:
+#
+#   # In your flake or configuration:
+#   let
+#     m3taLib = inputs.m3ta-nixpkgs.lib.${system};
+#
+#     # Load canonical agents from the AGENTS flake input
+#     canonical = m3taLib.agents.loadCanonical { agentsInput = inputs.agents; };
+#
+#     # Render for a specific tool
+#     agentFiles = m3taLib.agents.renderForTool {
+#       inherit pkgs;
+#       agentsInput = inputs.agents;
+#       tool = "opencode";
+#     };
+#   in { ... }
+#
+# Renderers are stubs for now (Tasks 9-11 will provide real implementations).
+{lib}: let
+  agentsLib = {
+    # Load canonical agent definitions from the AGENTS flake input.
+    # agentsInput: the AGENTS flake (e.g., inputs.agents in a consuming flake)
+    # Returns the canonical attrset from lib.loadAgents (keyed by slug).
+    loadCanonical = {agentsInput}: agentsInput.lib.loadAgents;
+
+    # Stub: OpenCode renderer — produces .opencode/agents/*.md files.
+    # To be implemented in Task 9.
+    renderForOpencode = {
+      pkgs,
+      canonical,
+      modelOverrides ? {},
+    }:
+      pkgs.runCommand "opencode-agents" {} "echo stub > $out";
+
+    # Stub: Claude Code renderer — produces .claude/agents/*.md files.
+    # To be implemented in Task 10.
+    renderForClaudeCode = {
+      pkgs,
+      canonical,
+      modelOverrides ? {},
+    }:
+      pkgs.runCommand "claude-code-agents" {} "echo stub > $out";
+
+    # Stub: Pi renderer — produces AGENTS.md + SYSTEM.md.
+    # To be implemented in Task 11.
+    renderForPi = {
+      pkgs,
+      canonical,
+    }:
+      pkgs.runCommand "pi-agents" {} "echo stub > $out";
+
+    # Dispatch renderer by tool name.
+    # tool: "opencode" | "claude-code" | "pi"
+    renderForTool = {
+      pkgs,
+      agentsInput,
+      tool,
+      modelOverrides ? {},
+    }: let
+      canonical = agentsInput.lib.loadAgents;
+    in
+      if tool == "opencode"
+      then
+        agentsLib.renderForOpencode {
+          inherit pkgs canonical modelOverrides;
+        }
+      else if tool == "claude-code"
+      then
+        agentsLib.renderForClaudeCode {
+          inherit pkgs canonical modelOverrides;
+        }
+      else if tool == "pi"
+      then agentsLib.renderForPi {inherit pkgs canonical;}
+      else throw "lib.agents.renderForTool: unknown tool '${tool}'. Must be opencode, claude-code, or pi.";
+  };
+in
+  agentsLib
diff --git a/lib/default.nix b/lib/default.nix
index 1b1a2e7..b4dd130 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -9,4 +9,7 @@
 
   # OpenCode rules injection utilities
   opencode-rules = import ./opencode-rules.nix {inherit lib;};
+
+  # Agent configuration management utilities
+  agents = import ./agents.nix {inherit lib;};
 }