From 6a5b431e39c3a77652dc22e692925027cb69b965 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Thu, 2 Jul 2026 00:18:10 +0300 Subject: docs: clarify agent instruction scope --- AGENTS.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 57 insertions(+), 3 deletions(-) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index 4f7d2a99..4edfb3ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,28 @@ Terminal based agent runtime for coding agents. -## Principles +## Scope and Audience + +These instructions are layered. + +- Unless a section explicitly says it is maintainer-only, local-machine-only, or + external-contributor-only, treat it as universal project guidance. +- Universal project rules apply to every agent working on Herdr, including forks. +- Maintainer workflow applies only when the acting GitHub account is + `ogulcancelik` or Can explicitly says this is maintainer work. If the account + is not `ogulcancelik`, skip maintainer workflow and follow the external + contributor guardrail instead. +- Local Can machine workflow applies only on Can's own workstation or Windows + VM setup, for example when `/home/can/Projects/herdr`, `HERDR_ENV=1`, or the + `windows-wirt` SSH alias exists. If those facts are not true, skip local + machine workflow. +- External contributor guardrail applies whenever the acting GitHub account is + not `ogulcancelik`, the work is happening in a fork, or the account cannot be + determined. + +## Universal Project Rules + +### Principles - **State is separated from runtime.** `AppState` is pure data, testable without PTYs or async. `PaneState` is separate from `PaneRuntime`. Workspace logic doesn't need real terminals. - **Render is pure.** `compute_view()` handles geometry and mutations. `render()` takes `&AppState` and only draws. Never mutate state during render. @@ -12,7 +33,7 @@ Terminal based agent runtime for coding agents. - **Screen detection is evidence-based.** When changing `src/detect/manifests/`, first capture the relevant bottom-buffer state with `herdr agent read --source detection --format text` and, when styling or alternate screen behavior matters, `--format ansi`. Decide which visible controls are invariant, which are alternatives, and encode them as explicit AND/OR gates. Do not match whole-pane incidental text, and do not use the user-visible viewport for agent status because users can scroll it. - **UI patterns should be reused.** Herdr is a mouse-first TUI. New dialogs, onboarding, settings, and post-update flows should follow the existing UI/UX language and interaction patterns instead of inventing one-off screens. Prefer reusing existing modal/screen structure, affordances, and close actions so the app feels consistent. -## Runtime/client boundary guardrail +### Runtime/client boundary guardrail Herdr is migrating toward a server-owned runtime protocol with the TUI as one client. New work should not deepen the current server/TUI coupling. @@ -29,7 +50,13 @@ Examples: - Sidebar layout, token placement, colors, selection, modals, mouse/viewport state: TUI/client. - Workspace/tab/pane remain shared session organization for now, but avoid making them mandatory identity for unrelated runtime features. -## Multi-agent isolation +## Maintainer Workflow + +This section applies only when the acting GitHub account is `ogulcancelik` or +Can explicitly says this is maintainer work. If the acting account is not +`ogulcancelik`, skip this section and follow the external contributor guardrail. + +### Multi-agent isolation Read-only investigation can happen in the shared checkout. @@ -77,6 +104,29 @@ server: env -u HERDR_SOCKET_PATH -u HERDR_CLIENT_SOCKET_PATH cargo run -- ``` +## Local Can Machine Workflow + +This section applies only on Can's workstation or Windows VM setup. If the +acting GitHub account is not `ogulcancelik`, skip this section and follow the +external contributor guardrail. + +### Windows VM validation + +The Windows VM is for final/manual Windows validation, not normal agent work. + +Use the single reusable checkout at `C:\work\repo`. Do not create additional +persistent Herdr clones or worktrees on the VM. The Windows account is already +named `herdr`, so avoid paths like `C:\Users\herdr\herdr`. + +Before validating a fix on Windows, sync or apply the Linux worktree changes +into `C:\work\repo`, then run the needed Windows build or test commands there. +Reuse the shared Rust caches under `C:\Users\herdr\.cargo` and +`C:\Users\herdr\.rustup`. Do not use WSL on the VM. + +After validation, leave `C:\work\repo` clean. Remove temporary files and delete +`C:\work\repo\target` when disk space is tight, but keep the shared Cargo and +Rustup caches. + ## Agent Detection Updates Agent detection changes should use the manifest hot-reload loop. Can drives the real agent UI into the target state, then you read the pane with `herdr agent read --source detection --format text` and inspect matching with `herdr agent explain --json`. Update the bundled manifest in `src/detect/manifests/.toml`, copy that manifest to the local override path at `~/.config/herdr/agent-detection/.toml`, then run `herdr server reload-agent-manifests`. Can verifies the live pane state, and once the rule is correct, remove the local override so the committed bundled manifest remains the source of truth. @@ -131,6 +181,10 @@ Do not use GitHub closing keywords like `fixes #`, `closes #