mirror of
https://github.com/moons-14/dotfiles.git
synced 2026-10-05 23:58:11 +09:00
87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
# Coding-agent workflow
|
|
|
|
This repository exposes deterministic validation and narrowly scoped research
|
|
tools for Codex, OpenCode, and editor agents. Live system activation is outside
|
|
this workflow.
|
|
|
|
## Validation commands
|
|
|
|
Use task-owned paths during the edit loop:
|
|
|
|
```console
|
|
nix run .#check -- plan --paths modules/applications/example/home.nix --json
|
|
nix run .#check -- fast --paths modules/applications/example/home.nix
|
|
nix run .#check -- eval --paths modules/applications/example/home.nix
|
|
nix run .#check -- build --paths modules/applications/example/home.nix
|
|
nix run .#check -- all --paths modules/applications/example/home.nix
|
|
```
|
|
|
|
For a committed pull-request range, replace `--paths ...` with
|
|
`--base <base-sha>`. `full` is reserved for CI, scheduled maintenance, or an
|
|
explicit repository-wide audit:
|
|
|
|
```console
|
|
nix run .#check -- full
|
|
```
|
|
|
|
The stages have distinct meanings:
|
|
|
|
- `plan` maps changed paths to Registry units, reverse `meta.includes`
|
|
dependencies, real hosts, and compatible build systems.
|
|
- `fast` parses changed Nix files, validates JSON, TOML, Python, and Agent Skill
|
|
frontmatter, checks whitespace, and runs configured hooks only for the
|
|
selected files.
|
|
- `eval` instantiates affected NixOS and nix-darwin configurations. Flake-wide,
|
|
validation-tool, shell, overlay, and test changes additionally evaluate every
|
|
flake system.
|
|
- `build` realizes affected configurations supported by the current platform
|
|
with no result link. Incompatible targets remain evaluation-only until a
|
|
matching runner handles them.
|
|
- `all` performs task-scoped file checks, all-system evaluation, and compatible
|
|
targeted builds.
|
|
- `full` runs all-file hooks, all-system evaluation, and every check for the
|
|
current platform through `nix-fast-build`.
|
|
|
|
The validation app constructs a filtered temporary `path:` flake from the
|
|
committed `HEAD` tree and overlays only task-owned changed paths. This isolates
|
|
unrelated worktree changes, makes new untracked Registry fragments visible to
|
|
Nix without staging them, and avoids copying ignored state such as `.direnv`.
|
|
|
|
None of these commands runs `nh os switch`, `nixos-rebuild switch`,
|
|
`darwin-rebuild switch`, `home-manager switch`, or another activation command.
|
|
The user performs activation separately.
|
|
|
|
## Agent Skills
|
|
|
|
Read `AGENTS.md` first. Use the repository skills as follows:
|
|
|
|
- `validate-nix-change` controls validation scope and evidence.
|
|
- `debug-nix-failure` classifies parse, evaluation, build, test, activation-log,
|
|
and runtime failures before proposing a correction.
|
|
- `test-nixos-service` adds a `pkgs.testers.runNixOSTest` check when a build
|
|
cannot prove service behavior.
|
|
- `update-flake-input` limits lock-file updates and validates them without
|
|
activating a host.
|
|
- `add-application-or-service` preserves Registry ownership and delegates
|
|
validation to `validate-nix-change`.
|
|
|
|
## MCP and language-server setup
|
|
|
|
The development workload installs `mcp-nixos`, `nixd`, `nix-fast-build`, and
|
|
`nix-tree`.
|
|
|
|
Project-local Codex and OpenCode configuration exposes:
|
|
|
|
- `mcp-nixos` for current NixOS, Home Manager, nix-darwin, package, and Nix
|
|
documentation queries;
|
|
- GitHub's remote MCP endpoint for Codex and OpenCode in read-only mode,
|
|
restricted to repository, pull-request, and Actions toolsets.
|
|
|
|
Set `GITHUB_PERSONAL_ACCESS_TOKEN` in the launching environment when GitHub MCP
|
|
access is needed. Do not commit the token or put it in a Nix expression because
|
|
that would expose it through source control or the Nix store.
|
|
|
|
The workspace VS Code settings use `nixd` and expose option sets for the
|
|
`galleria` NixOS configuration, its integrated Home Manager configuration, the
|
|
`m2` nix-darwin configuration, and its integrated Home Manager configuration.
|