# VibeBox Baseline V1

Date: 2026-05-26
Status: Downstream simplified branch of AirCoding Baseline V1

VibeBox is a highly simplified AirCoding derivative for an ARM Linux appliance. Its goal is to let non-technical users describe a small desktop utility in natural language, then run environment setup, development, testing, review, packaging, and delivery mostly silently in the background, finally handing the user a usable Electron application.

This baseline intentionally cuts most of AirCoding's general-purpose architecture to minimize implementation cost, runtime risk, and support burden.

## 1. Product Goal

VibeBox should behave like an appliance:

```text
User describes desired small tool in natural language
  → VibeBox asks only blocking product questions, if any
  → Runs doctor/setup silently where allowed
  → Generates Electron app from approved template
  → Implements UI and local logic in the background
  → Runs lint/typecheck/test/smoke test
  → Reviews generated code
  → Fixes issues automatically when possible
  → Packages app for ARM Linux
  → Delivers runnable app to user with report
```

Primary experience target: after the user states the requirement, VibeBox should work in the background and only return when a usable tool is ready, unless a truly blocking product or safety decision is required.

Target user: non-programmer / beginner.

Target output: small Electron-based desktop utilities for ARM Linux.

Typical examples:

- simple file renamer
- local note/todo app
- clipboard helper
- small form/data-entry utility
- image batch resizer wrapper
- CSV viewer/editor
- local dashboard around simple APIs
- single-purpose internal workflow helper

Non-goals:

- large software projects
- multi-language deep toolchains
- C++ build/debug loop
- complex distributed agents
- long-running enterprise workflow automation
- arbitrary system administration
- production SaaS/backend deployment

## 2. Relationship to AirCoding

VibeBox reuses AirCoding principles selectively.

Keep:

- Claude Code style execution-layer discipline
- Anthropic canonical message format internally
- conservative file edit/diff/update primitives
- local session persistence
- artifact/evidence records
- doctor/setup environment checks
- TUI/HUD or simple appliance UI status display
- review/test before delivery

Cut or defer:

- Architecture Designer as a separate agent
- complex Scheduler / TaskGraph / worktree parallelism
- C++ toolchain profile
- multi-language toolchain packages
- network/GUI/static-analysis Air plugin family as first-class components
- ExperienceMiner / Curator
- Debug Knowledge Network
- project migration complexity beyond simple schema versioning
- multi-provider complexity beyond one configured provider
- OpenCode-compatible advanced TUI

## 3. Core Design Principle

VibeBox should optimize for appliance reliability over architectural generality.

Key rule:

> One user request should produce one small app project through a linear setup → generate → test → review → package → deliver pipeline, with background silent execution as the default.

The system should not require the user to supervise intermediate development steps. Progress can be visible in status/HUD, but VibeBox should not ask for implementation choices unless the task is blocked.

No parallel write workers in V1.

No complex agent hierarchy in V1.

No automatic architecture replanning loop in V1.

## 4. Agent Model

### 4.1 Single Orchestrator

VibeBox has one main Orchestrator agent.

Responsibilities:

- Understand user's natural language request
- Ask only truly blocking product/safety questions
- Choose an app template
- Produce an internal implementation plan without requiring user approval for implementation details
- Run environment setup through doctor/setup according to appliance permission policy
- Drive Executor and Reviewer steps sequentially in the background
- Present final package and usage instructions

### 4.2 Executor

Executor can be implemented as a mode of Orchestrator or a simple child process.

Responsibilities:

- Scaffold Electron project from template
- Edit files using Claude Code-like execution primitives
- Run npm/pnpm commands
- Run tests and smoke checks
- Produce structured result

### 4.3 Reviewer/Tester

Reviewer/Tester can be a separate pass, not a long-lived agent.

Responsibilities:

- Inspect generated diff
- Check for obvious security issues
- Verify app matches user request
- Verify tests/smoke test passed
- Produce a concise approval or requested-change report

V1 pipeline:

```text
Orchestrator
  → Executor
  → Reviewer/Tester
  → Executor fix pass if needed
  → Package
  → Deliver
```

Maximum retry cycles: 2.

If still failing, show clear failure report and ask user whether to continue.

## 5. Execution-Layer Quality Standard

VibeBox follows AirCoding D-059: execution-layer primitives align with Claude Code for code quality.

Required behaviors:

- read before edit
- small exact edits
- no broad rewrites unless scaffolding from template
- no unrelated refactors
- run verification before declaring success
- collect evidence for build/test/package results
- diagnose root cause on failure, not random retries
- explicitly escalate if the requested app is outside supported scope

This is the most important reuse point from AirCoding.

## 6. Technology Stack

Recommended V1 stack:

```text
Runtime: TypeScript + Bun or Node.js
App target: Electron
Frontend: React + Vite or plain HTML/TS template
Package manager: pnpm or npm
Testing: vitest + Playwright/Electron smoke test
Packaging: electron-builder or electron-forge
Target OS: ARM Linux
```

Default app template:

```text
Electron + Vite + TypeScript
  ├── main process
  ├── preload bridge
  ├── renderer UI
  ├── local storage helper
  ├── test harness
  └── packaging config for ARM Linux
```

Security defaults:

- `contextIsolation: true`
- `nodeIntegration: false`
- explicit preload API
- no remote code execution
- no arbitrary shell command from generated app unless user explicitly requested and approved
- local-first storage by default

## 7. Project Layout

Each generated app is self-contained.

```text
<workspace>/<app-name>/
  ├── package.json
  ├── src/
  │   ├── main/
  │   ├── preload/
  │   └── renderer/
  ├── tests/
  ├── dist/
  ├── release/
  └── .vibebox/
      ├── project.json
      ├── session.db
      ├── artifacts/
      ├── reports/
      └── state.json
```

VibeBox may later converge with AirCoding `.air/shared` + `.air/local`, but V1 uses `.vibebox/` for product clarity and isolation.

## 8. Session and State

V1 uses one SQLite database per generated project:

```text
<app>/.vibebox/session.db
```

Minimum tables:

- `messages`
- `message_drafts`
- `steps`
- `tool_runs`
- `command_runs`
- `artifacts`
- `reports`

No complex TaskGraph tables in V1.

Pipeline steps are linear:

```text
clarify
plan
scaffold
implement
test
review
fix
package
deliver
```

Artifacts:

```text
.vibebox/artifacts/
  ├── command-runs/
  ├── screenshots/
  ├── build-logs/
  ├── test-logs/
  ├── review-reports/
  └── packages/
```

## 9. Tool Set

Minimum built-in tools include frontend design and image generation as first-class VibeBox capabilities, because the target output is a user-facing Electron app and the user may not be able to provide UI/assets manually.

### Filesystem

- list files
- read file
- write file
- edit file with exact replacement
- apply patch
- create project from template

### Shell

- run command with timeout
- capture stdout/stderr artifacts
- enforce output limits

### Electron workflow

- install dependencies
- run dev build
- run typecheck
- run unit tests
- run smoke test
- package app

### Frontend design

- generate layout plan from natural language requirement
- choose sensible UI pattern from templates (form, dashboard, list/detail, wizard, utility panel)
- generate component structure and styling tokens
- generate CSS/theme defaults suitable for appliance users
- generate responsive layout for common small displays
- review screenshot against requested UX

### Image generation / assets

- generate app icon
- generate placeholder illustrations / empty-state images
- generate simple background or decorative assets when useful
- generate SVG assets when bitmap generation is unavailable
- edit/regenerate assets from user feedback
- store generated assets as artifacts before copying into the app

### Electron automated testing

- generate Playwright/Electron tests for all core user workflows
- launch Electron app in controlled test mode
- interact with UI elements, forms, menus, file pickers, and local storage paths where applicable
- test invalid/empty/large input cases relevant to the generated tool
- test restart/persistence behavior when the app stores local data
- capture screenshots and traces for failed UI tests
- run packaged-app launch test after packaging

### UI evidence

- launch app under Xvfb/Wayland-compatible mode if available
- capture screenshot
- compare screenshot against generated design intent
- use automated UI test evidence, not only smoke-test evidence

### Delivery

- collect release artifact
- generate README / usage instructions
- generate final report

## 10. Doctor / Setup

First startup runs read-only doctor.

Checks:

- Node.js or Bun availability
- npm/pnpm availability
- Electron install ability
- frontend-design capability availability
- image generation provider availability or local image model availability
- build tools required by native npm modules
- display/Xvfb availability for automated Electron UI tests
- Playwright/Electron automation support
- disk space
- write permissions to workspace
- ARM Linux architecture
- package manager cache availability

If issues exist:

- Low-permission mode: ask user before fix
- High-permission appliance mode: run fix automatically after showing a brief visible plan, unless the user interrupts
- First startup on a prepared appliance may be pre-authorized by the vendor/operator; otherwise it shows the fix plan before proceeding

VibeBox's default appliance deployment should be high-permission and background-oriented. Environment setup is part of the product promise: the user should not need to manually install Node/Electron/build dependencies.

## 11. User Interaction Model

VibeBox should minimize technical language and assume the user lacks computer expertise. Default mode is highest-permission appliance automation with strong test/review gates, not an interactive developer workflow.

User sees:

```text
1. Understanding your app idea
2. Creating the app
3. Testing the app
4. Reviewing quality
5. Packaging for this box
6. Ready to use
```

Clarifying questions should be limited to product choices, for example:

- app name
- input/output file types
- desired UI layout
- whether data stays local
- whether app may access network

Do not ask users about implementation details unless necessary. If a decision can be safely inferred from the user's requirement and appliance defaults, VibeBox should choose automatically and report the choice in the final summary.

## 12. Review and Test Gate

VibeBox must maximize testing and review strength because the user may not be able to diagnose failures manually.

Before delivery, VibeBox must have:

- environment setup result
- dependency install result
- install/build command result
- typecheck result where TypeScript is used
- lint result when configured
- unit test result when tests exist
- integration test result for file/data flows when applicable
- end-to-end UI test result covering the main user workflows
- edge-case test result for invalid/empty/large inputs relevant to the app
- persistence/restart test result when the app stores local data
- frontend design review result
- generated asset review result when image-gen is used
- packaged-app launch test result
- screenshot evidence when a display backend is available
- reviewer report
- final package artifact

Recommended review passes:

1. Functional review: does the app match the user's request?
2. Runtime review: does it start and perform the golden path?
3. Full workflow test review: are all core user workflows covered by automated tests?
4. Edge-case review: are invalid/empty/large-input paths tested where relevant?
5. Frontend/design review: does the UI match the generated design intent and stay usable for a novice?
6. Asset review: are generated icons/images appropriate, local, and correctly bundled?
7. Security review: does it avoid dangerous filesystem/network/shell behavior?
8. Packaging review: can the delivered app run on the ARM Linux box?

If a gate is skipped, final report must say why. Delivery should be blocked if the app cannot be launched, packaged, or validated through all core workflows. Smoke testing alone is insufficient for delivery.

Delivery is blocked if:

- app fails to start
- package build fails
- generated app requests unsafe permissions not approved by user
- reviewer finds high-severity issue

## 13. Packaging and Delivery

Default package output:

```text
<app>/release/
  ├── <app-name>-arm64.AppImage or unpacked Linux directory
  ├── README.md
  └── vibebox-report.md
```

If AppImage is not feasible on the target box, deliver an unpacked Electron app directory plus launcher script.

Final report includes:

- what was built
- how to launch
- where files are stored
- tests run
- known limitations
- package path

## 14. Scope Guards

VibeBox should refuse or ask for escalation when user asks for:

- malware, credential stealing, persistence, stealth, evasion
- destructive system modification
- unsupported drivers/kernel changes
- large multi-service systems
- cloud deployment requiring secrets
- apps that require unapproved network or filesystem access

## 15. Reuse Strategy

Reuse strongly from AirCoding:

- execution-primitives aligned with Claude Code
- Anthropic canonical message handling
- ToolResult / ArtifactRef / EvidenceRef style
- doctor/dependency concepts
- basic session/artifact persistence

Reuse from OpenCode:

- optional TUI style if VibeBox has an operator console
- theme/dialog/status patterns

Reuse from Codex:

- shell/patch/test direct loop
- broad tool/capability examples

Reuse from Claude Skills:

- packaged workflow templates
- app-generation skill format

Do not carry over:

- AirCoding multi-agent scheduler complexity
- C++-specific toolchain
- long-term memory/curator in V1
- OpenCode business state model

## 16. MVP Acceptance Criteria

A VibeBox V1 prototype is acceptable when it can:

1. Run doctor on the ARM Linux box.
2. Accept a novice user's natural-language app request.
3. Ask at most 3 clarifying questions for a simple app.
4. Scaffold an Electron template.
5. Implement requested UI and local behavior.
6. Run build/typecheck/test or explain skipped gates.
7. Launch the app for a smoke test and capture evidence.
8. Run a review pass and fix at least one round of issues.
9. Package the app for ARM Linux or deliver a runnable unpacked app.
10. Produce a final user-friendly report.

## 17. Explicit Differences from AirCoding Baseline V1

| Area | AirCoding | VibeBox |
|---|---|---|
| Target | General coding agent, C++ first | Appliance for small Electron apps |
| User | Developer | Beginner/non-programmer |
| Agent model | Main + Architect + Scheduler + Workers | Linear Orchestrator + Executor + Reviewer |
| State layout | `.air/shared` + `.air/local` | `.vibebox/` per generated app |
| Toolchain | multi-language, C++ deep first | Electron/Node only |
| Parallelism | write-area/worktree capable | none in V1 |
| Memory | Project Rules + ExperienceMiner + Curator | minimal session memory only |
| Debug knowledge | structured local DB | not in V1 |
| UI assets | optional capability | useful for app UI generation |

## 18. Fixed V1 Implementation Decisions

Detailed rationale lives in `feasibility-plan.md`.

1. **Agent runtime**: Bun.
2. **Generated app stack**: Electron + Vite + TypeScript + React.
3. **Package manager**: bundled pnpm, npm fallback only if doctor records the fallback.
4. **Image generation**: cloud image provider first, SVG/design-prompt fallback always available.
5. **Display/test backend**: Xvfb-first controlled backend for automated Electron UI tests.
6. **Packaging**: unpacked app + launcher is the reliability baseline; AppImage arm64 is preferred when available.
7. **Permissions/setup**: default high-permission appliance mode with an allowlisted dependency installation set.
8. **Network**: generated apps are local-only by default unless the user request clearly requires network access or the user approves it.
9. **Testing**: smoke test alone is insufficient; V1 requires full workflow E2E tests for core user requirements.