specweave 0.33.3 → 0.33.5

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

@@ -0,0 +1,391 @@
+---
+name: specweave-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
+/specweave-docs:view
+
+# View public docs - port 3016
+/specweave-docs:view --public
+/specweave-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
+/specweave-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
+/specweave-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
+/specweave-docs:view
+
+# Terminal 2: Public docs
+/specweave-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 && /specweave-docs:view
+
+# For public docs
+rm -rf .specweave/cache/docs-site-public && /specweave-docs:view --public
+```
+
+### npm registry issues
+The setup uses `--registry=https://registry.npmjs.org` to bypass private registry configurations.
+
+## See Also
+
+- `/specweave-docs:build` - Build static site for deployment
+- `/specweave-docs:organize` - Generate themed indexes for large folders
+- `/specweave-docs:health` - Documentation health report
+- `/specweave-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,16 +33,29 @@ I help you preview your SpecWeave living documentation with Docusaurus:
 
 ## Available Commands
 
-### Preview Documentation
+### View Internal Documentation (Default)
 ```bash
-/specweave-docs:preview
+/specweave-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
+/specweave-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
@@ -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: /specweave-docs:view]
+```
+
+```
+User: "Show me my public documentation"
+You: "I'll launch the public documentation server."
+     [Run: /specweave-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 /specweave-docs:view again
+
+# For public docs
+rm -rf .specweave/cache/docs-site-public
+# Then run /specweave-docs:view --public again
 ```
 
 ### npm registry issues
@@ -92,3 +130,4 @@ The setup explicitly uses `--registry=https://registry.npmjs.org` to bypass priv
 - `/specweave-docs:build` - Build static site for deployment
 - `/specweave-docs:organize` - Organize large folders with themed indexes
 - `/specweave-docs:health` - Documentation health report
+- `/specweave-docs:validate` - Validate documentation before viewing

package/src/templates/AGENTS.md.template

@@ -32,16 +32,17 @@
 ```
 1. NEVER pollute project root with .md files
 2. Increment IDs unique (0001-9999)
-3. ONLY 3 files in increment root: spec.md, plan.md, tasks.md
+3. ONLY 4 files in increment root: metadata.json, spec.md, plan.md, tasks.md
 4. All reports/scripts/logs → increment subfolders
-5. Read context-manifest.yaml first (70%+ token savings)
+5. metadata.json MUST exist BEFORE spec.md can be created
 6. tasks.md + spec.md = SOURCE OF TRUTH (update after every task!)
 ```
 
 **File Organization**:
 ```
 .specweave/increments/0001-feature/
-├── spec.md, plan.md, tasks.md    # ONLY these in root
+├── metadata.json                  # REQUIRED - create FIRST
+├── spec.md, plan.md, tasks.md    # Core increment docs
 ├── reports/                       # SESSION-*.md, analysis, etc.
 ├── scripts/                       # Helper scripts
 └── logs/                          # Execution logs
@@ -410,26 +411,21 @@ TASK COMPLETED
 
 ## Context Loading {#context-loading}
 
-### Why Context Manifests Matter
+### Efficient Context Management
 
 ```
-Without manifest: Load all docs (50k tokens) → Crash risk
-With manifest:    Load relevant files (5k tokens) → 90% savings
+Read only what's needed for the current task:
+- Active increment: spec.md, tasks.md (always)
+- Supporting docs: only when referenced in tasks
+- Living docs: load per-US when implementing
 ```
 
-### Using context-manifest.yaml
+### Token-Efficient Approach
 
-```yaml
-# .specweave/increments/0001-feature/context-manifest.yaml
-spec_sections:
-  - .specweave/docs/internal/strategy/prd.md
-  - .specweave/docs/internal/architecture/hld.md
-documentation:
-  - .specweave/docs/internal/specs/default/relevant-spec.md
-max_context_tokens: 10000
-```
-
-**Rule**: Read context-manifest.yaml FIRST. Only load files listed there.
+1. Start with increment's `tasks.md` - contains current task list
+2. Reference `spec.md` for acceptance criteria
+3. Load living docs only when needed for context
+4. Avoid loading entire documentation trees
 
 ---
 
@@ -439,10 +435,10 @@ max_context_tokens: 10000
 .specweave/
 ├── increments/           # Feature increments (0001-9999)
 │   └── 0001-feature/
+│       ├── metadata.json # Increment metadata - REQUIRED
 │       ├── spec.md       # WHAT & WHY (user stories, ACs)
-│       ├── plan.md       # HOW (architecture, APIs)
-│       ├── tasks.md      # Task checklist with test plans
-│       └── context-manifest.yaml  # Files to load
+│       ├── plan.md       # HOW (architecture, APIs) - optional
+│       └── tasks.md      # Task checklist with test plans
 ├── docs/internal/
 │   ├── strategy/         # PRD, business requirements
 │   ├── specs/            # Living docs (extracted user stories)
@@ -521,10 +517,10 @@ AI: [Creates .specweave/increments/0001-auth/spec.md, plan.md, tasks.md]
 
 ### Creating Increment
 1. `mkdir -p .specweave/increments/0001-feature`
-2. Create `spec.md` (WHAT/WHY, user stories, ACs)
-3. Create `plan.md` (HOW, architecture, APIs)
+2. Create `metadata.json` (increment metadata) - **MUST be FIRST**
+3. Create `spec.md` (WHAT/WHY, user stories, ACs)
 4. Create `tasks.md` (task checklist with tests)
-5. Create `context-manifest.yaml` (selective loading)
+5. Optional: Create `plan.md` (HOW, architecture) for complex features
 
 ### Completing Tasks
 1. Implement the task
@@ -599,12 +595,12 @@ Or run: `/specweave:sync-tasks`
 
 **Symptoms**: Tool crashes 10-50s after start
 
-**Causes**: Loading too many files, no context manifest
+**Causes**: Loading too many files at once
 
 **Fix**:
-1. Create `context-manifest.yaml` in increment folder
-2. List only files needed for current task
-3. Never load entire `.specweave/docs/` folder
+1. Load only the active increment's spec.md and tasks.md
+2. Reference living docs only when needed for specific tasks
+3. Never load entire `.specweave/docs/` folder at once
 
 ### Skills/Agents Not Activating
 

package/src/templates/CLAUDE.md.template

@@ -67,10 +67,10 @@ Edit("spec.md", "- [ ] **AC-US1-01**", "- [x] **AC-US1-01**");
 .specweave/
 ├── increments/              # Feature increments (####-name/)
 │   └── 0001-feature/
+│       ├── metadata.json    # Increment metadata - REQUIRED
 │       ├── spec.md          # WHAT & WHY
-│       ├── plan.md          # HOW
-│       ├── tasks.md         # Checklist with embedded tests
-│       └── context-manifest.yaml  # Selective loading
+│       ├── plan.md          # HOW (optional)
+│       └── tasks.md         # Checklist with embedded tests
 ├── docs/internal/
 │   ├── strategy/            # Business specs
 │   ├── specs/               # Living docs (post-completion)
@@ -96,12 +96,16 @@ Edit("spec.md", "- [ ] **AC-US1-01**", "- [x] **AC-US1-01**");
 
 ---
 
-## Context Loading (Token Savings)
+## Increment Files
 
-**ALWAYS read `context-manifest.yaml` first!** Load only files listed there.
-- Full specs: 50k tokens
-- Manifest files: 5k tokens
-- **Savings: 90%**
+**Required files** for every increment:
+1. `metadata.json` - Increment metadata (status, type, dates) - MUST create FIRST
+2. `spec.md` - User stories, acceptance criteria
+3. `tasks.md` - Implementation tasks with embedded tests
+
+**Optional**:
+- `plan.md` - Technical design (for complex features only)
+- `reports/` - Completion reports, analyses
 
 ---