serdarvaran/copperwright

An electronics skill for coding agents that audits boards before you order them.
English · Türkçe
Copperwright teaches Claude Code, Codex, Hermes, LM Studio and other skill-aware agents to work on KiCad hardware
and the firmware tied to it the way a careful reviewer would. Critical electrical facts come from manufacturer
documents. Schematics, pin maps, PCB rules and fabrication files are checked by deterministic tools before a release
is called done.
> The expensive mistakes on a small board are rarely exotic: an LED on a boot strap, an EN pin with no RC, a missing
> 100 nF, a USB-C CC resistor of the wrong value. Copperwright looks for exactly those, on the netlist, not on a
> screenshot.
## Contents
What it catches
How it works
Schematic audits
ESP32 pin rules
PCB, power and fabrication
Rule library
Install
Usage
Tools reference
Repository layout
Testing and evaluation
Limits
License
## What it catches
Real findings from the tools on an ESP32-S3 sensor board netlist with seeded defects:
text
$ netlistaudit.py --netlist sensornode.xml
ERROR singlepinnet ref=U1 pin=38 net=LEDSTATUS: expected labelled net with >=2 pins, got 1 pin
ERROR decoupling ref=U1 pin=2 net=+3V3: expected >=1 capacitor Add a 100 nF capacitor from +3V3 to GND next to U1 pin(s) 2.
ERROR i2cpullups net=I2CSCL: expected exactly one pull-up to a rail, got none
-> Add one pull-up (e.g. 4.7k for fast mode) from I2CSCL to the I/O rail.
FAIL: 12 checks, 3 errors, 0 warnings
$ esp32pinaudit.py --netlist sensornode.xml --ref U1 --chip esp32s3
ERROR straplevel ref=U1 pin=27(GPIO0) net=BOOT: expected level 1 at reset, got 0
— LED R3+D1 to GND clamps the pin low -> Move LED R3+D1 off GPIO0, or buffer it with a transistor
ERROR enrc ref=U1 pin=3(EN) net=EN: expected R≈10kΩ to 3V3 and C≈1µF to GND (RC delay),
got missing C to GND; pull-ups [('R1', '10kΩ')], caps [] -> Add 1 µF from EN to GND near the module.
FAIL: 8 checks, 2 errors, 0 warnings
On an open-source ESP32-S3 watch schematic, the same tools found the EN pin and GPIO0 wired straight to the 3V3 rail
(no reset and no auto-programming), and a CP2102N and an AMS1117 with no supply capacitors.
## How it works
mermaid
flowchart TD
R[Requirements interfaces, power budget] --> S[Schematic KiCad 10]
S --> N[kicad-cli netlist]
N --> A[netlistaudit decoupling, I²C, shorts, names, BOM]
N --> P[esp32pinaudit straps, reserved pins, ADC, EN]
BI[board-interface.json] --> P
SC[sdkconfig] --> P
FW[firmware sources] --> P
A & P --> L[PCB layout fab .kicaddru rules]
L --> C[kicadchecks ERC, DRC, parity, waivers]
L --> T[powertracecheck IPC-2221 widths and vias]
C & T --> O[faboutputs Gerbers, drill, BOM, CPL, STEP]
O --> M[mechanical hand-off to Datumsmith]
Agents follow twelve non-negotiable rules in SKILL.md. Examples: never invent pinouts, absolute maximum ratings or
strap states; record the source of every critical value; separate verified facts, engineering choices, assumptions
and unknowns; never call a release passing without the deterministic checks.
## Schematic audits
netlistaudit.py reads a KiCad netlist (exported with kicad-cli, or directly from a .kicadsch) and reports
every finding with the reference, pin, net, expected value, actual value and a fix: