Omar SobhandClaude Opus 4.8
6c82b79b01
WORKSHOP-FLOW.md is the participant-journey / design-review doc: local-stack launch, the module→ADD-layer map, each screen's job (does/sees/system), and the open design questions. Mirrors the shared flow artifact. ONBOARDING refresh: matrix tools now include matrix_count; Telegram ships disabled (no more tokenless probe spam); drop the removed "Refine" step; cross- link the two docs. Co-Authored-By: Claude Opus 4.8 <[email protected]>
138 lines
7.0 KiB
Markdown
138 lines
7.0 KiB
Markdown
# APESS 2026 — Workshop flow
|
||
|
||
**From a cold laptop to a shipped agent design.** The end-to-end path a team walks
|
||
today — every screen, the job it does, what the person *does* versus what they
|
||
*see*, and the spots we think the flow can get better.
|
||
|
||
> Shared for design review. Companion to [`ONBOARDING.md`](./ONBOARDING.md) (the
|
||
> operational runbook) — this doc is the *journey*, that one is the *setup*.
|
||
|
||
`Arduino Uno Q · 4GB` · `ZeroClaw edge agent` · `FabLab Torino` · `27 Jul 2026`
|
||
|
||
---
|
||
|
||
## Before the room fills — launch the local stack
|
||
|
||
The workshop runs **on the team's own laptop**, right next to the board — a
|
||
cloud API can't reach devices behind the room's NAT. One command brings up the
|
||
web app and the API together.
|
||
|
||
```sh
|
||
# bring up web + API on the team laptop (same WiFi as the board)
|
||
cd deploy/lan
|
||
cp .env.example .env # set ADMIN_CODE, JUDGE_CODE, FLEET_SECRET
|
||
docker compose --env-file .env -f docker-compose.yml up -d --build
|
||
|
||
# → web on :80 · API proxied same-origin at /api · board app served at /download/
|
||
# ✓ everyone (team · board · judge) opens http://<laptop-ip>/
|
||
```
|
||
|
||
- **Local-first** — autonomous and offline-capable; nothing depends on the cloud during the session.
|
||
- **Shared secret** — `FLEET_SECRET` must match the value baked into the board app, or self-registration is rejected.
|
||
- **The board app** — the same laptop serves `/download/apess-onboard.zip`, the one-click App Lab app the team imports next.
|
||
|
||
---
|
||
|
||
## The through-line — one document, built five layers deep
|
||
|
||
Every screen after setup adds a layer to the team's **Agent Design Document
|
||
(ADD)**. The live board proves each capability as they design it — the modules
|
||
aren't lessons, they're the ADD taking shape.
|
||
|
||
| Layer | What it captures | Where |
|
||
|-------|------------------|-------|
|
||
| **Layer 1** | Domain & events | Module 1 |
|
||
| **Layer 2** | Skills | Module 2 |
|
||
| **Layer 3** | Policies & failure | Module 2 |
|
||
| **Layer 4** | Harness | Module 3 |
|
||
| **Layer 5** | Loops | Module 3 |
|
||
|
||
---
|
||
|
||
## The path, screen by screen
|
||
|
||
### ◦ Landing — `/`
|
||
|
||
Sets the frame: a Claude agent on the edge, on real hardware. One door in.
|
||
|
||
- **Does** — clicks **Start the workshop**.
|
||
- **Sees** — the pitch, the presenter, the single call to action — nothing else competing.
|
||
|
||
### ① Team registration — `/workshop` · Phase 1
|
||
|
||
Claim a name, and claim a board — the moment the physical device becomes *this
|
||
team's* agent.
|
||
|
||
- **Does** — enters team name + members → downloads the board app → App Lab **Import → Run** → types the code the matrix scrolls → **Bind board**.
|
||
- **Sees** — the board light up and scroll its claim code; on bind, three cards: *Say hi*, *Set up Telegram*, *Enable voice*.
|
||
- **System** — node self-registers to the laptop; the bearer token moves pool→bridge and never touches the browser.
|
||
- ⚠ **Watch** — first-connection is the busiest moment in the flow: binding plus three optional channel cards all land at once. Worth sequencing.
|
||
|
||
### ② Meet your agent — `/workshop/setup` · Phase 2
|
||
|
||
Introduce the agent, then name the **domain** it will serve — the seed the whole
|
||
ADD grows from.
|
||
|
||
- **Does** — opens the agent dashboard to explore, then **picks a domain** (e.g. "structural stress").
|
||
- **Sees** — the live ZeroClaw dashboard on the board; a single domain input that gates progress.
|
||
- ⚠ **Watch** — the domain drives every later layer but is introduced almost in passing. Does it deserve more weight this early?
|
||
|
||
### ③ Module 1 — Domain & events — `/workshop/module1` · ADD Layer 1
|
||
|
||
Turn the chosen domain into the world the agent lives in and the events it
|
||
reacts to.
|
||
|
||
- **Sees** — their domain carried over, read-only.
|
||
- **Does** — drafts Layer 1 of the Agent Design Document.
|
||
|
||
### ④ Module 2 — Skills & policies — `/workshop/module2` · ADD Layers 2–3
|
||
|
||
The hands-on core: talk to the agent, watch it use real tools on the board, then
|
||
codify what it can do and what governs it.
|
||
|
||
| Prompt | Tool | What it proves |
|
||
|--------|------|----------------|
|
||
| List the I2C devices on the bus | `i2c_scan` | reads real hardware |
|
||
| Count to 100, once a second, on the matrix | `matrix_count` | a timed loop on the MCU |
|
||
| Scroll GO CLAWS on the matrix | `matrix_text` | instant runtime display |
|
||
|
||
- **Sees** — each tool's *actual result* stream back into the chat — no flashing, all in-container.
|
||
- **Does** — runs all three → **What's next** unlocks Layers 2 & 3 (Skills, Policies & failure).
|
||
- ⚠ **Watch** — Module 2 alone carries two ADD layers plus the only live-hardware moment — heavier than 1 and 3. Prompts must be phrased as commands, since that's what reliably drives tools.
|
||
|
||
### ⑤ Module 3 — Harness, loops & submit — `/workshop/add` · ADD Layers 4–5
|
||
|
||
Finish the design: where each decision runs, how it repeats, and what happens
|
||
when a cycle fails — then ship it.
|
||
|
||
- **Does** — drafts Layer 4 (Harness) & Layer 5 (Loops), reviews the assembled document, hits **Submit ADD**.
|
||
- **Sees** — all five layers in one place; a confirmed submission.
|
||
- **System** — the ADD lands in the API, ready for judging at `/judge`.
|
||
|
||
---
|
||
|
||
## Behind the scenes
|
||
|
||
- **Fleet & scoring** — `/admin` shows every team, their phase and board health; `/judge` scores the submitted ADDs across the cohort.
|
||
- **Persistence** — team, board binding and progress live in the browser; a refresh or nav-away resumes where they left off, until an explicit Disconnect.
|
||
- **Reachability** — board and laptop share WiFi; the board self-registers over mDNS. If the room WiFi isolates clients, USB tethering is the fallback path.
|
||
- **One agent, no flashing** — a single agent with all skills. Matrix and I2C run on a resident MCU responder over a socket — instant, in-container, nothing to re-flash mid-workshop.
|
||
|
||
---
|
||
|
||
## For the designer — where the flow could get better
|
||
|
||
The honest open questions — where the current path works but feels uneven. This
|
||
is what we'd love a fresh eye on.
|
||
|
||
1. **The first-connection pile-up** — binding the board and three optional channel setups (say-hi, Telegram, voice) all appear at the same instant. What's the right sequence — celebrate the connection first, then offer channels?
|
||
2. **Uneven module weight** — layers map 1 → 2·3 → 4·5 across the three modules, so Module 2 does double duty *and* owns the only live-hardware moment. Rebalance the pacing, or split Module 2?
|
||
3. **The domain's quiet debut** — the domain seeds all five layers yet is chosen in one small field during "Meet your agent." Does it need a stronger framing moment?
|
||
4. **Feedback for a slow agent** — a cloud round-trip can take seconds; a tool result streams back as plain lines. What does "the agent is thinking / working" look like so waiting never reads as broken?
|
||
5. **When the board drops** — USB unplugs and WiFi isolation are real. The recovery path exists but is invisible to the team — how should a disconnect surface, and guide them back?
|
||
|
||
---
|
||
|
||
*Current-state workflow — APESS 2026 · RedClaw · Uno Q + ZeroClaw.*
|
||
*A rendered version of this doc is available as a shareable web page (ask the presenter for the link).*
|