@leanspec/ui 0.2.7-dev.20251126090633 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/017-vscode-extension/README.md

@@ -0,0 +1,261 @@
+---
+status: planned
+created: '2025-11-02'
+tags: ["feature","ide","vscode"]
+priority: low
+depends_on:
+  - 067-monorepo-core-extraction
+---
+
+# vscode-extension
+
+> **Status**: 📅 Planned · **Priority**: Medium · **Created**: 2025-11-02
+
+## Overview
+
+Create a VS Code extension that integrates LeanSpec directly into the editor, providing inline spec management, navigation, and AI agent integration.
+
+**Developer Pain Points:**
+- Switching between editor and terminal for spec management
+- Finding specs across folder structure
+- No syntax highlighting for spec frontmatter
+- AI agents can't easily reference specs during coding
+- Manual updating of spec status
+
+**What Success Looks Like:**
+- Create/edit specs without leaving VS Code
+- Tree view showing all specs with status indicators
+- Quick actions to update spec metadata
+- Frontmatter validation and autocomplete
+- Integration with GitHub Copilot context
+
+## Design
+
+### 1. Extension Features
+
+**Spec Explorer (Tree View)**
+```
+LEANSPEC SPECS
+├── 📅 20251102/
+│   ├── ✅ 001-custom-spec-templates/
+│   ├── 📅 002-complete-custom-frontmatter/
+│   └── 🔨 003-npm-publishing/
+├── ✅ 20251101/
+│   └── ✅ 001-existing-project-integration/
+└── 📅 Planned (3)
+    🔨 In Progress (1)
+    ✅ Complete (9)
+```
+
+**Quick Actions:**
+- Right-click spec → Update Status
+- Right-click spec → Archive
+- Right-click spec → Open in Editor
+- Right-click spec → Copy Path
+
+**Commands (Ctrl+Shift+P):**
+- `LeanSpec: Create New Spec`
+- `LeanSpec: Update Spec Status`
+- `LeanSpec: Show Stats`
+- `LeanSpec: Show Board`
+- `LeanSpec: Search Specs`
+- `LeanSpec: Validate All Specs`
+
+**Status Bar:**
+```
+📋 LeanSpec: 3 planned, 1 in progress, 9 complete
+```
+
+### 2. Editor Features
+
+**Frontmatter Validation:**
+- Syntax highlighting for YAML frontmatter
+- Red squiggles for invalid fields
+- Autocomplete for status, priority, tags
+- Hover tooltips showing field descriptions
+
+**Snippets:**
+- `lspec-spec` → Full spec template
+- `lspec-front` → Frontmatter block
+- `lspec-plan` → Plan section with checkboxes
+
+**CodeLens:**
+```markdown
+---
+status: planned
+---
+👆 Update Status | 🔄 Sync Metadata
+
+# My Feature Spec
+```
+
+### 3. AI Agent Integration
+
+**Copilot Context Provider:**
+```typescript
+// Enable Copilot to reference specs
+vscode.lm.registerContextProvider('leanspec', {
+  provideContext(query) {
+    // Search specs matching query
+    // Return relevant spec content
+  }
+});
+```
+
+**Usage:**
+```
+@leanspec How should I implement the API endpoints?
+// Copilot gets context from relevant specs
+```
+
+### 4. Extension Architecture
+
+```typescript
+// Extension structure
+src/
+├── extension.ts              # Activation
+├── commands/
+│   ├── createSpec.ts
+│   ├── updateSpec.ts
+│   └── searchSpecs.ts
+├── providers/
+│   ├── SpecTreeProvider.ts   # Tree view
+│   ├── FrontmatterValidator.ts
+│   ├── CompletionProvider.ts # Autocomplete
+│   └── CopilotProvider.ts    # AI context
+├── views/
+│   └── statsWebview.ts       # Stats dashboard
+└── utils/
+    └── lspecClient.ts        # Wrap CLI commands
+```
+
+### 5. Configuration
+
+```json
+{
+  "leanspec.specsDirectory": "specs",
+  "leanspec.autoRefresh": true,
+  "leanspec.showStatusBar": true,
+  "leanspec.validateOnSave": true,
+  "leanspec.copilotIntegration": true
+}
+```
+
+## Plan
+
+### Phase 1: Core Extension Setup
+- [ ] Initialize VS Code extension project
+- [ ] Set up TypeScript, webpack bundling
+- [ ] Create extension manifest (package.json)
+- [ ] Set up activation events
+- [ ] Install lean-spec as dependency
+
+### Phase 2: Spec Explorer Tree View
+- [ ] Implement SpecTreeProvider
+- [ ] Load specs from workspace
+- [ ] Display folder structure with icons
+- [ ] Show status indicators (icons)
+- [ ] Add click to open spec
+- [ ] Add refresh button
+
+### Phase 3: Commands & Quick Actions
+- [ ] Implement `Create New Spec` command
+- [ ] Implement `Update Status` command
+- [ ] Implement `Show Stats` command
+- [ ] Implement `Search Specs` command
+- [ ] Add context menu items to tree view
+- [ ] Add status bar item with spec counts
+
+### Phase 4: Editor Features
+- [ ] Add frontmatter syntax highlighting
+- [ ] Implement validation diagnostics
+- [ ] Add autocomplete for frontmatter fields
+- [ ] Create spec snippets
+- [ ] Add CodeLens for quick actions
+- [ ] Add hover tooltips
+
+### Phase 5: AI Integration
+- [ ] Research Copilot Context Provider API
+- [ ] Implement context provider
+- [ ] Test with GitHub Copilot
+- [ ] Add configuration toggle
+
+### Phase 6: Polish & Publishing
+- [ ] Create extension icon
+- [ ] Write comprehensive README
+- [ ] Add screenshots/GIFs
+- [ ] Test on Windows, macOS, Linux
+- [ ] Publish to VS Code Marketplace
+- [ ] Link from lean-spec README
+
+## Test
+
+### Tree View Tests
+- [ ] Tree view loads specs correctly
+- [ ] Icons match spec status
+- [ ] Click opens spec file
+- [ ] Refresh updates tree
+- [ ] Works with empty specs directory
+
+### Command Tests
+- [ ] Create spec command works
+- [ ] Update status command works
+- [ ] Commands show in palette
+- [ ] Status bar updates on changes
+
+### Editor Tests
+- [ ] Frontmatter validation detects errors
+- [ ] Autocomplete suggests valid values
+- [ ] Snippets expand correctly
+- [ ] CodeLens actions work
+
+### Integration Tests
+- [ ] Extension activates in workspace with .lean-spec/
+- [ ] Works with all templates
+- [ ] Handles spec creation/deletion
+- [ ] File watcher updates on external changes
+
+### Copilot Tests
+- [ ] Context provider registers
+- [ ] Copilot can query specs
+- [ ] Returns relevant spec content
+
+## Notes
+
+**VS Code Extension API:**
+- TreeDataProvider for tree view
+- DiagnosticCollection for validation
+- CompletionItemProvider for autocomplete
+- CodeLensProvider for inline actions
+- StatusBarItem for status display
+- FileSystemWatcher for auto-refresh
+
+**Marketplace Listing:**
+- Name: "LeanSpec"
+- Description: "Lightweight spec management for AI-powered development"
+- Categories: Programming Languages, Other
+- Icon: 📋 or spec document icon
+- Keywords: spec, sdd, documentation, ai, agent
+
+**Bundle Size:**
+- Keep extension lightweight (< 5MB)
+- Use webpack to bundle dependencies
+- Consider using CLI as subprocess vs. importing
+
+**Future Enhancements:**
+- Spec dependency graph visualization
+- Inline spec preview in hover
+- Spec templates gallery
+- Integration with other AI tools (Cursor, etc.)
+- Spec metrics dashboard (webview)
+- Git blame integration (show who wrote spec)
+
+**Alternative Approach:**
+- Could build as Language Server Protocol (LSP)
+- Would enable support for other editors (Neovim, etc.)
+- More complex but more portable
+
+**References:**
+- VS Code Extension API: https://code.visualstudio.com/api
+- Tree View Guide: https://code.visualstudio.com/api/extension-guides/tree-view
+- Copilot Context: https://code.visualstudio.com/api/extension-guides/language-model

package/.next/standalone/packages/ui/dist/standalone/specs/018-spec-validation/CLI-DESIGN.md

@@ -0,0 +1,380 @@
+# CLI Design
+
+Command-line interface for the `lean-spec validate` command.
+
+**Note:** This spec originally proposed expanding `lean-spec check`, but the implementation created a separate `lean-spec validate` command for comprehensive quality validation, while keeping `lean-spec check` focused on sequence conflicts.
+
+## Basic Usage
+
+### Current Implementation (v0.2.0)
+
+```bash
+# Validate all specs (runs: line count + frontmatter)
+lean-spec validate
+
+# Validate specific specs
+lean-spec validate 018
+lean-spec validate 043 048 018          # Multiple specs
+
+# Custom line limit
+lean-spec validate --max-lines 500
+lean-spec validate 018 --max-lines 300
+
+# For sequence conflicts (separate command)
+lean-spec check
+```
+
+### Planned Enhancements (v0.3.0+)
+
+```bash
+# Validate specific aspects
+lean-spec validate --frontmatter        # Only frontmatter validation
+lean-spec validate --structure          # Only structure validation
+lean-spec validate --content            # Only content validation
+lean-spec validate --corruption         # Only corruption detection
+lean-spec validate --staleness          # Only staleness detection
+lean-spec validate --sub-specs          # Only sub-spec validation
+
+# Combine validations
+lean-spec validate --frontmatter --structure
+lean-spec validate --sub-specs --structure  # Check sub-specs and main structure
+
+# Skip certain checks
+lean-spec validate --no-staleness       # Skip staleness warnings
+
+# Filter which specs to validate
+lean-spec validate --status=in-progress
+lean-spec validate --tag=api
+```
+
+## Output Options
+
+```bash
+# Output formatting
+lean-spec validate --format=json        # JSON output for CI
+lean-spec validate --quiet              # Brief output (errors only)
+lean-spec validate --verbose            # Detailed output with explanations
+
+# Behavior options
+lean-spec validate --strict             # Fail on warnings (not just errors)
+lean-spec validate --fix                # Auto-fix issues where possible
+```
+
+## Command Evolution
+
+### Current Implementation (v0.2.0+)
+
+Two separate commands with distinct purposes:
+
+```bash
+lean-spec check               # Fast sequence conflict detection
+lean-spec validate            # Comprehensive quality validation
+lean-spec validate [specs...] # Validate specific specs
+```
+
+### Planned Enhancements (v0.3.0+)
+
+Expand `lean-spec validate` with additional validation rules:
+
+```bash
+lean-spec validate --all           # All validation rules
+lean-spec validate --frontmatter   # Frontmatter validation
+lean-spec validate --structure     # Structure validation
+lean-spec validate --corruption    # Corruption detection
+```
+
+## Console Output Format
+
+### Current Output (v0.2.0)
+
+**Actual output format:**
+```
+Validating specs...
+
+Line Count:
+  ✓ 018-spec-validation (255 lines)
+  ⚠ 051-docs-system-prompt-principles (340 lines - approaching limit)
+     → Consider simplification or splitting
+  ✗ 048-spec-complexity-analysis (601 lines - exceeds limit!)
+     → Spec exceeds 400 lines (601 lines)
+     → Consider splitting into sub-specs using spec 012 pattern
+
+Frontmatter:
+  ✓ All 25 spec(s) passed
+
+Results: 25 specs validated, 3 error(s), 6 warning(s)
+```
+
+**Features:**
+- Groups results by validator type (Line Count, Frontmatter, etc.)
+- Clear pass/warn/error indicators (✓ ⚠ ✗)
+- Actionable suggestions for each issue
+- Summary with counts
+
+### Planned Output (v0.3.0+)
+
+```
+📋 Validating specs...
+
+Line Count:
+  ✓ 10 specs within limits
+  ⚠ 1 spec approaching limit (300-400 lines)
+  ✗ 1 spec exceeds limit (>400 lines)
+
+Frontmatter:
+  ✗ 1 spec has errors:
+    - specs/044-spec-relationships-clarity/
+      • Missing required field: created
+      • Invalid status: "wip"
+
+Structure:
+  ✗ 1 spec has errors:
+    - specs/044-spec-relationships-clarity/
+      • Missing required section: ## Testing
+
+Sub-Specs:
+  ⚠ 2 warnings:
+    - specs/018-spec-validation/
+      ⚠ Sub-spec TESTING.md (421 lines) exceeds 400 line limit
+      ⚠ Orphaned sub-spec: DEPRECATED.md (not linked from README.md)
+  ✓ All other specs with sub-specs are valid
+
+Corruption:
+  ✗ 1 spec corrupted:
+    - specs/018-spec-validation/
+      • Duplicate section: "Auto-Fix Capability" (lines 245, 320)
+      • Malformed code block (line 67)
+      • Incomplete JSON (line 156)
+
+Content:
+  ⚠ 1 warning:
+    - specs/043-official-launch-02/
+      ⚠ In progress for 45 days
+
+Results: 8/12 passed, 2 warnings, 4 errors
+
+Note: For sequence conflicts, run `lean-spec check`
+```
+
+### Quiet Output
+
+```
+✗ 2 specs with errors
+```
+
+### Verbose Output
+
+```
+📋 Validating specs...
+
+Line Count:
+  ✓ 10 specs within limits
+  
+  Checked 12 specs total
+  - 10 specs under 300 lines (ideal)
+  - 1 spec 300-400 lines (warning zone)
+  - 1 spec over 400 lines (should split)
+
+Frontmatter:
+  ✗ 1 spec has errors:
+  
+    specs/044-spec-relationships-clarity/
+      • Missing required field: created
+        → Fix: Add 'created: YYYY-MM-DD' to frontmatter
+      
+      • Invalid status: "wip"
+        → Valid values: planned, in-progress, complete, archived
+        → Fix: Change status to one of the valid values
+
+... (more detailed explanations)
+```
+
+## JSON Output Format
+
+For CI/CD integration:
+
+```json
+{
+  "summary": {
+    "total": 12,
+    "passed": 10,
+    "failed": 2,
+    "warnings": 1,
+    "checks": {
+      "sequences": {"passed": true, "conflicts": 0},
+      "frontmatter": {"passed": false, "errors": 2},
+      "structure": {"passed": false, "errors": 1},
+      "corruption": {"passed": false, "errors": 3},
+      "content": {"passed": true, "warnings": 1}
+    }
+  },
+  "results": [
+    {
+      "path": "specs/018-spec-validation/",
+      "valid": false,
+      "checks": {
+        "sequences": {"passed": true},
+        "frontmatter": {"passed": true},
+        "structure": {"passed": true},
+        "corruption": {
+          "passed": false,
+          "errors": [
+            {
+              "type": "duplicate-section",
+              "message": "Duplicate section: 'Auto-Fix Capability'",
+              "locations": [245, 320],
+              "severity": "error",
+              "fixable": true
+            },
+            {
+              "type": "malformed-code-block",
+              "message": "Code block not properly closed",
+              "line": 67,
+              "severity": "error",
+              "fixable": false
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+## Exit Codes
+
+- `0` - All checks passed
+- `1` - Errors found (any check failed)
+- `2` - Warnings found (only in --strict mode)
+- `3` - Command error (invalid arguments, etc.)
+
+**Note:** `lean-spec check` (sequence conflicts) uses same exit code pattern.
+
+## Auto-Fix Mode
+
+```bash
+lean-spec validate --fix
+```
+
+**What Gets Fixed:**
+- Missing frontmatter fields (adds with defaults)
+- Date formatting (converts to ISO 8601)
+- Duplicate sections (removes duplicates, keeps first)
+- Unclosed code blocks (closes them)
+- Visual badges (updates from frontmatter)
+- Missing sub-spec references in README.md (adds links)
+
+**What Doesn't Get Fixed:**
+- Invalid status values (requires decision)
+- Empty sections (requires content)
+- Broken links (requires investigation)
+- Complex corruption (requires judgment)
+- Sub-specs exceeding line limits (requires manual splitting)
+- Orphaned sub-specs (requires decision to keep or remove)
+
+**Output:**
+```
+📋 Checking and fixing specs...
+
+Fixed 3 issues:
+  ✓ specs/044-spec-relationships-clarity/
+    • Added missing field: created = 2025-11-04
+    • Formatted date: 2025/11/04 → 2025-11-04
+  
+  ✓ specs/018-spec-validation/
+    • Removed duplicate section: "Auto-Fix Capability"
+
+Could not auto-fix 2 issues:
+  ✗ specs/044-spec-relationships-clarity/
+    • Invalid status: "wip" - Please use: planned, in-progress, complete, archived
+
+Results: Auto-fixed 3/5 issues
+```
+
+## Filtering Specs
+
+```bash
+# By status
+lean-spec validate --status=in-progress
+lean-spec validate --status=planned,in-progress
+
+# By tag
+lean-spec validate --tag=api
+lean-spec validate --tag=quality,validation
+
+# By priority
+lean-spec validate --priority=high,critical
+
+# By path pattern
+lean-spec validate specs/2025*
+lean-spec validate specs/archived/
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+- name: Check spec quality
+  run: |
+    lean-spec validate --format=json --strict > validate-results.json
+  continue-on-error: true
+
+- name: Comment PR with results
+  uses: actions/github-script@v6
+  with:
+    script: |
+      const results = require('./validate-results.json');
+      // Post comment with results
+```
+
+### Pre-Commit Hook
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+
+# Run comprehensive validation
+lean-spec validate --format=json > /dev/null 2>&1
+
+if [ $? -ne 0 ]; then
+  echo "❌ Spec quality checks failed!"
+  echo "Run 'lean-spec validate' to see details"
+  echo "Run 'lean-spec validate --fix' to auto-fix issues"
+  exit 1
+fi
+
+echo "✓ All spec quality checks passed"
+```
+
+## Design Decisions
+
+### Why Separate `validate` Command (Implementation Choice)
+
+The original spec proposed expanding `lean-spec check`, but the implementation created a separate `lean-spec validate` command:
+
+**Rationale:**
+1. **Separation of concerns**: Sequence checking is fast/targeted; validation is comprehensive
+2. **Performance**: Users can run quick sequence checks without validation overhead
+3. **Backwards compatible**: Existing `lean-spec check` behavior unchanged
+4. **Incremental adoption**: Can add validation rules without affecting check command
+5. **Clearer intent**: `validate` explicitly signals quality checking vs. `check` for conflicts
+
+**Trade-offs:**
+- Two commands to remember (but both are intuitive)
+- More CLI surface area
+- Better performance and flexibility
+
+### Flag Design Philosophy
+
+- **Positive flags**: Enable specific validations (`--frontmatter`, `--structure`)
+- **Negative flags**: Disable validations (`--no-staleness`)
+- **Default**: All available validations when no flags specified
+- **Specificity**: Can validate individual specs or filter by status/tags
+
+### Performance Considerations
+
+- Fast by default (< 1s for 100 specs)
+- Parallel spec loading
+- Incremental checking (only changed specs in auto-check)
+- Caching of check results