AI Flow

{
  "name": "board",
  "title": "The board flow: parts placement to a qualified board",
  "scope": "Starts with component identity, reusable CAD review and native library assembly for an existing schematic/board. Reviews the selected model variants on camera before placement, then routes, pours, analyzes and delivers a bounded final video.",
  "steps": [
    {
      "name": "intake",
      "who": "ai",
      "does": "read the board and the spec, write the spec from the schematic if it is missing, plan; offer the optional Hydrogen progress widget (default off; enable when requested), reusing saved milestone images without extra AI calls",
      "record": "FIRST, the prompt: film the human's prompt being typed into the AI's input on the screen where it is typed (or, if it was typed before the run, save its exact text in run.json for a labelled re-enactment). The prompt states the design goal (part, input, output, current, molecule), never 'copy this video'. Then the board opening on the test box (capture open) and the spec being read. Skill aiflow-process-video.",
      "workflow": [
        "After EVERY board or model update, refresh and verify BOTH the native 2D editor and its linked 3D viewer before showing/reporting completion. Check exact saved board revision and actual rendered changes in both windows. Reload cached models; if reopening is required preserve unsaved user work, close only task-owned stale windows and retain one current editor/viewer pair. Never overwrite a newer disk edit from a stale editor. Use native bridge controls and keep foreground preferences."
      ]
    },
    {
      "name": "rules",
      "who": "both",
      "does": "Choose the fab and load its design rules before anything is drawn: the AI asks the human which fab builds the board (3rdPartyFab by default, JLCPCB on request) and loads that fab's rule profile into the EDA (KiCad .kicad_dru, Fusion DRC rules), so every later step designs to the process that will build it.",
      "binary": [
        "rules use",
        "rules check"
      ],
      "record": "the AI asking which fab and which design rules, the human's answer, then the rules loading in the EDA (Fusion's DRC dialog or KiCad's board setup) with the key numbers on screen",
      "workflow": [
        "Ask the human which fab will build the board and name the choices: 3rdPartyFab (default, Adom's own process; its rules are private, fetched with an Adom login and never restated on a public page) or JLCPCB (published 2-layer capabilities). Never guess: a board drawn to the wrong process is a respin.",
        "Then ask which rule set for that fab, and say they can switch any time: the fab's published limits (the default, nothing stricter or looser than the fab states), a variant someone published on top of it (`rules list` shows them, e.g. circuit-forge-strict, with its author and why), or their own preferences (bigger or smaller silkscreen text, wider tracks: a small JSON for `--prefs`, checked as warnings, never blocking). Never pick a stricter set for them.",
      "`adom-aiflow rules use --profile 3rdPartyFab` (or jlcpcb, or any pack; `--variant <name>` for a variant, `--prefs <file.json>` for their own preferences) writes the choice into the spec (fab.rules, fab.rulesVariant, fab.preferences), installs the KiCad rules beside the board and, on a Fusion run, loads the Fusion DRC rules into the open design. `rules check` must pass before placement.",
        "Say the rules out loud in the chat in plain words (minimum track, clearance, via, edge clearance) only for public profiles; for 3rdPartyFab say 'the 3rdPartyFab 2-layer rules are loaded' and nothing more."
      ]
    },
    {
      "name": "test-plan",
      "who": "ai",
      "does": "Think through how this board will be tested once it is built and on the probing workcell: the measurements a careful engineer would take (rails, switch node, feedback, ripple, enable, LEDs), the net each one needs, and a probe spot for every one. The binary checks each planned measurement has a probe-able spot (a 0.5 mm round test point or an exposed pad the pogo tip can land on, within 50 mm of a ground machine contact, not under a part body) and adds a test point to the netlist for every gap.",
      "binary": [
        "testplan check"
      ],
      "record": "the AI writing its test plan in the chat (what it will measure and why), then the binary's coverage table: each measurement, its net, its probe spot, and the test points it added",
      "workflow": [
        "Write tests.json: one entry per measurement {id, what, net, why, kind: dc|ripple|waveform|camera|ground, expect}. Think like the engineer at the bench: the input rail at the board, the output rail, the switch node, both inductor ends, feedback, enable, power-good, the bulk caps' ripple, every LED (camera), the ground pin. Use the circuit and the simulation, not a template.",
        "`adom-aiflow testplan check --tests tests.json` maps every measurement to a probe spot on the netlist (and on the board once it exists), and adds `TP<n>` test points (adom/testpoint-pad-0-5mm, 0.5 mm round exposed copper, no paste) for each gap. Rerun it after placement and before finish: a spot under a part body or out of tether reach is a gap again.",
        "Stephen's workcell numbers: smallest probing pad 200 um (pads under 300 um need a human crosshair check, so 0.5 mm is the default); two probes can work about 3 mm apart; every probed point within 50 mm of a MachineContactMedium ground contact; parts under a probed point under 18 mm tall."
      ]
    },
    {
      "name": "parts",
      "who": "ai",
      "does": "The chosen parts on the Adom wiki: every BOM row with an MPN matched to its wiki component page (symbol, footprint, STEP); a missing page is made before going on. Each page is shown in a Hydrogen tab as it is confirmed, so the viewer sees the parts being picked.",
      "binary": [
        "parts --show"
      ],
      "workflow": [
        "Run `parts --show` after the sourcing check passes: it reads that BOM, finds each MPN's wiki page and walks one Hydrogen tab through them.",
        "A part with no page: make it with the wiki-component skill (datasheet symbol, footprint and STEP, verified), then run `parts --show` again. Never substitute a similar part to dodge a missing page."
      ],
      "record": "Hydrogen with the Parts tab stepping through each component's wiki page, a few seconds each, then the parts list in the chat"
    },
    {
      "name": "project-page",
      "who": "ai",
      "does": "Revision 1 of the board's project page before any EDA work: README (what the board is, its requirements) with the component table linking every part's wiki page, and a KiCad PCM repository of all the parts (an Adom Cloud Library exported and repackaged), so KiCad installs them in one go.",
      "binary": [
        "project-page --page <owner/slug> --create"
      ],
      "workflow": [
        "`project-page --page <owner>/<slug> --create` (one page per board: later revisions update this same page; never a second page for the same board).",
        "Read the README it pushed and fix anything wrong in the summary or the table by hand; it opens in a Hydrogen tab."
      ],
      "record": "the project page opening in Hydrogen: the README, the component table, the PCM repository URL"
    },
    {
      "name": "components",
      "who": "ai",
      "does": "Audit wiki component identity, reusable CAD quality and redistribution evidence before placement; offer cached optional MPN-marked variants.",
      "binary": [
        "components"
      ],
      "workflow": [
        "Inventory every reference from the actual board and schematic: manufacturer, MPN, supplier code, package, value and ratings; group repeated exact parts and record their references. Do not invent an MPN or silently substitute a similar value/package. Distinguish populated parts, DNP parts and bare copper/mechanical features; a bare test pad needs no purchased component or fictitious 3D body.",
        "Search the wiki FIRST for each exact manufacturer/MPN and supplier code; reuse the matching component page and inspect its symbol, footprint and STEP/WRL assets. A page existing is not proof its CAD bundle is complete. Record the page URL and missing assets per reference.",
        "For missing identities or assets, use adom-parts-search next, then original manufacturer and distributor websites. Use Pup to navigate and download through the automated browser when curl/fetch is blocked or the site requires JavaScript; do not treat a blocked fetch as proof the part is unavailable. Read the relevant parts-search and Pup skills for current commands.",
        "Verify manufacturer, exact ordering code, package dimensions, pin numbering and required electrical ratings against source evidence before accepting CAD or a candidate part. Preserve source URLs and provenance. Label generated or approximate models as such; never present an approximate body as a verified vendor model.",
        "Global component pages are shared resources for ALL ADOM USERS, never a board-specific BOM dump. Create one only for a distinct reusable manufacturer part or independently specified reusable custom component, after searching for duplicates. Write a part-focused page with portable verified assets and provenance, and improve existing pages. Keep board references, unresolved identities, one-off land patterns, bare copper test pads and project-only assemblies inside the board project wiki page; do not create catalog placeholders or rename a one-off feature to make it appear global.",
        "Use portable project/library model paths, preserve placement and routing, rerun kicad_model_check and inspect the saved board in native KiCad 3D. Report reference coverage, reused/created page URLs, unresolved identities and missing CAD separately. A successful download or wiki publication alone does not close a missing-model finding.",
        "Judge quality per component, not per board screenshot: publish a linked visual register with top, bottom and oblique views. Check dimensions, units, terminal count and pitch, pin-1/polarity, body/pad alignment, standoff, materials and visible details. File resolution alone is not quality. Record pass, needs-work, reference-only or unknown with evidence and limits.",
        "Prefer manufacturer CAD when the source permits the intended redistribution. Keep third-party/Ultra Librarian downloads as private reference-only inputs unless redistribution is explicitly permitted. Compare independently generated models against manufacturer drawings and permitted reference views; retain dimensional deviations and source hashes. Converting, extracting, recoloring, or etching a restricted model does not make it independently authored or license-cleared.",
        "MPN marking is ON by default for ICs (John, 2026-09-30): every IC's 3D model carries its MPN laser-etched and finish checks it; passives are optional. Run `adom-aiflow-etch --in <model.step> --mpn <MPN> --out <model-etched.step> --footprint <part.kicad_mod>`: the mark planner places it (face, long axis, band between the terminations, size, reading direction from pin 1), the shared STEP service writes it (Adom.Chip + Adom.LaserEtch, flat, colours kept; nothing to install, no local OpenCascade), and the legibility gate checks it. Keep the plain model beside the marked one; `components --etch off` declines for a run. Marking is an identification aid, not the part's factory top mark.",
        "Cache reviewed artifacts on the existing global component page: source/plain STEP, optional MPN STEP, GLB, thumbnails and machine-readable provenance. Record input hash, generator/tool version, parameters, units, transforms, marking text/mode, reference evidence and review results. Cache keys must change when geometry, text or generator parameters change. Keep board-only transforms and mappings in the board project. Never claim cross-EDA parity without rendering the variant in the named native viewers.",
        "When publishing or improving a component page, make per-file provenance mandatory even though creating a new page is optional. Record original source URL/file and revision, retrieval date, source and output SHA-256, authoring classification (manufacturer-supplied, source-derived, AI-created, or unknown), generator/version and parameters, units/transforms, redistribution evidence and limitations. For AI-created geometry cite the actual datasheet page/figure/table and dimensions used, list simplifications and reference comparisons, and never present copied/extracted CAD as independent work. State which checks ran and which remain unverified; retain plain and marked variant lineage. Put a readable provenance section on the page plus a machine-readable asset record and a link to that component's issue tracker. Unknown provenance stays unknown, not a fabricated source. Reuse/improve existing pages first; offer new global-page publication only for reusable components, keeping board-specific records in the project.",
        "Marking checklist (laser-etched MPN): (1) let the planner place it: `adom-aiflow-etch --in part.step --mpn MPN --out part-etched.step --footprint part.kicad_mod` (`adom-aiflow-etch plan ...` shows the plan first); never hand-pick an axis or a rotation. (2) The rule it enforces: the mark runs along the longest usable dimension of the marking face (chip R/C/L: along the body between the end caps; ICs: parallel to the pin rows; LEDs: the front long side wall, window clear), as large as fits (one line; two equal lines only when both are larger), upright and left to right in the standard pose (pin 1 / pad 1 lower left seen from the top; the iso outline shows pin 1 toward the viewer), a flat light mark coplanar with the face in Adom.Chip / Adom.LaserEtch, never raised or recessed lettering. (3) The chip outline's name is the same mark: `adom-aiflow-etch outline part.step --etched part-etched.step --footprint part.kicad_mod` (adom-chip-thumbnailer does the same), never a hand-picked /outline rot. (4) Run the gate and look: `adom-aiflow-etch check part-etched.step --outline <named.svg>` must say PASS; open <etched>.check.png and the outline at 320 px before you report; a FAIL's Hint lines say what to rerun. (5) `--along` is only for keeping a polarity stripe or printed band clear (the tool warns, the gate still judges against the planner); a vendor model that already prints its marking stays as it is. Every part with an MPN gets the mark, passives included. LED models carry their lens colour from the datasheet's dominant wavelength, softened (the Adom basic-part LED pages ship that coloured STEP as the default). Swapping a model into the board: the board file must point at the etched STEP (check `(model ...)` for every marked ref, including parts that used a KiCad stock model), then show it with `kicad-cli pcb render` before and after, since the desktop 3D viewer cannot be filmed while another window covers it.",
        "Offer the optional Hydrogen progress widget. If enabled, reuse saved component, marked-model, symbol and later board/analysis thumbnails via widget event; do not generate extra screenshots or call a model solely for the widget. Respect widget disable immediately.",
        "Before accepting a wiki component, read its actual native model_3d and STEP bindings and hash the referenced downloads against the reviewed variants. Wait for the native viewer to finish painting, then inspect the visible body and readable mark; nonzero meshes or a successful HTTP request do not prove a painted model. Check the static hero too. Use a descriptive manufacturer/MPN/function title in both page.json and package.json; follow wiki-component and preserve other contributors and original files.",
        "A resolved 3D file may still be hidden by native EDA appearance filters (for example KiCad excludes models not in position files). Check those filters before inventing replacement parts or changing BOM/placement flags. Keep bridge-specific visibility, binding and native audit operations in the owning bridge; report missing capabilities there. Explicit rights-holder permission may authorize a derivative despite a restrictive package default; record who authorized what and its scope, without extending it to third-party assets.",
        "Read component-hero from adom/component-hero and the current wiki-component guidance, including state/appearance rules for LEDs. Component wiki heroes need separate nonphysical teal dashed COPPER boundaries (alpha 0.50), actual silk (0.30), and mapped signal labels (0.50); preserve physical pin1, MPN, animations and lights. Keep board-use models clean. Run the component-hero package generator (skills/component-hero/scripts/hero_glb.py in its source repo), inspect its alignment result and overlay sidecar, then inspect published top/underside/pin1 and native LED surfaces. Rediscover stale tool references rather than inventing commands. Raised LED skins must have verified non-coplanar clearance, including the MPN; STEP color is not a light. Record source, footprint, pin map, font and generator hashes. Never claim structural checks establish visual or electrical qualification."
      ]
    },
    {
      "name": "libraries",
      "who": "ai",
      "does": "Assemble and validate the reviewed symbols, footprints and selected model variants in the chosen EDA before placement.",
      "workflow": [
        "Use the components register to build a portable project library for the actual EDA (KiCad, Altium or Fusion). Verify symbol pin numbers against footprint pads, package dimensions and pin-1/polarity; resolve model transforms and selected plain or marked STEP paths. Record native tool/version and evidence per part.",
        "Keep board reference mappings and native project transforms in the board project, while reusable source CAD and provenance remain on their existing global component pages. Do not claim native EDA support from a GLB gallery or a file extension alone.",
        "Return to components with --back --why when identity, rights or geometry cannot be resolved; preserve honest unknowns and report the affected references."
      ],
      "record": "Native library review with the selected symbol, footprint and model; saved verification evidence belongs with the library register."
    },
    {
      "name": "models",
      "who": "ai",
      "does": "Check native board model resolution and inspect the selected library variants in the chosen EDA; use the component register for unresolved assets.",
      "binary": [
        "models"
      ],
      "record": "Native board 3D inspection and model-check evidence; the separate library-tour step reviews each selected component.",
      "workflow": [
        "Use the components register and its reviewed plain or explicitly selected marked variants; fix portable model paths, run kicad_model_check, then inspect the native board render. Do not substitute a model merely to make the missing-file gate pass.",
        "`models` also checks every bound model is right way up (step2glb bbox after the footprint's rotate/offset): a flat SMD chip whose thinnest axis is not Z, or an SMD body whose bottom is off the board, is a warning to fix in the binding and verify in the native 3D viewer, or to acknowledge with `models --ack <refs> --why ...`; finish refuses open ones. Never adom-chipsmith.",
        "After EVERY board or model update, refresh and verify BOTH the native 2D editor and its linked 3D viewer before showing/reporting completion. Check exact saved board revision and actual rendered changes in both windows. Reload cached models; if reopening is required preserve unsaved user work, close only task-owned stale windows and retain one current editor/viewer pair. Never overwrite a newer disk edit from a stale editor. Use native bridge controls and keep foreground preferences.",
        "Read component-hero from adom/component-hero and the current wiki-component guidance, including state/appearance rules for LEDs. Component wiki heroes need separate nonphysical teal dashed COPPER boundaries (alpha 0.50), actual silk (0.30), and mapped signal labels (0.50); preserve physical pin1, MPN, animations and lights. Keep board-use models clean. Run the component-hero package generator (skills/component-hero/scripts/hero_glb.py in its source repo), inspect its alignment result and overlay sidecar, then inspect published top/underside/pin1 and native LED surfaces. Rediscover stale tool references rather than inventing commands. Raised LED skins must have verified non-coplanar clearance, including the MPN; STEP color is not a light. Record source, footprint, pin map, font and generator hashes. Never claim structural checks establish visual or electrical qualification."
      ]
    },
    {
      "name": "library-tour",
      "who": "ai",
      "does": "Review each selected component model in motion and produce a separate short library overview for the final video.",
      "workflow": [
        "Use tools/library-tour.py with the reviewed library.json, --run and --ai-thread. The manifest must identify the same plain or explicitly chosen marked variants and hashes that the native board uses. A marking choice does not authorize silent plain-model fallback.",
        "Inspect the detailed orbit tour and the moving overview in a rendered browser. Reject blank, clipped, wrong-variant or static clips; retain raw recordings and contact sheets. The detailed tour stays separately linked for component review.",
        "Budget approximately five seconds for the moving overview within the entire final video limit of 120 seconds. Do not insert the whole BOM walkthrough or one wiki-page shot per part into the final video. Optional scrolling wiki-page clips belong in the separate detailed review.",
        "Automatic overview selection in released compose requires the complete maintained release source (issue #16); until integrated, report that limitation explicitly and keep the reviewed clips and selection manifest available for integration.",
        "Read component-hero from adom/component-hero and the current wiki-component guidance, including state/appearance rules for LEDs. Component wiki heroes need separate nonphysical teal dashed COPPER boundaries (alpha 0.50), actual silk (0.30), and mapped signal labels (0.50); preserve physical pin1, MPN, animations and lights. Keep board-use models clean. Run the component-hero package generator (skills/component-hero/scripts/hero_glb.py in its source repo), inspect its alignment result and overlay sidecar, then inspect published top/underside/pin1 and native LED surfaces. Rediscover stale tool references rather than inventing commands. Raised LED skins must have verified non-coplanar clearance, including the MPN; STEP color is not a light. Record source, footprint, pin map, font and generator hashes. Never claim structural checks establish visual or electrical qualification."
      ],
      "record": "Two separate raw clips: a detailed component orbit tour and a roughly five-second moving overview. No title pages or baked captions; the final composer supplies its own overlays."
    },
    {
      "name": "placement",
      "who": "ai",
      "does": "place the parts for routability, current and heat; the binary packs, checks courtyards and lands moves; reserve visible space for connector labels and the two-sided service silkscreen; the switch-node check refuses switch copper under another part or a switch loop longer than the spec allows, and sends the AI back here",
      "binary": [
        "place pack",
        "place check",
        "land moves"
      ],
      "record": "the parts landing ONE AT A TIME (land moves): each part is its own undo step, so the camera sees the board fill up part by part, never an empty board that is suddenly full"
    },
    {
      "name": "routing",
      "who": "binary",
      "does": "route to 100 percent with the spec's rules, gate with KiCad's DRC, land as undo steps; the AI takes it with take route=ai",
      "binary": [
        "route",
        "gate",
        "land route",
        "land vias"
      ],
      "record": "the traces drawn ONE AT A TIME (land route), then the vias: a net with several paths lands as several undo steps, so every trace is seen being drawn; the longest clip, the one viewers speed up"
    },
    {
      "name": "thermal-vias",
      "who": "binary",
      "does": "Heatsink vias where the heat is: for every part that dissipates real power (the regulator, the inductor, the catch diode, the FETs), an array of vias in its thermal pad or the copper it dumps heat into, stitched to the ground or the plane on the other side, sized and counted from its dissipation; the AI reviews the plan and the binary lands it.",
      "binary": [
        "thermal-vias plan",
        "thermal-vias land"
      ],
      "record": "the via arrays landing one part at a time beside the hot parts, then the count per part against its target",
      "workflow": [
        "`adom-aiflow thermal-vias plan` estimates each hot part's dissipation (spec loads, the datasheet's efficiency or Rds(on), the inductor's DCR) and proposes an array: count, drill, pitch, the net it stitches (usually GND), in the part's thermal pad or the copper beside its hottest pin. Never on the switch node.",
        "Review it: add vias where a part's heat has nowhere to go; then `thermal-vias land`. The thermal step and finish refuse while a hot part is below its target."
      ]
    },
    {
      "name": "pours",
      "who": "binary",
      "does": "pour every net the spec names, keepouts along Kelvin taps, thermal and stitching vias, land, measure the copper kept",
      "binary": [
        "pour",
        "land pours",
        "measure"
      ],
      "record": "the pours filling in (land pours) and the copper readback; keep the DRC refusals in the clip, they are the story",
      "workflow": [
        "Keep the copper (Drew, 2026-11-14, every board; docs/keep-copper.md): the 3rd party fab ablates whatever copper the board does not keep, so pour GND over the free area on both layers and remove no island silently: tie each orphan to GND on its own layer or widen the adjacent trace into the gap, and add a new via only when the island is worth a hole. Leave copper out only where its absence is the feature (mutual coupling, high-impedance analog inputs, RF and antenna keep-outs, controlled-impedance spacing, the switch node), as a named keepout in spec.pours. Report the copper kept and the area left to ablate per layer, before and after."
      ]
    },
    {
      "name": "outline",
      "who": "binary",
      "does": "Round the board's corners: every sharp outline corner becomes a radius (1.0 mm by default, spec outline.cornerRadius), so the board is kind to hands, panels and the fab's router.",
      "binary": [
        "outline round"
      ],
      "record": "the board corners changing from sharp to round in the editor",
      "workflow": [
        "`adom-aiflow outline round` replaces each sharp outline corner with an arc of the spec's radius (default 1.0 mm), keeps copper clear of the new edge, and lands it. finish refuses a board with a sharp outside corner."
      ]
    },
    {
      "name": "current",
      "who": "binary",
      "does": "IPC-2221 on every loaded net, pour and via capacity, the same-layer rule; then the AI's own current density drawing and a walkthrough of the pours it judged",
      "binary": [
        "analyze current",
        "artifact --kind analysis-image",
        "tour nets --nets <the pour nets>"
      ],
      "record": "the analysis table on the board, then the AI's current density drawing (fullscreen in the video, the one place it leaves the editor), then each pour net lit and framed"
    },
    {
      "name": "thermal",
      "who": "binary",
      "does": "copper and vias at every hot tab against the rise budget; then the AI's own temperature rise drawing and a walkthrough of the pours it judged",
      "binary": [
        "analyze thermal",
        "artifact --kind analysis-image",
        "tour nets --nets <the pour nets>"
      ],
      "record": "the hot tabs and their copper, the AI's heat map fullscreen, then each pour net lit and framed; when it fails, the return to pours or placement is the clip worth keeping"
    },
    {
      "name": "fields",
      "who": "both",
      "does": "the fields on the board: adom-fields solves the current density of every loaded net, the heat flow in each copper layer with the vias, and the temperature over the board; the AI reads the issues and walks the board in the app on camera",
      "binary": [
        "adom-fields analyze",
        "adom-fields serve",
        "tour fields"
      ],
      "record": "the Adom Fields window: the board in 3D drifting gently through each beat, the heat on the top copper, each pour isolated on its own, the board turned over to the bottom, the temperature, then an issue or two; slow on purpose, the final video plays it at ten times speed"
    },
    {
      "name": "nets",
      "who": "binary",
      "does": "the copper pour walkthrough: every poured net (and every loaded, wide or Kelvin net) highlighted on its own in turn, the board framed, so the viewer sees where each net's copper is; the AI names each one",
      "binary": [
        "tour nets"
      ],
      "record": "the editor with one net lit at a time, all of the pour nets in sequence, the board framed; the chat names the net"
    },
    {
      "name": "silkscreen",
      "who": "ai",
      "binary": ["silkscreen-layout", "silkscreen-audit --record"],
      "does": "Make both faces useful in real service: references and values, verified connector and machine-contact pinouts, polarity, board identity and bring-up labels; review native plots and assembled visibility. Offer the optional shared silkscreen dashboard: real solver events, candidate reasons, live/replay separation, fitted-model inspection and separately recorded detailed/5s replays. Audit every fitted body and every via/hole across the whole board, both faces, with coverage counts. Missing Fab geometry is not free space; native DRC does not establish fitted visibility. Keep unresolved labels explicit and do not apply an incomplete layout. Native geometry/edit/undo/refresh belongs to the EDA bridge.",
      "workflow": [
        "Read the 3rd party fab silkscreen skill for the selected process; reserve label space during placement and finalize after copper and analysis stabilize. Use both faces, a clear font-size hierarchy, and the approved process profile for small secondary text.",
        "Build a source-backed label manifest from actual schematic, pad numbers, nets and approved requirements. Include reference/value pairs, connector pinouts, power polarity, test points, switch/LED functions, revision and documentation link. Never infer voltage/current ratings from net names or component absolute maxima.",
        "For every machine pin, machine contact and edge-pin connector, repeat its reference/pin number and verified signal or power function on BOTH faces. A mounted board may expose only one side during debugging. Put the repeated labels beside the same physical connection where possible; when crowded, use a short clear leader to the actual connection on that face; a remote keyed legend is supplementary only. A pinout table on the other face alone does not satisfy this check. Review both faces in the mounted-access context, with bottom text correctly mirrored and pin numbering preserved.",
        "Every test point MUST have visible silkscreen identifying both its reference and verified net/signal or measurement function. Prioritize these labels before ordinary component values. Keep them adjacent to the accessible probe pad, or use a short unambiguous leader/key on the same accessible face when crowded. Check complete test-point coverage against the actual board; missing or ambiguous labels are unresolved findings, never silently omitted. Repeat on the opposite face when useful for mounted-board debugging, without implying a probe pad exists there.",
        "Keep each reference unmistakably associated with its own component. Prefer reducing reference font size locally over moving a label farther away. Aim for complete reference coverage; use a short clear leader only when proximity alone is ambiguous. Treat approximately 0.8 mm as an initial reference size, not a minimum. For dense 3rd party fab artwork Adam explicitly permits secondary values at 0.3 mm or even 0.2 mm (2026-09-16); try 0.5, 0.3 then 0.2 mm while preserving the ref/value pairing and required stroke/spacing. These tiny sizes are user-requested artwork options, not independently verified laser-process capability. Keep the actual sizes and any unresolved physical legibility/DFM limits in the review; do not silently omit labels or globally weaken fab rules. Inspect the result at actual size and close-up.",
        "Avoid mask openings, contact surfaces, holes, fiducials and bodies that hide labels. Inspect bottom mirroring, actual-size legibility and both native 2D/3D faces. Use EDA bridge text/plot/DRC operations; give missing primitives back to the bridge.",
        "Run native DRC against the chosen fab profile and compare with the baseline. Preserve connectivity, placement, copper, outline and model transforms for silk-only edits. Register the label manifest and top/bottom evidence; return here when placements or pinouts change.",
        "Record BEFORE the first silkscreen mutation: show labels appearing individually or in small meaningful groups, pairing references with smaller values. Film actual moves, resizing, rotations and overlap corrections in order; preserve a timestamped operation/reason sidecar and raw uncaptioned footage. Use native bridge edits and refresh, never invented verbs. If native incremental editing is missing, file the bridge gap; identify any checkpoint reconstruction as a replay, never as original live placement. Keep a detailed action cut and use 3–5 seconds of accelerated population/rework in the final 120-second film. Read docs/silkscreen.md for recording and evidence rules.",
        "Require positional contact labels on BOTH faces: a pinout table is supplementary, never a substitute for text beside each actual machine contact, machine pin or edge connection. Separate primary reference (MC10) and smaller secondary function (DSHOT) as independently sized paired text. Prefer consistent reading directions. Where association remains ambiguous, add a short gentle curved silkscreen leader ending outside the intended pad mask opening; avoid crossings and obstacles. Verify one-to-one pad association, bottom mirroring, label/leader clearance and legibility in close-up native views and DRC. Film real additions and rework; retain mapping and unresolved constraints. See docs/silkscreen.md.",
        "For the requested 3rd party fab profile, attempt a nearby value for EVERY resistor and capacitor, including rotated components and references. Search both orientations and adjacent sides at 0.5, 0.3 and 0.2 mm as needed, preserving an unmistakable reference/value association. Do not skip values merely because the reference is rotated, an initial placement fails, or a bottom table exists. Repack nearby silk or use a clear short leader when necessary. Audit actual-board value coverage and report each unresolved value explicitly; a back-side key is supplementary, not completion. Retain native mask/overlap checks and distinguish requested artwork sizes from measured physical legibility.",
        "After EVERY board or model update, refresh and verify BOTH the native 2D editor and its linked 3D viewer before showing/reporting completion. Check exact saved board revision and actual rendered changes in both windows. Reload cached models; if reopening is required preserve unsaved user work, close only task-owned stale windows and retain one current editor/viewer pair. Never overwrite a newer disk edit from a stale editor. Use native bridge controls and keep foreground preferences.",
        "Search space before shrinking text: 0.2 mm is a last resort. Use native text bounds and per-face body/pad/mask/via/silk obstacles, keep separate boxes for ref/value pairs, repack neighboring labels, preserve pin-row order and validate leader paths. Run silkscreen-layout on candidates; bounded search is not native verification. Apply by stable item ID, compare native DRC with baseline, inspect fitted visibility, and refresh BOTH native views. See docs/silkscreen.md.",
        "KiCad lane: `adom-aiflow silkscreen-audit --input <audit.json> --out <result.json> --record` is the step's proof. It is recorded only when the whole-board audit passes and its inventory names every footprint by its reference and a via or hole item for every via, with at least 0.5 visible labels per footprint (Fusion: `fusion silkscreen`)."
      ],
      "record": "Native incremental label population on both faces, individual ref/value pairs or meaningful groups, plus real rework. Raw uncaptioned clip and timestamped edit sidecar; detailed action cut separate from the 3–5 second final-video excerpt. Clearly label reconstructed replay.",
      "hints": [
        "Final documentation pass: prefer open interior regions for a verified board description and ordered left-aligned service blocks. Physical pin/contact labels remain local. Apply docs/silkscreen-priority-pass.md; inspect interior alternatives at readable fonts and report explicit edge fallbacks. Native Rust silkscreen-sections performs the documentation solve; preflight, native DRC and both EDA views still gate acceptance."
      ]
    },
    {
      "name": "3d",
      "who": "binary",
      "does": "the 3D walkthrough: the viewer opened from the editor, then fit, top, tilt, orbit, zoom in, swing, front, bottom, flip, top, fit, all by menu command, no mouse",
      "binary": [
        "tour 3d"
      ],
      "record": "the 3D Viewer window itself: the board turning, the components up close; full of motion, so the action cut keeps most of it",
      "workflow": [
        "After EVERY board or model update, refresh and verify BOTH the native 2D editor and its linked 3D viewer before showing/reporting completion. Check exact saved board revision and actual rendered changes in both windows. Reload cached models; if reopening is required preserve unsaved user work, close only task-owned stale windows and retain one current editor/viewer pair. Never overwrite a newer disk edit from a stale editor. Use native bridge controls and keep foreground preferences."
      ]
    },
    {
      "name": "mechanical-review",
      "who": "ai",
      "optional": "only when the spec or requirements declare mechanicalReview",
      "does": "Only when the spec or requirements declare mechanicalReview: the mechanical service-access review before assembly export: every service fastener with its real tool, approach, retention and removal order, and every access hole sized for the tool and the extracted part with explicit clearance. The binary runs adom-aiflow-mechanical lint on the declared review file and records the passing result bound to the review file, spec and board hashes.",
      "binary": [
        "review mechanical"
      ],
      "record": "the review file and the tool's PASS in the terminal; an optional tool animation, labelled illustrative",
      "workflow": [
        "Declare it during component selection or placement when the board has service fasteners, underside screws, mounting holes a tool must reach, or parts that must come out after assembly: spec mechanicalReview {\"schemaVersion\": 1, \"input\": \"<review.json>\", \"refs\": [\"H1\", \"J3\"]}. The input has \"schemaVersion\": 1 and a fasteners list in the adom-aiflow-mechanical format (docs/mechanical-wiring-reviews.md).",
        "`adom-aiflow review mechanical` runs the tool (on PATH, or AIFLOW_MECHANICAL_SRC=<clone> with cargo). Exit 1 is unresolved review work, not permission to waive it. Never set a Boolean true to satisfy the linter: link the CAD check report and review it.",
        "The tool checks declared completeness and dimensions only. It does not solve swept volumes or collisions and is not physical-fit evidence; say so when you report.",
        "Tool animation is optional; required service clearance is always checked. A board adoption that moves a named part or any hole voids this review and the test plan: run both again."
      ]
    },
    {
      "name": "wiring-review",
      "who": "ai",
      "optional": "only when the spec or requirements declare wiringReview",
      "does": "Only when the spec or requirements declare wiringReview: the wiring review before assembly export: every installed harness and factory lead once, its pin and colour map from supplier evidence, terminal fit, latch release, mating force in newtons, bend radius, retention, neighbouring connector service corridors and cut length. The binary runs adom-aiflow-wiring lint (and audit-glb on the exported assembly when declared) and records the passing result bound to the review file, spec and board hashes.",
      "binary": [
        "review wiring"
      ],
      "record": "the harness table and the tool's PASS in the terminal; an optional mate/unmate animation, labelled illustrative",
      "workflow": [
        "Declare it when the board takes harnesses, fan or sensor leads, or wire-to-board connectors: spec wiringReview {\"schemaVersion\": 1, \"input\": \"<wiring.json>\", \"refs\": [\"J9\"], \"glb\": \"<assembly.glb>\" (optional)}. The input has \"schemaVersion\": 1 and a harnesses list in the adom-aiflow-wiring format; each harness may name its board connectors in \"connectors\".",
        "`adom-aiflow review wiring` runs the tool (on PATH, or AIFLOW_WIRING_SRC=<clone> with cargo). Unknown force, overlength leads, duplicate conductors or endpoints, a pin count mismatch and missing neighbouring service clearance are findings to fix, not to waive.",
        "Prefer moving the connector near the wire exit over a long detour. A moved connector voids this review, the test plan, and (through the copper change) routing, DRC, current and thermal evidence: redo them.",
        "The tool checks declared completeness and lengths only; it is not a collision solver. Inspect the live viewer for stale wire meshes as well."
      ]
    },
    {
      "name": "capture",
      "who": "binary",
      "does": "window recording with markers, so every engine's video lines up",
      "binary": [
        "capture open",
        "capture start",
        "capture mark",
        "capture stop"
      ],
      "record": "this step is the recorder itself: every step's clip is a window capture of the PCB editor, started when the step is declared"
    },
    {
      "name": "finish",
      "who": "both",
      "does": "finish refuses until everything is true; the AI cuts the video and delivers",
      "binary": [
        "finish",
        "deliver"
      ],
      "record": "the finish line passing (0 unconnected, 0 new errors), then the cut video and the delivery message. Before delivering, record the run's cost for the process video: model calls and tokens (input, cache reads, cache writes, output) from the AI's own session logs inside the run's clock window, sub-agents included; plan-limit percentages are not a cost. Then build the process video per skill aiflow-process-video: every scene loaded into video-post's storyboard for per-clip review before assembly."
    },
    {
      "name": "export",
      "who": "both",
      "does": "The finish line for the human: Gerbers, drill, BOM and pick-and-place (CPL) written from the finished board, checked, and announced in the chat with where every file is.",
      "binary": [
        "export"
      ],
      "record": "the AI's prompt asking for the files, the export running, then the chat listing every file with its path and saying they are good to go",
      "workflow": [
        "`adom-aiflow export` (Fusion: `fusion export`) writes the manufacturing set, re-reads every file (layer count, drill hits, BOM refs against the board, CPL refs and rotations) and refuses a set that does not match the board. KiCad lane: kicad-cli through ADOM_AIFLOW_KICAD_CLI (adom-aiflow-kicad-cli-remote in a container) writes the Gerbers, drill and CPL into <run>/manufacturing; the BOM is built from the board's footprints. The proof records what was checked; bottom-side CPL rotations are counted, not compared."
      ]
    }
  ],
  "returns": "any step may send the AI back to any earlier step: step <name> --back --why \"...\"",
  "later": [
    {
      "name": "part-selection",
      "does": "choose the parts from the requirements; SPICE may send the AI back here"
    },
    {
      "name": "schematic",
      "does": "the schematic, and the spec that falls out of it"
    },
    {
      "name": "simulation",
      "does": "SPICE on the critical loops before the board exists"
    },
    {
      "name": "moleculize",
      "does": "machine pins so the board lives in the probing workcell; the STEP exported with pads and mask, step2glb convert --molecule, then real copper pads from the footprints' pad, mask and paste layers (board-glb copper, with its gate)",
      "binary": [
        "molecule check",
        "board-glb copper",
        "board-glb check"
      ]
    },
    {
      "name": "paste",
      "does": "solder paste jetting calculations"
    },
    {
      "name": "probe",
      "does": "how to probe the board when it comes off the 3rd party fab process"
    }
  ],
  "clips": "every `step <name>` stops the previous step's clip and starts a new window recording tagged with the step, when the board is open on a test box; run.json captures[] carries one entry per clip with its step, start, stop and file, and deliver lists them; the final video is cut from these clips, one segment per step, so two engines' videos line up step for step; a return (step <name> --back --why) is a new visit and gets its own clip, tagged <step>-<visit> with the reason, so the rework is on camera and the final cut can show the loop",
  "screenshots": "every step visit gets two background screenshots of the editor window, at its start and at its end (shot-<step>-<visit>-start.png, shot-<step>-<visit>-end.png), logged as artifacts, so a run's own README has a picture for every step without anyone taking one",
  "sequence": {
    "_": "The required steps in order, per lane. `step <x>` refuses to skip a required step before x; a return (`step <k> --back`) makes every later required step a redo; finish refuses until the chain is in order and each step's proof is recorded during its last visit. An Altium run also puts the parts on the wiki and the board on its project page before its library step (the library is built from those pages). kicad-new is a KiCad board from scratch (the run starts with no board): the parts go on the wiki and on the board's project page, KiCad installs them as one PCM library, and the schematic is drawn in KiCad before the board exists. pattern is a passive copper-pattern KiCad board with no parts, BOM, schematic or electrical load (`intake --kind pattern`, or requirements.json \"boardKind\": \"pattern\"): the electrical steps do not apply, finish runs the live native DRC with the fab rules and reports each step it left out and why. A board with pads on nets that need routing is refused this lane.",
    "altium": [
      "intake",
      "rules",
      "design",
      "test-plan",
      "sourcing",
      "parts",
      "project-page",
      "library",
      "schematic",
      "simulation",
      "placement",
      "routing",
      "thermal-vias",
      "pours",
      "outline",
      "current",
      "thermal",
      "fields",
      "nets",
      "silkscreen",
      "3d",
      "finish",
      "export"
    ],
    "fusion": [
      "intake",
      "rules",
      "design",
      "test-plan",
      "sourcing",
      "library",
      "schematic",
      "simulation",
      "placement",
      "routing",
      "thermal-vias",
      "pours",
      "outline",
      "current",
      "thermal",
      "fields",
      "nets",
      "silkscreen",
      "3d",
      "finish",
      "export"
    ],
    "kicad": [
      "intake",
      "rules",
      "components",
      "libraries",
      "models",
      "test-plan",
      "placement",
      "routing",
      "thermal-vias",
      "pours",
      "outline",
      "current",
      "thermal",
      "fields",
      "nets",
      "silkscreen",
      "3d",
      "finish",
      "export"
    ],
    "kicad-new": [
      "intake",
      "rules",
      "design",
      "test-plan",
      "sourcing",
      "parts",
      "project-page",
      "library",
      "schematic",
      "simulation",
      "components",
      "models",
      "placement",
      "routing",
      "thermal-vias",
      "pours",
      "outline",
      "current",
      "thermal",
      "fields",
      "nets",
      "silkscreen",
      "3d",
      "finish",
      "export"
    ],
    "pattern": [
      "intake",
      "rules",
      "models",
      "outline",
      "silkscreen",
      "3d",
      "finish",
      "export"
    ]
  },
  "proofs": {
    "_": "outcomes a step must record during its latest visit (any one of the list)",
    "parts": [
      "parts"
    ],
    "project-page": [
      "project-page"
    ],
    "rules": [
      "rules"
    ],
    "test-plan": [
      "testplan"
    ],
    "placement": [
      "place-land"
    ],
    "routing": [
      "land-route"
    ],
    "thermal-vias": [
      "thermal-vias"
    ],
    "pours": [
      "land-pours"
    ],
    "outline": [
      "outline"
    ],
    "current": [
      "analyze-current"
    ],
    "thermal": [
      "analyze-thermal"
    ],
    "fields": [
      "tour-fields"
    ],
    "nets": [
      "tour-nets"
    ],
    "silkscreen": [
      "silkscreen"
    ],
    "3d": [
      "tour-3d"
    ],
    "mechanical-review": [
      "mechanical-review"
    ],
    "wiring-review": [
      "wiring-review"
    ],
    "simulation": [
      "evidence-simulation"
    ],
    "export": [
      "export"
    ],
    "sourcing": [
      "sourcing"
    ],
    "library": [
      "library"
    ],
    "schematic": [
      "schematic"
    ],
    "models": [
      "models"
    ]
  },
  "titles": {
    "parts": "Parts on the wiki",
    "project-page": "Project page",
    "intake": "Intake",
    "rules": "Design rules",
    "design": "Circuit design",
    "simulation": "SPICE simulation",
    "test-plan": "Test plan",
    "sourcing": "Sourcing",
    "library": "Library",
    "components": "Components",
    "libraries": "Libraries",
    "models": "3D models",
    "schematic": "Schematic",
    "placement": "Placement",
    "routing": "Routing",
    "thermal-vias": "Heatsink vias",
    "pours": "Copper pours",
    "outline": "Rounded corners",
    "current": "Current",
    "thermal": "Thermal",
    "fields": "Fields",
    "nets": "Pour walkthrough",
    "silkscreen": "Silkscreen",
    "3d": "3D board",
    "mechanical-review": "Mechanical review",
    "wiring-review": "Wiring review",
    "finish": "Finish line",
    "export": "Gerbers, BOM, CPL"
  },
  "short": {
    "parts": "every part's wiki page, shown as it is picked",
    "project-page": "README rev 1, component table, KiCad PCM repo",
    "intake": "read the prompt and the requirements",
    "rules": "choose the fab, load its design rules",
    "design": "datasheet math and part values",
    "simulation": "the drawn schematic in SPICE: start-up, ripple, load step",
    "test-plan": "what to measure on the workcell, a probe spot for each",
    "sourcing": "every part in stock, with an MPN",
    "library": "symbols, footprints and 3D from the wiki",
    "components": "wiki component identity and CAD audit",
    "libraries": "the project library in the EDA",
    "models": "every 3D model bound and upright",
    "schematic": "drawn live, checked against the netlist",
    "placement": "parts placed for current and heat",
    "routing": "every trace routed, DRC clean",
    "thermal-vias": "via arrays under the hot parts",
    "pours": "copper pours and stitching",
    "outline": "sharp board corners rounded",
    "current": "current density on every loaded net",
    "thermal": "temperature rise against the budget",
    "fields": "current and heat solved in 3D",
    "nets": "each pour net lit in turn",
    "silkscreen": "labels, polarity, pinouts, both faces",
    "3d": "the finished board in 3D",
    "mechanical-review": "service fasteners, tools and access holes (declared reviews only)",
    "wiring-review": "harnesses, connectors and service corridors (declared reviews only)",
    "finish": "0 unconnected, 0 errors, every check passed",
    "export": "manufacturing files written and checked"
  },
  "minutes": {
    "_": "Expected wall minutes for one visit of each step. Past twice this, every command and finish-guard warn that the run is still in that step (warn only, never a block): work done with the AI's own scripts still belongs to the step it does. A step not listed here expects 45 minutes.",
    "parts": 15,
    "project-page": 10,
    "intake": 20,
    "rules": 10,
    "design": 45,
    "test-plan": 20,
    "sourcing": 30,
    "library": 30,
    "components": 30,
    "libraries": 30,
    "models": 30,
    "schematic": 45,
    "simulation": 30,
    "placement": 45,
    "routing": 60,
    "thermal-vias": 15,
    "pours": 20,
    "outline": 10,
    "current": 15,
    "thermal": 15,
    "fields": 20,
    "nets": 10,
    "silkscreen": 30,
    "3d": 15,
    "mechanical-review": 20,
    "wiring-review": 20,
    "finish": 20,
    "export": 20
  },
  "skills": {
    "_": "the companion skills to read for each step (the Companion skills table in SKILL.md); `step <name>` names each SKILL.md by absolute path",
    "intake": ["aiflow-intake", "aiflow-hands-on"],
    "rules": ["aiflow-sourcing", "aiflow-molecule"],
    "design": ["aiflow-circuit-design"],
    "test-plan": ["aiflow-test-plan"],
    "sourcing": ["aiflow-sourcing"],
    "parts": ["aiflow-sourcing"],
    "project-page": ["aiflow-project-page"],
    "library": ["aiflow-sourcing"],
    "components": ["aiflow-sourcing"],
    "libraries": ["aiflow-sourcing"],
    "models": ["aiflow-sourcing"],
    "library-tour": ["aiflow-sourcing", "aiflow-live-clips"],
    "schematic": ["aiflow-schematic-to-board", "aiflow-circuit-design"],
    "simulation": ["aiflow-simulate"],
    "placement": ["aiflow-power-layout", "aiflow-molecule"],
    "routing": ["aiflow-power-layout"],
    "thermal-vias": ["aiflow-power-layout"],
    "pours": ["aiflow-power-layout"],
    "outline": ["aiflow-molecule"],
    "current": ["aiflow-power-layout"],
    "thermal": ["aiflow-power-layout"],
    "fields": ["aiflow-power-layout"],
    "nets": ["aiflow-power-layout", "aiflow-live-clips"],
    "silkscreen": ["aiflow-silkscreen"],
    "3d": ["aiflow-molecule"],
    "mechanical-review": ["aiflow-sourcing", "aiflow-power-layout"],
    "wiring-review": ["aiflow-sourcing", "aiflow-power-layout"],
    "capture": ["aiflow-process-video", "aiflow-live-clips"],
    "finish": ["aiflow-measurement", "aiflow-process-video"],
    "export": ["aiflow-schematic-to-board", "aiflow-molecule"]
  },
  "phases": {
    "Plan": [
      "intake",
      "rules"
    ],
    "Circuit": [
      "design",
      "test-plan"
    ],
    "Parts": [
      "sourcing",
      "parts",
      "project-page",
      "library",
      "components",
      "libraries",
      "models"
    ],
    "Schematic": [
      "schematic",
      "simulation"
    ],
    "Board": [
      "placement",
      "routing",
      "thermal-vias",
      "pours",
      "outline"
    ],
    "Analysis": [
      "current",
      "thermal",
      "fields",
      "nets"
    ],
    "Finish": [
      "silkscreen",
      "3d",
      "mechanical-review",
      "wiring-review",
      "finish",
      "export"
    ]
  },
  "finishLine": {
    "altium": "Gerbers, BOM and CPL exported",
    "fusion": "Gerbers, BOM and CPL exported",
    "kicad": "Gerbers, BOM and CPL exported"
  }
}