---
name: circuit-weaver
description: >
  Circuit Weaver main entry point. Routes to new design (wizard + research-driven IC selection + 
  passive generation + schematic generation) or opens existing design for review/modification.
  Trigger on: "design a circuit", "new design", "design wizard", "circuit-weaver", or 
  when user provides a design directory path.
---

# 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

## Quick Start

**For a new design:**
```
/circuit-weaver
→ [asks new/existing]
→ [collects requirements via design_wizard]
→ [spawns research agent to find ICs]
→ [generates passives, validates, creates schematic]
```

**For an existing design:**
```
/circuit-weaver
→ [asks for design directory path]
→ [loads design.yaml and reports current state]
→ [offers options: validate, regenerate, modify, review]
```

---

## Workflow: New Design

### Step 0 — Welcome & Route

Display:
```
Welcome to Circuit Weaver

What would you like to do?
  [1] Design a new circuit (I'll guide you through the full workflow)
  [2] Open an existing design (I'll load your project)
```

Ask user to choose. If [1], proceed to Step 1. If [2], jump to "Existing Design" section below.

### Step 1 — Requirements Capture

Use the existing `design_wizard` skill logic (Steps 0-1a from `skills/design_wizard/SKILL.md`):

1. **Experience Level** — Ask beginner/intermediate/advanced/professional
   - Calibrate explanation depth throughout
2. **Purpose & Application** — What does this board do?
   - Example: "WiFi environmental sensor, battery-powered, 50x30mm enclosure"
3. **Features & Interfaces** — What external connections/sensors?
   - Example: "USB for charging, I2C for sensor, WiFi via ESP32"
4. **Power & Electrical** — Power source and rail requirements
   - Example: "3.7V LiPo, needs 5V and 3.3V rails, ~500mA total"

**Sanity check:** Run a power budget estimate inline using the `ee` skill formulas. If the math doesn't work (e.g., demanding 5A from a USB 2.0 port), flag it and ask the user to revise.

**Summarize before proceeding:**
```
=== Requirements Summary ===

Device:        WiFi Environmental Sensor (battery-powered)
Enclosure:     50x30mm (SMD components only, <10mm height)
Power source:  3.7V LiPo (500mAh nominal)
Output rails:  5V @ 1A, 3.3V @ 0.5A
Interfaces:    USB (charging), I2C (sensor)
Sensors:       Temperature + humidity + pressure
MCU:           WiFi capable (e.g., ESP32)

Power budget:  1.5A avg draw @ 3.7V → needs efficient boost + buck
Estimated BOM: 4-5 ICs (boost, buck, MCU, sensor, maybe charger)
```

Ask: **"Does this look right? Any changes?"**

### Step 2 — IC Research & Selection

**Trigger the research-analyst agent** to find:
1. Similar existing designs (reference implementations, app notes, eval boards)
2. Candidate ICs for each functional block (boost, buck, MCU, charger, etc.)
3. Key IC datasheets and typical application circuits
4. Alternative parts (pin-compatible, different cost tiers)

**Run the research agent:**

```bash
/research "Design a [user's application description].
  Find similar reference designs and select ICs for:
  - Power input stage: [user's power source + output voltage/current]
  - MCU: [WiFi/BLE/zigbee requirement]
  - Sensor/peripherals: [specific sensors or interfaces]
  
  Return:
  1. Similar designs from datasheets/app notes
  2. IC recommendations (MPN, package, LCSC/DigiKey part numbers, cost)
  3. Key parameters from datasheets
  4. Alternative options for each block"
```

The research-analyst agent will:
- Use Perplexity Sonar API (via `PERPLEXITY_API_KEY` env var) to search for similar designs
- Cross-reference with component databases (DigiKey, LCSC, Mouser)
- Return structured findings with datasheets and links

**User confirmation:**

Display research findings:
```
=== IC Research Results ===

Boost Converter (3.7V → 5V @ 1A):
  [1] TPS61230A (most common, $2.50)
  [2] MT3608   (budget option, $1.00)
  [3] LTC3105  (low-dropout, $4.20)

Buck Converter (5V → 3.3V @ 0.5A):
  [1] AP62300  (recommended, $1.20)
  [2] LM3671   (lower noise, $2.80)

MCU (WiFi, 4MB flash):
  [1] ESP32-WROOM-32E (widely used, $5.80)
  [2] ESP32-S3        (newer, better performance, $6.50)

Sensor (I2C, temp/humidity/pressure):
  [1] BME280 (very common, $2.15)
  [2] BME680 (gas sensor too, $3.50)

Charger (LiPo, optional):
  [1] TP5000 (simple, $1.80)
  [2] BQ24075 (more features, $3.50)
```

Ask: **"Do these IC choices look good? Any you'd like to swap?"**

If user wants to change any, re-run research for that block and re-confirm.

### Step 3 — Passive Generation & BOM Assembly

Once ICs are locked:

1. **Collect IC datasheets** — Extract from research findings
2. **Generate passives** — For each IC, calculate:
   - Input/output bulk caps (aluminum or ceramic, voltage rating, ESR)
   - Decoupling caps (100nF per VCC pin + 10µF mid-range)
   - Feedback divider resistors (voltage dividers for buck/boost feedback)
   - RC/LC filters (input/output EMI filters, crystal load caps)
   - Current-sense resistors (if any)
3. **Build initial BOM** — Combine ICs + passives
4. **Search LCSC for all parts** — Get live pricing and stock

Display:
```
=== Generated BOM ===

Reference | MPN              | Value         | Package  | LCSC       | Cost
----------|------------------|---------------|----------|------------|--------
U1        | TPS61230A        | Boost Conv.   | SOT-23-6 | C406093    | $2.50
U2        | AP62300          | Buck Conv.    | SOT-23-6 | C460320    | $1.20
U3        | ESP32-WROOM-32E  | WiFi MCU      | SMD-30   | C529676    | $5.80
U4        | BME280           | Sensor        | LGA-8    | C91305     | $2.15
C1-C8     | Passives (caps)  | Various       | 0402-1206| Various    | $0.60
R1-R8     | Passives (R)     | Various       | 0402     | Various    | $0.15
          |                  |               |          | TOTAL:     | $12.40
```

Ask: **"BOM looks good? Want to add/remove anything before we generate the schematic?"**

### Step 4 — Schematic Generation & Validation

Run the circuit-weaver CLI subcommands:

```bash
# Validate the design spec
circuit-weaver validate design.yaml

# Generate schematic, BOM, placement files, and design report
circuit-weaver generate design.yaml --output ./output
```

Display results from validation:
```
=== Validation Report ===

Structural checks:      PASS
Electrical checks:      PASS
  [✓] Power domain consistency (3 domains: VBAT, VBUS_5V, VDD_3P3)
  [✓] Decoupling coverage (all ICs have 100nF + bulk caps)
  [✓] Net connectivity (16 nets, no floating pins)
  [✓] Component ratings (voltage/current within safe limits)
  [✓] Feedback dividers (buck/boost feedback verified)
  [✓] Filter cutoff frequencies (input/output EMI filters OK)
  [✓] Crystal load caps (if applicable)
  [✓] Inductor selection (saturation current sufficient)

Implementation checks:   PASS
Presentation checks:    PASS

Overall: PASS (ready for schematic generation)
```

Display generated files:
```
=== Generated Artifacts ===

Schematic:
  ✓ output/main.kicad_sch (73 KB, 4 ICs + 16 passives, 16 nets)
  ✓ KiCad-native format, ready to open in KiCad GUI

PCB Placement:
  ✓ output/WiFi_Sensor_v1_placement.kicad_pcb (footprints with hints)

Design Documentation:
  ✓ output/WiFi_Sensor_v1_report.md (design analysis, power budget, DFM notes)
  ✓ output/design_ir.json (internal representation)
  ✓ output/canonical_spec.yaml (final design definition)
```

### Step 5 — Design Review Checkpoint

Parse the generated design report and present:
```
=== Design Review Checkpoint ===

Schematic generated: 4 ICs + 16 passive components
Nets: 16 unique signal/power networks
Power budget: 1.5A @ 3.7V → 3.9W average load

Warnings to review:
  [!] UART0_RX/TX on ESP32 are unconnected (OK for WiFi-only, but flag for user review)
  [!] I2C pull-ups on BME280 should be on parent board if shared bus

Next steps:
  1. Open output/main.kicad_sch in KiCad to review layout
  2. Add connectors, test points, mechanical holes
  3. Run KiCad DRC/ERC
  4. Generate gerbers and send to JLCPCB
```

Ask: **"Does the design look correct? Any changes needed?"**

If yes: ask what to change, loop back to Step 3.
If no: proceed to Step 6.

### Step 6 — PCB Layout Guidance & Export

Display:
```
=== PCB Layout Guidance ===

Board size: Recommend 60x40mm (fits your 50x30mm enclosure with margin)
Layers: 2-layer sufficient (single-sided with via stitching)
Component placement hints:
  - Boost converter (U1) near input (LiPo connector)
  - Buck converter (U2) near boost output
  - MCU (U3) center with decoupling caps nearby
  - Sensor (U4) on opposite edge (for airflow)
  - Power planes recommended (5V and 3.3V)

Manufacturing:
  - SMD assembly ready (all 0402-1206 passives, no fine-pitch BGA)
  - No thermal vias required for your power levels
  - JLCPCB-compatible (basic parts only)

Files ready to order:
  ✓ Design spec: design.yaml
  ✓ Schematic: output/main.kicad_sch
  ✓ Placement hints: output/WiFi_Sensor_v1_placement.kicad_pcb
  ✓ Design report: output/WiFi_Sensor_v1_report.md
```

Ask: **"Want to export manufacturing files (BOM + CPL for JLCPCB)?"**

If yes, run:
```bash
circuit-weaver export-jlcpcb design.yaml --output ./jlcpcb_export
```

This generates:
- `jlcpcb_export/bom_jlcpcb.csv` — LCSC part numbers for ordering
- `jlcpcb_export/cpl_jlcpcb.csv` — Placement file for pick-and-place
- `jlcpcb_export/README.txt` — Upload instructions for JLCPCB

---

## Workflow: Existing Design

### Load & Route

Ask: **"Path to your design directory?"**

User provides path (e.g., `./my_wifi_sensor` or `~/projects/sensor_board/design`).

Validate it contains `design.yaml`. Load it.

Display:
```
=== Loaded Design ===

Project:  WiFi_Sensor_v1
Modified: 2026-04-05
ICs:      4 (TPS61230A, AP62300, ESP32-WROOM-32E, BME280)
Status:   Schematic generated, ready for PCB layout

What would you like to do?
  [1] Validate design (check electrical rules)
  [2] Regenerate schematic (after making edits to design.yaml)
  [3] Review design report
  [4] Export manufacturing files (BOM + CPL)
  [5] Make design changes (IC swap, add/remove component, etc.)
  [6] Export gerbers (requires PCB file)
```

Route based on user's choice.

---

## Architecture: Skill vs CLI

This design separates two paths:

### `/circuit-weaver` Skill (Claude Code, Codex, OpenCode users)
- **Triggers when:** user says "design a circuit", `/circuit-weaver`, etc.
- **What it does:**
  1. Routes new vs existing design
  2. Runs interactive Q&A (steps 0-1)
  3. Spawns research-analyst agent (uses Perplexity Sonar API)
  4. Calls CLI subcommands: `circuit-weaver validate`, `circuit-weaver generate`, etc.
  5. Displays results + next steps
- **User experience:** Guided, mostly automatic, agent-driven IC research

### `circuit-weaver` CLI Wizard (Python CLI, standalone users)
When user runs:
```bash
circuit-weaver design-wizard
```

The Python CLI should:
1. Launch interactive wizard (same steps as skill)
2. Handle all Q&A locally (no agent calls)
3. Call internal functions from `mvp.py` (not subcommands)
4. Generate outputs without spawning external agents
5. Allow offline use (for environments without Perplexity API)

**Key difference:** Skill is agent-rich (research-driven), CLI is self-contained (no external APIs).

The **design_wizard** skill remains a fallback for manual step-by-step guidance if the user wants more control or offline operation.

---

## Files Generated

All files go in `./output/` and `./jlcpcb_export/`:

| File | Purpose |
|------|---------|
| `design.yaml` | Canonical circuit spec (YAML) |
| `design_ir.json` | Internal design representation (JSON) |
| `main.kicad_sch` | KiCad schematic (ready to open in KiCad GUI) |
| `main_report.md` | Design analysis report (features, power budget, DFM notes) |
| `main_placement.kicad_pcb` | PCB template with placement hints |
| `jlcpcb_export/bom_jlcpcb.csv` | BOM for JLCPCB (LCSC part numbers) |
| `jlcpcb_export/cpl_jlcpcb.csv` | Placement file for pick-and-place |

---

## Implementation Status

| Component | Status | Notes |
|-----------|--------|-------|
| CLI subcommands | ✅ Done | `validate`, `generate`, `export-jlcpcb`, etc. in `mvp.py` |
| Passive generation | ✅ Done | Implemented in subcircuits (boost, buck, etc.) |
| Research-analyst agent | ✅ Done | Uses Perplexity Sonar API via `PERPLEXITY_API_KEY` env var |
| `/circuit-weaver` skill | 🔨 TODO | Routes new/existing, orchestrates CLI calls |
| CLI wizard mode | 🔨 TODO | `circuit-weaver design-wizard` interactive workflow |
| Research integration | 🔨 TODO | Skill spawns research agent after Step 1 |

---

## Related Skills

- **design_wizard** — Detailed step-by-step guidance (manual control)
- **research-analyst** — EE research agent (IC selection, reference designs)
  - Uses Perplexity Sonar API (env var: `PERPLEXITY_API_KEY`)
  - Access: `~/.claude/agents/research-analyst.md`
- **ee** — Electrical engineering formulas (power budget, filter design)
- **bom** — BOM management and sourcing
- **jlcpcb** — Manufacturing file export and quoting
- **kicad** — Schematic and PCB analysis