276ed71f31
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
442 lines
14 KiB
Markdown
442 lines
14 KiB
Markdown
# DSS PowerTools: Adaptive Plugin Architecture
|
|
|
|
**Unified LOCAL/REMOTE Design System Development Tools**
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
**Vision**: A single Claude Code plugin that gives developers "superpowers" for design system work in both LOCAL (direct machine access) and REMOTE (server-based) modes.
|
|
|
|
**Key Innovation**: Adaptive Strategy Pattern that provides identical UX while routing to mode-specific implementations.
|
|
|
|
**Timeline**: 20 days (4 weeks)
|
|
|
|
**Current Assets**:
|
|
- Browser-logger.js with auto-sync (DONE)
|
|
- API server with browser log endpoints (DONE)
|
|
- Debug MCP tools (DONE)
|
|
- Task queue integration (DONE)
|
|
- dss-claude-plugin structure (EXISTS)
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ DSS PowerTools Plugin │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────────┐ │
|
|
│ │ Core Foundation │ │
|
|
│ │ - DSSConfig (mode detection) │ │
|
|
│ │ - DSSContext (singleton, capabilities) │ │
|
|
│ │ - Strategy Registry (factory pattern) │ │
|
|
│ └────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌────────────────┴────────────────┐ │
|
|
│ │ │ │
|
|
│ ┌──────▼──────┐ ┌──────▼──────┐ │
|
|
│ │ LOCAL Mode │ │ REMOTE Mode │ │
|
|
│ │ │ │ │ │
|
|
│ │ Playwright │ │ HTTP API │ │
|
|
│ │ CDP │ │ Browser-Log │ │
|
|
│ │ Filesystem │ │ Shadow State│ │
|
|
│ │ Screenshots │ │ Server API │ │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
│ │
|
|
│ Same Commands │ Different Implementations │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Mode Comparison
|
|
|
|
| Feature | LOCAL Mode | REMOTE Mode |
|
|
|---------|------------|-------------|
|
|
| **Browser Access** | Chrome DevTools Protocol (CDP) | browser-logger.js auto-sync |
|
|
| **Screenshots** | Playwright (local capture) | Server-side Playwright API |
|
|
| **File Access** | Direct filesystem | Upload to API / Git sync |
|
|
| **Storybook** | localhost:6006 | Server-hosted instance |
|
|
| **Real-time Debug** | Live CDP connection | Historical logs + Shadow State |
|
|
| **Setup Complexity** | Chrome with --remote-debugging-port | Just network access |
|
|
| **Offline Support** | Full functionality | Limited to cached data |
|
|
| **Best For** | Active development | Code review, monitoring, remote teams |
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Core Foundation (Days 1-3)
|
|
|
|
**Objective**: Build mode-aware infrastructure without breaking existing functionality
|
|
|
|
**Day 1**: Mode Detection
|
|
```python
|
|
# dss-claude-plugin/core/config.py
|
|
class DSSConfig(BaseModel):
|
|
mode: Literal["local", "remote", "auto"] = "auto"
|
|
|
|
@classmethod
|
|
async def detect_mode(cls):
|
|
# 1. Check DSS_MODE env var
|
|
# 2. Check ~/.dss/config.json
|
|
# 3. Ping localhost:6006 (API health)
|
|
# 4. Default to "remote" (safer)
|
|
```
|
|
|
|
**Day 2**: Context Manager
|
|
```python
|
|
# dss-claude-plugin/core/context.py
|
|
class DSSContext:
|
|
_instance = None # Singleton
|
|
|
|
async def initialize(self):
|
|
self.mode = await DSSConfig.detect_mode()
|
|
await self._verify_capabilities()
|
|
|
|
def get_strategy(self, strategy_type: str):
|
|
# Factory: returns LOCAL or REMOTE strategy
|
|
```
|
|
|
|
**Day 3**: Strategy Interfaces
|
|
```python
|
|
# dss-claude-plugin/strategies/base.py
|
|
class BrowserStrategy(ABC):
|
|
@abstractmethod
|
|
async def get_console_logs(...) -> List[Dict]: ...
|
|
|
|
@abstractmethod
|
|
async def capture_screenshot(...) -> str: ...
|
|
|
|
@abstractmethod
|
|
async def get_dom_snapshot() -> str: ...
|
|
```
|
|
|
|
**Deliverables**:
|
|
- [ ] config.py with mode detection (80% test coverage)
|
|
- [ ] context.py singleton with capabilities
|
|
- [ ] base.py with all strategy ABCs
|
|
- [ ] Unit tests passing
|
|
|
|
---
|
|
|
|
### Phase 2: LOCAL Mode Implementation (Days 4-7)
|
|
|
|
**Objective**: Enable local development superpowers
|
|
|
|
**Key Technologies**:
|
|
- Playwright (browser automation)
|
|
- Chrome DevTools Protocol (real-time access)
|
|
- Direct filesystem access
|
|
|
|
**Day 4-5**: Playwright Integration
|
|
```python
|
|
# strategies/local/browser.py
|
|
class LocalBrowserStrategy(BrowserStrategy):
|
|
async def connect(self):
|
|
# Connect to localhost:9222 (Chrome CDP)
|
|
p = await async_playwright().start()
|
|
self.browser = await p.chromium.connect_over_cdp("localhost:9222")
|
|
|
|
async def capture_screenshot(self, selector=None):
|
|
# Capture directly from local browser
|
|
path = Path.home() / ".dss" / "screenshots" / f"{uuid.uuid4()}.png"
|
|
await self.page.screenshot(path=str(path))
|
|
return str(path)
|
|
```
|
|
|
|
**Day 6-7**: Testing & Filesystem Strategy
|
|
|
|
**Deliverables**:
|
|
- [ ] Playwright browser control working
|
|
- [ ] CDP real-time console access
|
|
- [ ] Local screenshot capture
|
|
- [ ] Filesystem scanning strategy
|
|
|
|
---
|
|
|
|
### Phase 3: REMOTE Mode Implementation (Days 8-12)
|
|
|
|
**Objective**: Leverage existing browser-logger.js and create Shadow State
|
|
|
|
**Key Innovation from Gemini 3 Pro**: "Shadow State Pattern"
|
|
- Browser captures DOM snapshots on errors/navigation
|
|
- Server stores snapshots alongside logs
|
|
- Tools query "most recent state" like it's real-time
|
|
|
|
**Day 8-10**: Shadow State Implementation
|
|
```javascript
|
|
// admin-ui/js/core/browser-logger.js (enhancement)
|
|
class BrowserLogger {
|
|
captureDOMSnapshot() {
|
|
return {
|
|
html: document.documentElement.outerHTML,
|
|
url: window.location.href,
|
|
timestamp: Date.now(),
|
|
viewport: {width: window.innerWidth, height: window.innerHeight}
|
|
};
|
|
}
|
|
|
|
setupSnapshotCapture() {
|
|
// On error: immediate snapshot + sync
|
|
window.addEventListener('error', () => {
|
|
this.log('snapshot', 'error', 'DOM Snapshot', {
|
|
snapshot: this.captureDOMSnapshot()
|
|
});
|
|
this.syncToServer(); // Beacon for reliability
|
|
});
|
|
|
|
// On navigation: capture new state
|
|
let lastUrl = location.href;
|
|
setInterval(() => {
|
|
if (location.href !== lastUrl) {
|
|
lastUrl = location.href;
|
|
this.log('snapshot', 'navigation', 'Page Changed', {
|
|
snapshot: this.captureDOMSnapshot()
|
|
});
|
|
}
|
|
}, 1000);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Day 11-12**: Remote Strategy Implementation
|
|
```python
|
|
# strategies/remote/browser.py
|
|
class RemoteBrowserStrategy(BrowserStrategy):
|
|
async def get_console_logs(self, session_id=None):
|
|
# Query API for browser logs
|
|
url = f"{self.api_url}/api/browser-logs/{session_id or 'latest'}"
|
|
resp = await self.client.get(url)
|
|
return resp.json().get("logs", [])
|
|
|
|
async def get_dom_snapshot(self):
|
|
# Get Shadow State (most recent snapshot)
|
|
logs = await self.get_console_logs()
|
|
snapshots = [l for l in logs if l.get("category") == "snapshot"]
|
|
if snapshots:
|
|
return snapshots[-1]["data"]["snapshot"]["html"]
|
|
return "<html><body>No snapshot available</body></html>"
|
|
```
|
|
|
|
**Deliverables**:
|
|
- [ ] Shadow State working in browser-logger.js
|
|
- [ ] DOM snapshots captured on errors/navigation
|
|
- [ ] Remote strategy fetching logs via API
|
|
- [ ] Server-side screenshot API endpoint (NEW)
|
|
|
|
---
|
|
|
|
### Phase 4: Unified Commands & Testing (Days 13-16)
|
|
|
|
**Objective**: Make all commands mode-aware with seamless UX
|
|
|
|
**Day 13**: Command Unification
|
|
```python
|
|
# Example: /dss-screenshot command
|
|
async def handle_screenshot(args):
|
|
ctx = await DSSContext.get_instance()
|
|
|
|
# Get strategy for current mode
|
|
browser_strategy = ctx.get_strategy("browser")
|
|
|
|
# Same interface, different implementation
|
|
screenshot = await browser_strategy.capture_screenshot(
|
|
selector=args.get("selector"),
|
|
full_page=args.get("fullpage", False)
|
|
)
|
|
|
|
return {
|
|
"mode": ctx.mode,
|
|
"screenshot": screenshot, # Local path OR remote URL
|
|
"capabilities": ctx.capabilities
|
|
}
|
|
```
|
|
|
|
**Day 14**: New Management Commands
|
|
- `/dss-config set local|remote` - Change mode
|
|
- `/dss-config get` - Show current mode & capabilities
|
|
- `/dss-status` - Health check for current mode
|
|
|
|
**Day 15-16**: Integration Testing
|
|
|
|
**Test Matrix**:
|
|
| Test Scenario | LOCAL | REMOTE |
|
|
|--------------|-------|---------|
|
|
| Screenshot | Playwright | Server API |
|
|
| Console logs | CDP | browser-logger.js |
|
|
| Token extract | Filesystem | API upload |
|
|
| DOM snapshot | CDP live | Shadow State |
|
|
| Mode switch | Config change | Config change |
|
|
|
|
**Deliverables**:
|
|
- [ ] All commands mode-aware
|
|
- [ ] `/dss-config` and `/dss-status` working
|
|
- [ ] 90%+ test coverage
|
|
- [ ] Integration tests passing
|
|
|
|
---
|
|
|
|
### Phase 5: Multi-Agent Zen Challenge (Days 17-20)
|
|
|
|
**Objective**: Create compelling multi-agent collaboration scenario
|
|
|
|
**Challenge Name**: "Cross-Reality Design System Audit"
|
|
|
|
**Scenario**: Audit design system across 3 environments:
|
|
1. Local Development (LOCAL mode)
|
|
2. Staging Server (REMOTE mode)
|
|
3. Production (REMOTE mode)
|
|
|
|
**Agent Roles**:
|
|
1. **Architect** - Plans audit strategy
|
|
2. **Local Scout** - Audits local (LOCAL mode)
|
|
3. **Staging Inspector** - Audits staging (REMOTE mode)
|
|
4. **Production Monitor** - Monitors prod (REMOTE mode)
|
|
5. **Synthesizer** - Combines findings, creates report
|
|
|
|
**Challenge Flow**:
|
|
```
|
|
Architect (Planning)
|
|
|
|
|
v
|
|
┌─┴─┬─────┬─────┐
|
|
| | | |
|
|
Local Staging Prod Monitor
|
|
Scout Inspector (Remote)
|
|
| | |
|
|
└─┬─┴─────┘
|
|
|
|
|
v
|
|
Synthesizer (Report)
|
|
```
|
|
|
|
**Collaboration Mechanism**:
|
|
- Agents share session IDs via task-queue
|
|
- Screenshots stored centrally
|
|
- Token discrepancies flagged
|
|
- Console errors deduplicated
|
|
- Final report synthesizes all findings
|
|
|
|
**Deliverables**:
|
|
- [ ] Challenge file: `challenges/cross-reality-audit.md`
|
|
- [ ] Test with 5 real agents
|
|
- [ ] Documentation: `docs/MULTI-AGENT-COLLABORATION.md`
|
|
- [ ] Example scenarios
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
**Technical Excellence**:
|
|
- Mode switching < 2 seconds
|
|
- Zero breaking changes
|
|
- 90%+ test coverage
|
|
- All async-compatible
|
|
|
|
**Developer Experience**:
|
|
- Commands work identically in both modes
|
|
- Clear status indicators
|
|
- Helpful error messages
|
|
- Seamless migration
|
|
|
|
**Multi-Agent Capability**:
|
|
- 5 agents collaborate across modes
|
|
- Session IDs enable data sharing
|
|
- Task queue integration works
|
|
- Reports are comprehensive
|
|
|
|
---
|
|
|
|
## Risk Register
|
|
|
|
| Risk | Impact | Mitigation |
|
|
|------|--------|------------|
|
|
| Playwright install fails | HIGH | Graceful degradation, clear docs |
|
|
| Mode detection ambiguous | MEDIUM | Prompt user, default REMOTE |
|
|
| Shadow State too slow | LOW | Async capture, size limits |
|
|
| API breaking changes | HIGH | Feature flags, versioning |
|
|
| CDP port conflicts | LOW | Configurable port, auto-detect |
|
|
|
|
---
|
|
|
|
## First Steps (Day 1)
|
|
|
|
**Morning**:
|
|
1. Create `dss-claude-plugin/core/` directory
|
|
2. Implement `config.py` with mode detection
|
|
3. Write unit tests for config
|
|
4. Test with environment variables
|
|
|
|
**Afternoon**:
|
|
5. Implement `context.py` singleton
|
|
6. Add capability verification
|
|
7. Test capability caching
|
|
8. Document context lifecycle
|
|
|
|
---
|
|
|
|
## Documentation Plan
|
|
|
|
**Architecture Docs**:
|
|
- `ARCHITECTURE.md` - System design
|
|
- `STRATEGY-PATTERN.md` - Implementation details
|
|
- `MODE-DETECTION.md` - How mode is chosen
|
|
|
|
**User Guides**:
|
|
- `GETTING-STARTED.md` - Quick start
|
|
- `LOCAL-MODE.md` - LOCAL setup & usage
|
|
- `REMOTE-MODE.md` - REMOTE setup & usage
|
|
- `MODE-SWITCHING.md` - How to switch modes
|
|
|
|
**Developer Docs**:
|
|
- `CONTRIBUTING.md` - How to add strategies
|
|
- `TESTING.md` - Test strategy
|
|
- `API.md` - Internal APIs
|
|
|
|
---
|
|
|
|
## Key Insights from Gemini 3 Pro Analysis
|
|
|
|
**1. Impedance Mismatch**
|
|
- LOCAL is query-based (imperative)
|
|
- REMOTE is event-based (historical)
|
|
- Solution: Shadow State bridges the gap
|
|
|
|
**2. Beacon Strategy**
|
|
- Use `navigator.sendBeacon()` for critical logs
|
|
- Ensures data reaches server even during crashes
|
|
- Immediate XHR for errors
|
|
|
|
**3. Session ID Handshake**
|
|
- Browser generates unique session ID
|
|
- MCP server verifies session in API logs (REMOTE)
|
|
- Can connect to CDP and verify page URL (LOCAL)
|
|
- Avoids ambiguous mode detection
|
|
|
|
**4. Evolutionary vs Revolutionary**
|
|
- Better to evolve existing `dss-claude-plugin`
|
|
- Parallel "powertools" plugin adds migration complexity
|
|
- Backward compatibility is key
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
This plan delivers a **unified developer experience** across LOCAL and REMOTE modes while maximizing the capabilities available in each environment. The adaptive architecture enables powerful multi-agent collaboration scenarios that weren't previously possible.
|
|
|
|
**Next Actions**:
|
|
1. Review and approve this plan
|
|
2. Create the full zen challenge file
|
|
3. Begin Phase 1 implementation (Days 1-3)
|
|
4. Iterate based on feedback
|
|
|
|
---
|
|
|
|
**Plan Created**: 2025-12-06
|
|
**Analysis By**: Claude Sonnet 4.5 + Gemini 3 Pro Preview
|
|
**Deep Thinking**: 17 steps, Very High Confidence
|
|
**Planning**: 6 steps, Complete
|