mirror of
https://github.com/ryan4yin/nix-config.git
synced 2026-11-13 12:13:36 +01:00
Ryan Yin
4470b3d014
Move standalone repository docs from the root into docs/ and add a documentation index that links the moved docs and the code-local runbooks. Update Markdown links, source comments, and the root entry points to the new locations. Keep README.md and AGENTS.md at the root as required entry points. Assisted-by: DeepSeek Harness (deepseek-flash)
143 lines
8.7 KiB
Markdown
143 lines
8.7 KiB
Markdown
# Agents
|
|
|
|
Portable agent resources shared across projects: the global baseline rules, the global skills,
|
|
behavioral scenarios, and reference snippets for external tooling.
|
|
|
|
Home Manager links the rules and skills into the agents' config locations. The resource files here
|
|
remain portable Markdown; deployment lives in the Home Manager module.
|
|
|
|
Repo-scoped task procedures for one repository belong elsewhere: put them in that repository's
|
|
`.agents/skills/` (note the leading dot), which agents discover automatically. In a repository, use
|
|
the layers this way:
|
|
|
|
- `AGENTS.md`: always-loaded map and hard safety rules; keep it short.
|
|
- `agents/skills/*/SKILL.md`: custom global procedures reused across repositories.
|
|
- `*.md` / `README.md`: reference and domain runbooks for people, kept next to the code they
|
|
describe.
|
|
- `.agents/skills/*/SKILL.md`: procedures specific to the current repository.
|
|
|
|
Keep one canonical home for each fact; link between layers instead of copying paragraphs.
|
|
|
|
## What this directory contains
|
|
|
|
- `global-rules.md`: global baseline rules for coding agents. It is deliberately not named
|
|
`AGENTS.md`: agents working in this checkout would load it a second time as nested instructions
|
|
for `agents/`.
|
|
- `skills/`: global skills kept in this repository, e.g.
|
|
[`git-delivery`](skills/git-delivery/SKILL.md) for commit messages, PR descriptions, review
|
|
replies, and cleanup after merge; its [README](skills/README.md) records every global skill and
|
|
its source.
|
|
- `evals/global-rules.md`: how to size and run evaluations for changes to the rules or skills, and
|
|
the behavioral scenarios.
|
|
- `install-tooling.md`: install snippets for project-scoped skills and other external agent tooling.
|
|
|
|
The Nix side of the agents — deploying the rules and skills, the agent CLIs, and their environment —
|
|
lives in the Home Manager module [`home/base/tui/agents/`](../home/base/tui/agents/README.md).
|
|
|
|
## Core workflow
|
|
|
|
1. Maintain shared boundaries in `agents/global-rules.md` and task procedures in skills.
|
|
2. Configure permissions directly in the agent runtime; auto-approval is generally used.
|
|
3. Content changes to the rules and to skills in `agents/skills/` reach the next agent session
|
|
through out-of-store links; a running harness may need a reload. Adding or removing a skill, or
|
|
moving a skill flake input, requires a Home Manager switch, run by the user.
|
|
4. Use `install-tooling.md` as a reference when installing project-scoped 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 `global-rules.md`; put concrete incidents, bypass
|
|
attempts, and counterexamples in [behavioral scenarios](evals/global-rules.md). Keep the file
|
|
runtime- and project-neutral: runtime behavior belongs in that runtime's documentation, project
|
|
mechanics in the project's instructions, and a rule belongs here only when it applies across both.
|
|
|
|
- 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.
|
|
|
|
Some rules restate familiar principles as checkable boundaries: Grice's maxims shape Communication
|
|
and Output style, with the maxim of quality as the cite-or-mark-unverified rule under Repository
|
|
work; Orwell's "cut every word you can" shows in the one-line comment rule; and Occam's razor
|
|
becomes the minimal-diff rule. The rules deliberately do not cite these names, even as a summary. A
|
|
name adds no boundary and imports the whole principle with each model's own reading: the maxim of
|
|
relation can suppress reports the rules require (an exposed secret, config that appears unused), and
|
|
Occam's razor can favor the smallest diff over the upstream fix. Amend the concrete rule instead.
|
|
|
|
After changing the rules or a custom skill, size the evaluation to the change as the
|
|
[evaluation guide](evals/global-rules.md#choosing-the-scope) describes, and record the results in
|
|
the PR.
|
|
|
|
## Deployment
|
|
|
|
[`rules.nix`](../home/base/tui/agents/rules.nix) links `global-rules.md` into every supported agent
|
|
config directory as `AGENTS.md`, out-of-store, so edits apply without a rebuild. The per-agent
|
|
target list lives in that module's
|
|
[README](../home/base/tui/agents/README.md#deployed-rule-targets).
|
|
|
|
[`skills.nix`](../home/base/tui/agents/skills.nix) links every directory under `agents/skills/` and
|
|
the skills selected from pinned flake inputs into `~/.agents/skills/<name>`; see the module's
|
|
[global skills](../home/base/tui/agents/README.md#global-skills) section. To add a local skill,
|
|
create `agents/skills/<name>/SKILL.md`; the user activates it with a Home Manager switch. Links
|
|
point at the canonical checkout, so changes in another worktree deploy only after they are merged
|
|
there.
|
|
|
|
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.
|
|
|
|
Permission configuration is not managed by Nix. The repository-root `AGENTS.md` contains guidance
|
|
for this Nix configuration repository only; it is not deployed.
|
|
|
|
Auto-approval controls tool prompting. The global rules still define task authorization, safety, and
|
|
secret handling.
|
|
|
|
## TODO
|
|
|
|
Remaining work on the agent context, ordered by expected payoff. The goal is fewer tokens per
|
|
session and closer adherence to these rules. Done so far: the rules source rename, the move of
|
|
global skills to flake inputs (dropping superpowers, `find-skills`, and `caveman`), the i-have-adhd
|
|
always-on block, `find-docs` rewritten onto the nixpkgs `ctx7` CLI, the scenario and skill tables
|
|
converted to lists, and the duplication cleanup in the repo skills. Historical
|
|
[behavioral runs](evals/global-rules.md) cover tool-execution compression, whole-file compression,
|
|
and boundaries for readiness waits, process inspection, and shell command sequencing on
|
|
`gpt-6-luna`, the local model, and `gpt-6.1-sol`. A later full-scenario-set paper pass ran on
|
|
`DeepSeek-V41-Flash`, with focused verification on that model and `gpt-6-luna`. The added boundaries
|
|
cost more than the compression saved; revision-specific sizes, results, and coverage limits are
|
|
recorded in [#428](https://github.com/ryan4yin/nix-config/pull/428).
|
|
|
|
- **Fold `mattpocock/skills` `pr` into `git-delivery`**: before/after evidence, one-way or two-way
|
|
door, and blast radius for PR bodies.
|
|
- **Write a `testing-strategy` skill**: E2E of real workflows first, unit tests for logic and edge
|
|
cases E2E cannot reach.
|
|
- **Merge `ponytail-review` into the shipped `review-comments-and-docs` skill** (its doc-pruning
|
|
half came from `MidAutumnMoon/TaysiTsuki` `home/agents/skills/prune-comments-and-docs`). Worth
|
|
borrowing from `garrytan/gstack` `review/checklist.md`: a critical pass before an informational
|
|
one, reading consumers outside the diff for a new enum value or loosened validator, a do-not-flag
|
|
list, and "zero findings is valid". Keep review report-only.
|
|
- **Adapt `wayfinder` in the fork** so its map and tickets default to local Markdown and research
|
|
stays local, instead of GitHub issues and pushed `research/` branches.
|
|
- **Adapt `domain-modeling` in the fork** to record decisions in the repository's existing documents
|
|
(here `AGENTS.md`, `docs/WORKAROUNDS.md`, `docs/SECURITY.md`, READMEs) and create `GLOSSARY.md` or
|
|
ADRs only where none exist.
|
|
- **Borrow small gstack ideas into the rules**: completion statuses (done, done with concerns,
|
|
blocked, needs context); never call a failure pre-existing without running the same check on the
|
|
base branch; a subagent with no one to ask takes the recommended option but never a destructive or
|
|
publishing one.
|
|
- **Use progressive disclosure for large repo skills.** `nix-config-umu-game` (~3.5k tokens) keeps
|
|
its troubleshooting inline; move it to a reference file. Lower priority: `nix-config-secrets` §7
|
|
and `nixpkgs-review` §3.
|
|
- **Budget the always-loaded context in CI**: cap skill description length and rules size, as gstack
|
|
does for its catalog.
|
|
- **MCP servers** are still configured by hand per harness; they could come from the same Nix
|
|
source, though config formats differ per client. Reference: `mirkolenz/infra`
|
|
`options/home-manager/agents.nix`.
|
|
|
|
## 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.
|