Adopt AGENTS.md agent standard + guardrails

[pathscale]

Brings this repo onto the same agent-instruction standard as the rest of the pathscale codebase, following PakhomovAlexander/project-hub.

Docs and guardrails only — no source or dependency changes.

Single-sourced instructions

AGENTS.md is canonical; CLAUDE.md is a thin @AGENTS.md import. Codex, Cursor and Gemini CLI read AGENTS.md natively and Claude Code loads it through the import, so every agent lands on the same runbook instead of a per-vendor fork. Previously most of these repos had no agent instructions at all, and where they existed they were Claude-only and inconsistent between repos.

Stack-aware, not boilerplate

The invariants, build commands and release discipline reflect what this repo actually is — detected from the manifests rather than assumed: Rust crate vs binary vs workspace; JS library vs application/site (a library declares files plus main/exports; a site declares neither); and the package manager the lockfile actually indicates.

So a publishable crate gets the crates.io irreversibility rule and the pre-release pinning gotcha; a website does not get npm release invariants it would never use.

Shared across every repo

• Verification — run what you build; if you can't run it, say so. Compare against the base branch rather than asserting a failure is pre-existing. A build that finishes suspiciously fast was cached, not rebuilt.
• PR discipline — always paste the full PR URL, not just the number.
• Docs are shared memory — durable learnings belong in the repo, not an agent's private memory, which dies with the machine.
• Git workflow — explicit branch on push, branch naming, no force-push during review.

Guardrails are enforced, not just documented

.claude/settings.json pre-allows read-only commands for this stack and prompts before pushes, publishing, gh pr merge, cloud CLIs and deploys. The PreToolUse hook catches wrapper forms a permission glob misses — env X=y git push, git -C dir push, bash -c '…' — and includes bun in the publish watchlist, since that is the package manager actually in use across these repos.

The two overlap deliberately and must be kept in sync; both files say so. It is one layer of defence, not a sandbox — pattern matching over a command string is best-effort, and the hook is explicit about that.

CI rule ships dormant

The "don't call it done until CI is green" rule is present but commented out, with its reason and enabling steps. CI here does not reliably attach checks to pull requests, so statusCheckRollup returns empty and the rule would teach an agent to wait on nothing. Enabling it is a separate project.

.gitignore

Drops superseded blocks on CLAUDE.md, AGENTS.md and /.claude so this guidance is actually tracked. /.claude/settings.local.json stays ignored — personal overrides shouldn't be shared.

Note

Deliberate v1 across the whole codebase; expect to refine wording and the invariant list per repo. The reference is a multi-repo hub template, so its repos/ symlinks, tracker and ADR scaffolding were intentionally not cargo-culted into standalone repos.

🤖 Generated with Claude Code