Loopworks turns labeled GitHub issues into durable software-delivery runs. It coordinates planning, red-test writing, implementation, validation, review, and draft-PR preparation while GitHub remains the source of truth for intent and collaboration.
Case study · Architecture · Contributing
Loopworks is pre-1.0 and under active development. The development-loop control plane is implemented; research-loop execution remains fail-closed until its specialized agents are declared. Expect interfaces and configuration to change.
- Admits work through verified GitHub App webhooks, delivery-id idempotency, and durable run leases.
- Persists stages, artifacts, approvals, retries, and operational evidence in Postgres instead of treating GitHub comments or logs as an event store.
- Runs deterministic validation before agent review.
- Requires digest-bound human approval before plan execution and guarded GitHub writes. The write path produces a draft pull request; it never merges one.
- Emits vendor-neutral telemetry through OpenTelemetry with structured Pino logs linked to active trace context.
The application uses Next.js and Bun, Postgres with Drizzle, Auth.js and a GitHub App, Eve agents, Vitest, Playwright, and Storybook.
Install dependencies and start the portal with explicit non-production fixture data and local authentication bypass:
bun install
LOOPWORKS_PORTAL_DATA_MODE=fixtures bun run dev:fixtureOpen http://127.0.0.1:3000. For real GitHub, Postgres, webhook, seed, and
native-test setup, use the
database-backed local quick start.
The generated .env.example is the canonical configuration
inventory.
Run the repository-owned aggregate gate:
bun run validateApp and runtime changes also require:
bun run buildLoopworks work is issue-backed, test-driven, and reviewable. Read the
contribution guide and the nearest AGENTS.md before making
changes.
- Product intent: requirements and personas and test scenarios
- System contracts: architecture, loop manifest, and ADR index
- Local operation: development guide and
.env.example - Hosted operation: Vercel and Neon runbook
- Assurance: observability and MVP security review