Initial commit: Clean DSS implementation

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
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
--- a/.dss/WORKFLOWS/README.md
+++ b/.dss/WORKFLOWS/README.md
@@ -0,0 +1,262 @@
+# DSS Debug Workflows
+
+**Purpose**: Step-by-step procedures for common debugging tasks in Design System Swarm
+
+**How to Use**: Each workflow is a standalone markdown document with:
+- Clear prerequisites
+- Step-by-step instructions with console commands
+- Expected results for each step
+- Troubleshooting guidance
+- Success criteria
+
+---
+
+## Available Workflows
+
+### [01 - Capture Browser Logs](01-capture-browser-logs.md)
+**Purpose**: Capture and retrieve all browser-side logs from DSS dashboard
+
+**When to Use**:
+- User reports dashboard not loading
+- JavaScript errors in browser
+- Network request failures
+- Performance issues
+
+**Estimated Time**: 2-5 minutes
+
+**Key Steps**:
+1. Open dashboard and DevTools
+2. Verify browser logger loaded
+3. Get diagnostic summary
+4. Retrieve specific log types
+5. Export logs for analysis
+
+---
+
+### [02 - Diagnose Errors](02-diagnose-errors.md)
+**Purpose**: Systematically diagnose and resolve errors in DSS dashboard and API
+
+**When to Use**:
+- Dashboard displays error messages
+- API requests failing
+- Server health check shows degraded status
+- User reports functionality not working
+
+**Estimated Time**: 10-30 minutes
+
+**Key Steps**:
+1. Identify error scope (browser/API/database/system)
+2. Diagnose browser-side errors
+3. Diagnose API-side errors
+4. Diagnose database errors
+5. Diagnose system-wide issues
+6. Verify fix
+
+---
+
+### [03 - Debug Performance](03-debug-performance.md)
+**Purpose**: Diagnose and resolve performance issues in DSS dashboard and API
+
+**When to Use**:
+- Dashboard loads slowly
+- API requests taking too long
+- Browser becomes unresponsive
+- High memory usage warnings
+
+**Estimated Time**: 15-45 minutes
+
+**Key Steps**:
+1. Gather performance baseline
+2. Diagnose slow page load
+3. Diagnose slow API requests
+4. Diagnose memory leaks
+5. Diagnose CPU bottlenecks
+6. Server-side performance check
+
+---
+
+### [04 - Workflow Debugging](04-workflow-debugging.md)
+**Purpose**: Debug the workflow system itself and MCP tool integration
+
+**When to Use**:
+- Workflow execution fails
+- MCP tools not responding
+- API endpoints returning errors
+- Communication between layers broken
+
+**Estimated Time**: 10-20 minutes
+
+**Key Steps**:
+1. Verify all services running
+2. Test each layer independently
+3. Test data flow end-to-end
+4. Debug common workflow issues
+5. Verify workflow execution
+6. Check persistence (supervisord)
+
+---
+
+## Quick Reference
+
+### Access from Command Line
+```bash
+# View workflow list
+ls -1 /home/overbits/dss/.dss/WORKFLOWS/*.md
+
+# Read a workflow
+cat /home/overbits/dss/.dss/WORKFLOWS/01-capture-browser-logs.md
+
+# Quick hook for browser logs
+/home/overbits/dss/.dss/GET_BROWSER_LOGS.sh
+```
+
+### Access from API
+```bash
+# List workflows
+curl http://localhost:3456/api/debug/workflows
+
+# Execute workflow (when implemented)
+curl -X POST http://localhost:3456/api/debug/workflows/01-capture-browser-logs
+```
+
+### Access from MCP (Claude Code)
+```
+Use tool: dss_list_workflows
+Use tool: dss_run_workflow with workflow_name="01-capture-browser-logs"
+```
+
+---
+
+## Workflow Categories
+
+### User-Facing Issues
+- **01 - Capture Browser Logs**: First step for any dashboard issue
+- **02 - Diagnose Errors**: When specific errors occur
+
+### Performance Issues
+- **03 - Debug Performance**: Slow loading, high memory, CPU bottlenecks
+
+### System Issues
+- **04 - Workflow Debugging**: When the debug tools themselves fail
+
+---
+
+## Architecture Context
+
+These workflows operate within the 3-layer debug architecture:
+
+```
+┌──────────────────────────────────────────┐
+│ Layer 1: Browser (JavaScript)            │
+│  - browser-logger.js captures logs       │
+│  - window.__DSS_BROWSER_LOGS API         │
+└──────────────────────────────────────────┘
+                   ↓
+┌──────────────────────────────────────────┐
+│ Layer 2: API Server (FastAPI)            │
+│  - /api/browser-logs endpoints           │
+│  - /api/debug/* endpoints                │
+└──────────────────────────────────────────┘
+                   ↓
+┌──────────────────────────────────────────┐
+│ Layer 3: MCP Server (Python/MCP)         │
+│  - dss_get_browser_diagnostic            │
+│  - dss_get_browser_errors                │
+│  - dss_run_workflow                      │
+└──────────────────────────────────────────┘
+```
+
+See `.dss/MCP_DEBUG_TOOLS_ARCHITECTURE.md` for complete architecture details.
+
+---
+
+## Development Guide
+
+### Creating New Workflows
+
+1. **Choose Number**: Next sequential number (05, 06, etc.)
+2. **Create File**: `.dss/WORKFLOWS/NN-workflow-name.md`
+3. **Use Template**: See workflow 04 for template structure
+4. **Include**:
+   - Purpose and when to use
+   - Prerequisites
+   - Step-by-step instructions with commands
+   - Expected results for each step
+   - Troubleshooting guidance
+   - Success criteria
+   - Related documentation
+5. **Test**: Run through workflow manually
+6. **Refine**: Update based on actual experience
+7. **Restart API**: To load new workflow in system
+
+### Workflow Template Structure
+```markdown
+# Workflow NN: Title
+
+**Purpose**: Brief description
+**When to Use**: Scenarios
+**Estimated Time**: X-Y minutes
+
+---
+
+## Prerequisites
+- Required items
+
+---
+
+## Step-by-Step Procedure
+
+### Step 1: Title
+**Action**: Commands or actions
+**Expected Result**: What should happen
+**Troubleshooting**: If issues occur
+
+---
+
+## Success Criteria
+- ✅ Checkpoints
+
+---
+
+## Related Documentation
+- Links to related docs
+```
+
+---
+
+## Maintenance
+
+### Regular Testing
+- Run workflow 04 monthly to verify system health
+- Update workflows when architecture changes
+- Add new workflows for recurring issues
+
+### Update Triggers
+- New debug tools added
+- Architecture changes
+- New common issues discovered
+- User feedback on workflows
+
+---
+
+## Related Documentation
+
+- `.dss/MCP_DEBUG_TOOLS_ARCHITECTURE.md` - Complete MCP integration architecture
+- `.dss/BROWSER_LOG_CAPTURE_PROCEDURE.md` - Browser logger details
+- `.dss/GET_BROWSER_LOGS.sh` - Quick reference hook
+- `.dss/DSS_DIAGNOSTIC_REPORT_20251206.md` - Example diagnostic report
+- `.dss/DEBUG_SESSION_SUMMARY.md` - Previous debug session
+
+---
+
+## Implementation Status
+
+- ✅ **Workflow 01**: Capture Browser Logs - Complete
+- ✅ **Workflow 02**: Diagnose Errors - Complete
+- ✅ **Workflow 03**: Debug Performance - Complete
+- ✅ **Workflow 04**: Workflow Debugging - Complete
+- ⏳ **API Integration**: Endpoints need implementation
+- ⏳ **MCP Integration**: Tools need implementation
+- ⏳ **Supervisord**: Service configs need creation
+
+See architecture doc for full implementation checklist.