From f90fd8567e61fc07c2cfe5051d021d1e6f5742a5 Mon Sep 17 00:00:00 2001 From: anandh8x Date: Sat, 18 Jul 2026 21:16:00 +0530 Subject: [PATCH 1/2] docs: refresh repository agent guidelines --- AGENTS.md | 80 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0b912611a..a662d87f2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,27 +1,69 @@ ---- -description: Project guidelines for the open-source CLI coding agent (zero) repository. -globs: "*.go, *.js, *.md, *.json, *.toml, *.yaml, *.yml" -alwaysApply: false ---- +# Repository Guidelines for Zero -# Repository Conventions for Zero +These instructions apply to all work in this repository. For the user-facing +guide to extending Zero with specialists, hooks, plugins, MCP, and skills, see +[docs/EXTENDING.md](docs/EXTENDING.md). -This file outlines the project conventions and repository guidelines for coding agents when working on the `zero` repository. For the general guide on how to extend Zero (write specialist sub-agents, hooks, plugins, MCP, skills), see [docs/EXTENDING.md](docs/EXTENDING.md). +## 1. Contribution and Pull Request Rules -## 1. Project Conventions +- Before opening any pull request, **all contributors**—including maintainers, + community contributors, and coding agents—must read and follow + [CONTRIBUTING.md](CONTRIBUTING.md). +- Community pull requests require an existing parent issue with the + `issue-approved` label. Team members may open pull requests through the + internal development process described in `CONTRIBUTING.md`. +- Keep each change focused on the approved or assigned scope. Do not include + unrelated fixes, refactors, formatting churn, generated output, or existing + local changes in the same commit or pull request. +- Discuss new implementation languages, runtimes, major dependency changes, + and broad architectural rewrites with maintainers before implementation. +- Pull request descriptions must explain what changed and why, link the parent + issue when required, and list the tests or verification performed. Include + screenshots or a short recording for user-visible UI changes when practical. -- Build with `make`, not `go build` directly. -- Tests live next to the source file (`foo_test.go` next to `foo.go`). -- Run `make lint` before opening a PR. -- Never edit files under `third_party/` — those are vendored. -- Unify functions/methods where possible to prevent codebase inflation. Prefer a single cross-platform function with conditional checks over duplicating helpers per platform. +## 2. Repository and Implementation Conventions -## 2. Guidelines for Coding Agents +- Use the Go version declared in `go.mod`. Do not hardcode a different local + toolchain version in scripts or documentation. +- Use the repository build and release commands (`make` and + `go run ./cmd/zero-release ...`) instead of inventing parallel build flows. +- Keep tests beside their source files (`foo_test.go` next to `foo.go`). Add a + regression test for behavior changes and run affected concurrent code under + the race detector. +- Never edit files under `third_party/`; they are vendored. +- Prefer one cross-platform function with small conditional checks over + duplicated platform-specific helpers when the behavior can remain unified. +- Do not commit generated benchmark reports from + `internal/perfbench/reports/*.json`; reports are configuration-specific + evidence, not repository state. +- Preserve the user's working tree. Do not overwrite, delete, stage, or commit + unrelated tracked or untracked files. -If you are an AI coding agent executing tasks in this repository, you **MUST** run all Go code quality and security checks before committing code or completing your task: +## 3. Required Validation -1. **Format & Vet**: Run `go fmt ./...` and `go vet ./...`. -2. **Lint**: Run `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run --enable-only unused,ineffassign,staticcheck ./...`. -3. **Security**: Run `go run golang.org/x/vuln/cmd/govulncheck@v1.3.0 ./...`. +Run validation from the repository root before committing, opening a pull +request, or completing an implementation task: -If any check fails or cannot be run, do not ignore it. Prompt the user for instructions or setup assistance before proceeding. +1. **Formatting**: `go fmt ./...` (or `make fmt`). +2. **Vet**: `go vet ./...` (or `make vet`). +3. **Tests**: `go test ./...`. Use `make test` for the full race-enabled suite, + or run focused tests with `-race`, when concurrency is affected. +4. **Build**: `go run ./cmd/zero-release build`. +5. **Smoke test**: `go run ./cmd/zero-release smoke`. +6. **Advisory lint**: + `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run --enable-only unused,ineffassign,staticcheck ./...`. +7. **Security**: + `go run golang.org/x/vuln/cmd/govulncheck@v1.3.0 ./...`. +8. **Diff hygiene**: `git diff --check`. + +`make lint` currently runs the formatting check and `go vet`; it does **not** +run golangci-lint. The pinned golangci-lint job is advisory in CI while the +existing repository-wide backlog is cleaned up. Fix findings introduced by or +related to the current change. Unrelated pre-existing advisory findings do not +justify expanding a focused pull request; report them separately. + +Formatting, vet, tests, build, smoke, diff hygiene, and govulncheck are hard +requirements. If a related check fails, fix it. If a required check cannot run +because of the environment or fails for an unrelated external reason, report +the exact failure and obtain maintainer direction rather than silently ignoring +it. From 5fb01dae770b5c266adb1ab3da158bebf2bc472d Mon Sep 17 00:00:00 2001 From: anandh8x Date: Sat, 18 Jul 2026 21:24:07 +0530 Subject: [PATCH 2/2] docs: make validation guidance non-mutating --- AGENTS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a662d87f2..cdf9fe4f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,7 +44,8 @@ guide to extending Zero with specialists, hooks, plugins, MCP, and skills, see Run validation from the repository root before committing, opening a pull request, or completing an implementation task: -1. **Formatting**: `go fmt ./...` (or `make fmt`). +1. **Formatting check**: `make fmt-check`. If it fails, format with + `go fmt ./...` (or `make fmt`) and run the check again. 2. **Vet**: `go vet ./...` (or `make vet`). 3. **Tests**: `go test ./...`. Use `make test` for the full race-enabled suite, or run focused tests with `-race`, when concurrency is affected. @@ -54,7 +55,8 @@ request, or completing an implementation task: `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run --enable-only unused,ineffassign,staticcheck ./...`. 7. **Security**: `go run golang.org/x/vuln/cmd/govulncheck@v1.3.0 ./...`. -8. **Diff hygiene**: `git diff --check`. +8. **Diff hygiene**: `git diff HEAD --check` (covers staged and unstaged + tracked changes). `make lint` currently runs the formatting check and `go vet`; it does **not** run golangci-lint. The pinned golangci-lint job is advisory in CI while the