AirCoding/AirPlan/docs/architecture/vibeboxbaseline.md

VibeBox Baseline V1

Date: 2026-05-26 Status: Historical/top-level VibeBox overview; canonical VibeBox branch baseline lives at AirPlan/docs/architecture/branchvibebox/vibeboxbaseline.md

This file is retained as a high-level overview. Implementation decisions for VibeBox V1 are authoritative in AirPlan/docs/architecture/branchvibebox/vibeboxbaseline.md and AirPlan/docs/architecture/branchvibebox/feasibility-plan.md.

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:

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:

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:

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:

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.

<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:

<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:

clarify
plan
scaffold
implement
test
review
fix
package
deliver

Artifacts:

.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:

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:

<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. Open Issues Before Implementation

Before coding VibeBox, decide:

1. Bun vs Node for the appliance runtime.
2. Electron template stack: React/Vite vs plain HTML/TS.
3. Package manager: npm vs pnpm.
4. Packaging target: AppImage vs unpacked app + launcher.
5. Whether VibeBox has a TUI/operator UI or only a simple local web/app shell.
6. Exact smoke-test approach on the ARM Linux box.
7. Whether generated apps may use network by default or must be local-only.