From b9ebd238f80ccbcd2079d79f0e22287489db4272 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Sat, 25 Jul 2026 20:57:34 +0300 Subject: docs: define maintainer and agent contribution workflows --- AGENTS.md | 48 ++++++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 18 deletions(-) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index 48024902..62ca7033 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,17 +9,19 @@ 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 +- Maintainer accounts are listed in `.github/MAINTAINERS`. Treat the acting + account as a verified maintainer only when its username is listed there, the + configured remote is the canonical `ogulcancelik/herdr` repository, and the + authenticated account has write access to that repository. If any condition + cannot be verified, 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. + not a verified maintainer, the work is happening in a fork, or the account + cannot be determined. ## Universal Project Rules @@ -52,9 +54,9 @@ Examples: ## 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. +This section applies only to verified maintainers as defined under Scope and +Audience. Everyone else must skip this section and follow the external +contributor guardrail. ### Multi-agent isolation @@ -72,13 +74,17 @@ Do all code edits, tests, and validation inside the task worktree. Commit on the task branch in that worktree. -When the change is ready, fast-forward the shared checkout at `../herdr` to the task branch commit, then push `origin/master` from `../herdr`. Do not treat the task branch as the final landing branch. +For substantive feature and bug-fix work, default to opening a pull request instead of pushing `master` directly. Small, low-risk changes and documentation-only updates can use a lighter workflow when Can prefers it. + +After opening or updating a pull request, monitor all checks to completion with `gh pr checks --watch` or an equivalent command. Treat Greptile and CodeRabbit as part of CI: wait for both to review the latest pushed commit, not only for the build and test jobs to pass. Evaluate every actionable finding. Fix findings you agree with and reply with the fix; reply inline with a concise technical reason when you disagree. After any fix, wait for CI and both review bots again on the new head. + +When the current pull request head is green and both bot reviews are complete, report that it is ready and stop. Never merge a pull request; Can performs the final merge. If the current session is already inside an isolated task worktree, keep using it. Do not create nested worktrees. Before committing, propose the commit message and get alignment. -After the change is integrated, remove the task worktree and delete the task branch locally and remotely. +After Can confirms the change is integrated, update the shared checkout, remove the task worktree, and delete the task branch locally and remotely. ## Testing @@ -106,9 +112,10 @@ 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. +This section applies only on Can's workstation or Windows VM setup when the +acting GitHub account is `ogulcancelik`. Other verified maintainers skip this +local-machine section but continue following maintainer workflow. Everyone else +follows the external contributor guardrail. ### Windows VM validation @@ -134,7 +141,7 @@ manual testing, reset `C:\work\repo` back to a clean checkout before finishing. ## 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. +Agent detection changes should use the manifest hot-reload loop. Use the project-local `herdr-throwaway-repro` skill to create a disposable named session and drive the real agent UI through Herdr's CLI/API into the target state. 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` against the session under test. Before writing the override, check whether one already exists; never overwrite or remove a pre-existing override without alignment. Once the rule is correct, remove the temporary override or restore the previous one exactly so the committed bundled manifest remains the source of truth. Do not add large agent-specific full-screen fixture suites for routine manifest tuning. Keep Rust tests focused on manifest parsing, rule semantics, skip-state semantics, source precedence, cache reload behavior, and update flow. Use live pane reads for agent-specific screen evidence. @@ -187,8 +194,9 @@ Do not use GitHub closing keywords like `fixes #`, `closes #