diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..b3e69f6 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,171 @@ +# Requirements: Debate + +**Defined:** 2026-01-25 +**Core Value:** Make Linux customization visual and accessible to non-experts + +## v1 Requirements + +Requirements for initial release. Each maps to roadmap phases. + +### Builder Interface + +- [ ] **BUILD-01**: User can view configuration as interactive 3D stack of layers +- [ ] **BUILD-02**: User can rotate and zoom the 3D visualization +- [ ] **BUILD-03**: User can click a layer to select it and see details +- [ ] **BUILD-04**: User can add layers from the layer panel +- [ ] **BUILD-05**: User can remove layers by dragging off stack +- [ ] **BUILD-06**: User can search and filter available overlays in the panel +- [ ] **BUILD-07**: User sees smooth 60fps animations on mid-range hardware +- [ ] **BUILD-08**: Conflicting layers pulse red and lift off stack +- [ ] **BUILD-09**: User sees "Objection!" modal when conflicts arise +- [ ] **BUILD-10**: User can resolve conflicts via Concede (remove), Rebut (swap), or Withdraw (undo) +- [ ] **BUILD-11**: User can access 2D fallback interface on low-end devices + +### ISO Generation + +- [ ] **ISO-01**: User can initiate ISO build ("Deliver") when configuration is valid +- [ ] **ISO-02**: User sees queue position and estimated wait time +- [ ] **ISO-03**: User sees build progress with stages +- [ ] **ISO-04**: ISO builds run in sandboxed environment (systemd-nspawn) +- [ ] **ISO-05**: Identical configurations serve cached ISO immediately +- [ ] **ISO-06**: User can download completed ISO ("Take the Floor") +- [ ] **ISO-07**: Build failures report clear error messages to user + +### Speeches (Saved Configurations) + +- [ ] **SPCH-01**: User can save current configuration as named speech +- [ ] **SPCH-02**: User can add description and topics (tags) to speech +- [ ] **SPCH-03**: User can load saved speech into builder +- [ ] **SPCH-04**: Non-authenticated users can save locally (browser storage) +- [ ] **SPCH-05**: User can publish speech publicly +- [ ] **SPCH-06**: Published speeches are searchable by title/description +- [ ] **SPCH-07**: User can browse community speeches in grid view +- [ ] **SPCH-08**: User can filter speeches by topics, base distribution, window manager, author +- [ ] **SPCH-09**: User can sort speeches by popularity, rating, recent, trending +- [ ] **SPCH-10**: Speech cards show mini preview, title, author, topics, stats +- [ ] **SPCH-11**: User can load community speech into builder +- [ ] **SPCH-12**: User can rate community speeches + +### User Accounts + +- [ ] **USER-01**: User can register with email and password +- [ ] **USER-02**: User can log in with email and password +- [ ] **USER-03**: User session persists across browser refresh +- [ ] **USER-04**: User can log out +- [ ] **USER-05**: User can register/login via GitHub OAuth +- [ ] **USER-06**: User can register/login via Google OAuth +- [ ] **USER-07**: User receives email verification after registration +- [ ] **USER-08**: User can reset password via email link +- [ ] **USER-09**: User can set unique username +- [ ] **USER-10**: User can upload avatar image +- [ ] **USER-11**: User can write bio +- [ ] **USER-12**: User can view their saved speeches in dashboard +- [ ] **USER-13**: User can view their published speeches in dashboard +- [ ] **USER-14**: User can view build history in dashboard +- [ ] **USER-15**: Other users can view public profile (username, avatar, bio, published speeches) + +### Overlay System + +- [ ] **OVLY-01**: Overlays defined via YAML manifest schema +- [ ] **OVLY-02**: Manifests specify name, version, type, description, author, license +- [ ] **OVLY-03**: Manifests specify requires (dependencies), conflicts, provides, replaces +- [ ] **OVLY-04**: Manifests can define user-configurable options (toggle, select, text, number) +- [ ] **OVLY-05**: System builds dependency graph from selected overlays +- [ ] **OVLY-06**: System detects conflicts (objections) before build +- [ ] **OVLY-07**: System detects missing requirements and shows warnings +- [ ] **OVLY-08**: System suggests compatible alternatives when conflicts arise +- [ ] **OVLY-09**: System topologically sorts overlays for correct application order +- [ ] **OVLY-10**: Layer hierarchy enforced: Opening Statement → Platform → Rhetoric → Talking Points → Closing Argument +- [ ] **OVLY-11**: Users can submit new overlays via GitHub PR workflow +- [ ] **OVLY-12**: Submitted overlays undergo automated schema validation +- [ ] **OVLY-13**: Submitted overlays undergo security scan +- [ ] **OVLY-14**: Approved overlays appear in builder + +### Distribution Support + +- [ ] **DIST-01**: CachyOS available as Opening Statement +- [ ] **DIST-02**: Omarchy opinions mapped to overlays (theming, apps, configs) +- [ ] **DIST-03**: Hyprland available as Platform +- [ ] **DIST-04**: Sway available as Platform +- [ ] **DIST-05**: i3 available as Platform +- [ ] **DIST-06**: KDE Plasma available as Platform +- [ ] **DIST-07**: COSMIC available as Platform +- [ ] **DIST-08**: GNOME available as Platform +- [ ] **DIST-09**: Pure Arch available as Opening Statement +- [ ] **DIST-10**: EndeavourOS available as Opening Statement + +### Infrastructure + +- [ ] **INFR-01**: API response time < 200ms (p95) +- [ ] **INFR-02**: ISO build completes within 15 minutes +- [ ] **INFR-03**: Platform available 99.9% uptime +- [ ] **INFR-04**: User data protected and backed up daily +- [ ] **INFR-05**: All traffic over HTTPS +- [ ] **INFR-06**: Rate limiting on API endpoints +- [ ] **INFR-07**: CSRF protection enabled + +## v2 Requirements + +Deferred to future release. Tracked but not in current roadmap. + +### Enhanced Build Features + +- **ISO-V2-01**: Build size calculator shows real-time estimate +- **ISO-V2-02**: Live log output visible during build (collapsible) +- **ISO-V2-03**: Multi-format export (ISO, USB image, Ventoy-compatible) + +### Live Preview + +- **PREV-01**: User can boot generated ISO in browser via WebVM +- **PREV-02**: Preview runs without downloading full ISO + +### Additional Distributions + +- **DIST-V2-01**: Fedora available as Opening Statement +- **DIST-V2-02**: Ubuntu available as Opening Statement +- **DIST-V2-03**: Cross-distro package mapping layer + +### Collaboration + +- **COLLAB-01**: Multiple users can edit same speech simultaneously +- **COLLAB-02**: Speech version history with diff view + +### Moderation + +- **MOD-01**: Users can flag inappropriate speeches +- **MOD-02**: Admin can review flagged content +- **MOD-03**: Admin can remove/hide violating speeches +- **MOD-04**: Admin can warn/ban users + +## Out of Scope + +Explicitly excluded. Documented to prevent scope creep. + +| Feature | Reason | +|---------|--------| +| Mobile application | Web-first, desktop browser target; mobile can come later | +| Direct installation to hardware | Users download ISO and install themselves | +| Paid/premium tiers | v1 is free to establish user base | +| Enterprise features | Focus on individual users and community | +| Cross-distribution support (Fedora/Ubuntu) | Deep > wide; get Arch family working perfectly first | +| Full NixOS-style declarative config | Too complex for target audience | +| Custom package repository hosting | Infrastructure burden, security liability | +| Post-install configuration management | Scope creep; link to Ansible/dotfiles instead | +| Secure Boot signing | Nice to have but not critical for target audience | + +## Traceability + +Which phases cover which requirements. Updated during roadmap creation. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| (To be filled by roadmapper) | | | + +**Coverage:** +- v1 requirements: 70 total +- Mapped to phases: 0 +- Unmapped: 70 (awaiting roadmap) + +--- +*Requirements defined: 2026-01-25* +*Last updated: 2026-01-25 after initial definition*