Skip to content
This repository was archived by the owner on Sep 23, 2025. It is now read-only.

Commit e7b2342

Browse files
committed
Add comprehensive RFC structure for unified Socratic Shell installation
- Create main RFC for VSCode extension centralized installation approach - Add MCP server implementation details with Rust orchestrator design - Document hook system for AI tool lifecycle integration - Specify git subtree strategy for multi-language component coordination - Update SUMMARY.md to include all new RFCs Addresses planning phase of issue #16
1 parent eac39fb commit e7b2342

File tree

5 files changed

+807
-0
lines changed

5 files changed

+807
-0
lines changed

src/SUMMARY.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,13 @@
3333

3434
- [Introduction](./dialectic/README.md)
3535

36+
# RFCs for in-progress features
37+
38+
- [RFC: Socratic Shell VSCode extension for centralized installation and configuration](./rfcs/vscode-extension/README.md) <!-- Answers: overall goals and outlines the high-level implementation details -->
39+
- [Repository coordination and bundling](./rfcs/vscode-extension/repo-coordination.md) <!-- Answers: how to coordinate multi-language components using git subtrees and automated syncing -->
40+
- [MCP server](./rfcs/vscode-extension/mcp-server.md) <!-- Answers: details about how the MCP server will be implemented, how delegation will work -->
41+
- [Hooks](./rfcs/vscode-extension/hooks.md) <!-- Answers: details about which hooks we will make use of and how -->
42+
3643
# Appendices
3744

3845
- [Insights](./insights/README.md)
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# RFC: Socratic Shell VSCode Extension for Centralized Installation and Configuration
2+
3+
> **Tracking Issue**: [#16 - Implement unified Socratic Shell installation and MCP server](https://github.com/socratic-shell/socratic-shell/issues/16)
4+
5+
## Problem Statement
6+
7+
Socratic Shell currently exists as a collection of separate tools and documentation patterns that require manual setup and configuration. Users must:
8+
- Manually install and configure multiple MCP servers (hippo, dialectic)
9+
- Set up context injection for their AI tools
10+
- Configure hooks and integrations
11+
- Understand complex multi-tool interactions
12+
13+
This creates a high barrier to entry and limits adoption.
14+
15+
## Goals
16+
17+
Transform Socratic Shell from a collection of tools into a cohesive collaborative AI environment that "just works out of the box" through:
18+
19+
1. **Single Installation Point**: VSCode extension as the primary distribution mechanism
20+
2. **Unified MCP Interface**: One MCP server that orchestrates all Socratic Shell capabilities
21+
3. **Guided Setup**: UI-driven configuration that adapts to user's AI tool (Claude Code, Q CLI)
22+
4. **Complete Integration**: Automatic context injection, hook setup, and lifecycle management
23+
24+
## High-Level Architecture
25+
26+
### Components
27+
28+
**VSCode Extension (Control Plane)**
29+
- Installation orchestration and UI guidance
30+
- Lifecycle management of background services
31+
- Platform detection and binary selection
32+
- Configuration management
33+
34+
**Socratic Shell MCP Server (Rust Binary)**
35+
- Unified MCP interface for AI tools
36+
- Request routing to backend services
37+
- Process management for backend MCP servers
38+
- Hook execution (conversation-start, per-prompt)
39+
40+
**Backend MCP Servers**
41+
- `hippo-standalone` (Python executable) - memory operations
42+
- `dialectic-server` (TypeScript bundle) - code review and file operations
43+
- Future components as separate MCP servers
44+
45+
### Distribution Strategy
46+
47+
**Multi-Binary Bundling**
48+
```
49+
socratic-shell-extension/
50+
├── binaries/
51+
│ ├── windows-x64/
52+
│ ├── darwin-x64/
53+
│ ├── darwin-arm64/
54+
│ └── linux-x64/
55+
├── dialectic/ (TypeScript bundle)
56+
└── extension.js
57+
```
58+
59+
**Installation Flow**
60+
1. User installs VSCode extension from marketplace
61+
2. Extension detects platform and AI tool configuration
62+
3. UI guides user through setup choices
63+
4. Extension configures MCP connections and hooks
64+
5. Background services start automatically
65+
66+
## Key Design Decisions
67+
68+
### Why VSCode Extension as Primary Distribution?
69+
- Single install point with cross-platform support
70+
- Built-in UI capabilities for guided setup
71+
- Natural integration with dialectic (already VSCode-focused)
72+
- Handles binary distribution and lifecycle management
73+
74+
### Why Rust for Main MCP Server?
75+
- Single static binary (easy bundling)
76+
- Minimal resource overhead for orchestration
77+
- Excellent process management and IPC capabilities
78+
- Good cross-platform support
79+
80+
### Why Multi-Binary vs Universal Binary?
81+
- Proven Rust cross-compilation toolchain
82+
- Avoids experimental dependencies (cosmopolitan)
83+
- Predictable behavior across platforms
84+
- Standard CI/CD pipeline support
85+
86+
### Why Bundle All Binaries Initially?
87+
- Simplest installation experience ("just works offline")
88+
- Eliminates network dependency failures
89+
- Can optimize with lazy download later if size becomes issue
90+
91+
## Implementation Phases
92+
93+
### Phase 1: Core Infrastructure
94+
- Rust MCP server with basic routing
95+
- VSCode extension with platform detection
96+
- Multi-platform build pipeline
97+
- Basic backend server integration (hippo, dialectic)
98+
99+
### Phase 2: Installation Experience
100+
- Guided setup UI in VSCode extension
101+
- AI tool detection and configuration
102+
- Context injection mechanisms
103+
- Hook system integration
104+
105+
### Phase 3: Enhanced Features
106+
- Canned prompts/tools for common operations
107+
- Project-specific setup automation
108+
- Advanced lifecycle management
109+
- Performance optimizations
110+
111+
## Open Questions
112+
113+
1. **Hook Integration Points**: Where exactly do we plug into Claude Code vs Q CLI lifecycle events?
114+
2. **Context Injection Mechanics**: How do we reliably inject prompts into different AI tool contexts?
115+
3. **Backend Server Lifecycle**: Start/stop on demand vs keep-alive strategies?
116+
4. **Configuration Management**: How do we handle updates and version compatibility?
117+
5. **Error Handling**: How do we provide good diagnostics when components fail?
118+
119+
## Success Criteria
120+
121+
- New user can install and use Socratic Shell in under 5 minutes
122+
- Single VSCode extension provides complete Socratic Shell experience
123+
- Works reliably across Windows, macOS, and Linux
124+
- Extensible architecture supports future Socratic Shell components
125+
- Maintains performance characteristics of individual tools
126+
127+
## Related RFCs
128+
129+
- [MCP Server Implementation Details](./mcp-server.md)
130+
- [Hook System Design](./hooks.md)
131+
- [Repository Coordination and Multi-Language Bundling](./repo-coordination.md)

0 commit comments

Comments
 (0)