event-junkie

Imported from enorm-labs/event-junkie (AGENTS.md). Install upstream with npx skills add enorm-labs/event-junkie. Copyright stays with the author.

AGENTS.md

The conventions every change in this repository is held to. Written for AI agents, but it is simply this project's conventions written down.

The short version

Before you write anything: read the section below that covers what you are touching. This project has strong opinions; the ones that apply to everything are here, and the rest are one link away.

./gradlew clean build                    # compile, test, ktlint, detekt, coverage — the backend gate
./gradlew ktlintFormat                   # auto-fix formatting before fixing anything by hand
scripts/format-markdown.sh               # any .md change; the commit hook runs it anyway
cd events-frontend && npm run type-check && npm run lint && npm run test:unit

Skip the Gradle build for Markdown-only or frontend-only changes. /verify runs the full pre-PR sequence, including the infra and chart gates.

The rest is path-scoped and loads itself. The detail that only matters for one kind of file lives in .github/instructions/, one file per topic, each declaring the paths it applies to. Claude Code reads them through .claude/rules/ and GitHub Copilot reads them directly; both pull a file into context when you touch a file it matches. An agent that reads only this file should follow the links.

Sibling files, none of them optional in their own subtree: infra/AGENTS.md opens with the OpenTofu commands that must never be run · deploy/AGENTS.md with the difference between rendering the chart and installing it · events-frontend/AGENTS.md covers the SPA. A subtree's AGENTS.md loads when an agent reads a file under it, so guidance that only matters to one module goes next to the module.

There is no CLAUDE.md here, on purpose. Claude Code 2.1.277 and later reads AGENTS.md as the project instructions when no CLAUDE.md exists. Do not commit a CLAUDE.md or a CLAUDE.local.md: either one stops Claude Code reading AGENTS.md unless Project instructions in /config is claude-md-and-agents-md. .gitignore covers both names, so a session that cannot read AGENTS.md directly (Bedrock, Vertex, disableAllHooks) can keep a local CLAUDE.md holding just @AGENTS.md.

Agent Instructions

• An ambiguous request gets one clarifying question first. When a request can be read in more than one way, and the readings lead to different work, ask one clarifying question before doing anything. Ask the question whose answer decides the most. A request that the code, the docs or a conventional default already settles is not ambiguous.
• Git without a pager: git --no-pager <command> or GIT_PAGER=cat, on every command that may page (log, diff, show, branch).
• ktlint auto-format first: on a ktlint finding run ./gradlew ktlintFormat; edit by hand only what it cannot fix.
• Reformatting is intentional — keep it. Files are reformatted on purpose (IDE reformat-on-save, ktlintFormat, npm run format). Never revert, re-fetch or "restore" a file because its whitespace, wrapping or attribute order changed, and never reformat back. Review the content with git --no-pager diff -w; whitespace-only churn needs no report. This includes the scraper HTML fixtures under events-importer/src/test/resources/scraper/: Jsoup ignores indentation, so a reformatted snapshot is still valid and never on its own a reason to re-capture. The one caveat: whitespace between inline elements changes the text Jsoup returns (<b>a</b><b>b</b> is ab; with a newline, a b). If a reformat fails a scraper test, that is a finding — raise it with the user; do not revert the file or loosen the assertion.
• Build verification: ./gradlew clean build after a backend change. Skip it when only .md or events-frontend/ files changed; a Markdown change still runs scripts/format-markdown.sh (markdown.instructions.md).
• Write a plan to temp/ (gitignored), as Markdown, named temp/<issue>-<slug>.md or temp/<topic>.md. The same for an audit or a draft anyone will read. A plan in the tree becomes documentation nobody updates; a plan only in the terminal is gone at the next compaction. Format it by name — scripts/format-markdown.sh temp/<file>.md — because nothing else reaches temp/, and a plan pasted unformatted into an issue is the usual tell. Delete it when the work lands.
• No unsolicited git commits, pushes or rebases. Only when the user asks.
• Amend by default on a feature branch, and land one commit. Once the branch carries a commit of yours, the next change amends it; push with git push --force-with-lease, never bare --force. main allows only Rebase and merge, so every branch commit lands on main as written. A branch that ends up with several commits is squashed before merging — /squash-commit-message writes the message. Amending changes the diff, so rewrite the message, the PR title and the PR body with it. Keep commits separate when the user asks, or when a reviewer has already commented on one.
• Documentation describes the current state. Replace, never append. Present tense; rewrite the passage, no "Update:" notes, no dated banners, no new section beside the old one — two passages for successive states is a defect. Delete completed phases and settled decisions; git and the issue hold them. Reasoning goes below the instructions, in a final ## Background and history, or into an ADR, or nowhere. Every document over ~150 lines opens with ## The short version — commands and the two or three rules that catch most changes, no prose. A status banner stays only while it warns of something currently untrue and goes the moment that stops, as LEGAL.md's "not signed off" did. A closed item on a list of open questions is deleted, not annotated. An issue or ADR reference is a pointer, not a summary: see #540, and stop.
• Documentation under docs/ is written in Simplified Technical English. One idea per sentence, 25 words at most, active voice, no semicolons; the whole rule and the asd-ste100 skill are in documentation.instructions.md. Keep every hedge at its original strength — an STE rewrite goes wrong by shortening may have failed into failed (#733).
• A red release.yml on main blocks every release, and the cause is usually not the change that landed — the image scan gates on base-image findings. Look at the latest run before cutting; cut-release.yml refuses a red one. RELEASING.md § Publishing is blocked.
• Logging is part of the change. Before calling a backend change done, ask what someone on the cluster with one sourceslug or one requestid would need to see: a caught-and-continued path gets a WARN with the exception as the argument, a call out of the process gets its outcome, a scheduled pass gets start, result and failure. logging.instructions.md has the levels and the three places a field name lives. A change to what is logged is also a privacy change — see Privacy & GDPR.
• Correct the docs in the same change that makes them wrong. The document to fix is the one a reader would reach for, which is usually not the one you were editing.
• ADR numbers are claimed by writing the ADR, never by planning one. A "needs ADR-0NN" reservation is not honoured: the next ADR written takes that number and the reference silently points elsewhere — it happened twice. Refer to a future ADR by title only and take the next free number from docs/adr/ at the moment you create the file.
• gh is a prerequisite (brew install gh, gh auth login). How to drive it is a vendored skill, .claude/skills/gh/; what it cannot know about this repository is in Automating GitHub with gh.
• Library docs: ask context7 first, and read the release notes on a bump. The pinned versions (Tailwind 4, Vue Router 5, TypeScript 6, Spring Boot 4) postdate most of what a model remembers — a v2-era Tailwind answer writes tailwind.config.js into a project that has none. docs/LINKS.md § 10 pairs every framework with its release notes.

Privacy & GDPR — re-check when infrastructure or features change

The privacy notice (/legal/privacy) and the imprint describe what this system actually does, in two documents each — PrivacyView.en.vue and PrivacyView.de.vue under events-frontend/src/views/legal/, German authoritative — and they stay correct only while reality matches. The changes that break them do not look like privacy work. If your change is in a category below, say so in the PR description and update docs/LEGAL.md §7 plus the privacy page in the same PR.

Infrastructure and operations

• A new or changed hosting, CDN, WAF, DNS, mail, backup or object-storage provider — each is a processor that must be named, needs an Art. 28 DPA, and a transfer mechanism outside the EU/EEA. ADR-012 leaves one processor, Hetzner. INFRASTRUCTURE_IS_PROPOSED stays true until §5 of both notices has been checked against what runs (docs/LEGAL.md §14).
• Log content, log retention or IP handling — the notice states a retention period; it must be the real one.
• Monitoring, error tracking, uptime checks, APM or a metrics backend that receives request or user data.
• A staging or preview environment reachable from the internet. The build's robots.txt allows every crawler but the AI training ones, and its sitemap.xml names production, so override both per environment.

Features

• Anything stored on the visitor's device — cookie, localStorage, sessionStorage, IndexedDB, Cache API. § 25 TDDDG covers storage on terminal equipment. Today every stored item is strictly necessary, so no consent banner is required; the first non-essential item makes one mandatory and is a product decision. Escalate rather than implement.
• Any third-party resource loaded by the browser — font, script, iframe, map, embed, hotlinked image. Each transmits the visitor's IP. Fonts are self-hosted (@fontsource-variable/geist) for this reason.
• Any outbound call from the frontend to a domain we do not operate. LEGAL.md §4.1 says why the footer's version does not come from the GitHub API.
• Accounts, login, sessions, newsletter, contact form, comments, favourites, notifications — each needs its own legal basis, retention and deletion route.
• New personal data in the domain model. Artist names are already personal data (LEGAL.md §7.3). Contact details, social handles, photographs of identifiable people or user content extend that materially — and LEGAL.md §7.3a lists the categories the Hetzner AVV covers; a category not on that list is outside the agreement. Update §7.3a and re-check the AVV in the same change.
• Analytics of any kind, self-hosted and cookieless included — still processing, still needs a basis and a notice entry.

Commercial changes — ads, affiliate links, sponsorships, donations, paid features — also change the § 5 DDG imprint analysis.

When in doubt, flag it in the PR. Raising it costs a sentence; missing it is a legal defect on a public site.

Project Overview

Event Junkie discovers music events in Berlin. A Gradle multi-project build (root settings.gradle.kts) plus a standalone frontend:

• events-core — shared domain model, no Boot app; java-library + java-test-fixtures (src/testFixtures/); api() scope on spring-modulith-starter-core. Domain classes by feature: artist/, genretag/, promoter/, venue/. The event path has none, and event/ holds the enums and the money scale (ADR-003).
• events-bff — the public read API (Spring Boot 4 + WebFlux + R2DBC), port 8080.
• events-importer — imports events from venue sites (Boot 4 + WebFlux + R2DBC + Flyway), port 8081. Owns every migration under src/main/resources/db/migration/.
• detekt-rules — this repository's own detekt rules, on every module's detektPlugins classpath, configured under the event-junkie key in detekt.yml. Ships nothing, so it is out of Kover, the licence report and the OWASP scan; each exclusion sits next to its reason in build.gradle.kts.
• events-frontend — Vue 3 SPA (Vite 8, TypeScript 6, Vue Router), managed by npm, not Gradle. Node >=24.15.0: a patch floor forced by jsdom 30; events-frontend/AGENTS.md records both moves.
• events-admin — the operator's Vue app (Vite, shadcn-vue), npm-managed. Local only: never built into an image or deployed (ADR-045). Its dev server proxies /api/admin to the forward scripts/ej.sh up <env> opens; npm run dev -- --mode staging. build-admin.yml type-checks, lints and tests it.

Build & Dev Commands

./gradlew clean build          # all modules: tests, ktlint, detekt, Kover
./gradlew :events-bff:bootRun  # Postgres starts via compose.yaml; :events-importer:bootRun likewise
./gradlew ktlintFormat         # then ktlintCheck
./gradlew detekt detektMain detektTest   # CI runs all three; only the first is syntax-only
./gradlew koverLog             # coverage per module
./gradlew dependencyCheckAggregate --no-configuration-cache   # OWASP; the plugin forbids the cache, so skip the futile attempt
scripts/dev-env.sh             # the local stack; no arguments prints every command

Java comes from SDKMAN (.sdkmanrc, sdk env); target Java 25. Infra, chart, k3d, container images, k6 and the frontend commands are in docs/DEVELOPMENT.md; the safe-versus-never lists are in infra/AGENTS.md and deploy/AGENTS.md. scripts/k3d-rehearsal.sh is the only thing here that talks to a Kubernetes cluster, and it passes --context k3d-event-junkie on every call.

The local stack, as an agent meets it (/importer-smoke and /next-importer drive it):

• scripts/dev-env.sh up starts the importer with app.scheduling.enabled=false, so a smoke test scrapes only the source under test; --scheduling leaves it on. Neither bootRun nor the script hot-reloads Kotlin — down then up after a code change, or the test runs the previous build. Vite does hot-reload. Runtime artefacts land in build/dev-env/ (gitignored). The frontend alone renders but every request 502s; up all for the whole stack.
• Redirect a detached launch (> file 2>&1 < /dev/null): bootRun and vite inherit the tool's stdout pipe and keep the call hanging after the script exits.
• Never run Gradle while an import is in flight. Both Boot modules carry spring-boot-devtools, which restarts the service on any task that writes classes — compileKotlin, a single --tests run — and kills every import mid-flight. Those sources stay RUNNING forever, because the staleness guard only runs under the scheduler. The tell is restartedMain beside Started EventsImporterApplicationKt in 1.0 seconds (process running for 117.3). Recovery: scripts/dev-env.sh psql "UPDATE events.event_source SET status='IDLE', retry_count=0, version=version+1 WHERE status='RUNNING'", then re-trigger. On a long job compile first, restart once, then import.
• A parser fix at a one-page venue whose page has not changed is a 304 forever. The cached ETag / Last-Modified skip the import on schedule and manual trigger alike. Do not clear the columns; POST /api/admin/event-sources/<slug>/import?force=true (#1159) fetches unconditionally and stores fresh validators.
• Re-keying a live source collides with its own today-dated rows. A new sourceId shape stales every old row, but removeStaleEvents spares today, so a today-dated row keeps its slug while its replacement claims the same one. Re-key on a day the venue is dark, or clear that source's rows first — and check which before importing.
• Do not truncate <service>.log while the service runs. The process keeps its offset, so later writes land behind NUL padding, grep calls the file binary and grep -c prints nothing — which reads as a clean result. Restart to get a clean log; grep -a reads a truncated one. A zero count from a log you truncated is not evidence.
• In a worktree (docs/WORKTREES.md): files and Gradle output are isolated, the runtime is not. export COMPOSE_PROJECT_NAME=event-junkie before any bootRun or dev-env.sh up, or the worktree starts a second empty Postgres and diff-snapshot reports every source as GONE. Ports 8081 / 8080 / 5173 are fixed: down in the other checkout first, and the worktree that started the JVM is the code under test. Never import while another worktree is importing — snapshot counts the whole shared database. Every importer PR conflicts in docs/EVENT_DATA_SOURCES.md (recount after rebasing), http/importer/dev-seed.http (a "keep both" resolution fuses two blocks — rebuild by hand) and the EventSource.kt enum. Rebase onto main; never merge it in.

Project skills

Slash commands under .claude/skills/, each a one-line @ pointer into .github/prompts/:

• /afk [<issue>…] — while the user is away: the named issues, or every afk-ok one, to draft PRs, with decisions in each PR and a handover in temp/
• /code-review — review the current diff
• /codebase-audit — whole-repo review: size, duplication, conventions, simplification
• /commit-message — a commit message from the staged changes
• /compact-comments — classify each comment block DELETE → RENAME → EXTRACT → RELOCATE → KEEP, apply in that order, measure the drop
• /daily-check — the start of the day: failed runs, bot issues, unread reports, security, logs; merges the ready bot PRs, drafts the rest
• /data-quality-audit — read-only audit of the whole events database
• /importer-smoke — seed, import, inspect the rows and check for regressions, for one importer
• /log-check — both clusters' logs, Kubernetes events and alerts for the last day, sorted into noise, known, explained and new; drafts issues, files none
• /k3d-rehearsal — the chart and all three images on a local k3d cluster, end to end, then torn down
• /improve-test-coverage — find and fill coverage gaps
• /milestone-plan — a milestone from a list of open issues to an ordered plan
• /new-issue — file an issue: duplicate check, the right form, labels, milestone, board fields
• /next-importer — one venue from 🔨 Ready in docs/EVENT_DATA_SOURCES.md to an open PR; repeat, or run under /loop
• /next-issue — what to work on next, and why
• /open-pr — branch, commit (Conventional Commits), push, open a PR
• /owasp-top-10 — OWASP Top 10:2025 against the deployed tree, one line per category; agent-owasp.yml runs it weekly
• /plausibility-check — the next days' events on the public site against the venues' pages; agent-plausibility.yml runs it nightly
• /post-release — after a deployment, the checks, forced imports and scripts merged pull requests left under ## After deploy (label after-deploy)
• /refactor — change the shape of the code, not what it does; the acting counterpart to /codebase-audit
• /release-highlights — the visitor-facing summary that opens a release's notes; cut-release.yml runs it before every cut
• /start-issue <n> — claim an issue, move the board, cut the branch, read its dependencies, plan
• /scaffold-importer — a new venue importer end to end
• /security-report — read-only: Dependency-Check findings and Dependabot alerts, reconciled and triaged
• /security-triage — work the Security tab to zero: fix, file or dismiss; the mutating counterpart to /security-report
• /squash-commit-message — a squash commit message for the current branch
• /ui-check — every public page at four widths, both locales and both themes, probed against the design rules; drafts issues, files none
• /update-dependencies — bump backend and frontend dependencies safely
• /update-docs — find documentation that stopped being true; correct, delete or leave it, with the proving check
• /verify — the full pre-PR sequence; the prompt is the check list, and it runs every gate the diff touches
• /wrap-up — before a session closes: what the conversation promised, what still runs, what git and GitHub hold; proposes, changes nothing
• /write-adr — the record of a decision already made; claims the next ADR number by writing the file scripts/skill-parity.sh fails when this list, .claude/skills/ and .claude/commands/ disagree; it greps for the bullet shape above.

Two directory skills are not slash commands, vendored so every contributor has them and invoked by name: asd-ste100 (Simplified Technical English; /compact-comments and /update-docs call it) and gh (from cli/cli). Each has a VENDORED.md with its upstream commit and refresh command; edit nothing else inside them — the next update reverts it. .github/skills/ holds one symlink per directory skill, Copilot's documented path; skill-parity.sh asserts each is a symlink onto the right target.

Automating GitHub with gh

The mechanics — --json/--jq, silent list limits, -R, search versus list, when to drop to gh api — are the vendored gh skill. What follows is what upstream cannot know: this repository's board, rulesets and bulk edits. The workflow-file half — fork PRs, required checks, what CI may write to — is in ci-cd.instructions.md.

• A pull request's mergeable_state goes stale after a ruleset change, and polling never refreshes it. GitHub recomputes mergeability lazily, on a PR event or a UI view; gh api …/pulls/<n> reads the cache. Do not diagnose a stale blocked as a live rule — compare the required contexts against what reported:

  gh api repos/OWNER/REPO/rulesets/<id> --jq '.rules[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context' | sort > /tmp/req
  gh api repos/OWNER/REPO/commits/<sha>/check-runs?per_page=100 --jq '.check_runs[] | select(.conclusion=="success") | .name' | sort -u > /tmp/got
  comm -23 /tmp/req /tmp/got     # empty means nothing required is missing

  Empty: open the PR in a browser or attempt the merge instead of hunting for a rule that is gone.

• Pace bulk mutations: sleep 0.45 between calls. The secondary rate limit bites long before the hourly one.

• No --label on gh pr create. label-pr.yml sets a PR's labels from the title, an added *Importer.kt, the !/footer and an unticked ## After deploy step, and removes a managed label set by hand. On a PR importer means one thing, a new venue, and release.yml files it under "New Event Sources" (#1546).

• Screenshots go on the pull request through gh, not by hand. gh 2.102 and later upload an image with --attach on pr create, pr edit and pr comment, and rewrite a ![alt](./file.png) in the body to the uploaded URL. A change a visitor can see carries before and after, which scripts/pr-screenshots.sh takes. Outside a checkout, pass -R enorm-labs/event-junkie. The flags and limits are in the gh skill § Attaching images and videos.

• gh issue create takes --label; gh issue edit takes --add-label / --remove-label, and an update must reconcile both directions.

• Project view grouping and sorting cannot be set through the API (ProjectV2ViewConfigurationInput exposes only visibleFieldIds). Manual UI step.

• gitleaks fires on key: with a high-entropy value. Prefer slug, id or name for identifier fields; widening .gitleaks.toml costs coverage.

• A cautious first run pays for itself: --limit 5, inspect, then continue.

The Backlog — GitHub Issues

The backlog is GitHub Issues, not a file. Read a generated snapshot; write through gh:

scripts/generate-backlog-snapshot.sh                # renders every open issue into build/BACKLOG.md — refresh before relying on it
grep -i 'heimathafen' build/BACKLOG.md              # is this already tracked?
gh issue list --label importer --state open         # live state
gh issue view 313                                   # the full body, including its Links footer

The snapshot lives in build/ (gitignored) because the main ruleset lets nothing land without a PR and refuses the Actions bot as a bypass actor; its header carries the timestamp.

Filing. /new-issue checks for a duplicate and picks the form: 🛠 Task, ✨ Feature, 🔍 Importer / data defect, ⚖️ Decision, 🧭 Epic. The importer-defect form asks whether the fix needs a --full re-seed — usually the difference between an hour and a day.

Labels and fields. Intrinsic properties are labels — area:*, size:*, importer, documentation. Planning state is Status and Priority on the project board. Issue type is a GitHub issue type, not a label. Three labels say why something cannot start: blocked, needs-decision, needs-deployment — the last is work that cannot exist yet, not neglect. after-deploy is on a merged pull request: its ## After deploy steps wait for a release, and /post-release runs them, so no session waits open for one.

Milestones. v0.2 — Deployable → v0.3 — Launch-ready → v1.0 — Go-live lead to launch; Phase 2/3/4 are post-launch buckets. No milestone means unscheduled. Reasoning in docs/VISION_ROADMAP_IDEAS.md.

Closing. Closes #NNN in the PR body, one line per issue, Closes not Fixes. A commit message would work too under rebase-merge, but the body survives amending and is one line to fix. Give the PR the issue's milestone; every closed PR here carries one. A negated keyword still closes: GitHub reads close #N without the words around it, so "does not close #877" closed #877 when #1805 merged. A PR that leaves an issue open says Part of #N.

Key Files

The rows here carry a rule or a trap; a plain "where does X live" is one grep away and is not listed. ADRs are under docs/adr/, named for what they decide; ADR-032 is the one to know unprompted — no file carries the version, it is computed from the tags and the commits.