engineering-standards
/engineering-standards
The Roastpilot coding checklist. Use before writing or changing any code in this repo, and whenever unsure how something should be structured.
- Author
- mnabaci ↗
- Repository
- Roastpilot ↗
- Licence
- GPL-3.0
- Last repository change
- 11.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.
GPL-3.0, otwarta.
What it does and when to use it
The Roastpilot coding checklist. Use before writing or changing any code in this repo, and whenever unsure how something should be structured.
Original author description
The Roastpilot coding checklist. Use before writing or changing any code in this repo, and whenever unsure how something should be structured.
How it works
- 1. Know where the change belongs
- 2. Design
- 3. Types and errors
- 4. UI
- 5. Tests
- 6. Finish
SKILL.md preview
---
name: engineering-standards
description: The Roastpilot coding checklist. Use before writing or changing any code in this repo, and whenever unsure how something should be structured.
---
# Engineering standards
Read this before touching code. It is the checklist `code-review` holds you to.
## 1. Know where the change belongs
- Read the relevant `docs/spec/*.md`. If behaviour changes, update the spec first (`plan-feature`).
- Find the package by its job (root `AGENTS.md` boundaries table) and read that package's `AGENTS.md`.
- Variation (new roaster, rule, layer, exporter)? It is an extension point: use `add-extension`.
- Check the files you will touch against this checklist first. Anything that breaks it gets refactored in its own `refactor:` commit before or alongside your change.
## 2. Design
- One responsibility per module and per function. A file over ~200 lines or a function over ~40 is a smell.
- Depend on interfaces from `core`, receive dependencies through constructors or parameters.
- Inject time (`Clock`) and I/O; `core` stays pure.
- Prefer data + small functions over class hierarchies. No base classes "for later".
- No speculative options, flags or abstractions: add an extension point only when a second implementation is planned.
- Names say what, not how: `DropTempEndRule`, not `Rule2`.
## 3. Types and errors
- TypeScript for everything, including configs and scripts; no new `.js` files.
- `strict` TypeScript; no `any`, no non-null `!` without a comment saying why it is safe.
- Validate data at boundaries (IPC with zod, serial lines in the driver, DB rows in repositories).
- Errors: return typed results for expected failures; throw only for programmer errors (`docs/spec/errors-and-logging.md`).
- Never hide an error: no empty `catch`; every `void promise` gets a `.catch` that logs; a `catch` either handles, returns a typed error, or logs and rethrows.
- Think through the edge cases before coding: timeouts, disconnects mid-call, bad or missing input, a call during another, quit at any moment. Each gets a test.
- Log through the injected `Logger` (`logger.child('scope')`), never `console`. One event name per thing that happened (`session.connect-failed`) plus context; failures and state changes, not every reading.
- Anything that can leave the heater on ends in `safeStop()`.
## 4. UI
- Build from `@roastpilot/ui` components; new ones via `add-component`.
- Tokens only: Tailwind token classes (`bg-surface`, `text-ink-muted`) or CSS variables. No hex, no arbitrary sizes.
- One primary action per state, numbers before sentences, one-line hints, no modals during a roast except the confirmation dialog (`ConfirmDialog`) after the user's own click.
- Accessible: real `<button>`/`<input>` + `<label>`, focus ring, 44px targets.
## 5. Tests
- Vitest, next to the code: `thing.ts` + `thing.test.ts`.
- Every rule, controller, state transition and safety condition has a test, using `SimulatedDriver` and a fake clock.
- Test behaviour through public APIs, not private details.
- UI tests share one environment per worker: never `vi.mock` a module in a UI test; inject the dependency (e.g. the chart engine provider `PlotEngineProvider`) instead, and restore anything you change on globals.
## 6. Finish
- `pnpm check` passes.
- Spec and ADRs updated; skills updated if a workflow changed.
- Conventional commit on a branch; PR uses the template.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mnabaci/Roastpilot | 100 | GPL-3.0 |
| brentrector/claude-skills | 100 | MIT |
| andreibesleaga/gabbe | 90 | CC-BY-4.0 |
Database snapshot: 13.11.2026 · package version 02f48897d986 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100writing-code
Apply Gather V2 coding standards (STANDARDS.md) when writing or modifying code. Use when writing new code, refactoring, or reviewing code for standards compliance. - 86plan-feature
Plan a new Roastpilot feature spec-first. Use when asked to add or change behaviour, before writing code. - 100coding-standards
Use when writing, updating, or auditing CODING_STANDARDS.md, or when a mistake from a session or review should become a coding rule. - 90add-extension
Add a new implementation of a Roastpilot extension point (roaster driver, transport, end rule, coach rule, chart layer, exporter, notifier, ...). Use when supporting new hardware or a new rule. - 90cpp-coding-standards
C++ Core Guidelines coding standards. Use when writing, reviewing or refactoring C++ code for modern, safe, idiomatic practice. - 86review-checklist
The checklist to run on every code review. Use it each time you review code, before you write any finding.