@leanspec/ui 0.2.5 → 0.2.6-dev.20251125010539

package/.next/standalone/packages/ui/dist/standalone/specs/archived/050-tool-redesign-first-principles/README.md

@@ -1,400 +0,0 @@
----
-status: archived
-created: '2025-11-05'
-tags:
-  - architecture
-  - cli
-  - mcp
-  - redesign
-  - first-principles
-  - dx
-  - v0.3.0
-priority: medium
-related:
-  - 049-leanspec-first-principles
-  - 048-spec-complexity-analysis
-  - 043-official-launch-02
-created_at: '2025-11-05T00:00:00Z'
-updated_at: '2025-11-10T07:50:03.476Z'
-transitions:
-  - status: archived
-    at: '2025-11-10T07:50:03.476Z'
----
-
-# Tool Redesign: First Principles Application
-
-> **Status**: 📦 Archived · **Priority**: Medium · **Created**: 2025-11-05 · **Tags**: architecture, cli, mcp, redesign, first-principles, dx, v0.3.0
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-**Purpose**: Redesign CLI and MCP tools by applying the 5 LeanSpec first principles from spec 049, creating tools that practice what we preach.
-
-**Why Now**: 
-- We've established clear first principles (spec 049)
-- Current tools evolved organically without systematic design
-- Need to dogfood our own philosophy in the implementation
-- Opportunity to showcase first-principles thinking in practice
-
-**Key Insight**: Tools should embody the philosophy they enable. If LeanSpec optimizes for Context Economy and Signal-to-Noise, our tools must do the same.
-
-**Result**: Redesigned CLI and MCP that demonstrate first principles through their interface design, implementation structure, and user experience.
-
-## Background
-
-### Current Tool State
-
-**CLI (`lean-spec` command)**:
-- 15+ commands with inconsistent patterns
-- Some commands do too much (`stats` vs `stats --full`)
-- Error messages vary in helpfulness
-- No clear mental model for users
-
-**MCP Server**:
-- Good functionality but complex interface
-- Some operations require multiple round-trips
-- Not optimized for AI agent workflows
-- Error handling inconsistent
-
-### The First Principles (from spec 049)
-
-1. **Context Economy** - Fit in working memory (human + AI)
-2. **Signal-to-Noise Maximization** - Every word must inform decisions
-3. **Progressive Disclosure** - Start simple, add complexity when pain is felt
-4. **Intent Over Implementation** - Capture why, not just how
-5. **Bridge the Gap** - Align human intent with machine execution
-
-### Design Constraints
-
-**Human Usage** (CLI):
-- Working memory: 7±2 items
-- Need discoverable commands
-- Want quick feedback loops
-- Prefer consistent patterns
-
-**AI Usage** (MCP):
-- Token efficiency critical
-- Clear success/failure states
-- Batching for complex operations
-- Structured, parseable output
-
-## Design
-
-### Core Philosophy: Tools as Philosophy Demo
-
-**Principle**: Our tools should be the best example of LeanSpec thinking.
-
-**Application**: Every command, parameter, and output designed through first-principles lens.
-
-### CLI Redesign: Progressive Command Structure
-
-**Current Problem**: 15 commands with no clear organization
-**Solution**: Group by mental model, progressive disclosure
-
-#### Level 1: Discovery (Context Economy)
-```bash
-lean-spec                    # Show overview + 3 most common commands
-lean-spec help               # Show all commands, grouped by purpose
-lean-spec status             # Project health at-a-glance
-```
-
-#### Level 2: Core Operations (Signal-to-Noise)
-```bash
-# View/Navigate (most common)
-lean-spec list              # Smart defaults, most relevant first
-lean-spec view <spec>       # Single spec, optimized display
-lean-spec search <query>    # Focused search with ranking
-
-# Modify (when needed)
-lean-spec create <name>     # Guided creation with templates
-lean-spec update <spec>     # Status/metadata only
-lean-spec edit <spec>       # Open in editor
-
-# Project (occasional)
-lean-spec board            # Kanban view
-lean-spec stats            # Key metrics only
-```
-
-#### Level 3: Advanced (Progressive Disclosure)
-```bash
-# Analysis (when pain is felt)
-lean-spec validate         # Check first principles adherence  
-lean-spec complexity       # Detailed complexity analysis
-lean-spec deps <spec>      # Relationship analysis
-lean-spec split <spec>     # Guided spec splitting
-
-# Power User (specific needs)
-lean-spec stats --full     # Comprehensive analytics
-lean-spec export           # Various formats
-lean-spec init             # Project setup
-```
-
-**Key Changes**:
-- Grouped by frequency of use (Context Economy)
-- Each command has single clear purpose (Signal-to-Noise)  
-- Advanced features hidden until needed (Progressive Disclosure)
-- Intent clear from command name (Intent Over Implementation)
-- Same patterns work for humans and AI (Bridge the Gap)
-
-### MCP Redesign: Batch-First Architecture
-
-**Current Problem**: Many small operations, chatty interface
-**Solution**: Batch operations, rich context in responses
-
-#### Core Operations
-```typescript
-// Single spec operations (atomic)
-view(specPath: string, options?: ViewOptions) -> SpecWithContext
-update(specPath: string, changes: SpecChanges) -> SpecWithContext
-create(name: string, template: SpecTemplate) -> SpecWithContext
-
-// Multi-spec operations (batched) 
-list(filters?: Filters) -> SpecSummary[]
-search(query: string, options?: SearchOptions) -> SearchResults
-board() -> KanbanBoard
-
-// Project operations (contextual)
-stats(level?: 'basic' | 'full') -> ProjectStats  
-validate(specs?: string[]) -> ValidationReport
-health() -> ProjectHealth
-```
-
-**Key Changes**:
-- Rich context in every response (Context Economy for AI)
-- Structured errors with actionable guidance (Signal-to-Noise)
-- Batch operations reduce round-trips (Progressive Disclosure)
-- Clear success/failure states (Intent Over Implementation)
-- Same data structure for CLI/MCP (Bridge the Gap)
-
-### Shared Principles: Output Design
-
-#### Context Economy in Output
-```bash
-# Bad: Information overload
-lean-spec list
-049-leanspec-first-principles | planned | created: 2025-11-04 | priority: critical | tags: philosophy,meta,foundation,principles | related: 048-spec-complexity-analysis,043-official-launch-02,012-sub-spec-files | 1,042 lines (warning: >400) | last modified: 2 hours ago
-
-# Good: Essential info, detail on demand  
-lean-spec list
-📋 049 leanspec-first-principles (critical)
-✅ 048 spec-complexity-analysis 
-🔄 047 git-timestamps (in-progress)
-
-lean-spec list --verbose  # Detail when requested
-lean-spec view 049        # Full context for specific spec
-```
-
-#### Signal-to-Noise in Commands
-```bash
-# Bad: Ambiguous what it does
-lean-spec show 049 --with-meta --include-related --format=detailed
-
-# Good: Clear intent, smart defaults
-lean-spec view 049        # Show spec (formatted by default)
-lean-spec view 049 --raw  # Raw when needed (progressive disclosure)
-lean-spec view 049 --json # Structured when needed
-```
-
-### Implementation Strategy
-
-#### Phase 1: CLI Core Redesign
-- Implement new command grouping
-- Standardize output formats  
-- Add progressive disclosure patterns
-- Maintain backward compatibility with deprecation warnings
-
-#### Phase 2: MCP Optimization
-- Implement batch operations
-- Standardize response structures
-- Add rich error context
-- Optimize for AI workflows
-
-#### Phase 3: Integration
-- Ensure CLI and MCP use same core logic
-- Unified configuration system
-- Consistent behavior across interfaces
-- Performance optimization
-
-## Plan
-
-### Phase 1: Foundation (Week 1-2)
-**Goal**: New CLI command structure with backward compatibility
-
-**Tasks**:
-- [ ] Design new command hierarchy 
-- [ ] Implement core command groups (view/modify/project)
-- [ ] Add progressive disclosure for advanced commands
-- [ ] Create unified output formatting system
-- [ ] Add deprecation warnings for old patterns
-- [ ] Update help system to show grouped commands
-
-**Success Criteria**:
-- New users find commands intuitively
-- Output fits in terminal without scrolling (Context Economy)
-- Every command has single clear purpose (Signal-to-Noise)
-
-### Phase 2: MCP Optimization (Week 3-4)  
-**Goal**: Batch-first MCP with rich context
-
-**Tasks**:
-- [ ] Implement batch operations for multi-spec workflows
-- [ ] Redesign response structures with full context
-- [ ] Add structured error handling with actionable guidance
-- [ ] Optimize for common AI agent patterns
-- [ ] Create MCP performance benchmarks
-
-**Success Criteria**:
-- AI agents can accomplish tasks in fewer round-trips
-- Rich context reduces need for additional queries
-- Clear success/failure states for all operations
-
-### Phase 3: Integration & Polish (Week 5-6)
-**Goal**: Unified experience across interfaces
-
-**Tasks**:
-- [ ] Ensure CLI and MCP use same underlying logic
-- [ ] Create unified configuration system
-- [ ] Add cross-interface consistency tests
-- [ ] Performance optimization and profiling
-- [ ] Documentation updates reflecting new philosophy
-
-**Success Criteria**:
-- Identical behavior between CLI and MCP for same operations
-- Performance meets or exceeds current implementation
-- Documentation demonstrates first principles in practice
-
-### Phase 4: Validation (Week 7)
-**Goal**: Prove we practice what we preach
-
-**Tasks**:
-- [ ] User testing with both interfaces
-- [ ] Measure adherence to first principles
-- [ ] Gather feedback from AI agent usage
-- [ ] Performance benchmarking
-- [ ] Create case studies of improvements
-
-**Success Criteria**:
-- Tools demonstrate all 5 first principles
-- Users report improved experience
-- AI agents more efficient in workflows
-- Implementation serves as reference for first-principles design
-
-## Test
-
-### First Principles Validation
-
-**Context Economy** (Tools fit in working memory):
-- [ ] CLI commands grouped into 3 clear levels
-- [ ] MCP operations batchable to reduce context
-- [ ] Output designed for human/AI consumption limits
-
-**Signal-to-Noise Maximization** (Every element informs decisions):
-- [ ] Each command has single clear purpose
-- [ ] Output contains only actionable information
-- [ ] Error messages guide toward resolution
-
-**Progressive Disclosure** (Complexity when pain is felt):
-- [ ] Basic commands handle 80% of use cases
-- [ ] Advanced features available but not prominent
-- [ ] `--verbose` and detailed modes for when needed
-
-**Intent Over Implementation** (Why, not just how):
-- [ ] Command names reflect user goals, not system operations
-- [ ] Help text explains purpose, not just syntax
-- [ ] Error messages explain what user was trying to achieve
-
-**Bridge the Gap** (Human + AI alignment):
-- [ ] Same operations available in CLI and MCP
-- [ ] Consistent data structures across interfaces
-- [ ] Output formats optimized for both human and machine parsing
-
-### User Experience Tests
-
-**New User Journey**:
-- [ ] Can discover main commands in <2 minutes
-- [ ] Can complete basic workflow (create/view/update) without documentation
-- [ ] Advanced features discoverable when needed
-
-**AI Agent Efficiency**:
-- [ ] Common workflows require fewer tool calls
-- [ ] Batch operations reduce token usage
-- [ ] Error recovery is automated where possible
-
-**Performance Benchmarks**:
-- [ ] CLI response time <100ms for common commands
-- [ ] MCP operations complete in comparable time to current implementation  
-- [ ] Memory usage within acceptable bounds
-
-### Philosophy Demonstration
-
-**Can we say our tools demonstrate LeanSpec?**:
-- [ ] Tools embody the principles they enable
-- [ ] Implementation structure follows first principles
-- [ ] User experience optimized through first-principles lens
-- [ ] Tools serve as reference implementation for philosophy
-
-## Success Metrics
-
-**Quantitative**:
-- CLI command discovery time: <2 minutes (vs current ~5 minutes)
-- AI agent efficiency: 30% fewer tool calls for common workflows
-- User task completion: 90% success rate without documentation
-- Performance: Match or exceed current implementation
-
-**Qualitative**:
-- Tools feel "lean" and focused
-- Clear mental model for command organization
-- AI agents can use efficiently without extensive prompting
-- Implementation demonstrates first principles in practice
-
-**Philosophy Validation**:
-- Tools practice what LeanSpec preaches
-- Can point to tools as examples of first-principles thinking
-- Users understand LeanSpec philosophy through tool usage
-- Tools serve as template for future first-principles design
-
-## Notes
-
-### Why This Redesign Matters
-
-This is foundational work because:
-- **Credibility**: Tools must practice LeanSpec philosophy  
-- **Usability**: First principles create better user experiences
-- **Teaching**: Tools become examples of the methodology
-- **Scaling**: Systematic design enables growth without complexity creep
-
-### Key Design Decisions
-
-**Progressive Command Hierarchy**: Instead of flat command list, organize by frequency and complexity
-**Batch-First MCP**: Optimize for AI workflows while maintaining human usability
-**Unified Output**: Same data structures work for both CLI and MCP consumption
-**First-Principles Validation**: Every design decision justified by the 5 principles
-
-### Success Indicators
-
-We'll know this succeeded when:
-- New users intuitively discover commands
-- AI agents accomplish tasks more efficiently  
-- Tools feel like natural extensions of LeanSpec thinking
-- Implementation becomes reference for first-principles design
-
----
-
-**Remember**: We're not just building better tools. We're proving that LeanSpec philosophy creates superior user experiences when applied systematically.
-
----
-
-## Archive Note
-
-**Archived**: 2025-11-10
-
-**Reason**: Spec was too broad and many of its proposed improvements have already been implemented incrementally through other specs:
-- Spec 039: simplify-viewer-commands
-- Spec 045: unified-dashboard  
-- Spec 046: stats-dashboard-refactor
-- Spec 051: docs-system-prompt-principles
-- Spec 049: leanspec-first-principles
-
-**Key Learning**: The 7-week comprehensive redesign plan conflicted with LeanSpec's own "Progressive Disclosure" principle. Better to make incremental improvements as pain is felt rather than big-bang redesigns. The current CLI is already well-organized with grouped commands, and the MCP server functions effectively. This spec itself demonstrates why we should practice what we preach: start simple, add complexity when needed.

package/.next/standalone/packages/ui/package.json.backup

@@ -1,119 +0,0 @@
-{
-  "name": "@leanspec/ui",
-  "version": "0.2.5",
-  "description": "LeanSpec web UI launcher for visual spec management",
-  "type": "module",
-  "bin": {
-    "leanspec-ui": "./bin/ui.js"
-  },
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build && node ./scripts/post-build.mjs",
-    "start": "next start",
-    "lint": "eslint",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "tsx src/lib/db/migrate.ts",
-    "db:studio": "drizzle-kit studio",
-    "db:seed": "tsx src/lib/db/seed.ts"
-  },
-  "files": [
-    "bin/",
-    ".next/standalone/packages/",
-    ".next/standalone/node_modules/.pnpm/",
-    ".next/static/",
-    "public/",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "leanspec",
-    "spec",
-    "documentation",
-    "cli",
-    "ui"
-  ],
-  "author": "Marvin Zhang",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/codervisor/lean-spec.git"
-  },
-  "bugs": {
-    "url": "https://github.com/codervisor/lean-spec/issues"
-  },
-  "homepage": "https://lean-spec.dev",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@dagrejs/dagre": "^1.1.8",
-    "@leanspec/core": "workspace:*",
-    "@radix-ui/react-avatar": "^1.1.11",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-progress": "^1.1.8",
-    "@radix-ui/react-select": "^2.1.14",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-tooltip": "^1.2.8",
-    "better-sqlite3": "^11.7.0",
-    "chalk": "^5.3.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.0.0",
-    "cmdk": "^1.1.1",
-    "commander": "^14.0.2",
-    "dayjs": "^1.11.19",
-    "drizzle-orm": "^0.38.3",
-    "fuse.js": "^7.1.0",
-    "github-slugger": "^2.0.0",
-    "gray-matter": "^4.0.3",
-    "highlight.js": "^11.11.1",
-    "js-yaml": "^4.1.0",
-    "lucide-react": "^0.553.0",
-    "next": "16.0.1",
-    "next-themes": "^0.4.6",
-    "open": "^11.0.0",
-    "ora": "^9.0.0",
-    "react": "19.2.0",
-    "react-dom": "19.2.0",
-    "react-markdown": "^9.0.2",
-    "react-window": "^2.2.3",
-    "reactflow": "^11.11.4",
-    "recharts": "^3.4.1",
-    "rehype-highlight": "^7.0.1",
-    "rehype-slug": "^6.0.0",
-    "remark-gfm": "^4.0.0",
-    "sonner": "^2.0.7",
-    "swr": "^2.3.6",
-    "tailwind-merge": "^3.4.0",
-    "unified": "^11.0.5",
-    "unist-util-visit": "^5.0.0",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@tailwindcss/typography": "^0.5.15",
-    "@types/better-sqlite3": "^7.6.12",
-    "@types/mdast": "^4.0.4",
-    "@types/node": "^20",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "@vitest/ui": "^4.0.6",
-    "autoprefixer": "^10.4.20",
-    "drizzle-kit": "^0.31.0",
-    "eslint": "^9",
-    "eslint-config-next": "16.0.1",
-    "postcss": "^8.4.49",
-    "tailwindcss": "^3.4.17",
-    "tsx": "^4.19.2",
-    "typescript": "^5",
-    "vitest": "^4.0.6"
-  }
-}

package/.next/standalone/packages/ui/src/app/board/board-client.tsx

@@ -1,162 +0,0 @@
-'use client';
-
-import Link from 'next/link';
-import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
-import { Badge } from '@/components/ui/badge';
-import { Clock, PlayCircle, CheckCircle2, Archive } from 'lucide-react';
-import { PriorityBadge } from '@/components/priority-badge';
-import { cn } from '@/lib/utils';
-
-interface Spec {
-  id: string;
-  specNumber: number | null;
-  specName: string;
-  title: string | null;
-  status: string | null;
-  priority: string | null;
-  tags: string[] | null;
-}
-
-interface BoardClientProps {
-  initialSpecs: Spec[];
-}
-
-export function BoardClient({ initialSpecs }: BoardClientProps) {
-  const statusConfig = {
-    'planned': {
-      icon: Clock,
-      title: 'Planned',
-      colorClass: 'text-blue-600 dark:text-blue-400',
-      bgClass: 'bg-blue-50 dark:bg-blue-900/20',
-      borderClass: 'border-blue-200 dark:border-blue-800'
-    },
-    'in-progress': {
-      icon: PlayCircle,
-      title: 'In Progress',
-      colorClass: 'text-orange-600 dark:text-orange-400',
-      bgClass: 'bg-orange-50 dark:bg-orange-900/20',
-      borderClass: 'border-orange-200 dark:border-orange-800'
-    },
-    'complete': {
-      icon: CheckCircle2,
-      title: 'Complete',
-      colorClass: 'text-green-600 dark:text-green-400',
-      bgClass: 'bg-green-50 dark:bg-green-900/20',
-      borderClass: 'border-green-200 dark:border-green-800'
-    },
-    'archived': {
-      icon: Archive,
-      title: 'Archived',
-      colorClass: 'text-gray-600 dark:text-gray-400',
-      bgClass: 'bg-gray-50 dark:bg-gray-900/20',
-      borderClass: 'border-gray-200 dark:border-gray-800'
-    }
-  };
-
-  const statuses = ['planned', 'in-progress', 'complete', 'archived'] as const;
-  const columns = statuses.map(status => ({
-    status,
-    config: statusConfig[status],
-    specs: initialSpecs.filter(spec => spec.status === status),
-  }));
-
-  return (
-    <div className="min-h-screen bg-background">
-      <section className="container mx-auto px-4 py-8">
-        <div className="mb-8">
-          <h1 className="text-4xl font-bold tracking-tight">Kanban Board</h1>
-          <p className="text-muted-foreground mt-2">Track spec progress across all statuses</p>
-        </div>
-
-        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
-          {columns.map(column => {
-            const Icon = column.config.icon;
-            return (
-              <div key={column.status} className="flex flex-col">
-                <div className={cn(
-                  "sticky top-14 z-40 mb-4 p-3 rounded-lg border-2 bg-background",
-                  column.config.bgClass,
-                  column.config.borderClass
-                )}>
-                  <h2 className={cn(
-                    "text-lg font-semibold flex items-center gap-2",
-                    column.config.colorClass
-                  )}>
-                    <Icon className="h-5 w-5" />
-                    {column.config.title}
-                    <Badge variant="outline" className="ml-auto">{column.specs.length}</Badge>
-                  </h2>
-                </div>
-
-                <div className="space-y-3 flex-1">
-                  {column.specs.map(spec => {
-                    // Get priority color for left border
-                    const priorityColors = {
-                      'critical': 'border-l-red-500',
-                      'high': 'border-l-orange-500',
-                      'medium': 'border-l-blue-500',
-                      'low': 'border-l-gray-400'
-                    };
-                    const borderColor = priorityColors[spec.priority as keyof typeof priorityColors] || priorityColors.medium;
-
-                    return (
-                      <Card 
-                        key={spec.id} 
-                        className={cn(
-                          "hover:shadow-lg transition-all duration-150 hover:scale-[1.02] border-l-4 cursor-pointer border-gray-200 dark:border-gray-800",
-                          borderColor
-                        )}
-                        onClick={() => window.location.href = `/specs/${spec.specNumber || spec.id}`}
-                      >
-                        <CardHeader className="pb-3">
-                          <Link href={`/specs/${spec.specNumber || spec.id}`}>
-                            <CardTitle className="text-sm font-medium hover:text-primary transition-colors">
-                              {spec.specNumber ? `#${spec.specNumber}` : spec.specName}
-                            </CardTitle>
-                          </Link>
-                        </CardHeader>
-                        <CardContent className="space-y-2">
-                          <p className="text-sm text-muted-foreground line-clamp-2">
-                            {spec.title || spec.specName}
-                          </p>
-                          
-                          <div className="flex items-center gap-2 flex-wrap">
-                            {spec.priority && <PriorityBadge priority={spec.priority} />}
-                            
-                            {spec.tags && spec.tags.length > 0 && (
-                              <>
-                                {spec.tags.slice(0, 2).map(tag => (
-                                  <Badge key={tag} variant="outline" className="text-xs">
-                                    {tag}
-                                  </Badge>
-                                ))}
-                                {spec.tags.length > 2 && (
-                                  <Badge variant="outline" className="text-xs">
-                                    +{spec.tags.length - 2}
-                                  </Badge>
-                                )}
-                              </>
-                            )}
-                          </div>
-                        </CardContent>
-                      </Card>
-                    );
-                  })}
-
-                  {column.specs.length === 0 && (
-                    <Card className="border-dashed border-gray-300 dark:border-gray-700">
-                      <CardContent className="py-8 text-center">
-                        <Icon className={cn("mx-auto h-8 w-8 mb-2", column.config.colorClass, "opacity-50")} />
-                        <p className="text-sm text-muted-foreground">No {column.config.title.toLowerCase()} specs</p>
-                      </CardContent>
-                    </Card>
-                  )}
-                </div>
-              </div>
-            );
-          })}
-        </div>
-      </section>
-    </div>
-  );
-}