mirror of
https://github.com/ryan4yin/nix-config.git
synced 2026-11-13 12:13:46 +01:00
ryan4yin | 二花
373b233f32
* feat(agents): use the shell's own dialect; allow 5 s retry backoff Assisted-by: DeepSeek Harness (deepseek-flash) * feat(dsh): make Nushell the only shell Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): wait for CI in the background Pushes to a PR often start multi-minute CI runs, and an agent that holds the turn open on a foreground watch reports nothing until it ends. Require the pushed head and running checks to be reported first, the watch to run in the background, and the result to be collected after independent work or after ending the turn. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): keep the shell-handoff rule platform-neutral The global rules carry no Windows assumptions: drop the cmd, pwsh, and wsl handoff examples and keep the POSIX forms plus the dsh refusal. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(dsh): keep the shell-swap docs POSIX-only This repository manages Linux and Darwin hosts, not Windows: drop the Windows handoff examples and terminal-backend wording from dsh.md. The home patch also disabled pwsh-sandbox redundantly because dsh-base already disables that row on POSIX; keep only the active bash-sandbox disable and verify the composed rows with --dump-config. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): keep the global rules runtime-neutral Global rules are loaded by every agent CLI, so they must not describe one runtime's behavior. Drop the dsh-specific sentence and wording while keeping the expectation to prefer Nushell structured pipelines and Python. Runtime behavior stays documented in home/base/tui/agents/dsh.md. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): default shell work to Nushell Keep the Nushell preference explicit in the runtime-neutral global rules, and keep runtime behavior in runtime docs. Bash stays a narrow fallback for tasks Nushell cannot do. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): tighten global-rule scope and CI guidance Keep global rules runtime- and project-neutral, and state that boundary in the file. Remove the duplicated CI turn-steering text in favour of the Communication rule, resolve the watch run before watching instead of relying on gh pr checks --watch alone, name the working-directory parameter generically, and distinguish a bounded retry backoff from a fixed completion wait. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): never estimate a CI run's duration A CI run has no predictable length, so do not turn "it looks short" into a reason to wait. The rule is unconditional: report the head and started checks, start a background watch, and end the turn; collect the result on completion. The eval scenario now uses an unknown duration. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): move maintenance guidance to the README The runtime/project boundary is guidance for editing the rules, not a rule agents need loaded every session. The README's Maintaining global rules section already owns that audience; the loaded rules keep only behavior. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(dsh): render the home patch from a YAML template Move the home-layer cordis patch into dsh-cordis.patch.yml, substitute the bundle and Nushell store paths with replaceVars, and link the rendered file through home.file.source. This module is the only writer of ~/.dsh/cordis.patch.yml, the current host has no such file, and the profile patch is a separate layer. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(dsh): install the shell plugin through NUR withPlugins Replace the local runCommand bundle, peer symlink, and home-layer YAML file with the plugin package and dsh.withPlugins from ryan4yin/nur-packages#43. The package wrapper adds a generated --patch overlay after the profile layer, so dsh no longer writes or manages ~/.dsh/cordis.patch.yml. The NUR input is temporarily pinned to the PR branch and its commit; point it back at main once the NUR PR merges. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(nix): expose the NUR package set as nurPkgs Pass one per-system NUR package set through specialArgs instead of repeating nur-ryan4yin.packages.${pkgs.stdenv.hostPlatform.system} at each call site. The agents, rime, and idols-ruby modules now use the short binding. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(nix): use nurPkgs in package overlays The overlays receive specialArgs too, so they can use the per-system NUR package set instead of rebuilding the long input path from prev. This leaves only the definition in outputs/default.nix. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(nix): name the per-system NUR set myNurPkgs Leave room for consuming another NUR repository later, and match the existing mylib/myvars naming. Assisted-by: DeepSeek Harness (deepseek-flash) * chore(dsh): consume the merged NUR package set nur-ryan4yin now points at main after ryan4yin/nur-packages#43 was squash merged; the lock records the merge commit. No branch ref remains. Assisted-by: DeepSeek Harness (deepseek-flash) * fix(dsh): pass the web profile explicitly The withPlugins launcher prepends --patch, which historically prevented dsh from auto-expanding "dsh web" into "--profile web". Pass the profile explicitly in the Just recipe and the verification commands so they work with both plain dsh and the wrapper. Assisted-by: DeepSeek Harness (deepseek-flash) * chore(dsh): pick up the wrapped-profile fix Update nur-ryan4yin to the squash merge that keeps an implicit profile name first, so "dsh web" and "just dsh-web" work through the wrapper again. Assisted-by: DeepSeek Harness (deepseek-flash) * chore(dsh): pick up the plugin peer-link fix Update nur-ryan4yin to the squash merge that links the dsh peer tree at node_modules/@deepseek-ai instead of nesting it one level deeper. This is the import failure that stopped nushell-executor from activating after deploy. Assisted-by: DeepSeek Harness (deepseek-flash)
135 lines
8.0 KiB
Markdown
135 lines
8.0 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.
|
|
|
|
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`, `WORKAROUNDS.md`, `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.
|