Skip to content
Skills Library
Programming · Review & audit

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.

Repository
Roastpilot ↗
Licence
GPL-3.0
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

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. 1. Know where the change belongs
  2. 2. Design
  3. 3. Types and errors
  4. 4. UI
  5. 5. Tests
  6. 6. Finish
Original SKILL.md headings · 52 lines, 499 words
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

RepositoryScoreLicence
This page · mnabaci/Roastpilot100GPL-3.0
brentrector/claude-skills100MIT
andreibesleaga/gabbe90CC-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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.