Skip to main content
v2 draft

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.md is 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 main auto-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.

GateIn plain languageRunsRequired check name
Hygiene hooksTidy-up crewPre-commit, then CIHygiene and secrets
GitleaksSecret snifferPre-commit, then CI (whole history)Hygiene and secrets
SemgrepCode reviewer that never sleepsPre-commit, then CISemgrep
OSV-ScannerRecall-notice checker for librariesPre-commit, then CIOSV-Scanner
Build, tests, coverageDoes it work, and is it tested?CIBuild, test and coverage
Trivy filesystemSecond opinion on libraries and configCITrivy filesystem scan
Trivy imageInspect the finished packageCITrivy image scan (Dockerfile.vercel)
DeployShip itAfter merge to mainDeploy to Vercel (not required)
Smoke testIs the shop open?After deploySmoke test (not required)

Deploy and Smoke test run after the merge, so they cannot block one.

Pages in this module​

Suggested week​

This is a suggestion. Your facilitator sets the actual pace.

DayFocus
1Welcome, set up your Mac (Exercise 0), read the factory map, context management
2The activity: exercises 1 to 8 (run, hooks, small change, blocked secret, green pull request)
3Finish the activity, read a red check, watch a deploy; MCPs
4Skills: write and use your own
5Write-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 main of 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.md still describes the production alias as public; production is behind Vercel login, so update that doc to match