/pcb-new

name: pcb-new
description: Start a new PCB project from a text description. Sources parts, generates a wired .kicad_pcb, and hands off to EasyEDA for routing + JLCPCB ordering.
argument-hint: "[short description of the board you want to design]"
allowed-tools:
  # Each MCP tool is listed twice on purpose. A server from a project
  # .mcp.json is exposed as mcp__<server>__<tool>, but the same server
  # provided by an installed plugin is mcp__plugin_<plugin>_<server>__<tool>.
  # Listing only the short form meant this command ran with no MCP tools at
  # all for anyone who installed from the marketplace, and answered in prose.
  - Read
  - Write
  - Glob
  - Grep
  - Task
  - mcp__kicad-jlcpcb__detect_kicad
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__detect_kicad
  - mcp__kicad-jlcpcb__create_project
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__create_project
  - mcp__kicad-jlcpcb__load_project
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__load_project
  - mcp__kicad-jlcpcb__session_resume
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__session_resume
  - mcp__kicad-jlcpcb__session_confirm_bom
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__session_confirm_bom
  - mcp__kicad-jlcpcb__lcsc_search
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__lcsc_search
  - mcp__kicad-jlcpcb__lcsc_resolve_bom
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__lcsc_resolve_bom
  - mcp__kicad-jlcpcb__part_pin_map
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__part_pin_map
  - mcp__kicad-jlcpcb__pcb_generate
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__pcb_generate
  - mcp__kicad-jlcpcb__fetch_part_library
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__fetch_part_library
  - mcp__kicad-jlcpcb__sch_generate
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__sch_generate
  - mcp__kicad-jlcpcb__sch_run_erc
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__sch_run_erc
  - mcp__kicad-jlcpcb__package_for_jlcpcb
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__package_for_jlcpcb
  - mcp__kicad-jlcpcb__easyeda_handoff
  - mcp__plugin_kicad-jlcpcb_kicad-jlcpcb__easyeda_handoff

/pcb-new

Take a text description of a PCB and deliver a ready-to-import KiCad board file the user drags into EasyEDA for routing and ordering.

Instructions

> **`pcb_generate` overwrites the project's `.kicad_pcb`.** It rebuilds the > board from scratch and saves over the existing file — no merge, no backup. If > the project already has a board the user may have opened in KiCad, say so and > confirm before re-running.

1. Detect KiCad

Call `detect_kicad`. If `meets_min` is false, stop and pass the `install_hint` to the user. KiCad's `pcbnew` Python module is required by `pcb_generate`.

2. Check for a resumable session, then create or load the project

Ask the user where the project should live (default: current working directory) and what to name it.

If a `<parent_dir>/<name>/` directory already exists:

• Call `load_project` on it.
• If the response has `resume_available: true`, show the user the session summary (stage, completed checkpoints, next step) and ask whether to **resume** or start a **fresh** project in a different directory.
• If resuming, skip any step the session has already checkpointed (e.g. skip part sourcing if `parts_sourced` is already complete — just reuse the persisted `bom` and go to the BOM checkpoint).

Otherwise, call `create_project` with `parent_dir` and `name`. Each subsequent tool call automatically updates the session file, so mid-flow restarts are safe.

3. Decompose the description into a parts list

Read the user's description carefully. List the components the board will need: microcontroller, regulator, decoupling caps, connectors, indicator LEDs, etc. For each, write a one-line generic spec like `"3.3V LDO, SOT-23-5, 500mA, basic-tier preferred"`.

4. Source parts

Dispatch one `part-sourcer` agent per generic spec, in parallel — a single message with one Task call per spec. Each agent applies the basic-first ladder and returns a structured pick. For parts the user already has LCSC C-numbers for, skip to step 5.

For one or two specs, or when an agent comes back with no match and you want to retry by hand, call `lcsc_search` directly instead: `basic_only=true` first, then `basic_only=false`.

When writing a spec, put the **value and package in the query** (`10k 0603`, `0.1uF 0402`). Values route to an exact structured lookup; `0.1uF` and `100nF` are the same part. Keep queries short — the catalog AND-matches every word, so `TVS SMB 30V` finds parts that `bidirectional TVS diode rated 30 volts in SMB package` does not.

Collect picks into a BOM array of `{lcsc, qty}` rows and call `lcsc_resolve_bom` to validate and tally the extended-part setup fee.

Watch for a `stock_unknown` flag on any resolved part — its JLCPCB stock could not be verified, and you must say so at the checkpoint rather than presenting the number as fact.

5. **CHECKPOINT — present the BOM**

Show the user:

• Each resolved part (C-number, mfr part, package, tier, stock)
• **Every extended-tier part with its cost warning**
• The `estimated_setup_fee_usd` total
• Anything in `unresolved`

Ask whether to swap any extended parts for basic alternatives or proceed. **Do not call `pcb_generate` until the user confirms.**

When they confirm, call `session_confirm_bom` before moving on — pass any change they asked for as `notes`. Without it the approval exists only in this conversation, and a Claude Code restart will ask them to approve the same BOM again. Spending money on a board is the one decision here worth making durable.

6. Build the PCB spec

Construct a spec dict for `pcb_generate`:

{
  "name": "<project name>",
  "board": {"width_mm": 80, "height_mm": 60, "layer_count": 2},
  "components": [
    {
      "ref": "U1",
      "value": "ESP32-C3-WROOM-02",
      "lcsc": "C2934560",
      "lib": "RF_Module",
      "fp": "ESP32-C3-WROOM-02"
    },
    ...
  ],
  "nets": {
    "3V3": [["U1", "3V3"], ["C1", "1"], ...],
    "GND": [["U1", "GND"], ["C1", "2