homeracker

# 🤖 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](.github/workflows/README.md)
  - `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](.claude/rules/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](https://github.com/kellervater/kellervater/blob/main/.claude/skills/house-style/SKILL.md). 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`](https://github.com/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](docs/decisions/image-hosting-assets-repo.md).
- **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](https://www.conventionalcommits.org/).
  - 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
1. **Consult online docs**, especially the [BOSL2 wiki](https://github.com/BelfrySCAD/BOSL2/wiki)
1. **Ask before proceeding** if requirements conflict with best practices or patterns in the repo. This might indicate the needs for an ADR
1. **Make the changes**, create or update unit and integration tests, and run them locally. Iterate until all tests pass.
1. **Create/Update/Crosslink** documentation and ADRs where applicable
1. **Run pre-commit hooks** to catch formatting and linting issues before commit. Fix what they find, no ignores allowed.
1. **Code review**: review ALL changes holistically when done. Check for consistency, missed edge cases, and unintended side effects before presenting to the user.
1. **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](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.
1. **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](.claude/rules/openscad.md)
- Python: [python.md](.claude/rules/python.md)
- Shell and GitHub Actions: [shell.md](.claude/rules/shell.md)
- Renovate: [renovate.md](.claude/rules/renovate.md)
- E2E tests (`site/`, `configurator/`): [e2e.md](.claude/rules/e2e.md)
- TypeScript (`configurator/`, `site/`): see the Development Guidelines in [CONTRIBUTING.md](CONTRIBUTING.md)