agentleFS
kellerlabskellerlabs/homeracker/AGENTS.md

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

  • Other versions1 project uses a version of this.

    Word for word · 1

    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.

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
  1. Distinctive:

    Test-Driven Development: NO change without a test. EVERY change MUST be tested before completion.

    line 31
  2. Very specific:

    Unit tests: run via pre-commit hooks, fast and mocked.

    line 32
  3. Very specific:

    Integration tests: run in CI on ubuntu and windows (integration-tests.yml).

    line 33
  4. Distinctive:

    DRY, KISS, YAGNI: Keep it simple, don't over-engineer.

    line 35
  5. Distinctive:

    Every code change that adds, modifies, or removes functionality must include a documentation update.

    line 38
  6. Very specific:

    When adding or modifying model parts (parts/*.scad), regenerate the render PNGs with scadm export-png (full F6 renders, not previews) and …

    line 41
  7. Very specific:

    Assets Policy: All manually-created images (photos, diagrams, logos, MakerWorld description images) live in kellerlabs/assets.

    line 42
  8. Very specific:

    When the user makes an architectural or design decision during a session, create a decision record in docs/decisions/.

    line 44
  9. Distinctive:

    Commits: Use Conventional Commits.

    line 46
  10. Distinctive:

    Before terminal operations, consider these steps (use best judgement):

    line 54
  11. Distinctive:

    Ask before proceeding: if requirements conflict with best practices or patterns in the repo.

    line 67
  12. Very specific:

    Create the PR: Read .github/pull_request_template.md and fill in every section.

    line 74

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

🤖 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 type
    • cmd/: Python and shell tooling (scadm, scadfmt, test, export, lib, linux, setup)
    • configurator/: TypeScript web configurator
    • site/: Astro site that renders this repo's READMEs
    • docs/: style guide, workflows, and ADRs under docs/decisions/
    • .claude/: skills/ loaded on demand by name, rules/ scoped by paths: frontmatter, agents/ for subagents
    • .github/: workflows, composite actions, PR template. PR jobs run through ci.yml and must be listed in its check-results job, see CI overview
    • bin/: OpenSCAD binaries and libraries, generated by scadm install and gitignored
  • HomeRacker Standards: 15mm base unit, 4mm lock pins, 2mm walls, 0.2mm tolerance. See README.md.
  • Contribution Guide: See CONTRIBUTING.md for setup and workflow.
  • Dependency Manager: scadm installs OpenSCAD and the libraries declared in scadm.json.
    • Install: scadm install
    • Config: scadm.json in the project root
    • Help: scadm -h
  • Formatter: scadfmt format <path> formats .scad files. See cmd/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-tests hook fires on changes under cmd/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. See TESTING.md.
    • E2E tests: Playwright in site/e2e/, run by web.yml. Every user-visible change to site/ or configurator/ adds or updates a journey. See e2e.md.
  • 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 on main: git log -1 --format=%H origin/main -- <path>.
    • When adding or modifying model parts (parts/*.scad), regenerate the render PNGs with scadm export-png (full F6 renders, not previews) and update both the model's README 📸 Catalog and the parent models/README.md index.
  • Assets Policy: All manually-created images (photos, diagrams, logos, MakerWorld description images) live in kellerlabs/assets. Push directly to its main branch. Reference via https://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 the decision-records skill for the full workflow, template, and supersede flow.
    • Cross-link from related docs (READMEs, instructions, other decisions) where viable.
  • Commits: Use Conventional Commits.
    • Types: feat, fix, docs, chore, refactor, test
    • Format: type(scope): description or type: description
    • Breaking changes: add ! (e.g. feat!: change base unit)
    • NEVER amend commits (--amend). PRs are squash-merged, so extra commits are fine.

💻 Terminal Session Setup

Before terminal operations, consider these steps (use best judgement):

  1. git fetch origin && git rebase origin/main to sync with latest main
  2. source .venv/Scripts/activate (Windows) or source .venv/bin/activate (Linux/macOS) to activate the venv
  3. scadm install if OpenSCAD or a library in scadm.json is missing or out of date

⚙️ MANDATORY Workflow

[!IMPORTANT] On errors: step back, check the docs, ask the user if stuck. Don't iterate blindly.

  1. Check repo patterns first for consistency, and relevant ADRs to understand existing conventions and decisions
  2. Consult online docs, especially the BOSL2 wiki
  3. Ask before proceeding if requirements conflict with best practices or patterns in the repo. This might indicate the needs for an ADR
  4. Make the changes, create or update unit and integration tests, and run them locally. Iterate until all tests pass.
  5. Create/Update/Crosslink documentation and ADRs where applicable
  6. Run pre-commit hooks to catch formatting and linting issues before commit. Fix what they find, no ignores allowed.
  7. Code review: review ALL changes holistically when done. Check for consistency, missed edge cases, and unintended side effects before presenting to the user.
  8. User Review let the user review your changes BEFORE you stage anything in git and wait for their go ahead. For changes under site/ or configurator/, 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.
  9. Create the PR Read .github/pull_request_template.md and 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.