docs: document the toolchain, the checks and .claude/ in the README - #209
Merged
Conversation
README.md described the stacks and the backup wiring but nothing about working in the repo: no mise, no make, no mention of what CI runs or what gates a merge. Someone cloning it had no way to find `make check`. Adds a getting-started block, a checks table explaining what each step catches (including why .env.example coverage is checked at all — a variable missing there deploys fine on the host that already has it set and fails everywhere else), why the CVE sweep is deliberately not a required check, the .claude/ setup, and pointers to LICENSE and SECURITY.md. AGENTS.md gains the same .claude/ section, including the .env guard hook. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F9MnUHayBCrncnczqMhSVy
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
2 participants
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.
README.mddescribed the stacks and the backup wiring but nothing about working in the repo — no mise, nomake, no mention of what CI runs or what gates a merge. Someone cloning it had no way to discovermake check.README.md
make tools/make hooks/make check, plus the day-to-day targets (make stacks,make config STACK=…,make up|down|restart|pull|logs).mise.tomlis the single source of tool versions and CI installs from the same file, so a hook that passes locally passes in CI.make checkcatches. The.env.examplecoverage rule gets a sentence of its own, because the reason isn't obvious: a variable referenced in a Compose file but missing from.env.exampledeploys fine on the host that already has it set, and fails for everyone else.scan.ymlis path-filtered and advisory; a required check that doesn't run on every PR blocks the merge permanently. It answers "which of my services is currently exposed" weekly; an upstream CVE in someone else's image isn't something a commit here can fix.LICENSE/SECURITY.md.AGENTS.md
New Agent tooling section covering the checked-in
.claude/: thestack-consistency-revieweragent (with this many near-identical Compose files, drift is the failure mode rather than bugs), thenew-stackskill (disable-model-invocation: true, so it only runs when asked for by name),backup-preflight, and the two hooks — one refuses to edit a real.env(gitignored, so the edit would be invisible and unshippable), the other validates a Compose file at write time rather than atmake check.Verification
Markdown only; no Compose, workflow or script changes. Facts were read out of the repo rather than recalled: the
maketargets from theMakefile, the CI job name fromci.yml, the path filter and rationale fromscan.yml, the.claude/contents from the files themselves, and the single required context (pre-commit) from the ruleset inhomelab/terraform/github/variables.tf.pre-commitcould not be run here (mise is not installed in this container); checked by hand for trailing whitespace and a trailing newline. Thepre-commitjob on this PR runs the full hook set.🤖 Generated with Claude Code
https://claude.ai/code/session_01F9MnUHayBCrncnczqMhSVy
Generated by Claude Code