feat: config with agents rework

2026-04-13 16:53:17 +02:00
parent a81e178856
commit ccca3dd9db
47 changed files with 5940 additions and 22 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
-# Opencode Skills Repository
+# Agent Skills Repository

-Configuration repository for Opencode Agent Skills, context files, and agent configurations. Deployed via Nix home-manager to `~/.config/opencode/`.
+Configuration repository for AI Agent Skills, canonical agent definitions, context files, and agent configurations. Deployed via Nix home-manager to `~/.config/opencode/` (or equivalent paths for other tools).

 ## Quick Commands

@@ -12,6 +12,9 @@ Configuration repository for Opencode Agent Skills, context files, and agent con

 # Skill creation
 python3 skills/skill-creator/scripts/init_skill.py <name> --path skills/
+
+# Verify agent TOML parses
+for f in agents/*/agent.toml; do nix eval --impure --expr "builtins.fromTOML (builtins.readFile ./$f)" --json > /dev/null && echo "OK: $f"; done
 ```

 ## Directory Structure
@@ -28,8 +31,11 @@ python3 skills/skill-creator/scripts/init_skill.py <name> --path skills/
 │   ├── languages/   # Python, TypeScript, Nix, Shell
 │   ├── concerns/    # Testing, naming, documentation, etc.
 │   └── frameworks/  # Framework-specific rules (n8n, etc.)
-├── agents/          # Agent definitions (agents.json)
-├── prompts/         # System prompts (chiron*.txt)
+├── agents/          # Canonical agent definitions (harness-agnostic)
+│   ├── SCHEMA.md            # Canonical agent.toml schema definition
+│   └── <name>/
+│       ├── agent.toml       # Agent metadata, permissions, references
+│       └── system-prompt.md # Agent system prompt (markdown)
 ├── context/         # User profiles
 ├── commands/        # Custom commands
 └── scripts/         # Repo utilities (test-skill.sh, validate-agents.sh)
@@ -76,6 +82,42 @@ compatibility: opencode
 - `systematic-debugging/test-*.md` - Academic/pressure testing in wrong location
 - `pdf/forms.md`, `pdf/reference.md` - Docs outside references/

+## Canonical Agent Format
+
+Agent definitions live in `agents/<name>/agent.toml` + `agents/<name>/system-prompt.md`.
+This is a **harness-agnostic** format — renderers in m3ta-nixpkgs generate tool-specific configs.
+
+See `agents/SCHEMA.md` for the full schema definition.
+
+### Adding a new agent
+
+1. Create `agents/<name>/agent.toml` with required fields (`name`, `description`) and optional fields (`mode`, `permissions`, etc.)
+2. Create `agents/<name>/system-prompt.md` with the agent's system prompt
+3. Verify: `nix eval --impure --expr 'builtins.fromTOML (builtins.readFile ./agents/<name>/agent.toml)' --json`
+4. Add the agent to renderers by updating the consuming flake inputs
+
+### How renderers work
+
+Renderers live in **m3ta-nixpkgs** (not this repo). They consume `lib.loadAgents` and produce:
+
+| Tool | Output | Path |
+|------|--------|------|
+| OpenCode | `.opencode/agents/*.md` | `~/.config/opencode/agents/` |
+| Claude Code | `.claude/agents/*.md` + `settings.json` | `~/.claude/` |
+| Pi | `AGENTS.md` + `SYSTEM.md` | `~/.pi/agent/` |
+
+### Project-level usage
+
+```nix
+# In project flake.nix
+m3taLib.agents.shellHookForTool {
+  inherit pkgs;
+  agentsInput = inputs.agents;
+  tool = "opencode";
+  modelOverrides = { chiron = "anthropic/claude-sonnet-4"; };
+};
+```
+
 ## Deployment

 **Nix flake pattern**:
@@ -87,16 +129,17 @@ agents = {
 ```

 **Exports:**
+- `lib.loadAgents` — loads all canonical `agents/*/agent.toml` + `system-prompt.md` into an attrset
 - `lib.mkOpencodeSkills` — compose custom + external [skills.sh](https://skills.sh) skills into one directory
+- `lib.agentsJson` — backward-compat bridge producing legacy agents.json shape (temporary, will be removed)
 - `packages.skills-runtime` — composable runtime with all skill dependencies
- `devShells.default` — dev environment for working on skills
+- `devShells.default` — dev environment for working with skills

-**Mapping** (via home-manager):
+**Mapping** (via home-manager + m3ta-nixpkgs renderers):
+- `agents/` → rendered per-tool via `lib.agents.renderForTool` in m3ta-nixpkgs
 - `skills/` → composed via `mkOpencodeSkills` (custom + external merged)
- `context/`, `commands/`, `prompts/` → symlinks
- `agents/agents.json` → embedded into config.json
- Agent changes: require `home-manager switch`
- Other changes: visible immediately
+- `context/`, `commands/` → symlinks
+- Agent changes via file-based agents: visible on next tool restart (no `home-manager switch` needed for prompt changes)

 ### External Skills (skills.sh)

@@ -142,13 +185,130 @@ xdg.configFile."opencode/skills".source =
  };
 ```

+## Migration Guide (for the repo owner)
+
+This section documents how to complete the migration from the legacy `agents.json` + `prompts/*.txt` format to the canonical `agent.toml` + `system-prompt.md` format. The canonical files already exist; what remains is updating the consumer configs and removing legacy files.
+
+### Current state
+
+- ✅ All 6 agents exist in canonical format: `agents/{name}/agent.toml` + `agents/{name}/system-prompt.md`
+- ✅ `lib.loadAgents` loads canonical agents from TOML
+- ✅ `lib.agentsJson` backward-compat bridge produces the old JSON shape from TOML
+- ⏳ Legacy files still present: `agents/agents.json`, `prompts/*.txt`
+- ⏳ Consumer (home-manager) still reads `agents.json` directly via the old `coding.opencode` module
+
+### Step 1: Update home-manager config in your NixOS/HM flake
+
+Change from the old `coding.opencode` agent options to the new `coding.agents.opencode` module:
+
+```nix
+# BEFORE (legacy — agents embedded in config.json):
+coding.opencode = {
+  enable = true;
+  agentsInput = inputs.agents;
+  externalSkills = [ ... ];
+  ohMyOpencodeSettings = { ... };
+  extraSettings = { ... };
+};
+
+# AFTER (new — file-based agents from canonical TOML):
+coding.opencode = {
+  enable = true;  # handles theme, plugins, formatter, oh-my-opencode
+  ohMyOpencodeSettings = { ... };
+  extraSettings = { ... };
+};
+
+coding.agents.opencode = {
+  enable = true;
+  agentsInput = inputs.agents;
+  externalSkills = [ ... ];
+  modelOverrides = {
+    chiron = "zai-coding-plan/glm-5";
+    "chiron-forge" = "zai-coding-plan/glm-5";
+  };
+};
+```
+
+Key changes:
+- `agentsInput` and `externalSkills` move from `coding.opencode` to `coding.agents.opencode`
+- `modelOverrides` is new — per-agent model selection (previously hardcoded in agents.json)
+- Skills, context, commands are now handled by the agents module
+- Agents are deployed as file-based `~/.config/opencode/agents/*.md` instead of embedded in config.json
+
+### Step 2: Run home-manager switch
+
+```bash
+home-manager switch --flake .
+```
+
+Verify that `~/.config/opencode/agents/` contains 6 `.md` files with the correct frontmatter.
+
+### Step 3: Remove legacy files from AGENTS repo
+
+After confirming everything works with the new setup:
+
+```bash
+cd /home/m3tam3re/p/AI/AGENTS
+
+# Remove legacy agent definition
+rm agents/agents.json
+
+# Remove legacy prompt files (now in agents/*/system-prompt.md)
+rm prompts/chiron.txt prompts/chiron-forge.txt prompts/hermes.txt \
+   prompts/athena.txt prompts/apollo.txt prompts/calliope.txt
+rmdir prompts/  # if empty
+
+# Remove backward-compat bridge from flake.nix
+# Delete the lib.agentsJson section from flake.nix
+```
+
+After removing `lib.agentsJson`, update flake.nix to remove the bridge function. The `lib.loadAgents` and `lib.mkOpencodeSkills` exports remain.
+
+### Step 4: Verify
+
+```bash
+# AGENTS repo: all TOML files parse
+cd /home/m3tam3re/p/AI/AGENTS
+for f in agents/*/agent.toml; do
+  nix eval --impure --expr "builtins.fromTOML (builtins.readFile ./$f)" --json > /dev/null && echo "OK: $f"
+done
+nix flake check
+
+# nixpkgs: flake check passes
+cd /home/m3tam3re/p/NIX/nixpkgs
+nix flake check
+
+# Home-manager: agents deployed correctly
+ls ~/.config/opencode/agents/
+```
+
+### Optional: Enable other tool renderers
+
+To also deploy agents for Claude Code or Pi, add to your home-manager config:
+
+```nix
+# Claude Code agents
+coding.agents.claude-code = {
+  enable = true;
+  agentsInput = inputs.agents;
+  modelOverrides = { };
+};
+
+# Pi agents
+coding.agents.pi = {
+  enable = true;
+  agentsInput = inputs.agents;
+};
+```
+
 ## Rules System

-Centralized AI coding rules consumed via `mkOpencodeRules` from m3ta-nixpkgs:
+Centralized AI coding rules consumed via `mkCodingRules` from m3ta-nixpkgs
+(`mkOpencodeRules` still works as backward-compat alias):

 ```nix
 # In project flake.nix
-m3taLib.opencode-rules.mkOpencodeRules {
+m3taLib.coding-rules.mkCodingRules {
  inherit agents;
  languages = [ "python" "typescript" ];
  frameworks = [ "n8n" ];