🧶Loopcraft WorkshopAI Engineer · 2026
Build a local issue-progress loop you can trust.
You will build a small loop that can read issue events, check its own work, stop when it needs you, and leave receipts you can inspect.
The starting repo is prepared but not finished. Docker gives you the workshop computer, Herdr gives you the two-pane workspace, Pi gives you controls you can use, and Lakebed shows the loop state as it changes.
By the end, the loop can tell ready work from blocked work, ask before risky moves, show state in Lakebed, and run through Pi and Herdr controls.
- Lessons
- 8
- Repo
- public
- Status
- Pi + Herdr
- View
- Lakebed
Agent quickstart
If you are a coding or browser agent reading this page
Your role is to help someone run Lesson 01 from the public workshop repo. Use Docker as the happy path, start Pi inside the Herdr window that Docker opens, and stop before product code.
Public agent instructions are available at /agent.md, /AGENTS.md, and /llms.txt.
- Clone:
git clone https://github.com/joelhooks/aie-loopcraft-workshop-2026.git, thencd aie-loopcraft-workshop-2026. - Start Docker: run
corepack enable,corepack prepare pnpm@11.9.0 --activate, thenpnpm run workshop. - Start Pi: in the Herdr window opened inside Docker, start
piin a pane and use/loop-lesson-01. - Open Lesson 01: read Lesson 01, then follow the starter prompt.
- Fallback: if the slash command or local skill is unavailable, use the Lesson 01 page manually: ask one question at a time, write
VISION.md, and stop at boundaries.
Stop rules
- Do not require Herdr on the host machine; Herdr runs inside Docker.
- Do not assume private auth, private paths, raw transcripts, or Joel's local setup.
- Do not edit before the lesson asks.
- Lesson 01 stops at
VISION.mdand clear repo boundaries. No issue events, checks, Lakebed code, dispatch, or workers yet.
Agent starter prompt
You are a coding/browser agent helping me start the Loopcraft workshop from the public site.
Role: guide me through Lesson 01 only. Use the public repo and Docker path; do not assume Joel's private machine, host Herdr, private auth, or local paths.
Start:
1. Clone https://github.com/joelhooks/aie-loopcraft-workshop-2026.git and cd into aie-loopcraft-workshop-2026.
2. Run corepack enable, corepack prepare pnpm@11.9.0 --activate, then pnpm run workshop.
3. In the Herdr window opened inside Docker, start pi in a pane and use /loop-lesson-01.
4. Open /lessons/01-tour-vision-repo/ and use the starter prompt as the fallback if the slash command or local skill is unavailable.
Stop rules: do not edit files before Lesson 01 asks. Lesson 01 stops at VISION.md plus clear boundaries. Do not create issue events, checks, Lakebed code, dispatch, or workers yet. Report commands run, files changed, checks, and blockers.Agent links: /agent.md, /AGENTS.md, /llms.txt, Lesson 01, repo, setup.
System map
Get started
Use Docker as the main path. You need Git, Docker Desktop or OrbStack, and Corepack for the pinned pnpm command. Herdr opens inside the container, so you do not need Herdr installed on your host machine.
Before you run the start command, make sure either docker compose version or docker-compose version works. If both fail, install or update Docker Desktop / OrbStack first.
- Clone the repo.
git clone https://github.com/joelhooks/aie-loopcraft-workshop-2026.git cd aie-loopcraft-workshop-2026 - Enable the pinned package manager if this machine has not used pnpm yet.
corepack enable corepack prepare pnpm@11.9.0 --activate - Start the workshop computer.
pnpm run workshop
That command opens Herdr inside the Docker container. Start pi from a Herdr pane, sign in if Pi asks, then use /loop-lesson-01.
If startup fails
Use the direct commands below before changing your host machine setup.
Pull the image, then open Herdr in the container:
pnpm run workshop:pull
pnpm run workshop:herdrIf the package is still private, sign in to GHCR and pull again:
gh auth refresh -h github.com -s read:packages
gh auth token | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
pnpm run workshop:pullIf the image is unavailable, build it locally:
pnpm run workshop:build
pnpm run workshop:herdrIf Herdr is the blocker, use Pi directly inside the same Docker image:
pnpm run workshop:piMore fallback notes live in docs/setup.md. If you are intentionally avoiding Docker, use the full setup without Docker appendix.
Tools we use
Pi
The coding-agent shell for the workshop. You use it to ask for the next small move, inspect evidence, and stop before risky work.
- What it does here
- Starts the repo tour, loads the Lesson 01 prompt, and later exposes local commands for status and checks.
- When you touch it
- You want to inspect the loop, ask for a small pass, or decide whether the loop may continue.
Herdr
A terminal multiplexer for coding agents. In this workshop it is the visible workbench: Pi in one pane, logs or runtime state in another.
- What it does here
- Keeps the chat, commands, daemon output, and status visible in one container session.
- When you touch it
- You need to see whether the loop is alive, stuck, waiting, or finished.
Docker Compose
The workshop computer. It runs the pinned tools in a container so your host machine stays boring.
- What it does here
- Runs Herdr, Pi, Claude Code, Codex, OpenCode, and the local repo in one repeatable container.
- When you touch it
- You start the day, reset a broken container, or build the image locally.
Lakebed
The small app view for loop state. It shows the same issue facts the local loop is using.
- What it does here
- Projects issue events into list, board, and event views without becoming the source of truth.
- When you touch it
- You want to compare what the loop thinks with what you see.
Effect
A TypeScript toolkit for typed data, errors, and effects. Here it guards messy issue input before the loop trusts it.
- What it does here
- Adds schemas, typed errors, and clear failure output around issue events and checks.
- When you touch it
- You read files, accept tool output, or turn loose text into data the loop can trust.
XState
A state-machine library for work that can be ready, blocked, waiting, running, failed, cancelled, or stopped.
- What it does here
- Turns stop rules, dispatch, recovery, and supervision into explicit states instead of hidden booleans.
- When you touch it
- A flow needs retries, approval gates, cancellation, or a clear recovery path.
pi-subagents
A Pi package for bounded specialist help. Scouts and reviewers can produce notes without taking over the loop.
- What it does here
- Adds narrow review and research passes once the main loop has enough guardrails.
- When you touch it
- You want a second read on evidence, design, or risk before you approve a move.
Claude Code, Codex, OpenCode
Other coding-agent shells you can compare inside the same workshop computer. Pi stays the main path.
- What it does here
- Lets you compare how other agent shells behave against the same repo, prompts, and checks.
- When you touch it
- You want to compare agent-shell behavior after the core loop is working.
Guardrails
The fast local checks we add in front of the agent loop, one at a time, so failure is visible instead of mysterious.
- What it does here
- Introduces pnpm, TypeScript, tsgo, oxlint, oxfmt, Ultracite, tests, and hooks as visible setup steps.
- When you touch it
- You need the loop to fail early, explain why, and avoid repeating the same mistake.
Lesson path
Each lesson is a checkpoint with something to prompt, build, inspect, or decide. If a term slows you down, use the glossary appendix. If Docker is not the right path for your machine, use the local setup appendix before Lesson 01.
- 01 Tour the repo and set the course
Use Pi plus grill-with-docs to write VISION.md: what the local issue checker should do, which files it may edit, and when it must stop.
- 02 Make bad input fail loudly
Turn VISION.md into one local event file, one check command, tests, and a saved receipt from a real run.
- 03 Show issue events in Lakebed
Read the same local event file from Lesson 02 and show matching issue cards in Lakebed.
- 04 See and control the check from Pi and Herdr
Add a visible way to ask for status, run the local check, and see what happened.
- 05 Claim one ready issue without changing product files
Pick one ready issue, write a claim, run a dry-run, and prove no product files changed.
- 06 Let cleanup propose one follow-up
Let the checker propose one maintenance event, then prove it stops when the repo or queue is not safe to touch.
- 07 Ask for review without handing over the repo
Ask a small reviewer for help without letting another agent edit the app files.
- 08 Compare a candidate check beside the current check
Use the same event file and check command while a small TypeScript candidate check says the next state and reason. The current checker still decides.
Repo map
Start the workshop
package.json— Docker and site commands.docker-compose.yml— mounts the repo into/workspaceand keeps tool state in Docker volumes.docker/workshop.Dockerfile— pinned Pi, Herdr, Claude Code, Codex, OpenCode, Node, pnpm, and shell setup.WORKSHOP_RIG.md— quick map of the prepared rig and what is intentionally left for the lessons.
Ask for help inside the repo
agents/skills/loopcraft-ta— local guide skill for this repo.agents/skills/grill-with-docs— guided questioning for Lesson 01 vision and boundaries..agents/skillsand.claude/skills— symlinks that expose the local skills to agent tools..pi/extensions/loop-workshop.ts— Pi commands such as/loop-workshop-statusand/loop-lesson-01.
Build the loop
lessons/— step-by-step checkpoints from repo tour to supervisor runtime.- Glossary appendix — plain-language terms linked back to the lessons that use them.
scripts/loop-daemon-stub.mjs— temporary status process for the Herdr runtime pane.surface/lakebed/— Lakebed view shell for issue state..agent_sources/— local source mirrors for Effect, XState, and pi-subagents when you need receipts.