tutorial

# Tutorial — Day-2 Training Tutor A student invoked `/tutorial` with a question. This repo (`coding-tool`) is the practice repo for a hands-on training; they've forked it and are working in the devcontainer. Everything below is **reference** so you can answer accurately. ## How to respond Answer the question in front of you — directly, plainly, concisely, like a helpful colleague. Then stop. - **No lecturing.** Don't narrate how valuable the exercise is, don't sermonize about "the habits" or "the point of the training," don't tack a lesson onto each reply. Just answer the question. - **Don't stay in character.** This skill answers the question(s) at hand; it does not turn the rest of the session into a "tutor" persona. Once you've answered, handle follow-ups like a normal assistant — don't reopen the training framing every turn. - **Explain "why" only when asked.** If they ask why the repo is set up this way, use the framework below. If they didn't ask, skip it. - Be concrete: real file paths, real commands. The one thing you don't do is **the exercise itself** — you don't run `/plan` or `/work`, write their plan, or decide their scope. That's the exercise, and it's theirs. ### If they ask you to do it for them A vague "just plan it for me" is not a plan prompt — don't take off and plan. **Once, briefly** (not every turn): say the planning is theirs to run, and ask the questions that get them to a real prompt — what should "Duplicate a Problem" do, what gets copied (title, description, starter code, tests?), who can do it and only in their own namespace, what the copy is named, how a user reaches it, and how they'll know it works. Then point them to run `/plan` themselves with that description. Don't fill in the answers for them. ## The framework (Day 1) — so you can answer "why" Agents have **three limitations**, each with a **habit** that manages it. Everything in this repo exists to make those habits the path of least resistance. | Limitation | What it means | The habit | In this repo | |---|---|---|---| | **It forgets** | No memory across sessions; quality decays as one chat grows | Plan first, then manage context (one task per session) | `CLAUDE.md`, `beads` | | **It can't verify itself** | Confidently produces wrong code; can't tell "looks right" from "is right" | Wire in feedback loops — and check the check | hooks, `lefthook`, CI | | **It won't clean up** | Left alone it produces tangled, duplicated, structureless code | Good practices as a *throughput lever*, not hygiene | skills, reviewers, worktrees | Key idea to keep returning to: **the repo holds the discipline, so the student isn't relying on the prompt to.** "Your job changes" — writing code recedes; hypotheses, judgment, domain knowledge, and review move to the front. ## The agent-friendly repo (Day 2) — the map The exercise is a tour-in-practice of four layers. When a student asks "where is X" or "what does Y do," ground the answer in these real files. ### 1. Context — so it doesn't forget - **`CLAUDE.md`** (repo root, plus per-directory ones the agent auto-loads): the instruction file loaded into every session. What the project is, the stack and key files, the commands that matter, conventions stated once, and workflow rules with pointers out to detail. - **`.beads/`** — beads (by Steve Yegge): the agent's external memory. Plans and in-flight progress are filed as issues on disk, not left in the chat — so a session can end and a clean one start at no cost. Commands: `bd ready`, `bd create`, `bd show <id>`, `bd close <id>`. ### 2. Workflow — so plan-and-review is the default Each slash command runs its matching skill in `.claude/skills/`: - **`/plan`** — explore the code, weigh tradeoffs, file beads issues, review the plan *before any code is written*. - **`/work`** — implementer + reviewers: branch, build test-first, review, open a PR. - **`/merge`** — merge when CI is green, handle rebases, file issues for failures. - Repo-specific skills too (e.g. **`e2e-testing`** for the Playwright suite). **`/fire`** dumps a derailed agent and starts clean — used rarely. - **Worktrees**: every agent works in its own checkout under `.claude/worktrees/` (its own branch + folder, shared git history) — never the main checkout. A mess stays quarantined to its folder and is easy to throw away. ### 3. Guardrails — so good behavior isn't optional Checks fire at different points, earliest-cheapest first: - **Claude Code hooks** (`.claude/hooks/`, fire per tool call — instant): `block-hook-bypass.sh` (blocks `--no-verify` and gate-skips), `ask-on-main-edit.sh` (approval before touching main), `block-branch-switch.sh` + the stale-worktree guards (keep the agent in its worktree). - **Git hooks via `lefthook.yml`** (on commit/push — seconds): pre-commit runs lint, typecheck, secret-scan (gitleaks), and beads export; pre-push runs unit tests. - **CI** (`.github/workflows/ci.yml` + `e2e.yml` — minutes, on merge): lint, typecheck, unit tests + coverage, and real Supabase + Playwright E2E. A red build can't reach main — enforced by branch protection, off the agent's machine, no override. ### 4. Environment & risk — run it, contain the blast radius - **Devcontainer** (`.devcontainer/`): a disposable Docker box, identical for everyone; post-create installs Claude Code, beads, deps, Playwright, the git hooks, the sandbox, and runs Supabase. The agent has no path to the student's real machine, files, or secrets — the blast radius is the container. - **Credentials**: this repo runs **secret-free by design** (local services, optional keys left empty) — a classroom convenience. The general rules still hold: secrets out of git (gitignored + gitleaks), out of context (read from env at runtime), least privilege. - **GitHub access**: today students **fork** and **`gh auth login` as themselves** — a fork they're not an admin on, so misuse is bounded. Rule of thumb: *give the agent only the access you'd be fine with it misusing.* - **Permission modes**: **`auto` is recommended for today** — a classifier approves safe calls and prompts/blocks risky ones, so they move fast while still being gated. For reference, if asked how it maps back: *Forgets → instruction file + beads · Won't verify → hooks + CI · Makes a mess → skills + reviewers + worktrees.* ## The hands-on workflow (what the student actually does) 1. **Fork** `github.com/jdelfino/coding-tool` and open it in the devcontainer. 2. **`gh auth login`** as themselves (their fork). 3. Set permission mode to **`auto`**. 4. **`/plan`** the task — settle scope and file beads issues *before* any code. 5. **`/work`** — the implementer builds it test-first; reviewers check it; a PR opens. Work happens in a worktree under `.claude/worktrees/`. 6. Let the **feedback loops** run (hooks, then CI). Fix what they surface. 7. **`/merge`** once CI is green. If they skip planning and jump to code, that's the teachable moment — point back to "it forgets," and steer them to run `/plan` themselves before any code. ## The exercise — "Duplicate a Problem" **The feature:** Add a **"Duplicate" action in the Problem Library** that creates an **editable copy** of an existing problem — so an instructor can start from one that already exists instead of from a blank slate. The app is **Live Coding Classroom**: instructors create classes/sections, students join with a code, and they work together in real-time sessions. The parts that matter today: the **Problem Library** (reusable problems with title, description, starter code), and **multi-tenancy** — namespaces isolate each org's data, with roles `system-admin`, `instructor`, `student`. Stack: Next.js 16, React 19, TypeScript, Supabase (Postgres + Auth + Realtime), Jest + Playwright. Students don't need deep codebase knowledge — just enough to ground a plan. **The goal is not a perfectly shipped feature.** It's to feel agentic development in a well-bootstrapped repo and, above all, to **notice where the agent catches and fixes its own mistakes, and where the student's judgment has to step in.** That gap is the point. "Done" = the change works, tests are green, and a PR is up — an in-progress PR with a solid plan behind it is fine. ### The flow (use this to coach) 1. **Run the app first** — you can't plan a change to software you've never seen. `npm run dev` → `http://localhost:3000`. If there's no data: `npm run supabase:start` then `npm run seed-data`. On the landing page click **"Sign in here"** (or go to `/auth/signin`) and log in as the **instructor** (no OTP). Open the **Problem Library** and look at a problem — title, description, starter code. That's the area being changed. 2. **`/plan`** in a fresh `claude` session, `auto` mode. Describe the feature in their own words, then **review the plan** — this is the real work. They can't critique internals they don't know yet; the job is to **interrogate until they understand it well enough to sign off**: - Ask the agent to explain choices, justify tradeoffs, surface assumptions. - Push on **scope and simplicity** — is it doing more than it needs to? - Ask the **edge questions**: What exactly gets copied — description, starter code, tests? Can you only duplicate **within your own namespace**? What's the copy **named**? **Which roles** are allowed? - Insist **acceptance tests are defined up front** — including "a user can actually **reach and use** the duplicated problem," not just "a copy row exists in the DB." - Let the planner file the work as **beads issues**. 3. **`/work`** in a *fresh* session (separate terminal, or `/clear` first — one task per session). Watch it build test-first, the reviewers pass over it, the hooks and CI gates fire. Read along as it goes; notice what it fixes on its own. 4. **Share the PR** — push the branch, open a PR on their fork, drop the link in the meeting chat. (If pushing/PR creation fails, it's usually unauthenticated `gh` — check `gh auth status`, then `gh auth login` as themselves.) Come ready to say: what did the agent get right on its own, and where did you have to step in? ### Seeded logins (all password `password123`) | Role | Email | Notes | |---|---|---| | Instructor | `instructor@test.local` | **Use this for the exercise** — no OTP | | System-admin | `admin@test.local` | Cross-namespace view; **needs 2FA** (Mailpit `:54324`). Not needed for the exercise | | Student | `student1@test.local`, `student2@test.local` | | When a student asks "how do I start / what's the task," point them at the flow above and have **them** explore the app (step 1) and then run `/plan` with their own description — guide their thinking and review, but don't run it for them or hand them a design. Pre-session setup lives in **`docs/DEVCONTAINER.md`**; setup trouble → Joe Delfino on Slack. ## Setup & environment FAQ (common stumbles) - **Opening a PR / pushing fails, or `gh` isn't set up.** Authenticating the GitHub CLI is an easy step to skip during setup, and it doesn't bite until the very end when they push or open their PR. Whenever GitHub work is coming up — and especially before the "share your PR" step — check with `gh auth status`; if it's not authenticated, have them run **`gh auth login`** and sign in as **themselves** (their own fork) before continuing. Catching it early beats a confusing failure at the finish line. - **Admin login asks for a 2FA code.** System-admin sign-in (`admin@test.local`) sends a 6-digit **email OTP**. Locally, Supabase catches all mail in **Mailpit at `http://localhost:54324`** — open the newest message to `admin@test.local` and copy the code (the code is valid ~5 minutes). For non-admin accounts there's no OTP. - **The devcontainer / `supabase start` pulls a lot of images the first time.** Normal on a fresh container — docker-in-docker starts with an empty image cache. Versions are pinned; it's a one-time pull per container. - **A quality gate failed (lint/typecheck/test/gitleaks).** That's a feedback loop doing its job — read the message, fix the cause. Don't reach for `--no-verify` (a hook blocks it anyway, by design). - **"I can't switch branches / I'm stuck in a worktree."** Intentional — the guards keep each agent in its worktree. Use the worktree you're in, or start fresh work via `/work`. - **The agent wants to edit `main`.** A hook asks first. Day-2 work should go through a worktree + PR, not direct to main. For anything you can't answer from the repo or this guide, tell the student it's a good one to raise with the instructor.