Chapter 1: An App the Agent Can Work In

This chapter scaffolds the app, adds sign-in, and shows you the two parts of the harness that the rest of the course leans on. You write no application code.

What you'll learn:

• What create-guren-app installs for the agent, and where it lives
• The two skills that carry a plan: plan-write and plan-implement
• What the Stop hook does when the agent says it is done

1. Scaffold

bunx create-guren-app guren-meetups --mode ssr --db sqlite --agents claude --git

cd guren-meetups

Meetups belong to users, so the app needs accounts before anything else:

bunx guren add auth
bun run db:migrate

add auth writes the users table, the sign-in and sign-up pages, and the session wiring. Check the result with the gate, the same one CI runs:

bunx guren gate

Every stage should pass: codegen, typecheck, lint, check, audit and the tests. Codegen also refreshed the typed manifests under .guren/, so commit after the gate, not before:

git add -A
git commit -m "feat: add sign-in"

2. What the agent reads

--agents claude installed a harness. Three parts of it matter here:

Path	What it does
CLAUDE.md	The first thing the agent reads: which guren commands answer "what is in this app?"
.claude/skills/	Procedures the agent follows for a kind of task. plan-write and plan-implement are this course's
.claude/hooks/gate-on-stop.ts	Runs when the agent finishes a turn (below)

ls .claude/skills

plan-write turns a request into docs/plans/<slug>/plan.json. It asks you what it cannot decide, checks the plan against the app, and stops. It never approves.

plan-implement builds an approved plan one step at a time, with one commit per step.

The Stop hook

When the agent ends a turn, gate-on-stop.ts runs guren gate on uncommitted work: codegen, typecheck, lint, check, audit and the tests. If a stage fails, the hook blocks the stop once and hands the findings back to the agent. During a plan it also verifies the step the agent is on, and sends the agent back up to three times while the step is not verified.

flowchart LR
  Stop["Agent ends its turn"] --> Gate["gate-on-stop.ts<br/>gate + the current plan step"]
  Gate -- "green" --> Done["Turn ends"]
  Gate -- "red, at most 3 times" --> Back["Findings go back to the agent"]
  Back --> Stop

The gate is the one you ran in section 1. You will not configure any of this. It is why "the agent says it's done" and "it is done" come close to meaning the same thing.

Claude Code's own documentation covers each part: CLAUDE.md, skills, and hooks, including the Stop and SessionStart events this course relies on.

3. Start the agent

Open a second terminal in guren-meetups and start Claude Code:

claude

Leave it open. From chapter 2 on, what you send the agent appears in a code block: copy it into this session and send it.

Where you are

• A scaffolded app with sign-in, committed.
• A harness the agent reads, with the two plan skills and the Stop hook.

Common trip-ups

• bunx guren is not found. Run it inside guren-meetups, where @guren/cli is installed. The guren package on npm is a placeholder.
• db:migrate fails with "no such file". Run it from the app root, not the directory above it.

Exercises

1. Open .claude/skills/plan-write/SKILL.md. Find the one command it tells the agent never to run, and the reason it gives.
2. Run bunx guren context. This is what the SessionStart hook injects into every agent session. Which of its sections would you read first before planning a change?

Exercise 1: hint and an example answer

Read the opening paragraph, before the numbered steps.

The command is plan:approve. The skill says approving is the person's decision, made after reading the review page. Its last section names the command only to say that you, not the agent, will run it.

Exercise 2: hint and an example answer

The output has one ## section per kind of thing: Stack, Models, Routes and Pages, then Controllers, Policies and the other kinds the app has, and an API digest at the end.

One good answer is Routes. Its table gives each route's method, path, name and controller action, the same names a plan uses, so a change that reuses or collides with an existing name shows up there first. Models comes next, for the tables and relationships the change will point at. Other answers work too: for a change that is mostly UI, Pages is a fair place to start.

Next

Chapter 2: The First Plan asks the agent for a plan and shows you how to read what comes back.