Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
738
AirPlan/docs/architecture/branchvibebox/feasibility-plan.md
Normal file
738
AirPlan/docs/architecture/branchvibebox/feasibility-plan.md
Normal file
@@ -0,0 +1,738 @@
|
||||
# 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.
|
||||
545
AirPlan/docs/architecture/branchvibebox/vibeboxbaseline.md
Normal file
545
AirPlan/docs/architecture/branchvibebox/vibeboxbaseline.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user