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
+Harness-agnostic agent management. Reads canonical `agent.toml` +
-flake input and renders tool-specific configs.
+`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 |
+| `renderForPi { pkgs, canonical, modelOverrides, primaryAgent }` | Render to Pi AGENTS.md + SYSTEM.md + agents/ |
-| `renderForTool { pkgs, agentsInput, tool, modelOverrides }` | Dispatch to correct renderer |
+| `renderForTool { pkgs, agentsInput, tool, modelOverrides }` | Dispatch to correct renderer by tool name |
-| `shellHookForTool { pkgs, agentsInput, tool, modelOverrides }` | Generate devShell shellHook |
+| `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.
+**td** is an optional task-tracking package. See `docs/packages/td.md` for details.
-Run `td usage --new-session` at conversation start to see current work.
-Use `td usage -q` for subsequent reads.
 
-**Quick reference:**
+## Agent System Architecture
 
-- `td usage --new-session` - Start new session and view tasks
+The agent system uses harness-agnostic canonical definitions stored as
-- `td usage -q` - Quick view of current tasks (subsequent reads)
+`agent.toml` + `system-prompt.md` in the AGENTS repository. Renderers in
-- `td version` - Check version
+`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
+### Key files in this repo
-canonical `agent.toml` + `system-prompt.md` in the AGENTS repo. Renderers in
-`lib/agents.nix` generate tool-specific configs.
 
-### What changed in this repo
+- `lib/agents.nix` — renderers, dispatcher, shellHook generator
-
+- `lib/coding-rules.nix` — coding rules injection (`mkCodingRules`)
-- **`lib/agents.nix`**: New — 3 renderers (OpenCode, Claude Code, Pi) + dispatcher + shellHook
+- `modules/home-manager/coding/agents/` — per-tool HM sub-modules (opencode, claude-code, pi)
-- **`lib/coding-rules.nix`**: Renamed from `opencode-rules.nix`, `mkCodingRules` replaces `mkOpencodeRules`
+- `modules/home-manager/coding/opencode.nix` — OpenCode HM module (slimmed, agents handled separately)
-- **`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`