AI Flow

@@ -149,6 +149,7 @@ Everything below is what John has asked for, in the order it is likely to land. ## Skills in this package  - `adom-aiflow`: the flow, the commands, the spec, the honesty rules.+- `aiflow-comparison-video`: how to make the comparison video and page for two runs: pull the other run, `compose --with` and its narration script (the words lead, no dead air, who won each step, how the clock works), `compare --push`. - `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

⋯ 1 unchanged line ⋯

@@ -2,11 +2,12 @@ # adompkg install hook for adom-aiflow: the prebuilt binary to ~/.local/bin and the skill to ~/.claude/skills. set -e HERE="$(cd "$(dirname "$0")" && pwd)"-mkdir -p "$HOME/.local/bin" "$HOME/.claude/skills/adom-aiflow" "$HOME/.claude/skills/aiflow-measurement"+mkdir -p "$HOME/.local/bin" "$HOME/.claude/skills/adom-aiflow" "$HOME/.claude/skills/aiflow-measurement" "$HOME/.claude/skills/aiflow-comparison-video" cp "$HERE/bin/adom-aiflow" "$HOME/.local/bin/adom-aiflow" chmod +x "$HOME/.local/bin/adom-aiflow" cp "$HERE/skills/adom-aiflow/SKILL.md" "$HOME/.claude/skills/adom-aiflow/SKILL.md" cp "$HERE/skills/aiflow-measurement/SKILL.md" "$HOME/.claude/skills/aiflow-measurement/SKILL.md"+cp "$HERE/skills/aiflow-comparison-video/SKILL.md" "$HOME/.claude/skills/aiflow-comparison-video/SKILL.md" command -v service-kicad >/dev/null 2>&1 || echo "Hint: the offline gate needs service-kicad (adom-wiki pkg install adom/service-kicad)" command -v adom-bridge >/dev/null 2>&1 || echo "Hint: the live stages need adom-bridge (the Adom Bridge CLI) and the KiCad Bridge on a desktop" echo "OK: adom-aiflow installed at ~/.local/bin/adom-aiflow. Run 'adom-aiflow --version'."

@@ -1,7 +1,7 @@ {   "slug": "adom-aiflow",   "type": "app",-  "version": "0.1.20",+  "version": "0.1.21",   "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.",

@@ -1,7 +1,7 @@ {   "slug": "adom-aiflow",   "type": "app",-  "version": "0.1.20",+  "version": "0.1.21",   "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.",

@@ -0,0 +1,48 @@+---+name: aiflow-comparison-video+description: How to make the comparison video and page for two AI Flow runs (two engines, one board) with adom-aiflow: pull the other run, cut the side-by-side with `compose --with`, write the narration script the words lead (the setup, what each step is, who won each step, the overall winner, how the clock was measured), never dead air, then `compare --push` for the sub-README that leads with the video and links both runs. Trigger words: comparison video, side by side, fable vs astra, two engines, compare runs, narration script, comparison page, who won.+---++# The comparison video and page (adom-aiflow)++Two runs of the same flow on the same board make one comparison: one video, one page. The page is the thing people share, so the video has to explain itself to someone who never saw the flow.++## 1. Get the other run next to yours++The other engine's run directory must be readable from this container: its `run.json`, `run.jsonl`, every clip's `<clip>-10x.mp4`, and its drawings. When it lives on another machine, pull them through Adom Bridge (`pull_file` from `\\wsl.localhost\<distro>\home\...` for a Hydrogen Desktop workspace) into a local folder; `compose --with` finds a clip's 10x cut by file name in that folder when the recorded path does not exist here. Ask the other engine for a hand-over issue on the page (run page URL, run directory, clip list, drawings, sessions table) so nothing is guessed.++## 2. Cut the side-by-side++```+adom-aiflow compose --with <other run dir> --script <narration.json> --out esc-a-vs-b.mp4+```++Left is this run, right is the other. Steps run in the story's order (placement, routing, pours, current, thermal, fields, nets, 3D, finish), each step's two columns paced together, each run's own clocks in its own corner (AI time), both AIs' drawings side by side after their step, each step's AI-minute bars below, the delivery footer at the bottom. A column that fails to render says so on stderr; a step with nothing on either side is skipped.++Without `--script`, the picture leads (motion only, about two minutes, words cut to fit). With `--script`, the words lead: each step's picture is paced to its narration, slower or faster, never held and never cut short, so there is no dead air anywhere. Use the script for the video people share.++## 3. Write the narration script++A JSON object, step name to words; `drawings:<step>` for that step's drawing pair, `drawings:<step>:<n>` for the n-th pair. Every step in the video gets words (a step without words keeps its own pace and its own default line, which is how dead air creeps back in). About 2.5 words per second of picture you want.++What the words must do, in order:+- **The setup, over placement and into routing.** Who asked for what, on which board, and what state the board started in (for the ESC: the components moved off, the traces and copper torn up, only the outline kept; then place, route, pour, make it a molecule). Placement is over in a second of motion, so give it twenty seconds of words and let the story spill into routing.+- **What is happening, not what the tool is.** Routing: the AI works the flow, chooses the placement and the rules, goes back and moves parts when a pin cannot escape; not an autorouter button. Say which engine is on which side once.+- **Who won each step**, with the two numbers (AI minutes, returns) and the name at the end of the line.+- **The drawings**: what the picture is and what both AIs found (the necks, the hot tab, the missing via).+- **The finish**: the overall winner with both totals and returns, then how the clock works: the AI's own time from the pasted prompt to "done, here is your video", idle gaps over fifteen minutes cut out, so it measures the AI and not the human's day.++No dead air, no title pages, no em dashes in the words (they read badly and the voice pauses on them), numbers as words the voice says well ("twenty-eight minutes"), the engine names as people say them.++## 4. Look at it, then the page++```+ffmpeg -i esc-a-vs-b.mp4 -vf fps=1/8,scale=320:-2,tile=4x4 sheet.png     # every step, both columns, the drawings+adom-aiflow compare --with <other run dir> --page <owner/slug> --push --refresh+```++`compare` writes `docs/comparisons/<a>-vs-<b>/README.md` on the page: the video first with one paragraph, the number (AI time to delivery, returns, turns, thinking and binary minutes for both), the per-step table, the drawings side by side with each AI's caption, and the links to both run pages and the flow. Link it from the page's README so people find it. A re-cut is `compose --with` again, then `compare --push` again; the video gets a new name each time so no browser shows the old one.++## What the numbers mean++AI time is the sum of the run's sessions, prompt to done, idle cut out (docs/time.md). The delivery number is the first session; the walkthroughs and drawings added later are follow-ups and are not in it. Per-step minutes are the AI's active time under that step. Returns are the `--back` visits before delivery.