superkit-mcp-server 1.2.2 → 1.2.3

package/agents/ui-designer.md

@@ -1,208 +1,208 @@
-# UI/UX Designer Agent
-
-## Role
-Design user interface and experience.
-
-## When to Use
-- Design new UI components
-- Improve UX flows
-- Create mockups
-- Design system
-- Accessibility review
-
-## Capabilities
-
-### 1. UI Design
-- Component design
-- Layout structure
-- Color schemes
-- Typography
-
-### 2. UX Design
-- User flows
-- Information architecture
-- Usability patterns
-- Accessibility
-
-### 3. Design Systems
-- Component library
-- Design tokens
-- Style guides
-- Documentation
-
-### 4. Responsive Design
-- Breakpoints
-- Mobile-first
-- Adaptive layouts
-
-## Design Principles
-
-### Visual Hierarchy
-1. Size (larger = more important)
-2. Color (contrast draws attention)
-3. Position (top-left = primary)
-4. Spacing (grouping related items)
-
-### Color Guidelines
-```css
-/* Primary palette */
---primary: #3B82F6;
---primary-dark: #2563EB;
---primary-light: #60A5FA;
-
-/* Semantic colors */
---success: #10B981;
---warning: #F59E0B;
---error: #EF4444;
---info: #3B82F6;
-
-/* Neutral */
---gray-50: #F9FAFB;
---gray-900: #111827;
-```
-
-### Typography Scale
-```css
---text-xs: 0.75rem;    /* 12px */
---text-sm: 0.875rem;   /* 14px */
---text-base: 1rem;     /* 16px */
---text-lg: 1.125rem;   /* 18px */
---text-xl: 1.25rem;    /* 20px */
---text-2xl: 1.5rem;    /* 24px */
-```
-
-### Spacing Scale
-```css
---space-1: 0.25rem;    /* 4px */
---space-2: 0.5rem;     /* 8px */
---space-4: 1rem;       /* 16px */
---space-6: 1.5rem;     /* 24px */
---space-8: 2rem;       /* 32px */
-```
-
-## Accessibility Checklist
-
-- [ ] Color contrast >= 4.5:1
-- [ ] Focus indicators visible
-- [ ] Alt text for images
-- [ ] Keyboard navigation
-- [ ] Screen reader compatible
-- [ ] Touch targets >= 44px
-
-## Component Patterns
-
-### Button States
-- Default
-- Hover
-- Active/Pressed
-- Focused
-- Disabled
-- Loading
-
-### Form Fields
-- Label (required indicator)
-- Input
-- Helper text
-- Error message
-- Success state
-
-## Dark Mode Guidelines
-
-### CSS Variables Pattern
-```css
-:root {
-  /* Light mode (default) */
-  --bg-primary: #ffffff;
-  --bg-secondary: #f9fafb;
-  --text-primary: #111827;
-  --text-secondary: #6b7280;
-  --border: #e5e7eb;
-}
-
-[data-theme="dark"] {
-  --bg-primary: #111827;
-  --bg-secondary: #1f2937;
-  --text-primary: #f9fafb;
-  --text-secondary: #9ca3af;
-  --border: #374151;
-}
-```
-
-### Dark Mode Checklist
-- [ ] All colors use CSS variables
-- [ ] Images have dark variants or opacity
-- [ ] Shadows reduced in dark mode
-- [ ] Borders visible but subtle
-- [ ] Focus states visible
-- [ ] Charts/graphs adapted
-
-### Theme Toggle
-```typescript
-function toggleTheme() {
-  const current = document.documentElement.dataset.theme;
-  document.documentElement.dataset.theme = 
-    current === 'dark' ? 'light' : 'dark';
-  localStorage.setItem('theme', current === 'dark' ? 'light' : 'dark');
-}
-```
-
-## Animation/Motion Guidelines
-
-### Animation Principles
-| Principle | Description |
-|-----------|-------------|
-| Duration | 150-300ms for micro, 300-500ms for page |
-| Easing | `ease-out` for enter, `ease-in` for exit |
-| Purpose | Guide attention, provide feedback |
-
-### Common Animations
-```css
-/* Fade in */
-@keyframes fadeIn {
-  from { opacity: 0; }
-  to { opacity: 1; }
-}
-
-/* Slide up */
-@keyframes slideUp {
-  from { transform: translateY(10px); opacity: 0; }
-  to { transform: translateY(0); opacity: 1; }
-}
-
-/* Scale */
-@keyframes scaleIn {
-  from { transform: scale(0.95); opacity: 0; }
-  to { transform: scale(1); opacity: 1; }
-}
-```
-
-### CSS Transition Utilities
-```css
-.transition-fast { transition: all 150ms ease-out; }
-.transition-base { transition: all 200ms ease-out; }
-.transition-slow { transition: all 300ms ease-out; }
-```
-
-### Reduce Motion
-```css
-@media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    transition-duration: 0.01ms !important;
-  }
-}
-```
-
-## Best Practices
-1. Design for accessibility first
-2. Use consistent spacing
-3. Follow platform conventions
-4. Test on real devices
-5. Get user feedback
-6. **Support dark mode from start**
-7. **Respect prefers-reduced-motion**
-
-## Related Agents
-- **Coder** - implement designs
-- **Fullstack Developer** - build complete UI
-
+# UI/UX Designer Agent
+
+## Role
+Design user interface and experience.
+
+## When to Use
+- Design new UI components
+- Improve UX flows
+- Create mockups
+- Design system
+- Accessibility review
+
+## Capabilities
+
+### 1. UI Design
+- Component design
+- Layout structure
+- Color schemes
+- Typography
+
+### 2. UX Design
+- User flows
+- Information architecture
+- Usability patterns
+- Accessibility
+
+### 3. Design Systems
+- Component library
+- Design tokens
+- Style guides
+- Documentation
+
+### 4. Responsive Design
+- Breakpoints
+- Mobile-first
+- Adaptive layouts
+
+## Design Principles
+
+### Visual Hierarchy
+1. Size (larger = more important)
+2. Color (contrast draws attention)
+3. Position (top-left = primary)
+4. Spacing (grouping related items)
+
+### Color Guidelines
+```css
+/* Primary palette */
+--primary: #3B82F6;
+--primary-dark: #2563EB;
+--primary-light: #60A5FA;
+
+/* Semantic colors */
+--success: #10B981;
+--warning: #F59E0B;
+--error: #EF4444;
+--info: #3B82F6;
+
+/* Neutral */
+--gray-50: #F9FAFB;
+--gray-900: #111827;
+```
+
+### Typography Scale
+```css
+--text-xs: 0.75rem;    /* 12px */
+--text-sm: 0.875rem;   /* 14px */
+--text-base: 1rem;     /* 16px */
+--text-lg: 1.125rem;   /* 18px */
+--text-xl: 1.25rem;    /* 20px */
+--text-2xl: 1.5rem;    /* 24px */
+```
+
+### Spacing Scale
+```css
+--space-1: 0.25rem;    /* 4px */
+--space-2: 0.5rem;     /* 8px */
+--space-4: 1rem;       /* 16px */
+--space-6: 1.5rem;     /* 24px */
+--space-8: 2rem;       /* 32px */
+```
+
+## Accessibility Checklist
+
+- [ ] Color contrast >= 4.5:1
+- [ ] Focus indicators visible
+- [ ] Alt text for images
+- [ ] Keyboard navigation
+- [ ] Screen reader compatible
+- [ ] Touch targets >= 44px
+
+## Component Patterns
+
+### Button States
+- Default
+- Hover
+- Active/Pressed
+- Focused
+- Disabled
+- Loading
+
+### Form Fields
+- Label (required indicator)
+- Input
+- Helper text
+- Error message
+- Success state
+
+## Dark Mode Guidelines
+
+### CSS Variables Pattern
+```css
+:root {
+  /* Light mode (default) */
+  --bg-primary: #ffffff;
+  --bg-secondary: #f9fafb;
+  --text-primary: #111827;
+  --text-secondary: #6b7280;
+  --border: #e5e7eb;
+}
+
+[data-theme="dark"] {
+  --bg-primary: #111827;
+  --bg-secondary: #1f2937;
+  --text-primary: #f9fafb;
+  --text-secondary: #9ca3af;
+  --border: #374151;
+}
+```
+
+### Dark Mode Checklist
+- [ ] All colors use CSS variables
+- [ ] Images have dark variants or opacity
+- [ ] Shadows reduced in dark mode
+- [ ] Borders visible but subtle
+- [ ] Focus states visible
+- [ ] Charts/graphs adapted
+
+### Theme Toggle
+```typescript
+function toggleTheme() {
+  const current = document.documentElement.dataset.theme;
+  document.documentElement.dataset.theme = 
+    current === 'dark' ? 'light' : 'dark';
+  localStorage.setItem('theme', current === 'dark' ? 'light' : 'dark');
+}
+```
+
+## Animation/Motion Guidelines
+
+### Animation Principles
+| Principle | Description |
+|-----------|-------------|
+| Duration | 150-300ms for micro, 300-500ms for page |
+| Easing | `ease-out` for enter, `ease-in` for exit |
+| Purpose | Guide attention, provide feedback |
+
+### Common Animations
+```css
+/* Fade in */
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+/* Slide up */
+@keyframes slideUp {
+  from { transform: translateY(10px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+/* Scale */
+@keyframes scaleIn {
+  from { transform: scale(0.95); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+```
+
+### CSS Transition Utilities
+```css
+.transition-fast { transition: all 150ms ease-out; }
+.transition-base { transition: all 200ms ease-out; }
+.transition-slow { transition: all 300ms ease-out; }
+```
+
+### Reduce Motion
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Best Practices
+1. Design for accessibility first
+2. Use consistent spacing
+3. Follow platform conventions
+4. Test on real devices
+5. Get user feedback
+6. **Support dark mode from start**
+7. **Respect prefers-reduced-motion**
+
+## Related Agents
+- **Coder** - implement designs
+- **Fullstack Developer** - build complete UI
+

package/build/index.js

@@ -293,25 +293,34 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     try {
         const content = await fs.readFile(safePath, "utf-8");
         const parsed = toml.parse(content);
-        const promptText = parsed?.prompt || `Execute the ${promptName} command.`;
+        let promptText = parsed?.prompt || `Execute the ${promptName} command.`;
+        // Resolve @{path} includes from super-kit package root
+        const includePattern = /@\{([^}]+)\}/g;
+        let match;
+        while ((match = includePattern.exec(promptText)) !== null) {
+            const includePath = match[1];
+            const resolvedPath = getSafePath(superKitRoot, includePath);
+            if (resolvedPath) {
+                try {
+                    const includeContent = await fs.readFile(resolvedPath, "utf-8");
+                    promptText = promptText.replace(match[0], includeContent);
+                }
+                catch {
+                    promptText = promptText.replace(match[0], `[File not found: ${includePath}]`);
+                }
+            }
+        }
         // Load SUPERKIT.md for systematic inclusion
         const superKitPath = path.join(superKitRoot, "SUPERKIT.md");
         const superKitContent = await fs.readFile(superKitPath, "utf-8");
         return {
             description: parsed?.description || `Loaded command: ${promptName}`,
             messages: [
-                {
-                    role: "system", // Try standard system role if supported by the client
-                    content: {
-                        type: "text",
-                        text: superKitContent,
-                    },
-                },
                 {
                     role: "user",
                     content: {
                         type: "text",
-                        text: promptText,
+                        text: `[SYSTEM INSTRUCTIONS - Follow these strictly]\n\n${superKitContent}\n\n[USER TASK]\n\n${promptText}`,
                     },
                 },
             ],

package/build/tools/__tests__/loggerTools.test.js

@@ -17,7 +17,7 @@ describe('Logger Tools', () => {
         vi.setSystemTime(new Date('2026-03-04T00:00:00Z'));
         const result = await logSkill('test-skill', 'manual', 'context', tempDir);
         expect(result).toBe('Successfully logged skill usage for test-skill');
-        const logFile = path.join(tempDir, '.agent', 'logs', 'skill_usage.log');
+        const logFile = path.join(tempDir, 'docs', 'agents', 'logs', 'skill_usage.log');
         const content = await fs.readFile(logFile, 'utf-8');
         expect(content).toContain('2026-03-04T00:00:00Z|test-skill|manual|context\n');
         vi.useRealTimers();
@@ -27,7 +27,7 @@ describe('Logger Tools', () => {
         vi.setSystemTime(new Date('2026-03-04T00:00:00Z'));
         const result = await logWorkflow('test-workflow', 'session-123', tempDir);
         expect(result).toBe('Successfully logged workflow usage for test-workflow');
-        const logFile = path.join(tempDir, '.agent', 'logs', 'workflow_usage.log');
+        const logFile = path.join(tempDir, 'docs', 'agents', 'logs', 'workflow_usage.log');
         const content = await fs.readFile(logFile, 'utf-8');
         expect(content).toContain('2026-03-04T00:00:00Z|test-workflow|session-123\n');
         vi.useRealTimers();
@@ -36,13 +36,13 @@ describe('Logger Tools', () => {
         vi.useFakeTimers();
         vi.setSystemTime(new Date('2026-03-04T00:00:00Z')); // 1772582400 in seconds
         await logWorkflow('test-workflow', '', tempDir);
-        const logFile = path.join(tempDir, '.agent', 'logs', 'workflow_usage.log');
+        const logFile = path.join(tempDir, 'docs', 'agents', 'logs', 'workflow_usage.log');
         const content = await fs.readFile(logFile, 'utf-8');
         expect(content).toContain('2026-03-04T00:00:00Z|test-workflow|1772582400\n');
         vi.useRealTimers();
     });
     it('should rotate logs older than retention days', async () => {
-        const logDir = path.join(tempDir, '.agent', 'logs');
+        const logDir = path.join(tempDir, 'docs', 'agents', 'logs');
         await fs.mkdir(logDir, { recursive: true });
         // Old log line (e.g. 100 days old)
         const oldTimestamp = new Date();
@@ -61,7 +61,7 @@ describe('Logger Tools', () => {
         expect(finalContent).toContain('context2');
     });
     it('should report if no logs need rotation', async () => {
-        const logDir = path.join(tempDir, '.agent', 'logs');
+        const logDir = path.join(tempDir, 'docs', 'agents', 'logs');
         await fs.mkdir(logDir, { recursive: true });
         const newTimestamp = new Date();
         newTimestamp.setDate(newTimestamp.getDate() - 10);

package/build/tools/archTools.js

@@ -102,29 +102,16 @@ export async function validateArchitecture(projectPath = '.') {
     };
     const expSkills = getExpected('skills');
     const expWorkflows = getExpected('workflows');
-    const expScripts = getExpected('scripts');
     const expPatterns = getExpected('patterns');
-    let actSkills = 0, actWorkflows = 0, actScripts = 0, actPatterns = 0;
+    let actSkills = 0, actWorkflows = 0, actPatterns = 0;
     try {
         actSkills = (await fs.readdir(path.join(projectPath, 'skills'))).length;
     }
     catch { }
     try {
-        const wfs = await fs.readdir(path.join(projectPath, '.agent/workflows'));
+        const wfs = await fs.readdir(path.join(projectPath, 'skills', 'workflows'));
         actWorkflows = wfs.filter(f => f.endsWith('.md') && f !== 'README.md').length;
     }
-    catch {
-        // Fallback to workflows/
-        try {
-            const wfs = await fs.readdir(path.join(projectPath, 'workflows'));
-            actWorkflows = wfs.filter(f => f.endsWith('.md') && f !== 'README.md').length;
-        }
-        catch { }
-    }
-    try {
-        const scripts = await fs.readdir(path.join(projectPath, 'scripts'));
-        actScripts = scripts.filter(f => f.endsWith('.sh') || f.endsWith('.js') || f.endsWith('.ts')).length;
-    }
     catch { }
     try {
         const patternsCont = await fs.readFile(path.join(projectPath, 'docs/solutions/patterns/critical-patterns.md'), 'utf8');
@@ -141,10 +128,6 @@ export async function validateArchitecture(projectPath = '.') {
         out += `❌ Workflows mismatch: Doc says ${expWorkflows}, Found ${actWorkflows}\n`;
         fail = true;
     }
-    if (actScripts !== expScripts) {
-        out += `❌ Scripts mismatch: Doc says ${expScripts}, Found ${actScripts}\n`;
-        fail = true;
-    }
     if (actPatterns !== expPatterns) {
         out += `❌ Patterns mismatch: Doc says ${expPatterns}, Found ${actPatterns}\n`;
         fail = true;

package/build/tools/autoPreview.js

@@ -2,12 +2,12 @@ import * as fs from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
 import { spawn, execSync } from 'child_process';
-const AGENT_DIR = path.resolve('.agent');
+const AGENT_DIR = path.resolve('docs', 'agents');
 const PID_FILE = path.join(AGENT_DIR, 'preview.pid');
 const LOG_FILE = path.join(AGENT_DIR, 'preview.log');
 export async function manageAutoPreview(action, port = 3000) {
     const root = path.resolve('.');
-    // Ensure .agent dir exists
+    // Ensure docs/agents dir exists
     if (!existsSync(AGENT_DIR)) {
         await fs.mkdir(AGENT_DIR, { recursive: true });
     }

package/build/tools/compoundTools.js

@@ -4,8 +4,8 @@ export async function compoundSearch(terms, projectPath = '.') {
     const searchDirs = ['docs/solutions', 'docs/explorations', 'docs/decisions'].map(d => path.join(projectPath, d));
     // Log usage
     const logLine = `${new Date().toISOString().replace(/\.[0-9]{3}Z$/, 'Z')}|compound-search|manual|${terms.join(',')}\n`;
-    await fs.mkdir(path.join(projectPath, '.agent', 'logs'), { recursive: true });
-    await fs.appendFile(path.join(projectPath, '.agent', 'logs', 'compound_usage.log'), logLine);
+    await fs.mkdir(path.join(projectPath, 'docs', 'agents', 'logs'), { recursive: true });
+    await fs.appendFile(path.join(projectPath, 'docs', 'agents', 'logs', 'compound_usage.log'), logLine);
     const results = new Set();
     async function searchInDir(dir) {
         try {
@@ -54,8 +54,8 @@ export async function updateSolutionRef(files, projectPath = '.') {
     const today = new Date().toISOString().split('T')[0];
     let count = 0;
     const logLine = `${new Date().toISOString().replace(/\.[0-9]{3}Z$/, 'Z')}|update-solution-ref|manual|${files.join(',')}\n`;
-    await fs.mkdir(path.join(projectPath, '.agent', 'logs'), { recursive: true });
-    await fs.appendFile(path.join(projectPath, '.agent', 'logs', 'compound_usage.log'), logLine);
+    await fs.mkdir(path.join(projectPath, 'docs', 'agents', 'logs'), { recursive: true });
+    await fs.appendFile(path.join(projectPath, 'docs', 'agents', 'logs', 'compound_usage.log'), logLine);
     let output = '';
     for (const file of files) {
         const fullPath = path.resolve(projectPath, file);

package/build/tools/docsTools.js

@@ -66,14 +66,9 @@ export async function checkDocsFreshness(skipDocs = false, projectPath = '.') {
     let warnings = 0;
     let output = `🔍 Checking documentation freshness for: ${commitMsg}\n`;
     const changedFiles = changedFilesStr.split('\n');
-    const newScripts = changedFiles.filter(f => f.startsWith('scripts/') && f !== 'scripts/README.md');
-    if (newScripts.length > 0 && !changedFiles.includes('scripts/README.md')) {
-        output += "⚠️  Scripts modified but scripts/README.md not updated.\n";
-        warnings++;
-    }
-    const newWorkflows = changedFiles.filter(f => f.startsWith('.agent/workflows/') && f !== '.agent/workflows/README.md');
-    if (newWorkflows.length > 0 && !changedFiles.includes('.agent/workflows/README.md')) {
-        output += "⚠️  Workflows modified but .agent/workflows/README.md not updated.\n";
+    const newWorkflows = changedFiles.filter(f => f.startsWith('skills/workflows/') && f !== 'skills/workflows/README.md');
+    if (newWorkflows.length > 0 && !changedFiles.includes('skills/workflows/README.md')) {
+        output += "⚠️  Workflows modified but skills/workflows/README.md not updated.\n";
         warnings++;
     }
     const codeChanged = changedFiles.some(f => /^(src|components|lib|app)\//.test(f));
@@ -91,7 +86,7 @@ export async function checkDocsFreshness(skipDocs = false, projectPath = '.') {
     return output;
 }
 export async function discoverUndocumentedFolders(projectPath = '.') {
-    const roots = ["app", "lib", "backend", "scripts", "src"];
+    const roots = ["app", "lib", "backend", "src"];
     const exclusions = ["node_modules", "__pycache__", ".git", "__tests__", "archive", ".vercel", ".next", "dist"];
     const undocumented = [];
     async function scanDir(dir, depth) {
@@ -132,7 +127,7 @@ export async function discoverUndocumentedFolders(projectPath = '.') {
     return "✅ All key folders have README documentation.";
 }
 export async function validateFolderDocs(strict = false, targetFolders = [], projectPath = '.') {
-    const coreFolders = ["src", "scripts", "docs/solutions", "docs/architecture", ".agent/workflows"];
+    const coreFolders = ["src", "docs/solutions", "docs/architecture", "skills/workflows", "agents"];
     const foldersToCheck = targetFolders.length > 0 ? targetFolders : coreFolders;
     let exitCode = 0;
     let output = "🔍 Validating hierarchical documentation...\n";

package/build/tools/loggerTools.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 function getLogDir(projectPath = '.') {
-    return path.join(projectPath, '.agent', 'logs');
+    return path.join(projectPath, 'docs', 'agents', 'logs');
 }
 export async function logSkill(skill, trigger = 'manual', context = '', projectPath = '.') {
     // Format timestamp like 2026-03-04T00:12:42Z (ISO 8601 without milliseconds)