specweave 1.0.593 → 2.0.3

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

@@ -1,338 +0,0 @@
----
-description: Initialize Docusaurus documentation site with spec-driven structure, living docs integration, and SpecWeave-optimized configuration.
----
-
-# Initialize Documentation Site
-
-Initialize a Docusaurus documentation site with spec-driven documentation structure, living docs integration, and SpecWeave-optimized configuration.
-
-## Usage
-
-```
-/docs:init [options]
-```
-
-## What I Do
-
-1. **Scaffold Docusaurus Site**: Create standard Docusaurus 3.x structure
-2. **Configure Plugins**: Set up Mermaid diagrams, search, versioning
-3. **SpecWeave Integration**: Link to `.specweave/docs/` living documentation
-4. **Theme Customization**: Apply professional theme with dark mode
-5. **Sidebar Generation**: Auto-generate sidebar from directory structure
-
-## Options
-
-- `--template <template>` - Template type: classic, material, custom (default: classic)
-- `--typescript` - Use TypeScript configuration (default: true)
-- `--mermaid` - Enable Mermaid diagram support (default: true)
-- `--search` - Add Algolia DocSearch or local search (default: local)
-- `--versioning` - Enable documentation versioning (default: false)
-- `--output <path>` - Output directory (default: `./docs-site`)
-
-## Generated Structure
-
-```
-docs-site/
-├── docs/                    # Documentation content
-│   ├── intro.md
-│   ├── features/
-│   ├── api/
-│   └── guides/
-├── blog/                    # Optional blog
-├── src/
-│   ├── components/         # React components
-│   ├── css/               # Custom styles
-│   └── pages/             # Custom pages
-├── static/                # Static assets
-│   ├── img/
-│   └── diagrams/
-├── docusaurus.config.ts   # Main configuration
-├── sidebars.ts            # Sidebar configuration
-├── package.json
-└── tsconfig.json
-```
-
-## SpecWeave Integration
-
-### Living Docs Auto-Sync
-
-Automatically imports content from `.specweave/docs/`:
-
-```typescript
-// docusaurus.config.ts
-module.exports = {
-  plugins: [
-    [
-      '@docusaurus/plugin-content-docs',
-      {
-        id: 'specweave-docs',
-        path: '../.specweave/docs',
-        routeBasePath: 'specweave',
-        sidebarPath: './sidebars.ts',
-      },
-    ],
-  ],
-};
-```
-
-### Architecture Diagrams
-
-Mermaid integration for `.specweave/docs/architecture/`:
-
-```markdown
-# System Architecture
-
-```mermaid
-graph TB
-  A[Frontend] -->|API| B[Backend]
-  B -->|Query| C[Database]
-  B -->|Publish| D[Kafka]
-\```
-```
-
-### API Documentation
-
-OpenAPI/Swagger integration:
-
-```typescript
-// docusaurus.config.ts
-plugins: [
-  [
-    'docusaurus-plugin-openapi-docs',
-    {
-      id: 'api',
-      docsPluginId: 'classic',
-      config: {
-        api: {
-          specPath: '../.specweave/docs/api/openapi.yaml',
-          outputDir: 'docs/api',
-        },
-      },
-    },
-  ],
-],
-```
-
-## Default Configuration
-
-### Theme
-
-```typescript
-// docusaurus.config.ts
-themeConfig: {
-  colorMode: {
-    defaultMode: 'dark',
-    respectPrefersColorScheme: true,
-  },
-  navbar: {
-    title: 'Project Name',
-    logo: {
-      src: 'img/logo.svg',
-    },
-    items: [
-      {
-        type: 'doc',
-        docId: 'intro',
-        label: 'Docs',
-      },
-      {
-        to: '/specweave',
-        label: 'Architecture',
-      },
-      {
-        to: '/api',
-        label: 'API',
-      },
-      {
-        href: 'https://github.com/your-org/your-repo',
-        label: 'GitHub',
-        position: 'right',
-      },
-    ],
-  },
-  footer: {
-    copyright: `Copyright © ${new Date().getFullYear()} Your Company`,
-  },
-}
-```
-
-### Plugins
-
-```typescript
-plugins: [
-  '@docusaurus/plugin-content-docs',
-  '@docusaurus/plugin-content-blog',
-  '@docusaurus/plugin-content-pages',
-  '@docusaurus/theme-classic',
-  '@docusaurus/theme-mermaid',
-  '@docusaurus/plugin-sitemap',
-],
-```
-
-## Post-Init Steps
-
-After initialization:
-
-1. **Install Dependencies**
-   ```bash
-   cd docs-site && npm install
-   ```
-
-2. **Start Dev Server**
-   ```bash
-   npm start
-   ```
-
-3. **Build for Production**
-   ```bash
-   npm run build
-   ```
-
-4. **Deploy**
-   ```bash
-   npm run serve # Preview production build
-   ```
-
-## Use Cases
-
-### 1. Product Documentation
-Create comprehensive user guides, feature docs, and tutorials.
-
-### 2. API Documentation
-Generate interactive API documentation from OpenAPI specs.
-
-### 3. Technical Specifications
-Document architecture, design decisions (ADRs), and technical specs.
-
-### 4. Living Documentation
-Auto-sync SpecWeave living docs (features, user stories, modules).
-
-### 5. Internal Knowledge Base
-Team documentation, runbooks, incident reports, postmortems.
-
-## Deployment Options
-
-### Static Hosting
-- GitHub Pages
-- Netlify
-- Vercel
-- AWS S3 + CloudFront
-
-### Configuration for GitHub Pages
-```typescript
-// docusaurus.config.ts
-module.exports = {
-  url: 'https://your-org.github.io',
-  baseUrl: '/your-repo/',
-  organizationName: 'your-org',
-  projectName: 'your-repo',
-  deploymentBranch: 'gh-pages',
-};
-```
-
-## Customization
-
-### Add Custom React Components
-
-```typescript
-// src/components/FeatureCard.tsx
-export function FeatureCard({ title, description, icon }) {
-  return (
-    <div className="feature-card">
-      <div className="icon">{icon}</div>
-      <h3>{title}</h3>
-      <p>{description}</p>
-    </div>
-  );
-}
-```
-
-### Custom Homepage
-
-```tsx
-// src/pages/index.tsx
-import React from 'react';
-import Layout from '@theme/Layout';
-
-export default function Home() {
-  return (
-    <Layout title="Home" description="Project Documentation">
-      <main>
-        <h1>Welcome to Our Documentation</h1>
-        {/* Custom content */}
-      </main>
-    </Layout>
-  );
-}
-```
-
-### Add Search
-
-```bash
-# Local search
-npm install --save @easyops-cn/docusaurus-search-local
-
-# Algolia DocSearch (requires approval)
-# Add to docusaurus.config.ts:
-themeConfig: {
-  algolia: {
-    appId: 'YOUR_APP_ID',
-    apiKey: 'YOUR_API_KEY',
-    indexName: 'YOUR_INDEX_NAME',
-  },
-}
-```
-
-## Examples
-
-### Basic Initialization
-```bash
-/docs:docs-init
-```
-
-### TypeScript with Mermaid
-```bash
-/docs:docs-init --typescript --mermaid
-```
-
-### Material Theme with Versioning
-```bash
-/docs:docs-init --template material --versioning
-```
-
-### Custom Output Directory
-```bash
-/docs:init --output ./documentation
-```
-
-## Related Commands
-
-- `/docs:generate` - Generate docs from code/specs
-- `/docs:view` - Launch documentation server
-- `/docs:build` - Build static documentation site
-
-## Requirements
-
-- Node.js 18.0 or higher
-- npm or yarn package manager
-- ~200MB disk space for Docusaurus + dependencies
-
-## Troubleshooting
-
-### Port Already in Use
-```bash
-PORT=3001 npm start
-```
-
-### Build Failures
-```bash
-# Clear cache
-npm run clear
-npm run build
-```
-
-### Broken Links
-```bash
-# Check for broken links
-npm run build -- --debug
-```

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

@@ -1,183 +0,0 @@
----
-description: Smart documentation organization - generates themed navigation indexes for large folders. Works seamlessly with Docusaurus preview.
----
-
-# Smart Documentation Organizer
-
-Automatically organize large documentation folders by detecting themes and generating navigable category indexes.
-
-## Why Organize?
-
-When folders grow beyond 30+ files, navigation becomes painful:
-- ADRs (147 files) - hard to find sync vs hooks vs testing decisions
-- Specs - many features across different domains
-- Guides - mixed topics without clear structure
-
-**Solution**: Generate themed category indexes WITHOUT moving files (preserves URLs).
-
-## Usage
-
-```bash
-# Analyze and organize all internal docs
-/docs:organize
-
-# Analyze specific folder only
-/docs:organize --folder architecture/adr
-
-# Preview without generating files
-/docs:organize --dry-run
-
-# Force regeneration even if under threshold
-/docs:organize --force
-
-# Set custom threshold (default: 30)
-/docs:organize --threshold 20
-```
-
-## Your Task
-
-Execute the smart documentation organizer:
-
-```typescript
-import { SmartDocOrganizer, organizeDocumentation } from '../../src/living-docs/smart-doc-organizer.js';
-import * as path from 'path';
-
-const projectPath = process.cwd();
-
-// Option 1: Quick organize all internal docs
-const result = await organizeDocumentation(projectPath, {
-  dryRun: false,  // Set true to preview
-  thresholdForOrganization: 30,
-});
-
-console.log(result.summary);
-
-// Option 2: Analyze specific folder
-const organizer = new SmartDocOrganizer({
-  projectPath,
-  thresholdForOrganization: 30,
-  generateIndexes: true,
-  dryRun: false,
-});
-
-const adrPath = path.join(projectPath, '.specweave/docs/internal/architecture/adr');
-const plan = await organizer.analyzeFolder(adrPath);
-
-console.log(`
-DOCUMENTATION ANALYSIS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Folder: ${plan.folder}
-Total Files: ${plan.totalFiles}
-Needs Organization: ${plan.needsOrganization ? 'Yes' : 'No'}
-
-Theme Categories:
-${plan.themeCategories
-  .filter(c => c.count >= 3)
-  .map(c => `  ${c.theme.icon} ${c.theme.name}: ${c.count} files`)
-  .join('\n')}
-
-Uncategorized: ${plan.uncategorized.length} files
-`);
-
-// Generate indexes if needed
-if (plan.needsOrganization) {
-  const generatedFiles = await organizer.generateCategoryIndexes(plan);
-  console.log(`\nGenerated ${generatedFiles.length} index files`);
-}
-```
-
-## What Gets Generated
-
-### 1. Category Index (`_categories.md`)
-
-Main navigation hub with:
-- Links to all theme categories
-- Quick stats (total docs, categorized count)
-- Recently updated documents
-
-### 2. Theme Indexes (`_index-{theme}.md`)
-
-Per-theme navigation with:
-- All files in that category
-- Sub-grouping for large themes (15+ files)
-- Sorted alphabetically
-
-## Theme Detection
-
-The organizer automatically detects these themes:
-
-| Icon | Theme | Keywords |
-|------|-------|----------|
-| 🔄 | Synchronization | sync, integration, bidirectional |
-| 🐙 | GitHub | github, issue, actions |
-| 🪝 | Hooks | hook, event, trigger |
-| 🔌 | External Tools | jira, ado, area-path |
-| 🧪 | Testing | test, fixture, coverage |
-| 🏗️ | Brownfield | brownfield, migration, legacy |
-| ⚡ | Performance | cache, pagination, batch |
-| 🔒 | Security | permission, auth, token |
-| 📦 | Increments | increment, status, lifecycle |
-| ⚙️ | Configuration | config, env, setup |
-| 📚 | Documentation | doc, spec, naming |
-
-## Output Example
-
-```
-DOCUMENTATION ANALYSIS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Folder: architecture/adr
-Total Files: 147
-Needs Organization: Yes
-
-Theme Categories:
-  🔄 Synchronization & Integration: 23 files
-  🐙 GitHub Integration: 18 files
-  🪝 Hooks & Events: 15 files
-  🧪 Testing & Quality: 12 files
-  🔌 External Tools (ADO, JIRA): 11 files
-  📦 Increment Lifecycle: 10 files
-  ⚡ Performance & Optimization: 9 files
-  ⚙️ Configuration & Setup: 8 files
-
-Uncategorized: 14 files
-
-Generated 9 index files:
-  - _categories.md
-  - _index-sync.md
-  - _index-github.md
-  - _index-hooks.md
-  - _index-testing.md
-  - _index-external-tools.md
-  - _index-increments.md
-  - _index-performance.md
-  - _index-config.md
-```
-
-## Docusaurus Integration
-
-After running this command, use:
-
-```bash
-/docs:view
-```
-
-The generated indexes will appear in the sidebar:
-- **Browse by Category** - main hub
-- **Synchronization & Integration** - themed section
-- **GitHub Integration** - themed section
-- etc.
-
-## Best Practices
-
-1. **Run periodically** - As docs grow, re-run to update indexes
-2. **Review uncategorized** - Files without themes may need better naming
-3. **Check Docusaurus** - Preview after organizing to verify navigation
-4. **Don't move files** - Indexes are virtual, original URLs preserved
-
-## See Also
-
-- `/docs:view` - View documentation with Docusaurus
-- `/docs:build` - Build static documentation site
-- `/docs:health` - Documentation health report