From c9a81ec88b11301236464442c63855bd1c704600 Mon Sep 17 00:00:00 2001 From: rndm_x Date: Tue, 14 Jul 2026 23:25:58 +0700 Subject: [PATCH 1/2] Update README.md --- README.md | 235 +++++++++++++++++++++++++++--------------------------- 1 file changed, 117 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index ba1f40d..9210467 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,77 @@ -# QuantumByte +

+ QuantumByte +

-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) -[![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/zFD35kwHmU) +

Vibe coding is just the beginning.

-> **The first open-source Convergence App Builder.** +

+ The open-source Convergence App Builder.
+ Generate a working app from intent, then verify every agent turn against its business requirements. +

-Generate working service-automation apps from intent, then continuously verify what the AI built against the app's business requirements. +

+ Apache 2.0 license + Join the founding group on Discord + Public alpha +

-**The model generates. The harness verifies. Humans decide when it is ready to ship.** +

+ Quickstart · + Why convergence · + The harness · + Contribute +

-## Why QuantumByte exists +> **The model generates. The harness verifies. Humans decide when it is ready.** -AI can produce software that looks finished long before it is actually ready. +QuantumByte is early, working, and intentionally being built in public. We are looking for founding contributors who believe software should be shaped by the people who understand the problem, not only by the people who can code. -The interface may render. The happy path may work. The demo may impress. Yet important requirements can still be missing, misunderstood, or silently broken. We call this **false convergence**. +**[Join the founding group on Discord](https://discord.gg/zFD35kwHmU)** -QuantumByte approaches AI-assisted software development as a continuing loop: +## Why convergence -```text -Intent -> Build -> Inspect -> Verify -> Repair -> Decide -``` - -It does not treat generated code as the final answer. After every agent turn, QuantumByte's built-in requirements harness checks the current app and returns structured verdicts with evidence. +Vibe coding made software creation accessible. That is the breakthrough. -**Vibe coding ends at the demo. Convergence starts with evidence.** - -## What ships today +But an app can look finished long before it is ready for real operations. The interface renders. The happy path works. The demo impresses. Important requirements can still be missing, misunderstood, or silently broken. -QuantumByte is a working, open-source app builder engine with an integrated business-requirements harness. +We call this **false convergence**. -### App generation +Generation gets you to an app that builds. Convergence asks what comes next: -- Capture the product intent through a conversational workspace. -- Generate and update a working application in a dedicated project repository. -- Keep every completed agent turn in a buildable state. -- Preview the app live with health checks and device frames. -- Coordinate multiple workers with project-to-worker affinity and turn recovery. +- Does the app still match the original intent? +- Are its critical business requirements satisfied? +- What evidence supports each verdict? +- What must be repaired before humans trust it? -### Continuous requirements verification - -- Derive business requirements from the product overview. -- Let users add or lock requirements that must remain authoritative. -- Audit every requirement independently using a read-only verifier. -- Return structured `SUCCESS` or `FAIL` verdicts with supporting evidence. -- Record inconclusive runs separately instead of turning uncertainty into a false failure. -- Re-check only requirements affected by relevant code changes. -- Run verification in the background without blocking the next conversation. -- Show live requirement status in the product workspace. - -## How it works +QuantumByte turns app generation into a continuing loop: ```text -User intent - | - v -Main agent -> product overview -> engineer agent -> working app - | - v - requirements harness - | - +--------------------+--------------------+ - | | | - verdict evidence watched files - | | | - +--------------------+--------------------+ - | - v - repair or ship decision +Intent -> Build -> Verify -> Evidence -> Repair or Ready ``` -The builder and verifier are deliberately separated. The builder can edit the project. The harness is read-only and evaluates one business requirement at a time, without inheriting the builder's conversational context. - -## Convergence Programming - -QuantumByte is an early executable system inspired by **Convergence Programming**, a research framework for AI-assisted programming and agents. - -Traditional software generation is often framed as: - -```text -specification -> program -``` - -Convergence Programming studies the larger trajectory: - -```text -lossy intent - -> generated behavior - -> observation - -> evidence - -> repair - -> readiness decision - -> action or block -``` - -The central research problem is false convergence: a system appears ready under visible review while important operational constraints remain undiscovered or unsatisfied. - -The current open-source harness implements an initial part of that agenda: continuous verification of generated software against explicit business requirements. It does not yet claim full world-grounded verification, complete production readiness, or the proposed ConvergenceBench evaluation framework. - -## Who this is for - -### Programmers - -Study, run, modify, and extend a real AI app-building system. Build from intent, verify against requirements, and inspect the evidence behind every verdict. - -### Researchers +The current open-source release begins with explicit business requirements. After every agent turn, a separate read-only harness checks the app requirement by requirement and returns structured verdicts with evidence. -Use QuantumByte as an evolving reference implementation for studying false convergence, requirements preservation, verifier-centric agents, evidence collection, and readiness decisions in AI-generated software. - -### Operators and internal builders +## What ships today -Turn a real workflow into an application while keeping the business requirements visible and continuously checked throughout the build. +### App builder -## Architecture +- Conversational intent capture and product overview +- Agent-generated applications in dedicated project repositories +- Build recovery after every completed agent turn +- Live app previews with health checks and device frames +- Worker coordination with project affinity and turn recovery -| Component | Role | Current stack | -| ------------------- | ---------------------------------------------------------------------------------- | --------------------------- | -| `apps/web` | Product workspace, chat, live preview, requirements UI | Next.js, TypeScript, Prisma | -| `apps/orchestrator` | Project assignment, worker coordination, recovery | Python, PostgreSQL | -| `apps/worker` | Agent execution, workspace management, build loop, verification harness | Python, Claude Agent SDK | -| PostgreSQL | Shared source of truth for projects, messages, workers, requirements, and verdicts | PostgreSQL | -| Redis | Per-project harness locking | Redis | +### Requirements harness -The current worker uses the Claude Agent SDK. A provider-neutral agent boundary and additional model providers are on the roadmap. +- Requirements derived from the product overview +- User-locked requirements that remain authoritative +- Independent, read-only audits for every requirement +- Structured `SUCCESS` or `FAIL` verdicts with evidence +- `INCONCLUSIVE` recorded separately from genuine failure +- Diff-scoped re-verification when relevant files change +- Non-blocking background runs with live verdicts in the UI -See [ARCHITECTURE.md](ARCHITECTURE.md) for the system overview and [docs/running.md](docs/running.md) for the complete local setup. - -## Getting started +## Quickstart ### Prerequisites @@ -147,21 +93,72 @@ make migrate make dev ``` -The web app runs at [http://localhost:3000](http://localhost:3000). Run `make help` to see the available development commands. +Open [http://localhost:3000](http://localhost:3000). Run `make help` to see all development commands. For environment variables, service topology, and troubleshooting, read [docs/running.md](docs/running.md). +## How the harness works + +```text +User intent + | + v +Product overview -> Builder agent -> Working app + | + v + Read-only harness + | + +------------------+------------------+ + | | | + Verdict Evidence Watched files + | | | + +------------------+------------------+ + | + v + Repair or ready +``` + +The builder and verifier are deliberately separated. The builder can edit the project. The harness evaluates one business requirement at a time without inheriting the builder's conversation, and it cannot modify the repository it is auditing. + +## Architecture + +- **`apps/web`**: workspace, chat, live preview, and requirements UI using Next.js, TypeScript, and Prisma +- **`apps/orchestrator`**: project assignment, worker coordination, and recovery using Python and PostgreSQL +- **`apps/worker`**: agent execution, build loop, workspace management, and requirements harness using Python and the Claude Agent SDK +- **PostgreSQL**: source of truth for projects, messages, workers, requirements, and verdicts +- **Redis**: per-project harness locking + +The current worker uses the Claude Agent SDK. Provider-neutral agent boundaries and additional model providers are on the roadmap. + +See [ARCHITECTURE.md](ARCHITECTURE.md) for the system overview. + +## Convergence Programming + +QuantumByte is an early executable system inspired by **Convergence Programming**, a research framework for AI-assisted programming and agents. + +Traditional software generation is often framed as `specification -> program`. Convergence Programming studies the larger trajectory: + +```text +lossy intent + -> generated behavior + -> observation + -> evidence + -> repair + -> readiness decision + -> action or block +``` + +The current harness implements one part of that agenda: continuous verification of generated software against explicit business requirements. It does not yet claim full world-grounded verification, complete production readiness, or the proposed ConvergenceBench evaluation framework. + ## Roadmap - [x] Intent-to-app generation -- [x] Live application preview and health checks +- [x] Live previews and health checks - [x] Continuous business-requirements harness -- [x] Structured per-requirement verdicts and evidence +- [x] Per-requirement verdicts and evidence - [ ] One-command self-hosting - [ ] Model and agent provider adapters -- [ ] Concept editor -- [ ] Live code editor -- [ ] Visual blueprint editor +- [ ] Concept, code, and blueprint editors - [ ] World-grounded evidence and readiness gates - [ ] ConvergenceBench reference tasks and evaluation tooling @@ -169,20 +166,22 @@ See [docs/roadmap.md](docs/roadmap.md) for milestone details. ## Why open source -The AI app-generation layer is commoditizing. Generating more code is not the durable problem. +The AI app-generation layer is commoditizing. We would rather help it happen than pretend otherwise. -The harder problem is keeping human intent, AI interpretation, generated behavior, and operational requirements aligned as the system changes. +Generating more code is not the durable problem. The harder problem is keeping human intent, AI interpretation, generated behavior, and operational requirements aligned as the system changes. -We are open-sourcing the engine so programmers and researchers can inspect the harness, challenge its assumptions, reproduce its behavior, and help build better ways to determine when AI-generated software is actually ready. +We are opening the engine so programmers and researchers can inspect the harness, challenge its assumptions, reproduce its behavior, and help build better ways to decide when AI-generated software is actually ready. ## Contributing -Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a contribution. All participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). +The first contributor group is intentionally small. We are looking for engineers with taste, first-principles thinkers who still ship, and researchers interested in requirements, verification, agents, and human-AI collaboration. + +1. **[Join the Discord](https://discord.gg/zFD35kwHmU)** and introduce yourself. +2. Read [CONTRIBUTING.md](CONTRIBUTING.md). +3. Review [docs/roadmap.md](docs/roadmap.md) and propose where you can help. -- Join the [QuantumByte Discord](https://discord.gg/zFD35kwHmU) -- Follow or DM [@kevin.pantasdo](https://www.threads.com/@kevin.pantasdo) -- Report security issues according to [SECURITY.md](SECURITY.md) +All participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). Report security issues according to [SECURITY.md](SECURITY.md). ## License -QuantumByte is licensed under [Apache License 2.0](LICENSE). +QuantumByte is licensed under the [Apache License 2.0](LICENSE). From 3a423e8eedf6b75c8e0c5fc7a03aa267b171c1a4 Mon Sep 17 00:00:00 2001 From: RealtaNua Date: Tue, 14 Jul 2026 23:29:10 +0700 Subject: [PATCH 2/2] docs: fix quickstart prerequisites and list minio Prerequisites now match docs/running.md: Docker + Docker Compose provide Postgres, Redis, and minio via compose, so they are no longer listed as host installs. Pin Node.js 20+ and Python 3.11+, and add minio to the architecture list. Co-Authored-By: Claude Fable 5 --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9210467..8309309 100644 --- a/README.md +++ b/README.md @@ -75,10 +75,9 @@ The current open-source release begins with explicit business requirements. Afte ### Prerequisites -- Node.js and npm -- Python 3 -- PostgreSQL -- Redis +- Docker and Docker Compose (Postgres, Redis, and minio run in containers) +- Node.js 20+ and npm +- Python 3.11+ - An Anthropic API key for the current worker implementation ### Run locally @@ -127,6 +126,7 @@ The builder and verifier are deliberately separated. The builder can edit the pr - **`apps/worker`**: agent execution, build loop, workspace management, and requirements harness using Python and the Claude Agent SDK - **PostgreSQL**: source of truth for projects, messages, workers, requirements, and verdicts - **Redis**: per-project harness locking +- **minio**: S3-compatible store for agent-generated assets The current worker uses the Claude Agent SDK. Provider-neutral agent boundaries and additional model providers are on the roadmap.