DEV Community: Keo Fung | FormLM

The Facilitator's Stack: A Checklist From Invitation to Follow-Up

Keo Fung | FormLM — Fri, 06 Nov 2026 01:45:28 +0000

Series: How to Run a Workshop People Remember (10/10)

Nine posts of opinions, mechanics and tool links later, here's the whole series compressed into the artifact people actually asked me for: the runbook. Print it, paste it into Notion, ignore half of it — the checklist is the point, not the compliance.

T-minus 2 weeks: design

[ ] Write the outcome sentence: "By the end, participants can ___" (part 1)
[ ] Write the evidence sentence: "I'll know because ___"
[ ] Draft the four-beat arc with minutes: Open → Explore → Converge → Close
[ ] Pick activities from folders with run sheets, props and debrief scripts — WorkshopSkill, or file your own materials in the folder shape (part 2)
[ ] Pressure-test the plan with ChatGPT or Claude; keep the one-page plan in Notion

T-minus 1 week: prep

[ ] Print props (poker-spec cards, A3 posters, both manual sizes)
[ ] Create the sign-up card and check-in card — QRCard AI, printable, live status after printing (part 3)
[ ] Send the invite with the card in it; if tickets are paid, the money lives in Eventbrite, the card handles the day
[ ] Build the pre/post measure — FormLM, from the pre/post-training quiz template, one description and the scoring is generated (part 6)
[ ] Optional, if you do this monthly: let an agent do the above from the folder's SKILL.md via skills.json, and build the forms over FormLM's MCP server — npm package @formlm/cli, npx -y @formlm/cli mcp (part 7)

Day before: the room

[ ] Pre-build the remote/hybrid board if needed — Miro or FigJam, frames per group, never a blank canvas (part 5)
[ ] Wi-Fi card on each table — free in-browser generator, nothing uploaded
[ ] Charge everything; pack the clicker; check the projector with the presenter deck
[ ] Deal tomorrow's groups in advance — random group generator, cross-matching if the goal is introductions

Day of: run it

[ ] Pre-measure open as people arrive (under 10 minutes, scored)
[ ] Open with pairs, not the big screen — Two Truths and a Lie, two minutes (part 4)
[ ] One live-screen moment, genuinely used: trainer live screen — counts, not names (part 4)
[ ] Every group task = artifact + visible countdown + midpoint callout (part 5)
[ ] Debrief scripted, not improvised — What? So what? Now what? Exit ticket at the door; anonymous wall for the unsayable (live message wall) (part 8)
[ ] Close with one written commitment per person
[ ] Post-measure before people leave; feedback card on the table

Within 48 hours: follow-up

[ ] One email: commitments, materials, what changes next time (part 8)
[ ] Structured feedback survey out — workshop feedback form template
[ ] Ten minutes of margin notes on the run sheet: what ran over, what got cut, which debrief question produced silence
[ ] If a client sponsored this: the per-respondent knowledge-lift report forwards itself (part 6)

Monthly: keep the program alive

[ ] Same date every month: the client report — attendance and deltas at the top, what the group worked on, one chart, one note (ReportSkills; the trainers' section and the monthly client report guide define the shape) (part 9)
[ ] The templates hub has the starting points; paste the tables you already have, send per-recipient on a schedule:

The whole stack, every URL in one place

The tools from my own shop (I'm one of the makers — full disclosure below):

Tool	The job	URL
WorkshopSkill	Ready-to-run activity folders: run sheet, deck, props, debrief script, pre/post measure; SKILL.md for agents	workshopskill.com
QRCard AI	Printed QR cards: sign-ups, check-ins, feedback, live screen, message wall, group generator	qrcard-ai.com
FormLM	Scored forms and assessments; per-respondent PDF reports; open-source MCP server	formlm.me
ReportSkills	Recurring branded client reports from pasted tables; scheduled, per-recipient delivery	reportskills.com

The other people's tools this series leans on:

Tool	The job	URL
ChatGPT / Claude	Outcome sharpening, drafting, arc pressure-tests	chatgpt.com / claude.ai
Notion	The one-page plan	notion.so
Google Slides / Canva	Teaching-block slides, one-pagers	slides.google.com / canva.com
Eventbrite	Paid ticketing, refunds, receipts	eventbrite.com
Calendly / Cal.com	Scheduling around the session	calendly.com / cal.com
Mentimeter / Slido / AhaSlides	Heavyweight polling when you need the features	mentimeter.com / slido.com / ahaslides.com
Miro / FigJam	The remote room's shared artifact	miro.com / figjam.com
Zoom	Breakout rooms for remote programs	zoom.us
Google Forms	Free-and-manual measurement when that's enough	forms.google.com
Otter.ai	Debrief transcripts, with consent	otter.ai
Looker Studio	The dashboards world, when your data lives there	lookerstudio.google.com

The sentence to keep

If the whole series had to compress to one line, it's this: a workshop is not a deck; it's a folder, a measure and a follow-through. Every tool in the tables above just makes one of those three cheaper. A folder of markers, a show of hands, and a follow-up email you actually send beats a premium stack with a missing debrief every single time.

That's the series. If you run workshops, I'd genuinely like to hear which part of the pipeline eats your evenings — the fastest way to reach me is through any of the contact pages above.

Every part of this series: 1 — Design before the slides · 2 — The activity folder · 3 — Registration and check-in · 4 — Opening the room · 5 — Group work · 6 — Pre/post measures · 7 — Agent-assisted prep · 8 — The debrief · 9 — Client reporting.

*Disclosure: I'm one of the makers — the tools from my own shop named across this series. *

From One-Off Workshop to Retainer: The Monthly Report Clients Actually Read

Keo Fung | FormLM — Fri, 06 Nov 2026 01:43:47 +0000

Series: How to Run a Workshop People Remember (9/10)

If you run workshops for organizations, you've met this client. The workshop went well, everyone said so — and six weeks later the engagement quietly ends with a one-line email: "we're pausing for this quarter."

Nothing failed. There's just no recurring evidence that anything is happening. A one-off workshop produces one afternoon of proof; a program that reports monthly produces a paper trail of progress, and paper trails get renewed. The uncomfortable truth for those of us who'd rather be in the room than in a spreadsheet: the monthly report is part of the workshop.

What the report needs to be

The failure mode I see is over-reporting: a twelve-tab workbook with pivot tables and a two-page methodology note. Clients don't read it, you resent building it, and it still takes four hours.

The trainers' version that works is one readable page, and the best formulation of it I've seen is in ReportSkills' own FAQ for the consultants and trainers section: attendance and homework with the session average at the top, a small chart by topic, what the group actually worked on this period, one note about this specific student. Beyond that, resist — a progress report that needs a legend has quietly become a transcript. (For trainers running ongoing classes, the class progress report template implements exactly that shape.)

The pipeline: paste a table, get a branded PDF

The tool I built for this job is ReportSkills, and its core mechanic is deliberately boring: paste the table of data you already have, and the report renders live from it.

What that looks like in a workshop-program month: your session notes, the pre/post deltas from part 6 and the feedback scores from part 8 arrive as small tables. Paste each into the template; the report renders immediately — you watch it happen, which is the fastest way to build trust in the tool; then send it per-recipient in a batch, on a schedule, with tracked delivery so you know it actually landed rather than assuming. There's a page of sample reports rendered from fictional table data — marketing, owner statements, bookkeeping and class progress — if you want to see the output before pasting anything:

The honest mechanics, since I'm the maker and get to set expectations:

Templates are widget-composed — blocks you arrange per template, not a fixed PDF you can't change. The features page has the full capability list.
Schedules and per-recipient batches mean the same report goes out on the same date monthly without you touching it again. That's the "delivered like clockwork" behavior the home page promises, and it's the single feature that most reduces retainer churn, because it makes your presence felt in months you were busy elsewhere.
No connectors required. It's built for the paste-and-CSV route — client reporting without API access is a guide on the site precisely because most training data has no connector: it lives in your notes and your grade sheet. If your data does live in marketing dashboards, there's a Looker Studio template shelf for that world, and a comparison of ReportSkills vs Looker Studio that's fair about where each wins.
Pricing is flat — Basic free, Plus $19/mo, with a pricing page that lays out the whole matrix. I mention flat pricing because per-client reporting pricing is the specific trap for trainers: if the tool's price scales with your client count, the tool eats the retainer you just won.

The guide shelf worth reading even if you never buy

ReportSkills ships field guides that stand on their own — genuinely useful, no login, and applicable even if your "pipeline" remains a Google Doc:

How to write a monthly client report — the four-block structure and the missing-data rule (the rule alone saves more report emails than any tool: never delay a report over one missing figure)
How long should a client report take? — where the hours hide, manual vs templated
How to show clients their retainer is working — five moves against churn from invisible results
Email PDF, live link or client portal? — the delivery-format question, answered honestly

Wire it to the workshop series

The through-line of this whole series becomes a system at this point. The monthly client report guide plus the parts you already have:

Pre/post deltas from FormLM (part 6) → the "what changed" block
Attendance and check-in counts from the QR cards (part 3) → the top-line numbers
Debrief notes and feedback scores (part 8) → the "what the group actually worked on" block

Every workshop you run now feeds the report that renews the program that books the next workshop. That loop — not any single session — is the business.

Next and last in the series: the whole stack in one place — a printable checklist from invitation to follow-up, with every tool and URL from all ten parts.

Tools in this post:

ReportSkills — recurring branded client reports from pasted tables: features, pricing, templates hub, class progress template, for consultants and trainers, guides on monthly client reports, retainer visibility and reporting time
Looker Studio — the dashboards-side world, with a fair comparison and a template shelf on ReportSkills

*Disclosure: I'm one of the makers — the tools from my own shop named across this series. *

The Debrief Is Where the Learning Happens. Most Facilitators Cut It

Keo Fung | FormLM — Thu, 05 Nov 2026 05:38:27 +0000

Series: How to Run a Workshop People Remember (8/10)

Here's a pattern I've watched in hundreds of observed workshops: the activity runs beautifully, the energy in the room is high, and then the facilitator says "Great! So… what did we all think of that?" Three people talk. Five minutes of unstructured conversation later, the clock says time's up, and the facilitator moves on — relieved, because the activity "went well."

The activity produced an experience. The debrief is where the experience becomes learning. Skip or rush it, and the best activity in the world is just a fun fifteen minutes with a prop budget.

Why "what did we think?" fails

Open-ended, opinion-shaped, aimed at the whole room at once. It invites the confident to perform and gives the reflective nothing to chew on. A debrief needs what any good interview needs: a sequence of questions with a job each.

The sequencing logic I use is the oldest one in facilitation — What? So what? Now what? — and it's exactly why the Blind Portrait folder from part 2 ships its debrief as a script: eight questions in order, each with a purpose (which instructions were missing, what did you guess instead, where does this happen on your team). You don't have to invent a question sequence per workshop. You have to not skip it when you're behind — which is why it lives in the run sheet, with minutes attached like any other block.

Give the room a private channel

The biggest debrief handicap is that speaking in front of twenty people is a performance. Two mechanics that pull honest answers out of people who will never raise a hand:

Written before spoken. Everyone writes one answer on a sticky or a card before anyone speaks. It's much harder to quietly conform to the group when your answer already exists on paper. The Exit Ticket folder is built on exactly this: one written takeaway per person at the door, not a mic passed around the room.

An anonymous wall. For the questions people won't say out loud ("what's one thing this workshop is missing?"), QRCard's live message wall works the way the name suggests: participants scan and post, and messages appear on the screen as a wall — as a grid or drifting bullets, anonymous by design:

The facilitator's move that makes the wall earn its keep: read two or three posts out loud and respond to the critical ones first. The room learns that the anonymous channel reaches the facilitator and gets taken seriously — which is what makes it honest next time. Contrast with part 4's rule (counts, not names): the wall is the one place where anonymous text is the point, but it's still text, not identities.

Capture the trail — for yourself and for the client

Three capture habits that separate professionals from people who run workshops:

Record the debrief, with consent. I put a note about it in the invite and say it out loud at the start. Otter.ai is the lazy, reliable option for transcription — the transcript is for your own debrief-of-the-debrief ("which questions landed, which produced silence"), not for the client.
Collect structured feedback while the room is still warm. A feedback card on the table (part 3's QR card, one action, no login) for the two-minute in-room version, and a structured follow-up survey for the next morning — the workshop feedback form template from part 6 is the one I use, because the responses come back scored rather than as paragraphs to decode.
Follow up within 48 hours. One email: the commitments people wrote at the close (part 1's beat four), the slides or materials, the one thing you'd change next time. Wait a week and you're just another inbox item; within 48 hours, you're still the room they were in.

The debrief of the debrief

The step almost everyone skips: ten minutes after the room empties, before you pack the props. Three questions, written in the margin of the run sheet:

Which block ran over, and what did I cut? (If the answer is "the debrief," fix the timing, not the debrief.)
Which debrief question produced silence, and what will I replace it with?
What did the wall say that nobody said out loud?

That margin note is the difference between a workshop you run once and a workshop you get better at. It's also, incidentally, the raw material for part 9 — because the notes, the measured deltas and the feedback all feed the thing that turns a one-off workshop into a recurring engagement: reporting.

Next in the series: the monthly report clients actually read — and how to produce it in fifteen minutes instead of an afternoon.

Tools in this post:

WorkshopSkill — folders with scripted debriefs and exit tickets: Blind Portrait (8-question debrief), Exit Ticket, Four Styles Debrief
QRCard AI — the live message wall for anonymous, scan-to-post reflections
FormLM — the workshop feedback form template for structured, scored post-session feedback
Otter.ai — consent-on-the-record transcripts for your own review

*Disclosure: I'm one of the makers — the tools from my own shop named across this series. *

I Let an AI Agent Prep My Workshop. Prep Took 20 Minutes.

Keo Fung | FormLM — Thu, 05 Nov 2026 00:46:54 +0000

Series: How to Run a Workshop People Remember (7/10)

Workshop prep is the part nobody teaches and everybody dreads: read the run sheet, list the props, check print specs, build the sign-up and feedback forms, write the invite. It's all mechanical work that takes an evening — which is exactly the kind of work an AI agent should be doing while you do the human parts.

The blocker was always that AI couldn't see your materials. It could draft you an email, but it couldn't open your activity folder, know the group size, count the props, or tell you that the A3 poster needs a color printer. So I made the materials machine-readable, and this post shows the workflow — because it generalizes to any prep materials you keep in files.

Make the prep a skill file

Every folder on WorkshopSkill ships with a SKILL.md file — frontmatter (name, description, group size, duration, props) plus runnable prep commands. The point of the format: an AI agent that can read files can discover the activity, install it, and run the prep without you explaining any of it in the chat.

The three-step workflow, in practice:

Discover. The site publishes a machine-readable index — skills.json, one entry per folder with the bundle URL and a checksum. Point an agent at it and ask "I need a 20-minute pairs activity on communication for 16 people" and it can shortlist from actual metadata, not vibes.
Install. Download the folder (each has a files/SKILL.md at a predictable URL — here's Blind Portrait's, for example). The agent reads the run sheet, the props list and the prep commands the same way you would.
Run the prep. This is where it stops being a gimmick. The agent produces the actual checklist: "print 8 prompt cards poker-spec, A4; print the A3 poster; cut cards; you'll need markers; run the pre measure before doors open." It knows all of this because it's in the folder, not because the model guessed.

The skills-for-agents page documents the workflow for humans, and the skill tutorials walk through it per client and per scenario (28 tutorials at time of writing — Claude, Cursor, and the rest, each with its quirks). There's also a plain guide on AI agent workshop prep for the concept without the tooling.

The forms, via MCP

The prep checklist has always ended with the annoying tail: "build the registration form, build the pre/post measure, build the feedback form." Those are all form-shaped, and form-building is now an MCP-shaped problem.

FormLM ships an open-source CLI and MCP server (the npm package @formlm/cli). If you use Claude, Cursor or any MCP-compatible client, the whole install is:

npx -y @formlm/cli mcp

One command, stdio transport, no API keys to wire up — a client with no token signs in through the chat. Then your agent can build the workshop's forms and assessments as part of the same prep session: describe the pre/post measure once, get the live scored form, the registration page and the feedback form — each with a URL you can drop onto a printed card (part 3) or into the invite email.

So the whole prep conversation with the agent ends up being one message:

"Install the blind-portrait folder from skills.json, give me the prep checklist, then build the registration form and the pre/post measure on FormLM for my 16-person session Thursday."

Twenty minutes later you have: props checklist, print specs, a run sheet summary, and three live form URLs. The evening you would have spent on this is now the evening you spend rehearsing the debrief questions — the part that actually decides whether the workshop is any good.

Honest limits, learned the hard way

The agent doesn't run the room. It can tell you to print twelve cards; it can't make the printer cooperate. Prep, yes; facilitation, no.
Machine-readable beats clever prompting. The workflow works because SKILL.md and skills.json state facts the model can't hallucinate. When I prep with materials that aren't structured this way, the agent confidently invents group sizes and prop counts — garbage in, confident garbage out.
ChatGPT-style drafting still has a seat. For the invite email and the one-page agenda, chatgpt.com or claude.ai with your prep checklist pasted in is plenty. The agent-with-tools route earns its setup cost when you do this every month.
Trust, but verify. I read the agent's checklist against the human-readable folder page every time. Not because it's often wrong — because the one time it's wrong is the night before.

Next in the series: the debrief — the beat where the learning actually happens, and the one most workshops skip.

Tools in this post:

WorkshopSkill — every folder ships a SKILL.md; the skills workflow, the skills.json index, per-agent tutorials and the AI agent workshop prep guide
FormLM — forms and scored assessments; open-source CLI and MCP server, npm package @formlm/cli (npx -y @formlm/cli mcp)
ChatGPT / Claude — drafting the invite and agenda around the checklist

*Disclosure: I'm one of the makers — the tools from my own shop named across this series. *

Prove the Workshop Worked: Pre/Post Measures Without the Spreadsheet Pain

Keo Fung | FormLM — Wed, 04 Nov 2026 09:17:53 +0000

Series: How to Run a Workshop People Remember (6/10)

Part 1 of this series made you write an evidence sentence: "I'll know it worked because ___." This is the part where we actually collect that evidence — because the industry-standard substitute for it is embarrassing.

The smile sheet — "How satisfied were you with this workshop, 1–5?" — collects politeness, not learning. It can only go up. Nobody rates a workshop badly on the way out the door when the facilitator is standing right there, and even an honest 4.8 tells you nothing about whether participants can do the thing you promised. If a client asks "did the training work?" and your answer is a satisfaction percentage, you don't have an answer.

The measure that actually moves

The design is old and boring and correct: the same short scored instrument, run before and after the session. Before: it measures where people actually are (and calibrates their confidence). After: it measures the same knowledge and self-ratings again. The difference between the two is your evidence.

If you want the framework language, this is where the Kirkpatrick levels get cited in every L&D conversation — the WorkshopSkill guide on measuring training effectiveness covers the levels without the consultant-speak, and there's a dedicated guide on pre/post measures for the instrument design. The mechanics in the room are simpler than the literature suggests:

Keep it under ten minutes. A pre-measure that takes twenty minutes will be sabotaged by late arrivals and coffee logistics before it collects a single honest answer.
Score it, don't just ask it. "Rate your confidence 1–5" is an opinion; ten right-or-wrong items plus two confidence self-ratings is a measure. Scored instruments are the difference between vibes and deltas.
Same items, same order, both times. If the post-test differs from the pre-test, your "improvement" is noise.

From paper instrument to automatic before/after deltas

Here's where I stopped doing this the hard way. For years my pre/post measure lived in a Google Form (forms.google.com) — free, fine, and completely manual afterwards: export two spreadsheets, VLOOKUP participants by hand (the ones who spelled their email differently in round two), compute deltas, build a chart per person for the client. That's the "spreadsheet pain" in this post's title, and it's the reason most facilitators quietly skip the pre/post entirely.

The tool I built to make this automatic is FormLM — you describe a diagnostic once, and it generates the questions, the scoring logic, and a print-ready PDF report for every respondent:

The template I start from for workshops is the pre/post-training quiz: the same scored quiz runs before and after training, every attempt gets graded automatically, and FormLM computes the before/after deltas into a per-participant report — the knowledge lift in plain numbers:

What that buys you at the end of a session:

Per-participant before/after deltas, computed — not hand-joined from two exports.
A PDF report per respondent (scored, branded), which is the artifact you forward to a sponsoring manager who asks "so what did my team actually get?"
An honest aggregate: "average knowledge lift from 41 to 63 points, biggest gains on the two items about X."

The surrounding templates I keep in rotation for the full workshop measurement loop: the workshop feedback form (the useful kind of post-session survey — structured, not smile sheet), the training evaluation form for program-level evaluation, and the post-training survey for the two-weeks-later check on what stuck. There's a whole training template category if you run recurring programs.

One connection worth knowing if you use both tools from this series: the WorkshopSkill folders each ship with a pre/post measure in the folder, and FormLM is the engine that turns that measure into a live scored form with the deltas computed — the folder is the paper instrument, FormLM is the scoring desk.

Free tools when you just need the math

Two situations where you don't need a platform at all:

You already have scores in a spreadsheet and just need the charts for a debrief slide: FormLM's free in-browser tools — the radar chart maker, the Likert scale and weighted-score calculators — run without an account and upload nothing.
The measure is one question ("how confident are you running this activity, 1–10?" on the way in and on the way out): a whiteboard and a show of hands is the honest, zero-tool version. Do this one even when you have the platform — it makes the lift visible to the room in real time, which is worth more than any PDF.

What measurement won't do for you

Honest limits, because overselling measurement is its own industry disease:

A pre/post lift proves learning happened in the room, not that behavior changed back at the desk. For behavior, you need a follow-up at two to four weeks (the post-training survey above) and a client who actually wants to know.
Don't measure more than you'll report. Ten items you'll show the sponsor beat forty items you'll never open again.
If the workshop is genuinely just "exposure" — a one-hour talk with no practice — measuring learning is theater. Part 1's outcome sentence decides whether a pre/post is even appropriate.

Next in the series: the part I get the most pushback on — handing the prep work to an AI agent, on purpose.

Tools in this post:

FormLM — AI form and assessment platform with scored pre/post measures, automatic before/after deltas and a PDF report per respondent: pre/post-training quiz template, workshop feedback form, training evaluation form, training templates, free in-browser tools
WorkshopSkill — guides on measuring training effectiveness and pre/post measures; every folder ships a pre/post measure
Google Forms — free, fine, and fully manual afterwards

*Disclosure: I'm one of the makers of WorkshopSkill, QRCard AI, FormLM and ReportSkills — the tools from my own shop named across this series. *

Group Work That Doesn't Collapse Into Silence

Keo Fung | FormLM — Wed, 04 Nov 2026 02:06:12 +0000

Series: How to Run a Workshop People Remember (5/10)

You've seen the failure mode: "Okay, get into groups of four and discuss!" — followed by thirty seconds of chair-scraping negotiation, one loud table, one table of people checking phones, and a debrief where the same three people speak.

Group work fails for boring, mechanical reasons. Not because humans are lazy — because the grouping was social roulette, the task had no artifact, and the clock was invisible. All three are fixable before the room ever fills.

Fix 1: Group people like you deal cards, not like you pick teams

Self-selected groups are the most expensive thing you can do to a room of strangers: the confident cluster, the friends pair off, and whoever is left over absorbs the message that they were chosen last. Randomization isn't a gimmick — it's the fastest way to make "who's in my group" a non-event so the group can get to work.

What I use: QRCard's random group generator. It runs in the browser, free, nothing gets uploaded, and it does more than count-off-to-four:

Pairs and arbitrary group sizes, obviously.
Rotations, for when you want the same pairs to meet twice — round one, then a deal that keeps each pair together across rounds.
Cross-matching, for when you want everyone to have met everyone — each round pairs people who haven't worked together yet.

That third mode is the sleeper feature. For a workshop whose real purpose is "these twenty people should know each other afterwards," cross-matching turns your grouping mechanic into the outcome itself.

Fix 2: Never give a group a topic — give them an artifact

"Discuss the challenges of stakeholder management" produces silence. "Draw your project's stakeholders on this sheet, mark who blocks whom, be ready to present in 12 minutes" produces arguments, laughter, and a thing that exists afterwards.

The difference is that a topic invites opinions, but an artifact demands decisions. Every time you feel a group drifting, the missing ingredient is something physical to produce. This is why the activity folders from part 2 all ship with props: Minefield has its printed grid cards, Silent Lineup has the constraint, Blind Portrait has poker-spec prompt cards, and nearly every folder has an A3 poster designed for exactly this — the group's shared canvas, sized for a table or a wall.

The template for any task you invent yourself: noun + verb + visible output + deadline. "List" is weak; "rank," "draw," "map," "build a top-three" are strong. If you can't name the thing the group will be holding up at the end, the task isn't ready.

Fix 3: Make the clock public and ruthless

Groups don't stall at minute two; they stall at minute seven, when the easy surface is exhausted and nobody remembers how much time is left. Two mechanics that fix this:

Visible countdown. The run-of-show timer in the WorkshopSkill presenter deck exists precisely for this. When "three minutes left" appears on the projector without you saying a word, the group self-manages — you don't have to play the enforcer walking between tables.
Midpoint callout. At half-time, say one sentence: "You should have your first draft of the map by now." Groups that lost the thread get a reset; groups that finished early start improving instead of chatting.

Remote and hybrid rooms

The same three fixes apply, with one substitution each:

Grouping: the same random generator works — paste the attendee list, deal.
Artifact: this is where Miro and FigJam genuinely earn their place. A shared board is the A3 poster for remote groups. My honest usage note: pre-build the board template (frames, sticky zones, a titled area per group) before the session — dropping people into a blank infinite canvas produces the same silence as "discuss." The WorkshopSkill guide on remote and hybrid workshops has a fuller checklist for this; for long-form remote programs, running it over Zoom breakout rooms plus a pre-built board is the boring, reliable stack.
Clock: put the countdown in the board itself or name a timer in chat. Remote groups can't see the room's clock; give them one.

The safety floor

One caveat that outranks all the mechanics: none of this works if speaking up feels dangerous. If groups go quiet after you've fixed grouping, artifacts and clocks, the problem is safety, not structure — psychological safety is the guide I point people at for that layer. The short version: model fallibility yourself early ("here's where I got this wrong last month"), protect the first person who says something half-baked, and never let a group's output be mocked in the debrief — critique the artifact, never the makers.

Next in the series: the part most facilitators skip and most clients quietly wish they'd asked for — proving the workshop actually worked.

Tools in this post:

QRCard AI — the random group generator (pairs, rotations, cross-matching, free and in-browser)
WorkshopSkill — activity folders with props, A3 posters and presenter-deck timers: Minefield, Silent Lineup, Blind Portrait; guides on remote and hybrid workshops and psychological safety
Miro and FigJam — the remote room's shared artifact; Zoom — breakout rooms

Disclosure: I'm one of the makers of WorkshopSkill, QRCard AI, FormLM and ReportSkills — the tools from my own shop named across this series. Every claim about them matches what the products do today, and links go to the live pages. This series was drafted with AI assistance and reviewed before publishing.

Open the Room Without Forcing an App on Everyone

Keo Fung | FormLM — Wed, 04 Nov 2026 00:52:11 +0000

Series: How to Run a Workshop People Remember (4/10)

Every facilitator knows the moment: twenty minutes into your workshop you want the room's input. "Grab your phones and go to..." — and then you watch the energy drain out through people's thumbs while they type a URL, miss the slash, install something, or stare at a join code on your slide.

The tools we reach for by habit — Mentimeter, Slido, AhaSlides — are good at what they do. They run live quizzes, word clouds, ranked voting. But the default joining flow is a toll booth: open browser or app, type a join code, maybe log in, then you can participate. In a two-hour workshop with strangers, a chunk of the room never gets through the booth at all.

The joining cost is the whole ballgame

For a workshop (as opposed to a conference keynote), I optimize for one variable: seconds from deciding to participating. Everything else — word clouds, fancy chart types — is decoration if the join costs ninety seconds.

The setup I've converged on uses the printed card from part 3, but pointed at the big screen instead of at a clipboard. QRCard AI has a trainer live screen: you project the card onto the room's display, people scan once with their phone — no app, no login, no join code — and their check-ins, sign-ups and answers appear on the screen in real time.

What this buys you on stage, concretely:

A live read on the room's state. Seats filling as people arrive; answers landing as a card stream while you talk. The screen becomes the room's shared awareness instead of your private spreadsheet.
Presenter control from the clicker. Pause it, fullscreen it, freeze it when time's up — you don't need to walk back to the laptop mid-sentence.
It survives bad venue Wi-Fi. Any facilitator who has watched a cloud-based poll die on conference-hall Wi-Fi mid-activity knows this is not a nice-to-have.
Private by default. It projects counts, not names and emails. The shy person in row three can answer honestly because the room sees "17 people picked B," not her name.

If you're comparing options, QRCard publishes its own honest comparison pages — vs Mentimeter, vs Slido, vs AhaSlides — which state plainly where each tool wins. Those tools genuinely do more poll types; that's why they charge per seat. My line is: when participants are strangers and the session is short, joining cost beats feature count.

The first ten minutes: pairing instead of polling

Before any screen, the cheapest participation tech is still another human. The fastest way to wake up a room of strangers is to put them in pairs doing something slightly ridiculous, and the fastest way to do that fairly is to remove the social calculus of "who do I sit with?"

Two moves:

Randomize the pairing. Letting people pick means cliques pair up and the anxious person at the edge of the room gets picked last — or not at all. QRCard's random group generator does pairs, rotations and cross-matching in the browser, free, nothing uploaded. You paste your list or just set the group size; it deals the room.
Give the pair something with rules. This is where the activity folders from part 2 earn their keep: Two Truths and a Lie (two minutes, zero props, both people talk), or the icebreaker games guide when you need options for a specific kind of room.

The sequencing that works for me: pairs first (voices already warm), then the big screen (the room is now comfortable being visible). Reverse the order and the first thing the room learns about your workshop is that being anonymous is the safe state.

What I don't use the screen for

The live screen is a scalpel, not the workshop. Things I deliberately keep off it:

Anything long. If the task takes more than sixty seconds of typing, the screen version will strand people mid-sentence when you advance. Long reflection goes on paper (part 8's exit tickets).
Anything that names people. The moment the screen shows names, participation becomes a performance. Counts only.
Anything you don't plan to use. If you collect answers and never reference them again, the room learns that answering is theater. One screen moment, genuinely used, beats five decorative ones.

Next in the series: the hardest fifteen minutes of any workshop — group work that doesn't collapse into silence, and how to actually run it.

Tools in this post:

QRCard AI — trainer live screen for projecting a card to the room display, audience participation without an app, random group generator, honest comparisons: vs Mentimeter, vs Slido, vs AhaSlides
Mentimeter, Slido, AhaSlides — the established poll/quiz tools; more poll types, more joining friction, per-seat pricing
WorkshopSkill — Two Truths and a Lie folder and the icebreaker games guide

Registration and Check-in That Runs Itself: Put the Paper to Work

Keo Fung | FormLM — Wed, 04 Nov 2026 00:50:41 +0000

Series: How to Run a Workshop People Remember (3/10)

Watch what happens at the average workshop check-in table: a printed list, a pen, someone crossing out names, and a line of people spelling their email addresses at each other. Meanwhile the facilitator is trying to remember who said they were vegetarian and whether the waitlist people got told the venue changed.

The root cause is that most of us treat registration and check-in as paperwork instead of as the first five minutes of the workshop experience. It's the first thing participants touch. It sets the tone for how organized the rest of the day will feel.

The three anti-patterns

The long URL. You paste a Google Form link into an email, and at the venue you tape a printout of a QR code pointing at docs.google.com/forms/d/1Xk9... with no explanation of what happens after scanning. People won't scan what they don't trust, and they shouldn't.
The static QR. You print a code that points at one fixed page. Then the venue changes, the capacity drops from 30 to 20, the deadline moves — and every printed code is now wrong. Reprinting everything is the only fix, so nobody does it.
The app wall. "Just download this event app and enter code WORKSHOP-2026-AB." For a two-hour session, the download is more expensive than the ticket.

What paper actually wants to be

The fix I've landed on — and yes, this is my own tool, I'll be honest about that up front — is to treat the printed artifact as the interface: a QR Card. QRCard AI turns one sentence ("Sign up for the October design workshop, 20 seats") into a printable card that collects data.

Three properties make this work where the anti-patterns fail:

The card face explains itself. A QR code floating alone on a page is sketchy; a card that says what scanning does — "Sign up: 20 seats, closes Friday" — earns the scan. There's a good short explainer on how QR Cards work and what makes a card trustworthy.

One scan, one action. Registration, check-in, feedback, whatever the card is for — after the scan, the person does one thing and they're done. No account, no login, no join code.

Live status flows back to the printed card. This is the part that sold me on the model: spots left, deadlines, waitlists update dynamically — the printed code keeps pointing at a page that always knows the truth. The card is printed once; everything behind it can change anytime. That's the dynamic QR behavior, and it kills the "static QR" anti-pattern dead.

To see the range of what people run on these, the examples gallery shows twelve complete sample cards — club sign-ups, event pre-registration, class sign-up slips, feedback cards, each scannable right now:

For a workshop specifically, I run two cards: a sign-up card (goes out in the invite email and gets printed for the noticeboard) and a check-in card (on the door the morning of). Both free-tier friendly — the pricing page has a free plan with up to 10 live cards, which is more than a workshop season needs.

The room's paper layer

Two more pieces of workshop paper that people never regret:

A Wi-Fi card. Instead of people hunting for the venue network name and shouting passwords across tables, a Wi-Fi QR code on each table connects phones in one scan. It's a free in-browser generator — nothing gets uploaded.
A feedback card, which I'll cover properly in part 8 (the debrief and follow-up), because it belongs to the end of the arc, not the beginning.

When you need something heavier

Being fair about the boundaries:

Paid tickets, refunds, seat maps? That's a ticketing system. Eventbrite does the money-handling and receipting properly; a QR card doesn't and shouldn't. The two compose fine — Eventbrite takes the payment, a card handles day-of check-in and feedback.
Scheduling one-on-ones before or after the session? Calendly or Cal.com still owns that job.
A long, scored assessment (pre/post measures, the subject of part 6) shouldn't be crammed onto a card either — the card collects; the assessment platform scores. There's an honest comparison of exactly this split on QRCard's own site: FormLM vs QR Card, which says plainly that a long instrument belongs to a form platform, not to printed paper.

The rule of thumb I use: cards for one action, platforms for processes. Registration is one action. Check-in is one action. That's why they keep running themselves while the facilitator is doing the actual job — being in the room.

Next in the series: opening the room — live participation without forcing an app on everyone.

Tools in this post:

QRCard AI — printable QR Cards for workshop sign-ups, check-ins and feedback: how cards work, examples gallery, dynamic QR behavior, free in-browser Wi-Fi QR generator, pricing
Eventbrite — paid ticketing, refunds, receipts
Calendly / Cal.com — scheduling the conversations around the session

Steal a Run Sheet: What a Ready-to-Run Workshop Folder Contains

Keo Fung | FormLM — Tue, 03 Nov 2026 09:31:10 +0000

Series: How to Run a Workshop People Remember (2/10)

In part 1 I argued you should design the workshop before the slides, and I teased a thing called a run sheet. Here's the confession that goes with it: for years I built every one of those from scratch. Run sheet in a doc, deck in Google Slides, props in whatever drawing tool was closest, instructions on loose paper, the debrief question list in my head.

Every one of those artifacts died a separate, un-versioned death after the session. The next time I ran a similar workshop, I started over.

Then I flipped the unit of preparation from "a bunch of files" to one folder per activity, and I built WorkshopSkill around that idea. This post walks through what a finished folder actually contains, because the anatomy matters more than any single piece — and because you can build your own version of this filing system with whatever tools you like.

The anatomy of an activity folder

Take a real one. Blind Portrait — a classic back-to-back drawing exercise, 2 people per pair, 15 minutes, offline, one person describes an image while the other draws it without seeing it. Simple activity. Here's everything that ships in the folder:

A minute-by-minute run sheet. Not "introduce the activity" but exactly what you say to brief it, when pairs swap roles, when pens down. The run sheet is the artifact that survives contact with a real room: when the fire alarm kills ten minutes, you cut blocks, you don't improvise the debrief away.
A presenter-grade HTML deck. It opens in a browser and it's built for stage use: a presenter drawer with your notes, a run-of-show timer visible only to you, and a built-in QR engine — you can put a join code on screen in one step. I'll come back to that QR engine in part 4, because it's the bridge to live participation.
Print-and-cut props. The drawing prompts are poker-card spec — print, cut along the lines, done. No "find a suitable image online and hope it prints at the right size."
An A3 wall poster. The artifact the room builds on together, sized for the wall, not for a laptop.
A debrief script. The actual questions, in order, with the sequencing logic written down. Not "discuss what happened" — "which instructions were the describer missing? what did you guess instead?" Part 8 of this series covers why this file is the most important one in the folder.
A pre/post measure. A short scored instrument that runs before and after the session, so "it felt great" becomes a number that moved. Part 6 covers what to do with it.
The manual, in A4 and US Letter. Both sizes, with PDF bookmarks, because printers and continents vary.
A white-label guide, so if you're a consultant delivering under a client's brand, the materials don't shout someone else's name.

And the whole folder is downloadable as a zip, free, under CC BY — attribution and you're done. There are paid tiers if you need a single-event or organization license, but the free default is genuinely usable: no account, no paywall.

Why "a deck" is the wrong unit

Compare that to the default workflow — building in Google Slides (slides.google.com) or Canva (canva.com):

Slides have no clock. A deck doesn't know your room started eight minutes late. A run-of-show timer does.
Slides can't hold the run sheet, the props and the debrief script without becoming a 60-page monster where the presenter has to hunt for the cue cards mid-session.
Decks die alone. The deck is on one laptop, the props never got printed, the debrief questions lived in your head and left with you.

None of this is an attack on slide tools — I still use slides for content-heavy teaching blocks, and Canva makes a gorgeous one-pager. The point is the unit of preparation: if the folder is the unit, everything travels together, gets versioned together, and is ready to run again next quarter without archaeology.

Where to steal from, and what to file yourself

The blunt advice:

Stop writing activities from scratch. A well-run Two Truths, Minefield or Silent Lineup has been refined in thousands of rooms before yours. WorkshopSkill exists precisely so you can pull a folder and go — the folder categories are organized by what the activity trains (communication, trust, conflict, leadership, icebreakers and more), and the how-to guide library covers the surrounding craft: designing a workshop, icebreaker games, large-group activities, psychological safety.
File your own activities the same way. After every session you run, spend ten minutes upgrading your materials into the folder shape: run sheet, props spec, debrief script, measure. The discipline is the value; the site is just one implementation of it.
License properly when you borrow. CC BY means "credit the author, run it anywhere." The licensing page spells out the free tier and the paid tiers for commercial contexts that need them.

The honest limits

Folders don't fix everything. A run sheet can't rescue a workshop aimed at no outcome — that's part 1's job. Props don't make an activity fit a room it wasn't designed for — check the folder details (group size, duration, setting) before you commit, not after the room fills up. And printing is still yours to do the day before; no archive prints your props for you.

What the folder unit buys you is the thing veteran facilitators all have and few can name: a shelf you can pull from at 9 p.m. the night before, and trust.

Next in the series: registration and check-in — the part of workshops everyone pretends is solved by pasting a long URL into an email.

Tools in this post:

WorkshopSkill — free archive of ready-to-run activity folders; see the Blind Portrait folder, the full activity categories, the guides library and licensing
Google Slides — fine for teaching blocks; wrong unit for the whole workshop
Canva — one-pagers and visual materials

Design the Workshop Before You Build the Slides

Keo Fung | FormLM — Tue, 03 Nov 2026 09:29:31 +0000

Series: How to Run a Workshop People Remember (1/10)

I've sat through a lot of bad workshops. When I ask the facilitator afterwards what went wrong, the answer is almost never "my slides were ugly." It's always some version of the same confession: "I built the deck first and figured out the workshop along the way."

The deck is not the workshop. The deck is packaging. If you design the session in Keynote or Google Slides, you'll get a presentation with a bit of discussion bolted on — which is exactly the format people have learned to sleep through.

This series is about the whole job of running a workshop that people actually remember: design, materials, registration, the room itself, measurement, follow-up, and the boring-but-lucrative part — reporting to whoever paid for it. This first part is the foundation: how to design before you build anything.

Start with two sentences

Before you open any tool, write these two sentences on paper:

The outcome: "By the end of this session, participants can ___." One verb, one observable behavior. Not "understand stakeholder mapping" — "can draw a stakeholder map for their own project and name their two riskiest relationships."
The evidence: "I'll know it worked because ___." What will you see or measure that proves the outcome happened? A map on the wall per team? A pre/post score? A commitment written down before people leave?

If you can't finish sentence two, your workshop is a lecture with snacks. Everything else in this series — activities, QR screens, measurement, reporting — exists to make the evidence sentence cheap to collect.

The four-beat arc

Every workshop I've run or admired follows the same rhythm. Steal it:

Beat 1 — Open (10–15%). Low-risk warmup that gets voices into the room. It's not entertainment; it's establishing that speaking here is safe. A ninety-second pair exercise like Two Truths and a Lie does more than thirty minutes of icebreaker bingo.

Beat 2 — Explore (50%). The actual work, done by participants, not by you. This is where tools and props earn their keep — timed exercises, group artifacts, visible outputs. You talk the least in this beat. That's the point.

Beat 3 — Converge (20%). The debrief. This is where learning actually happens, and it's the beat most facilitators cut when they run late. (Part 8 of this series is entirely about this, because it deserves its own article.)

Beat 4 — Close (10%). Each person leaves with one commitment written in their own words. If they leave with nothing written, the workshop evaporates on the drive home.

From arc to run-of-show

Now assign minutes. A run-of-show is the workshop cut into timed blocks with an owner per block: not "team activity," but "Minefield, 20 min, pairs, needs 8 printed cards, debrief 5 min." When something runs over — something always runs over — the run-of-show tells you exactly what to cut without gutting the debrief.

I stopped writing slide outlines years ago and now design every session as a run sheet first. If you want to see what a finished one looks like, the folders on WorkshopSkill each ship with a minute-by-minute run sheet — that's the artifact I'm describing, filed and ready to compare against your own. There's also a dedicated guide there on how to design a workshop that goes deeper on outcomes and timing than this post can.

Where AI and tools fit in design (and where they don't)

I use AI at exactly two points in the design phase, and both are drafting, not deciding:

Sharpening the outcome sentence. Paste your draft outcome into ChatGPT (chatgpt.com) or Claude (claude.ai) with a prompt like:

"Here's my draft learning outcome for a 3-hour workshop: [outcome]. Rewrite it as one observable behavior per participant, list three ways I could see or measure that behavior during the session, and flag anything vague."

It's a superb vagueness detector. It will catch every "understand" and "appreciate" hiding in your sentence. It will not know your participants; you still own the call.

Pressure-testing the arc. Give it your four beats with minutes and ask: "Which beat is underweighted for a group of 25 who don't know each other?" The answers are generic but often embarrassing in a useful way — usually it points out that your Open beat is two minutes shorter than it should be.

For the plan itself, I keep it boring: one page in Notion or any doc with a table — beat, minutes, activity, materials, evidence captured. If the design doesn't fit one page, it won't fit the room.

What's coming in this series

The next nine parts walk the whole pipeline with the tools I actually use — mine and other people's, named and linked, so you can assemble your own stack:

Stealing a run sheet: what a ready-to-run activity folder contains
Registration and check-in that runs itself
Opening the room without forcing an app on everyone
Group work that doesn't collapse into silence
Proving it worked: pre/post measures without the spreadsheet pain
Letting an AI agent do the prep work
The debrief: where learning actually happens
From one-off workshop to monthly retainer (reporting clients read)
The whole stack: a checklist from invitation to follow-up

Tools in this post:

WorkshopSkill — free archive of ready-to-run workshop activity folders, each with a minute-by-minute run sheet; see the design-a-workshop guide and the theory behind filing activities like skills
ChatGPT and Claude — outcome sharpening and arc pressure-tests
Notion — the one-page plan

50 Forms in 30 Days: What I Learned Building Assessment Forms With an AI Agent

Keo Fung | FormLM — Wed, 12 Aug 2026 03:43:50 +0000

This is the last post in the series. Over the past 30 days, I used Claude Desktop and the formlm-cli MCP server to build 50 assessment forms — everything from a 3-question mood check to a 40-item leadership 360 evaluation. Some were for production, some were tests, some were experiments to see how far I could push the AI.

Here's what worked, what didn't, and what I'd do differently.

The Numbers

Over 30 days:

Forms created: 50 (12 production, 38 testing/experimentation)
Total fields added: ~640 (average ~13 fields per form)
MCP tool calls: ~3,200 (average ~64 per form)
AI-induced bugs: 7 (details below)
Time per form: 30 seconds for simple forms, 3-5 minutes for complex ones
Manual fixes needed: 23 forms needed at least one manual correction after AI build

The manual fix rate (46%) is the number I want to drive down. It means roughly half the forms the AI built weren't ready without human intervention. The bugs weren't catastrophic — but they were real.

The 7 Bugs

Here's every AI-induced bug I hit, ranked by severity:

1. The `field_update` Options Wipe (Critical)

Claude replaced an entire options list with a single option, destroying the other options' scores. This is the find-then-set pattern story from article 12. Fixed by adding field_set_property and enforcing the find-first pattern.

2. The Staging/Production Profile Leak (High)

Claude published a form to staging when I asked for production. This is the multi-profile story from article 18. Fixed by making the environment visible in every response — still in progress.

3. The `assess form clear` Attempt (High)

Claude tried to bulk-delete all fields in a form. Blocked by the server-side whitelist. This is the whitelist story from article 19. No fix needed — the whitelist caught it.

4. The Duplicate Fields (Medium)

Claude re-added all fields after a session restart, creating duplicates. This is the idempotency story from article 15. Fixed by enforcing find-before-add.

5. The Boolean Trap (Medium)

Claude couldn't set required: false — it kept omitting the parameter, which defaulted to true. This is the boolean trap story from article 14. Fixed by making the schema description explicit about the default.

6. The Reverse Scoring Confusion (Low)

Claude inverted option scores when it should have used scale-level reversal. This is the scoring story from article 17. Fixed by being explicit about what kind of "reverse" I mean in prompts.

7. The Forgotten App ID (Low)

Claude lost track of the app ID mid-session and tried to add fields without it. This is from the stress test in article 13. Fix idea: maintain a "current app" state in the MCP server — not implemented yet.

Four of the seven bugs were caught before reaching production. Three made it to staging. None made it to production users. The whitelist was the hardest backstop — everything else was caught by manual review.

What Worked Well

Schema-Driven Discovery

Claude consistently called field_schema and field_config before adding fields. It treated the .describe() strings like documentation — reading them, understanding them, and making decisions based on them. This is the single most important design decision I made: making every parameter self-documenting through zod schemas.

Natural Language to Field Structure

Claude was excellent at translating assessment frameworks (PHQ-9, Maslach Burnout, Big Five) into field structures. It knew the items, the scoring ranges, and the dimensional groupings. Give it a framework name and it would produce the right fields with the right options and scores. This saved hours of manual work.

Safe Defaults

The share_publish tool hardcodes formDay: 3650000 (never expires) and formPerm: 1 (public read). The AI never had to decide on expiry or permissions — it just published. Safe defaults eliminated an entire class of potential mistakes.

The Whitelist

Every single time Claude tried something it shouldn't have (the clear attempt, the delete-all variant), the whitelist caught it. Not one dangerous command slipped through. The three-token subcommand extraction was simple, fast, and effective.

What Didn't Work

State Management Across Sessions

Claude doesn't remember what it did in a previous session. When I asked it to "continue building," it started from scratch — re-creating fields that already existed. The find-before-add pattern helped, but the fundamental issue is that MCP tools are stateless. There's no "current app" or "last field added" concept.

Complex Scoring Configuration

The MCP tools handle form construction well. They don't handle scoring at all. For any form that needed dimensional scoring, reverse items, or score cutoffs, I had to configure the Scale module manually. This was the biggest gap — about 70% of the forms I built needed manual scoring configuration after the AI finished the form structure.

Boolean Parameters

The required, unique, and shareable boolean parameters were consistently problematic. Claude's instinct to omit rather than explicitly set false caused silent bugs in multiple forms. The schema description fix helped, but it's a band-aid on a deeper design issue.

Environment Awareness

Claude had no concept of "staging" vs "production." It used whatever profile was active and didn't know the difference. The URL in the response was the only signal, and Claude didn't flag it when the environment didn't match my request.

Patterns That Emerged

Over 30 days, I noticed consistent patterns in how Claude interacted with the tools:

Claude always checks before adding. Before the first field_add, Claude calls field_schema and field_config. Every single time. This is good — it means the schema descriptions are doing their job.

Claude batches similar operations. When adding 10 fields, Claude doesn't ask for confirmation between each one. It adds all 10 in sequence. This is fast, but it means if the first field is wrong, the next 9 are probably wrong too (same pattern, same mistake).

Claude verifies after building. After adding fields, Claude calls field_list to check. This is a self-verification step that catches missing fields but doesn't catch scoring errors (since field_list shows structure, not scoring logic).

Claude gets creative when blocked. When Claude couldn't find a bulk-delete tool, it tried shell commands. When it couldn't set required: false, it tried omitting the parameter. The AI doesn't give up — it finds workarounds. Some of those workarounds are clever. Some are dangerous. The whitelist is what keeps the dangerous ones in check.

What I'd Do Differently

If I were starting over, I'd make these changes:

Add a field_add_many batch tool. Reduce 10 round-trips to 1. But define clear error semantics — if one field in the batch fails, return the error for that field and let the AI decide whether to retry.
Make the "current app" implicit. After app_create or app_get, set the app ID as the active context. Subsequent field operations default to the active app. This eliminates the "forgotten app ID" bug.
Expose scoring configuration via MCP. This is the biggest gap. Without it, the AI can only build the form shell — not the assessment engine. I'm working on this, but it requires careful whitelist design (AI can set scoring, but not reset it).
Add environment labels to every response. "Published on staging.formlm.me" not just the URL. Make the environment impossible to miss.
Make boolean parameters required, not optional. If required must be true or false, never undefined, Claude can't fall into the "omit means default" trap. The extra parameter in every call is worth the safety.

The Meta-Lesson

The biggest thing I learned over 30 days is this: designing tools for AI agents is different from designing tools for humans.

When I design a CLI for humans, I optimize for ergonomics — sensible defaults, helpful flags, clear error messages. Humans read the docs, understand the context, and make informed decisions.

When I design an MCP server for AI agents, I optimize for explicitness — no hidden defaults, no ambiguous parameters, no operations that require context the AI doesn't have. Every tool needs to be self-contained: the description tells the AI what it does, the schema tells the AI what to pass, and the response tells the AI what happened.

The .describe() string on every zod field isn't just documentation. It's the instruction manual the AI reads before deciding to use the tool. A vague description ("Mark as required") leads to vague behavior. An explicit description ("Defaults to true if omitted. Set to false explicitly for optional fields.") leads to correct behavior.

This series has been about the journey from "the code works" to "the AI can use the code correctly." The first part — writing working code — took a few weeks. The second part — making it AI-safe — has taken 30 days and counting, and I'm still finding edge cases.

What's Next

The formlm-cli MCP server now has 6 layered tools + 6 knowledge resources, a server-side whitelist, explicit schema descriptions, and the patterns (find-then-set, find-before-add) that make AI interactions safe. The CLI is open source. The platform is live at formlm.me.

We're not there yet. But 50 forms in 30 days has proven that the foundation works. The tools are solid. The patterns are reliable. The whitelist holds. The AI can build forms.

Now it can build assessments too.

This concludes the 20-part series on building AI-native tooling for FormLM. The CLI and MCP server are open source at github.com/formlm/cli. The platform is at formlm.me. Thanks for reading.

The Whitelist That Saved My Production Data: A Security Boundary Story

Keo Fung | FormLM — Wed, 12 Aug 2026 03:42:09 +0000

I almost lost every field in a production form last week. Not to a bug, not to a crash — to an AI that was trying to be helpful. If I hadn't built a server-side command whitelist, I'd be writing a very different post right now.

Here's what happened, how the whitelist caught it, and why I'll never ship an AI-accessible API without one.

The Setup

I was cleaning up a staging form that had accumulated junk fields from various test runs. I told Claude:

"This form has too many test fields. Remove all the fields that start with 'test' and clean it up."

Claude looked at the field list, saw about 15 fields starting with "test_", and decided the most efficient approach was not to call field_remove 15 times. Instead, it tried something... creative.

What Claude Tried

Claude called field_remove for individual test fields — that part was fine. But after the fifth call, it apparently decided individual removals were too slow. It tried to find a "remove all" or "clear" command.

The MCP tools don't expose a "clear all fields" operation. But Claude was looking at the CLI command structure, and it noticed that the underlying server commands follow a pattern: assess form <subcommand>. If assess form remove removes one field, maybe assess form clear removes all of them?

Claude didn't have a field_clear MCP tool. But it could construct the raw CLI command and... wait, it couldn't. The MCP server only exposes tools, not raw command execution. Every MCP tool call goes through execCommand(cmd), where cmd is a string built from the tool parameters.

But here's the thing — the CLI itself is installed on my machine. Claude Desktop could, in theory, run shell commands. And it did. Claude opened a terminal and tried:

formlm-cli field clear --app abc123

The CLI doesn't have a field clear command. It failed with "unknown command." But Claude wasn't done. It tried:

formlm-cli assess form clear --app abc123

This one sent a request to the server. The server received assess form clear --app abc123. And that's where the whitelist kicked in.

The Whitelist

On the server side, every command sent through /api/v1/mcp/exec goes through a whitelist check. The whitelist operates at the subcommand level — not the module level, not the individual field level, but the specific subcommand.

The server extracts the first three space-separated tokens from the command string and checks them against an allowlist:

assess app list      ✅ allowed
assess app create    ✅ allowed
assess app update    ✅ allowed
assess app remove    ✅ allowed
assess form add      ✅ allowed
assess form update   ✅ allowed
assess form remove   ✅ allowed
assess form move     ✅ allowed
assess form find     ✅ allowed
assess form query    ✅ allowed
assess form types    ✅ allowed
assess form config   ✅ allowed
assess form set-property  ✅ allowed
assess share set     ✅ allowed
assess share query   ✅ allowed
assess share url     ✅ allowed
...
assess form clear    ❌ BLOCKED
assess app clear     ❌ BLOCKED
assess form delete-all  ❌ BLOCKED

assess form clear was not on the allowlist. The server returned:

{
  "code": 403,
  "message": "Command not allowed: assess form clear",
  "data": null
}

Claude got the error. It tried once more with a slight variation (assess form clear-all), got the same 403, and then gave up and went back to removing fields one by one. The whitelist held.

Why Subcommand-Level, Not Module-Level

I could have built the whitelist at the module level — allow everything under assess form * and block everything else. But that would have been too permissive. The assess form module has both safe operations (add, update, find, query) and dangerous ones (clear, delete-all, reset). Module-level whitelisting would either allow everything (dangerous) or block everything (useless).

Subcommand-level whitelisting is more precise:

assess form add — safe, creates data
assess form remove — safe in isolation, removes one field
assess form clear — DANGEROUS, removes ALL fields
assess form move — safe, reorders
assess form update — safe, modifies one field

The dangerous operations are the "bulk" ones — clear, delete-all, reset. These are administrative commands that a human would run intentionally but an AI might trigger accidentally (or "creatively," as in my case).

What Would Have Happened Without the Whitelist

If assess form clear had been allowed, the server would have:

Deleted every field in the form — not just the "test_" fields, ALL of them
Returned a success response
Left me with a published form that had zero fields

Respondents clicking the form URL would see an empty page. No error, no warning — just an empty form. The data wouldn't be recoverable because clear doesn't soft-delete; it hard-deletes.

I had about 200 responses on that form from real users. The responses would have been orphaned — response data without corresponding field definitions. The reporting module would have crashed trying to map response data to non-existent fields.

It would have been a very bad day.

The Extract Function

The key piece of the whitelist is the subcommand extraction. It takes the raw command string and extracts the first three tokens:

def extract_sub_command(cmd: str) -> str:
    parts = cmd.strip().split()[:3]
    return ' '.join(parts)

Then it checks against the allowlist:

ALLOWED = {
    'assess app list',
    'assess app create',
    'assess app update',
    'assess app remove',
    'assess form add',
    'assess form update',
    'assess form remove',
    'assess form move',
    'assess form find',
    'assess form query',
    'assess form types',
    'assess form config',
    'assess form set-property',
    'assess share set',
    'assess share query',
    'assess share url',
}

def is_allowed(cmd: str) -> bool:
    sub = extract_sub_command(cmd)
    return sub in ALLOWED

Simple. Three tokens. If the combination isn't in the set, it's rejected. No regex, no pattern matching, no partial matching. Just a set lookup.

Why This Works for AI Agents

The whitelist works because it's server-side. The AI can't bypass it. Even if Claude somehow figures out a way to send raw HTTP requests (which it shouldn't be able to through the MCP server), the server still checks the command against the whitelist.

The whitelist works because it's explicit. There's no "allow everything except..." logic. It's a pure allowlist — if it's not on the list, it's not allowed. This means I can't accidentally forget to block a dangerous command; I can only forget to allow a safe one (which is a much safer failure mode).

The whitelist works because it's at the right granularity. Blocking at the module level is too coarse. Blocking at the parameter level (e.g., "don't allow --app with certain IDs") is too fine. The subcommand level — assess form clear vs assess form remove — is the sweet spot. It's where the semantic difference between "delete one" and "delete all" lives.

What I Learned

After this incident, I made three changes:

Added more blocked commands to the documentation. The MCP tool descriptions now explicitly say "There is no bulk delete operation available." Claude doesn't need to go looking for one.
Added logging. Every blocked command is now logged with the timestamp, the command string, and the user token (to identify which AI agent tried it). I can see if Claude (or any other MCP client) attempts a blocked command.
Added a "dangerous operations" review. Once a month, I review the full command list and ask: "Is there any subcommand that an AI might reasonably try that I haven't explicitly allowed or blocked?" It's a manual process, but it catches edge cases.

The whitelist is the most boring piece of security infrastructure in the whole system. It's a set lookup. It's not fancy. But it's the one thing that stood between my production data and an AI that was trying to be efficient.

The formlm-cli MCP server is backed by a server-side command whitelist that blocks bulk operations. Open source at github.com/formlm/cli — try the platform at formlm.me.

DEV Community: Keo Fung | FormLM

The Facilitator's Stack: A Checklist From Invitation to Follow-Up

T-minus 2 weeks: design

T-minus 1 week: prep

Day before: the room

Day of: run it

Within 48 hours: follow-up

Monthly: keep the program alive

The whole stack, every URL in one place

The sentence to keep

From One-Off Workshop to Retainer: The Monthly Report Clients Actually Read

What the report needs to be

The pipeline: paste a table, get a branded PDF

The guide shelf worth reading even if you never buy

Wire it to the workshop series

The Debrief Is Where the Learning Happens. Most Facilitators Cut It

Why "what did we think?" fails

Give the room a private channel

Capture the trail — for yourself and for the client

The debrief of the debrief

I Let an AI Agent Prep My Workshop. Prep Took 20 Minutes.

Make the prep a skill file

The forms, via MCP

Honest limits, learned the hard way

Prove the Workshop Worked: Pre/Post Measures Without the Spreadsheet Pain

The measure that actually moves

From paper instrument to automatic before/after deltas

Free tools when you just need the math

What measurement won't do for you

Group Work That Doesn't Collapse Into Silence

Fix 1: Group people like you deal cards, not like you pick teams

Fix 2: Never give a group a topic — give them an artifact

Fix 3: Make the clock public and ruthless

Remote and hybrid rooms

The safety floor

Open the Room Without Forcing an App on Everyone

The joining cost is the whole ballgame

The first ten minutes: pairing instead of polling

What I don't use the screen for

Registration and Check-in That Runs Itself: Put the Paper to Work

The three anti-patterns

What paper actually wants to be

The room's paper layer

When you need something heavier

Steal a Run Sheet: What a Ready-to-Run Workshop Folder Contains

The anatomy of an activity folder

Why "a deck" is the wrong unit

Where to steal from, and what to file yourself

The honest limits

Design the Workshop Before You Build the Slides

Start with two sentences

The four-beat arc

From arc to run-of-show

Where AI and tools fit in design (and where they don't)

What's coming in this series

50 Forms in 30 Days: What I Learned Building Assessment Forms With an AI Agent

The Numbers

The 7 Bugs

1. The field_update Options Wipe (Critical)

2. The Staging/Production Profile Leak (High)

3. The assess form clear Attempt (High)

4. The Duplicate Fields (Medium)

5. The Boolean Trap (Medium)

6. The Reverse Scoring Confusion (Low)

7. The Forgotten App ID (Low)

What Worked Well

Schema-Driven Discovery

Natural Language to Field Structure

Safe Defaults

The Whitelist

What Didn't Work

State Management Across Sessions

Complex Scoring Configuration

Boolean Parameters

Environment Awareness

Patterns That Emerged

What I'd Do Differently

The Meta-Lesson

What's Next

The Whitelist That Saved My Production Data: A Security Boundary Story

1. The `field_update` Options Wipe (Critical)

3. The `assess form clear` Attempt (High)