@fateforge/xpedition-cli 1.0.0

package/skills/xpedition-pcb/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: xpedition-pcb
+version: "1.0.0"
+description: "Handles board work in Xpedition Layout through the xpedition-cli tool: builds the board from a drawn schematic, forward-annotates it and brings it up to date after the schematic or a footprint changes, then the outline, mounting holes, placement, copper pours, net classes and trace widths, autorouting or planned hand routing, DRC, board renders and screenshots, and the fabrication package (Gerber, NC drill, ODB++, centroid). Use when the user asks to lay out, place or move parts on, route, DRC-check, render or export the PCB of an Xpedition project, including a part move given in mm, even without the word Xpedition. Not for the schematic, pin planning or footprint mapping (xpedition-schematic), or for install, doctor, sessions and Layout connection failures, project creation, the BOM and ChangeSet writes (the xpedition-cli Skill, loaded before this one)."
+license: MIT
+user-invocable: true
+metadata: {"requires":{"bins":["xpedition-cli"],"skills":["xpedition-cli"],"min_version":"1.0.0"}}
+---
+
+# xpedition-pcb
+
+Read `../xpedition-cli/SKILL.md` before running any command. It carries what
+every xpedition-cli task needs and this Skill does not repeat: the install, the
+first step (`context`, `doctor`, `reference`), native sessions, the dry-run →
+confirm recipe, the error decision tree, the security boundary and the
+`_untrusted` rule. If that file is missing, STOP CHECKPOINT: tell the user the
+xpedition-cli entry Skill is not installed and, once they agree, install the
+family with `npx skills add fatecannotbealtered/xpedition-cli -y -g`.
+
+This Skill covers the board in Xpedition Layout, from packaging a drawn
+schematic to the fabrication package.
+
+## When to use
+
+Use this Skill for:
+
+- turning a drawn schematic into a board: package the parts, create the board,
+  forward-annotate;
+- the first layout: outline, mounting holes, placement, pours, net classes,
+  autorouting and DRC;
+- routing by hand, moving parts and small local placement adjustments;
+- looking at a board and reading it back;
+- the fabrication package.
+
+Do not use it for the schematic, pin planning or footprint mapping
+(xpedition-schematic), or for the BOM or creating a project (xpedition-cli).
+Never present an autorouted board or a generated placement as signed off: both
+are starting points for a person.
+
+## Before a board task
+
+`pcb *` commands run in Xpedition Layout, except `pcb stitch` and
+`pcb placement-plan`, which work from files. Check `doctor`'s `native_session` for
+what is attached and start Layout explicitly with `session start --backend
+native_xpedition --kind pcb`. `--backend` defaults to `mock`, so every native
+command names `--backend native_xpedition --project X.prj`; the short forms in
+the prose leave both out. Read `reference/pcb-conventions.md` before touching a
+board: the rules in this Skill are its non-negotiable subset, and only a
+company rule changes them. `reference --compact` stays the source of truth for
+commands and parameters. When `context` lists a knowledge-base document for
+board work, read it first: its rules replace the design defaults, here and in
+the conventions, and settle the TBDs; the verified facts and the write safety
+rules stand (see Company knowledge base in the entry Skill).
+
+Every write is shown as its dry run: inspect the preview, then run the same
+command with `--confirm <confirm_token>` in place of `--dry-run`. The token is
+bound to the arguments, so change nothing else.
+
+While a board opens, Layout may ask about a stale lock, database recovery or
+forward annotation; the adapter answers them and lists what it pressed under
+`prompts`. If a result carries a prompt you did not expect, read it before
+going on.
+
+A MockBackend read needs no Layout:
+
+```bash
+xpedition-cli pcb info --backend mock --project ./demo-project.json --compact
+```
+
+## From the schematic to a board
+
+Three guarded steps, each `--dry-run` then `--confirm`, then a read-back:
+`library build --design FILE --package` (padstacks, cells and parts for every
+part — placeholder cells unless the design names KiCad footprints — imported into
+the project's central library, then packaged), `pcb create` (the board from the
+library's `4 Layer Template` through JobWizard; `--template` for another), `pcb
+annotate` (Layout's forward annotation: the packaged parts and nets arrive
+unplaced), then `pcb info` and `pcb components` to read the board back. Report
+done only when `pcb annotate` says `outcome: annotated` (`annotated_on_open` and
+`in_synch` count too) with no `errors`, and the counts match the schematic.
+
+`FILE` is the design file the schematic was drawn from. Its `packages` choose
+the footprints; see the drawing conventions in `../xpedition-schematic/SKILL.md`.
+
+```bash
+xpedition-cli session start --backend native_xpedition --kind pcb --compact
+xpedition-cli library build --backend native_xpedition --project X.prj --design design.json --package --dry-run --compact
+xpedition-cli pcb create --backend native_xpedition --project X.prj --dry-run --compact
+xpedition-cli pcb annotate --backend native_xpedition --project X.prj --dry-run --compact
+xpedition-cli pcb info --backend native_xpedition --project X.prj --compact
+xpedition-cli pcb components --backend native_xpedition --project X.prj --compact
+```
+
+## First layout
+
+Forward-annotated parts are invisible until placed. The first layout is a
+handful of commands in this order; 1–7 are guarded writes, each `--dry-run` then
+`--confirm`, and 8–9 are reads to run directly:
+
+1. `pcb outline --width W --height H --radius 3`: a rectangle from the origin
+   with rounded corners, replacing the board's outline.
+2. `pcb holes`: a mounting hole in each corner; do it before the arrangement so
+   the planner keeps the corners clear (`--replace` once the outline has grown).
+3. `pcb arrange --design FILE`: one cluster per IC with its parts around it,
+   decoupling nearest, rows and columns on one pitch, centres on a 0.5 mm grid,
+   room above every part for its designator, clusters in rows by sheet,
+   connectors on the side edges with their designators inward, test points
+   along the bottom, a zone label per sheet from the design file's `zone`;
+   `--all` to move parts that are already placed; each part of a cluster stands
+   beside the IC pin it connects to, its own pad facing that pin. Its dry run
+   sizes the board: `summary.outside` names parts the outline could not hold,
+   which means a bigger outline (steps 1 and 2 again), not a smaller gap — 70 ×
+   48 mm held the 39-part board of the recorded end-to-end run on real
+   footprints, with room for every designator. A confirmed arrange deletes every
+   trace and via on the board first and reports what it removed; on a routed
+   board its dry run says `dangerous` and the confirm needs `--dangerous`.
+4. `pcb pour --net GND --layer 2`: a copper plane inset from the outline,
+   rounded like it; `--replace` after the outline changed.
+5. `pcb rules --class POWER --nets VBAT,+3V3 --width 0.5`: a net class with its
+   trace widths on every layer, written through Constraint Manager; supply nets
+   get 0.5 mm, signals keep the template's 0.254 mm; the result must say
+   `seen_by_layout`.
+6. `pcb route --layers 1,4`: Layout's autorouter on the outer layers only:
+   Route at effort 1–5, Via Min, Smooth; `--unroute` to start over.
+7. `pcb pour --net GND --layer 1` and `--layer 4`, the outer-layer ground
+   pours: after routing, never before: a pour in place makes the router count
+   the ground net as done while the copper leaves pins cut off.
+8. `pcb drc`: Layout's Batch DRC, every hazard listed with its kind, objects
+   and position; `errors` and `warnings` apart, `passes` when there are no
+   errors.
+9. `pcb render --output board.png`: the board drawn from its geometry in KiCad's
+   colours, `--side bottom` for the other side.
+
+The result of `pcb route` says `complete` and lists `unrouted` nets with their
+open count; a net that stays open next to a fine-pitch part is a rule problem
+(0.254 mm traces and clearances on the stock templates), not a router problem.
+Report a board as checked only when `pcb drc` says `passes` and you can name
+each warning kind and why it is acceptable (`ViasUnderParts` — vias under
+surface-mount bodies, tented — is; overlapping pads or partial nets are errors
+and are not).
+
+The placement is a starting point for a person, not a layout. `pcb arrange`
+lists each part's `x`/`y` in millimetres and `read_back` proves the placement.
+
+```bash
+xpedition-cli pcb outline --backend native_xpedition --project X.prj --width W --height H --radius 3 --dry-run --compact
+xpedition-cli pcb holes --backend native_xpedition --project X.prj --dry-run --compact
+# confirm the arrange only once its dry run leaves nothing in summary.outside
+xpedition-cli pcb arrange --backend native_xpedition --project X.prj --design design.json --dry-run --compact
+xpedition-cli pcb pour --backend native_xpedition --project X.prj --net GND --layer 2 --dry-run --compact
+xpedition-cli pcb rules --backend native_xpedition --project X.prj --class POWER --nets VBAT,+3V3 --width 0.5 --dry-run --compact
+xpedition-cli pcb route --backend native_xpedition --project X.prj --layers 1,4 --dry-run --compact
+xpedition-cli pcb pour --backend native_xpedition --project X.prj --net GND --layer 1 --dry-run --compact
+xpedition-cli pcb pour --backend native_xpedition --project X.prj --net GND --layer 4 --dry-run --compact
+xpedition-cli pcb drc --backend native_xpedition --project X.prj --compact
+xpedition-cli pcb render --backend native_xpedition --project X.prj --output board.png --compact
+```
+
+## Moving parts
+
+One part: `pcb move --refdes R1 --to x,y --rotate 90`. Its traces stay where
+they were, so check the routing afterwards (`pcb drc`, `pcb render`) and route
+again where it broke; Layout refuses a position that touches another part.
+Several parts, aligned or distributed: use the selected-placement workflow
+(`pcb placement-plan`, `pcb placement`) and read `reference/placement-tasks.md`,
+which states its native evidence and partial-execution boundaries. Never use
+`pcb arrange` for a small edit.
+
+```bash
+xpedition-cli pcb components --backend native_xpedition --project X.prj --compact
+xpedition-cli pcb move --backend native_xpedition --project X.prj --refdes R12 --to 34,35.5 --dry-run --compact
+```
+
+## Looking at the board
+
+`pcb show --output board.png` puts the board in front of the person; look at it
+yourself too. Layout opens the stock templates under the `Loc: Assembly Bottom`
+display scheme, which hides top-side parts, so a board that "looks empty" after
+annotation or placement usually needs this, not a fix; `pcb show` switches to
+`Loc: All On` (or `--scheme`). When the person looks at Layout's own screen,
+`pcb show --top-view`: the stock schemes draw the pours as outlines and every
+layer at once, so a poured, routed board looks bare and crowded until that
+scheme is picked.
+
+`pcb render --output board.png` needs no screen, unlike `pcb show --output`,
+which captures a black PNG while the desktop is locked. A render does not
+overwrite an existing file without `--replace`.
+
+## After a cell changed
+
+After `library build` changed a cell that is already on the board, annotate
+again and the part keeps its old cell: Layout never swaps the cell of an
+existing component. Recreate the board instead: `pcb create --replace`, then
+`pcb annotate`, `pcb outline`, `pcb holes`, `pcb arrange`, `pcb pour`, `pcb
+rules`, `pcb route`, the outer pours — about three minutes, all through the CLI.
+
+STOP CHECKPOINT: `pcb create --replace` archives the existing layout folder to a
+zip beside the project and deletes it. Confirm only with the user's go-ahead for
+that board (the confirm needs `--dangerous`), and report the archive path.
+
+## Handing over
+
+Placeholder cells are placeholders: right pin count and rough size, nothing a
+factory can use. Say so when handing over, and keep real cells from the
+company's library as the follow-up. With a fabrication package, also say that its
+README leaves board thickness, finish and mask colour to the board house
+(`pcb export` takes no such options); pass on any the person named separately.
+
+STOP CHECKPOINT: ask the user before confirming a board write they have not
+asked for, and before any that discards work: `pcb arrange` on a routed board (a
+confirmed arrange deletes every trace and via first; `--all` also moves the parts
+already placed), `pcb route --unroute`, `pcb unroute`, `pcb annotate --unroute`,
+`pcb pour --replace` or `pcb holes --replace` on pours or holes that were there
+before this task (redoing the ones this layout just made, after the outline grew,
+is part of the first layout), or any confirm whose preview lists something it
+deletes or removes. The ones whose preview says `dangerous` -- routing
+deleted with no archive, a layout replaced -- also need `--dangerous` next to the
+token; add it only after the user agreed to that loss.
+
+## References
+
+| Task | Read |
+| --- | --- |
+| Any board edit | `reference/pcb-conventions.md` |
+| Routing a net or a board by hand | `reference/hand-routing.md` |
+| Sending the board out | `reference/fabrication.md` |
+| Aligning or distributing a set of parts | `reference/placement-tasks.md` |
+
+## Eval Scenarios
+
+- Entry first: read `../xpedition-cli/SKILL.md` before any command; with it
+  missing, stop and ask before installing the family.
+- Schematic to board: package, create and annotate with a dry run each; done
+  only on `outcome: annotated` (`annotated_on_open`, `in_synch`) with matching
+  counts.
+- First layout: the outline grown until the arrange dry run leaves nothing
+  outside, holes before the arrangement, the outer ground pours only after
+  routing, and "checked" only when `pcb drc` passes with every warning kind
+  explained.
+- Work that goes: a confirmed arrange deletes all routing and `pcb create
+  --replace` archives the layout; both stop for the user, and `--dangerous` is
+  added only after the user agreed.
+- One part: `pcb move`, never `pcb arrange`, and the routing checked afterwards.
+- Boundary: a schematic drawing or BOM request is not this Skill's.

package/skills/xpedition-pcb/reference/fabrication.md

@@ -0,0 +1,26 @@
+# Fabrication package
+
+To send the board out: `pcb export --output DIR` (`--dry-run` then `--confirm`)
+writes Layout's ODB++, Gerber (RS-274X) and NC drill outputs and gathers them
+into `DIR`: `gerber/*.gbr` (empty and duplicate files left out), `drill/*.drl`,
+the ODB++ job as a zip, `centroid.csv`, `bom.csv`, `README.md` for the board
+house and `manifest.json` with `checks`. Report the package as ready only when
+`checks.ok` is true; `problems` names what is missing (a silkscreen, an outline,
+a drill layer). The first run on a board closes and reopens it in Layout to
+patch the output setups; later runs do not. The README leaves board thickness,
+finish and mask colour to the board house (`pcb export` takes no such options);
+pass on any the person names separately.
+
+`checks` covers what the package contains, not the board's design rules, so run
+`pcb drc` first: a board that does not pass is not ready to send.
+
+`manufacturing artifacts` and `manufacturing verify` read the artifact records a
+project stores, and `manufacturing bom` lists BOM rows built from its
+components; none of them produces files.
+
+```bash
+xpedition-cli pcb drc --backend native_xpedition --project X.prj --compact
+xpedition-cli pcb export --backend native_xpedition --project X.prj --output ./fab --dry-run --compact
+```
+
+Confirm with the same arguments and the returned token.

package/skills/xpedition-pcb/reference/hand-routing.md

@@ -0,0 +1,33 @@
+# Routing by hand
+
+For the person's layout, when the autorouter's is not good enough. Native
+commands name `--backend native_xpedition --project X.prj`; every write is a
+dry run first, then the same command with `--confirm <confirm_token>`.
+
+`pcb geometry --output board.json` gives every pad, pin, trace, via and plane;
+plan the traces yourself (a `PlanBuilder` from `xpedition_cli.routing_plan`
+resolves pin names and checks angles and clearances; `pcb stitch --geometry
+board.json --net GND` plans the ground vias without Layout, a plan to draw with
+`pcb trace --file`), then `pcb trace --file plan.json --geometry board.json`
+(`--dry-run` shows the nearest pin of every trace end and the offline check;
+`--confirm` draws; Layout's online DRC refuses an item that violates a rule and
+the result names it), read `opens_after` per net and `pcb render` to look. Fix a
+wrong piece with `pcb unroute --at x,y --layer N` (its confirm takes `--dangerous`:
+the routing it deletes is not archived) and draw it again; move a part
+with `pcb move --refdes R1 --to x,y --rotate 90`; when someone is watching
+Layout's screen, `--pace 0.15` on `pcb trace` / `pcb via` / `pcb arrange` makes
+the items land one at a time instead of in a burst; tidy the designators with
+`pcb labels`.
+
+Widths: 0.254 mm signals, 0.5 mm supply (the POWER class), 0.3 mm ground stubs
+(raise the default class's expansion width first). Keep 0.254 mm from any pad a
+via does not sit inside; a test point is a surface-mount pad, so an inner-layer
+run to it needs a via beside it; pour the outer layers after the traces are in,
+then stitch every ground pad with a via. A 39-part board took two rounds this
+way: 129 traces, 41 vias, DRC clean.
+
+```bash
+xpedition-cli pcb geometry --backend native_xpedition --project X.prj --output board.json --compact
+xpedition-cli pcb stitch --geometry board.json --net GND --output stitch.json --compact
+xpedition-cli pcb trace --backend native_xpedition --project X.prj --file plan.json --geometry board.json --dry-run --compact
+```

package/skills/xpedition-pcb/reference/pcb-conventions.md

@@ -0,0 +1,162 @@
+# PCB layout conventions for Xpedition Layout
+
+Defaults an agent applies when it creates or edits a board. Nothing here is
+enforced by the CLI: the Skill's commands create, place, route and check a board,
+but every value below is a **default** (industry practice) unless marked
+**verified**. Company rules supersede defaults: when `context` lists a
+knowledge-base document for board work, read it first (**TBD** marks where a
+company decision is still expected). `reference --compact` is the source of
+truth for commands.
+
+Contents
+
+1. Scope and units
+2. Stackup
+3. Net classes: width and clearance
+4. Vias
+5. Placement
+6. Routing
+7. Copper and planes
+8. Silkscreen, assembly and test
+9. Manufacturing outputs
+10. Checklist
+11. Sources
+
+## 1. Scope and units
+
+- Work in mm. Every `pcb` command and read takes and reports millimetres,
+  whatever unit the board displays; only a ChangeSet place or move without a
+  `unit` uses the board's current unit.
+- A board comes from the CLI: `library build --package` builds and packages the
+  parts, `pcb create` makes the board from a template through JobWizard and `pcb
+  annotate` forward-annotates it; the Skill has the order.
+- Produce ODB++ alongside Gerber: DFM and assembly tools commonly read it.
+
+## 2. Stackup
+
+| Layers | Order (top to bottom) | Use |
+|---|---|---|
+| 2 | SIG + GND pour, SIG + GND pour | simple boards without controlled impedance |
+| 4 | SIG, GND, PWR, SIG | default for MCU + USB + charger class boards |
+| 6 | SIG, GND, SIG, PWR, GND, SIG | when 4 layers cannot route or two reference planes are needed |
+
+- Every signal layer adjacent to a solid reference plane.
+- 1 oz (35 µm) outer copper by default; 2 oz for rails above 3 A.
+- Total thickness 1.0 or 1.6 mm unless mechanics say otherwise (TBD).
+
+## 3. Net classes: width and clearance
+
+Defaults for 1 oz copper; the fab's capability sheet sets the floor (TBD). The
+stock templates ship 0.254 mm width and clearance, and the Skill keeps signals
+there; the SIGNAL row is the target once the fab's capability sheet allows it.
+
+| Class | Width | Clearance | Notes |
+|---|---|---|---|
+| SIGNAL (default) | 0.15 mm | 0.15 mm | 6/6 mil; 0.1/0.1 mm only for BGA escape |
+| POWER | by current: ≥ 0.3 mm per A on outer layers, ≥ 0.6 mm per A on inner layers, 10 °C rise | 0.2 mm | IPC-2221 sizing; recompute for the real copper weight; pours preferred above 1 A |
+| USB2_DIFF | 90 Ω differential per stackup | pair gap per stackup | coupled and length-matched (§6) |
+| DIFF_100 | 100 Ω differential per stackup | pair gap per stackup | |
+| RF_50 | 50 Ω single-ended per stackup | | keep-out both sides |
+| HIGH_VOLTAGE | class width | per the IPC-2221 voltage table | battery packs and mains-adjacent nets |
+
+- Copper to board edge ≥ 0.3 mm; components to board edge ≥ 1 mm.
+
+## 4. Vias
+
+| Type | Drill / pad | Use |
+|---|---|---|
+| Standard | 0.3 / 0.6 mm | everything |
+| Minimum | 0.2 / 0.45 mm | dense escape only |
+| Power | at least 2 vias per ampere per layer change | rails |
+
+- No via in an SMT pad unless filled and capped; via to pad ≥ 0.2 mm.
+- A ground via next to every signal-layer change; a via fence every ≤ 5 mm
+  along RF sections and the board edge of RF boards.
+
+## 5. Placement
+
+- Mechanics first: connectors, switches, LEDs and mounting holes where the
+  enclosure needs them; keep-out ring ≥ 1 mm around mounting holes (TBD washer
+  size).
+- Decoupling: each supply pin has its capacitor ≤ 2 mm away on the same side
+  with the shortest path to a ground via; the smallest value closest to the pin.
+- Crystal ≤ 10 mm from its IC, nothing routed underneath, ground fill around it.
+- Switching converters (charger, boost): input capacitor, switch, inductor and
+  output capacitor in the smallest loop; the switch node is a small island.
+- Thermal: heat sources spaced apart and over copper; temperature sensors and
+  thermistors away from them at the distance the design note specifies.
+- Group by function following the schematic sheets; single-side SMT preferred,
+  bottom side for passives only when the assembly process allows (TBD).
+- Polarised parts oriented consistently.
+
+## 6. Routing
+
+- 45° bends or arcs; no acute angles, stubs or loops.
+- Continuous return path: no trace crosses a plane split; every layer change
+  has a nearby ground via.
+- Differential pairs routed together at the class gap; USB 2.0 intra-pair
+  mismatch ≤ 1.25 mm (common design-guide value; the platform guide wins).
+- Sensitive analog nets (battery sense, thermistor, regulator feedback) short
+  and away from switch nodes and inductors; the feedback divider next to the IC.
+- No routing under crystals, switcher inductors or antenna keep-outs; antenna
+  areas have no copper on any layer, per the module datasheet.
+
+## 7. Copper and planes
+
+- Solid ground plane unbroken under signal areas; power planes split only along
+  rail boundaries and never under a differential pair.
+- Ground pour on outer layers with stitching vias every ≤ 5 mm; no dead copper
+  islands.
+- Thermal reliefs on through-hole and hand-soldered pads; direct connection on
+  SMT power pads.
+- Pour clearance equals the class clearance; minimum pour width 0.2 mm.
+
+## 8. Silkscreen, assembly and test
+
+- A refdes on silk for every part, readable in at most two orientations, never
+  on pads or vias; text ≥ 0.8 mm high, line ≥ 0.15 mm (TBD fab capability).
+- Polarity and pin-1 marks for diodes, LEDs, electrolytic capacitors,
+  connectors and ICs.
+- Fiducials: 3 per SMT side, 1 mm copper dot with a 3 mm mask opening, ≥ 5 mm
+  from the edge; local fiducials for fine-pitch BGA and QFN.
+- Test points on rails, ground, UART, reset and battery sense: ≥ 1 mm pad,
+  2.54 mm pitch preferred, one side.
+- Solder-mask dam ≥ 0.1 mm between pads; mask expansion 0.05 mm unless the fab
+  says otherwise.
+- Panel rails, tooling holes and breakaway per the assembler (TBD).
+
+## 9. Manufacturing outputs
+
+ODB++ and Gerber X2, NC drill, IPC-D-356 netlist, pick-and-place centroid
+file, assembly drawing, fabrication drawing with stackup and notes, and the
+BOM — all from the same released revision.
+
+## 10. Checklist
+
+Classes: L2 from the netlist, L2b from geometry, manual needs an engineer.
+
+| ID | Check | Class |
+|---|---|---|
+| DP-01 | every schematic part placed; forward annotation has zero unresolved items | L2 |
+| DP-02 | DRC clean at the class rules | L2b |
+| DP-03 | decoupling ≤ 2 mm from its pin | L2b |
+| DP-04 | no plane split under differential pairs | L2b |
+| DP-05 | via count on power layer changes | L2b |
+| DP-06 | antenna, mounting and edge keep-outs respected | L2b |
+| DP-07 | silk clear of pads; polarity marks present | L2b |
+| DP-08 | fiducials and test points present | L2 |
+| DP-09 | thermal and sensor distances per design notes | L2b |
+| DP-10 | board netlist equals schematic netlist | L2 |
+| DP-11 | outputs generated from the released revision and reviewed | manual |
+
+## 11. Sources
+
+Versions unverified; cite by name until the edition in use is checked.
+
+- IPC-2221 generic design, IPC-2222 rigid boards, IPC-2141 controlled impedance.
+- IPC-7351 land patterns — the installation's Footprint Expert generates to it.
+- IPC-6012 fabrication acceptance, IPC-A-610 assembly acceptance, IPC-D-356
+  netlist.
+- Interface specifications: USB 2.0, I2C (NXP UM10204).
+- Company PCB design specification — the knowledge-base document `context`
+  lists for board work, when one is bound; it supersedes every default.

package/skills/xpedition-pcb/reference/placement-tasks.md

@@ -0,0 +1,28 @@
+# Local placement tasks
+
+Obtain the input schemas and preconditions of `pcb placement-plan` and
+`pcb placement` from `reference`. The native path has been smoke-tested on one
+disposable board, top side only (`reference`'s `release_readiness` says what that
+covers); that is
+not a reason to assume native compatibility or bypass engineer authorization.
+
+Prefer an explicit selected set and local transforms when adjusting an existing
+layout. Do not use whole-board arrangement as a substitute for a small edit: it
+has different effects on placement and routing. Determine the intended order,
+anchor and coordinate origin before planning; origin spacing is not body clearance.
+
+The native path reads a running Xpedition Layout session; `placement-plan` is
+offline and needs none. Check `doctor`'s `native_session` for what is attached
+before previewing, and start Layout explicitly rather than letting the command
+activate it.
+
+Preview, inspect every before/target and the native evidence status, then confirm
+only within the user's authorization. Do not override fixed/locked states. Check
+per-item results as well as the outer envelope. A failed or missing response can
+leave earlier changes or an unplaced part; do not replay or silently reconstruct
+the original write. Read the observed state and plan the remaining work explicitly.
+
+Native placement DRC is not full-board DRC. Moving a component does not repair its
+traces. Inspect routing, render the board, run the appropriate native checks, and
+record remaining warnings before handing off. Successful coordinate read-back
+is not a save/close/reopen durability test or a hardware sign-off.

package/skills/xpedition-pcb/test-prompts.json

@@ -0,0 +1,62 @@
+[
+  {
+    "id": "entry-skill-first",
+    "prompt": "Use xpedition-pcb to check the board in the running Layout session.",
+    "expected": "Read ../xpedition-cli/SKILL.md first and run context, doctor and reference as it says; check doctor's native_session for Layout before a native command."
+  },
+  {
+    "id": "schematic-to-board",
+    "prompt": "The schematic of the demo sensor board is drawn in Designer from design.json. Turn it into a board in Layout.",
+    "expected": "Start Layout with session start --backend native_xpedition --kind pcb; run library build --design design.json --package, pcb create and pcb annotate with --backend native_xpedition --project X.prj, each --dry-run then the same command with --confirm and the returned token; read back with pcb info and pcb components; report done only when pcb annotate says outcome annotated (annotated_on_open or in_synch also count) with no errors and the counts match the schematic."
+  },
+  {
+    "id": "first-layout",
+    "prompt": "Place the parts on the new board, route it and tell me whether it is clean.",
+    "expected": "Draw the outline and the holes first, dry-run pcb arrange and grow the outline (holes --replace) until summary.outside is empty, then confirm the arrange; pour GND on layer 2, set the POWER class and check seen_by_layout, route layers 1 and 4, pour the outer layers only after routing, then run pcb drc; call the board checked only when drc passes and every warning kind is named with why it is acceptable; present the placement as a starting point for a person, not a signed-off layout."
+  },
+  {
+    "id": "fabrication-package",
+    "prompt": "Send this board out for fabrication.",
+    "expected": "Read reference/fabrication.md; run pcb drc, then pcb export --output DIR --dry-run and confirm with the same arguments and the returned token; report the package ready only when drc passes and checks.ok is true, naming any problems; say the README leaves thickness, finish and mask colour to the board house, and pass on any the user gave separately."
+  },
+  {
+    "id": "rebuild-after-cell-change",
+    "prompt": "I changed the footprint of U3 and rebuilt the library. Update the board.",
+    "expected": "Explain that annotating again keeps the old cell, so the board is recreated with pcb create --replace; stop and ask before confirming it because it archives the layout folder to a zip and deletes it; with the user's go-ahead confirm with --dangerous as well as the token; report the archive path; then annotate, outline, holes, arrange, pour, rules, route and the outer pours again."
+  },
+  {
+    "id": "arrange-on-routed-board",
+    "prompt": "Two parts are still unplaced on the routed board. Run the arrange so they get placed.",
+    "expected": "Stop and ask first: a confirmed pcb arrange deletes every trace and via on the board before placing (its dry run says dangerous and the confirm would need --dangerous), so the routing would have to be redone. Offer pcb move for the two parts instead."
+  },
+  {
+    "id": "small-local-move",
+    "prompt": "Move R12 two millimetres to the left, nothing else.",
+    "expected": "Read R12's position with pcb components, then pcb move --refdes R12 --to <new x,y> with a dry run first; never pcb arrange for a small edit; confirm only with the user's authorization; its traces do not move with it, so check the routing afterwards with pcb drc or pcb render."
+  },
+  {
+    "id": "board-looks-empty",
+    "prompt": "I annotated the board but Layout shows nothing on it. Is it broken?",
+    "expected": "Not broken: forward-annotated parts are unplaced until placed, and the stock templates open under the Loc: Assembly Bottom scheme that hides top-side parts. Check placement with pcb components, and use pcb show (Loc: All On) or pcb render to look; do not try to repair the board."
+  },
+  {
+    "id": "hand-route-a-net",
+    "prompt": "The autorouter gave VBAT a long detour. Route it by hand.",
+    "expected": "Read reference/hand-routing.md; pcb geometry --output board.json; remove the detour with pcb unroute (its confirm deletes routing that is not archived and needs --dangerous, so ask first); plan the trace (PlanBuilder, 0.5 mm for a supply net), pcb trace --file plan.json --geometry board.json --dry-run, check the nearest pins and the offline check, confirm with the user's authorization, then read opens_after and look with pcb render."
+  },
+  {
+    "id": "schematic-request-boundary",
+    "prompt": "Draw a schematic for a 5 V to 3.3 V regulator with an I2C sensor.",
+    "expected": "Not this Skill: schematic drawing belongs to xpedition-schematic (its drawing conventions and design format); read ../xpedition-schematic/SKILL.md. Run no pcb command."
+  },
+  {
+    "id": "bom-request-boundary",
+    "prompt": "Export the BOM of this design as CSV.",
+    "expected": "Not this Skill: bom export belongs to xpedition-cli. Only inside a fabrication package does pcb export write bom.csv."
+  },
+  {
+    "id": "entry-skill-missing",
+    "prompt": "Check the board in the running Layout session. (The entry Skill is not installed here: ../xpedition-cli/SKILL.md does not exist.)",
+    "expected": "Stop before any command: the entry Skill this one builds on is missing. Tell the user and, once they agree, install the family with npx skills add fatecannotbealtered/xpedition-cli -y -g."
+  }
+]