m3tam3re/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update AGENTS.md to reflect current codebase state

Browse Source
This commit is contained in:
Chiron
2026-04-15 18:45:25 +00:00
committed by Chiron
parent d04d405297
commit a0f4d401df
1 changed files with 33 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
AGENTS.md
View File

@@ -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)