template/flow-app/new-flow.sh probing ~/project/adom-aiflow-probing
cd ~/project/adom-aiflow-probing
# write flows/flow.json (your steps), skills/adom-aiflow-probing/SKILL.md, add verbs in src/main.rs
./build.sh                                   # tests, release build, bin/adom-aiflow-probing
# before the first publish: fill package.json (brief, discovery_*, sample_prompts), make the hero in Hero Studio
# (docs/hero.png; the human clicks Generate), then `adom-wiki pkg lint` and `adom-wiki pkg publish --org adom --public`

# Flow app template

AI Flow is a family of small apps, one per stage of making a board. The board flow (adom-aiflow) takes a prompt
to a finished, routed, DRC-clean board. Every later stage (ordering from a fab, probing and testing, ...) is its
own flow app built from this template. Each one is a separate wiki page and a separate Linux CLI, owned by
whoever builds it.

## What a flow app is: a dynamic skill

Every flow app is a **dynamic skill**: a small Rust binary that holds the AI's hand through one stage. It says which step comes next, ships the routine parts as ready-made code, checks the AI's work with deterministic linters and answers every command with hints.

- **The AI does about 97 % of the work. Your binary is about 3 %:** the guide and the checker, never the worker.
- **Never a hard gate, at any step.** `next` suggests; it does not decide whether the AI may continue.
- **Linters report and suggest, gently.** A finding plus a suggested next action. The AI and the human decide.
- **Do not do the AI's job.** AI keeps getting better; a binary that encodes today's limits as rules is out of date with the next model.
- **The only error is "I could not run"**, with what to try next.

Where the rules below ask the AI to check with the human first (money, publishing), that is the AI asking a person, not the binary blocking the AI.

## Rules

- **Its own app.** One wiki page, one Cargo project, one binary named `adom-aiflow-<stage>`. Copy this folder and
  own the copy. Never depend on adom-aiflow as a crate, and never need a PR to adom-aiflow to change your app.
  Pull improvements from this template when you want them, by hand.
- **Rust, Linux only.** One Linux binary, no Node and no Python. It runs where the AI runs (the container) and
  reaches Windows desktops through `adom-bridge`.
- **Open source.** MIT. The full source ships on the page so anyone can read it, build it with `./build.sh`, and
  send a PR. The binary in `bin/` is a convenience; `install.sh` builds from source when it does not run.
- **The binary tells the AI what to do next.** `next` names the current step and what the AI must do in it,
  from `flows/flow.json`. Every command answers `OK:` or `ERROR:` with `Hint:` lines. The binary does the
  deterministic work; the AI does the judgement the step's `do` text asks for.
- **Start from a board release.** `init --release <board-release.json>` (schema in
  `schema/board-release.schema.json`, `adom/board-release@1`). The board flow writes it when the board is
  finished; `init` refuses when a named file's sha256 no longer matches, so a stage never acts on a board that
  changed after it was finished.
- **Keep your state in one folder.** `<project>/<stage>-flow/`: `state.json`, `run.jsonl` (one line per command:
  time, AI thread, what happened), `clips/`, and the evidence each step produces. Never edit earlier ledger lines.
- **Record every step.** `clip start --name <step> --hwnd <window>` / `clip stop` records one window in the
  background. Drive browsers with pup (`pup_eval`, `pup_input_dispatch`), never the OS mouse, so clips show no
  moving cursor.
- **Ask before money and before publishing.** A step that pays, orders, posts or publishes waits for the human's
  explicit OK, recorded in the ledger.

## Start a new flow app

```bash
template/flow-app/new-flow.sh probing ~/project/adom-aiflow-probing
cd ~/project/adom-aiflow-probing
# write flows/flow.json (your steps), skills/adom-aiflow-probing/SKILL.md, add verbs in src/main.rs
./build.sh                                   # tests, release build, bin/adom-aiflow-probing
# before the first publish: fill package.json (brief, discovery_*, sample_prompts), make the hero in Hero Studio
# (docs/hero.png; the human clicks Generate), then `adom-wiki pkg lint` and `adom-wiki pkg publish --org adom --public`
```

## What is in here

| File | What it is |
|---|---|
| `src/main.rs` | the CLI: `init`, `next`, `steps`, `ledger`, `clip start/stop`; add your stage's verbs |
| `src/flow.rs` | the step engine: the first step whose `done` artifacts are missing is the current one |
| `src/ledger.rs` | the project folder, `state.json` and `run.jsonl` |
| `src/bridge.rs` | Adom Bridge calls: window recording, pull_file with a check, window screenshots, pup |
| `src/out.rs` | `OK:` / `ERROR:` with hints |
| `flows/flow.json` | your stage's steps, their artifacts and what the AI does in each |
| `schema/board-release.schema.json` | the handoff from the board flow |
| `build.sh`, `install.sh`, `uninstall.sh` | build from source; the package install and uninstall hooks |
| `new-flow.sh` | copies this folder into a new app with the names changed |