@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/034-copilot-slash-commands/README.md

@@ -0,0 +1,107 @@
+---
+status: planned
+created: '2025-11-03'
+tags:
+  - vscode
+  - copilot
+  - ai
+  - ux
+  - v0.2.0-optional
+priority: medium
+created_at: '2025-11-03T00:00:00Z'
+updated_at: '2025-11-05T05:03:54.950Z'
+depends_on:
+  - 067-monorepo-core-extraction
+  - 017-vscode-extension
+---
+
+# GitHub Copilot Chat Slash Commands & Prompts
+
+> **Status**: 🗓️ Planned · **Priority**: Medium · **Created**: 2025-11-03 · **Tags**: vscode, copilot, ai, ux, v0.2.0-optional
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Add LeanSpec integration directly into VS Code via GitHub Copilot Chat using slash commands and chat participants. This enables developers to interact with specs naturally through Copilot chat without leaving their coding context.
+
+**Why now?** Copilot Chat is where developers already ask questions and get guidance. Integrating LeanSpec here makes specs discoverable and actionable at the exact moment they're needed—when writing code.
+
+## Design
+
+**Implementation Options:**
+
+**Option A: Chat Participant** (Recommended)
+- Register `@lean-spec` chat participant via VS Code extension
+- Natural language interactions: `@lean-spec what's the status of auth system?`
+- Context-aware: can reference open files, workspace, current work
+
+**Option B: Slash Commands**
+- Register commands like `/lspec-search`, `/lspec-create`, `/lspec-status`
+- More structured but less conversational
+- Fallback if participant API has limitations
+
+**Key Features:**
+- `/lean-spec search <query>` or `@lean-spec search for authentication specs`
+- `/lean-spec status` or `@lean-spec show me what's in progress`
+- `/lean-spec create` or `@lean-spec help me create a spec for this feature`
+- `/lean-spec read <spec>` or `@lean-spec show me the API redesign spec`
+- `/lean-spec update <spec> --status <status>` or `@lean-spec mark auth-system as complete`
+
+**Context Integration:**
+- Automatically detect related specs based on open files
+- Suggest creating specs when Copilot detects new feature work
+- Link spec references in code comments to full specs
+
+**Architecture:**
+- Extend existing VS Code extension (spec 006)
+- Use VS Code Chat Participant API or Slash Command API
+- Reuse LeanSpec CLI logic via TypeScript imports
+- Return formatted markdown with links to specs
+
+## Plan
+
+- [ ] Research VS Code Chat Participant API vs Slash Command API
+- [ ] Choose implementation approach (likely Chat Participant)
+- [ ] Extend VS Code extension package
+- [ ] Implement spec search with Copilot Chat
+- [ ] Add spec status queries and visualization
+- [ ] Enable spec creation through conversational flow
+- [ ] Add spec reading/preview in chat
+- [ ] Implement status updates
+- [ ] Add context-aware spec suggestions
+- [ ] Test with real development workflows
+- [ ] Document in extension README and docs
+
+## Test
+
+- [ ] Chat participant/commands register successfully
+- [ ] Search returns relevant results with correct formatting
+- [ ] Status queries show accurate current state
+- [ ] Create flow guides user through spec creation
+- [ ] Read command displays spec content clearly
+- [ ] Update commands modify specs correctly
+- [ ] Context awareness suggests relevant specs
+- [ ] Works alongside other Copilot features
+- [ ] Handles workspaces without LeanSpec gracefully
+
+## Notes
+
+**GitHub Copilot Chat APIs:**
+- Chat Participants: https://code.visualstudio.com/api/extension-guides/chat
+- Language Model API for context
+
+**Design Principles:**
+- Conversational over command-line syntax
+- Smart defaults based on workspace context
+- Clear feedback and error messages
+- Don't interrupt flow—augment it
+
+**Related:**
+- VS Code extension (spec 006) - base extension to extend
+- MCP server (spec 019) - similar capabilities, different context (Claude Desktop vs VS Code)
+
+**Open Questions:**
+- Should this replace or complement the VS Code extension sidebar?
+- Can we auto-generate spec suggestions from PR descriptions?

package/.next/standalone/packages/ui/dist/standalone/specs/035-live-specs-showcase/ARCHITECTURE.md

@@ -0,0 +1,244 @@
+# Architecture & Technical Design
+
+Technical architecture, technology stack, database schema, and GitHub integration strategy for LeanSpec Web.
+
+## System Architecture
+
+**Three-Tier Architecture:**
+```
+Frontend (Next.js + React)
+    ↓
+API Layer (Next.js API Routes)
+    ↓
+Database (PostgreSQL/SQLite) + GitHub API
+```
+
+**Data Flow:**
+1. Frontend requests data from API
+2. API checks database cache
+3. If cache miss/stale, fetch from GitHub
+4. Parse and store in database
+5. Return to frontend
+
+**Storage Strategy:**
+- **GitHub**: Source of truth (authoritative, versioned)
+- **Database**: Performance layer (fast queries, caching)
+- Best of both: Reliability + Speed + Decoupled from API limits
+
+## Technology Stack
+
+### Frontend
+- **Framework**: Next.js 16+ (App Router, Server Components)
+- **Styling**: Tailwind CSS v3 + shadcn/ui
+- **Markdown**: react-markdown + rehype-highlight + remark-gfm
+- **State**: React Query (TanStack Query)
+- **Theme**: next-themes (dark/light/system)
+
+### Backend
+- **API**: Next.js API Routes (serverless)
+- **Database**: PostgreSQL (prod) / SQLite (dev)
+- **ORM**: Drizzle ORM with type-safe queries
+- **GitHub**: Octokit.js (official client)
+- **Cache**: Redis (optional, for rate limiting)
+
+### Infrastructure
+- **Hosting**: Vercel (recommended) or Railway/Fly.io
+- **Database**: Neon (PostgreSQL) or Turso (SQLite on edge)
+- **Deployment**: Zero-config CI/CD via Vercel
+
+## Database Schema
+
+### Projects
+```sql
+CREATE TABLE projects (
+  id UUID PRIMARY KEY,
+  github_owner TEXT NOT NULL,
+  github_repo TEXT NOT NULL,
+  display_name TEXT,
+  description TEXT,
+  stars INTEGER DEFAULT 0,
+  is_public BOOLEAN DEFAULT true,
+  is_featured BOOLEAN DEFAULT false,
+  last_synced_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(github_owner, github_repo)
+);
+```
+
+### Specs
+```sql
+CREATE TABLE specs (
+  id UUID PRIMARY KEY,
+  project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
+  spec_number INTEGER,
+  spec_name TEXT NOT NULL,
+  title TEXT,
+  status TEXT CHECK(status IN ('planned', 'in-progress', 'complete', 'archived')),
+  priority TEXT CHECK(priority IN ('low', 'medium', 'high', 'critical')),
+  tags TEXT[],
+  assignee TEXT,
+  content_md TEXT NOT NULL,
+  created_at TIMESTAMP,
+  updated_at TIMESTAMP,
+  completed_at TIMESTAMP,
+  file_path TEXT NOT NULL,
+  github_url TEXT,
+  synced_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(project_id, spec_number)
+);
+
+CREATE INDEX idx_specs_project ON specs(project_id);
+CREATE INDEX idx_specs_status ON specs(status);
+```
+
+### Spec Relationships
+```sql
+CREATE TABLE spec_relationships (
+  id UUID PRIMARY KEY,
+  spec_id UUID REFERENCES specs(id) ON DELETE CASCADE,
+  related_spec_id UUID REFERENCES specs(id) ON DELETE CASCADE,
+  relationship_type TEXT CHECK(relationship_type IN ('depends_on', 'related')),
+  UNIQUE(spec_id, related_spec_id, relationship_type)
+);
+```
+
+### Sync Logs
+```sql
+CREATE TABLE sync_logs (
+  id UUID PRIMARY KEY,
+  project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
+  status TEXT CHECK(status IN ('pending', 'running', 'success', 'failed')),
+  specs_added INTEGER DEFAULT 0,
+  specs_updated INTEGER DEFAULT 0,
+  specs_deleted INTEGER DEFAULT 0,
+  error_message TEXT,
+  started_at TIMESTAMP DEFAULT NOW(),
+  completed_at TIMESTAMP
+);
+```
+
+## API Design
+
+### Endpoints
+```
+GET  /api/projects              - List all projects
+GET  /api/projects/:id          - Get project details
+POST /api/projects              - Add new project
+GET  /api/projects/:id/specs    - List project specs
+GET  /api/specs/:id             - Get spec details
+GET  /api/stats                 - Global statistics
+GET  /api/search?q=query        - Full-text search
+POST /api/projects/:id/sync     - Trigger sync
+```
+
+### Response Format
+```json
+{
+  "data": { /* resource */ },
+  "meta": { "total": 42, "page": 1 }
+}
+```
+
+## GitHub Integration
+
+### Sync Mechanisms
+
+**1. Manual Trigger (MVP)**
+User adds GitHub URL → immediate sync
+
+**2. Scheduled Sync (Phase 2)**
+- Featured projects: Every 6 hours
+- Active projects: Daily
+- Inactive projects: Weekly
+
+**3. Webhooks (Phase 4)**
+Real-time updates when repo changes
+
+### Sync Process
+
+**Discovery:**
+1. Fetch repository tree via API (recursive)
+2. Filter files matching `specs/*/README.md` pattern
+3. Exclude `specs/archived/**`
+
+**Parsing:**
+1. Download file content from GitHub
+2. Parse frontmatter (reuse `spec-loader.ts` from CLI)
+3. Extract markdown content
+4. Generate GitHub URL
+
+**Storage:**
+1. Upsert project record
+2. Upsert specs (match by spec_number or file_path)
+3. Handle deletions (soft delete)
+4. Upsert relationships
+5. Log results in sync_logs
+
+### Rate Limiting
+
+GitHub API limits:
+- Authenticated: 5000 req/hour
+- Unauthenticated: 60 req/hour
+
+**Strategies:**
+- Conditional requests (ETags)
+- Response caching (Redis/database)
+- Request batching (tree API)
+- Rate limit monitoring
+- Exponential backoff on errors
+- Prioritization (manual > featured > active)
+
+### Error Handling
+
+- **404 Repo Not Found**: Mark unavailable, keep for history
+- **429 Rate Limit**: Pause until reset, queue job
+- **Parse Errors**: Log error, continue with other specs
+- **Network Timeouts**: Retry with backoff, alert if persistent
+
+## Caching Strategy
+
+**Layer 1: Database (Primary)**
+- Parsed spec content
+- Fast indexed queries
+- TTL: Until next sync (~24h)
+
+**Layer 2: React Query (Client)**
+- In-memory cache
+- Background refetch
+- TTL: 5min stale / 30min cache
+
+**Layer 3: Redis (Optional)**
+- GitHub API responses
+- Rate limit tracking
+- TTL: 1 hour
+
+**Invalidation:**
+- Manual/scheduled sync → invalidate project
+- Stale-while-revalidate pattern
+- Optimistic updates for mutations
+
+## Security
+
+- Sanitize user inputs (prevent SSRF, XSS)
+- Validate GitHub URLs (whitelist domains)
+- Rate limit API endpoints
+- Parameterized queries (prevent SQL injection)
+- Environment variables for secrets
+- CORS configuration
+
+## Performance
+
+- Database indexes on frequent queries
+- Connection pooling
+- Code splitting per route
+- Image optimization (Next.js Image)
+- Lazy loading heavy components
+- Response compression (gzip/brotli)
+
+## Future Enhancements
+
+- Private repo support (OAuth)
+- Real-time webhooks
+- Multi-branch support
+- Cross-repo relationships
+- Version history/diffs