app
AI Flow
Public Made by Adomby adom
Adom's AI Flow: a tool to help the AI follow all of the steps it takes to build a board.
← Commit history
README.mdadded+258@@ -0,0 +1,258 @@+# AI Flow++++**Adom's AI Flow: a tool to help the AI follow all of the steps it takes to build a board.** The AI thinks its way from parts placement through routing, copper pours, current and thermal analysis to a delivered video. The binary does the fast, deterministic parts of every step, hands back hints written for an AI, and keeps a ledger of every turn, every return to an earlier step, and the clock from your prompt to "done". One flow, one clock, one file, so Claude, Codex and any other engine are compared on the same thing.++```+adom-wiki pkg install adom/adom-aiflow+adom-aiflow --version+```++> Screenshots and video clips on this page marked **after the first run** are placeholders until the first measured run under Fable 5.1 lands. The comparison numbers are examples of what the ledger produces, not results.++## The final video++The evidence of a run is its video: one segment per step, both engines side by side, the per-step numbers between segments, narration fitted to each segment. This is the piece people will share.++<video width="100%" controls poster="/blob/app/adom-aiflow/docs/videos/aiflow-esc-fable-vs-codex-poster.jpg">+ <source src="/blob/app/adom-aiflow/docs/videos/aiflow-esc-fable-vs-codex.mp4" type="video/mp4"></video>++*Placeholder: the two-minute split screen, Fable 5.1 on the left and Codex on the right, on the ESC G431. Lands after both engines' first runs.*++## The flow++++The flow is a file, `flows/board.json`. For now it starts at parts placement and ends at a board that is 100 percent routed, DRC-clean, poured, its copper measured, its current and thermal analyses passed, and delivered on video. It will grow at the front (choosing components, building the libraries: symbols, footprints, 3D chips; the schematic; SPICE) and at the back (moleculizing with machine pins for the probing workcell, solder paste jetting, probe planning). The ledger and the clock do not change when it does.++| Step | Who | What happens | The binary offers |+|---|---|---|---|+| intake | AI | read the board and the spec, write the spec from the schematic if it is missing, plan | `start`, `plan`, `take` |+| placement | AI | place for routability, current and heat | `place pack`, `place check`, `land moves` |+| routing | binary, or the AI | route to 100 percent, gate with KiCad's DRC, land as undo steps | `route`, `gate`, `land route`, `land vias` |+| pours | binary | every net the spec names, Kelvin keepouts, thermal and stitching vias, copper measured | `pour`, `land pours`, `measure` |+| current | binary | IPC-2221 on every loaded net, pour and via capacity | `analyze current` |+| thermal | binary | copper and vias at every hot tab against a rise budget | `analyze thermal` |+| capture | binary | one window clip per step, markers, the 10x cut | `capture open`, `capture mark` |+| finish | both | refuses until everything is true; the AI cuts the video and delivers | `finish`, `deliver` |++Any step may send the AI back to any earlier step: `step placement --back --why "Q4's tab has no room for copper under the gate driver's routing"`. That is the same iterative analysis a human does, and every return is recorded with its reason and filmed.++## Why a binary and not a skill++A skill is prose. The AI reads it once, agrees, and then does not follow it when the board gets hard: it leaves seven pins unconnected and calls it done, it pours copper without checking the thermal reliefs, it forgets the clock. AI Flow is the skill made executable. The order of the steps is a file, not a paragraph. The gate refuses an unrouted board instead of advising against one. The hint arrives at the exact moment the AI needs it, as the answer to the command it just ran, in the language of this board, which is the one moment an AI reliably reads guidance. The finish line refuses until everything is true. And the ledger records what the AI actually did, including the steps it skipped, so following the flow is measured rather than hoped for.++The AI is still the one thinking. Any box can be its own code instead: it takes the step itself (`take route=ai`, `stage start`/`stage end` around its own work), hands the binary as many specs, configs, plans and scripts as it wants, and a plan it writes itself drops into the same gate, landing, measurement and analysis. The binary exists so the fast parts are not reinvented every run. When the AI's replacement is better, it files it on this page and it becomes a crate.++## A run, command by command++Every state-changing command takes `--ai-thread "<your thread name>"`. A run lives in one directory (`--run DIR`).++```+adom-aiflow start --board esc.kicad_pcb --spec spec.json --engine "Claude Fable 5.1" \+ --prompt-time 2026-09-15T14:02:11Z --target ConfRoomROG --remote-board C:/.../esc.kicad_pcb+adom-aiflow plan # the flow, who does each step, what the binary offers+adom-aiflow capture open # the board on the test box, maximised; the disk budget for the run+adom-aiflow step placement # the clip for placement starts by itself+adom-aiflow place pack --wish wishes.json+adom-aiflow place check --moves moves.json+adom-aiflow land moves --moves moves.json+adom-aiflow step routing+adom-aiflow route # ERROR names the pins it could not close and the three levers+adom-aiflow gate # KiCad's DRC offline; nothing lands until it passes+adom-aiflow land route+adom-aiflow step pours+adom-aiflow pour && adom-aiflow land vias && adom-aiflow land pours && adom-aiflow measure+adom-aiflow step current && adom-aiflow analyze current+adom-aiflow step thermal && adom-aiflow analyze thermal+adom-aiflow step placement --back --why "Q4 tab short of copper" # rework, on camera+...+adom-aiflow step finish && adom-aiflow finish+adom-aiflow deliver --video esc-fable.mp4 --message "Done. Here is your video."+```++Every answer is `OK:` or `ERROR:` followed by `Hint:` lines about this board, this run, this step. A refusal says what to change: starved thermal reliefs at JP1.1 and C43.2 (a solid patch in the spec), stitching vias outside the +VBAT pour (move them), a low-side tab with 255 mm² of copper against a 60 C rise budget (a spreader on the other layer, thermal vias in the tab, or a move).+++*After the first run.*++## The spec++`docs/spec-example.json` is the ESC G431's: copper thickness, clearances, the inherited error count, the fixed refs (the molecule interface), planes, wide and mid nets, Kelvin pairs (the INA181's inputs tapping the shunt's pads on dedicated traces with pour keepouts), loads per net (amps, max rise), hot parts (watts stated physically, tab net), the pours (outline, around parts, or explicit polygons; priorities and connection styles), solid patches, thermal and stitching vias, and the nets that are deliberately not poured. The spec is the electrical judgement, written by the AI from the schematic before the run starts, and it is what makes two engines' runs comparable.++## The ledger: how a run is measured++The number is the wall clock from the human's prompt to the AI saying "done, here is your video". The cost per step is the AI's thinking, not the binary's seconds: deterministic code is fast, the AI thinking its way through a board is slow, and that is what the chart shows.++`run.jsonl` is append-only, one JSON line per event, never rewritten:++```+{"t":"...","event":"turn","n":17,"step":"placement","command":"place check --moves moves.json","thinkingSeconds":412}+{"t":"...","event":"turn-end","n":17,"step":"placement","binarySeconds":1,"ok":true,"said":"21 moves, 0 overlaps"}+{"t":"...","event":"step","step":"placement","visit":2,"back":true,"why":"Q4 tab short of copper"}+{"t":"...","event":"clip-start","step":"placement","visit":2,"back":true,"recordingId":"rec-..."}+{"t":"...","event":"artifact","step":"routing-1","kind":"clip10x","file":".../window-...-10x.mp4","seconds":72.4,"speed":10}+{"t":"...","event":"deliver","minutes":93.2,"video":"esc-fable.mp4","steps":{...}}+```++`adom-aiflow ledger` prints it in order with the per-step table: wall, thinking, tool, turns, visits, returns, longest single think. `run.json` is the derived state; when the two disagree, the ledger wins. Nothing inside the window is excluded: waiting, an overnight gap, a re-take all count, and a marker explains them rather than subtracting them.+++*After the first run.*++## The clips: one per step, the rework too++Declaring a step stops the previous step's clip and starts this step's own window recording of the PCB editor through Adom Bridge's recorder (Windows Graphics Capture, H.264 on the box's GPU, frames only when the window changes, background-capturable: whatever another window does in front of KiCad on a shared box does not reach the take, and nobody at the box is disturbed). A return is a new visit and its own clip, tagged `placement-2 (rework)` with the reason. When a clip stops, the binary pulls it, measures it, cuts a 10x version next to it, and logs both as artifacts of the step. The flow file says what each clip should show, and the hint repeats it when the step is declared.++| Step | The clip shows | Clip |+|---|---|---|+| placement | the parts landing as undo steps, one batch per decision | <video width="100%" controls><source src="/blob/app/adom-aiflow/docs/videos/step-placement.mp4" type="video/mp4"></video> |+| routing | the routing landing net by net, then the vias; the one viewers speed up | <video width="100%" controls><source src="/blob/app/adom-aiflow/docs/videos/step-routing.mp4" type="video/mp4"></video> |+| pours | the pours filling in and the copper readback; the DRC refusals stay in, they are the story | <video width="100%" controls><source src="/blob/app/adom-aiflow/docs/videos/step-pours.mp4" type="video/mp4"></video> |+| current | the analysis table on the board | <video width="100%" controls><source src="/blob/app/adom-aiflow/docs/videos/step-current.mp4" type="video/mp4"></video> |+| thermal | the hot tabs and their copper; when it fails, the return is the clip worth keeping | <video width="100%" controls><source src="/blob/app/adom-aiflow/docs/videos/step-thermal.mp4" type="video/mp4"></video> |+| rework | the return to placement, filmed | <video width="100%" controls><source src="/blob/app/adom-aiflow/docs/videos/step-placement-2-rework.mp4" type="video/mp4"></video> |+| finish | the finish line passing, then the delivery | <video width="100%" controls><source src="/blob/app/adom-aiflow/docs/videos/step-finish.mp4" type="video/mp4"></video> |++*All placeholders until the first run.* The disk is budgeted before every clip: the flow's expected minutes for the step at 10 MB per minute, doubled for the pull and the cut, checked against the run drive and the test box, with a 1 GB floor. Measured: 128 MB for 17 minutes of routing landing at 3818 by 2052.++## The comparison: what two runs look like side by side++Everything below comes from the two runs' ledgers and nothing else. **These are example numbers**; the first measured runs replace them.++### The number: prompt to "done, here is your video"++| Engine | Prompt to delivered | Finish at | Returns | Turns | Cost at API rates | Cost on a 20x plan |+|---|---|---|---|---|---|---|+| Claude Fable 5.1 | **93 min** | 71 min | 2 | 41 | $6.10 | $0.31 |+| Codex (Astra) | **146 min** | 118 min | 4 | 63 | $9.40 | $0.47 |++Commercial users on API plans pay the API figure; a 20x subscription plan pays a twentieth. Both lines, always.++### Per step: the AI's thinking versus the binary's time (minutes)++| Step | Fable think | Fable tool | Fable wall | Codex think | Codex tool | Codex wall | Returns F / C |+|---|---|---|---|---|---|---|---|+| intake | 6 | 0 | 6 | 9 | 0 | 9 | 0 / 0 |+| placement | 18 | 2 | 20 | 30 | 3 | 33 | 1 / 2 |+| routing | 6 | 12 | 18 | 20 | 14 | 34 | 0 / 1 |+| pours | 8 | 6 | 14 | 12 | 6 | 18 | 1 / 1 |+| current | 3 | 0 | 3 | 4 | 0 | 4 | 0 / 0 |+| thermal | 5 | 0 | 5 | 10 | 0 | 10 | 0 / 0 |+| capture | 1 | 3 | 4 | 2 | 3 | 5 | 0 / 0 |+| finish and video | 18 | 5 | 23 | 24 | 9 | 33 | 0 / 0 |+| **total** | **65** | **28** | **93** | **111** | **35** | **146** | 2 / 4 |++Thinking is the gap before each command, charged to the step the AI declared. Tool is the binary's own seconds. The sum over steps is the whole run.++++### The rework map: where each engine went back, and why++| Engine | Return | Why, from the ledger | Cost |+|---|---|---|---|+| Fable | thermal to placement | Q4's tab had no room for a B.Cu spreader under the gate driver's routing; moved TP12 and R28 | 6 min |+| Fable | thermal to pours | re-poured phase B after the move | 5 min |+| Codex | routing to placement | router closed with 3 unconnected in the escape band; moved TP4 and LED1 | 8 min |+| Codex | placement to routing | re-routed after the move | 9 min |+| Codex | current to pours | +VBAT stitch vias landed outside the pour: 2 unconnected | 7 min |+| Codex | thermal to pours | Q2 and Q6 tabs short of copper | 7 min |++### The board that came out++| Outcome | Fable | Codex |+|---|---|---|+| unrouted at finish | 0 | 0 |+| new DRC errors (13 inherited counted apart) | 0 | 0 |+| copper kept, F.Cu / B.Cu | 66 % / 74 % | 61 % / 70 % |+| pours landed / refused first | 31 / 3 | 27 / 5 |+| vias (thermal and stitch) | 13 | 9 |+| current: loaded nets passing | 7 / 7 | 7 / 7 |+| thermal: worst tab rise at spec watts | 42 C (Q4) | 55 C (Q6) |+| Kelvin taps kept clean | yes | yes |++Both must reach 0 / 0 or the run is not a result. The rest is where the engineering judgement shows: copper kept for ablation, tab temperatures, how many refusals it took.++### What it cost++| Measure | Fable | Codex |+|---|---|---|+| turns (commands run) | 41 | 63 |+| thinking, total | 61 min | 104 min |+| tool, total | 32 min | 42 min |+| longest single think | 11 min (placement) | 19 min (placement) |+| steps the AI took itself | placement | placement, routing |+| tokens in / out | 1.9 M / 140 k | 3.1 M / 210 k |+| cost at API rates | $6.10 | $9.40 |+| cost on a 20x plan | $0.31 | $0.47 |++Token and dollar figures are self-reported by each engine into run.json; everything else is stamped by the binary.++++## The ESC G431, the first board++The proving run (the binary on a placement made earlier, not a measured run of the AI) ended with the ESC routed to 100 percent, 31 pours landed, both analyses passed:++++## What the binary is made of++One Rust binary, a crate per module: `aiflow-board` (the KiCad board model), `aiflow-grid`, `aiflow-router` (0.1 mm grid A*, escapes, plane stubs, per-net vias, rip-up, Kelvin taps), `aiflow-copper` (plans to copper, KiCad's DRC offline), `aiflow-place` (courtyards, packing, moves), `aiflow-pours` (zones, keepouts, thermal and stitching vias from the spec), `aiflow-analyze` (IPC-2221, tab copper, rise budgets), `aiflow-run` (the ledger and the manifest), `aiflow-bridge` (the live half through the Adom KiCad Bridge: landing, recording, measurement, validation), and `adom-aiflow`, the command.++KiCad Bridge today. Next backends: the Altium bridge, the Fusion bridge, then Adom's own web apps (adom-schematic, adom-2dboard, adom-3dboard). The board model and the bridge crate are the only ones that know KiCad; the flow, the spec, the ledger and the analyses do not change when the backend does.+++## Roadmap++Everything below is what John has asked for, in the order it is likely to land. 0.1 is what this page describes; nothing here is built until its version says so.++**Steps in front of placement (the flow grows at the front)**+- **components**: choose the parts from the requirements; a SPICE result or a thermal result can send the AI back here.+- **libraries**: build the symbols, footprints and 3D chips for every part (with adom-symbol, adom-footprint, chip-thumbnailer).+- **schematic**: draw it, and derive the spec from it, so the spec stops being hand-written.+- **simulation**: SPICE on the critical loops before the board exists (the KiCad Bridge's SPICE verbs, #89), with the loop back to components when a part choice is wrong.++**Steps after the board (the flow grows at the back)**+- **moleculize**: add the machine pins so the board can live in the probing workcell as a molecule.+- **paste**: solder paste jetting calculations and analysis.+- **probe**: work out how to probe the board when it comes off the InstaPCB process.++**Analyses (0.2)**+- **current 0.2**: cross-sections through the filled copper instead of the narrowest-track heuristic; a current-density heat map per net.+- **thermal 0.2**: copper area weighted by distance from the tab, via conduction, the other layer's contribution; a heat map per hot part.+- **impedance**: controlled-impedance and return-path checks on the nets the spec marks.+- **ablation**: the copper-kept metric per layer as a mill-time estimate for the InstaPCB process, so "least copper to ablate" is a number the AI can push.++**The video (0.2)**+- The step's own code frames the shot: zoom to fit before a landing, the part on screen when a move lands.+- The composer at `deliver`: one segment per step from the 10x clips and the analysis cards, about two minutes, the words for each segment written by the AI, adom-tts for the voice, the audio measured against the segment and the words rewritten until it fits, gang-takes for the assembly and the charts.+- The split screen for two engines, and the grid for five (Fable, Astra, Antigravity, Grok, Kimi), cut from the same step tags.+- A clip for each step on this page, and the final video at the top of it.++**Backends**+- The Altium bridge and the Fusion bridge, behind the same commands.+- Adom's own web apps: adom-schematic, adom-2dboard, adom-3dboard, so users can stop relying on the legacy tools; the board model and the bridge crate are the only crates that change.++**The binary and the bridge**+- A batched landing verb in the KiCad Bridge (one DRC preflight for a whole plan) to bring a clean pass from 18 minutes to about 4.+- An ungated free-disk-space verb in ab (adom-bridge#196) so the recording budget can see the test box.+- Every step the AI replaces with its own better code comes back as a crate, filed on this page.++**Measurement**+- Token and dollar accounting written by the binary from the engine's own usage where an engine exposes it, instead of self-reported.+- The comparison page generated from the ledgers by the binary itself (`adom-aiflow compare run1 run2 ...`), so nobody assembles a chart by hand.++## Skills in this package++- `adom-aiflow`: the flow, the commands, the spec, the honesty rules.+- `aiflow-measurement`: how a run is measured, in John's words: the clock from the prompt to "done, here is your video", the AI's thinking per step, the rework loops, the append-only run.jsonl, the cost both ways.++## Honesty rules++- The clock starts at the prompt and stops at `deliver`. A late `start` takes `--prompt-time`.+- A stage the AI takes itself is stamped by the AI and named `ai`; the binary's are `binary`. Both go on the chart.+- A run without `deliver` is not a result, and its minutes are still counting.+- A run assembled from earlier work with a back-dated prompt is a proving run of the tool, not a measured run of the AI. Say so.+- 0.1's analyses are conservative heuristics (IPC-2221 for tracks; presence, connection style, area and vias for pours and tabs) and say so in their output. 0.2 computes cross-sections through the filled copper.
page.jsonadded+89@@ -0,0 +1,89 @@+{+ "slug": "adom-aiflow",+ "type": "app",+ "version": "0.1.0",+ "title": "AI Flow",+ "description": "Adom's AI Flow: a tool to help the AI follow all of the steps it takes to build a board. One Rust binary with a crate per step (placement helpers, a grid router with Kelvin taps, pours with keepouts, KiCad's DRC gate, live landing through the KiCad Bridge, copper measurement, current and thermal analysis) and a finish line that refuses an unfinished board. Every command answers with hints for the AI; every turn, its thinking time and every rework loop go into run.jsonl, so Claude, Codex and any other engine are compared on the same flow. KiCad today; Altium, Fusion and Adom's own web apps next.",+ "summary": "Adom's AI Flow: a tool to help the AI follow all of the steps it takes to build a board. The AI thinks its way from placement through routing, pours, current and thermal analysis to a delivered video; the binary does the fast, deterministic parts of every step, hands back hints, and keeps a ledger of every turn, every return to an earlier step, and the clock from the prompt to done.",+ "brief": "Adom's AI Flow: a tool to help the AI follow all of the steps it takes to build a board.",+ "category": "Developer Tools",+ "tags": [+ "kicad",+ "pcb",+ "eda",+ "routing",+ "placement",+ "copper pours",+ "ablation",+ "current density",+ "thermal",+ "kelvin",+ "comparison"+ ],+ "status": "live",+ "discovery_pitch": "Take a KiCad board from parked parts to a routed, poured, analysed board through one command that keeps the clock, records who did each stage, and refuses to finish early. Both Claude and Codex run the same flow, so their numbers compare.",+ "discovery_triggers": [+ "100% routed",+ "ablation copper",+ "adom-aiflow",+ "ai flow",+ "aiflow",+ "board flow",+ "board loop",+ "compare engines on a board",+ "copper pours",+ "current density",+ "fable vs codex board",+ "finish the board",+ "flow for making a board",+ "from placement to a probed board",+ "kelvin keepout",+ "measure the ai per step",+ "place the parts",+ "route the board",+ "run.jsonl",+ "thermal analysis"+ ],+ "dependencies": {},+ "scripts": {+ "install": "./install.sh",+ "uninstall": "./uninstall.sh"+ },+ "visibility": "public",+ "install": {+ "binary_name": "adom-aiflow"+ },+ "hero": {+ "type": "image",+ "path": "screenshots/hero.png"+ },+ "bundled": true,+ "sample_prompts": [+ {+ "label": "Run the flow on a board",+ "prompt": "aiflow the ESC: place, route, pour, analyze and deliver the video"+ },+ {+ "label": "Route to 100 percent",+ "prompt": "route this board to 100 percent and refuse to finish with anything unconnected"+ },+ {+ "label": "Pours and thermal",+ "prompt": "pour the copper, keep the Kelvin taps clean, and tell me if any FET tab is too hot"+ },+ {+ "label": "Measure the AI per step",+ "prompt": "how long did the AI think at each step of the board flow, and where did it go back"+ },+ {+ "label": "Compare engines",+ "prompt": "run the same board flow on Fable and Codex and show me the comparison"+ }+ ],+ "org": "adom",+ "tag": "insiders",+ "author": {+ "name": "John Lauer",+ "email": "[email protected]"+ }+}