| name | design-wizard |
| description | Run the explicit, human-in-the-loop Circuit Weaver questionnaire from requirements through a validated design and KiCad handoff. Use only when the user asks for the design-wizard skill, the offline interactive wizard, or a slow step-by-step guided questionnaire. Do not trigger for ordinary new-design requests; use circuit-weaver for automatic end-to-end orchestration.
|
Circuit Design Wizard
An interactive, console-level question-and-answer workflow that hand-holds
users through the full Circuit Weaver pipeline — from vague idea to
quote-ready KiCad outputs.
Disambiguation: This is the step-by-step guided wizard with human-in-the-loop control at every step. For automatic same-agent design orchestration, use $circuit-weaver. For analyzing existing KiCad files, use $kicad.
About this skill: This is the manual, step-by-step guide with human-in-the-loop control. Compare with:
$circuit-weaver skill — Automatic, same-agent orchestration for IC research and design assembly; supports fast vs normal research depth, and uses sonar-pro when configured and compatible, otherwise native web toolingcircuit-weaver design-wizard CLI — Offline interactive wizard (no agents, works standalone, good for learning)
How this skill works: You (the AI agent) drive a multi-step conversation.
At each step you ask the user targeted questions, summarize what you learned,
and then proceed. Never skip a step without telling the user why. Use the
AskUserQuestion-style conversational pattern throughout — present numbered
options, suggest defaults, and let the user confirm or override.
Output Formatting Rules
When presenting CLI command output to the user, follow these rules for clarity:
| Command | Success Output | Error Output |
|---|
validate | "Validation passed: X errors, Y warnings" or full categories if issues exist | List each error with code + message |
apply-patch | "Added [ref] ([topology]) to design.yaml" | List errors from patch validation |
scaffold | Print the generated YAML snippet | Report error with details |
generate | JSON containing artifact_manifest; the manifest contains root_schematic and artifacts | Report generation failure reason |
export-jlcpcb | "JLCPCB export: [bom_rows] rows, [missing_lcsc] need manual lookup" | Report export error |
cost-bom | Print formatted BOM table with totals | List pricing lookup failures |
Never output raw JSON unless the user explicitly requests --json flag. Present human-readable tables and summaries instead.
For validate specifically:
- The current Circuit Weaver CLI emits structured JSON to stdout by default.
- Diagnostics and environment warnings may still appear on stderr.
- Do not add
--json to validate unless the CLI explicitly supports it.
- Do not parse JSON from a stream where stderr has been merged with stdout via
2>&1.
- Read
valid, summary, categories, and metadata from the JSON object.
Long-Running Operations & Timeout Awareness
Do not leave the user without status during long wizard-driven work.
For any step likely to exceed ~2 minutes — research, repeated validation,
generation, simulations, confidence runs, placement, exports, or large log/design
triage — the wizard must:
- Announce the long-running step before starting it.
- Follow up at ~2 minutes with a progress check.
- At ~5 minutes, inspect for issues rather than just waiting:
python -m circuit_weaver log-status <project_dir>python -m circuit_weaver log-view <project_dir>design.logcircuit-weaver.log- recently created or updated artifacts
- Tell the user whether the work is progressing, blocked, or likely stuck.
- Never stay silent for ~30 minutes; keep sending bounded follow-ups and surface blockers.
If resuming after an interrupted run, check status/logs first before retrying the
same expensive command sequence.
Step -1 — Auto-Detection (ALWAYS RUN FIRST)
Before starting, scan the current directory for existing projects:
python -m circuit_weaver discover --json
Exclude bundled samples: Filter out any project whose path contains samples/ or samples\. The samples/ directory contains reference designs shipped with Circuit Weaver — they are NOT user projects. Only show user-created projects.
If user projects are found, present them and ask whether the user wants to:
- Continue/modify an existing project (load its design.yaml and skip to the relevant step)
- Start a fresh design (proceed to Step 0)
If no user projects are found, proceed directly to Step 0.
Step 0 — Welcome & Orientation
Greet the user and explain what the wizard will cover:
Welcome to the Circuit Weaver Design Wizard.
I'll walk you through building a new circuit design from scratch:
Step 1 Requirements & goals
Step 2 IC selection & research
Step 3 BOM assembly & sourcing preferences
Step 4 Schematic generation
Step 5 Design review checkpoint
Step 6 Confidence & simulation check
Step 7 PCB layout guidance & next steps
You can pause, go back, or skip any step. Let's start.
Ask: Do you have an existing YAML spec or are we starting fresh?
- If they have a spec, load it and skip to the step that makes sense.
- If starting fresh, proceed to the experience check below.
0a. Experience Level Calibration
Before diving in, gauge the user's background so you can adjust depth and
pacing throughout the wizard. Ask:
- How would you describe your electronics experience?
- Beginner — I've used dev boards (Arduino, Raspberry Pi) but never
designed a custom PCB
- Intermediate — I've designed 1-3 boards, comfortable reading
schematics, done basic soldering
- Advanced — I regularly design boards, familiar with KiCad, understand
signal integrity and DFM
- Professional EE — Just get me to a YAML spec fast, I know what I'm doing
Adapt behavior based on their answer:
| Level | Wizard behavior |
|---|
| Beginner | Explain every concept briefly as it comes up. Suggest safe defaults aggressively. Flag anything that needs manual EE judgment. Link to the ee skill reference for learning. |
| Intermediate | Explain non-obvious trade-offs. Suggest defaults but invite overrides. Skip basic definitions. |
| Advanced | Lead with options, not explanations. Compact summaries. Start with a compact design brief that covers purpose, power, interfaces, and constraints, then only fill gaps. |
| Professional | Minimize chatter. Do not open with a standalone "What does the circuit do?" prompt. Start with a structured design brief or pasted spec fragment, then ask only missing or high-risk questions. |
Store the experience level and reference it throughout — don't re-ask.
0b. Intake Mode By Experience
Use a different first prompt after calibration:
- Beginner: Start with a plain-language purpose question, then walk through mechanics, interfaces, and power one topic at a time.
- Intermediate: Group 2-3 related requirement questions per turn, with examples and defaults.
- Advanced: Start with one compact design brief covering purpose, input power, rails/current, key interfaces, and mechanical constraints. Follow up only on missing fields.
- Professional: Start with one batch intake prompt or a pasted YAML/spec fragment. Useful format:
purpose; input power; rails/current; interfaces; mechanical constraints; preferred ICs/vendors. Do not immediately ask a generic standalone "what does it do?" question.
Step 1 — Requirements Definition
Goal: Capture enough context to make informed IC and topology decisions.
Use the intake mode that matches the stored experience level:
- Beginner / Intermediate: Ask these questions one group at a time. After each answer, acknowledge and summarize before moving on.
- Advanced / Professional: Treat sections 1a-1d as a completeness checklist, not a fixed question order. Start with a compact brief, then ask follow-ups only for missing, ambiguous, or risky details.
1a. Purpose & Application
For Beginner / Intermediate, ask this directly as the opening requirements question.
For Advanced / Professional, this should usually come from the compact design brief; only re-ask if the brief is vague or incomplete.
Ask:
- What does this circuit/board need to do? (e.g., "battery-powered IoT sensor",
"USB-powered motor controller", "audio amplifier with Bluetooth")
- What is the end-use environment? (consumer, industrial, automotive, hobby)
- Any size or form-factor constraints? (e.g., "fits in a 50x30mm enclosure")
1a-mech. Mechanical & Enclosure Integration
If the user mentioned an enclosure or physical constraints, dig deeper:
- Is there an existing enclosure this board must fit inside? (dimensions, mounting pattern)
- Any fixed connector positions? (e.g., "USB port must be on the left edge")
- Height restrictions? (component height limit from enclosure lid)
- Mounting method? (screw holes, snap-fit tabs, standoffs, adhesive)
- Board-to-board stacking? (if part of a multi-board system)
- Cable routing constraints? (which edges have cable egress)
For beginners: explain that connector placement and mounting holes are best
decided now — moving them after PCB layout is expensive rework.
Record all mechanical constraints — they feed directly into Step 7 (PCB layout)
for board outline and keep-out zone generation.
1a-rf. Specialized RF / Microwave Intake
If the design brief mentions RF/microwave work beyond ordinary module-level
wireless integration (for example: radar, phased array, beamforming, Ku-band,
mmWave, SDR front-end, custom LNA/mixer/filter chain), switch to this
specialized intake instead of treating it like a generic embedded board.
Ask:
- What frequency band and bandwidth are you targeting?
- What is the system architecture? (direct conversion, superhet, FMCW radar, phased array, IF sampling, etc.)
- How many channels or array elements are involved?
- What are the transmit / receive power, gain, NF, dynamic range, and phase-coherence requirements?
- What reference clock / LO architecture is required?
- What transmission-line / controlled-impedance constraints already exist?
- What parts of the chain are fixed versus still open for selection?
Then state clearly:
- Circuit Weaver can still help with architecture capture, block partitioning,
BOM research, custom block scaffolding, review, and simulation planning.
- Final microwave layout closure, EM behavior, antenna performance, shielding,
and calibration remain manual engineering tasks.
1b. Features & Interfaces
Ask:
- What external interfaces are needed? (USB, SPI, I2C, UART, Ethernet, WiFi,
BLE, CAN, analog I/O, GPIO, display, buttons, LEDs, etc.)
- What sensors or actuators? (temperature, pressure, IMU, motor, relay, etc.)
- How many of each? Any specific models or preferences?
1c. Power & Electrical Requirements
Ask:
- What is the primary power source? (USB 5V, battery type/voltage, wall adapter,
PoE, solar, etc.)
- What voltage rails do you need? (3.3V, 1.8V, 5V, 12V, etc.)
- Estimated current budget per rail? (rough is fine — "under 500mA" works)
- Any battery charging requirements?
1c-validate. Power Budget Sanity Check
Do this immediately after collecting power requirements. Don't wait until
IC selection — catch impossible power trees now.
Using the ee skill reference formulas, run a quick power budget:
=== Power Budget Estimate ===
Source: USB 5V (500mA USB 2.0 or 3A USB-C PD)
Rail Voltage Est. Current Power
---------------------------------------------
VDD_3P3 3.3V 350 mA 1.16 W
VDD_1P8 1.8V 50 mA 0.09 W
VMOT 12.0V 800 mA 9.60 W
---------------------------------------------
Total load 10.85 W
Source capacity (USB 5V @ 3A) 15.00 W
Headroom 4.15 W (27%) OK
Conversion losses (~85% buck efficiency):
Total input draw ≈ 12.76 W → 2.55 A @ 5V OK (under 3A)
Flag problems early:
- Total load exceeds source capacity → stop and renegotiate requirements
- Headroom < 15% → warn about thermal margins
- Battery runtime math: capacity_mAh / avg_draw_mA = runtime_hours
- If battery-powered, estimate runtime and ask if it's acceptable
For beginners: explain why we check this now ("if the power math doesn't add
up, no amount of clever IC selection will fix it").
1d. Goals & Constraints
Ask:
- Target unit cost at volume? (or "doesn't matter, it's a prototype")
- Target production volume? (1-off prototype, 10 units, 1000+, etc.)
- Timeline or deadline?
- Regulatory or certification needs? (FCC, CE, UL, automotive, medical, etc.)
- Any must-use or must-avoid components/vendors?
1e. Comparable Products or Reference Designs
Ask:
- Are there existing products, dev boards, or reference designs that do
something similar? (e.g., "like an Adafruit Feather but with CAN bus")
- Any open-source hardware projects to draw from?
- Datasheets or app notes you've already found?
Summary Gate
After collecting all answers, present a structured Requirements Summary:
=== Requirements Summary ===
Project: [name]
Application: [description]
Environment: [consumer/industrial/etc.]
Form factor: [constraints]
Interfaces: [list]
Sensors: [list]
Actuators: [list]
Power source: [description]
Voltage rails: [list with estimated currents]
Battery: [charging? type?]
Volume: [quantity]
Budget: [target cost or "prototype"]
Certifications: [list or "none"]
Comparables: [list]
Ask: Does this look right? Anything to add or change?
Iterate until the user confirms.
Summary-risk. Complexity & Risk Flags
After the user confirms the requirements summary, automatically scan for
design areas that are harder than average. Present any flags found:
=== Complexity Flags ===
⚠ HIGH-SPEED DIFFERENTIAL: USB 3.x or Ethernet requires controlled-
impedance routing and a 4-layer stackup. This adds PCB cost and
requires careful layout — it can't be fully autorouted.
⚠ RF / ANTENNA: WiFi/BLE with a PCB antenna or external antenna
needs RF matching and ground plane management. Expect manual
tuning and possibly a VNA for validation.
⚠ MICROWAVE / PHASED ARRAY / RADAR: Ku-band and other microwave
systems are still in scope, but they are not turnkey-generated
designs. Expect a research-first workflow, explicit RF chain
blocks, transmission-line constraints, custom simulation work,
and manual layout/validation closure.
⚠ MIXED-SIGNAL: Combining analog sensors with digital/switching
circuits requires careful ground partitioning and power filtering.
Layout matters more than schematic here.
⚠ HIGH CURRENT (>2A per rail): Power traces need width calculations,
thermal relief, and possibly copper pours. May need thermal vias
under regulator pads.
⚠ BATTERY + CHARGING: Adds a charging IC, protection circuit, and
fuel gauge considerations. Safety implications for Li-ion/LiPo.
✓ No certification flags for hobby/prototype use.
Only show flags that apply. For each flag:
- Explain what it means in plain language (especially for beginners)
- State whether Circuit Weaver can handle it automatically or if it needs
manual EE work
- Ask if the user wants to proceed, simplify, or get more details
For Professional users in specialized domains, default to "proceed with
custom architecture mode" instead of framing the domain as unsupported.
If no flags apply, say so: "This design is straightforward — no special
complexity concerns."
Summary-test. Test & Debug Strategy
Before moving to IC selection, ask about testability. Many users forget this
and regret it when the board arrives and they can't debug it.
Ask:
- Debug interface: Do you need SWD/JTAG header for MCU debugging?
(Suggest: yes, even for prototypes — it's a $0.20 header that saves hours)
- Serial console: UART header for debug logging?
(Suggest: yes, expose TX/RX/GND on a 3-pin header)
- Power LEDs: LED on each voltage rail to confirm power is up?
(Suggest: yes for prototypes, DNP for production)
- Test points: Exposed pads on critical nets for oscilloscope probing?
(Suggest: at minimum on power rails and clock signals)
- Spare GPIO: Break out 2-4 unused MCU pins to a header for rev2 features?
(Suggest: yes — costs nothing and enables future flexibility)
For beginners: explain why each matters. "An LED on your 3.3V rail costs
$0.02 and immediately tells you if power is working when you first plug in."
For professionals: present as a compact checklist, defaults all yes, let them
trim.
Add confirmed debug/test features to the requirements summary.
Step 2 — IC Selection & Research
Goal: Use AI reasoning to identify the primary ICs, then kick off
research to validate and enrich selections before BOM construction.
2a. AI-Driven IC Reasoning
Based on the requirements summary, reason through the design and propose
primary ICs for each functional block:
- MCU / processor — Match peripherals, memory, package, ecosystem
- Power management — Buck, boost, LDO, charger ICs based on rails and source
- Communication ICs — WiFi/BLE modules, Ethernet PHY, CAN transceivers, etc.
- Sensor ICs — Match specifications to requirements
- Driver ICs — Motor drivers, LED drivers, display drivers
- Protection — ESD, overcurrent, reverse polarity
For MCUs specifically, also consider the firmware & software ecosystem:
- Toolchain: Arduino, ESP-IDF, STM32CubeIDE, Zephyr RTOS, PlatformIO, etc.
- SDK maturity: Is the SDK well-documented? Active community? Stable releases?
- Debugger support: SWD/JTAG support, compatible probes (J-Link, ST-Link, etc.)
- RTOS compatibility: FreeRTOS, Zephyr, NuttX — if real-time is needed
- Language support: C/C++, MicroPython, Rust, CircuitPython
- OTA update capability: If the device needs field updates
Ask the user: What's your firmware development preference? (Arduino IDE,
PlatformIO, vendor SDK, or "whatever is easiest"). Factor this into MCU choice —
a technically superior MCU with a bad SDK is worse than a modest one with
great tooling.
For each proposed IC, explain why it was chosen:
=== Proposed IC Selection ===
MCU: ESP32-S3-WROOM-1 (N16R8)
Why: WiFi + BLE built-in, sufficient GPIO for your sensor array,
large community, good availability, JLCPCB basic part
Power: TPS563200 (5V→3.3V buck, 3A)
Why: Wide input range covers USB 5V with margin, high efficiency
at your current draw, SOT-23-6 keeps it small
Sensor: BME280
Why: Temp + humidity + pressure in one package, I2C, matches your
environmental monitoring requirement
[... etc for each block ...]
Ask: Do these selections look reasonable? Want me to research alternatives
for any of them?
2b. Parallel Research Jobs
For each confirmed IC, kick off research to gather:
- Datasheet review — Verify pinout, electrical specs, recommended circuit
- Application circuit — Extract reference design from datasheet
- Availability check — Stock at DigiKey, Mouser, LCSC (use distributor skills)
- Alternative parts — At least one pin-compatible or functional alternative
- Known issues — Errata, common design pitfalls, community reports
Use the digikey, mouser, and lcsc skills to search for parts and check
stock. Use the ee skill for any calculations (power budgets, filter values,
thermal checks).
Present research results per IC:
=== Research: ESP32-S3-WROOM-1 ===
Sourcing:
DigiKey: In stock (2,400+ units), $3.15 @ qty 1
Mouser: In stock (800+ units), $3.22 @ qty 1
LCSC: In stock (JLCPCB basic), $2.85 @ qty 1
Reference circuit: See datasheet Section 4.2
- Requires 3.3V rail, 500mA peak during TX
- 10uF + 100nF decoupling on VDD
- EN pin needs RC delay (10k + 1uF)
- USB D+/D- need 22R series resistors
Alternatives:
- ESP32-C3-MINI-1: Cheaper, single-core, fewer GPIO (if you can trim pins)
- STM32WB55: ST ecosystem, better low-power, no WiFi (BLE only)
Known issues:
- GPIO 12 must be LOW at boot (strapping pin)
- ADC2 unavailable when WiFi active
2b-thermal. Thermal Checks on Power Components
For every power IC (buck, boost, LDO, charger, motor driver), run a thermal
sanity check using the ee skill formulas:
=== Thermal Check: TPS563200 (3.3V buck) ===
Input: 5V @ ~380mA (estimated input draw)
Output: 3.3V @ 350mA
Efficiency: ~88% (from datasheet at this load point)
Power dissipated: Pin - Pout = 1.90W - 1.16W = 0.74W
Package: SOT-23-6 (θJA ≈ 150°C/W without copper pour)
Junction temp: 25°C + 0.74W × 150°C/W = 136°C ← OVER LIMIT (125°C max)
With recommended copper pour (θJA ≈ 55°C/W):
Junction temp: 25°C + 0.74W × 55°C/W = 65.7°C ← OK (59°C margin)
→ Copper pour under this IC is MANDATORY. Flag for PCB layout.
Flag thermal problems immediately:
- Tj > 100°C → warn, suggest copper pour or heatsink requirement
- Tj > Tj_max → stop, suggest a different package or IC
- LDO with large Vin-Vout drop at high current → calculate Pdiss and flag
- Motor drivers → check Rds(on) × I² heat at operating current
For beginners: explain that "the chip has to get rid of the power it wastes as
heat, and small packages can only dump so much heat into the board."
2b-leadtime. Lead Time & Availability Reality Check
After gathering stock data for all ICs, present a consolidated availability
summary:
=== Supply Chain Summary ===
Part DigiKey Mouser LCSC Lead Time
--------------------------------------------------------------------
ESP32-S3-WROOM-1 2,400+ 800+ In stock Immediate
TPS563200 5,200+ 3,100+ In stock Immediate
BME280 150 0 In stock ⚠ Low stock
DRV8833 0 0 42 units ⚠ 16 weeks
⚠ DRV8833: Out of stock at major distributors. Lead time 16+ weeks.
Options:
1. Use alternative: TB6612FNG (pin-compatible, in stock)
2. Order from LCSC now (42 remaining)
3. Wait for restock (check distributor ETAs)
⚠ BME280: Low stock at DigiKey (150 units). Order soon or identify
alternative (BMP280 if humidity not needed, SHT40 for better accuracy).
Flag any part with:
- Zero stock at all checked distributors → blocker, must find alternative
- Stock < 2× order quantity → warn about ordering soon
- Lead time > 4 weeks → warn, ask if timeline allows it
- NRND (Not Recommended for New Design) or EOL status → blocker
Ask after presenting all research: Any ICs you want to swap or dig deeper on?
2c. Generation Coverage Check
Check which of the confirmed blocks map cleanly onto existing Circuit Weaver
data-driven topology/builder coverage and which will need explicit custom block
definition.
Common well-covered areas include:
- power conversion and regulation
- USB / common digital interfaces
- common mixed-signal support circuits
- standard driver, protection, sensing, and conditioning blocks
Report which blocks have direct coverage and which will need custom definition:
Direct coverage:
[x] Power: buck regulator path
[x] Power: ldo regulator path
[x] Sensor conditioning path
[x] USB interface path
Custom blocks needed:
[ ] MCU: ESP32-S3 — will use component_db + manual pin mapping
[ ] Custom analog frontend — explicit custom block needed
Important: "no direct coverage" does not mean "unsupported." It means
the design should continue using explicit custom blocks, manual interface
definitions, and targeted EE/simulation review instead of turnkey generation.
For specialized RF/microwave designs, continue with:
- RF chain blocks captured explicitly (LNA, mixer, LO, PA, filter, antenna path)
- Interface/net constraints recorded explicitly (impedance, diff-pair, isolation, shielding)
- Custom sourcing/research for the active RF parts and passives
- Manual layout and validation expectations stated up front
For professional users, present this as a capability boundary:
"supported with custom engineering flow," not "outside scope."
Step 3 — BOM Assembly & Sourcing Preferences
Goal: Build the BOM with user input on manufacturing, vendors, and budget.
3a. Manufacturing Intent
Ask:
3b. Vendor & Sourcing Preferences
Ask:
3c. Real Spec Assembly (Scaffold + Apply-Patch Workflow)
Build the YAML spec incrementally using the CLI commands:
Step 1: Scaffold the first block
Identify the primary power source and scaffold the first IC.
Note: the current CLI still uses the legacy flag name --template for topology
selection. Treat that as compatibility syntax, not the workflow model.
circuit-weaver scaffold --template buck --ref U1 --output design.yaml
This creates a minimal spec with the first power block. Present the output to the user and confirm it looks reasonable before proceeding.
Step 2: Add blocks iteratively with apply-patch
For each additional IC, create a patch JSON file and apply it.
Give every architectural block a stable unique id and a descriptive
functional section. Use separate sections for each major power stage,
processing, sensing/analog, communications, external I/O, UI, and debug/test.
Generation preserves those explicit sections as professional sub-sheets even
for small designs and keeps support passives with their owning block.
Note: the patch schema still uses legacy internal field names like
kind: "template" and template_type. In workflow terms, think of these as
"generated block" and "topology name".
{
"upsert_blocks": [
{
"id": "U2_ldo",
"section": "power",
"kind": "template",
"template_type": "ldo",
"ref": "U2",
"params": {
"vin": 3.3,
"vout": 1.8,
"vin_net": "VDD_3P3",
"rail_name": "VDD_1P8"
}
}
]
}
circuit-weaver apply-patch design.yaml patch_u2_ldo.json --output design.yaml
For each new block, present ONLY the newly-added components (from diff.added_blocks). Do NOT show the full updated spec — it's too verbose.
=== Block Added: U2 LDO ===
U2 TLV75533 3.3V → 1.8V LDO, 500mA
Bypass caps: C2, C3 (100nF on input/output)
Enable pulled to VDD_3P3
Ready for next block? (or 'done' to move to validation)
Repeat this for each IC until all blocks are added.
Step 3: Cost Estimation (Optional)
Once all blocks are added, generate an estimated BOM cost at target quantities:
circuit-weaver cost-bom design.yaml --qty 1,10,100
Present the pricing summary (prices by quantity break), noting any parts without LCSC codes that need manual sourcing.
Step 4 — Schematic Generation
Goal: Generate the KiCad schematic and set expectations for what comes out.
4a. Pre-Generation Review
Before generating, confirm the YAML spec with the user:
I'm about to generate the KiCad schematic from this spec:
Project: [name]
Sheets: [estimated count] (1 top-level + N sub-sheets)
Components: [count] active + [count] passive
Power tree: [description]
Buses: [I2C, SPI, UART, etc.]
Output directory: [path]
Ask: Ready to generate? Any last changes?
4b. Generate & Validate
Run the generation pipeline:
circuit-weaver generate "${SPEC_PATH}" --output "${OUTPUT_DIR}"
circuit-weaver validate "${SPEC_PATH}"
circuit-weaver generate "${SPEC_PATH}" --output "${OUTPUT_DIR}" --require-kicad
Report results:
=== Generation Results ===
Files created:
[x] project.kicad_sch (top-level schematic)
[x] power.kicad_sch (power sheet)
[x] digital.kicad_sch (MCU + peripherals)
[x] project_report.md (design report)
[x] assembly_manifest.json (physical-part inventory)
[x] placement_result.json (review status and blockers)
[x] placement_review_context.json (official/reference context)
[x] placement.svg + placement_editor.html (review-only proposal)
Validation:
Structural: PASS (12/12 checks)
Electrical: PASS (8/8 checks)
Implementation: PASS (6/6 checks) [or WARN with details]
Presentation: PASS (4/4 checks)
Internal validation is not real KiCad verification. Read
artifact_manifest.json and claim release-quality generation only when it says
kicad_verified: true and verification_status: verified.
4c. What's Automated vs. Manual
Be explicit about what the user still needs to do. This is critical for
setting expectations:
=== What's Done vs. What You'll Finish ===
DONE (generated automatically):
- Symbol placement and declared pin mappings for review
- Power connections and decoupling capacitors
- Net labels for all buses (I2C, SPI, UART, etc.)
- Hierarchical sheet structure
- Support passives (pull-ups, bypass caps, RC filters)
YOU'LL FINISH IN KICAD (~10-20% of the schematic work):
- Review net label names for clarity
- Adjust component positions for readability
- Add any project-specific notes or annotations
- Verify pin assignments match your physical layout intent
- Run ERC and resolve any remaining warnings
- Fine-tune sheet aesthetics (alignment, spacing)
Open the schematic:
Open `artifact_manifest.json`, then open its `root_schematic` path in KiCad.
Step 5 — Design Review Checkpoint
Goal: Catch expensive mistakes before committing to PCB layout. This is
the cheapest place to find problems — a schematic fix costs minutes, a PCB
respin costs weeks and dollars.
5a. Automated Review
Run the generated schematic through the validation tools:
circuit-weaver validate "${SPEC_PATH}" --enhanced --verbose
circuit-weaver confidence "${SPEC_PATH}" --run-sims -o "${OUTPUT_DIR}/confidence_report.html"
Confidence Report: The confidence command aggregates all available checks
into a single 0-100 score with a readiness classification (ready_for_fab /
needs_review / not_ready). Present the terminal output to the user. If an HTML
output path was given, mention the HTML file for detailed review in a browser.
Parse the validation report (categories level=error or level=warning) and present a structured review summary:
=== Design Review ===
Power Tree:
[x] All rails have valid sources
[x] Decoupling caps on every IC power pin
[x] Enable pins properly connected
[ ] ⚠ No bulk capacitor on 3.3V rail — recommend 10-47µF near source
Connectivity:
[x] All MCU peripheral pins connected to intended targets
[x] I2C bus has pull-ups (4.7kΩ to 3.3V)
[x] SPI bus CS lines properly assigned
[ ] ⚠ UART TX/RX — verify TX→RX crossover (pin names can be ambiguous)
Protection:
[x] USB VBUS has overcurrent protection
[ ] ⚠ No ESD protection on USB data lines — recommend TVS diode
[ ] ⚠ No reverse polarity protection on power input
Debug & Test:
[x] SWD header connected
[x] UART debug header connected
[x] Power LEDs on all rails
5b. Human Review Guidance
Tell the user what to check manually in KiCad:
=== Manual Review Checklist ===
Open the schematic in KiCad and verify:
[ ] Pin assignments match your physical layout intent
(e.g., I2C on pins closest to the sensor)
[ ] Net names are meaningful (not just NET_001)
[ ] No unintended connections (zoom in on dense areas)
[ ] All ICs have correct pin-1 orientation markers
[ ] Power flags on all power nets (avoids ERC warnings)
[ ] Footprint assignments are correct for your sourced parts
(SOT-23-3 vs SOT-23-5 is a common mistake)
If this is for a real product, consider having another engineer
review the schematic before proceeding to layout.
5c. Review Gate
Ask: Have you reviewed the schematic and are you satisfied with it?
- If issues found → help fix them, re-generate if needed, re-validate
- If satisfied → proceed to confidence check (Step 6)
- If they want peer review → suggest they share the .kicad_sch and come back
Do not let beginners skip this step. For advanced users, a quick "looks good,
moving on" is fine.
Step 6 — Confidence & Simulation Check
Goal: Run all available checks in one pass to produce a single readiness
score before the user invests time in PCB layout.
6a. Run Confidence Dashboard
This step runs automatically after the review gate passes. Do not skip it.
circuit-weaver confidence "${SPEC_PATH}" --run-sims -o "${OUTPUT_DIR}/confidence_report.html"
circuit-weaver validate "${SPEC_PATH}" --enhanced --verbose
The confidence dashboard aggregates:
- Electrical validation — all 14 checks (decoupling, enable pins, power budget, thermal, SI)
- Circuit simulation — power supply transient/AC analysis via ngspice
- Thermal analysis — junction temperature vs Tj_max for all power ICs
- Cross-reference audit — spec vs schematic, BOM completeness, duplicate refs
- ERC — KiCad electrical rule check (if KiCad CLI installed)
6b. Present Results
Show the confidence score and readiness to the user:
Score: 82/100 (B)
Readiness: NEEDS REVIEW
Sections:
[OK] Electrical Validation 90/100 (A)
[OK] Simulation 75/100 (C)
[OK] Thermal Analysis 100/100 (A)
[--] Signal Integrity N/A (skipped)
[--] Manufacturing (DFM) N/A (skipped)
[OK] Cross-Reference Audit 85/100 (B)
[--] ERC/DRC N/A (skipped)
Interpretation guidance:
- ready_for_fab (80+, no blockers): "Your design looks solid. Proceed to PCB layout."
- needs_review (60-80): "Design works but has issues worth addressing first."
- not_ready (<60 or blockers): "Fix the blockers before investing in PCB layout."
For beginners: explain what each section means and why the score matters.
"This score tells you how confident we are that the circuit will work correctly
when you build it. A higher score means fewer surprises when the board arrives."
6c. Address Action Items
If blockers or high-priority action items exist, walk through each one:
- Present the action item with context
- Offer to fix it (loop back to the relevant step: Step 2 for IC changes, Step 3 for passives)
- Re-run confidence after fixes to verify improvement
Ask: Want to address any of these items before moving to PCB layout?
If the user wants to proceed despite issues, note the decision in the log.
Log: [Step 6] Confidence: {score}/100 ({grade}), readiness: {readiness}
Step 7 — PCB Layout Guidance & Next Steps
Goal: Guide the user into the PCB phase with clear expectations about
what can be scripted vs. what requires manual KiCad work.
7a. PCB Kickoff — Automated Layout Assistance
generate emits an exhaustive review-only bundle:
placement_result.json, placement_review_context.json, placement.svg, and
placement_editor.html. It does not emit an electrical PCB. Read the result
and context first, surface every blocker, and use linked manufacturer
datasheets/reference layouts as the placement authority.
circuit-weaver optimize-placement "${SPEC_PATH}" -o "${OUTPUT_DIR}/placement.json"
circuit-weaver placement-viewer "${SPEC_PATH}" -o "${OUTPUT_DIR}/placement.html"
Present results:
=== PCB Layout Preparation ===
Automated steps completed:
[x] Placement optimized (thermal + SI + DFM scoring)
[x] Review status: output/placement_result.json
[x] Official/reference context: output/placement_review_context.json
[x] Interactive editor: output/placement_editor.html
[x] Editable vector: output/placement.svg
Open placement_editor.html to review or drag the exact assembly inventory.
The placement files always remain `fabrication_ready: false`.
WHAT YOU'LL DO IN KICAD:
- Board outline and edge cuts
- Fine-tune placement for routing convenience
- Route traces (power first, then signals)
- Ground/power planes and zone fills
- Silkscreen labels and polarity markers
WHAT WE CAN HELP WITH:
- Trace width suggestions (use `$ee`)
- Layer stackup recommendation (2-layer vs 4-layer)
- Autorouting of non-critical nets after an electrical PCB exists (see 7c)
If mechanical constraints were captured in Step 1a-mech, incorporate them now:
- Board outline matches enclosure dimensions
- Mounting holes at specified positions
- Connectors placed on specified edges
- Height-restricted zones marked as keep-outs
7b. Create the Electrical PCB
Open the manifest returned by generate, then open its root_schematic, assign
and verify footprints, and run Update PCB from Schematic in KiCad. Save the resulting
electrically annotated .kicad_pcb under a user-confirmed path. Record that path
as ${ELECTRICAL_PCB} for routing, DFM, and fabrication steps.
Dry-run the edited SVG against the real board before applying it. Exact
SVG↔PCB reference matching is the default; use --allow-partial only for an
explicit subset update.
circuit-weaver import-placement "${OUTPUT_DIR}/placement.svg" \
"${ELECTRICAL_PCB}" -o "${OUTPUT_DIR}/placed.kicad_pcb" --dry-run
circuit-weaver import-placement "${OUTPUT_DIR}/placement.svg" \
"${ELECTRICAL_PCB}" -o "${OUTPUT_DIR}/placed.kicad_pcb"
7c. Routing Guidance
Based on the design:
- Identify critical nets that need manual routing (power, USB, high-speed)
- Suggest trace widths for power vs signal nets (use
ee skill calculations)
- Recommend layer stackup if 4-layer
- Identify candidates for autorouting (non-critical signal nets)
Autorouting with Freerouting (Optional)
If the user has Freerouting installed, offer to auto-route only a real
pad-bearing named-net PCB or a user-exported Specctra DSN. Output is a validated
Specctra session, not a routed PCB:
circuit-weaver autoroute "${ELECTRICAL_PCB}" -o "${OUTPUT_DIR}/routed.ses"
If kicad-cli does not advertise Specctra export, export a DSN in KiCad PCB
Editor and route that file. Treat exit code 2 / status: partial as incomplete.
Import the SES in KiCad and run DRC. Route power, switching loops,
differential/high-speed pairs, RF, clocks, and crystals manually.
7d. DFM Check (Recommended Before Ordering)
Run DFM checks against the target manufacturer:
circuit-weaver check-dfm "${ELECTRICAL_PCB}"
If DFM issues are found, present them and offer to fix (adjust trace widths,
via sizes, clearances).
Optional Repository Templates
A source checkout can contain optional project-skills/ templates for advanced
placement, autorouting, pin-map, hierarchy, and custom-generation work. These
templates are not installed from PyPI. Read a template only after verifying its
SKILL.md exists in the current repository; otherwise continue with the built-in
CLI and KiCad steps in this wizard.
7e. Manufacturing Checklist
Based on Step 3 manufacturer choice, present the final checklist:
=== Pre-Order Checklist ===
[ ] Confidence score >= 80 (circuit-weaver confidence design.yaml --run-sims)
[ ] DFM check clean (circuit-weaver check-dfm board.kicad_pcb)
[ ] ERC clean in KiCad
[ ] DRC clean in KiCad
[ ] BOM exported (use /bom skill)
[ ] Gerbers exported and visually inspected
[ ] CPL (component placement list) generated for assembly
[ ] Design rules match manufacturer minimums
[ ] Silkscreen readable, polarity marked
[ ] Test points accessible
[ ] Board dimensions verified against enclosure
Reference the jlcpcb or pcbway skill for manufacturer-specific DFM rules.
7f. Revision Planning & Future-Proofing
Before the user commits to fabrication, help them think about the next revision.
This is especially valuable for beginners who don't realize rev1 is almost never
the final board.
=== Revision Planning ===
This is Rev 1 of your design. Here's how to set yourself up for Rev 2:
Version tracking:
- Add "Rev 1.0" and the date to the silkscreen
- Tag this point in git: git tag -a v1.0 -m "Rev 1.0 sent to fab"
- Keep your YAML spec, generated files, and BOM CSV committed
Built-in flexibility (already in your design):
[x] Spare GPIO broken out to header (Step 1 test strategy)
[x] Debug UART accessible
[x] SWD header for firmware development
For Rev 2, common changes to plan for:
- Component swaps based on testing results
- Layout tweaks for signal integrity or thermal issues
- Additional features from your "nice to have" list
- Cost optimization (swap extended JLCPCB parts for basic ones)
For future revisions, keep your YAML specs in git so you can diff changes.
Ask: Ready to order, or do you want to add any future-proofing features
before we finalize?
Conversation Style Guide
Throughout the wizard, follow these principles:
-
One topic at a time. Don't ask 10 questions in one message. Group 2-3
related questions, wait for answers, acknowledge, then move on.
-
Suggest sensible defaults. "For a prototype, I'd suggest 0603 passives
and HASL finish — does that work?" is better than "what passive size and
surface finish do you want?"
-
Show your reasoning. When recommending an IC or topology, briefly
explain why. Users learn from this and catch bad assumptions early.
-
Summarize before proceeding. At each step boundary, show what you
captured and ask for confirmation before moving to the next step.
-
Save progress. After Steps 1 and 2, offer to save a draft YAML spec
so the user doesn't lose work if the session ends. After Step 3, the
spec should be saved to disk.
-
Be honest about limitations, but distinguish automation limits from scope.
If the engine lacks pre-modeled builder coverage for something unusual, do not
reject the whole design space. Instead say what Circuit Weaver can still do
(requirements capture, architecture, custom block scaffolding, sourcing,
validation planning, simulation setup, review) and what still needs manual
engineering closure.
Related Skills
| Skill | Used in step | Purpose |
|---|
ee | 1, 2, 7 | Calculations: power budget, filter values, thermal, trace widths |
digikey | 2, 3 | Part search, stock check, datasheets |
mouser | 2, 3 | Alternative sourcing |
lcsc | 2, 3 | Production sourcing, JLCPCB parts |
bom | 3 | BOM export and order file generation |
kicad | 4, 5 | Schematic analysis, validation, and design review |
jlcpcb | 3, 7 | DFM rules, assembly ordering |
pcbway | 3, 7 | Alternative fab DFM rules |
Resuming a Wizard Session
If the user returns and says "continue my design" or "where were we":
-
Reconcile durable state before inferring progress from filenames:
circuit-weaver status "${PROJECT_DIR}"
circuit-weaver resume "${PROJECT_DIR}"
-
Treat resume as a plan only; it never executes the next action.
-
Use its current_phase, reconciliation findings, and next_actions. If no
manifest exists, fall back to saved YAML completeness:
- Has requirements but no ICs → resume at Step 2
- Has ICs but no sourcing data → resume at Step 3
- Has full spec but no generated files → resume at Step 4
- Has generated schematics but no review → resume at Step 5
- Has reviewed schematics → resume at Step 6 (confidence check)
- Has confidence report → resume at Step 7 (PCB layout)
-
Summarize the current state and confirm with the user before proceeding.
