admin-valentin/agent-ecosystem
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agent-ecosystem/.planning/REQUIREMENTS.md
matt ae4833e310 feat(planning): add project planning documents and configuration for SSH multi-context workspaces 
- 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.
2026-02-12 09:37:58 +09:00

4.9 KiB
Raw Blame History

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)