fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(product): commit Veect product spec bundle under docs/product/

Browse Source 
Sandcastle implementers run in git worktrees that contain only committed
files, so every PRD referencing the spec was unreadable to dispatch
agents while the bundle sat untracked in .proto/. The eight spec
documents are copied verbatim (filenames preserved) from
.proto/veect-product-docs/ and become the canonical source.

The stray veect-product-docs.zip at the repo root was already removed
before this change — that half of the task is a verified no-op.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
This commit is contained in:
Danijel Martinek
2026-07-12 12:58:47 +02:00
parent 99180887f3
commit 4d1d53432e
8 changed files with 1498 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
docs/product/README.md Normal file
View File

@@ -0,0 +1,120 @@
# Veect — Product Documentation Bundle
_Entry point for the development agent. Generated 2026-07-10._
You are about to build **Veect**. This bundle is the complete product, design, and technical specification. Read this README first — it tells you what each document is, **which document wins when two disagree**, the invariants you must never break, and exactly where to start.
---
## 1. What Veect is (read this once)
Veect is a **standalone design application that connects to a code repository** and turns it into a design surface. A product designer connects their team's repo (remote via GitHub/GitLab/git URL, or a local checkout); Veect discovers the repo's **real components and design tokens** and lets the designer compose screens on a canvas using _only_ that system. Every design project is a **git branch in an app-managed worktree**; the designer composes, an AI assistant helps (constrained to the repo's own components), and the result is **checkpointed as real TSX and published as an ordinary pull request** the team can review.
The wedge: v0 / Lovable / Bolt / Figma Make generate _generic, throwaway_ UI. Veect emits the team's **real components** as **real code an engineer will merge** — on-brand and high-craft, not slop.
**Pronounced VEEKT** (rhymes with "piqued"). Design language is a **monochrome "ink instrument"** — the tool is deliberately colorless so the customer's brand is the hero.
### The three invariants — never violate these
1. **One runtime.** Canvas, preview, isolation view, and exported code all render the same node tree through the same renderer. No approximations, no "roughly how it'll look."
2. **0 unregistered elements.** AI output is whitelist-sanitized against the discovered component registry. Anything outside it is **refused, never faked** with generic markup.
3. **Deterministic code.** Same tree → byte-identical code, every time. Export imports the customer's real library; it never inlines cloned components.
---
## 2. How to read these documents (authority hierarchy)
Documents were written across several iterations and **deliberately supersede each other**. When two conflict, the higher-authority doc wins on its domain:
| Domain | Authoritative doc | Notes |
| ----------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **How the system must behave** (architecture, connections, git, adapters, AI, milestones) | **`veect-technical-spec.md`** (rev 1.2.2) | The primary build document. Start here after this README. |
| **Visual & interaction language** (color, type, radius, icons, motion, components) | **`veect-design-spec-current.md`** | Ground truth from the built prototype. **Wins over the design brief's older art-direction section.** |
| **UI/UX still to be built** (repo-connect, publish, environment, editor deltas) | **`veect-ui-gap-spec.md`** | Your UI work order. Everything the prototype doesn't cover yet. |
| **UX intent** (north star, principles, journeys, signature moments, voice, a11y) | **`design-brief-veect.md`** | Authoritative for _intent_; where its §11 art direction conflicts with the design spec, the design spec wins (it says so itself). |
| **Product scope — what & why** (features, out-of-scope, personas, acceptance criteria) | **`design-app-prd.md`** | Distribution details superseded by the tech spec; wedge/personas/JTBD/scope discipline still authoritative. |
| **Strategy & context** (problem, positioning, market, assumptions, decisions log) | **`company-context.md`** | The "why." Read for orientation; not a build doc. |
| **Project status** (what's validated, what's missing, non-code work) | **`founder-os-audit.md`** | Honest state-of-the-company. Read to understand what is NOT yet proven. |
**Recommended reading order for building:**
1. This README
2. `veect-technical-spec.md` (the whole thing — it's the backbone)
3. `veect-design-spec-current.md` (the design language you'll implement in)
4. `veect-ui-gap-spec.md` (what to build, in milestone order)
5. Skim `design-brief-veect.md`, `design-app-prd.md`, `company-context.md` for intent/scope/why
6. `founder-os-audit.md` last (context on what's unproven)
---
## 3. What already exists vs. what you're building
**⚠️ Not in this bundle (request from the founder):** the **interactive prototype** (`Veect.dc.html`), the **landing page** (`Veect Landing.dc.html`), and the **React 18 / TypeScript codebase** (`veect-codebase/`). These are the founder's built artifacts. `veect-design-spec-current.md` is their specification. **The codebase seeds `packages/editor`** — do not rebuild the editor from scratch.
**Already built (inherit, do not redesign):** the entire editor — canvas (React Flow substrate, zustand store), 3-pane panels, activity bar, responsive **multi-view frames** (desktop/tablet/mobile clusters), constrained-AI UX (compose ghosts, scoped edits, refusal protocol, model picker), Polish pass, history with restore cursor, token editor with live ripple, isolation mode, the **bidirectional code grammar** (TSX generates _and_ parses back), and the landing page. See `veect-ui-gap-spec.md` §1.
**What you're building** is the **repo-native layer** the prototype fakes: the desktop shell (Electron, bundled Node), repository connections, worktree/git engine, discovery engine (real component/token scanning), the preview adapters (embedded Vite + managed `next dev`), SQLite persistence, publish flow, and the new UI surfaces (Connect Repository, Checkpoint/Publish, Environment). The prototype's "seams" map 1:1 onto these subsystems — the wiring table is `veect-ui-gap-spec.md` §4.
---
## 4. Locked decisions (do not relitigate)
- **Distribution:** standalone desktop app (default) + Docker image (additional). The npm-in-repo package (Storybook-style) is a **later** distribution — build the core layered so it can be added.
- **Repository connection:** remote-first — GitHub device-flow, any git URL (token/SSH), or local folder.
- **Config:** `veect.config.json` (JSON, app-writable, schema-validated). `veect.preview.tsx` stays a hand-authored code file.
- **AI:** ships in v1. Anthropic; key via app Settings (OS-encrypted) or `ANTHROPIC_API_KEY` env. Haiku default, Sonnet option.
- **Framework support:** any React + TypeScript repo, with **full Next.js** (App Router incl. server components) as a first-class adapter via a managed `next dev`.
- **Persistence:** local SQLite (working state/history) + canonical `design.veect.json` committed on the branch (shareable/reviewable).
- **Name:** Veect · npm `veect` · scope `@veectjs/*`.
Full decision logs live in `veect-technical-spec.md` §18 and `company-context.md`.
---
## 5. Build order (start at M0)
From `veect-technical-spec.md` §17, cross-referenced with the UI priorities in `veect-ui-gap-spec.md` §7:
| Milestone | What | Proves |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **M0** | Walking skeleton — shell boots with **no system Node**; open both fixture repos (Vite + Next) as local folders; one real component renders through **both** adapters; minimal worktree. | The bundled-runtime + dual-adapter foundation (highest technical risk — front-loaded deliberately). |
| **M1** | Discovery & registry — real component/token scan, props/tokens panels, watch/HMR, split lazy registries, perf-500 budgets; JSON config wizard. | The repo _is_ the design system. |
| **M2** | Canvas + doc + persistence — the prototype editor on real data; SQLite + JSON write-through. | Composing on real components, durably. |
| **M3** | Worktrees + codegen + checkpoint (local complete) — commit transaction, parity check, code-owned flip, committer identity, **env manager core**. | Real code an engineer would merge, on a branch. |
| **M4** | **Remote repositories + publish** — device flow, PAT/SSH, clone/install pipeline, trust prompt, publish → PR link, failure playbooks. | The flagship remote flow + design-partner onboarding. |
| **M5** | Next.js depth — server-component subtrees, root-layout/middleware handling, font fidelity, adapter pool/crash recovery. | Real Next.js repos work. |
| **M6** | AI compose — context assembly, constrained generation, ghost propose/accept, refusal, provenance, eval suite. | The differentiator, wired to the real registry. |
| **M7** | Docker + hardening — image, doctor, Windows pass, docs. | Self-host + shippable. |
**Your first concrete actions:** (1) request the prototype codebase from the founder; (2) read `veect-technical-spec.md` end to end; (3) stand up the pnpm monorepo per its §3; (4) build M0 against the two kitchen fixtures defined in its §15.
---
## 6. Known risks & unresolved items the spec flags
These are called out so you don't discover them mid-build:
- **Impeccable craft ruleset is unreconciled.** The Polish/craft layer (F9) cites Impeccable's _philosophy_ — the verbatim `DESIGN.md` rules couldn't be fetched. Treat exact craft thresholds as provisional; the founder can supply the real ruleset.
- **Trust model.** Cloning a repo and running its install scripts + dev server = executing repo code inside the app. This is a stated, mitigated surface (workspace-trust prompt, `--ignore-scripts` opt-in) — implement it, don't skip it. See tech spec §6 + §16.
- **Native-module / Electron ABI, `node` PATH shim, per-worktree installs, credential-helper mechanics, SSH-from-GUI, git-lfs** — all have specific handling in tech spec §3 + §6. These are the "fails on real machines" landmines; follow the spec precisely.
- **Open design questions** (need founder input before the noted milestone): board↔design-doc mapping (before M2); keep the no-repo "Playground" sandbox?; checkpoint granularity; landing-page proof-strip claims are targets stated as facts (validate before public traffic). See `veect-ui-gap-spec.md` §8.
- **Non-code, founder-owned:** name/domain/npm/trademark registration, design-partner recruiting, and Phase-1 validation are tracked in `founder-os-audit.md` — not your build work, but context for why some acceptance criteria reference "design partners."
---
## 7. Document manifest
| File | One line |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `README.md` | This entry point. |
| `veect-technical-spec.md` | **rev 1.2.2** — the authoritative build spec: architecture, distribution, connections, git/worktrees, adapters, AI, persistence, security, milestones, decision log. |
| `veect-design-spec-current.md` | The **built** design language + prototype/codebase spec — the monochrome ink instrument, editor anatomy, node model, AI/Polish/history UX, codegen grammar, landing. **Ground truth for visuals.** |
| `veect-ui-gap-spec.md` | The **work order** for UI not yet built — new surfaces (connect/publish/environment), editor deltas, the seams→subsystems wiring table, per-surface state/error catalog, build order. |
| `design-brief-veect.md` | UX **intent** — north star, opinionated principles, personas, journeys, the 6 signature moments, voice, accessibility, the Craft/Impeccable checklist. |
| `design-app-prd.md` | Product **scope** — the wedge, F1–F10 features with acceptance criteria, the load-bearing out-of-scope list, success metrics, the validation gate. |
| `company-context.md` | **Strategy** — problem, positioning (April Dunford), competitive frame, North Star Metric, riskiest assumptions, the naming decision, all pivots. |
| `founder-os-audit.md` | **Status** — Founder OS phase-by-phase: what's solid (product/tech), what's missing (validation, business model), and the recommended sequence. |
---
_Build the invariants first and never break them; inherit the editor; follow the tech spec precisely on the "real machines" details; implement the design in the ink language. When a document disagrees with another, use the authority table in §2. Good building._