---
name: aci-board-creator
description: Build a real, manufacturable PCB the proper Adom way — one component at a time through the datasheet → symbol → footprint → 3D → chipfit pipeline, then board-assemble + route + 3D-place via the aci orchestrators. Trigger words — make a board, build a circuit board, design a PCB, RP2040 dev board, ToF carrier, BME680 board, AI-first PCB, aci board creator, aci component, aci board, datasheet-first board, KiCad-from-AI, Adom dev board, Adom carrier board.
---

# aci board creator

Build a real, manufacturable PCB the proper Adom way. **Every component goes through the same six-step pipeline before its symbol lands on a schematic, its footprint on a PCB, or its 3D model in the assembled scene.** The two `aci` orchestrator subcommands — `aci component <mpn>` and `aci board <name>` — exist so the AI can run that flow end-to-end without skipping gates.

This skill operationalizes [PLAN Part 30](../../../adom-circuit/PLAN.md#part-30--per-component-datasheet-first-pipeline-the-proper-way). Read that section first if you want the full rationale; this skill is the executable summary.

## When to use

- User asks to **make a board**, **build a circuit board**, or **design a PCB**.
- User wants a **carrier** combining an MCU + sensor + power + USB.
- User wants **AI-driven board design** ("an AI builds it from a prompt").

## When NOT to use

- User wants a **strict castellated Adom molecule** with the molecule grid + `<MachineContactMedium>` machinery → use [adom-tscircuit-skill](../adom-tscircuit-skill/) (Ray's tooling).
- User wants to **edit an existing board in a GUI** → that's KiCad / Eeschema, not aci.

## The non-negotiable order

For every refdes on the board, in order, before any board-level work runs:

1. **Datasheet parse** — [datasheet-parser](../datasheet-parser/) → `project-content/datasheets/<part>/<part>.md`. Grounds every step below.
2. **Symbol create** — [symbol-creator](../symbol-creator/) → `.kicad_sym` + `-metadata.json`. Reads the parsed Pin Configuration table.
3. **Footprint create** — [footprint-creator](../footprint-creator/) → `.kicad_mod` + `-fp-metadata.json`. Reads the symbol's pinDescriptions to backfill `symbolPinMap`.
4. **3D create** — [3d-component-creator](../3d-component-creator/) → `.glb` + `.step`. Resolves from kicad-packages3d (7,200+ STEPs) where possible.
5. **chipfit validate** — [adom-chipfit](../../../adom-chipfit/) → MANDATORY GATE. Three guardrails (package family + pin count, seat-plane Δz, body-plateau pin-1 registration). On pass, bake → `<part>-3d-pin1.glb`.
6. **pin-pad-mesh map** — `aci lib pin-pad-mesh <part>` → `<part>-map.json` for LibView cross-highlight.

Then board assembly — only after every component is library-complete:

7. `aci sch assemble <board>` → `board/<board>.kicad_sch`
8. `aci pcb layout <board>` → `board/<board>.kicad_pcb` (real footprints, real edge cuts, GND zone)
9. `aci pcb place-3d <board>` → scene-IR with the chipfit-baked GLBs (pin-1 dots visible)
10. `aci build` → DRC, ERC, GLB, SVG, gerbers, BOM, markdown

## ALWAYS open `aci library` first

Before kicking off any per-component work, **open the live dashboard**:

```bash
aci library      # drops a "Component Library" tab into Hydrogen
```

This is non-negotiable. The Part 30 pipeline runs across many minutes per component; without the dashboard the user is blind to progress. The dashboard shows every component's datasheet/symbol/footprint/3D status in real time, with cards popping in as new artifacts land via WebSocket events the orchestrator emits. Skipping this step is what the user calls "totally forgetting about the human experience" — it's the single most common feedback on this flow. See [PLAN Part 30.10](../../../adom-circuit/PLAN.md#3010--aci-library-live-component-library-dashboard) for the full design.

If `adom-cli` isn't reachable (running outside the Adom container), `aci library --no-tab` prints the URL and you paste it into a Hydrogen webview manually. Either way: dashboard first, components second.

## The two orchestrator commands

Per-component:

```bash
aci component <mpn> [--datasheet-url <url>] [--force] [--no-publish]
```

Runs steps 1–6 above. Hard-fails on chipfit. Auto-publishes to wiki on green (per [PLAN Part 20](../../../adom-circuit/PLAN.md#part-20--per-artifact-auto-publish-to-the-adom-wiki-ecosystem-leverage)) unless `--no-publish`. Idempotent — re-running on a complete part is a no-op.

Per-board:

```bash
aci board <name> [--components <ref-list>] [--force]
```

Runs steps 7–10. Verifies every refdes in `board/<name>.toml` has a complete library entry first. Missing entries print `aci component <mpn>` retry hints + exit non-zero.

## Anti-patterns (DON'T)

- **Don't write `.kicad_pcb` from scratch** with hand-inlined pad geometry. The first draft of this skill recommended that approach. It's wrong. Even when kicad-cli accepts the file, every footprint is a stub with guessed pad geometry, the BOM has no datasheet grounding, chipfit is structurally impossible (no `.glb` is produced), and the 3D scene is bbox placeholders. Caught hard during iteration on the RP2040 + VL53L8CX dev board — the file rendered, every claim about it was wrong.
- **Don't reach for tscircuit** when authoring a board for an aci-shipped artifact. tscircuit is a separate, pre-aci tool — useful for tscircuit-compatible projects, but not the Adom-canonical flow per [PLAN Part 22 decision 10](../../../adom-circuit/PLAN.md#part-22--critical-decisions).
- **Don't skip chipfit** because "the dev-harness shows it rendering". The dev-harness has no idea whether the (footprint, GLB) pair actually matches. Chipfit's three guardrails are the only gate that catches wrong-package + wrong-size + wrong-origin errors at design time.
- **Don't author symbols + footprints inline in `.kicad_pcb` / `.kicad_sch`.** They live in `project-content/schematics/{symbols,footprints}/<part>/` per the [canonical tree](../../../adom-circuit/PLAN.md#306--canonical-project-content-directory-tree). Board files only *reference* them.
- **Don't batch fixes.** Per the ralph-loop rule below: every change ralph-loops once. No "I'll fix five things and then look."
- **Don't conflate skill names with CLI binaries.** `datasheet-parser`, `sym`, `fp`, `3d` are *skill* names — they're not standalone binaries on the user's PATH. The actual mechanisms are: HTTP POST to `https://ds-extract-fa4sdo7pnkrl.adom.cloud/extract` (datasheet), AI-authored `.kicad_sym`/`.kicad_mod`/`.glb` files via skill workflows (sym/fp/3D), `service-kicad` for KiCad-side rendering + model fetch, `adom-chipfit` for the validation gate. Probe for the *actual binaries* (`service-kicad`, `adom-chipfit`) — never claim a skill is "missing" without first running `which <name>` against a binary that's supposed to exist. Past incident: 2026-04-26, `aci component`'s probe list rejected every run because it expected four phantom binaries; the user had every real CLI they needed.

## The ralph-loop rule (mandatory at every step)

This skill has one hard rule that supersedes "go fast": **after every artifact you write or modify, you must re-run the next pipeline step and see the result with your own eyes before claiming progress.** Silent claims like "the board looks right" without a fresh screenshot are forbidden.

**This includes the `aci library` dashboard.** Every time the dashboard is meant to update — a new card popping in, a status pill flipping teal, a thumbnail appearing — `adom-cli hydrogen screenshot panel --name "Component Library"` and `Read` the resulting PNG. Verify with your own eyes that:

- The card actually appeared (count cards, match against expected).
- Pills are coloured correctly (datasheet/symbol/footprint/3d done = teal, missing = grey).
- Thumbnails render the actual SVGs (not empty placeholders, not broken-image icons).
- Brand-compliant: monochrome icons (no emoji), `#0d1117` background, Familjen Grotesk + Satoshi fonts loaded (not falling back to Inter/system).

If a screenshot reveals a violation — a teal favicon, an emoji `📦` instead of a custom SVG, a wrong-shade background, the wrong font — fix it BEFORE moving to the next component. Shipping the board with a broken dashboard means the user will catch it later anyway, and rework is more expensive than ralph-loop now.

> **Failure mode that motivates this rule (2026-04-26):** the first cut of the `aci library` dashboard rendered with emoji icons (`📄 🔣 📦 🎲`), `#060809` instead of the brand `#0d1117` background, and a coloured teal tab favicon — all hard violations of `gallia/skills/brand/SKILL.md`. Caught by the user with one screenshot. Lesson: never claim a UI feature done from server-side `curl` 200s. Open it, screenshot it, look at it.

By step:

| Step | Self-test gate (must pass before continuing) |
|---|---|
| Datasheet parsed | `cat project-content/datasheets/<part>/<part>.md \| head -60` shows real pin / electrical sections, not "TBD". Wiki page exists. **Then: `aci library` screenshot — confirm a new card appeared with the correct MPN, manufacturer, and package badge.** |
| Symbol created | `kicad-cli sym export svg <part>.kicad_sym` produces a sane SVG. `Read` the SVG-converted PNG. **Dashboard screenshot — symbol pill is teal, symbol thumbnail renders the SymView SVG, not an empty placeholder.** |
| Footprint created | Same — `kicad-cli fp svg`, `Read` the PNG. Pad numbers visible + correct count. **Dashboard screenshot — footprint pill teal, thumbnail shows the FpView SVG.** |
| 3D created | Open `<part>-3d-viewer.html` and screenshot it (or load the `.glb` in the dev-harness). Body shape recognizable as the part. **Dashboard screenshot — 3d pill teal, click to expand → `<model-viewer>` rotates the GLB.** |
| chipfit ran | `adom-chipfit check` exit code = 0. HUD shows green on all three guardrails. `<part>-3d-pin1.glb` exists. **Dashboard screenshot — card border is teal-glow, ✓ next to MPN, summary count incremented.** |
| Schematic assembled | `kicad-cli sch erc <board>.kicad_sch --format json` violations are the kind you'd predict (unconnected GPIO, etc.), not "missing power input on a power-input pin". |
| PCB laid out | `kicad-cli pcb drc` parses. PCB SVG → PNG → `Read`. Every component placed inside outline. |
| `aci build` ran | Status output line-by-line matches the counts you authored. Dev-harness webview screenshot shows the board with traces, not blank. |

If any check fails, fix the upstream artifact + re-run. Never paper over a failed gate by skipping it. The wrong-path that made this skill necessary started with skipping every gate above and ended with a board that *looked* fine but had 191 hand-guessed pads.

### Ralph-loop the dashboard itself when you build/modify it

If you're MODIFYING `packages/aci-scene/library.html`, the aci-serve `/library` routes, or any `emit_component` call in the orchestrator, you've changed the dashboard surface — that triggers the **app-creator pre-flight** automatically:

1. Re-Read `gallia/skills/brand/SKILL.md` and `gallia/skills/human-ui-patterns/SKILL.md` (mandatory step 0 in app-creator).
2. Make the change.
3. Restart the standalone server (`pkill -f "examples/standalone"` then re-spawn).
4. `adom-cli hydrogen screenshot panel --name "Component Library"`.
5. Read the PNG. Audit against the brand + human-ui-patterns checklists with your own eyes:
   - Are all icons monochrome `#e6edf3` SVGs (no emoji)?
   - Is the bg `#0d1117`, panel `#161b22`, accent `#00b8b1`?
   - Are tooltips body-appended position:fixed z 99999?
   - Any ALL CAPS text leaking through?
   - Cards have frosted-glass + 0.2-alpha teal border?
   - Hero image (a single big identifying preview per card)?
6. Only then claim "dashboard updated."

## Worked example

The user's standing demo target: RP2040 + VL53L8CX (8×8 SPAD ToF) USB-C dev board.

```bash
# 1. Per-component (14 unique parts; passive families collapse).
aci component RP2040
aci component VL53L8CX
aci component AP2112K-3.3
aci component W25Q128JV
aci component ABM8-12.000MHz-B2T  # 12 MHz crystal
aci component USB_C_Receptacle_HRO_TYPE-C-31-M-12
aci component B3U-1000P
aci component LED_Red_0402
aci component R_4.7k_0402
aci component R_27_0402
aci component R_5.1k_0402
aci component R_1k_0402
aci component C_100nF_0402
aci component C_10uF_0805
aci component C_15pF_0402

# 2. Board assembly (one command — runs sch + pcb + route + place-3d + build).
aci board rp2040-vl53l8

# 3. Review.
cat project-content/boards/rp2040-vl53l8/artifacts/review.md
```

End state: a real, manufacturable, datasheet-grounded, chipfit-validated, wiki-published RP2040 + VL53L8CX dev board.

## Cross-references

- [PLAN Part 30 — Per-component datasheet-first pipeline](../../../adom-circuit/PLAN.md#part-30--per-component-datasheet-first-pipeline-the-proper-way) — the authoritative spec this skill operationalizes.
- [PLAN Part 13 — LibView + creators](../../../adom-circuit/PLAN.md#part-13--libview-absorbed-library-viewer--creators)
- [PLAN Part 14 — Datasheet pipeline](../../../adom-circuit/PLAN.md#part-14--datasheet-first-pipeline-runs-before-supplier--grounds-candidate-selection)
- [PLAN Part 28 — Sibling-tool integrations](../../../adom-circuit/PLAN.md#part-28--sibling-tool-integrations-hard-project-requirements) — adom-chipfit + adom-parts-search.
- Sub-skills (each is the source-of-truth for its step): [datasheet-parser](../datasheet-parser/), [symbol-creator](../symbol-creator/), [footprint-creator](../footprint-creator/), [3d-component-creator](../3d-component-creator/), [adom-chipfit](../../../adom-chipfit/), [library-creator](../library-creator/), [adom-parts-search](../adom-parts-search/), [instapcb](../instapcb/).

## How this skill was derived

A previous draft of this skill (committed and immediately superseded) recommended writing `.kicad_pcb` files directly from AI knowledge of IC pinouts + the KiCad s-expression format, generating the files via a Python script. That approach produced a board the user explicitly called "absolutely awful" — every footprint was a stub, no datasheet grounded any pin name, no chipfit ever ran, and the 3D scene was 43 white blocks. **This rewrite documents the proper flow that prevents that failure mode** by making the canonical orchestrator commands the path of least resistance.