kicad-pcb-place

name	kicad-pcb-place
description	Review Circuit Weaver's exhaustive placement proposal and apply approved SVG coordinates to a real electrically annotated KiCad PCB. Use after schematic generation for placement optimization, official-reference review, interactive SVG editing, strict reference reconciliation, and PCB placement handoff. Do not treat review artifacts as fabrication data.

KiCad PCB Placement

Separate the heuristic review proposal from the electrical PCB. Circuit Weaver does not generate a routable board during generate.

1. Generate and inspect the review bundle

circuit-weaver generate "${SPEC_PATH}" --output "${OUTPUT_DIR}"

Read these together:

• assembly_manifest.json: exhaustive physical-part inventory, including generated support passives;
• placement_result.json: proposed coordinates, exact reference reconciliation, quality findings, and fabrication_ready: false;
• placement_review_context.json: board constraints, placement rules, review blockers, targeted research prompts, and official/reference-layout links;
• placement.svg: editable vector proposal; and
• placement_editor.html: interactive drag/review tool that can export SVG.

Stop when placement_result.json is blocked, inventories do not match, or the review gate reports unresolved overlaps, out-of-board parts, constraint violations, missing support parents, missing footprint geometry/dimensions, or unresolved sourcing. Never hide a blocker because the visual layout looks reasonable. Use manufacturer datasheets and reference layouts as authority.

For an alternate optimizer configuration, run:

circuit-weaver optimize-placement "${SPEC_PATH}" \
  --strategy balanced --iterations 5000 --seed 42 \
  --output "${OUTPUT_DIR}/placement.json"
circuit-weaver placement-viewer "${SPEC_PATH}" \
  --output "${OUTPUT_DIR}/placement.html"

2. Apply physical-placement judgment

Review at minimum:

• connectors and controls against mechanical edges and enclosure constraints;
• decoupling/strap/bootstrap parts against their owning IC pins;
• regulator hot loops, switch-node copper, inductors, and current paths against the regulator reference layout;
• crystal loops, RF matching, antenna keepouts, USB/differential entry paths, and sensitive analog feedback;
• component rotations, pin-1 access, courtyard/rework spacing, thermal paths, fiducials, mounting hardware, and assembly-side constraints; and
• all explicit keepouts and placement constraints in the context artifact.

Edit placement.svg with the interactive editor or a standards-compliant vector editor. Preserve each component's data-ref, transform, and layer metadata. Do not add or duplicate assembly references.

3. Create the real electrical PCB

Open the manifest-selected root schematic in KiCad, assign and verify every footprint, and run Update PCB from Schematic. Save a separate, pad-bearing, named-net .kicad_pcb. This is the only valid target for placement, routing, DFM, CPL, and Gerber work.

4. Reconcile and import the SVG

Dry-run first:

circuit-weaver import-placement "${OUTPUT_DIR}/placement.svg" \
  "${ELECTRICAL_PCB}" --output-pcb "${PLACED_PCB}" --dry-run

The default contract requires the SVG and PCB reference inventories to match exactly. Duplicate, unexpected, missing, malformed, or non-finite placements block publication. Apply only after the dry-run is clean:

circuit-weaver import-placement "${OUTPUT_DIR}/placement.svg" \
  "${ELECTRICAL_PCB}" --output-pcb "${PLACED_PCB}"

For a deliberate subset edit, opt in explicitly; unknown SVG references still fail:

circuit-weaver import-placement subset.svg "${ELECTRICAL_PCB}" \
  --output-pcb "${PLACED_PCB}" --allow-partial

The command updates an existing sibling <board-stem>_cpl.csv when present; it does not manufacture a trustworthy CPL from heuristic coordinates.

5. Verify in KiCad

• Reopen the written board without repair prompts.
• Confirm every assembly reference is present once with the intended footprint, side, rotation, and position.
• Run courtyard and full DRC checks.
• Check board-edge, connector, mounting, antenna, thermal, and height constraints against mechanical data.
• Keep support passives adjacent to their owning pins and minimize loop area.
• Route critical nets manually before any optional bulk autorouting.
• Generate CPL/Gerbers only from the reviewed real PCB.

For optional routing, use the repository autoroute skill and produce a validated .ses; never invoke raw Freerouting flags by guesswork.