Les 2 Klas B — OpenCode Pro met AGENTS.md, worktrees & GSAP/Lenis

This commit is contained in:
2026-05-18 14:30:00 +02:00
parent 0393976b23
commit b053fc7206
10 changed files with 2506 additions and 0 deletions

View File

@@ -0,0 +1,536 @@
# Les 2 — OpenCode Pro: Rules, Worktrees & Scroll Animations
## Docenttekst + Docenthandleiding (Klas B — 2 uur, online)
**Les:** 2 van 18
**Duur:** 120 minuten online
**Vorige les:** Les 1 — Introductie AI Developer leerlijn
---
## Leerdoelen
- Begrijpen waarom we OpenCode kiezen i.p.v. Cursor (multi-provider, open source, alternatieven)
- OpenCode Desktop kunnen draaien met Plan/Build/@explore/init
- `AGENTS.md` regelbestand schrijven (officieel format)
- `opencode.json` config met permissions
- `opencode-worktree` plugin via `ocx` installeren
- Parallel agents via Sessions sidebar
- Live: Next.js 16 + GSAP + Lenis scroll-site opzetten
---
## Lesflow
**Geen heen-en-weer switchen.** De les is opgedeeld in:
- **Theorie 1** — uninterrupted uitleg (slides 4-6)
- **Live Demo 1** — alle features tonen achter elkaar (slide 7)
- **Theorie 2** — uninterrupted uitleg (slides 8-12)
- **Live Demo 2** — setup + bouw SmoothScroll (slide 13)
- Pauze
- Lesopdracht
---
# DEEL 1 — Docenthandleiding (volg dit live tijdens de les)
## VÓÓR DE LES — Setup (30 min)
### 1. OpenCode Desktop
- Download van https://opencode.ai/download
- Installeer
- Log in met OpenAI key (uit Brightspace)
### 2. `ocx` + worktree plugin
```bash
curl -fsSL https://kdco.dev/ocx/install.sh | sh
ocx add kdco/worktree --from https://registry.kdco.dev
```
Sluit en open OpenCode opnieuw zodat plugin geladen wordt.
### 3. Demo-repo aanmaken
```bash
cd ~
npx create-next-app@latest scroll-demo \
--typescript --tailwind --app --eslint --no-src-dir --turbopack
cd scroll-demo
npm install gsap @gsap/react lenis
git init
git add .
git commit -m "init: next 16 + gsap + lenis"
```
### 4. Test je setup
- Open OpenCode Desktop → File → Open Folder → `~/scroll-demo`
- Type in chat: `Wat is de stack?` → moet Next.js 16 + Tailwind herkennen
- Type `/init` en abort (Esc) — alleen testen dat 't werkt
- Maak test-worktree om plugin te valideren:
```
Maak een testworktree feature-test
```
- Klik **+ New Session** linksboven, open folder van die worktree
- Sluit Session, verwijder worktree:
```bash
git worktree remove ~/.local/share/opencode/worktree/scroll-demo/feature-test
```
### 5. Browser tabs open
- https://opencode.ai/download
- https://opencode.ai/docs/rules/
- https://gsap.com/resources/React/
- https://github.com/kdcokenny/opencode-worktree
### 6. Backup plan
Als plugin live faalt:
```bash
git worktree add ../scroll-demo-hero -b feature-hero
```
Dan handmatig nieuwe Session → Open Folder.
---
## TIJDENS DE LES
### Blok 1 — Welkom + Terugblik (10 min)
**Slides 1, 2, 3.**
- Start meeting
- Slide 2: vraag in chat: "Wie heeft tot nu toe alleen met chat (ChatGPT/Claude) gewerkt?"
- Slide 3: planning langslopen. **Benadruk** dat we eerst theorie geven, dan demo, dan weer theorie, dan demo. Geen heen-en-weer.
**Geen demo nodig in dit blok.**
---
### Blok 2 — THEORIE 1: Waarom OpenCode + Kern features (20 min)
**Slides 4, 5, 6. Achter elkaar, zonder switchen.**
#### Slide 4 — Waarom OpenCode (en niet Cursor) — 6 min
**Vertel:**
"Iedereen kent Cursor. Sommigen gebruiken het al. Goede tool. Waarom beginnen we dan met OpenCode?
Drie redenen.
**Eén — alternatieven kennen is professioneel.** Wie alleen Cursor kent, zit vast aan één tool. Een goede dev kent meerdere coding-assistenten en kiest per project.
**Twee — provider-keuze.** Cursor heeft eigen routing — jij hebt niet vol overzicht welk model wanneer wordt gebruikt. OpenCode is provider-agnostisch: OpenAI vandaag, Anthropic morgen, lokaal met Ollama als je dat wilt. Jij beslist.
**Drie — open source = geen lock-in.** Voor je eindopdracht en je carrière is dit relevant. Tools veranderen, abonnementen veranderen. Open source blijft beschikbaar.
Belangrijk: dit is **geen Cursor-bashing**. Cursor is uitstekend. We komen er later in de leerlijn op terug. Vandaag de open variant — dan kun je daarna zelf kiezen."
Loop tabel langs.
#### Slide 5 — Wat is OpenCode — 7 min
**Vertel:**
"OpenCode is een AI coding-IDE. 60.000+ GitHub stars. Gemaakt door SST. Werkt met elke provider — OpenAI, Anthropic, Google, Groq, of lokaal met Ollama.
Twee smaken: Desktop en TUI. Wij gebruiken Desktop. Waarom?
- Visuele diff-viewer (klik accept/reject)
- File tree links, Sessions sidebar
- Multiple sessies naast elkaar
- Sneller leren als je begint
De TUI bestaat ook. Goed voor SSH-servers, scripts, CI/CD. Ik laat 'm 1 minuut zien in de demo — daarna 100% Desktop."
Loop tabel langs.
#### Slide 6 — Plan/Build/@explore + /init — 7 min
**Vertel:**
"Vier dingen die je echt moet kennen.
**Modes** — twee modes, Tab om te wisselen:
- **plan** is read-only. Denkt mee, leest files, wijzigt niks. Goed voor verkenning en brainstorm.
- **build** is default. Schrijft code, voert commands uit.
**Sub-agents** — drie ingebouwde:
- `@explore` is read-only verkenning. Eigen context, spaart tokens.
- `@general` is brede taak.
- `@scout` is gerichte zoek.
**`/init` commando** — eerste actie in elk nieuw project. Scant je repo, stelt vragen, schrijft je `AGENTS.md`.
**Best practice:** plan eerst, lees mee, geef feedback, dan Tab → build. Dit voorkomt rommel.
Dat was de theorie. Nu zien jullie het live."
---
### Blok 3 — LIVE DEMO 1: Desktop Tour (10 min)
**Slide 7.**
**Setup vooraf:** OpenCode Desktop open op `~/scroll-demo`. Systeem-terminal open naast OpenCode voor de TUI-demo.
#### Stap 1 — TUI in 1 minuut (1 min)
- Switch naar systeem-terminal
- Type: `opencode`
- Toon kort de TUI met chat onderaan
- Type: `wat is de stack van dit project?` → krijg antwoord
- Druk **Tab** → switch naar plan mode → tab terug
- **Ctrl+D** om te sluiten
**Zeg:** "Dat was de TUI. Werkt prima. Vandaag verder met Desktop."
#### Stap 2 — Desktop UI tour (2 min)
- Switch naar Desktop
- Wijs aan:
- **File tree** links (klik op `app/page.tsx` om te tonen)
- **Chat panel** onderaan
- **Diff viewer** in midden
- **Sessions sidebar** (toon dat 't er is, leeg op één session na)
- **Model selector** + **mode indicator** bovenin
**Zeg:** "Alles op één scherm. File tree, chat, diff. Veel makkelijker dan switchen tussen terminals."
#### Stap 3 — Plan mode demo (2 min)
- Onder in chat, check dat mode-badge op `build` staat
- Druk **Tab** → wisselt naar `plan`
- Type in chat: `analyseer dit project en stel verbeteringen voor`
- Wacht op antwoord
- **Zeg:** "Zie? Concrete voorstellen. Geen file wijzigingen. Veilig om los te laten."
#### Stap 4 — Build mode demo (2 min)
- Druk **Tab** → terug naar `build`
- Type: `voeg een comment bovenaan app/page.tsx toe met de tekst "scroll demo"`
- Toon diff in viewer — klik **Accept**
- Open `app/page.tsx` in file tree — comment staat er
**Zeg:** "Plan is denken, build is doen."
#### Stap 5 — @explore demo (1.5 min)
- Type in chat: `@explore wat is de folder structuur van dit project?`
- Toon dat het in eigen context werkt
- **Zeg:** "Read-only sub-agent. Spaart tokens, kan niks kapot maken."
#### Stap 6 — /init demo (1.5 min)
- Type: `/init`
- Beantwoord de vragen die OpenCode stelt (Next.js 16, GSAP, scroll-animaties)
- Wacht tot AGENTS.md gegenereerd is
- Open `AGENTS.md` in file tree — toon wat 't gegenereerd heeft
- **Zeg:** "Dit is een goede basis. Volgende blok: hoe we 'm aanvullen met onze regels."
---
### Blok 4 — THEORIE 2: AGENTS.md + opencode.json + plugin + stack (15 min)
**Slides 8, 9, 10, 11, 12. Achter elkaar, zonder switchen.**
#### Slide 8 — AGENTS.md — 3 min
**Vertel:**
"Belangrijkste concept van vandaag. `AGENTS.md` is **dé** manier om OpenCode jouw regels te geven. Officieel format, automatisch in elke context.
Twee locaties:
- `./AGENTS.md` in je repo — versioned, deelt met team
- `~/.config/opencode/AGENTS.md` — globaal, jouw persoonlijke voorkeuren
Externe regels mag je referencen met `@rules/styling.md` — agent laadt 'm lazy.
Tip: schrijf je AGENTS.md zoals je 'm aan een junior dev zou geven. Concreet, controleerbaar."
#### Slide 9 — opencode.json — 3 min
**Vertel:**
"Naast regels heb je config. Welk model, welke permissies, welke plugins.
`$schema` geeft autocomplete in je editor.
`model` is `provider/model-id`.
Belangrijkste is **permissions**. Drie levels: `allow`, `ask`, `deny`. Glob patterns voor bash én files.
Voor student-project: `bash.*` op `ask` is veilig — je reviewed elke shell command. Productie: alleen specifieke folders editable."
#### Slide 10 — Worktree plugin — 3 min
**Vertel:**
"Plugin van **kdcokenny** — community lid, ook achter `ocx` extension manager. Twee tools voor de agent:
- `worktree_create` — branch + worktree
- `worktree_delete` — commit + cleanup
Installatie via `ocx`. Restart na install.
Verschil TUI vs Desktop:
- TUI: plugin spawnt automatisch nieuw terminal venster
- Desktop: plugin maakt de worktree, jij opent 'm in nieuwe Sessions tab
Klein verschil, zelfde resultaat: parallel agents."
#### Slide 11 — Demo stack — 3 min
**Vertel:**
"De stack waarmee we vandaag bouwen — en waarom dit dé combinatie is voor scroll storytelling.
**Next.js 16** — uit oktober 2025. Belangrijkste verandering t.o.v. 15: `cookies()`, `headers()`, `params`, `searchParams` zijn allemaal async. Altijd `await`. Turbopack is default — snellere builds.
**GSAP 3.15** — sinds januari 2025 100% gratis, incl. ScrollTrigger en SplitText. Hét animatie-pakket op pro-niveau. Apple product pages, Stripe homepage, OpenAI marketing — allemaal GSAP. Award-winning sites op Awwwards en FWA: vrijwel altijd GSAP.
**Lenis 1.3** — door **Darkroom Engineering** (voorheen Studio Freight, een award-winning studio uit Brooklyn die zelf onder andere voor Studio Freight, Activision en Riot werkt). Beste smooth scroll lib. Integreert naadloos met GSAP ScrollTrigger.
**`@gsap/react`** — geeft je de officiele `useGSAP` hook. Drop-in voor useEffect met auto cleanup.
**Waarom niet Framer Motion?**
Framer Motion is uitstekend — voor app UI. Modals, page transitions, micro-interacties. Maar voor scroll storytelling (zoals jij gaat bouwen) wil je timing-precisie en GPU-optimalisaties die GSAP biedt en Framer Motion niet matcht. Pro-studios zoals **Active Theory**, **Locomotive**, **Resn**, **Darkroom Engineering** — allemaal GSAP-based.
Daarom staat in onze AGENTS.md: 'Geen Framer Motion'. Het is geen anti-Framer, het is pro-GSAP voor dit type werk."
#### Slide 12 — Onze AGENTS.md — 3 min
**Vertel:**
"Hier zie je onze concrete regels voor dit project. Let op de structuur:
- Stack — versies expliciet
- Hard rules — niet onderhandelbaar
- Patterns — hoe we organiseren
- Done — wat klaar betekent
Regels die opvallen:
- 'Geen Framer Motion' — voorkomt dat AI default naar 't bekendere
- 'useGSAP, nooit useEffect' — werkt met Strict Mode
- 'Lenis sync via gsap.ticker.add' — voorkomt jank
- 'await params in Next 16' — anders runtime error
Deze regels heb ik uit ervaring. In de volgende demo zet ik dit in, en zie je dat de AI ze volgt."
---
### Blok 5 — LIVE DEMO 2: Setup + Worktree + SmoothScroll (15 min)
**Slide 13.**
**Setup vooraf:** OpenCode Desktop nog open op `~/scroll-demo`. Plugin al geïnstalleerd.
#### Stap 1 — AGENTS.md vervangen (3 min)
- Open `AGENTS.md` in Desktop file tree
- Selecteer alles → vervang met content uit slide 12:
```markdown
# Project Rules
## Why this stack
High-end scroll storytelling site (Awwwards/FWA niveau).
GSAP + Lenis = pro standaard — Apple, Stripe, OpenAI, Active Theory,
Locomotive, Darkroom Engineering. Framer Motion is voor app UI, niet voor
scroll storytelling. Kies GSAP voor timing-precisie + GPU-perf.
## Stack
- Next.js 16 (App Router, TypeScript, Turbopack)
- TailwindCSS · GSAP 3.15+ (incl. ScrollTrigger, SplitText)
- Lenis 1.3+ (`lenis/react`)
- @gsap/react voor de useGSAP hook
## Hard rules
- Geen Framer Motion, react-spring, AOS
- Animaties altijd in Client Components (`"use client"`)
- Animatie-code in useGSAP(() => {}, { scope: ref })
- Nooit useEffect voor GSAP code
- Lenis sync: gsap.ticker.add met autoRaf: false
- Next 16: await params, await cookies(), await headers()
## Patterns
- Eén <SmoothScroll> wrapper in app/layout.tsx
- Tailwind voor layout; GSAP voor transform/opacity
## Done =
- Geen hydration warnings
- ScrollTrigger.refresh() na dynamische content
```
- Cmd+S
- Type in chat: `Lees AGENTS.md. Welke regels ga jij volgen, en waarom kiezen we deze stack?`
- Toon dat het ook de **why** uitlegt — niet alleen de regels napapegaait
#### Stap 2 — opencode.json maken (3 min)
- Right-click in file tree → New File → `opencode.json`
- Plak:
```json
{
"$schema": "https://opencode.ai/config.json",
"model": "openai/gpt-4o-mini",
"permission": {
"bash": {
"*": "ask",
"git *": "allow",
"npm *": "allow",
"rm *": "deny"
}
}
}
```
- Cmd+S
- Restart OpenCode (File → Reload Window)
- Type: `rm -rf node_modules` → toon dat 't blokkeert
- Type: `git status` → toon dat 't direct werkt
- **Zeg:** "Geen surprises meer."
#### Stap 3 — Worktree plugin in actie (3 min)
- Type: `Welke tools heb je beschikbaar?`
- Wijs aan: `worktree_create`, `worktree_delete` in lijst
- Type: `Maak een worktree feature-hero voor een hero-sectie.`
- Wacht tot plugin klaar is
- Klik **+ New Session** linksboven
- **Open Folder** → navigeer naar `~/.local/share/opencode/worktree/scroll-demo/feature-hero/`
- Nieuwe Session opent — toon dat 't naast main staat in sidebar
#### Stap 4 — SmoothScroll laten bouwen (5 min)
- In de **feature-hero** Session, type:
```
Bouw een SmoothScroll wrapper component volgens AGENTS.md.
Plaats in components/SmoothScroll.tsx en wrap children in app/layout.tsx.
```
- Wacht op diff
- **Wijs aan wat de regels volgen:**
- `"use client"` bovenaan
- `useGSAP` import (niet useEffect)
- `gsap.ticker.add` met `autoRaf: false`
- Geen Framer Motion of andere libs
- Klik **Accept**
#### Stap 5 — Bewijs van regels (1 min)
**Zeg:** "Zie je? Met goede AGENTS.md krijg je consistente output. Zonder zou de AI waarschijnlijk Framer Motion pakken of useEffect gebruiken. Schrijf je regels op, krijg je betrouwbare resultaten."
---
### Blok 6 — Pauze (15 min)
**Slide 14.**
Stuur in chat: "Terug over 15 minuten." Camera mag uit.
---
### Blok 7 — Lesopdracht (35 min)
**Slide 15.**
#### Briefing (3 min):
"Eigen worktree maken, sectie kiezen, bouwen. Plan eerst, dan Build."
Loop checklist op slide 15 langs.
#### Tijdens 30 min werken:
- Tim blijft in main meeting-room
- Breakout-rooms op verzoek
- Check in chat: "Wie heeft worktree? Type W." → "Wie ziet animatie? Type A."
#### Veelvoorkomende problemen:
| Probleem | Oplossing |
|----------|-----------|
| Plugin niet beschikbaar | `ocx list` om te checken |
| Worktree-tool onbekend | Desktop herstarten na ocx add |
| Sessions sidebar leeg | Klik `+ New Session` |
| `useGSAP is not a function` | `npm install @gsap/react` |
| Hydration mismatch | `"use client"` mist of `useEffect` ipv `useGSAP` |
| Lenis import error | Niet `@studio-freight/lenis`, maar `lenis` |
| ScrollTrigger niets | `gsap.registerPlugin(ScrollTrigger)` mist |
| Async params error Next 16 | `await params` toevoegen |
#### Check-in (~25 min in):
"Wie heeft werkende animatie? Type A in chat." Bij <50%: 5 min klassikaal debug.
---
### Blok 8 — Huiswerk + Afsluiting
**Slides 16, 17.**
- Loop huiswerk eisen langs
- "Volgende keer: **Introductie Cursor** — de commerciele tegenhanger. Cursor rules vs AGENTS.md, Composer, wanneer welke tool."
- Vragen + feedback
---
# DEEL 2 — Docenttekst (referentie per slide)
## Slide 4 — Waarom OpenCode
Vertel waarom **niet** Cursor:
- Cursor is goed maar commercieel ($20/mnd), eigen routing
- OpenCode is gratis (alleen API-kosten), open source, jij kiest model
- Voor je carriere: meerdere tools kennen > vasthangen aan één
- We komen later in leerlijn terug op Cursor — vandaag de open variant
## Slide 5 — Wat is OpenCode
Provider-agnostisch, scriptable, multi-instance. Twee smaken: Desktop (vandaag), TUI (kort tonen).
## Slide 6 — Plan/Build/@explore + /init
Tab voor mode switch. `@explore` voor verkenning. `/init` voor eerste AGENTS.md.
## Slide 8 — AGENTS.md
Officieel format. Automatisch in context. Concrete regels werken, vage regels niet.
## Slide 9 — opencode.json
Schema voor autocomplete. Model. Permissions (allow/ask/deny). Plugins.
## Slide 10 — Worktree plugin
Via ocx installeren. Twee tools voor agent. Desktop: nieuwe Session tab; TUI: auto terminal.
## Slide 11 — Stack
Next.js 16 (async params, Turbopack). GSAP gratis. Lenis door darkroomengineering. useGSAP hook.
## Slide 12 — Onze AGENTS.md
Concrete regels die voorkomen dat AI default naar bekende-maar-verkeerde keuzes (Framer Motion, useEffect).
---
## Bronnen voor studenten
**OpenCode:**
- Docs: https://opencode.ai/docs/
- Download: https://opencode.ai/download
- Rules: https://opencode.ai/docs/rules/
- Config: https://opencode.ai/docs/config/
- GitHub: https://github.com/sst/opencode
**Plugin:**
- opencode-worktree: https://github.com/kdcokenny/opencode-worktree
- ocx: https://github.com/kdcokenny/ocx
**Stack:**
- Next.js 16: https://nextjs.org/blog/next-16
- GSAP: https://gsap.com/docs/v3/
- GSAP React: https://gsap.com/resources/React/
- Lenis: https://github.com/darkroomengineering/lenis
---
## Backup-onderwerpen (als tijd over)
1. **Custom sub-agents** in `~/.config/opencode/`
2. **MCP servers** — context7 voor up-to-date library docs
3. **opencode-workspace plugin** (uitgebreidere variant)
4. **Cursor live laten zien** — vergelijken
5. **Ollama setup** voor lokale models (privacy)