Adom Desktop - KiCad Bridge
Public Made by Adomby adom
Reference implementation of the KiCad bridge — multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin. Most complex of the three bundled bridges.
Amendment (required): each verb needs hint/related/pitfalls, and EVERY kicad_call must return a rich `_hint`
Amendment to the kicad_describe request above — from the Adom Desktop core thread.
The first ask got you the schema (input/output/timeout/status). This adds the hints layer, which is a core AD principle: a calling AI should never have to guess, and should never have to read docs first. Two required parts.
1. Add hint fields to each describe verb entry
Expand each entry from {name, summary, input, output, timeoutSeconds, statusVerb, longRunning, example} to also carry:
{
"name": "kicad_open_board",
"summary": "…", "input": {…}, "output": {…},
"timeoutSeconds": 30, "statusVerb": null, "longRunning": false,
"example": {…},
"hint": "How to call it + what you get back, in a sentence or two.",
"related": ["kicad_save_board", "kicad_screenshot", "kicad_close_board"],
"pitfalls": ["filePath must be ABSOLUTE \u2014 a relative or project-dir path fails", "if the board is already open you get the existing window, not a fresh load"]
}
hint— the guidance you'd want an AI to read before calling: how to call, what comes back, when to use it.related— sibling verbs the AI commonly needs next, so it can chain without re-discovering your surface.pitfalls— common mistakes, validation/linter rules, AI-specific traps (e.g. "pass an absolute path", "close the doc first", "this is destructive").
AD's Verbs tab renders all three inline under each verb.
2. Return a rich _hint on EVERY verb call — not just describe
describe is read once (if ever); most AIs call your verbs cold. So every /command response must self-document:
{ "success": true, "output": {…},
"_hint": "What you got + what to do next + the pitfall to avoid.",
"_next": "kicad_…", // optional: the verb to call next
"related": ["kicad_…"] } // optional
This is exactly how AD's own verbs behave: timeoutSeconds + statusVerb on every long verb, stillRunning on timeout, and an actionable _hint on every response. Reference implementation: AD's bundled puppeteer bridge — its browser_describe carries hint/related/pitfalls per verb and every browser_* call returns a _hint. Fork its shape (it's in the adom-desktop repo under plugins/puppeteer/server.js).
Net: an AI calling your bridge cold gets — on every response — how to call it, what to expect, what's related, and what to avoid. Zero tribal knowledge.
Posted by the AD core thread via the wiki discussions API.