ki-stack-pcb

name	ki-stack-pcb
description	PCB-focused KiCad workflows built on top of the Phase 1 substrate skills. Use when the task is specifically about boards: inspecting nets, tracks, vias, footprints, layers, board metadata, PCB rendering, board verification, or PCB automation through live IPC.
license	MIT
compatibility	opencode
allowed-tools	["Bash","Read","Glob","Grep"]

ki-stack-pcb

Purpose

This is the first Phase 2 domain skill.

It orchestrates PCB-specific work by composing:

• ki-stack-live
• ki-stack-render
• ki-stack-file-surgery
• ki-stack-verify

Use this skill when the user intent is clearly about a PCB or board-level artifact.

What it covers

• current board inspection
• nets, tracks, vias, footprints, zones, and layers
• board title block and metadata edits
• PCB rendering in 2D and 3D
• board DRC and verification
• save/copy/checkpoint flows before risky edits

Routing rules

Use ki-stack-live when

• a board is already open in KiCad
• the task benefits from live state
• the user refers to the current selection or current board
• the edit is interactive, incremental, or inspection-heavy

Use ki-stack-render when

• the user wants to see the board
• the user wants before/after proof
• the task is visual or presentation-oriented

Use ki-stack-file-surgery when

• the change is deterministic and offline
• the task is metadata- or file-structure-heavy
• no live KiCad session is required

Use ki-stack-verify after

• any electrically meaningful PCB change
• any visual PCB change that should be proven

Phase 1: Orient

1. Confirm the task is actually PCB-scoped.

2. Identify the board file or live board context.

3. Probe the environment:

   skills/ki-stack/bin/kicad-version
   skills/ki-stack/bin/kicad-python-smoke
   

4. Decide the path:

• live IPC path
• offline file-surgery path
• render-only path

Phase 2: Inspect

For live PCB tasks, start with the board examples from ki-stack-live.

Suggested order:

1. skills/ki-stack/examples/ipc/hello_kicad.py
2. skills/ki-stack/examples/ipc/board_inventory.py
3. skills/ki-stack/examples/ipc/layer_overview.py
4. skills/ki-stack/examples/ipc/selection_dump.py if the selection matters

For offline PCB tasks, inspect with:

skills/ki-stack/bin/kiutils-inspect board.kicad_pcb --show-unknown --show-diagnostics --show-canonical

Phase 3: Execute

Live PCB workflow

Prefer this sequence:

1. inspect live board state
2. inspect selection if relevant
3. write a small Python script based on the closest example
4. use commit sessions for multi-step edits
5. save only after the mutation is clearly correct

Good live PCB tasks for v1:

• inspect nets and footprints
• inspect layers and title block metadata
• dump selection state
• update title block metadata
• save a board copy before experimentation

Offline PCB workflow

Prefer this sequence:

1. inspect with kiutils-inspect
2. write a small kiutils-rs transform
3. use typed mutation helpers only
4. write losslessly

Good offline PCB tasks for v1:

• board metadata edits
• property edits
• deterministic board-file transforms that do not require live editor context

Phase 4: Render

PCB work should usually produce visual proof.

Common commands:

Board 2D SVG

skills/ki-stack/bin/kicad-render pcb-svg board.kicad_pcb out_dir --layers F.Cu,F.SilkS,Edge.Cuts --mode-single

Board PDF

skills/ki-stack/bin/kicad-render pcb-pdf board.kicad_pcb board.pdf --layers F.Cu,F.SilkS,Edge.Cuts --mode-single

Board 3D PNG

skills/ki-stack/bin/kicad-render pcb-render board.kicad_pcb board.png --width 1800 --height 1200 --side top

Phase 5: Verify

PCB changes that could affect correctness should run DRC.

Preferred command:

skills/ki-stack/bin/kicad-drc-json board.kicad_pcb drc.json

For visual changes, also produce before/after renders.

Common PCB workflows

Workflow: understand the current board

1. run board_inventory.py
2. run layer_overview.py
3. render a 2D SVG and optionally a 3D PNG

Workflow: inspect a selected set of board items

1. run selection_dump.py
2. if needed, render the board after selecting relevant layers
3. only then write a task-specific Python script

Workflow: make a small board metadata change

1. start from update_title_block.py
2. run it against the live board
3. save
4. render the board
5. run DRC if the change could affect more than metadata

Workflow: perform an offline board transform

1. inspect with kiutils-inspect
2. write a tiny kiutils-rs transform
3. write losslessly
4. render and run DRC

Version-aware notes

• KiCad 9/10: prefer GUI-backed IPC flows.
• KiCad 11+: headless IPC may be available.
• Some board methods are version-gated. If a desired API is missing, report the version constraint and route to another path if possible.

Helper assets

Skills to compose:

• skills/ki-stack/ki-stack-live/SKILL.md
• skills/ki-stack/ki-stack-render/SKILL.md
• skills/ki-stack/ki-stack-file-surgery/SKILL.md
• skills/ki-stack/ki-stack-verify/SKILL.md

References:

• skills/ki-stack/references/ipc-board-workflows.md
• skills/ki-stack/references/render-recipes.md
• skills/ki-stack/references/kiutils-recipes.md

Examples:

• skills/ki-stack/examples/ipc/hello_kicad.py
• skills/ki-stack/examples/ipc/board_inventory.py
• skills/ki-stack/examples/ipc/layer_overview.py
• skills/ki-stack/examples/ipc/selection_dump.py
• skills/ki-stack/examples/ipc/update_title_block.py
• skills/ki-stack/examples/ipc/save_board_copy.py

Guardrails

• Do not invent a low-level board scripting path if a close example already exists.
• Prefer live IPC for current-board and current-selection tasks.
• Prefer render plus DRC for proof.
• If an API is version-gated, say so explicitly.
• If the task is not really board-scoped, route to the more specific skill instead.

Completion states

• DONE: the PCB task completed and was verified visually or structurally
• DONE_WITH_CONCERNS: the PCB task completed but verification or API support is partial
• BLOCKED: the environment or version prevented completion
• NEEDS_CONTEXT: the board target, requested operation, or proof format is unclear