From a0f4d401df7800f121b0d6e35a461b711d10fa16 Mon Sep 17 00:00:00 2001 From: Chiron Date: Wed, 15 Apr 2026 18:45:25 +0000 Subject: [PATCH] docs: update AGENTS.md to reflect current codebase state --- AGENTS.md | 74 +++++++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 41 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1ed3682..9738bf0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,5 @@ # m3ta-nixpkgs Knowledge Base -## MANDATORY: Use td for Task Management - -You must run td usage --new-session at conversation start (or after /clear) to see current work. -Use td usage -q for subsequent reads. - **Generated:** 2026-02-14 **Commit:** dc2f3b6 **Branch:** master @@ -114,8 +109,8 @@ Port management utilities. See [Port Management](#port-management). ### `lib.agents` -Harness-agnostic agent management. Reads canonical `agent.toml` from the AGENTS -flake input and renders tool-specific configs. +Harness-agnostic agent management. Reads canonical `agent.toml` + +`system-prompt.md` from the AGENTS flake input and renders tool-specific configs. **Functions:** @@ -124,17 +119,18 @@ flake input and renders tool-specific configs. | `loadCanonical { agentsInput }` | Load canonical agents from AGENTS flake | | `renderForOpencode { pkgs, canonical, modelOverrides }` | Render to OpenCode file-based agents | | `renderForClaudeCode { pkgs, canonical, modelOverrides }` | Render to Claude Code agents + settings.json | -| `renderForPi { pkgs, canonical }` | Render to Pi AGENTS.md + SYSTEM.md | -| `renderForTool { pkgs, agentsInput, tool, modelOverrides }` | Dispatch to correct renderer | -| `shellHookForTool { pkgs, agentsInput, tool, modelOverrides }` | Generate devShell shellHook | +| `renderForPi { pkgs, canonical, modelOverrides, primaryAgent }` | Render to Pi AGENTS.md + SYSTEM.md + agents/ | +| `renderForTool { pkgs, agentsInput, tool, modelOverrides }` | Dispatch to correct renderer by tool name | +| `shellHookForTool { pkgs, agentsInput, tool, modelOverrides }` | Generate devShell shellHook (symlinks rendered files) | ### `lib.coding-rules` -Coding rules injection (renamed from `lib.opencode-rules`). The old name still works. +Coding rules injection. Generates `coding-rules.json` + symlinks rules from +the AGENTS repository. The old `lib.opencode-rules` name still works. | Function | Purpose | |----------|--------| -| `mkCodingRules { agents, languages, concerns, frameworks }` | Generate rules config + shellHook | +| `mkCodingRules { agents, languages, concerns, frameworks, rulesDir }` | Generate rules config + shellHook. `rulesDir` defaults to `.opencode-rules` | | `mkOpencodeRules` | Backward-compat alias for `mkCodingRules` | ## PORT MANAGEMENT @@ -188,38 +184,34 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore` ## Task Management -This project uses **td** for tracking tasks across AI coding sessions. -Run `td usage --new-session` at conversation start to see current work. -Use `td usage -q` for subsequent reads. +**td** is an optional task-tracking package. See `docs/packages/td.md` for details. -**Quick reference:** +## Agent System Architecture -- `td usage --new-session` - Start new session and view tasks -- `td usage -q` - Quick view of current tasks (subsequent reads) -- `td version` - Check version +The agent system uses harness-agnostic canonical definitions stored as +`agent.toml` + `system-prompt.md` in the AGENTS repository. Renderers in +`lib/agents.nix` transform these into tool-specific configs at build time. -For full workflow details, see the [td documentation](./docs/packages/td.md). +### How it works -## MIGRATION: Agent System (OpenCode → Canonical TOML) +1. **Canonical definitions** live in the AGENTS repo as `agent.toml` files + (one per agent) with shared fields: name, description, mode, systemPrompt, + permissions, skills. +2. **`loadCanonical`** reads all agent definitions from the AGENTS flake input. +3. **Renderers** produce tool-specific output: + - `renderForOpencode` → `*.md` files with YAML frontmatter for `.opencode/agents/` + - `renderForClaudeCode` → `.claude/agents/*.md` + `.claude/settings.json` with permission rules + - `renderForPi` → `AGENTS.md`, `SYSTEM.md`, `agents/*.md` for Pi's subagent format +4. **`renderForTool`** dispatches to the correct renderer by tool name + (`"opencode"`, `"claude-code"`, or `"pi"`). +5. **`shellHookForTool`** generates a devShell shellHook that symlinks rendered + files into the project directory. +6. **HM modules** in `modules/home-manager/coding/agents/` handle per-tool + Home Manager integration. -The agent system was migrated from embedded `agents.json` to harness-agnostic -canonical `agent.toml` + `system-prompt.md` in the AGENTS repo. Renderers in -`lib/agents.nix` generate tool-specific configs. +### Key files in this repo -### What changed in this repo - -- **`lib/agents.nix`**: New — 3 renderers (OpenCode, Claude Code, Pi) + dispatcher + shellHook -- **`lib/coding-rules.nix`**: Renamed from `opencode-rules.nix`, `mkCodingRules` replaces `mkOpencodeRules` -- **`modules/home-manager/coding/agents/`**: New — per-tool HM sub-modules -- **`modules/home-manager/coding/opencode.nix`**: Slimmed — no longer handles agents/skills/context -- **`flake.nix`**: Exports new `agents` HM module - -### What the user must do - -See `modules/home-manager/AGENTS.md` for the full migration guide. Summary: - -1. Move `agentsInput`/`externalSkills` from `coding.opencode` to `coding.agents.opencode` -2. Add `modelOverrides` with previously hardcoded model strings -3. Run `home-manager switch` -4. Remove legacy `agents.json` + `prompts/*.txt` from AGENTS repo -5. Remove `lib.agentsJson` backward-compat bridge from AGENTS `flake.nix` +- `lib/agents.nix` — renderers, dispatcher, shellHook generator +- `lib/coding-rules.nix` — coding rules injection (`mkCodingRules`) +- `modules/home-manager/coding/agents/` — per-tool HM sub-modules (opencode, claude-code, pi) +- `modules/home-manager/coding/opencode.nix` — OpenCode HM module (slimmed, agents handled separately)