Module 1 is written in full but is still a draft. Check commands and screenshots against the repo before the cohort starts.
Module 1: Operate a Good Factory
Sizing: 5 days (Week 1)
What this module is for
Before you can fix a broken project, you need to know what a working one feels like. This week you operate a repo where every safety check is already in place, and you push one small change through all of it. You are not building the factory yet. You are learning to recognize one.
You do not need to be an engineer for this module. The aim is the instinct to run a quality check before something ships, and to read what the check tells you.
Outcome
By the end of the week you can:
- Name each gate in the factory, say what it protects against, and say where it runs
- Take a small change from your computer to a green pull request
- Read a failing check and say what it means
- Use your AI agent with the repo's instructions, a lean set of tools, and a skill you wrote
The practice repo
liatrio-labs/emerald-grove-hotels is a small hotel-booking web app (Spring Boot, Java 21). It ships fully wired:
AGENTS.mdis the only agent-instruction file- Pre-commit hooks run on your computer: hygiene checks, Gitleaks, Semgrep and OSV-Scanner
- CI runs on every pull request: build, tests and a 75% coverage floor, plus the same hooks and two Trivy scans
- Dependabot opens weekly pull requests to update dependencies
- A merge to
mainauto-deploys to Vercel, and a smoke test is the final gate
The repo's own docs/factory.md is the source of truth for gate names. You work in your own fork of the repo, so everything you change, merge and break is yours.
The factory in one table
A change passes through three places, in order: your computer, the pull request, and after the merge. The earlier a problem is caught, the cheaper it is to fix.
| Gate | In plain language | Runs | Required check name |
|---|---|---|---|
| Hygiene hooks | Tidy-up crew | Pre-commit, then CI | Hygiene and secrets |
| Gitleaks | Secret sniffer | Pre-commit, then CI (whole history) | Hygiene and secrets |
| Semgrep | Code reviewer that never sleeps | Pre-commit, then CI | Semgrep |
| OSV-Scanner | Recall-notice checker for libraries | Pre-commit, then CI | OSV-Scanner |
| Build, tests, coverage | Does it work, and is it tested? | CI | Build, test and coverage |
| Trivy filesystem | Second opinion on libraries and config | CI | Trivy filesystem scan |
| Trivy image | Inspect the finished package | CI | Trivy image scan (Dockerfile.vercel) |
| Deploy | Ship it | After merge to main | Deploy to Vercel (not required) |
| Smoke test | Is the shop open? | After deploy | Smoke test (not required) |
Deploy and Smoke test run after the merge, so they cannot block one.
Pages in this module
- Fundamentals: context management, MCPs and skills, with a short exercise for each
- Activity: Ship a change: Mac setup, then fork to green pull request, step by step
Suggested week
This is a suggestion. Your facilitator sets the actual pace.
| Day | Focus |
|---|---|
| 1 | Welcome, set up your Mac (Exercise 0), read the factory map, context management |
| 2 | The activity: exercises 1 to 8 (run, hooks, small change, blocked secret, green pull request) |
| 3 | Finish the activity, read a red check, watch a deploy; MCPs |
| 4 | Skills: write and use your own |
| 5 | Write-up and demo |
What you hand in
- A green pull request in your own fork of the repo
- Evidence of the blocked fake-secret commit
- A five-line write-up of your change's journey
- A short demo: what your change was, which gate did what, what you would check next time
Habits to build
- Read the diff before you accept it, whether you or an agent wrote it
- Anything you approve must be short enough to review in a few minutes. If it is not, send it back to be condensed.
- Defend your work: be able to explain each choice if asked
- A green gate is not proof until you know what it checks
Pitfalls
- Touring the repo without shipping anything
- Approving agent output you have not read
- Treating a green check as proof without knowing what it checks
- Loading every tool server into your agent at once
Where this goes next
Week 2 hands you a repo that has most of these safety checks missing or ignored. What you learn to recognize this week is what you will go looking for.
From v1
- Carries over, edited: environment setup, install verification, MCP and skills setup, context management
- Dropped: the SDD install; the Pet Clinic fork becomes the Hotels fork
TODO
- TODO: confirm
mainof the good repo carries the factory before the cohort starts - TODO: decide how learners pick up issues in their fork (forks have issues turned off by default); see
week1-activity-options.md - TODO: run the cold-run checklist on a clean Mac and fix whatever it exposes
- TODO: fit check for nontechnical learners: Mac setup, the activity and the fundamentals inside 5 days
- TODO: the repo's
docs/factory.mdstill describes the production alias as public; production is behind Vercel login, so update that doc to match