@hybridlabor-api/aos 4.6.0 → 4.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.6.0",
+  "version": "4.6.1",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "engines": {

package/skills/basic/godmode-hardware-pcb/SKILL.md

@@ -57,46 +57,100 @@ Before issuing schematic edits, layout changes, or fabrication exports, the agen
 
 ---
 
+## 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, 5 companion skills under the `engineering-hardware` category):
+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`.
+* **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, headless validation gates, and hardware/software co-design boundaries.
+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.
+- **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.
-3. Run headless ERC and DRC with `--exit-code-violations`; treat any non-zero exit as a hard stop.
-4. Benchmark the layout against the real target fab house's DFM limits before calling a design release-ready.
-5. Cross-check the enclosure (OpenSCAD) against the board outline and connector placements (KiCad) before sign-off.
+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 visual check is not ERC/DRC. Only a headless run with `--exit-code-violations` and a real exit code is evidence. |
+| "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 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.