Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
63af4cef6This file is pinned to the selected release. Download the original to open it in your design tool.
# Instructions for Claude working in this repo
This repo is one design in Amish Chadha's Open Hardware Portfolio. These rules apply to every session and override any broader instruction in a prompt. If a prompt conflicts with them, stop and ask.
## 1. Current portfolio phase: TRL cap 3
- The whole portfolio is capped at **TRL 3** (proof of concept on paper) until every repo is populated. The cap is set in `.kit/PHASE.yaml`.
- Do **not** create TRL 4 or later work: no test articles, build procedures, cut lists, purchasing checklists, test plans or reports (TST), PCB layouts or Gerbers, firmware beyond a clearly labeled sketch, or build-log tooling.
- `trl` and `trl_target` in `project.yaml` must not exceed the cap. `python .kit/render.py --check` enforces this.
- If the design looks ready for TRL 4, write that up as a recommendation in the review note (section 4) and stop.
## 2. Decision rights
- Amish makes all decisions on scope, budget, naming, visibility, safety trade-offs and anything that changes the pitch.
- Never record a decision as made, accepted or approved unless Amish stated it in this session. Record it as **"Proposed, awaiting Amish"** with the options and a recommendation.
- Never raise a budget past the figure in `project.yaml` without flagging it as proposed.
## 3. Scope of a session
- Do exactly what the prompt asks, in the order asked. Do not add deliverables the prompt did not name.
- Optional ideas go in the review note as suggestions, not into the repo.
- Keep each session to one TRL step for one repo.
## 4. End every session with a review note
Write or update `docs/REVIEW.md` before the final commit:
- What was done, with file paths
- Key results and numbers, including any requirement that is **not** met
- Decisions proposed and awaiting Amish
- Safety concerns
- Recommended next step
Then commit, push and **stop**. Do not continue into the next step without a new instruction.
## 5. Required concept media (all repos, TRL 2 and up)
Every repo needs visuals that explain the idea. Generate them from `cad/src/concept_media.py` with `.kit/concept.py` (`render_all`):
| File | What it shows | When |
| --- | --- | --- |
| `media/hero.png` | Shaded isometric render with a 1.75 m person for scale; the website card | Always |
| `media/concept-blueprint.png` (+ `.pdf`) | Blueprint concept sheet: views, scale, key figures | Always |
| `media/model.glb` + `media/viewer.html` | Interactive 3D viewer for the website | Always |
| `media/cutaway.png` | Section view | When the inside matters |
| `media/exploded.png` | Exploded view with numbered callouts matching the BOM | Recommended |
| `media/flow.png` | System, energy or material flow diagram | When the concept moves energy or material |
For small objects (wearables, handheld tools) use a context part such as a hand or forearm instead of the 1.75 m person (`scale_figure=False, context=[...]`); see `tremortrace` for a worked example. At TRL 2 the model may be a simple massing model: correct proportions and main parts, not detailed geometry. Label concept media "CONCEPT, NOT FOR FABRICATION". Mark estimated flow values as estimates.
## 5a. Session commands
Use the repo's slash commands rather than improvising scope: `/populate` (strong TRL 2 with media), `/advance-trl3` (only after Amish approves), `/rein-in` (stop and review), `/refresh-media`, `/render-product` (appearance model, photoreal renders and storefront images), `/release` (release gate and release preparation; never makes the repo public).
## 5b. Product renders and storefront images (TRL 3)
- Build `cad/src/product_model.py` (`product_parts()`, `TITLE`, `RENDER_VIEWS`) with every main dimension taken from `cad/src/model.py`. Record any appearance deviation in `docs/REVIEW.md` as "Proposed, awaiting Amish".
- Give scale with `.kit/context_parts.py`: a hand or forearm for small objects, `mannequin()` for body-scale products. Never render a floating person.
- Render with `.kit/export_views.py` and `.kit/photoreal.py`, caption with `.kit/photo_caption.py`, and lead the README with `media/render-hero.png`.
- Then run `python .kit/cards.py .` for `media/card.png` and `media/social-preview.png`. See `.kit/STANDARDS.md` sections 12 and 13.
- Run `python .kit/image_qc.py` and look at every image yourself. Text must be inside the image, never overlap other text or the render, and be readable; renders must be sharp. Fix and regenerate anything that fails.
## 6. Standards
- Follow `.kit/STANDARDS.md` (document IDs, versions, revision history, TRL evidence).
- Chicago Manual of Style. **Never use em dashes.** Restructure the sentence instead.
- SI units, with imperial in parentheses where useful.
- Safety notes stay in every document that describes something hazardous. Mains voltage, high temperature, pressure, lithium cells and moving machinery always get a safety section.
- Run `python .kit/render.py --check` before committing. Do not commit if it fails.
## 7. Release and authorship
- Making a repository public, tagging a release or changing repository settings is Amish's decision. Prepare, then ask.
- Before any release, `python .kit/release_gate.py` must pass (`.kit/STANDARDS.md` section 14). Fix what fails; report warnings.
- Author commits as Amish Chadha <amish@designmolecule.com> with a `Co-Authored-By: Claude` trailer. Commits must reach GitHub signed with Amish's key (Verified). Never rewrite history once a repository is public.
- Keep `CITATION.cff` (Amish first, ORCID 0009-0000-8079-7141), `CONTRIBUTORS.md` and the README Credits section in agreement. `CITATION.cff` names one license only (Zenodo rejects a list); the full license split lives in `REUSE.toml`.
- Keep the repo REUSE compliant: when you add a kind of file that `REUSE.toml` does not cover, add an annotation there and run `reuse lint` before committing (`.kit/STANDARDS.md` section 16).
- Zenodo and Software Heritage (`.kit/STANDARDS.md` section 17): prepare with `python .kit/archive.py reuse` and `python .kit/archive.py zenodo`. Switching a repo on in Zenodo, publishing releases and requesting archive saves are Amish's decisions. After Zenodo mints the DOIs, record the concept DOI with `python .kit/archive.py zenodo --doi <concept DOI>`.
- OpenRatio and BioMedical repos: soft, non-clinical wording only ("research and educational prototype, not a medical device").