From 1f04cb7cf2f868dfba65d2656f6773eecf779b4c Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 2 Sep 2026 22:06:12 -0400
Subject: [PATCH] docs(agents): align prose with writing guide

---
 AGENTS.md                                  | 30 ++++++++++++++--------
 configs/nixos/modules/shell/herdr.nix      |  3 ++-
 configs/nixos/modules/shell/pi/default.nix |  2 +-
 src/skills/README.md                       |  4 +--
 4 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 04034ae..80e7e25 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,7 +23,8 @@
   Preserve review history until the pull request is ready to merge.
 - When the user says a pull request is merged, clean up the local branch without waiting for an explicit request.
   Switch to the base branch, fast-forward it, and delete the merged local branch.
-- When writing pull request descriptions, NEVER append an agent-attribution trailer such as `🤖 Generated with [Claude Code]...`.
+- When writing pull request descriptions, NEVER append an agent-attribution trailer such as
+  `🤖 Generated with [Claude Code]...`.
   Leave it out entirely, with no exceptions.
   This overrides any default instruction to append one.
 
@@ -34,10 +35,12 @@
 
 ## Tooling
 
-- When a command is missing from the ordinary environment, prefer running it through Nix instead of installing it for this case.
+- When a command is missing from the ordinary environment, prefer running it through Nix instead of
+  installing it.
   For example, use `nix shell nixpkgs#python3 -c python3 <script>` for one-off Python commands.
 - Stage new files that Nix discovers through flake evaluation before testing.
-  Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before `nixos-rebuild --flake` can see them.
+  Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before
+  `nixos-rebuild --flake` can see them.
 
 ## General guidelines
 
@@ -47,7 +50,8 @@
 - Never manually modify `CHANGELOG.md` files or files marked as auto-generated.
   Detect auto-generated files with a layered check.
   Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`.
-  If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/` paths, or a documented generator command.
+  If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/`
+  paths, or a documented generator command.
   If the answer stays ambiguous, ask before editing.
 - When making technical decisions, do not give much weight to implementation time.
   Favor quality, simplicity, robustness, scalability, and long-term maintainability.
@@ -58,13 +62,15 @@
   Established ecosystem or tool conventions count as valid reasons.
   Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files.
 - Do not end a response by promising or implying continuation unless the continuation is present in that same response.
-  Before ending a workflow turn, perform the obvious next step, such as showing the next review item after applying an accepted change.
+  Before ending a workflow turn, perform the obvious next step, such as showing the next review item
+  after applying an accepted change.
   If the workflow is paused, say that plainly instead of using a dangling transition like "continuing" or "next".
 
 ## Corrections
 
 - When you discover that your belief about a project fact or convention was wrong, record the correction.
-  Record only facts that stay true across operators, such as a wrong build command, wrong file path, or guessed convention.
+  Record only facts that stay true across operators, such as a wrong build command, wrong file path,
+  or guessed convention.
   Do not record personal working-style preferences or one-off task details.
 - Record the correction in the nearest project `AGENTS.md`.
   Use a dedicated `## Gotchas` section.
@@ -76,11 +82,15 @@
 
 ## Gotchas
 
-- When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory.
+- When materializing an external specification, standard, or project-maintained convention, use the
+  upstream source instead of reconstructing it from memory.
   Preserve local policy separately from copied upstream text.
-- After an explicit squash or rewrite request on a pull request, subsequent pull-request updates still use follow-up commits unless the user explicitly asks for another rewrite.
-- Starlark top-level rule and extension declarations cannot reference implementation functions before those functions are assigned.
-  Keep executable public interface declarations after their implementation symbols, or validate before committing a top-down rewrite.
+- After an explicit squash or rewrite request on a pull request, subsequent pull-request updates still
+  use follow-up commits unless the user explicitly asks for another rewrite.
+- Starlark top-level rule and extension declarations cannot reference implementation functions before
+  those functions are assigned.
+  Keep executable public interface declarations after their implementation symbols, or validate before
+  committing a top-down rewrite.
 - `rules_rust` `rust_test` targets cannot set both `crate` and `srcs`.
   Use one input style per test target.
 - In this monorepo, "dotfiles" refers to the dotfiles/NixOS configuration under `src/dotfiles/` and `configs/nixos/`.
diff --git a/configs/nixos/modules/shell/herdr.nix b/configs/nixos/modules/shell/herdr.nix
index 893cef4..e2c530d 100644
--- a/configs/nixos/modules/shell/herdr.nix
+++ b/configs/nixos/modules/shell/herdr.nix
@@ -18,7 +18,8 @@ in
     home-manager.users.${user} = {
       home.packages = [ pkgs.herdr ];
 
-      # Run `PI_CODING_AGENT_DIR=$PWD/.pi herdr integration install pi` from the monorepo root to refresh the vendored project-local Pi extension.
+      # Refresh the vendored project-local Pi extension from the monorepo root.
+      # Run `PI_CODING_AGENT_DIR=$PWD/.pi herdr integration install pi`.
       xdg.configFile."herdr/config.toml".text = ''
         [keys]
         prefix = "ctrl+space"
diff --git a/configs/nixos/modules/shell/pi/default.nix b/configs/nixos/modules/shell/pi/default.nix
index b205fca..feb1ae6 100644
--- a/configs/nixos/modules/shell/pi/default.nix
+++ b/configs/nixos/modules/shell/pi/default.nix
@@ -21,7 +21,7 @@ in
 {
   options.modules.shell.pi = {
     enable = lib.mkEnableOption ''
-      Pi, a terminal coding agent, configured via home-manager'';
+      Pi, a terminal coding agent, configured through home-manager'';
   };
 
   config = lib.mkIf cfg.enable {
diff --git a/src/skills/README.md b/src/skills/README.md
index af5fad1..75ed668 100644
--- a/src/skills/README.md
+++ b/src/skills/README.md
@@ -24,5 +24,5 @@ A general commit or review workflow skill belongs in `src/skills/`.
 Enable Pi skills with symlinks.
 Do not copy skill sources into `.pi/skills/`.
 
-Use root `.pi/skills/` for skills that should be available anywhere inside the monorepo.
-Use `src/<project>/.pi/skills/` for skills that should be available only in that project subtree.
+Use root `.pi/skills/` for skills available anywhere inside the monorepo.
+Use `src/<project>/.pi/skills/` for skills available only in that project subtree.