Auto Build Log

Auto Build Log is the automation system that powers a developer portfolio site. It runs a six-phase pipeline: Scout discovers new repositories, Detective decides which qualify for tracking, Enricher calls an LLM to draft portfolio copy from repository contents, Review presents drafts for human approval, Shipping opens pull requests against the Astro build log repo, and Live tracks merged entries.

The worker processes jobs from a Postgres queue with deduplication, retry logic, and back-edge transitions between phases. The enricher agent reads README files, package manifests, and commit history, then writes structured JSON describing the project in a builder-to-builder voice. An admin UI surfaces every phase as a table with bulk actions and keyboard shortcuts.

The system handles edge cases like empty repositories (409 handling), malformed LLM outputs (schema validation with in-loop retries), and pipeline reversals (moving builds back to Scout or Draft). A shared logging package wraps Pino with job and request correlation. The entire stack is self-hosted and designed to eliminate manual copy-writing for new projects.

Why

Maintaining a portfolio by hand means either writing the same technical pitch over and over or letting projects disappear into GitHub’s void. Every new repo deserves a coherent explanation of what it does and why it exists, but drafting that explanation from scratch interrupts the momentum of shipping. This pipeline turns repository metadata and commit history into reviewable portfolio copy automatically, so the build log stays current without becoming a second job.

How

The system is structured as a Next.js app for the admin UI and an independent worker process that claims jobs from a Postgres queue. The enricher uses a model resolver that walks provider-and-family preferences, applies minimum capability floors, and calls either OpenAI-compatible or Anthropic APIs through a shared LLM package. Schema validation runs inside the agent loop using Zod; invalid drafts trigger corrective tool results and up to two retries before marking the job permanently failed. The worker records every phase transition as an activity row, and the admin queries those rows to derive build state and enforce one-pending-job-per-build-kind with a partial unique index. GitHub integration is read-only except for the Shipping phase, which opens PRs against a separate Astro repository.