ae4833e310
- Introduced new planning files including PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and STATE.md to outline the vision and requirements for SSH multi-context workspaces. - Added ARCHITECTURE.md and CONCERNS.md to detail the codebase structure and address technical debt, known bugs, and security considerations. - Created CONVENTIONS.md to establish coding standards and practices for the project. - Updated .gitignore to exclude demo files and added configuration for planning tools. This commit lays the groundwork for enhancing SSH functionality and user experience in managing multiple workspaces.
114 lines
4.9 KiB
Markdown
114 lines
4.9 KiB
Markdown
# Requirements: SSH Multi-Context Workspaces
|
|
|
|
**Defined:** 2026-02-12
|
|
**Core Value:** Users can seamlessly switch between local and SSH workspaces without losing state, and SSH sessions actually load their conversation history.
|
|
|
|
## v1 Requirements
|
|
|
|
Requirements for initial release. Each maps to roadmap phases.
|
|
|
|
### Provider Plumbing
|
|
|
|
- [ ] **PROV-01**: SSH sessions display full conversation history (fix FileSystemProvider plumbing through SessionParser)
|
|
- [ ] **PROV-02**: SSH subagent drill-down loads correctly over SFTP (fix SubagentResolver and SubagentDetailBuilder provider plumbing)
|
|
|
|
### Service Context Management
|
|
|
|
- [ ] **SCTX-01**: ServiceContextRegistry manages local + N SSH service contexts with getActive/switch/create/destroy lifecycle
|
|
- [ ] **SCTX-02**: Local service context is always alive and never destroyed on SSH connect/disconnect
|
|
- [ ] **SCTX-03**: Each SSH context has independent services (ProjectScanner, SessionParser, SubagentResolver, ChunkBuilder, DataCache, FileWatcher)
|
|
- [ ] **SCTX-04**: All services implement dispose() for proper cleanup (EventEmitter listeners, timers, SSH connections)
|
|
- [ ] **SCTX-05**: IPC requests are stamped with context ID to prevent race conditions during rapid switching
|
|
|
|
### IPC Context API
|
|
|
|
- [ ] **IPC-01**: Context management IPC channels exist (context:list, context:switch, context:connect-ssh, context:disconnect-ssh, context:destroy)
|
|
- [ ] **IPC-02**: Preload exposes context API to renderer (window.electronAPI.context)
|
|
- [ ] **IPC-03**: File watcher events are scoped to active context only
|
|
|
|
### State Snapshot/Restore
|
|
|
|
- [ ] **SNAP-01**: Full Zustand state snapshot captured on context switch (projects, sessions, tabs, pane layout, selections, notifications)
|
|
- [ ] **SNAP-02**: Switching to a previously visited context restores exact state instantly (no refetch)
|
|
- [ ] **SNAP-03**: Switching to a never-visited context shows empty/skeleton state (not stale local data)
|
|
- [ ] **SNAP-04**: Loading overlay displayed during context switch to prevent stale data flash
|
|
- [ ] **SNAP-05**: Context snapshots persist to IndexedDB (survive app restart)
|
|
|
|
### Workspace UI
|
|
|
|
- [ ] **WSUI-01**: Context switcher dropdown in sidebar lists Local + connected SSH workspaces
|
|
- [ ] **WSUI-02**: Status bar indicator shows active workspace name and connection status
|
|
- [ ] **WSUI-03**: Connection status indicators display connected/connecting/disconnected/error states
|
|
- [ ] **WSUI-04**: SSH connection profiles can be saved, edited, and deleted in settings
|
|
- [ ] **WSUI-05**: Keyboard shortcuts available for switching between workspaces
|
|
|
|
## v2 Requirements
|
|
|
|
Deferred to future release. Tracked but not in current roadmap.
|
|
|
|
### Enhanced UX
|
|
|
|
- **WSUI-06**: Color-coded workspace indicators per SSH connection
|
|
- **WSUI-07**: Fuzzy search in workspace switcher for quick filtering
|
|
- **WSUI-08**: Auto-reconnect with exponential backoff on SSH disconnect
|
|
- **WSUI-09**: Workspace health metrics (latency, connection uptime)
|
|
|
|
### Advanced Capabilities
|
|
|
|
- **ADV-01**: Parallel workspace windows (view two workspaces simultaneously)
|
|
- **ADV-02**: Cross-context session comparison (local vs remote side-by-side)
|
|
- **ADV-03**: Workspace groups (organize related SSH connections)
|
|
|
|
## Out of Scope
|
|
|
|
| Feature | Reason |
|
|
|---------|--------|
|
|
| SFTP performance optimization | Investigating separately after workspace switching works |
|
|
| SSH key management UI | Use system SSH keys, not app-managed |
|
|
| Multi-window side-by-side workspaces | v2+ complexity; current model is one-at-a-time switching |
|
|
| Mobile/responsive layout | Desktop-only app |
|
|
| BroadcastChannel multi-window sync | Single window for v1; multi-window is v2+ |
|
|
| Offline-first workspace caching | Would require conflict resolution strategy; defer |
|
|
|
|
## Traceability
|
|
|
|
Which phases cover which requirements. Updated during roadmap creation.
|
|
|
|
| Requirement | Phase | Status |
|
|
|-------------|-------|--------|
|
|
| PROV-01 | Phase 1 | Pending |
|
|
| PROV-02 | Phase 1 | Pending |
|
|
| SCTX-01 | Phase 2 | Pending |
|
|
| SCTX-02 | Phase 2 | Pending |
|
|
| SCTX-03 | Phase 2 | Pending |
|
|
| SCTX-04 | Phase 2 | Pending |
|
|
| SCTX-05 | Phase 2 | Pending |
|
|
| IPC-01 | Phase 2 | Pending |
|
|
| IPC-02 | Phase 2 | Pending |
|
|
| IPC-03 | Phase 2 | Pending |
|
|
| SNAP-01 | Phase 3 | Pending |
|
|
| SNAP-02 | Phase 3 | Pending |
|
|
| SNAP-03 | Phase 3 | Pending |
|
|
| SNAP-04 | Phase 3 | Pending |
|
|
| SNAP-05 | Phase 3 | Pending |
|
|
| WSUI-01 | Phase 4 | Pending |
|
|
| WSUI-02 | Phase 4 | Pending |
|
|
| WSUI-03 | Phase 4 | Pending |
|
|
| WSUI-04 | Phase 4 | Pending |
|
|
| WSUI-05 | Phase 4 | Pending |
|
|
|
|
**Coverage:**
|
|
- v1 requirements: 20 total
|
|
- Mapped to phases: 20
|
|
- Unmapped: 0
|
|
|
|
**Validation:**
|
|
- Phase 1: 2 requirements (PROV-01, PROV-02)
|
|
- Phase 2: 8 requirements (SCTX-01 through SCTX-05, IPC-01 through IPC-03)
|
|
- Phase 3: 5 requirements (SNAP-01 through SNAP-05)
|
|
- Phase 4: 5 requirements (WSUI-01 through WSUI-05)
|
|
- Total: 20 requirements mapped
|
|
|
|
---
|
|
*Requirements defined: 2026-02-12*
|
|
*Last updated: 2026-02-12 after roadmap creation (traceability complete)*
|