specweave 0.33.4 → 0.33.6

package/plugins/specweave-docs/commands/view.md

@@ -0,0 +1,391 @@
+---
+name: sw-docs:view
+description: Launch Docusaurus documentation server for living docs. Supports internal (default, port 3015) and public (--public, port 3016) docs. Validates docs first, auto-fixes issues, auto-setup on first run.
+---
+
+# Documentation View Command
+
+Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.
+
+**CRITICAL**: Runs pre-flight validation to catch issues BEFORE starting the server.
+
+## Usage
+
+```bash
+# View internal docs (default) - port 3015
+/sw-docs:view
+
+# View public docs - port 3016
+/sw-docs:view --public
+/sw-docs:view public
+```
+
+## Your Task
+
+**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
+
+### Step 0: Parse Arguments
+
+```typescript
+// Determine which docs to view
+const args = process.argv.slice(2);
+const isPublic = args.includes('--public') || args.includes('public');
+
+const config = isPublic
+  ? {
+      docsPath: '.specweave/docs/public',
+      port: 3016,
+      title: 'Public Documentation',
+      cachePath: '.specweave/cache/docs-site-public',
+      navbarTitle: 'Public Docs'
+    }
+  : {
+      docsPath: '.specweave/docs/internal',
+      port: 3015,
+      title: 'Internal Documentation',
+      cachePath: '.specweave/cache/docs-site',
+      navbarTitle: 'Internal Docs'
+    };
+
+console.log(`\n📚 Starting ${config.title} server...\n`);
+```
+
+### Step 1: Check Prerequisites
+
+```bash
+# Verify docs exist at the selected path
+ls -la ${config.docsPath}/
+
+# If missing, inform user:
+# "No documentation found at ${config.docsPath}/.
+#  Run 'specweave init' first or create the folder structure."
+```
+
+### Step 1.5: CRITICAL - Run Pre-Flight Validation
+
+**ALWAYS run validation BEFORE starting the server!**
+
+```typescript
+import { DocsValidator } from '../../../src/utils/docs-validator.js';
+
+const validator = new DocsValidator({
+  docsPath: config.docsPath,
+  autoFix: true,  // Auto-fix common issues
+});
+
+console.log('\n🔍 Running pre-flight validation...\n');
+const result = await validator.validate();
+
+// Show summary
+console.log(DocsValidator.formatResult(result));
+
+// If errors remain after auto-fix, STOP and report
+if (!result.valid) {
+  console.log('\n❌ Documentation has errors that must be fixed before preview.');
+  console.log('   Fix the issues above, then try again.\n');
+  process.exit(1);
+}
+
+console.log('\n✅ Validation passed! Starting server...\n');
+```
+
+**What this catches:**
+- YAML frontmatter errors (unquoted colons, tabs)
+- MDX compatibility issues (unquoted attributes, unclosed tags)
+- Duplicate routes
+- Broken internal links
+
+**Auto-fixes applied:**
+- Wraps YAML values with colons in quotes
+- Quotes HTML attributes
+- Adds closing slashes to void elements (`<br>` → `<br />`)
+- Converts tabs to spaces in YAML
+
+### Step 2: Check for Cached Installation
+
+```bash
+# Check if Docusaurus is already set up in cache
+if [ -d "${config.cachePath}/node_modules" ]; then
+  echo "✓ Docusaurus installation found in cache"
+  NEEDS_INSTALL=false
+else
+  echo "⚙ First-time setup: Installing Docusaurus (~30 seconds)..."
+  NEEDS_INSTALL=true
+fi
+```
+
+### Step 3: First-Time Setup (if needed)
+
+If `NEEDS_INSTALL=true`, create the cached Docusaurus installation:
+
+```typescript
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+// Create cache directory
+fs.mkdirSync(config.cachePath, { recursive: true });
+
+// Create package.json
+const packageJson = {
+  name: isPublic ? 'specweave-docs-public' : 'specweave-docs-internal',
+  version: '1.0.0',
+  private: true,
+  scripts: {
+    start: `docusaurus start --port ${config.port}`,
+    build: 'docusaurus build',
+    clear: 'docusaurus clear'
+  },
+  dependencies: {
+    '@docusaurus/core': '^3.9.2',
+    '@docusaurus/preset-classic': '^3.9.2',
+    '@docusaurus/theme-mermaid': '^3.9.2',
+    '@mdx-js/react': '^3.0.0',
+    'clsx': '^2.0.0',
+    'prism-react-renderer': '^2.3.0',
+    'react': '^19.0.0',
+    'react-dom': '^19.0.0'
+  },
+  engines: {
+    node: '>=20.0'
+  }
+};
+
+fs.writeFileSync(
+  path.join(config.cachePath, 'package.json'),
+  JSON.stringify(packageJson, null, 2)
+);
+
+// Calculate relative path from cache to docs
+// For internal: ../../docs/internal
+// For public: ../../docs/public
+const relativePath = isPublic ? '../../docs/public' : '../../docs/internal';
+
+// Create Docusaurus config
+const docusaurusConfig = `import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: '${config.title}',
+  tagline: 'SpecWeave Living Documentation',
+  favicon: 'img/favicon.ico',
+  future: { v4: true },
+  url: 'http://localhost:${config.port}',
+  baseUrl: '/',
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+  i18n: { defaultLocale: 'en', locales: ['en'] },
+  markdown: { mermaid: true, format: 'md' },
+  themes: ['@docusaurus/theme-mermaid'],
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          path: '${relativePath}',
+          routeBasePath: '/',
+          sidebarPath: './sidebars.ts',
+          showLastUpdateTime: true,
+          sidebarCollapsible: true,
+          sidebarCollapsed: true,
+        },
+        blog: false,
+        theme: { customCss: './src/css/custom.css' },
+      } satisfies Preset.Options,
+    ],
+  ],
+  themeConfig: {
+    colorMode: {
+      defaultMode: 'dark',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: '${config.navbarTitle}',
+      items: [
+        {to: '/', label: 'Home', position: 'left'},
+        {type: 'search', position: 'right'},
+      ],
+    },
+    footer: {
+      style: 'dark',
+      copyright: 'SpecWeave Living Documentation',
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ['bash', 'typescript', 'yaml', 'json'],
+    },
+    mermaid: { theme: {light: 'neutral', dark: 'dark'} },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;
+`;
+
+fs.writeFileSync(path.join(config.cachePath, 'docusaurus.config.ts'), docusaurusConfig);
+
+// Create auto-generated sidebar
+const sidebarsConfig = `import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  docs: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
+};
+
+export default sidebars;
+`;
+
+fs.writeFileSync(path.join(config.cachePath, 'sidebars.ts'), sidebarsConfig);
+
+// Create minimal CSS
+fs.mkdirSync(path.join(config.cachePath, 'src', 'css'), { recursive: true });
+const customCss = `:root {
+  --ifm-color-primary: ${isPublic ? '#059669' : '#2563eb'};
+  --ifm-code-font-size: 95%;
+}
+[data-theme='dark'] {
+  --ifm-color-primary: ${isPublic ? '#34d399' : '#60a5fa'};
+}
+`;
+
+fs.writeFileSync(path.join(config.cachePath, 'src', 'css', 'custom.css'), customCss);
+
+// Create static folder with placeholder favicon
+fs.mkdirSync(path.join(config.cachePath, 'static', 'img'), { recursive: true });
+fs.writeFileSync(
+  path.join(config.cachePath, 'static', 'img', 'favicon.ico'),
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="90">📚</text></svg>'
+);
+
+// Install dependencies using PUBLIC npm registry
+execSync('npm install --registry=https://registry.npmjs.org --legacy-peer-deps', {
+  cwd: config.cachePath,
+  stdio: 'inherit'
+});
+```
+
+### Step 4: Start the Server
+
+```bash
+cd ${config.cachePath} && npm start
+```
+
+This will:
+- Start Docusaurus on **http://localhost:${config.port}**
+- Enable hot reload (edit markdown, see changes instantly)
+- Render Mermaid diagrams
+- Auto-generate sidebar from folder structure
+
+### Output to User
+
+After starting, display:
+
+```
+📚 Documentation View Server Started!
+
+   Mode: ${isPublic ? 'PUBLIC' : 'INTERNAL'} docs
+   URL: http://localhost:${config.port}
+   Content: ${config.docsPath}/
+
+   Features:
+   • Hot reload - edit markdown, see changes instantly
+   • Mermaid diagrams - architecture diagrams render beautifully
+   • Auto sidebar - generated from folder structure
+   • Dark/light mode - toggle in navbar
+
+   Press Ctrl+C to stop the server.
+```
+
+## What You Get
+
+- **Hot reload** - Edit markdown, see changes instantly
+- **Auto sidebar** - Generated from folder structure
+- **Mermaid diagrams** - Architecture diagrams render beautifully
+- **Dark/light mode** - Toggle in navbar
+- **Local search** - Instant search across all docs
+- **Color coding** - Internal docs use blue theme, public docs use green theme
+
+## Examples
+
+### View Internal Docs (Default)
+
+```bash
+/sw-docs:view
+
+# Output:
+📚 Starting Internal Documentation server...
+🔍 Running pre-flight validation...
+✅ Validation passed! Starting server...
+
+📚 Documentation View Server Started!
+   Mode: INTERNAL docs
+   URL: http://localhost:3015
+   Content: .specweave/docs/internal/
+```
+
+### View Public Docs
+
+```bash
+/sw-docs:view --public
+
+# Output:
+📚 Starting Public Documentation server...
+🔍 Running pre-flight validation...
+✅ Validation passed! Starting server...
+
+📚 Documentation View Server Started!
+   Mode: PUBLIC docs
+   URL: http://localhost:3016
+   Content: .specweave/docs/public/
+```
+
+### View Both Simultaneously
+
+Run in separate terminals:
+```bash
+# Terminal 1: Internal docs
+/sw-docs:view
+
+# Terminal 2: Public docs
+/sw-docs:view --public
+
+# Now both servers are running!
+# Internal: http://localhost:3015
+# Public: http://localhost:3016
+```
+
+## Troubleshooting
+
+### Port already in use
+```bash
+# For internal docs (port 3015)
+lsof -i :3015 && kill -9 $(lsof -t -i :3015)
+
+# For public docs (port 3016)
+lsof -i :3016 && kill -9 $(lsof -t -i :3016)
+```
+
+### Reinstall from scratch
+```bash
+# For internal docs
+rm -rf .specweave/cache/docs-site && /sw-docs:view
+
+# For public docs
+rm -rf .specweave/cache/docs-site-public && /sw-docs:view --public
+```
+
+### npm registry issues
+The setup uses `--registry=https://registry.npmjs.org` to bypass private registry configurations.
+
+## See Also
+
+- `/sw-docs:build` - Build static site for deployment
+- `/sw-docs:organize` - Generate themed indexes for large folders
+- `/sw-docs:health` - Documentation health report
+- `/sw-docs:validate` - Validate documentation without starting server

package/plugins/specweave-docs/skills/preview/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: preview
-description: Documentation preview expert for Docusaurus integration. Launches interactive preview server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Works in ANY SpecWeave project with auto-setup. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
+description: Documentation view expert for Docusaurus integration. Launches interactive server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Works in ANY SpecWeave project with auto-setup. Supports both internal (port 3015) and public (port 3016) docs. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
 ---
 
-# Documentation Preview Skill
+# Documentation View Skill
 
-Expert in launching and managing Docusaurus documentation preview for SpecWeave projects.
+Expert in launching and managing Docusaurus documentation server for SpecWeave projects.
 
 ## What I Do
 
-I help you preview your SpecWeave living documentation with Docusaurus:
+I help you view your SpecWeave living documentation with Docusaurus:
 
 ### Key Features
 - **Zero-config setup** - Works in any SpecWeave project automatically
+- **Internal & Public docs** - Internal on port 3015, public on port 3016
 - **Cached installation** - Docusaurus cached in `.specweave/cache/docs-site/` (gitignored)
 - **Hot reload** - Edit markdown, see changes instantly
 - **Mermaid diagrams** - Architecture diagrams render beautifully
@@ -22,9 +23,9 @@ I help you preview your SpecWeave living documentation with Docusaurus:
 ## How It Works
 
 1. **First run (~30 seconds)**:
-   - Creates Docusaurus in `.specweave/cache/docs-site/`
+   - Creates Docusaurus in `.specweave/cache/docs-site/` (internal) or `.specweave/cache/docs-site-public/` (public)
    - Installs dependencies from public npm registry
-   - Configures to read from `.specweave/docs/internal/`
+   - Configures to read from `.specweave/docs/internal/` or `.specweave/docs/public/`
 
 2. **Subsequent runs (instant)**:
    - Uses cached installation
@@ -32,20 +33,33 @@ I help you preview your SpecWeave living documentation with Docusaurus:
 
 ## Available Commands
 
-### Preview Documentation
+### View Internal Documentation (Default)
 ```bash
-/specweave-docs:preview
+/sw-docs:view
 ```
 
 **What it does:**
 1. Checks if `.specweave/docs/internal/` exists
-2. Sets up Docusaurus in cache (if first run)
-3. Starts dev server on **http://localhost:3015**
-4. Enables hot reload
+2. Runs pre-flight validation (auto-fixes common issues)
+3. Sets up Docusaurus in cache (if first run)
+4. Starts dev server on **http://localhost:3015**
+5. Enables hot reload
+
+### View Public Documentation
+```bash
+/sw-docs:view --public
+```
+
+**What it does:**
+1. Checks if `.specweave/docs/public/` exists
+2. Runs pre-flight validation (auto-fixes common issues)
+3. Sets up Docusaurus in cache (if first run)
+4. Starts dev server on **http://localhost:3016**
+5. Enables hot reload
 
 ### Build Static Site
 ```bash
-/specweave-docs:build
+/sw-docs:build
 ```
 
 **What it does:**
@@ -56,32 +70,56 @@ I help you preview your SpecWeave living documentation with Docusaurus:
 ## When to Use This Skill
 
 ### Activate for:
-- "Preview my documentation"
+- "View my documentation"
+- "Preview my docs"
 - "Show me my docs in a browser"
 - "Launch Docusaurus"
 - "View my living documentation"
-- "Start docs preview"
+- "Start docs server"
 - "I want to see my internal docs"
+- "View public docs"
 
 ### Workflow
 
 ```
 User: "I want to preview my docs"
-You: "I'll launch the documentation preview server."
-     [Run: /specweave-docs:preview]
+You: "I'll launch the documentation view server."
+     [Run: /sw-docs:view]
+```
+
+```
+User: "Show me my public documentation"
+You: "I'll launch the public documentation server."
+     [Run: /sw-docs:view --public]
 ```
 
+## Port Reference
+
+| Docs Type | Port | Path |
+|-----------|------|------|
+| Internal (default) | 3015 | `.specweave/docs/internal/` |
+| Public | 3016 | `.specweave/docs/public/` |
+
 ## Troubleshooting
 
-### Port 3015 already in use
+### Port 3015 or 3016 already in use
 ```bash
+# For internal docs
 lsof -i :3015 && kill -9 $(lsof -t -i :3015)
+
+# For public docs
+lsof -i :3016 && kill -9 $(lsof -t -i :3016)
 ```
 
 ### Reinstall from scratch
 ```bash
+# For internal docs
 rm -rf .specweave/cache/docs-site
-# Then run /specweave-docs:preview again
+# Then run /sw-docs:view again
+
+# For public docs
+rm -rf .specweave/cache/docs-site-public
+# Then run /sw-docs:view --public again
 ```
 
 ### npm registry issues
@@ -89,6 +127,7 @@ The setup explicitly uses `--registry=https://registry.npmjs.org` to bypass priv
 
 ## See Also
 
-- `/specweave-docs:build` - Build static site for deployment
-- `/specweave-docs:organize` - Organize large folders with themed indexes
-- `/specweave-docs:health` - Documentation health report
+- `/sw-docs:build` - Build static site for deployment
+- `/sw-docs:organize` - Organize large folders with themed indexes
+- `/sw-docs:health` - Documentation health report
+- `/sw-docs:validate` - Validate documentation before viewing

package/plugins/specweave-figma/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "name": "specweave-figma",
+  "name": "sw-figma",
   "description": "Comprehensive Figma design-to-code automation. Import Figma designs via API/MCP, convert components to React/Vue/Angular, extract design tokens, generate responsive layouts, and sync design systems. Focus on accelerating frontend development from Figma designs.",
   "version": "0.24.0",
   "author": {

package/plugins/specweave-figma/commands/figma-import.md

@@ -1,4 +1,4 @@
-# /specweave-figma:import
+# /sw-figma:import
 
 Import Figma designs into your project using Figma REST API or MCP server integration.
 

package/plugins/specweave-figma/commands/figma-to-react.md

@@ -1,4 +1,4 @@
-# /specweave-figma:to-react
+# /sw-figma:to-react
 
 Convert Figma components to production-ready React components with TypeScript, styled-components, and responsive design.
 

package/plugins/specweave-figma/commands/figma-tokens.md

@@ -1,4 +1,4 @@
-# /specweave-figma:tokens
+# /sw-figma:tokens
 
 Extract design tokens from Figma and generate token files for theme configuration (CSS variables, JavaScript, JSON, SCSS).
 

package/plugins/specweave-frontend/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "name": "specweave-frontend",
+  "name": "sw-frontend",
   "description": "Frontend development for React, Vue, and Angular projects. Includes Next.js 14+ App Router support, design system architecture (Atomic Design), and UI component best practices. Focus on modern frontend patterns and performance.",
   "version": "0.24.0",
   "author": {

package/plugins/specweave-frontend/agents/frontend-architect/README.md

@@ -270,13 +270,13 @@ Document complex components in Storybook with examples.
 
 ## Integration with SpecWeave
 
-### Use with /specweave:increment
+### Use with /sw:increment
 
 When planning a frontend feature increment:
 
 ```bash
 # 1. Plan increment
-/specweave:increment "Design and implement responsive navigation with mega menu"
+/sw:increment "Design and implement responsive navigation with mega menu"
 
 # 2. Generate architectural plan
 Task({
@@ -285,16 +285,16 @@ Task({
 });
 
 # 3. Implement based on architectural plan
-/specweave:do
+/sw:do
 ```
 
-### Use with /specweave:qa
+### Use with /sw:qa
 
 After implementation, validate architecture decisions:
 
 ```bash
 # Run quality assessment
-/specweave:qa 0123
+/sw:qa 0123
 
 # Agent checks:
 # - Component modularity

package/plugins/specweave-frontend/commands/component-generate.md

@@ -1,4 +1,4 @@
-# /specweave-frontend:component-generate
+# /sw-frontend:component-generate
 
 Generate React/Vue/Angular components with tests, stories, and documentation following Atomic Design principles.
 

package/plugins/specweave-frontend/commands/design-system-init.md

@@ -1,4 +1,4 @@
-# /specweave-frontend:design-system-init
+# /sw-frontend:design-system-init
 
 Initialize a complete design system with Atomic Design principles, design tokens, and component library.
 

package/plugins/specweave-frontend/commands/frontend-scaffold.md

@@ -1,4 +1,4 @@
-# /specweave-frontend:frontend-scaffold
+# /sw-frontend:frontend-scaffold
 
 Scaffold a complete frontend project with modern tooling and best practices.
 

package/plugins/specweave-frontend/commands/nextjs-setup.md

@@ -1,4 +1,4 @@
-# /specweave-frontend:nextjs-setup
+# /sw-frontend:nextjs-setup
 
 Set up Next.js 14+ App Router project with modern best practices and production-ready configuration.
 

package/plugins/specweave-github/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "name": "specweave-github",
+  "name": "sw-github",
   "description": "GitHub Issues integration for SpecWeave increments. Bidirectional sync between SpecWeave increments and GitHub Issues. Automatically creates issues from increments, tracks progress, and closes issues on completion. Uses GitHub CLI (gh) for seamless integration.",
   "version": "0.24.0",
   "author": {

package/plugins/specweave-github/MULTI-PROJECT-SYNC-ARCHITECTURE.md

@@ -441,10 +441,10 @@ tags: ["project:frontend", "project:backend", "cross-team"]
 
 ```bash
 # Create spec
-/specweave:increment "User authentication"
+/sw:increment "User authentication"
 
 # Sync to GitHub (auto-detects project = default)
-/specweave-github:sync-spec spec-001
+/sw-github:sync-spec spec-001
 ```
 
 ### Multi-Project Usage
@@ -454,10 +454,10 @@ tags: ["project:frontend", "project:backend", "cross-team"]
 # (place in .specweave/docs/internal/specs/frontend/)
 
 # Sync to GitHub (auto-detects project = frontend, routes to frontend-app repo)
-/specweave-github:sync-spec spec-001
+/sw-github:sync-spec spec-001
 
 # Cross-team spec (auto-syncs to multiple repos)
-/specweave-github:sync-spec spec-auth
+/sw-github:sync-spec spec-auth
 # → Creates issues in frontend-app AND backend-api
 ```