AirCoding/AirPlan/docs/architecture/branchvibebox/feasibility-plan.md

# VibeBox Feasibility and Implementation Plan

Date: 2026-05-26
Status: Practical implementation plan for the VibeBox downstream branch

## 1. Feasibility Verdict

VibeBox is feasible if scoped as an appliance that generates small, local Electron utilities from templates.

It is not feasible as an unrestricted “any software from any prompt” agent. The product must enforce a constrained scope:

```text
small local Electron app
  + template-based generation
  + default high-permission appliance setup
  + frontend-design and image-gen capabilities
  + full automated workflow testing
  + review gates
  + ARM Linux packaging/delivery
```

Expected timelines:

| Stage | Estimate | Outcome |
|---|---:|---|
| Prototype | 3–5 weeks | Generates and packages simple Electron tools |
| Partner trial | 6–8 weeks | Background setup/dev/test/review/package on ARM Linux box |
| Stable appliance version | 10–12 weeks | Hardened testing, packaging fallback, diagnostics, user-friendly failure handling |

## 2. Product Contract

VibeBox should provide this user experience:

```text
User: “I want a tool that renames photos by date and lets me preview the result.”

VibeBox:
  1. asks only blocking product questions, if any
  2. configures the environment silently where allowed
  3. generates a small Electron app
  4. designs the UI and required assets
  5. writes code
  6. runs full automated tests
  7. reviews security/functionality/packaging
  8. packages for ARM Linux
  9. gives the user a runnable app and a simple report
```

The user should not supervise implementation. The user may lack computer expertise.

## 3. Scope Boundaries

### Accepted by default

- Small desktop utility
- Local-first app
- Simple filesystem workflows
- Form/data-entry tools
- CSV/JSON/image batch helpers
- Clipboard/notes/todo utilities
- Single-window dashboards
- Simple API client if network access is declared

### Requires narrowing question

- vague app idea
- multiple unrelated features
- unclear input/output data
- network access or credentials
- destructive filesystem operations
- system integration beyond app sandbox

### Refuse or escalate

- malware, credential theft, stealth, evasion
- destructive system modification
- kernel/driver changes
- large Excel/Photoshop/IDE-like apps
- multi-service cloud systems
- unbounded automation over arbitrary shell commands

## 4. Architecture Cut from AirCoding

VibeBox keeps only the minimum needed path.

```text
Orchestrator
  → Executor
  → Reviewer/Tester
  → Packager
  → Delivery Reporter
```

No V1 support for:

- Architecture Designer as a separate agent
- complex TaskGraph / Scheduler
- parallel write workers
- worktree merging
- C++ toolchain
- ExperienceMiner / Curator
- Debug Knowledge Network
- plugin marketplace
- broad multi-language runtime

## 5. Default Permission Model

VibeBox is an appliance product and should default to highest-permission automation.

However, highest permission is bounded by appliance policy:

```text
Allowed automatically:
  - installing approved runtime dependencies
  - creating/modifying generated app projects
  - running tests/build/package commands
  - writing artifacts/reports
  - using configured image-gen provider

Requires explicit user/operator confirmation:
  - credentials entry
  - network access not implied by the user request
  - destructive file operations outside the app workspace
  - system-sensitive paths
  - shell execution exposed inside generated app
```

System dependency installation should use an allowlist controlled by the appliance vendor/operator.

## 6. Recommended Technology Stack

### Runtime

Preferred for V1:

```text
Node.js runtime for generated apps
Bun or Node.js for the VibeBox agent runtime
```

Choose Node for maximum Electron ecosystem compatibility if uncertain.

### Generated app stack

```text
Electron
Vite
TypeScript
React
CSS modules or simple Tailwind-like design tokens
Playwright/Electron tests
Electron Builder or Electron Forge
```

### Test stack

```text
Vitest for unit tests
Playwright + Electron for E2E tests
Xvfb or configured display backend for ARM Linux UI automation
```

### Packaging

Primary:

```text
AppImage arm64 if stable on target box
```

Fallback:

```text
unpacked Electron app + launcher script
```

The fallback is important. Packaging should not block delivery if an unpacked app runs reliably.

## 7. Template Strategy

VibeBox must be template-first.

Suggested V1 templates:

```text
templates/
  file-batch-tool/
  data-table-tool/
  form-entry-tool/
  clipboard-tool/
  notes-todo-tool/
  image-batch-tool/
  api-dashboard-tool/
  single-panel-utility/
```

Each template includes:

- Electron secure main/preload/renderer structure
- React component skeleton
- local storage helper
- design tokens
- test harness
- Playwright fixtures
- packaging config
- README/report template

AI should select and fill templates, not build projects from scratch.

## 8. Built-in Capabilities

### 8.1 frontend-design

First-class built-in capability.

Inputs:

- user requirement
- selected template
- display size constraints
- novice-user profile

Outputs:

- UI layout plan
- component hierarchy
- design tokens
- copywriting
- empty/loading/error states
- screenshot review checklist

Default design priorities:

1. clarity over aesthetics
2. large readable controls
3. obvious next action
4. safe defaults
5. clear error messages
6. local-first expectations

### 8.2 image-gen

First-class built-in capability.

V1 should support:

- app icon generation
- empty-state / placeholder illustration generation
- simple decorative assets
- SVG fallback when bitmap generation is unavailable
- multiple candidate generation if provider supports it

Provider strategy:

```text
preferred: configured cloud image provider
fallback: SVG/simple generated asset
deferred: heavy local image model on ARM unless hardware supports it
```

Generated assets are artifacts first. They are copied into the app only after internal selection/review.

### 8.3 electron-test

First-class built-in capability.

Required functions:

- launch generated Electron app in test mode
- interact with UI through Playwright
- test core workflows
- test edge cases
- test persistence/restart when applicable
- capture screenshot/trace artifacts
- launch packaged app or unpacked delivery

Smoke test alone is insufficient.

## 9. Testing Policy

VibeBox users may not be able to diagnose software failures. Therefore, delivery requires full workflow validation.

Minimum delivery gates:

1. environment setup passed
2. dependencies installed
3. build passed
4. typecheck passed when TypeScript is used
5. lint passed when configured
6. unit tests passed or skipped with reason
7. integration tests passed for data/file flows
8. E2E tests cover all core user workflows
9. edge cases tested where relevant
10. persistence/restart tested if local data is stored
11. packaged or delivered app launches
12. screenshot evidence captured when display backend exists
13. review report approves delivery

Core workflow coverage definition:

```text
For every user-visible requirement, at least one automated test exercises the path.
For every input type, normal / empty / invalid / large input cases are tested where practical.
For storage features, restart recovery is tested.
For delivery, the packaged or unpacked app launch is tested.
```

## 10. Review Policy

Reviewer/Tester pass should use a fixed checklist.

### Functional review

- Does the app implement the user request?
- Are any requested features missing?
- Are assumptions clearly reported?

### UX/design review

- Is the UI understandable to a novice?
- Are controls readable on the target display?
- Are error states visible and actionable?
- Does screenshot match design intent?

### Asset review

- Are generated icons/images appropriate?
- Are assets bundled locally?
- Are missing provider fallbacks acceptable?

### Security review

- `contextIsolation: true`
- `nodeIntegration: false`
- preload API is minimal
- no arbitrary shell exposure
- filesystem access scoped to the app's purpose
- network access declared if used

### Test review

- Do tests cover all core workflows?
- Are skipped tests justified?
- Are failure artifacts available?

### Packaging review

- Does the delivered app launch on the ARM Linux box?
- Is there a fallback launcher if AppImage fails?

## 11. Doctor / Setup

Doctor runs at first boot and before generation.

Checks:

- ARM Linux architecture
- Node/Bun availability
- npm/pnpm availability
- Electron install ability
- native npm build tools
- frontend-design capability availability
- image-gen provider or fallback availability
- Playwright/Electron automation support
- Xvfb/display backend
- disk space
- workspace write permission
- package cache availability

Modes:

```text
prepared appliance:
  pre-authorized high-permission setup
  run fixes automatically with brief visible status

unprepared/manual mode:
  show fix plan and ask operator before fixing
```

## 12. State Layout

Each generated app is self-contained.

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

Minimum DB tables:

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

Pipeline steps:

```text
understand
setup
plan
scaffold
design
asset_generate
implement
test
review
fix
package
deliver
```

## 13. Delivery Contract

Delivery directory:

```text
<app>/release/
  ├── <app-name>-arm64.AppImage        # if available
  ├── unpacked/                        # fallback if needed
  ├── launch.sh                        # fallback launcher
  ├── README.md
  └── vibebox-report.md
```

Final report must be non-technical and include:

- what was built
- how to launch it
- what it can do
- where its data is stored
- tests that passed
- known limitations
- package path
- what VibeBox automatically configured

## 14. Failure Handling

If generation fails, VibeBox should not dump raw logs to the user.

It should provide:

```text
- simple explanation
- what was attempted
- what failed
- whether retry is possible
- what the user/operator can do next
- diagnostic artifact bundle path
```

Automatic retry limits:

- implementation/test fix cycle: max 2–3 rounds
- dependency setup: max 1 automatic fix attempt per issue
- package fallback: AppImage → unpacked app + launcher

If still failing, deliver a failure report and preserve artifacts.

## 15. Implementation Phases

### Phase 0 — Feasibility spike (3–5 days)

Goal: prove Electron generation/testing/package path on the ARM box.

Tasks:

- choose runtime/package manager
- scaffold one fixed Electron template
- run build/typecheck
- run Playwright/Electron E2E on box
- package AppImage or produce unpacked app
- document environment dependencies

Exit criteria:

- a hand-coded sample app can be built, tested, and launched on the target box

### Phase 1 — Prototype generator (1–2 weeks)

Tasks:

- implement Orchestrator linear pipeline
- implement filesystem/shell/template tools
- implement session/artifact logging
- implement one template family
- generate simple app from natural language
- generate tests for golden path
- produce final report

Exit criteria:

- user prompt → generated runnable app for 2–3 simple examples

### Phase 2 — Strong testing/review (1–2 weeks)

Tasks:

- add electron-test capability
- add edge-case test generation
- add restart/persistence test
- add reviewer checklist
- add screenshot evidence
- add fix loop

Exit criteria:

- generated apps pass workflow tests and review gates before delivery

### Phase 3 — frontend-design + image-gen (1–2 weeks)

Tasks:

- implement frontend-design spec generation
- add design tokens/templates
- add image-gen provider interface
- add SVG fallback
- add asset review

Exit criteria:

- generated app includes coherent UI design and usable assets

### Phase 4 — appliance hardening (2–4 weeks)

Tasks:

- doctor/setup automatic fixes
- high-permission appliance policy
- package fallback
- non-technical failure reports
- more templates
- partner trial scenarios

Exit criteria:

- partner can use VibeBox on the ARM box with minimal operator intervention

## 16. Recommended V1 Cut Line

V1 should include:

- high-permission appliance setup
- Electron + Vite + TS + React template
- 5–8 templates
- frontend-design
- image-gen provider with SVG fallback
- full workflow Playwright/Electron tests
- review gate
- AppImage or unpacked delivery fallback
- final non-technical report

V1 should not include:

- arbitrary app complexity
- local heavy image model unless hardware supports it
- plugin marketplace
- long-term memory/curator
- multi-agent scheduler
- cloud/backend deployment
- unrestricted shell apps

## 17. Top Risks and Mitigations

| Risk | Mitigation |
|---|---|
| User asks for too-large app | scope classifier + propose smaller MVP |
| Electron packaging fails on ARM | unpacked app + launcher fallback |
| UI tests flaky on display backend | fixed appliance environment + Xvfb/Wayland profile |
| image-gen unavailable | SVG fallback + design prompt artifact |
| generated app unsafe | fixed Electron security template + security review gate |
| novice user cannot debug failure | non-technical report + preserved diagnostics |
| dependency setup breaks system | allowlisted high-permission setup only |

## 18. Implementation Decisions

The following decisions are fixed for VibeBox V1 to avoid delaying implementation.

### 18.1 Agent Runtime

**Decision: Bun for the VibeBox agent runtime.**

Reasons:

- aligns with AirCoding baseline
- fast startup on appliance
- good TypeScript support
- easy subprocess management
- can still generate Node/Electron apps normally

The generated Electron apps use Node/Electron runtime as usual; Bun is only the agent/runtime implementation choice.

### 18.2 Generated App Package Manager

**Decision: bundled pnpm for generated apps.**

Reasons:

- deterministic dependency resolution
- faster installs than npm
- better workspace/cache behavior
- avoids relying on user-installed package manager

VibeBox should ship or bootstrap a known pnpm version into its appliance cache.

Fallback: npm may be used only if pnpm bootstrap fails and doctor records the fallback.

### 18.3 Electron Template Stack

**Decision: Electron + Vite + TypeScript + React.**

Reasons:

- mature Electron template ecosystem
- React is easier for AI-generated UI composition
- TypeScript improves generated-code validation
- Vite gives fast build/dev loop
- Playwright/Electron testing works well with this stack

Default security posture:

- `contextIsolation: true`
- `nodeIntegration: false`
- explicit preload bridge
- no arbitrary shell exposure to renderer
- local-first storage

### 18.4 Image Generation Provider

**Decision: cloud image provider first, SVG fallback always available.**

V1 includes a provider interface and default cloud-provider adapter selected by deployment configuration.

If image provider is unavailable:

- generate SVG icon/assets
- generate design prompt artifact
- use template placeholder assets
- continue delivery if app functionality is not blocked

Heavy local image models are not V1 unless the appliance hardware is explicitly provisioned for them.

### 18.5 Display / UI Test Backend

**Decision: Xvfb-first controlled display backend for automated tests.**

Reasons:

- predictable CI/appliance behavior
- mature with Electron and Playwright
- easier to run headless than Wayland-first automation

If the target appliance is Wayland-only, provide a configured compatibility path, but V1 test automation assumes Xvfb availability.

### 18.6 Packaging Default

**Decision: unpacked app + launcher is the reliability baseline; AppImage is a preferred artifact when available.**

Delivery order:

1. Build unpacked Electron app directory.
2. Generate `launch.sh` and verify it starts.
3. Attempt AppImage arm64 packaging.
4. If AppImage fails but unpacked app passes full tests, deliver unpacked app + launcher and report AppImage failure as non-blocking.

Rationale: delivery of a working tool matters more than a single-file package.

### 18.7 High-Permission Dependency Installation Allowlist

**Decision: high-permission setup may automatically install only allowlisted dependencies.**

Initial ARM Linux allowlist:

```text
runtime:
  - nodejs
  - npm
  - pnpm bootstrap into VibeBox cache

build/electron:
  - python3
  - make
  - gcc/g++ or build-essential equivalent
  - git
  - unzip
  - tar
  - xz-utils
  - ca-certificates

ui-test/display:
  - xvfb
  - libgtk-3 / gtk runtime package
  - libnss3
  - libxss1
  - libasound2 or platform equivalent
  - libx11-xcb1
  - libxcomposite1
  - libxdamage1
  - libxrandr2
  - libgbm1

packaging:
  - fuse or fuse3 when AppImage requires it
  - desktop-file-utils when available
```

Rules:

- Dependency names are normalized per OS/package manager by Doctor.
- Commands are shown in status, but appliance high-permission mode runs them unless interrupted.
- Credentials, destructive system changes, kernel/driver changes, and non-allowlisted packages require operator confirmation.
- All setup actions are recorded in `.vibebox/reports/setup-report.md` and command artifacts.

### 18.8 Network Default

**Decision: generated apps are local-only by default.**

Network access is allowed only when:

- the user's request clearly requires it, or
- VibeBox asks and receives product-level approval, or
- the template explicitly declares a safe local-only loopback service.

Final report must state whether the generated app uses network access.