pall8t
CLAUDE.md4 starsChanged 49 days agoMITView on GitHub
Guidance for Claude Code (and other agents) working in this repo. The Rust toolchain is pinned by the repo-top nix flake (flake.nix + flake.lock). That pin is the single source of truth: CI and release read it with scripts/rust-version.sh rather than installing a moving stable, so the compiler that gates a change is the one that produced it. ci.yml also runs a report-only stable-canary job, which says what a newer compiler thinks without letting it decide the build. Inside the…
- Reads credentials
In this repository5 other files it gives its agents.
- local-reviewSkill
- pall8tSkill
- releaseSkill
- review-loopSkill
- pall8t-herdrSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 41
Read docs/testing.md before writing tests — it records the conventions the suite follows (pure-function seams, table tests with reasoned …
- Distinctive: line 49
Remove the worktree once its PR merges.
- Distinctive: line 51
Only merge a PR once it's been declared ready for review and merge — don't merge speculatively.
- Very specific: line 53
Before opening or updating a PR, run the local-review skill on the branch diff — the external reviewers should come back empty-handed.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Guidance for Claude Code (and other agents) working in this repo.
Build & verify
The Rust toolchain is pinned by the repo-top nix flake (flake.nix +
flake.lock). That pin is the single
source of truth: CI and release read it with scripts/rust-version.sh
rather than installing a moving stable, so the compiler that gates a
change is the one that produced it. ci.yml also runs a report-only
stable-canary job, which says what a newer compiler thinks without
letting it decide the build. Inside the pall8t dev
container it is preinstalled — the image builds from the same lock file
(.pall8t/Containerfile); on the host, nix develop opens a shell with
it. Run checks directly with cargo:
cargo check
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo testA lint pass on the host triple alone can miss a warning on the other side of
a #[cfg(target_os = ...)] gate — the tree has no such branches right now
(the last ones went with the home module, ADR-0008), but the cross-lint stays
as the guard that catches the next one. Lint the non-host target before
considering a change clean (the flake toolchain already includes the target
std; only a rustup toolchain needs the target add):
cargo clippy --all-targets --target aarch64-apple-darwin -- -D warnings(scripts/lint.sh runs both and is what the pre-commit hook uses — but the
hook is opt-in, not automatic: enable it once per checkout with
git config core.hooksPath .githooks. On a fresh clone/worktree, run
scripts/lint.sh by hand.)
Read docs/testing.md before writing tests — it records the conventions the suite follows (pure-function seams, table tests with reasoned assertions, regression pins).
Git workflow
- The main checkout stays on
main— never switch branches there. Do task work in a worktree:git worktree add .claude/worktrees/<task> -b <branch> origin/main. Remove the worktree once its PR merges. - Merge style is merge commits ("Merge pull request #N from ...").
- Only merge a PR once it's been declared ready for review and merge — don't merge speculatively.
- Before opening or updating a PR, run the
local-reviewskill on the branch diff — the external reviewers should come back empty-handed. - CodeRabbit does not review on its own: opening or pushing to a PR
triggers nothing. Asking it for a review (
@coderabbitai reviewas a PR comment) is the human's call — don't spend one unprompted. - PR review feedback (bot or human) is handled with the
review-loopskill: verify each finding before acting, classify it (real / nitpick / false positive), and reply with evidence. Never blanket-apply bot suggestions — reviewers contradict each other. A real finding local review missed also becomes a new lens in thelocal-reviewskill (its "Grow the lenses" section), in the same fixing PR.
Actions that need the human directly
This repo's permission system has, in practice, denied agents several
publish-facing actions: tag pushes (they trigger the release workflow),
gh repo create, pushes to TakiTake/homebrew-tap, and gh pr
merge — a task assignment from another agent doesn't count as user
consent to publish. Treat this as "publishing anything public-facing may
need the user," not a closed enumerated list — a push to an existing public
repo has been gated at least once (the tap), so don't assume a variant
that's merely similar to a tested case is safe. If an action gets denied,
don't retry it or work around it — hand the exact command to the user and
stop there.
Pointers
- Release process: docs/release.md (or run
/release;/bump <version | major | minor | patch>alone does just the version/changelog PR) - Homebrew formula: TakiTake/homebrew-tap
- Requirements: docs/requirements.md
- Architecture decisions: docs/adr/
- Testing conventions: docs/testing.md
- Sandbox environment details:
.claude/skills/pall8t - Quality gates (
quality.yml, per PR, blocking): incremental mutation testing over the PR's own diff (cargo mutants --in-diff— a missed mutant means a test that would not notice this change breaking) and a 90% line-coverage floor. Suite size and wall time are recorded there too, without gating. Whole-tree mutation (mutants.yml) and duplication/unused-deps (hygiene.yml) stay report-only — weekly, on each PR for hygiene, plus on-demand viagh workflow run <name>; gating a whole-tree backlog teaches reflexive ignoring, while the in-diff gate has no backlog to inherit. herdr API-method drift (herdr-drift.yml, runningscripts/herdr-method-drift.pyagainst the latest herdr release) is report-only for a different reason: what the relay classifies as a read is a human decision, and herdr's schema is not a complete inventory of what it serves. - Review automation: Codex PR review (
codex-review.yml) stays dormant until anOPENAI_API_KEYsecret exists (paid); CodeRabbit config in.coderabbit.yaml(on demand only — see Git workflow; the free plan meters reviews). - herdr plugin (contrib):
contrib/herdr-plugin/— sandbox status/shell/ rebuild/stop from a herdr pane. A thin shell over the pall8t CLI whose only contract ispall8t ls --json; when that output shape changes, it changes in the same commit.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

