LeanSpec

This specification outlines the refactoring of the ui-vite project's routing and layout structure to align it with the Next.js implementation pattern. The goal is to resolve inconsistencies in how routes, layouts, and global state are managed.

Key Problems Addressed:

• Router Structure: Moving from inconsistent programmatic react-router usage toward a more structured approach that mirrors Next.js file-based routing (using root layouts to wrap pages).
• Layout Inconsistency: Standardizing the use of layouts (e.g., SpecsLayout vs. Layout) across different route paths like /projects/:projectId/specs/:specName.
• Global State Positioning: Aligning where providers (Theme, Project, I18n) reside. In Next.js, these are in the root layout; in ui-vite, they are currently in App.tsx.
• Navigation vs Layout: Decoupling the Navigation component from the Layout component to treat navigation as a separate concern in the layout composition.

Objectives:

• Create a cleaner separation of concerns.
• Ensure consistent route definitions.
• Facilitate further UI parity work (related to Spec 193 and Spec 190).

The @leanspec/ui-components package is a framework-agnostic, tree-shakeable React component library designed to serve both web (Next.js/Vite) and desktop (Tauri) environments. It consolidates UI elements previously duplicated across packages/ui and packages/desktop into a single source of truth.

Key Features

• Framework-Agnostic: Components use callback props for navigation and state changes instead of framework-specific hooks (like next/router), making them compatible with any React setup.
• Tree-shakeable: Built with Vite to ensure users only bundle the components they actually import.
• Comprehensive Suite: Includes spec management (lists, details, cards), visualizations (dependency graphs, charts), search/filter tools, and layout primitives.
• Design Standards: Built with React 18, TypeScript 5, Tailwind CSS 3, and supports dark mode and responsive design.

The LeanSpec CLI is a toolkit for managing specifications throughout their lifecycle. It is designed to be used by both human developers and AI agents. It supports creating, searching, tracking, and validating specifications.

Core Command Categories

• Creating & Managing: Core operations like create, update, view, and open.
• Finding Specs: Discovery tools like list, search, and deps (dependencies).
• Project Management: Health and quality tools like board (Kanban view), stats (metrics), and validate (quality checks).

Integration Capabilities

• Version Control: Specs are stored as plain markdown files, making them compatible with Git and easy to review in Pull Requests.
• CI/CD: You can automate quality checks in pipelines (e.g., running lean-spec validate in GitHub Actions).
• Editors: Use lean-spec open <spec> to open a specification in your preferred editor.
• AI Agents: Agents can interact via direct CLI calls or through an MCP (Model Context Protocol) server which exposes CLI functionality as structured tools.

# Most common commands
lean-spec create <name>           # Create new spec
lean-spec list                    # View all specs
lean-spec search "query"          # Find relevant specs
lean-spec view <spec>             # Read spec content
lean-spec update <spec> --status  # Update status
lean-spec board                   # Visual overview
lean-spec validate                # Check quality

# Get help
lean-spec --help                  # All commands
lean-spec <command> --help        # Command details

The packages/ui-components package is a tree-shakeable, framework-agnostic React component library built with Vite, TypeScript, and Tailwind CSS. It is designed to have zero Next.js dependencies, making it suitable for any React environment.

Key Features

• Tree-shaking: Optimized for minimal bundle size (final size ~95KB gzipped including primitives).
• Theming: Built-in support for light and dark modes via useTheme hook.
• Accessibility: Includes ARIA labels and keyboard navigation support.
• Documentation: Fully documented via Storybook 8.

Core Component Groups

• Base UI: Button, Input, Card, Select, Popover, Dialog, Command (Command Palette).
• Spec Components: SpecCard, SpecMetadata, StatusBadge, PriorityBadge, TagBadge, SpecTimeline.
• Visualization: SpecDependencyGraph, ProgressBar, StatsCard, StatsOverview.
• Layout & Feedback: Skeleton (various types), EmptyState, ProjectAvatar.

The AI Coding Session Management and Monitoring Infrastructure is a foundational layer in LeanSpec designed to bridge the gap between high-level orchestration and actual AI tool execution. It provides the necessary plumbing to manage the lifecycle of AI-driven coding tasks.

Core Capabilities

• Session Execution Engine: Triggers and manages external AI coding tool processes (e.g., Claude Code, Copilot, Codex-CLI, OpenCode).
• Session Persistence: Uses a SQLite-based storage layer to save session metadata, logs, and outcomes, ensuring state is not lost after processes exit.
• Real-time Monitoring: Enables live viewing of session output and status updates via WebSocket streaming.
• Spec-Session Linking: Establishes a relationship between specifications and their corresponding implementation attempts, allowing multiple sessions to be tracked per spec.
• UI Integration: Provides the backend and data structures required to display and manage sessions within Desktop and Web interfaces.

LeanSpec is a lightweight Spec-Driven Development (SDD) framework designed to optimize development velocity by improving human-AI alignment. It is built on the principle of keeping specs concise (typically under 2,000 tokens) to ensure they fit within AI context windows and human working memory.

Core Strengths

• Lightweight: Minimal setup with no heavy dependencies.
• Simplicity: Start with a single file and grow complexity only as needed (Progressive Disclosure).
• Agility: Direct editing of files in your repository; no multi-step workflows or rigid processes.
• Adaptivity: Works with any editor (VS Code, Vim, etc.) and any AI tool (Copilot, Claude, Cursor, Windsurf).
• Comprehensive Tooling: Includes a CLI, MCP server, and validation tools.

When to Choose LeanSpec

• You want a simple, flexible structure that starts from one file.
• You prefer direct editing without multi-step workflows.
• You want low-latency, local, version-controlled specs.
• You want to maintain high velocity by minimizing cognitive load.

When to Choose Alternatives

• Enterprise Governance: Use Spec Kit if you require a prescriptive 5-step process (constitution → specify → plan → tasks → implement).
• Formal Change Proposals: Use OpenSpec if you need a formal proposal → review → archive workflow with explicit delta tracking.
• Integrated AI IDE: Use Kiro if you want an all-in-one SDD environment with autonomous agents and are willing to switch editors.
• Task Tracking: Use Jira or Linear for project management (use these alongside LeanSpec, not instead of it).