nix-config/agents/README.md

Agents

Portable agent resources shared across projects: the global baseline rules, behavioral scenarios for those rules, and reference snippets for external tooling.

Home Manager links the rules from here into each agent's config location, so agents/ itself stays plain Markdown with no Nix dependency.

It is shared across projects. Repo-scoped task procedures for one repository belong elsewhere: put them in that repository's .agents/skills/ (note the leading dot), which OpenCode and compatible tools discover automatically. In a repository, use the layers this way:

• AGENTS.md: always-loaded map and hard safety rules; keep it short.
• *.md / README.md: reference and domain runbooks for people, kept next to the code they describe.
• .agents/skills/*/SKILL.md: on-demand procedures, verification steps, and agent-only constraints.

Keep one canonical home for each fact; link between layers instead of copying paragraphs.

What this directory contains

• AGENTS.md: global baseline rules for coding agents.
• evals/global-rules.md: behavioral scenarios for validating changes to the global rules.
• install-tooling.md: curated install snippets for external agent tooling (npx skills, npx ctx7, tuios integration).

The Nix side of the agents — deploying these rules, the agent CLIs, and their environment — lives in the Home Manager module home/base/tui/agents/.

Core workflow

1. Maintain shared rules in agents/AGENTS.md.
2. Configure permissions directly in the agent runtime; auto-approval is generally used.
3. Edit the rules; Home Manager links them out-of-store, so the change reaches the next agent session without a rebuild. Run a Home Manager switch only when the deployed target set changes.
4. Use install-tooling.md as a reference when installing external agent tooling.

Maintaining global rules

Before adding or expanding a rule, read the current rules and identify the decision boundary that needs to change. Keep reusable boundaries in AGENTS.md; put concrete incidents, bypass attempts, and counterexamples in behavioral scenarios.

• If an existing rule already covers the incident, add or refine a scenario instead of another rule.
• If the boundary is missing or ambiguous, amend the relevant rule rather than append a special case.
• Keep authorization, trust, and secret-handling boundaries always loaded. Put command examples and task-specific procedures in reference docs or skills.
• Review the net growth and remove repetition. Brevity must preserve the boundary; verify both the prohibited action and the authorized action still behave as intended.

Run the scenarios required by the evaluation guide after rule changes, and record their results.

Deployment

home/base/tui/agents/rules.nix links AGENTS.md into every supported agent config directory as an out-of-store symlink, so edits apply without a rebuild. The per-agent target list lives in that module's README.

The module is imported through home/base/tui, so it covers the hosts that import home/linux/gui.nix or the macOS home/darwin stack; core-only servers are unchanged.

Only AGENTS.md is deployed to the agents. Permission configuration and skills are not installed by Nix; the CLIs themselves are, via the same module's packages.nix. The repository-root AGENTS.md contains guidance for this Nix configuration repository. It is not the global rules source and is not deployed.

Auto-approval controls tool prompting. The global rules still define task authorization, safety, and secret handling.

About install-tooling.md

Use it as a snippet library:

• review the commands
• select what you need
• run selected commands manually

TODO

Ideas worth adopting once a concrete need appears; nothing here is implemented yet.

• Unified skill and MCP management. Skills are installed with npx skills and MCP servers are configured by hand per harness; a single source that renders to each agent would be nicer, though MCP config formats differ per client. Reference: mirkolenz/infra options/home-manager/agents.nix (custom programs.agents, follows the Agent Skills spec).

Conventions

• Keep files portable and reviewable.
• Keep secrets and machine-specific credentials out of this directory.
• Keep guidance generic enough to reuse across multiple agent environments.