---
name: aiflow-hands-on
description: >-
  Hands-on AI Flow: the human chooses, for every step of an adom-aiflow run, how much the AI does on its own (1 the AI takes care of it, 2 the AI does it and checks in for their OK, 3 the human does it, 4 their own custom instructions) on the AI Flow timeline before any design work, and the choice is saved as a named flow profile ("my flow", "Full AI flow") that the next board starts from. Covers the check-in loop (`handson ask`, `handson wait`, approve or request changes), handing a step to the human and turning their work into the step's proof, switching profiles, and the screen and notification preferences (never raise windows on the human's desktop unless they allow it). Use when the human says "hands on", "hands-on AI Flow", "check in with me after placement", "let me do the routing myself", "use my flow", "use full AI flow", or names one of their flow profiles. Trigger words: hands on, hands-on aiflow, hands-on AI Flow, use hands on AI Flow, check in with me, ask me before routing, I'll place it myself, I'll route it myself, my flow, noah flow, full AI flow, flow profile, flow preference, switch flow, AI Flow timeline options, approve placement, request changes, don't take over my screen, notify me.
---

Parent skill: **adom-aiflow**

# aiflow-hands-on: the human decides who does each step

AI Flow normally takes a board from the prompt to the finish line on its own. Hands-on mode lets the human take part where they want to, step by step. It comes from Noah's comparison of two builds of the same ESC: the board he steered by hand was better routed and placed, and the fully automatic run took over his screen. Nothing about the engineering gates changes. A step's proof is still required, `finish` still refuses an unfinished board, and nothing the human chooses waives a check.

## The four choices, per step

| # | Mode | What you do | What the binary enforces |
|---|---|---|---|
| 1 | `auto` | Do the step as AI Flow always has, asking only what is truly their decision. | Nothing new. |
| 2 | `checkin` | Do the step, then show the human the result and run `handson ask <step> --summary "..."`. | Wait for their OK before the next step (AI Flow notes it if you go on, and finish lists it as open). A return to the step is a new visit and needs a new OK. |
| 3 | `human` | Do NOT do the step's work. Tell them what it needs, wait for "done", then run the step's own check on their work. | Wait for their "done" before the next step (AI Flow notes it if you go on, and finish lists it as open). The step's own check still runs on their work. |
| 4 | `custom` | Follow their written instructions for the step. They are printed every time you enter it. | Nothing new, unless you `handson ask` (then it is a check-in). |

## Start: before any design work

1. Open the run as usual (`intake ...` or `start ...`, skill aiflow-intake). If the human has a default flow profile, the run already follows it; the `intake` answer says so in a hint. Tell them in one line which flow applies.
2. When they asked for hands-on (or want to change the plan for this board): `adom-aiflow --run <run> --ai-thread "<thread>" handson plan [--profile <slug>]`.
   - The AI Flow timeline (the dashboard in Hydrogen) shows every step of this run with the four choices, plus "notify me" (Hydrogen, desktop toast, both, none) and "my screen" (hands-off or allowed).
   - It also has "save as a flow" and "use it for my next boards". The first flow a human confirms is saved as their preference automatically ("My flow") and becomes their default.
   - While the plan is open, wait for the human to confirm it before design work (`step` notes any step started before).
3. Tell the human it is on the timeline and what the choices mean. Then `handson wait`, which returns when they press Start. Run it in the background or repeat it: it waits up to `--timeout` seconds, 540 by default.
4. If they answer in chat instead, set it from their words:

   ```bash
   adom-aiflow ... handson set placement=checkin routing=human --note schematic="draw it with wires, blocks left to right" --notify toast --screen hands-off
   adom-aiflow ... handson start --save-as "Noah flow" [--default]
   ```

Never pick modes for them beyond what they said. A step they did not mention stays as their profile has it (or `auto`).

## Profiles: their preferences, kept between boards

- Profiles live on the human's machine in `~/.adom/aiflow/profiles/<slug>.json`. The default is in `~/.adom/aiflow/preferences.json`.
- `handson profiles` lists them, with `*` marking the default. `full-ai` is built in: every step auto, screen hands-off.
- `handson use <slug>` switches this run (for example `handson use full-ai` for a quick, unimportant board).
- `handson profiles --profile <slug> --default` sets their default. `handson profiles --delete <slug>` removes one.
- "Use my noah flow", "do this one with full AI": run `handson use <slug>` and say so in one line.
- A profile stores modes by step name, so it carries across KiCad, Fusion and Altium runs. A step a lane does not have is ignored.

## Check-in steps

1. Do the step fully, with its own command and proof, as in auto mode.
2. Show them. Point at the evidence they need to judge it:
   - the board in their editor (refreshed, not raised; see Screen)
   - a screenshot or drawing (`artifact --file ... --caption ...`)
   - the numbers that matter (loop lengths, vias, DRC, temperatures)
3. `handson ask <step> --summary "<what to look at and where>"`. This notifies them their way and puts Approve / Request changes on the timeline.
4. `handson wait`. On **approved**, go on. On **changes**, their words are printed: make the changes, then `handson ask <step>` again.
5. If they answer in chat, record it in their words: `handson approve <step> --quote "<their words>"` or `handson changes <step> --quote "..."`. A chat approval needs a quote.

**Never approve on their behalf**, and never read silence as approval.

## Human steps

When `step <name>` prints HANDS-ON HUMAN STEP:

1. Do not do the step's work, not even "to help".
2. Tell them what the step needs:
   - its goal and inputs (the spec, the constraints, the ranking of signals or heat if you made one)
   - what files to save and where
   - which check you will run afterwards
3. `handson wait`. They press "I'm done" on the timeline, or tell you in chat (`handson done <step> --quote "..."`).
4. Turn their work into the step's proof with the step's own check. `handson done` prints the recipe for the step:

| Step | Recipe |
|---|---|
| placement | `adopt-board --board <their saved board> --evidence <note>`, then `place verify` |
| routing | `adopt-board`, then `route` (plans only what their copper leaves open), `gate --plan <run>/plan-route.json`, `land route --plan <run>/plan-route.json` (an empty plan records the proof) |
| pours | `adopt-board`, then `verify-pours --from-board --adopt --why "poured by the human"` (writes the plan from their saved zones, `plan-pours-from-board.json`, recorded as theirs: provenance `from-board`) |
| schematic | `schematic check --sch <their file>` |
| silkscreen | `silkscreen-audit ... --record` |
| simulation | `evidence add --kind simulation --file <their result>` |

5. If a check fails, show them exactly what failed and let them choose: they fix it, you fix it, or (only when the check is wrong for this board) a deviation they agree to.

## Custom steps

The human's instructions are printed by `step <name>` under "THE HUMAN'S INSTRUCTIONS FOR ...". They take precedence over your defaults for that step, but never over a safety limit or a gate. If they ask to see the result, `handson ask` makes it a check-in. If an instruction conflicts with a check, say so and ask; do not quietly drop either.

## Screen and notifications

The human's computer is theirs.
- **Screen.** With `screen: hands-off`, the default for every profile, AI Flow never brings KiCad or Hydrogen to the front and never maximises windows:
  - `step` skips the per-step raises.
  - `capture open` opens the board without focus.
  - Step clips are still recorded by window capture, which works on covered windows but not minimised ones.
  - `tour 3d` stops and asks, because KiCad's 3D viewer only paints in front. Ask the human; with their yes, run `handson set --screen allowed`, `tour 3d`, then `handson set --screen hands-off` straight after.
  - Do not use other tools to raise windows either (skill foreground-etiquette).
- **Notify.** `notify` is how you reach them when the run needs them (the plan, a check-in, their turn): `hydrogen` (a Hydrogen notification), `toast` (an Adom Bridge desktop toast), `both` or `none`. With `none`, say it in chat only. A notification never raises a window by itself.

## While waiting

- `finish-guard` reports `waiting-for-human` (mayStop true) while a plan, check-in or human step is open. That is a legitimate pause, not an unfinished run.
- Work that does not depend on the open step is fine meanwhile (updating the project page, the clips, the next step's research). Do not start the next step's design work before the gate opens.
- The time spent waiting is logged as `handson-wait` with `humanWaitSeconds`, so measured AI time can leave it out (aiflow-measurement).

## Discoverability

When a run is not hands-on, the timeline shows a "Want a say in each step?" card with the four choices and a "Choose my flow" button. A human who presses it can confirm a plan from the dashboard; your next command prints `HUMAN (timeline): confirmed the hands-on plan ...`. Follow it from then on. When a human seems frustrated by how much the AI decided alone, mention hands-on mode in one line.