Circuit Weaver — Main Entry Skill

The master entry point for circuit design workflows. This skill orchestrates:

1. New design creation (wizard + requirements + research + IC selection + BOM + passive generation + schematic)
2. Existing design loading and review

This skill is platform-aware:

• Claude Code: Uses native interactive buttons (AskUserQuestion tool) for all choices
• Codex/OpenCode: Uses conversational prompting with numbered options
• CLI: Uses py -m circuit_weaver design-wizard with input() for terminal mode

All platforms follow the same design flow — just different UI for user input.

Domain Routing

Do not treat the absence of built-in topology coverage as evidence that a design domain is unsupported.

Use these routing rules:

• Standard covered designs: follow the normal wizard flow.
• Specialized domains such as RF/microwave, phased arrays, Ku-band radar, mmWave, precision analog instrumentation, unusual isolation, or mixed-signal boards with custom front ends: still proceed with Circuit Weaver, but switch to a research-first custom architecture path.

In the research-first custom architecture path:

• Use ee for first-principles analysis and domain-specific calculations.
• Use python -m circuit_weaver simulate for supported power, signal, and thermal analysis after the spec exists; document external RF/S-parameter analysis separately.
• Use kicad for review and downstream schematic/PCB analysis.
• Capture the system as custom blocks + interfaces + explicit constraints even when no turnkey builder/topology coverage exists.
• Be precise about what is automated versus what remains manual (for example: transmission-line synthesis, antenna tuning, EM/cavity effects, array calibration, and final RF layout closure).

Do not respond with blanket language like "Circuit Weaver is only for standard embedded electronics" when the real limitation is narrower: some domains have less automation and require more manual engineering review.

---

Long-Running Operations & Timeout Awareness

Do not let Circuit Weaver work run silently for long periods.

When a step is expected to take noticeable time — for example confidence --run-sims, simulate, generate on a large design, optimize-placement, autoroute, large research passes, or repeated validation/generation retries — follow these rules:

1. Before starting any command likely to exceed ~2 minutes, tell the user:
   • what command or phase is starting,
   • why it may take a while,
   • what success artifact or status you expect.
2. At ~2 minutes without completion, send a follow-up and check progress using the best available source:
   • python -m circuit_weaver log-status <project_dir>
   • python -m circuit_weaver log-view <project_dir>
   • recent entries in design.log
   • recent entries in circuit-weaver.log
   • output/artifact timestamps or files created so far
3. At ~5 minutes, do not just keep waiting. Inspect for actionable issues:
   • unresolved validation blockers,
   • missing dependencies/tools,
   • stalled artifact generation,
   • repeated warnings/errors in logs,
   • no file or status movement since the last check. Then tell the user whether the work is actively progressing, blocked, or likely stuck.
4. At ~15 minutes, either:
   • explain concretely why the wait is still expected and what milestone remains, or
   • stop/pivot to a smaller bounded step and surface the blocker.
5. Never allow a run to sit silent for ~30 minutes. Long-running work must include periodic follow-up plus an explicit progress/issue check.

When reopening an interrupted or stale project, reconcile durable state before re-running expensive commands. Minimum restart triage:

python -m circuit_weaver status <project_dir>
python -m circuit_weaver resume <project_dir>

resume prints a plan; it does not execute it. If state reports a prior failure or modified/missing files, inspect log-status, log-view, design.log, and circuit-weaver.log before deciding whether to retry, validate, or edit.

---

Workflow: New Design

Step -2 — Installed Version Banner (ALWAYS RUN FIRST)

Before presenting any choices, detect the installed Circuit Weaver CLI version from the command on PATH and paste it back to the user.

Preferred command:

circuit-weaver --version

Fallback if the circuit-weaver entrypoint is missing:

python -m circuit_weaver --version

Rules:

• Prefer the circuit-weaver command on PATH when available. That is the installed CLI.
• Do not infer the version by reading src/circuit_weaver/__init__.py or other repo files.
• If forced to use python -m circuit_weaver --version from a checkout, clearly label it as the local/imported version rather than the installed CLI version.

Paste back a short banner before the menu, for example:

Circuit Weaver installed: vX.Y.Z

If only the fallback worked:

Circuit Weaver local/imported version: vX.Y.Z

Step -1 — Auto-Detection

Before presenting any choices, automatically scan for existing projects and available samples:

python -m circuit_weaver discover --json

Then detect the sample sources that actually exist in the current installation. Source checkouts may provide the full samples/ gallery:

ls -d samples/*/  # POSIX
# or
dir /b /ad samples\  # Windows

Do not assume that directory exists in a PyPI installation. The wheel carries a single portable starter spec instead; verify it with:

python -c "from importlib.resources import files; p=files('circuit_weaver').joinpath('examples','iot_sensor.yaml'); print(p if p.is_file() else '')"

Separate user projects from available examples:

• User projects: from the discover --json output, exclude any project whose path contains /samples/ or \samples\. These are your actual user projects. Only show these in the "Open existing" option.
• Source-checkout samples: when a real repo-local samples/ directory exists, its subdirectories are reference designs, not user projects. Show only the directories actually found under option [3].
• Packaged example: PyPI installs expose iot_sensor.yaml through importlib.resources. Show it as iot_sensor under option [3]. Do not claim that the full source-checkout gallery is bundled in the wheel.

If user projects are found, present them:

Found 2 existing circuit project(s):

  #  Project                  Type            Status       Files
  -  -------                  ----            ------       -----
  1  WiFi_Sensor_v1           circuit_weaver  validated    yaml, sch, pcb, log
  2  Motor_Controller         kicad_native    generated    sch, pcb, pro

If no user projects are found (only examples or nothing), skip the project list. If neither a repo-local sample nor the packaged example is available, omit option [3] instead of presenting a broken route.

Log: python -m circuit_weaver log-event <project_dir> --type wizard_step --message "Auto-detection: N projects found, M samples available"

Step 0 — Welcome & Route

Present a choice (platform-adapted):

Claude Code / Codex / OpenCode:

Welcome to Circuit Weaver

What would you like to do?
  [1] Design a new circuit
  [2] Open an existing design
  [3] Start from a sample design

For Claude Code: Use AskUserQuestion with options ["Design a new circuit", "Open an existing design", "Start from a sample design"] For Codex/OpenCode: Present as numbered list, ask user to type [1], [2], or [3] For CLI: User already running design-wizard, skip this step

Based on choice:

• [1] New design → Proceed to Step 1
• [2] Existing design → Jump to "Workflow: Existing Design" section
• [3] Sample design → Proceed to Step 0.3 (below)

Step 0.3 — Start from a Sample Design

List only sample designs detected in Step -1. In a source checkout, enumerate the real subdirectories under samples/. In a normal PyPI install, present the packaged starter:

Available sample designs:

  #  Sample                   Description
  -  ------                   -----------
  1  iot_sensor               ESP32-based IoT environmental sensor

  [0] Back to main menu

When the repo gallery exists, replace that one-item example with the actual directory names and descriptions found there. Ask for a number in the displayed range; never hard-code a 13-item range when those files are absent.

On selection:

1. Ask for the destination before copying.
2. For a repo-local sample, copy the existing directory: cp -r samples/<sample>/ <user-chosen-destination>/.
3. For the packaged iot_sensor example, create the destination and copy the resource bytes from importlib.resources.files("circuit_weaver").joinpath("examples", "iot_sensor.yaml") into <destination>/design.yaml. Use Python's Path.mkdir() and Path.write_bytes() so this works on Windows, macOS, and Linux.
4. Ask the user for a project name (default: same as sample).
5. Rename the YAML if desired and set the project name in the spec.
6. Print: ✓ Sample copied to <project_name>/.
7. Log: [Step 0.3] Started from sample: <sample_name>.
8. Jump to "Workflow: Existing Design" section (treat the copied sample as an existing design to review/modify).

Step 1 — Project Setup & Folder Creation

This step must happen FIRST, before any other questions.

1a. Project Name (REQUIRED FIRST)

Question: "What's the name of your project?"

Examples:

• "WiFi_Sensor_v1"
• "Motor_Controller_2024"
• "USB_Audio_Interface"

All platforms: Ask as open text input.

Action:

1. Take the project name
2. Create folder: ${PROJECT_NAME}/
3. Create logfile: ${PROJECT_NAME}/design.log
4. Log: [Step 1] Project created: {project_name}
5. Print to user: ✓ Project folder and logfile created

Continue immediately to Step 1b once folder + log are created.

1b. Experience Level

Question: "What's your EE experience level?"

Claude Code: Use AskUserQuestion with options:

• Beginner (I'm new to circuit design)
• Intermediate (I've designed 1-2 circuits)
• Advanced (I've designed 5+ circuits)
• Professional (I design circuits for a living)

Codex/OpenCode: Present as numbered list, ask user to select [1-4]

Reasoning: Calibrate explanation depth and component complexity throughout the wizard.

Log: [Step 1b] Experience level: {selected_level}

Immediately branch the intake style by level. Do not use the same first requirements question for every tier:

• Beginner: Start with a plain-language application question, then ask form factor, power, and interfaces separately.
• Intermediate: Keep guided prompts with examples and defaults.
• Advanced: Start with one compact design brief covering purpose, power, interfaces, and constraints, then ask only the missing fields.
• Professional: Do not immediately ask "What does this circuit do?" as a standalone question. Ask for a compact design brief or spec fragment instead.

Useful professional format: purpose; input power; rails/current; interfaces; mechanical constraints; preferred ICs

1c. Requirements Intake

For Beginner / Intermediate, ask:

Question: "What does this circuit do? (describe the end application)"

Examples:

• "WiFi environmental sensor, battery-powered, 50x30mm enclosure"
• "Motor controller for robot arm, wall-powered"
• "USB audio interface, desktop device"

For Advanced, ask:

Question: "Give me a compact design brief covering purpose, power, interfaces, and constraints."

For Professional, ask:

Question: "Paste a compact design brief or spec fragment. Useful format: purpose; input power; rails/current; interfaces; constraints."

Log: [Step 1c] Purpose: {user_input}

If the brief indicates specialized RF/microwave work (radar, phased array, Ku-band, mmWave, custom RF front-end), immediately switch from generic embedded intake to a specialized architecture intake. Ask for:

• frequency band and bandwidth
• system architecture (FMCW, direct conversion, superhet, IF chain, etc.)
• channel/array count
• LO/reference clock plan
• gain / NF / power / dynamic-range targets
• controlled-impedance and shielding constraints

Do not refuse the design space. Frame it as: "supported through a custom engineering workflow with manual RF closure."

1d. Form Factor & Mechanical

Only ask this as a separate follow-up if it was not already captured clearly in Step 1c.

Question: "What are the size and component height constraints?"

Examples:

• "50×30mm enclosure, max component height 12mm"
• "Credit-card sized (85×54mm), compact"
• "No size constraint, but want to fit in existing housing"

All platforms: Ask as open text input.

Log: [Step 1d] Form factor: {user_input}

1e. Power Source & Rails

Only ask this as a separate follow-up if Step 1c did not already capture input power and rail/current needs.

Question: "What power source will you use, and what voltage rails do you need?"

Examples:

• "3.7V LiPo battery, needs 3.3V@500mA for MCU and 5V@100mA for USB"
• "5V USB, only needs 3.3V rail"
• "12V wall supply, needs 5V and 3.3V"

All platforms: Ask as open text input.

Log: [Step 1e] Power rails: {user_input}

1f. Interfaces & Sensors

Only ask this as a separate follow-up if Step 1c did not already capture the key interfaces, buses, or sensors.

Question: "What interfaces and sensors does your circuit need?"

Examples:

• "USB charging, I2C for BME280 sensor, WiFi via ESP32"
• "SPI for SD card, UART for debug, GPIO for button/LED"
• "CAN bus, no sensors"

All platforms: Ask as open text input.

Log: [Step 1f] Interfaces: {user_input}

1g. Confirm & Summarize

Compile the answers and present a summary:

=== Requirements Summary ===

Project:        {project_name}
Application:    WiFi Environmental Sensor
Experience:     Intermediate
Form Factor:    50×30mm enclosure, SMD only, <12mm component height
Power Source:   3.7V LiPo battery (500mAh nominal)
Output Rails:   3.3V @ 500mA (MCU), 5V @ 100mA (USB charging circuit)
Interfaces:     USB for charging, I2C for sensor (BME280)

Question: "Does this look right? Any changes?"

Claude Code / Codex / OpenCode: Use yes/no question All platforms: Accept "yes", "no", or redirection to specific field

If user wants to change something, loop back to the relevant question.

Log: [Step 1g] Requirements confirmed. Ready for IC research.

Step 2 — IC Research & Selection

Before the first query, resolve the effective research settings:

Backend:

• Respect metadata.research_backend from a scaffolded spec when present.
• Otherwise respect CIRCUIT_WEAVER_RESEARCH_BACKEND={auto,sonar-pro,standard}.
• auto means: use sonar-pro when PERPLEXITY_API_KEY is configured, otherwise standard.

Depth:

• Respect metadata.research_depth from a scaffolded spec when present.
• Otherwise respect CIRCUIT_WEAVER_RESEARCH_DEPTH={fast,normal}.
• fast means: latency-first pass. Run one project-context query plus at most 2 targeted block queries. Skip deep alternates, detailed pricing, and connector research unless the user explicitly asks or the block is critical.
• normal means: fuller pass. Run one project-context query plus the standard 3-5 targeted block queries, including alternatives and rough pricing context where useful.
• circuit-weaver doctor is the source of truth for the effective backend, depth, and credential status.

Use the backend consistently for the whole session:

• Keep IC research in the current agent/session. Do not spawn a separate research subagent or worker for Step 2.
• sonar-pro → prefer the platform's high-quality research mode only if it runs in-thread in the current agent.
• standard → use the platform's native web search / web fetch tools in the current agent.
• If the premium path would delegate to a subagent, or if it throws a model / tool conflict, skip it and continue with native web tooling in the current agent. Persist the backend that actually ran.

Persist every completed research run with circuit-weaver save-research. The saved {project_dir}/research/*.json files are the source of truth; design.log should point back to those JSON artifacts for reproducibility.

Phase 2a — Project Context

Single broad query to understand the design space in the current agent session:

Design a [application description].
  Constraints: [form factor], [power source], [interfaces].
  Find 1-2 existing reference designs, key IC families (MCU, power conversion, sensors),
  typical topologies, and estimated BOM size."

If sonar-pro is available without delegation, use that path for the query. Otherwise, run the same query with the platform's built-in web tools and record standard as the backend you actually used.

After the result is consolidated, persist it:

circuit-weaver save-research --project-dir ./output --backend <sonar-pro|standard> --topic "project-context" --file research.json

This grounds subsequent searches in reality.

Log: [Step 2a] Started IC research for {application} | Query logged

Phase 2b — Targeted Function Queries

For each major functional block, run targeted research in parallel:

If research depth is fast, run at most 2 of these and prioritize the highest-risk blocks first:

• MCU / main SoC
• Primary power conversion path
• Primary sensor or interface only if it is novel, safety-critical, or likely to drive the package choice

In fast mode, return 1-2 options per block and skip deep alternates, detailed cost tables, and non-critical connector lookups unless the user explicitly asks.

If research depth is normal, run 3-5 of these (adapt to your design):

MCU for [interfaces: WiFi, BLE, Ethernet, etc.],
  [power constraint: battery, low-power, high-performance].
  Return: Top 3 options with MPN, LCSC cost, key specs (flash, RAM, peripherals).

Power conversion: [input voltage] to [output voltage, current].
  Application: [battery/USB/wall-powered, form factor constraints].
  Return: Top 3 IC options (topology, MPN, LCSC cost, efficiency), required passives.

[Sensor type: environmental, motion, audio, etc.] for [application].
  Interface: [I2C/SPI/analog], power constraint: [mA budget].
  Return: Top 3 sensors with MPN, LCSC cost, typical application circuit.

Connector/interface: [USB/Barrel Jack/JST-PH/etc.] for [application].
  Return: Recommended part with MPN, LCSC cost, pin assignment, typical footprint.

Run these in parallel where the platform supports it, but keep them in the current agent/session. Do not offload Step 2 to a research subagent. Use the selected backend's same-agent tooling when available; otherwise use native web tooling. Persist the backend and depth that actually ran with circuit-weaver save-research --project-dir ./output ....

Log: [Step 2b] Targeted research queries: [list each query]

Phase 2c — Present & Confirm

Consolidate findings into a table:

=== IC Selection Results ===

MCU (WiFi, 4MB flash, 500mA):
  [1] ESP32-S3-WROOM-1 (most common, $5.80)
  [2] ESP32-C3 (smaller, $3.50)

Power Conversion (3.7V → 3.3V @ 500mA):
  [1] TPS62300 (buck, 95% eff, $1.20)
  [2] LDO (simpler, lower noise, $0.50)

Sensor (I2C, temp+humidity+pressure):
  [1] BME280 (standard, $2.15)
  [2] BME680 (with gas, $3.50)

Charging Circuit (LiPo, USB 5V input):
  [1] TP5000 (simple, $1.80)
  [2] BQ24075 (feature-rich, $3.50)

Claude Code / Codex / OpenCode: "Do these IC selections look good? Want to swap any?"

Log: [Step 2c] IC selections confirmed: {selected_ics_list}

Step 3 — Generate Design Spec

Choose the closest supported topology from list-templates, scaffold one valid starting block, and then edit the YAML to incorporate the confirmed architecture, ICs, interfaces, and constraints. scaffold accepts a template and reference; it does not accept project-name or MPN flags.

python -m circuit_weaver scaffold \
  --template "${SELECTED_TEMPLATE}" \
  --ref "U1" \
  --output "${PROJECT_NAME}/design.yaml"

Example:

python -m circuit_weaver scaffold \
  --template "buck" \
  --ref "U1" \
  --output "WiFi_Sensor_v1/design.yaml"

Set the top-level project value to ${PROJECT_NAME}. Replace scaffold placeholders and add the selected blocks before validation. For a custom architecture with no matching template, author design.yaml directly from a validated sample/schema rather than inventing unsupported scaffold flags.

Give every architectural block a stable unique id and an explicit functional section, for example power_input, core_processing, sensors, communications, user_interface, or debug. Generation preserves those sections as separate schematic sheets even for a small design; support passives stay with their owning block. Do not collapse unrelated functions into one section merely to reduce file count. The allocator sanitizes and disambiguates filenames, but unique, descriptive section names make the hierarchy legible to humans.

Output: a complete ${PROJECT_NAME}/design.yaml ready for validation.

Log: [Step 3] Design spec generated: design.yaml

Step 4 — Validate Design

Run validation to catch errors before generation:

python -m circuit_weaver validate "${PROJECT_NAME}/design.yaml"

If validation passes:

[PASS] Design validated successfully.
  - Electrical checks: OK
  - Power domain consistency: OK
  - Decoupling coverage: OK

If validation fails, display errors and ask user to refine the spec.

Log: [Step 4] Validation: {PASS|FAIL}. Errors: {error_list if any}

Step 5 — Generate Artifacts

Generate the schematic and placement files:

python -m circuit_weaver generate "${PROJECT_NAME}/design.yaml" \
  --output "${PROJECT_NAME}/output"

Before any release-quality, handoff, or fabrication-readiness claim, regenerate with the real KiCad gate:

python -m circuit_weaver generate "${PROJECT_NAME}/design.yaml" \
  --output "${PROJECT_NAME}/output" --require-kicad

Internal validation is not a substitute for this final KiCad load/ERC check.

Read the JSON result from stdout, open the path in its artifact_manifest field, and use artifact_manifest.json as the source of truth. Read root_schematic and select paths from its artifacts array. Manifest paths are portable and relative to the directory containing the manifest, so resolve them against artifact_manifest.json's parent directory. Use the result's files only as a compatibility fallback.

Inspect valid, kicad_verified, verification_status, and erc in the manifest before reporting success. verification_status: unverified means KiCad was unavailable or skipped; say so explicitly and never describe that artifact as KiCad-verified. The generated bundle includes:

• the manifest-selected root schematic plus one sub-sheet per functional section;
• assembly_manifest.json, the exhaustive physical-part/reference inventory;
• placement_result.json, placement_review_context.json, placement.svg, and placement_editor.html, the review-only placement bundle; and
• ${PROJECT_NAME}_report.md, the design analysis and power budget.

Never guess main.kicad_sch or any section filename. Resolve every artifact through artifact_manifest.json. Inspect placement_result.json before showing the visual artifacts: it must reconcile exactly to assembly_manifest.json and must always say fabrication_ready: false. Surface every placement blocker. Treat manufacturer datasheets and reference layouts linked from placement_review_context.json as authoritative over the heuristic proposal.

Log: [Step 5] Artifacts generated in output/

Step 6 — Confidence & Simulation Check