Adopt AGENTS.md agent standard + guardrails - #198
Merged
Conversation
Three references written against v1.2.11 that were sitting untracked: - CLAUDE.md — usage reference: component API, theming, common patterns. - CLAUDE-INTERNALS.md — how the library is built, for modifying it. - ANALYSIS.md — analysis of the repo as cloned on 2026-07-18. Committing so they survive and can be updated alongside the code rather than being regenerated from scratch each time. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Brings this repo onto the same agent-instruction standard as the rest of the
pathscale codebase, following PakhomovAlexander/project-hub.
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.
Contents are stack-aware rather than boilerplate: invariants, build/test
commands and release discipline reflect what this repo actually is (Rust crate
vs binary vs workspace; JS library vs application; which package manager the
lockfile says). Shared across every repo: Verification ("run what you build";
compare against the base branch instead of asserting; a suspiciously fast build
was cached), PR discipline, docs-are-shared-memory-not-private-memory, and the
git workflow.
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
in use here.
The CI-green rule ships commented out with its reason and enabling steps: CI
does not reliably attach checks to pull requests yet, so "wait for green" would
teach an agent to wait on nothing. It is a separate project.
.gitignore drops superseded blocks on CLAUDE.md, AGENTS.md and /.claude so this
guidance is tracked; /.claude/settings.local.json stays ignored, since personal
overrides should not be shared.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
🚀 Preview deployment is ready! You can view the preview at: https://pr-ui-preview-198.surge.sh |
Adds docs/frontend-conventions.md — the frontend working agreement — and links it as the first invariant in AGENTS.md so it is read before implementation files are opened. Covers the non-negotiables (SolidJS not React; signals/<Show>/<For>/class=; reuse @pathscale/ui and verify props from existing usage; Bun and Biome; mirror an existing pattern before inventing one), a context-efficient workflow (classify before reading, search narrowly, at most five files to start, don't repeat known searches, validate incrementally, report only what changed), and this repo's actual validation commands read from package.json. Content is tiered to what this repo actually is, verified against the manifests rather than assumed: - Full frontend apps also get the backend-contract rules: docs/*.services.json is authoritative, don't invent endpoints/params/returns/roles, never hand-edit generated DTOs under src/models/**, and don't introduce REST/fetch where the app uses the @pathscale/wss-adapter WebSocket RPC. - Solid apps with no backend contract get the stack rules only — quoting a services JSON at them would point at a file that does not exist. - Packages that are not Solid apps get Bun/Biome and mirror-existing-patterns only. Two repo-specific adjustments: @pathscale/ui is told it *is* the library, so a prop change is an API change for every consumer, rather than being told to "reuse @pathscale/ui"; and the i18n rule is stated only where an i18n system exists, phrased conditionally elsewhere. The References section (project map / services contract / UI conventions / validation) is included as the intended split but marked TODO — those documents do not exist yet, and pointing at missing files is worse than not pointing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdis canonical;CLAUDE.mdis a thin@AGENTS.mdimport. Codex, Cursor and Gemini CLI readAGENTS.mdnatively 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
filesplusmain/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
Guardrails are enforced, not just documented
.claude/settings.jsonpre-allows read-only commands for this stack and prompts before pushes, publishing,gh pr merge, cloud CLIs and deploys. ThePreToolUsehook catches wrapper forms a permission glob misses —env X=y git push,git -C dir push,bash -c '…'— and includesbunin 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
statusCheckRollupreturns 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.mdand/.claudeso this guidance is actually tracked./.claude/settings.local.jsonstays 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