AI Flow

@@ -11,110 +11,13 @@ adom-aiflow --version  ## The final video -The evidence of a run is its video, two minutes at most: only the moments something moved, every step in order, the AI's own current density and temperature rise drawings fullscreen, the run and step clocks in the corner, the words cut to the picture. Both engines side by side in 0.2. This is the piece people will share.+The evidence of a run is its video, two minutes at most: only the moments something moved, every step in order, the AI's own current density and temperature rise drawings fullscreen, the run and step clocks in the corner, the words cut to the picture. Every run's page carries its own; the pair is the piece people 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>+**The first pair: Claude Fable 5.1 versus Codex (Astra) on the ESC G431.** Same board, same spec, same prompt, same flow, measured the same way. [The comparison page](docs/comparisons/board-claude-fable-5-1-20260914-vs-source-unplaced-codex-astra-20260914-0314/README.md) leads with the side-by-side video and links both runs in full. -*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.*+<video width="100%" controls><source src="/blob/app/adom-aiflow/docs/comparisons/board-claude-fable-5-1-20260914-vs-source-unplaced-codex-astra-20260914-0314/comparison-20260915162905.mp4" type="video/mp4"></video> -## The flow--![The flow: the AI drives, the binary does the fast parts, dashed arrows are the rework loops](docs/flow-preview.png)--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).--![Placeholder: the terminal during a run, an ERROR with its hints and the OK that followed](docs/screenshots/run-terminal.png)-*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 AI's time from the human's prompt to the AI saying "done, here is your video": the sum of the run's sessions (one per human prompt, prompt to done) with every idle gap over 15 minutes cut out, so a night's sleep between two prompts is not charged to the AI (docs/time.md). 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.--![Placeholder: adom-aiflow ledger for the first Fable run](docs/screenshots/ledger.png)-*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, the AI's current density drawing fullscreen, then each pour net lit and framed | <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, the AI's heat map fullscreen, then the pours lit; when it fails, the return is the clip worth keeping |-| fields | the Adom Fields window: the board in 3D with the current and the heat on the copper, each net lit, the hot tabs, the issues flown to | <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.+*Fable delivered in 53 min of AI time with 2 returns to earlier steps; Astra in 78 min with 14. The runs: [Fable](docs/runs/board-claude-fable-5-1-20260914/README.md), [Astra](docs/runs/source-unplaced-codex-astra-20260914-0314/README.md).*  ## The comparison: what two runs look like side by side