mikkel/debate
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: create roadmap (9 phases)

Browse source 
Phases:
1. Core Infrastructure & Security: INFR-*, ISO-04
2. Overlay System Foundation: OVLY-01 to OVLY-07, OVLY-10
3. Build Queue & Workers: ISO-01 to ISO-07 (except ISO-04)
4. User Accounts: USER-01 to USER-15
5. Builder Interface (2D): BUILD-04 to BUILD-06, BUILD-09 to BUILD-11
6. Speeches & Community: SPCH-*, OVLY-11 to OVLY-14
7. 3D Visualization: BUILD-01 to BUILD-03, BUILD-07, BUILD-08
8. Advanced Dependency Resolution: OVLY-08, OVLY-09
9. Distribution Content: DIST-01 to DIST-10

All 70 v1 requirements mapped to phases.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Mikkel Georgsen 2026-01-25 19:32:27 +00:00
parent f4d2185a56
commit 16b17ca2cf
3 changed files with 353 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
.planning/REQUIREMENTS.md
View file

@ -159,13 +159,99 @@ Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|-------------|-------|--------|
| (To be filled by roadmapper) | | |
| BUILD-01 | Phase 7 | Pending |
| BUILD-02 | Phase 7 | Pending |
| BUILD-03 | Phase 7 | Pending |
| BUILD-04 | Phase 5 | Pending |
| BUILD-05 | Phase 5 | Pending |
| BUILD-06 | Phase 5 | Pending |
| BUILD-07 | Phase 7 | Pending |
| BUILD-08 | Phase 7 | Pending |
| BUILD-09 | Phase 5 | Pending |
| BUILD-10 | Phase 5 | Pending |
| BUILD-11 | Phase 5 | Pending |
| ISO-01 | Phase 3 | Pending |
| ISO-02 | Phase 3 | Pending |
| ISO-03 | Phase 3 | Pending |
| ISO-04 | Phase 1 | Pending |
| ISO-05 | Phase 3 | Pending |
| ISO-06 | Phase 3 | Pending |
| ISO-07 | Phase 3 | Pending |
| SPCH-01 | Phase 6 | Pending |
| SPCH-02 | Phase 6 | Pending |
| SPCH-03 | Phase 6 | Pending |
| SPCH-04 | Phase 6 | Pending |
| SPCH-05 | Phase 6 | Pending |
| SPCH-06 | Phase 6 | Pending |
| SPCH-07 | Phase 6 | Pending |
| SPCH-08 | Phase 6 | Pending |
| SPCH-09 | Phase 6 | Pending |
| SPCH-10 | Phase 6 | Pending |
| SPCH-11 | Phase 6 | Pending |
| SPCH-12 | Phase 6 | Pending |
| USER-01 | Phase 4 | Pending |
| USER-02 | Phase 4 | Pending |
| USER-03 | Phase 4 | Pending |
| USER-04 | Phase 4 | Pending |
| USER-05 | Phase 4 | Pending |
| USER-06 | Phase 4 | Pending |
| USER-07 | Phase 4 | Pending |
| USER-08 | Phase 4 | Pending |
| USER-09 | Phase 4 | Pending |
| USER-10 | Phase 4 | Pending |
| USER-11 | Phase 4 | Pending |
| USER-12 | Phase 4 | Pending |
| USER-13 | Phase 4 | Pending |
| USER-14 | Phase 4 | Pending |
| USER-15 | Phase 4 | Pending |
| OVLY-01 | Phase 2 | Pending |
| OVLY-02 | Phase 2 | Pending |
| OVLY-03 | Phase 2 | Pending |
| OVLY-04 | Phase 2 | Pending |
| OVLY-05 | Phase 2 | Pending |
| OVLY-06 | Phase 2 | Pending |
| OVLY-07 | Phase 2 | Pending |
| OVLY-08 | Phase 8 | Pending |
| OVLY-09 | Phase 8 | Pending |
| OVLY-10 | Phase 2 | Pending |
| OVLY-11 | Phase 6 | Pending |
| OVLY-12 | Phase 6 | Pending |
| OVLY-13 | Phase 6 | Pending |
| OVLY-14 | Phase 6 | Pending |
| DIST-01 | Phase 9 | Pending |
| DIST-02 | Phase 9 | Pending |
| DIST-03 | Phase 9 | Pending |
| DIST-04 | Phase 9 | Pending |
| DIST-05 | Phase 9 | Pending |
| DIST-06 | Phase 9 | Pending |
| DIST-07 | Phase 9 | Pending |
| DIST-08 | Phase 9 | Pending |
| DIST-09 | Phase 9 | Pending |
| DIST-10 | Phase 9 | Pending |
| INFR-01 | Phase 1 | Pending |
| INFR-02 | Phase 1 | Pending |
| INFR-03 | Phase 1 | Pending |
| INFR-04 | Phase 1 | Pending |
| INFR-05 | Phase 1 | Pending |
| INFR-06 | Phase 1 | Pending |
| INFR-07 | Phase 1 | Pending |
**Coverage:**
- v1 requirements: 70 total
- Mapped to phases: 0
- Unmapped: 70 (awaiting roadmap)
- Mapped to phases: 70
- Unmapped: 0
**Phase Distribution:**
- Phase 1 (Infrastructure & Security): 8 requirements
- Phase 2 (Overlay System Foundation): 8 requirements
- Phase 3 (Build Queue & Workers): 6 requirements
- Phase 4 (User Accounts): 15 requirements
- Phase 5 (Builder Interface 2D): 7 requirements
- Phase 6 (Speeches & Community): 16 requirements
- Phase 7 (3D Visualization): 5 requirements
- Phase 8 (Advanced Dependency Resolution): 2 requirements
- Phase 9 (Distribution Content): 10 requirements
---
*Requirements defined: 2026-01-25*
*Last updated: 2026-01-25 after initial definition*
*Last updated: 2026-01-25 after roadmap creation*

196
.planning/ROADMAP.md Normal file
View file

@ -0,0 +1,196 @@
# Roadmap: Debate
## Overview
Debate transforms Linux distribution customization from command-line complexity into visual creativity. The roadmap follows a dependency-driven path: secure infrastructure first, then overlay and build systems, then user-facing features (accounts, 2D interface, speeches), and finally polish (3D visualization, advanced dependency resolution, multi-distribution content). Each phase delivers verifiable user value, building toward a platform where non-experts can visually customize Linux distributions with confidence.
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 1: Core Infrastructure & Security** - Foundation with sandboxed build environment
- [ ] **Phase 2: Overlay System Foundation** - Layer management and composition engine
- [ ] **Phase 3: Build Queue & Workers** - ISO generation with archiso
- [ ] **Phase 4: User Accounts** - Authentication and user profiles
- [ ] **Phase 5: Builder Interface (2D)** - Functional UI without 3D visualization
- [ ] **Phase 6: Speeches & Community** - Save, share, and discover configurations
- [ ] **Phase 7: 3D Visualization** - Interactive stack visualization (core differentiator)
- [ ] **Phase 8: Advanced Dependency Resolution** - SAT solver with visual conflict resolution
- [ ] **Phase 9: Distribution Content** - Multiple platforms and opening statements
## Phase Details
### Phase 1: Core Infrastructure & Security
**Goal**: Production-ready backend infrastructure with security-hardened build environment
**Depends on**: Nothing (first phase)
**Requirements**: INFR-01, INFR-02, INFR-03, INFR-04, INFR-05, INFR-06, INFR-07, ISO-04
**Success Criteria** (what must be TRUE):
1. FastAPI backend serves requests with <200ms p95 latency
2. PostgreSQL database accepts connections with daily backups configured
3. All traffic flows over HTTPS with valid certificates
4. API endpoints enforce rate limiting and CSRF protection
5. ISO builds execute in sandboxed containers (systemd-nspawn) with no host access
6. Build environment produces deterministic ISOs (identical input = identical hash)
**Plans**: TBD
Plans:
- [ ] 01-01: TBD (during phase planning)
### Phase 2: Overlay System Foundation
**Goal**: Layer-based configuration system with dependency tracking and composition
**Depends on**: Phase 1
**Requirements**: OVLY-01, OVLY-02, OVLY-03, OVLY-04, OVLY-05, OVLY-06, OVLY-07, OVLY-10
**Success Criteria** (what must be TRUE):
1. System can store overlay manifests with metadata (name, version, type, description, author, license)
2. Manifests define relationships (requires, conflicts, provides, replaces) via YAML schema
3. Manifests support user-configurable options (toggle, select, text, number)
4. System detects direct conflicts between selected overlays before build
5. System enforces layer hierarchy: Opening Statement → Platform → Rhetoric → Talking Points → Closing Argument
6. System builds dependency graph from selected overlays
7. Overlay engine merges layers with correct precedence (higher layers override lower)
**Plans**: TBD
Plans:
- [ ] 02-01: TBD (during phase planning)
### Phase 3: Build Queue & Workers
**Goal**: Asynchronous ISO generation with queue management and caching
**Depends on**: Phase 2
**Requirements**: ISO-01, ISO-02, ISO-03, ISO-05, ISO-06, ISO-07
**Success Criteria** (what must be TRUE):
1. User can initiate ISO build when configuration is valid
2. User sees queue position and estimated wait time
3. User sees build progress with stage updates (package install, customization, ISO creation)
4. ISO builds complete within 15 minutes
5. Identical configurations serve cached ISO immediately (no rebuild)
6. User can download completed ISO
7. Build failures show clear error messages explaining what went wrong
**Plans**: TBD
Plans:
- [ ] 03-01: TBD (during phase planning)
### Phase 4: User Accounts
**Goal**: User authentication, profiles, and personal dashboard
**Depends on**: Phase 1
**Requirements**: USER-01, USER-02, USER-03, USER-04, USER-05, USER-06, USER-07, USER-08, USER-09, USER-10, USER-11, USER-12, USER-13, USER-14, USER-15
**Success Criteria** (what must be TRUE):
1. User can register with email/password or via GitHub/Google OAuth
2. User receives email verification after registration
3. User can log in and session persists across browser refresh
4. User can reset forgotten password via email link
5. User can set unique username, upload avatar, and write bio
6. User can view dashboard showing saved speeches, published speeches, and build history
7. Other users can view public profiles (username, avatar, bio, published speeches)
**Plans**: TBD
Plans:
- [ ] 04-01: TBD (during phase planning)
### Phase 5: Builder Interface (2D)
**Goal**: Functional configuration UI with layer management (no 3D yet)
**Depends on**: Phase 2, Phase 3
**Requirements**: BUILD-04, BUILD-05, BUILD-06, BUILD-09, BUILD-10, BUILD-11
**Success Criteria** (what must be TRUE):
1. User can browse and search available overlays in layer panel with filtering
2. User can add layers to configuration from panel
3. User can remove layers from configuration
4. When conflicts arise, user sees "Objection!" modal with conflict details
5. User can resolve conflicts via Concede (remove layer), Rebut (swap layer), or Withdraw (undo)
6. User can access 2D fallback interface on low-end devices
7. User can build valid configuration and initiate ISO generation from UI
**Plans**: TBD
Plans:
- [ ] 05-01: TBD (during phase planning)
### Phase 6: Speeches & Community
**Goal**: Save, publish, browse, and discover community configurations
**Depends on**: Phase 4, Phase 5
**Requirements**: SPCH-01, SPCH-02, SPCH-03, SPCH-04, SPCH-05, SPCH-06, SPCH-07, SPCH-08, SPCH-09, SPCH-10, SPCH-11, SPCH-12, OVLY-11, OVLY-12, OVLY-13, OVLY-14
**Success Criteria** (what must be TRUE):
1. User can save current configuration as named speech with description and topics (tags)
2. Non-authenticated users can save speeches locally in browser storage
3. Authenticated users can publish speeches publicly
4. User can browse community speeches in grid view with mini previews
5. User can filter speeches by topics, base distribution, window manager, author
6. User can sort speeches by popularity, rating, recent, trending
7. User can load community speech into builder
8. User can rate community speeches
9. Users can submit new overlays via GitHub PR workflow
10. Submitted overlays undergo automated schema validation and security scanning
11. Approved overlays appear in builder
**Plans**: TBD
Plans:
- [ ] 06-01: TBD (during phase planning)
### Phase 7: 3D Visualization
**Goal**: Interactive 3D stack visualization making configuration tangible
**Depends on**: Phase 5
**Requirements**: BUILD-01, BUILD-02, BUILD-03, BUILD-07, BUILD-08
**Success Criteria** (what must be TRUE):
1. User sees configuration as interactive 3D stack of layers
2. User can rotate and zoom the 3D visualization with mouse/touch
3. User can click a layer in 3D space to select it and see details
4. 3D visualization runs at 60fps on mid-range hardware (Intel UHD Graphics)
5. Conflicting layers visually pulse red and lift off the stack
6. Animations are smooth and responsive to user interaction
**Plans**: TBD
Plans:
- [ ] 07-01: TBD (during phase planning)
### Phase 8: Advanced Dependency Resolution
**Goal**: SAT solver-based dependency resolution with intelligent conflict suggestions
**Depends on**: Phase 2, Phase 5
**Requirements**: OVLY-08, OVLY-09
**Success Criteria** (what must be TRUE):
1. System detects missing requirements and shows clear warnings
2. System suggests compatible alternative overlays when conflicts arise
3. System topologically sorts overlays for correct application order
4. Dependency resolution completes in <1 second for typical configurations (50-100 overlays)
5. Conflict explanations help users understand why overlays are incompatible
6. Alternative suggestions are contextually relevant (same type, similar features)
**Plans**: TBD
Plans:
- [ ] 08-01: TBD (during phase planning)
### Phase 9: Distribution Content
**Goal**: Multiple window managers and base distributions available
**Depends on**: Phase 2
**Requirements**: DIST-01, DIST-02, DIST-03, DIST-04, DIST-05, DIST-06, DIST-07, DIST-08, DIST-09, DIST-10
**Success Criteria** (what must be TRUE):
1. CachyOS available as Opening Statement
2. Pure Arch and EndeavourOS available as Opening Statements
3. Omarchy opinions (theming, apps, configs) mapped to overlays
4. Hyprland, Sway, and i3 available as Platform overlays
5. KDE Plasma, COSMIC, and GNOME available as Platform overlays
6. User can select any base distribution and combine with any compatible platform
7. Each platform includes working configuration that boots successfully
**Plans**: TBD
Plans:
- [ ] 09-01: TBD (during phase planning)
## Progress
**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Core Infrastructure & Security | 0/TBD | Not started | - |
| 2. Overlay System Foundation | 0/TBD | Not started | - |
| 3. Build Queue & Workers | 0/TBD | Not started | - |
| 4. User Accounts | 0/TBD | Not started | - |
| 5. Builder Interface (2D) | 0/TBD | Not started | - |
| 6. Speeches & Community | 0/TBD | Not started | - |
| 7. 3D Visualization | 0/TBD | Not started | - |
| 8. Advanced Dependency Resolution | 0/TBD | Not started | - |
| 9. Distribution Content | 0/TBD | Not started | - |

67
.planning/STATE.md Normal file
View file

@ -0,0 +1,67 @@
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 2026-01-25)
**Core value:** Make Linux customization visual and accessible to people who aren't Linux experts
**Current focus:** Phase 1 - Core Infrastructure & Security
## Current Position
Phase: 1 of 9 (Core Infrastructure & Security)
Plan: 0 of TBD in current phase
Status: Ready to plan
Last activity: 2026-01-25 - Roadmap created with 9 phases
Progress: [░░░░░░░░░░] 0%
## Performance Metrics
**Velocity:**
- Total plans completed: 0
- Average duration: N/A
- Total execution time: 0 hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
**Recent Trend:**
- Last 5 plans: N/A
- Trend: N/A
*Updated after each plan completion*
## Accumulated Context
### Decisions
Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:
- [Roadmap]: 9-phase structure following research recommendations - infrastructure first, then backend systems, then user features, then polish
### Pending Todos
None yet.
### Blockers/Concerns
**Phase 1 readiness:**
- Research suggests systemd-nspawn for build sandboxing - need to validate compatibility with archiso
- Deterministic builds require SOURCE_DATE_EPOCH and fixed locales - verify archiso supports these configurations
**Phase 7 readiness:**
- 3D visualization requires 60fps target on Intel UHD Graphics - may need early performance prototyping
**Phase 8 readiness:**
- SAT solver integration complexity is high - research phase recommended before planning
## Session Continuity
Last session: 2026-01-25 (roadmap creation)
Stopped at: Initial roadmap and state files created
Resume file: None