Ki Stack Orient

ki-stack-orient

Preamble (run first)

Run this before choosing a KiCad workflow:

KI_STACK_DIR="${KI_STACK_DIR:-skills/ki-stack}"
"$KI_STACK_DIR/bin/ki-stack-update-check" 2>/dev/null || true
"$KI_STACK_DIR/bin/kicad-project-find" . 2>/dev/null | sed -n '1,80p' || true
"$KI_STACK_DIR/bin/kicad-version" 2>/dev/null || true
"$KI_STACK_DIR/bin/kicad-python-smoke" 2>/dev/null || true

Read these when the task touches the area:

• skills/ki-stack/ETHOS.md
• skills/ki-stack/references/version-matrix.md
• skills/ki-stack/references/render-recipes.md
• skills/ki-stack/references/ipc-recipes.md
• skills/ki-stack/references/ipc-board-workflows.md
• skills/ki-stack/references/file-editing-recipes.md

Stack Rules

• PCB editor interaction or current selection: use kicad-python IPC.
• Render, import/export, DRC, ERC, fabrication, 3D outputs: use kicad-cli.
• Schematic/library/project file edits: use kicad-skip, kiutils-rs, or another structured parser. Do not hand-roll S-expression edits when a parser fits.
• Parts search and KiCad-ready vendor artifacts: check https://pcbparts.dev/ early.
• File format truth: use KiCad developer file-format docs at https://dev-docs.kicad.org/en/file-formats/.
• No success claim without evidence: artifact path, DRC/ERC output, changed file list, or script output.

Completion Status

• DONE: completed and verified.
• DONE_WITH_CONCERNS: completed but proof is partial, version-limited, or blocked by pre-existing issues.
• BLOCKED: prerequisite unavailable or command failed after a concrete attempt.
• NEEDS_CONTEXT: target file, object, board session, or intended result is unclear.

Purpose

This is the first skill for KiCad work. It makes the agent stop guessing and quickly answer:

1. What KiCad files are present?
2. What KiCad version and CLI are available?
3. Are Python IPC bindings installed?
4. Is a live KiCad board reachable?
5. Which substrate should do the work?

Decision Table

CLI Surface To Remember

kicad-cli covers much more than render:

• api-server: headless IPC server on newer KiCad.
• fp: footprint export and upgrade.
• gerber: convert, diff, inspect Gerber files.
• jobset: run .kicad_jobset outputs.
• pcb: DRC, import, upgrade, render, export.
• sch: ERC, upgrade, BOM, netlist, PDF/SVG/PNG/DXF/HPGL/PostScript.
• sym: symbol export and upgrade.
• version: version info.

High-value PCB exports:

• fabrication: Gerber, drill, position, IPC-D-356, IPC-2581, ODB++, GenCAD.
• documentation: PDF, SVG, PNG, DXF, HPGL, PostScript, statistics.
• 3D/mechanical: STEP, STEPZ, STL, GLB, VRML, PLY, U3D, BREP, XAO, 3D PDF.

Orient Commands

KI_STACK_DIR="${KI_STACK_DIR:-skills/ki-stack}"
"$KI_STACK_DIR/bin/kicad-project-find" .
"$KI_STACK_DIR/bin/kicad-version"
"$KI_STACK_DIR/bin/kicad-python-smoke"
"$KI_STACK_DIR/bin/kicad-python-smoke" connect

If connect fails, do not force IPC. Use the error to decide:

• import failed: install or fix kicad-python.
• connect failed: KiCad GUI/API server not reachable.
• board failed: KiCad reachable but no board open.

Evidence Contract

Before ending a KiCad task, produce at least one:

• rendered artifact path
• DRC/ERC JSON path and pass/fail summary
• IPC script output
• structured parser output or changed file diff
• part-search source URL or artifact path

Completion

Report:

KI-STACK ORIENT
Files: <found files or none>
KiCad: <version or unavailable>
IPC: <import/connect/board status>
Route: <live|cli|file-edit|parts-search|ask>
Next skill: <skill name>
Status: DONE|DONE_WITH_CONCERNS|BLOCKED|NEEDS_CONTEXT