justinzeus/discovery-by-llm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
discovery-by-llm/docs/workflow.md
Justin Visser fa356ba5c5
Some checks are pending
ci / backend (push) Waiting to run
Details
ci / frontend (push) Waiting to run
Details
docs: write the README and map the build workflow
2026-08-11 09:47:22 +02:00

2.9 KiB
Raw Blame History

How I work

A short map of the setup behind this repo, because the process says as much as the code.

The environment

Everything was built over SSH from a laptop (I was house-sitting for most of it) against my home server, a Debian box that runs my self-hosted infrastructure. The server carries the whole toolchain: uv and node for fast local feedback, Docker for the deliverable, and the deployment stack below. No cloud dev environment involved.

Source control and CI

  • Origin is my self-hosted Forgejo instance, with a push mirror to GitHub; the repo you are reading is the mirror and shows the same history and the same green CI.
  • CI runs on every push: ruff, mypy and pytest for the backend; typecheck, lint, build and vitest for the frontend. It has been green since the first commit.

Deployment

  • The hosted instance is a single container on the same server, built from this repo's Dockerfile and managed with Komodo (a self-hosted container control plane). It is rebuilt from main as the build advances.
  • Routing and TLS come from caddy-docker-proxy: the container carries its route as labels, Caddy picks them up. The streaming endpoint needed one deliberate setting there (no response buffering), verified through the public URL.
  • HTTP basic auth sits at the edge because the instance runs against my personal Spotify account.

AI-assisted building

I work with coding agents, and this project was built that way end to end:

  • One orchestrating session (Claude Code harness) holds the plan and the state. It briefs implementation agents (codex CLI, Opus 5 subagents) that build scoped tracks in their own git worktrees, in parallel.
  • Contracts come first: the API schemas and the event protocol were frozen before frontend and backend lanes ran in parallel against them.
  • Parallel lanes buy time where it matters. While I was working on the backend, a separate lane generated a ready-to-implement UI (design tokens, component structure, copy) against the frozen event protocol, so frontend implementation started from a settled design instead of a blank page.
  • Everything that lands is reviewed by me, commit by commit, in my editor before it goes in. Voice-carrying text (this file, the README, the logboek) I write or rewrite myself.
  • Verification against the real APIs is deliberate and budgeted: the Spotify development quota is a daily account-level budget, so live test runs are planned, sequential and measured rather than sprayed.
  • Review also runs as a tool: adversarial review passes over the diffs produced findings that became fix batches; the useful findings and the rejected ones are both traceable in the logboek.

The result is that implementation is cheap and parallel, while design, review and verification stay serial and human. The logboek (logboek.md) records that rhythm as it happened, including what was dropped under time pressure.