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. 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 (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 → project-content/datasheets/<part>/<part>.md. Grounds every step below.
2. Symbol create — symbol-creator → .kicad_sym + -metadata.json. Reads the parsed Pin Configuration table.
3. Footprint create — footprint-creator → .kicad_mod + -fp-metadata.json. Reads the symbol's pinDescriptions to backfill symbolPinMap.
4. 3D create — 3d-component-creator → .glb + .step. Resolves from kicad-packages3d (7,200+ STEPs) where possible.
5. chipfit validate — 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:

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 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:

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) unless --no-publish. Idempotent — re-running on a complete part is a no-op.

Per-board:

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.
• 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. 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:

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.

# 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 — the authoritative spec this skill operationalizes.
• PLAN Part 13 — LibView + creators
• PLAN Part 14 — Datasheet pipeline
• PLAN Part 28 — Sibling-tool integrations — adom-chipfit + adom-parts-search.
• Sub-skills (each is the source-of-truth for its step): datasheet-parser, symbol-creator, footprint-creator, 3d-component-creator, adom-chipfit, library-creator, adom-parts-search, 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.