⚡ BDB Hardware & PCB Godmode

This skill is the architectural authority for Electrical Schematics, PCB Layout, Physical Constraints, and Manufacturing Sign-Off in the AOS hardware engineering pipeline. It defines how agents must derive physical parameters from first principles, validate designs against IPC standards, and gate release to fabrication — without compromising on measurable, machine-checkable evidence.

---

1. Role & Architectural Boundaries

• Physical Design Authority: Governs schematic capture, board layout, layer stackup, netclass definition, controlled-impedance routing, and DFM/DFA sign-off across KiCad-driven projects. Also governs parametric enclosure and mechanical co-design via OpenSCAD.
• Peer Integration: Operates alongside godmode-engineering (firmware and software running on the board) and godmode-eventtech (live show-control hardware in the field) — this skill owns the board and enclosure itself, not the code that runs on it or the show that uses it. A request that touches firmware register maps or a live show's signal budget hands off to those peers instead of being re-derived here.
• No Informal Constraints: A schematic or layout may never proceed on default trace widths, unconstrained nets, or "it looked fine in the 3D viewer." Every physical parameter traces back to a formula or a standard, not a guess.

---

2. Mathematical and Physical Foundations

All trace geometry and thermal boundaries are derived from first principles and IPC standards, never estimated by eye:

• Trace Current Capacity (IPC-2152): $I = k \cdot \Delta T^{0.44} \cdot A^{0.725}$, with $k = 0.048$ for external (convective) traces and $k = 0.024$ for internal (conductive-only) traces. A $2.5\text{A}$ DC rail at $\Delta T = 10^\circ\text{C}$ on $1\text{ oz}$ external copper needs $\approx 0.79\text{mm}$ trace width — not a rounded-up guess.
• Controlled Impedance (IPC-2141): Single-ended microstrip $Z_0 = \frac{87}{\sqrt{\varepsilon_r + 1.41}} \ln\left(\frac{5.98h}{0.8w+t}\right)$; edge-coupled differential $Z_{diff} \approx 2Z_0\left(1 - 0.48e^{-0.96 s/h}\right)$. USB is a $90\Omega$ differential target, Ethernet/PCIe is $100\Omega$ — these are not interchangeable, and getting the pair spacing wrong by a fraction of $h$ misses the target by more than manufacturing tolerance forgives.
• DC IR Drop: $R_{trace} = \rho \cdot L / (w \cdot t)$, $V_{drop} = I_{peak} \cdot R_{trace}$. On a $+3.3\text{V}$ rail, $V_{drop}$ must stay $\le 0.10\text{V}$ ($3%$); if it doesn't, widen the trace or move the net to a copper flood — don't just note the number and move on.
• Crosstalk (the 3W rule): center-to-center separation $D \ge 3w$ for parallel traces longer than $15\text{mm}$ keeps mutual coupling below a $70%$ reduction threshold. This is the default spacing assumption for any signal or clock line, not an optional refinement.

---

3. Headless Validation — the Unforgiving Gate

No board may be released to fabrication on visual inspection or LLM self-attestation. This is not a style preference; it's the same lesson this whole ecosystem has paid for repeatedly elsewhere: a clean-looking run is not evidence, a real exit code is.

• ERC: kicad-cli sch erc --exit-code-violations -o reports/erc_report.txt project.kicad_sch — exit 0 means zero errors and zero unhandled warnings, not "looks connected."
• DRC: kicad-cli pcb drc --exit-code-violations --format json -o reports/drc_report.json board.kicad_pcb — must show zero unrouted nets, zero clearance violations, zero broken annular rings, zero thermal spoke disconnections.
• DFM/DFA: benchmark the layout against the target fab house's real capabilities (e.g. JLCPCB standard, PCBWay 4-layer minimum trace/space/via), not a generic "should be fine" assumption.
• A non-zero exit code from any of the above is an immediate gate blockage — the pipeline halts, it does not continue with a caveat noted for later.

---

4. Dedicated MCP Tool Validation Requirement

Before issuing schematic edits, layout changes, or fabrication exports, the agent MUST validate the required MCP servers are actually reachable — not assume they are because a config file lists them:

1. KiCad MCP: validate the kicad-mcp-server responds over stdio (tools/list returns its full tool set — schematic editing, PCB layout, ERC/DRC execution, Gerber/BOM/CPL export) before issuing any node or netlist command.
2. OpenSCAD MCP: validate the openscad-mcp-server responds before requesting parametric model generation, modification, or STL/3MF export for enclosure co-design.
3. Version awareness: a stale or absent kicad-cli (KiCad 8+) or openscad binary on the host changes what's actually possible — check for it and say so plainly, rather than emitting commands that will fail downstream with no clear cause.

---

5. Hardware/Software Co-Design Boundary

• PCB and enclosure design decisions here must stay coordinated with, but not encroach on, the firmware/software skills that consume the resulting pinout and register map — a GPIO reassignment on the board is a breaking change to firmware that already assumed the old pin, and must be flagged as such, not silently absorbed.
• Mechanical (OpenSCAD) and electrical (KiCad) constraints are two halves of the same physical object: a connector placement that satisfies routing but collides with the enclosure wall is not a valid design, even if ERC/DRC both pass.

---

6. Iterative Visual Loop — Render as Complement, Not Gate

A render never replaces ERC/DRC, but every edit must be seen before the next one lands. Generate in small batches, render after each batch, and compare against the reference with a vision-capable model before continuing:

1. Orient first: locate project files (the kicad-project-find helper in the companion module, or raw find for *.kicad_pro, *.kicad_sch, *.kicad_pcb), then report kicad-cli path and version. If kicad-cli is absent, stop and say BLOCKED — do not emit commands that will fail downstream.
2. Small batches: place or edit at most 5–10 components per batch, on a fixed 0.5mm or 1mm placement grid. Never generate a whole schematic or board in one shot.
3. Render after every batch:
   • schematic: kicad-cli sch export svg --output out/ design.kicad_sch
   • board layers: kicad-cli pcb export svg --output out/ board.kicad_pcb
   • board 3D: kicad-cli pcb render --output board-top.png board.kicad_pcb
   • The companion module ships these as the kicad-render, kicad-drc-json, and kicad-erc-json helper scripts.
4. Vision diff: load the fresh render into the vision model alongside the reference (photo, datasheet figure, or schematic from the web). On chaos — overlapping symbols, nets crossing the sheet, decoupling far from pins — fix before the next batch.
5. Machine checks per batch: kicad-cli sch erc and kicad-cli pcb drc with --exit-code-violations. Unconnected-pin warnings after a messy batch are worked off systematically, not batched up for the end.
6. Substrate routing: live board/session edits prefer kicad-python IPC; render, export, DRC/ERC, and fabrication outputs use kicad-cli; deterministic offline file edits use a structured S-expression parser (e.g. kiutils), never hand-rolled regex on .kicad_sch / .kicad_pcb.
7. Evidence report: close every batch with target, commands run, artifact paths, check outputs, and one of DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT.

Shared placement preamble (applies to every schematic/layout batch)

• Schematic flow goes left to right (inputs left, outputs right); VCC points up, GND points down; use global labels or hierarchical sheets instead of dragging dozens of wires across the sheet.
• Every decoupling capacitor sits on the same layer as its IC, within 1.5mm of the power pin, in the sequence rail-via → cap pad → IC pin.
• Reverse-engineering work (rebuilding a board photo or web schematic in KiCad) routes to schematic-reverse-engineering first: identify parts via a parts source, record manufacturer part numbers, verify symbol/footprint visually before use, and never invent pinouts from memory.

Universal Agent Harness Integration

This Godmode rulebook is universally available across the BDB ecosystem, installed alongside the @hybridlabor-api/bdb-hardware-pcb module (KiCad + OpenSCAD MCP servers, 6 companion skills under the engineering-hardware category):

• Claude Code / CLI Agents: loaded during electrical, PCB, and enclosure design sessions.
• Peer skills: code-first-hardware-design, pcb-constraint-definition, pcb-layout-routing-automation, pcb-validation-dfm-signoff, schematic-datasheet-analysis, schematic-reverse-engineering.

Overview

This skill acts as the architectural authority for electrical and PCB design, enforcing IPC-standard physical constraints, iterative visual verification, headless validation gates, and hardware/software co-design boundaries.

When to Use

• Trigger: The user is designing or modifying a schematic, PCB layout, layer stackup, netclass, or an OpenSCAD enclosure meant to house the board — including rebuilding a board photo or web schematic in KiCad.
• Exclude: Do not use for firmware/register-level software running on the board (hand off to godmode-engineering), or for live show-control signal routing in the field (hand off to godmode-eventtech).

Core Process

1. Derive every trace width, impedance target, and clearance from the formulas above or a cited IPC standard — never from a rounded-up guess.
2. Validate KiCad and OpenSCAD MCP servers are actually responsive before issuing edits; confirm kicad-cli path and version.
3. Work in batches of at most 5–10 components on a fixed grid; render after every batch and vision-diff against the reference before continuing (see section 6).
4. Run headless ERC and DRC with --exit-code-violations per batch; treat any non-zero exit as a hard stop.
5. Benchmark the layout against the real target fab house's DFM limits before calling a design release-ready.
6. Cross-check the enclosure (OpenSCAD) against the board outline and connector placements (KiCad) before sign-off.

Common Rationalizations

Rationalization	Reality
"0.25mm default trace width is fine for a power rail."	IPC-2152 current-capacity math, not the CAD tool's default, sets minimum trace width — a 2.5A rail needs ~0.79mm at 1oz copper, not the default.
"The 3D viewer looks correct, so the board is done."	A render complements ERC/DRC, it never replaces them. A clean render with a non-zero ERC/DRC exit code is still BLOCKED; a passing exit code with no render is DONE_WITH_CONCERNS.
"Rendering every few components slows me down; one big generation is faster."	One-shot generation produces overlapping symbols and unconnected pins that cost more to untangle than batches of 5–10 with a render between them.
"USB and Ethernet differential pairs can use the same spacing."	USB targets 90Ω differential, Ethernet/PCIe targets 100Ω — same formula, different required spacing for the same dielectric height.
"The GPIO can be reassigned in layout; firmware can just adapt."	A pin reassignment is a breaking change to any firmware that already assumed the old pinout — it must be flagged to the software side, not silently absorbed.

Red Flags

• Proceeding to layout with unconstrained nets or no defined netclasses.
• Generating a whole schematic or board in one shot with no intermediate render.
• Treating a clean-looking 3D render as equivalent to a passing ERC/DRC exit code.
• Skipping the vision diff against the reference photo or schematic after a batch.
• Skipping DFM benchmarking against the actual target fab house's capabilities.
• Changing a pinout or connector placement without flagging the firmware or enclosure impact.
• Inventing a footprint or pinout from memory when a parts source was available.

Verification

• Every load-bearing trace width/impedance/clearance traces back to a formula or IPC standard, not a default or a guess.
• Work proceeded in batches of at most 5–10 components with a render and vision diff per batch; artifact paths are reported.
• ERC and DRC were run headless with --exit-code-violations, and the actual exit code — not a description of the run — was checked.
• KiCad and OpenSCAD MCP tool availability was validated before issuing edits; kicad-cli path and version are on record.
• DFM limits were checked against the real target fab house, not a generic assumption.
• Any pinout/connector change was cross-checked against firmware assumptions and enclosure geometry.
• Reverse-engineered parts cite a real manufacturer part number and source, not memory.