homeracker
AGENTS.md553 starsChanged 2 months agoMITView on GitHub
The canonical instruction set for every coding agent working in this repository. HomeRacker is a modular 3D-printable rack-building system. Core components are parametric OpenSCAD models built on the BOSL2 library. Licensed MIT (code) and CC BY-SA 4.0 (models).
1 other project uses a version of this.
Adopted by
Most recently taken up by
- kellervater/homerackerword for word, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- kellervater/homeracker★ 553100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- decision-recordsSkill
- grill-my-modelSkill
- grill-my-planSkill
- humanizerSkill
- makerworld-descriptionSkill
- scadfmt-adaptSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 0 are common, 6 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Test-Driven Development: NO change without a test. EVERY change MUST be tested before completion.
- Very specific: line 32
Unit tests: run via pre-commit hooks, fast and mocked.
- Very specific: line 33
Integration tests: run in CI on ubuntu and windows (integration-tests.yml).
- Distinctive: line 35
DRY, KISS, YAGNI: Keep it simple, don't over-engineer.
- Distinctive: line 38
Every code change that adds, modifies, or removes functionality must include a documentation update.
- Very specific: line 41
When adding or modifying model parts (parts/*.scad), regenerate the render PNGs with scadm export-png (full F6 renders, not previews) and …
- Very specific: line 42
Assets Policy: All manually-created images (photos, diagrams, logos, MakerWorld description images) live in kellerlabs/assets.
- Very specific: line 44
When the user makes an architectural or design decision during a session, create a decision record in docs/decisions/.
- Distinctive: line 46
Commits: Use Conventional Commits.
- Distinctive: line 54
Before terminal operations, consider these steps (use best judgement):
- Distinctive: line 67
Ask before proceeding: if requirements conflict with best practices or patterns in the repo.
- Very specific: line 74
Create the PR: Read .github/pull_request_template.md and fill in every section.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.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
🤖 HomeRacker Agent Instructions
The canonical instruction set for every coding agent working in this repository.
📌 Project Overview
HomeRacker is a modular 3D-printable rack-building system. Core components are parametric OpenSCAD models built on the BOSL2 library. Licensed MIT (code) and CC BY-SA 4.0 (models).
🗂️ Tools & Structure
- Languages: OpenSCAD (
.scad), Python, Bash, TypeScript - Key Dirs:
models/: OpenSCAD models, one folder per model typecmd/: Python and shell tooling (scadm,scadfmt,test,export,lib,linux,setup)configurator/: TypeScript web configuratorsite/: Astro site that renders this repo's READMEsdocs/: style guide, workflows, and ADRs underdocs/decisions/.claude/:skills/loaded on demand by name,rules/scoped bypaths:frontmatter,agents/for subagents.github/: workflows, composite actions, PR template. PR jobs run throughci.ymland must be listed in itscheck-resultsjob, see CI overviewbin/: OpenSCAD binaries and libraries, generated byscadm installand gitignored
- HomeRacker Standards: 15mm base unit, 4mm lock pins, 2mm walls, 0.2mm tolerance. See
README.md. - Contribution Guide: See
CONTRIBUTING.mdfor setup and workflow. - Dependency Manager:
scadminstalls OpenSCAD and the libraries declared inscadm.json.- Install:
scadm install - Config:
scadm.jsonin the project root - Help:
scadm -h
- Install:
- Formatter:
scadfmt format <path>formats.scadfiles. Seecmd/scadfmt/README.md.
🧭 Core Principles
- Test-Driven Development: NO change without a test. EVERY change MUST be tested before completion. No exceptions for "simple" changes.
- Unit tests: run via pre-commit hooks, fast and mocked. The
scadm-testshook fires on changes undercmd/scadm/. - Integration tests: run in CI on ubuntu and windows (
integration-tests.yml). Update them when adding or modifying CLI commands or the config schema. SeeTESTING.md. - E2E tests: Playwright in
site/e2e/, run byweb.yml. Every user-visible change tosite/orconfigurator/adds or updates a journey. See e2e.md.
- Unit tests: run via pre-commit hooks, fast and mocked. The
- DRY, KISS, YAGNI: Keep it simple, don't over-engineer.
- Be Brief: Any written output (docs, ADRs, code comments, commit messages, PR bodies, GitHub comments) needs to use the house-style skill. It lives outside this repo, so fetch it before drafting:
curl -sS https://raw.githubusercontent.com/kellervater/kellervater/main/.claude/skills/house-style/SKILL.md - Documentation Policy:
- Every code change that adds, modifies, or removes functionality must include a documentation update.
- Cross-link related documentation and GitHub issues/PRs. Also update links upon refactoring.
- Links must survive squash merges. Repo docs link files relatively. PR and issue bodies and comments link files as
https://github.com/kellerlabs/homeracker/blob/main/<path>, since a relative link there resolves against the PR URL. Never link a PR branch or a commit on it: both vanish after the squash merge. An older file version (e.g. a superseded ADR) is linked by its commit onmain:git log -1 --format=%H origin/main -- <path>. - When adding or modifying model parts (
parts/*.scad), regenerate the render PNGs withscadm export-png(full F6 renders, not previews) and update both the model's README 📸 Catalog and the parentmodels/README.mdindex.
- Assets Policy: All manually-created images (photos, diagrams, logos, MakerWorld description images) live in
kellerlabs/assets. Push directly to itsmainbranch. Reference viahttps://raw.githubusercontent.com/kellerlabs/assets/main/<repo>/<path>. Only auto-generated render PNGs (**/renders/*.png) are tracked in source repos. See image-hosting-assets-repo. - Architecture Decision Records (ADRs):
- When the user makes an architectural or design decision during a session, create a decision record in
docs/decisions/. Load thedecision-recordsskill for the full workflow, template, and supersede flow. - Cross-link from related docs (READMEs, instructions, other decisions) where viable.
- When the user makes an architectural or design decision during a session, create a decision record in
- Commits: Use Conventional Commits.
- Types:
feat,fix,docs,chore,refactor,test - Format:
type(scope): descriptionortype: description - Breaking changes: add
!(e.g.feat!: change base unit) - NEVER amend commits (
--amend). PRs are squash-merged, so extra commits are fine.
- Types:
💻 Terminal Session Setup
Before terminal operations, consider these steps (use best judgement):
git fetch origin && git rebase origin/mainto sync with latest mainsource .venv/Scripts/activate(Windows) orsource .venv/bin/activate(Linux/macOS) to activate the venvscadm installif OpenSCAD or a library inscadm.jsonis missing or out of date
⚙️ MANDATORY Workflow
[!IMPORTANT] On errors: step back, check the docs, ask the user if stuck. Don't iterate blindly.
- Check repo patterns first for consistency, and relevant ADRs to understand existing conventions and decisions
- Consult online docs, especially the BOSL2 wiki
- Ask before proceeding if requirements conflict with best practices or patterns in the repo. This might indicate the needs for an ADR
- Make the changes, create or update unit and integration tests, and run them locally. Iterate until all tests pass.
- Create/Update/Crosslink documentation and ADRs where applicable
- Run pre-commit hooks to catch formatting and linting issues before commit. Fix what they find, no ignores allowed.
- Code review: review ALL changes holistically when done. Check for consistency, missed edge cases, and unintended side effects before presenting to the user.
- User Review let the user review your changes BEFORE you stage anything in git and wait for their go ahead. For changes under
site/orconfigurator/, start the dev server and give them the local URL first, see CONTRIBUTING.md.- Cloud sessions (
CLAUDE_CODE_REMOTE=true) skip this step: commit, push and open the PR directly. Address Copilot reviews when they arrive, but never request one.
- Cloud sessions (
- Create the PR Read
.github/pull_request_template.mdand fill in every section. Stick to house-style.
📚 Technology-Specific Guidelines
Each file below carries paths: frontmatter and loads automatically when you touch a matching file.
- Documentation: stick to the house-style skill
- OpenSCAD: openscad.md
- Python: python.md
- Shell and GitHub Actions: shell.md
- Renovate: renovate.md
- E2E tests (
site/,configurator/): e2e.md - TypeScript (
configurator/,site/): see the Development Guidelines in CONTRIBUTING.md
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.

