Changelog

May 20, 2026 · View on GitHub

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

  • Dynamic Schema Enrichment (issue #274) — Long-running processes now reuse a resolved adapter across requests instead of re-issuing schema enrichment network calls per hit. New AdapterCache in leanspec-core holds the resolved Arc<dyn Adapter> per project root with a 5-minute TTL; the HTTP server exposes POST /api/projects/{id}/schema/refresh to flush a project's cache on demand, the MCP server adds a reload_schema tool that re-resolves the active adapter without restarting, and leanspec capabilities accepts --refresh (informational for the single-shot CLI). Adapter enrichment failures are now warnings on stderr, not fatal — offline / bad-token sessions fall back to the static schema defaults instead of aborting.
  • leanspec init --adapter github (issue #263) — Initialize a GitHub Issues-backed project from the CLI: detects the GitHub remote, validates $GITHUB_TOKEN via GET /user, writes leanspec.adapter.yaml, and installs an adapter-agnostic AGENTS.md. Stubs for --adapter ado / --adapter jira print a "coming soon" message.
  • TUI Multi-Project Management (spec 372) — Switch between and manage multiple projects from the TUI
  • TUI Sidebar Navigation & Tree View (spec 371) — Sidebar with sort/filter controls and hierarchical tree view for specs
  • TUI Board View Enhancements — Collapsible board groups with sort indicator, TOC overlay, and scrollbars
  • TUI Vertical Scrollbars — Scrollbar widgets in list, board, and detail views
  • TUI Theme Overhaul — Modern theme with Unicode symbols and RGB color palette
  • Configurable Project Sources — Local and GitHub project sources via capabilities endpoint
  • GitHub Tab in Create Dialog — New UI entry point for importing GitHub projects on mobile

Changed

  • Default TUI View — Default view changed from Board to List
  • MCP Deprecation — Removed MCP integration and deprecated leanspec-mcp package

Fixed

  • TUI Mouse Scroll — Routes mouse scroll events by cursor position instead of keyboard focus
  • Mobile Blank Page — Fixes blank page on custom domain for mobile web
  • Clippy Lints — Resolves map_or → is_some_and and redundant else branch warnings

Technical

  • CI Speed-Up — Removes --test-threads=1 constraint and skips session tests for faster builds
  • MCP Test Cleanup — Ignores MCP config test (feature deprecated)
  • Adds specs 372–377 covering project management, UX defaults, real-time file watch, spec editing, and testing infrastructure

[0.2.28] - 2026-03-23

Added

  • Interactive TUI for Spec Management (spec 369) - Terminal UI built with Ratatui for managing specs from the command line
    • Sidebar navigation with keyboard shortcuts and markdown rendering
    • Spec list, detail, and status management views
  • GitHub Repo Import UI - Import specs from GitHub repositories in the cloud deployment interface
  • GitHub Integration (specs 361-366) - Detect and manage specs from connected GitHub repos
    • Cloud deployment readiness checks
    • GitHub-sourced spec detection and synchronization
  • Extended CLI Flags - Richer spec creation and update options
    • --content, --file, --assignee flags for create command
    • --description for create and --expected-hash for update
  • Docker Deployment (spec 317) - Self-hosted leanspec UI via Docker
    • Multi-arch builds (amd64 + ARM64) with native ARM64 runner
    • Non-root container execution with documented project mounting and data persistence

Changed

  • Artifacts Sub-Tree - Deprecates flat subspec display in favor of an artifacts sub-tree concept
  • Skill Architecture - Removes lean-spec skill subcommand and project-scoped skill install; leanspec-sdd skill now uses CLI only (no MCP dependency)
  • Skills Reorganization - Consolidates and reorganizes agent skills layout

Fixed

  • GitHub Project Import - Corrects field naming mismatch and adds missing UI entry points
  • Label Component - Adds missing Label component to the UI library
  • Session Completion - Improves session completion handling and worktree management
  • Railway Deployment - Fixes healthcheck endpoint (/health), timeout (30s), build base image, and consolidates deploy configs to prevent auto-detection issues
  • Docker - Removes hardcoded --project flag; adds data persistence and non-root user support

Technical

  • Database Migration - Migrates database layer from rusqlite to sqlx (Phase 2)
  • CI Improvements - Decouples Docker workflow from npm publish, adds NPM_TAG support, chains Docker build after npm publish, shortens workflow names
  • Bumps Docker runtime base to Debian 13 (trixie)
  • Ignores worktree tests requiring git commit signing

0.2.27 - 2026-03-09

Added

  • Git Worktree Session Isolation (spec 358) - Isolates parallel agent sessions using Git worktrees
    • Worktree lifecycle management with status tracking (created, running, completed, merging, merged, conflict, abandoned)
    • Merge strategies: auto-merge, squash, pull request, manual
    • Registry persistence via .leanspec-worktrees/registry.json with garbage collection
    • CLI commands for merge, cleanup, and gc operations
    • Branch removal fix for streamlined worktree cleanup
  • Shell-Based Runner Execution (spec 357) - Structured run_direct functionality with protocol overrides and model specifications
    • Per-runner protocol field supporting acp and shell execution modes
    • CreateSessionOptions struct for cleaner session creation parameter passing
    • Project-scoped memory support in session management
  • Dynamic Runner Model Discovery (spec 353) - Replaces hardcoded available_models with model_providers in runner schema
    • resolve_runner_models() fetches agentic-capable models from models.dev providers
    • Filters to text I/O models with tool_call support; excludes embedding/audio-only
    • Bundled registry fallback for offline use
    • API endpoint for per-runner dynamic model lists
  • KaTeX Math Rendering (spec 354) - Adds LaTeX math rendering to spec detail markdown
    • remarkMath and rehypeKatex plugins for $...$ and $$...$$ syntax
  • Session Create Preferences - Persists model selection per runner across sessions
    • Zustand store backed by localStorage with setModelForRunner/getModelForRunner
  • Progressive Spec List Rendering - Deferred rendering for large spec lists
    • useDeferredValue() for non-blocking renders with skeleton loading states
    • In-process cache for batch metadata
  • Session Stream Tests - Comprehensive test suite for ACP session streaming

Changed

  • Model Selection UI - Searchable popover with custom model input in SessionCreateDialog and RunnerSettingsTab
    • Dynamic model fetching based on selected runner's model_providers
    • Stored model preference with fallback to runner default
  • ACP Event Handling - Stabilized event keys in AcpConversation preventing key shifts during in-place merges
    • Preserved line breaks in reasoning display and refined tool call logic
    • Active status checks with interval updates in SessionDetailPage
  • Skill Installation - Smart detection of installed AI tools via RunnerRegistry::detect_available()
    • Selective installation to detected agents only (claude-code, copilot, cursor, gemini-cli, codex, etc.)
    • Removes deprecated ralph runner mode
  • Token Management - Refactors global token counter to use LazyLock
  • Specs Query Invalidation - Improved cache invalidation and inline badge editing performance

Fixed

  • StatsPage Error Handling - Handles undefined specsByStatus to prevent runtime errors
  • DashboardClient - Improved error handling for missing data
  • MCP Package Version - Updates MCP package version in VSCode configuration

Technical

  • Refactors session creation internals to CreateSessionOptions struct
  • Strips numeric prefix from spec names with dedicated utility and tests
  • Updates dependencies across packages

0.2.26 - 2026-03-04

Added

  • Sessions UX Overhaul (spec 348) - New SessionsPopover with model selection, status indicators, and toast notifications
  • Spec Search Backend - Backend-driven search with relevance ranking and enriched query support
  • Prompt Input Refactor - Splits monolithic prompt input into modular core, context, hooks, and compound components
  • Generated TypeScript Bindings - Expands generated API types for sessions, runners, stats, and validation with pre-push verification
  • Runner Research Skill - Dedicated skill for tracking runner ecosystem changes and compatibility
  • MCP Tooling Expansion - Adds view, update, validate, tokens, stats, and search MCP tools

Changed

  • Rust Crate Modularity - Reorganizes core, HTTP, and MCP crates into domain-focused modules (spec_ops, compute, io)
  • CLI Argument Architecture - Moves CLI argument parsing into dedicated cli_args module
  • Spec Detail and Navigation UI - Modular spec detail sections, sub-spec tabs, and improved sidebar filtering

Fixed

  • Tool Error Feedback - Clearer error messages for missing fields and structured HTTP error logging
  • UI Responsiveness - Fixes status badge and tool header layout on constrained widths
  • Context Prompt Test - Fixes missing created field in build_context_prompt test frontmatter

Technical

  • Adds Aider artifacts to .gitignore

0.2.25 - 2026-02-27

Added

  • Prompt-First Session Creation (spec 337) - Redesigns session creation as a prompt-first experience

    • SpecContextTrigger and SpecContextChips components for attaching spec context
    • Reusable spec-context pattern shared between sessions and chat
    • Transparent, customizable prompt defaults replacing hidden system templates

  • Sessions Management UI - Comprehensive session browsing and management experience

    • SessionStatusBadge component with color-coded status indicators
    • SessionsNavSidebar with integrated status badges and session navigation
    • Session detail layout with sidebar and context management
    • SessionDurationBadge and SessionModeBadge display components
    • CollapsibleJsonLog component for structured JSON log viewing
    • Enhanced SessionsPage with improved filtering and project ID support
    • Notification support for ACP session ID and initialization response

  • Spec Hierarchy Management - Parent assignment validation and cache invalidation

    • Parent assignment validation with index-based checks
    • Enhanced HierarchyList component with improved rendering
    • Spec cache invalidation logic for consistent hierarchy state

  • Legacy Database Migration - Migration support from legacy databases

    • Automated migration for existing spec data
    • Optimized spec loading via enhanced spec_loader

  • CLI Relationship Commands (spec 335) - New Rust CLI commands for spec hierarchy and dependencies

    • children command to list child specs of a given parent
    • deps command to list dependencies and dependents of a spec
    • list command now supports --parent filter for hierarchy traversal
    • create command gains --parent and --depends-on options for relationship creation

  • SDD Skill Documentation Overhaul (spec 335) - Aligned skill documentation with actual CLI capabilities

    • Rewritten SKILL.md with relationship management details and best practices
    • Replaced COMMANDS.md/EXAMPLES.md with lowercase commands.md/examples.md references
    • Expanded MCP relationship tools with full CRUD operations (link, unlink, set_parent, list_children)

  • ACP Sessions Integration (spec 330) - Agent-Client-Protocol support for interactive AI sessions

    • Human-in-the-loop permission response handling in UI and backend
    • Resume session functionality for paused ACP sessions
    • New AcpConversation component for structured agent interactions
    • Session streaming via session-stream.ts for real-time updates

  • Files Page (spec 331) - Full-featured file browser in web UI

    • FileExplorer component with tree navigation and tab management
    • CodeViewer with syntax highlighting and sticky line numbers
    • File search with support for ignored files
    • Material-style file icons via @exuanbo/file-icons-js
    • File browsing API endpoints in Rust HTTP server

  • Session Context Redesign (spec 328) - Multi-spec and multi-prompt session support

    • Sessions can now reference multiple specs and prompts
    • SearchableSelect and SpecSearchSelect reusable components
    • Enhanced SessionCreateDialog with searchable spec selection
    • Session timeout management and watchdog support

  • Runner Enhancements - Flexible prompt handling and version management

    • prompt_flag field in RunnerConfig and RunnerDefinition for dynamic prompt injection
    • Runner version retrieval API with settings integration
    • Global scope support and IDE runner filters in runner settings
    • Updated runners schema to document prompt usage

  • CLI Template Loading - Template loading in Rust CLI create command

    • Loads and applies templates during spec creation (PR #139)

  • Advanced Search Refactoring (spec 313) - Modular search architecture in Rust

    • Split monolithic search.rs into filters, fuzzy, query, and scorer modules
    • MCP search tool integration tests

  • Session E2E Tests - End-to-end tests for session lifecycle

    • CLI session integration tests covering create, list, and management workflows

Changed

  • Desktop Package Migrated (spec 325) - Moved desktop app to separate repository

    • Removed entire packages/desktop directory (Tauri source, components, hooks, styles)
    • Removed desktop-build.yml GitHub Actions workflow
    • Updated packages README to reflect new architecture

  • Session Management - Uses sessionStorage for project ID handling and improved session start process

  • Component Performance - Memoized BoardView and ListView for optimized rendering

    • Enhanced search functionality in SpecsFilters

  • BackToTop Component - Added targetId prop for scoping scroll behavior to specific containers

  • Session Runner - Supports dynamic prompt replacement via prompt_flag configuration

Fixed

  • pnpm Version - Updated packageManager to pnpm@10.30.2 in root package.json
  • Publishing Scripts - Removed ui-components from package handling in publish scripts
  • Context Prompt - Simplified header assignment in build_context_prompt function

Technical

  • Refactored CLI create and list command parameters to use params structs for better organization
  • Added Clippy guideline for using params structs in functions with more than 7 arguments
  • Removed deprecated badge-config.ts from UI components root (moved to lib/)
  • Added new API types for sessions, files, and ACP in types/api.ts
  • Updated pnpm-lock.yaml and Rust Cargo.lock dependencies
  • Added server configuration to vitest for media-chrome inline dependency

0.2.24 - 2026-02-23

Added

  • Tool Registry for LeanSpec AI - New hook infrastructure for AI tool management

    • useChatConfig and models registry hooks

  • Auto Title Generation - Automatic title generation for chat conversations

    • Conversations now auto-generate titles based on first message

  • Models Settings Enhancements - Enhanced model configuration and management

    • Clear API key functionality
    • Improved toast notifications for model operations
    • Renamed AI settings to Models settings for clarity

  • Draft Spec Status - New draft status for specs to represent work-in-progress items

    • Full support in UI with status badges and filtering

  • Customizable Workflow Enums - Configurable status, priority, and field enums per project

    • Enables teams to define custom values that fit their workflow

  • Tool Call Result Rendering - Rich result display for AI tool calls in chat

    • Specialized renderers for different result types
    • JSON truncation for large payloads to keep UI readable

  • Reasoning Support in Chat - Streaming reasoning/thinking steps in AI chat responses

    • Enhanced tool event handling with dynamic reasoning flag

  • UmbrellaBadge Component - New badge for displaying spec hierarchy in the UI

    • Visual indicator for umbrella parent-child relationships

  • Chat Keyboard Shortcuts - Enhanced keyboard shortcut handling across chat interface

    • Enhanced Markdown rendering components for chat messages

  • Chat Auto-Focus - ChatContainer and ChatSidebar input auto-focus on open

  • Organize Prompt - New AI prompt for managing specs relationships, status, and priority

  • Docker Deployment - Support and documentation for deploying LeanSpec UI via Docker

    • Vite favicon plugin for development build support

Changed

  • UI Components Consolidation (spec 314) - Major refactoring of UI package

    • Phase 1: DRY elimination with consolidated badge config and removed duplicates
    • Phase 2: Renamed 80 component files to kebab-case naming convention
    • Removed @leanspec/ui-components package entirely
    • Updated all import paths to use @/library instead of @leanspec/ui-components

  • Chat Transport Enhancements - Dynamic body values and improved provider compatibility

  • Project-Scoped Storage - Project-scoped localStorage for user preferences and chat settings

    • Zustand store synchronization improvements
    • Models registry fetching optimizations

  • Skill Installation - Enhanced to target detected AI tools and streamline MCP configuration

  • Chat Sidebar Global Store - Refactored to use global chat preferences store; removed deprecated standalone chat page

  • Chat Message Handling - Enhanced with parts and metadata support for richer message structures

    • Human-readable title field in tool input structs for better action clarity

  • PriorityBadge / StatusBadge - Added outline variant for flexible display options

  • TerminalStatus Component - Now displays "Running..." message when no child content is provided

  • Completion Verification - Archived child specs are now considered when verifying spec completion

Fixed

  • lean-spec ui Path Issue - Fixed "specs/specs" doubled path when launching lean-spec ui command
    • Passes project root instead of specs directory to HTTP server
  • CI/CD Linux Build - Pinned Linux build runner to ubuntu-22.04 for GLIBC 2.35 compatibility
  • CI Rust Target Cache - Dropped failing rust target cache step in CI workflow
  • Chat Sidebar Conversation History - Fixed layout sidebar race conditions
  • TypeScript Deprecation - Removed deprecated ignoreDeprecations option from tsconfig
  • Spec Prompt Clarity - Clarified spec loading instructions and dependency checks
  • Clippy Warnings - Added allowance for too many arguments in stream_openai_round function
  • Linux arm64 Error Messages - Removed misleading linux-arm64 support claims from error output

Technical

  • Consolidated script references and updated skill documentation
  • Removed Makefile, updated build scripts for Rust binaries
  • Refactored merge_frontmatter function to use input struct for better readability
  • Added development logos and dev-build navigation support

0.2.23 - 2026-02-03

Added

  • AI Chat Model Whitelisting (spec 307) - Control which models appear in the chat selector

    • New enabledModels field in chat config to filter model list per provider
    • Smart default selection uses first configured provider's tool-enabled model
    • Fixed provider mismatch bug ("missing API key for provider: OpenAI" when using OpenRouter)
    • Loading state shown while registry initializes

  • AI Chat Conversation History (spec 308) - Fixed missing conversation history in web UI

    • Fixed "first message before session" race condition in layout sidebar
    • Added empty state UI for when no conversations exist
    • Conversations now properly persist and load across page refreshes

  • Models.dev Integration (spec 302) - Default model registry for automatic AI model discovery

    • Uses models.dev API as source of truth for available AI models
    • Auto-detects configured API keys and shows only usable providers
    • Caches model data locally with 24h TTL and offline fallback
    • Shows model capabilities (tool_call, reasoning, vision) with context window info

  • Settings Page Optimization (spec 306) - Comprehensive UX improvements

    • Settings sidebar matches MainSidebar icon-only collapse pattern
    • Search, filter, and sort for AI providers and runners
    • Display mode toggle (Wide/Normal) in Appearance settings
    • Auto-validation of runners and API keys with status badges
    • One-click default selection with star buttons

Changed

  • UI Layout Alignment (spec 305) - Consistent layout across all pages

    • Shared page container with min-w-4xl desktop width
    • Centered column with consistent padding and max-w-7xl
    • Horizontal scroll behavior for sidebars

  • Init Example Improvements - Enhanced lean-spec init --example guidance

    • Polished example comments and next steps
    • Clearer onboarding for new users

Fixed

  • Chat sidebar now properly creates session before sending first message
  • Model selector initializes from registry defaults instead of hardcoded values
  • Status and priority editors sync with prop changes correctly
  • Icon swap for normal/wide modes in WideModeToggle component
  • Clippy errors in leanspec-http resolved
  • Better error handling for undefined response in listAvailableRunners
  • jiti version updated in dependencies

0.2.22 - 2026-02-02

Added

  • Inline Metadata Editing in List/Board Views - Quick status and priority updates without navigation

    • Clickable status/priority badges with dropdown selectors
    • Optimistic updates with immediate API sync
    • Works in both ListView and BoardView components

  • Structured Spec Hierarchy Management (spec 250) - Parent-child relationships for umbrella specs

    • New parent field in frontmatter for organizational grouping (distinct from depends_on technical dependencies)
    • Auto-detection of umbrella specs (specs with children get umbrella indicator)
    • lean-spec list --hierarchy - Tree view showing parent-child nesting
    • lean-spec children <spec> - List all direct children of an umbrella spec
    • lean-spec board --group-by parent - Board view grouped by parent umbrellas
    • MCP tools: set_parent, list_children, list_umbrellas for AI agent workflows
    • Hierarchy validation: circular parent detection, orphan detection, status consistency checks
    • UI list view: groupByParent toggle with collapsible tree groups
    • UI board view: de-emphasized child specs, auto-collapse after 3 children with "[+X more]" toggle
    • Related specs: 252, 253, 254, 258

  • Unified Relationships Editing UI (spec 253) - ADO-style relationship management

    • Single "Relationships" panel replacing separate buttons
    • Inline editing for all relationship types: parent, children, depends_on, required_by
    • ADO-style searchable spec picker dropdown

  • Streamlined Relationship Commands (spec 254) - Unified CLI/MCP interface

    • New lean-spec rel command for all relationship operations (view/add/rm)
    • MCP relationships tool unifying all relationship operations
    • Deprecation notices on old link, unlink, set-parent, deps, children commands

  • Write-Time Relationship Validation (spec 257) - Prevent invalid relationship states

    • Parent/dependency cycle detection with clear error messages
    • Hierarchy/dependency conflict detection

  • UI Enhancements

    • Storage utilities consolidation with unified hooks (spec 271)
    • Wide mode toggle for compact/expanded list views
    • Archived specs visibility toggle in filters
    • Enhanced markdown rendering with code block copy button and table styling
    • Token count and validation dialogs with i18n support
    • Spec edit history viewer via git integration
    • Responsive sidebar visibility with resize observer

  • UI Utilities Consolidation (spec 261) - Deduplicated shared code into @leanspec/ui-components

Changed

  • Chat Server Retired (spec 264) - AI now fully native in Rust

    • Removed @leanspec/chat-server package completely
    • AI chat handled natively using async-openai and anthropic Rust crates

  • Token Validation Performance (spec 270) - Lazy static singletons for TokenCounter and validators

  • Technical Debt Refactoring (spec 259)

    • Type definitions consolidated (spec 262)
    • Rust spec handler consolidated (spec 263)
    • Config standardization (spec 265)
    • Hierarchy icon updated from Umbrella to FolderTree

  • Status-Only Archiving (spec 256) - Archiving now only sets status: archived (no file move)

  • Rust Monorepo Architecture Refactoring - Sessions, storage, and AI modules consolidated into leanspec-core

Fixed

  • Rust Cargo.toml version regex handling
  • Doctest assertions and missing react-window types
  • Mermaid diagram rendering logic and empty chart handling
  • Spec navigation with incorrect spec ID in dependency graph
  • Clippy warnings across Rust codebase
  • Skills path references (now relative)
  • Sidebar layout row height

0.2.21 - 2026-01-27

Fixed

  • Tailwind Typography Plugin - Added typography plugin and fixed animation plugin import

0.2.20 - 2026-01-27

Added

  • AI Chat Configuration Improvements (spec 224) - Full multi-provider support and settings UI

    • Configuration-driven AI model management via ~/.leanspec/chat-config.json
    • Support for OpenAI, Anthropic, Deepseek, OpenRouter and any OpenAI-compatible API
    • ModelPicker component for quick provider/model selection in chat header
    • Full Settings page with CRUD operations for providers and models
    • Environment variable interpolation (${OPENAI_API_KEY}) for secure API key management
    • Config hot-reload without server restart
    • Default provider/model/maxSteps configuration
    • i18n support (English and Chinese) for all settings UI

  • IPC-Based AI Chat Bridge (spec 237) - Unified Rust HTTP server with AI worker

    • Single server process (Rust manages Node.js AI worker via IPC)
    • JSON Lines protocol for stdin/stdout communication
    • Automatic worker spawning on first chat request
    • Node.js version detection with tiered warnings (v20 EOL warning, v22+ recommended)
    • Graceful degradation when Node.js unavailable
    • Environment variables: LEANSPEC_NO_AI, LEANSPEC_NODE_PATH, LEANSPEC_AI_WORKER

  • UI Component Consolidation (spec 238) - Unified component library

    • Consolidated all shadcn/ui components into @leanspec/ui-components
    • Integrated ai-elements wrappers (48 components) into @leanspec/ui-components
    • Cleaner architecture: @leanspec/ui focuses on application logic, @leanspec/ui-components on reusable components
    • Added comprehensive Radix UI and ai-elements peer dependencies

  • HTTP Server Auto-Installation - Seamless UI startup experience

    • @leanspec/ui automatically installs @leanspec/http-server if not present
    • Delete confirmation dialogs for providers and models in settings

  • GitHub Actions Skills - New documentation for CI/CD workflow management

    • Added .github/skills/github-actions/SKILL.md for workflow triggers and monitoring

Changed

  • Mermaid Diagram Enhancements - Improved theme support and rendering

    • Better dark/light theme detection and switching
    • Enhanced component styling for improved visual consistency

  • Settings Page Layout - Responsive tab navigation with improved styling

    • Added appearance settings tab with language selection
    • Better organization of configuration options

  • Theme System Refactoring - Improved structure and clarity

    • Refactored theme context and hooks for better maintainability
    • Centralized theme management

Fixed

  • Dependency Graph Self-References - Prevented specs from referencing themselves in dependency visualization

    • Filters self-references in dependency graph computation
    • Clears cache on spec change for accurate updates
    • Fixed required_by computation to exclude self-references

  • ChatContainer Error Handling - Added error and onRetry handling

    • Graceful error recovery for chat message failures

  • Theme Context Import Paths - Fixed inconsistent import paths for theme utilities

  • Tokens Command - Made path argument optional for better CLI ergonomics

  • Clippy Warnings - Resolved all Rust linter warnings

[0.2.18] - 2026-01-16

Fixed

  • Critical: Fixed EACCES permission error for platform binaries
    • npm doesn't preserve file permissions when installing packages
    • Added postinstall scripts to all platform packages (CLI, MCP, HTTP) to set execute permissions
    • Fixes error: spawn leanspec-http EACCES when running npx @leanspec/ui
    • All Unix binaries now automatically get execute permissions (0o755) after installation

[0.2.17] - 2026-01-15

Fixed

  • Critical: Fixed workspace:* dependencies in published packages
    • Version 0.2.15 of @leanspec/http-server was published with unresolved workspace protocol references
    • This caused installation failures: npm error Unsupported URL Type "workspace:": workspace:*
    • All packages now properly resolve workspace dependencies before publishing
    • Platform packages (CLI, MCP, HTTP) optionalDependencies now correctly reference versioned packages

[0.2.13] - 2026-01-13

Added

  • Enhanced i18n support - Comprehensive internationalization improvements
    • Localized MermaidDiagram, SpecsLayout, and ThemeToggle components
    • Shared translation keys for common UI elements
    • Enhanced error message localization
    • Status and priority filters with session storage persistence
  • Statistics Dashboard - New StatsPage with charts and statistics overview
    • Visual analytics with recharts integration
    • Project health metrics display
    • Progress tracking visualization
  • Embeddings-based Search - PgVector storage integration for semantic search
    • Improved search relevance
    • Preparation for AI-powered spec discovery

Changed

  • Navigation Enhancements - Refined navigation and project switcher
    • Improved UI consistency across components
    • Better status icon indicators
    • Enhanced DesktopNavigationFrame integration
  • Layout Refactoring - Consolidated header components
    • PageHeader component for consistent layout
    • Improved page structure across all views
  • Backend Adapter - Project-specific API endpoint usage
    • Better multi-project support
    • Enhanced localization for spec statuses

Fixed

  • YAML Frontmatter - Enhanced YAML handling with safeDump support
  • Testing Setup - localStorage mock and improved API test scripts
  • Status Handling - Refined status fallbacks and validation

[0.2.12] - 2025-12-22

Added

  • Initial 0.2.x release with Vite SPA migration

0.2.11 - 2025-12-19

Added

  • Internationalization (i18n) support - Full localization for UI components and CLI commands
    • Chinese (zh-CN) translations for all UI pages, components, and status/priority labels
    • Localized CLI command outputs and error messages
    • Language switcher in web UI header
    • System language detection with fallback to English
  • Token count formatting - Enhanced display of token counts in UI components
    • Formatted with thousands separators for readability
    • Consistent formatting across stats pages and spec metadata
  • Sidebar enhancements - Improved navigation and project management
    • Enhanced MainSidebar layout with better spacing and hover states
    • Improved ProjectSwitcher item styling with clear selection indicators
    • Better project avatar display with color coding

Changed

  • Multi-project architecture refactoring (spec 151) - Deep architectural improvements
    • Unified routing: All routes now use /projects/[id]/* structure (single-project uses 'default' ID)
    • Consolidated specs service replacing separate filesystem-source and multi-project-source
    • Single code path for spec operations (no more mode-specific branching)
    • Consistent relationship computation across all views
    • Improved URL handling with automatic redirects for legacy paths
    • Reduced technical debt from incremental multi-project fixes
  • Config format migration - Migrated project registry from YAML to JSON
    • Better compatibility with web standards
    • Improved parsing performance
    • Easier programmatic manipulation
  • Dependency graph enhancements (spec 154) - Enhanced dependency visualizations
    • Icon-based status/priority indicators (Clock, PlayCircle, CheckCircle2, Archive)
    • Color-coded backgrounds for quick status recognition
    • Level indicators (L1, L2, L3) showing dependency depth
    • Unified design between dependencies page and spec detail dialog
    • Focus mode with layered layout options
    • Better visual hierarchy with tooltips

Fixed

  • Sidebar highlighting issues - Fixed sidebar link highlighting with proper path normalization
    • Correctly handles root path and nested routes
    • Active link properly highlighted during navigation
    • Improved SidebarLink component with better URL matching
  • Relationship extraction - Fixed full content retention for relationship parsing
    • FilesystemSource and MultiProjectFilesystemSource now properly extract relationships
    • "View Dependencies" button now works correctly in multi-project mode
    • Relationship computation consistent across all spec sources
  • Layout responsiveness - Enhanced responsive design in CreateProjectDialog and DirectoryPicker
    • Better handling of long paths with proper text truncation
    • Improved mobile layouts
    • Fixed path overflow issues
  • Hydration mismatches - Added ClientOnly component to prevent SSR/client hydration errors
    • Fixes React hydration warnings
    • Improved first paint stability
    • Better handling of client-side only components
  • Atomic file operations - Implemented atomic writes for spec create/update operations
    • Prevents race conditions during concurrent operations
    • Prevents partial writes that could corrupt specs
    • Better error handling during file system operations
  • Filename formatting - Enhanced acronym preservation in spec names
    • API, UI, UX, etc. now properly capitalized in display names
    • Improved readability of generated filenames

Technical

  • All 982 tests passing with unified architecture
  • Dependency updates: drizzle-kit and storybook/test versions for improved stability
  • Legacy route removal: Simplified codebase by removing deprecated /specs/* routes
  • ProjectContext now always provides currentProjectId (derived from mode)
  • Components receive projectId prop instead of mode checks

Notes

Version 0.2.11 focuses on stabilizing the Next.js-based @leanspec/ui with architectural improvements and bug fixes. This prepares for version 0.3.0, which will introduce the major Rust-based CLI/MCP/Web/Desktop migration with:

  • Unified Rust codebase for all platforms (CLI, MCP server, HTTP server, Desktop app)
  • Native performance improvements
  • Cross-platform binaries via GitHub Actions CI/CD
  • Simplified distribution with scoped npm packages
  • New framework-agnostic UI component library (@leanspec/ui-components)
  • Lightweight Vite-based SPA (@leanspec/ui-vite) replacing Next.js
  • See spec 181 for Rust migration details

0.2.10 - 2025-12-05

Added

  • Inline metadata editing in Web UI (spec 134) - Edit spec metadata directly in the browser
    • Status dropdown with color-coded badges (planned, in-progress, complete, archived)
    • Priority selector (low, medium, high, critical)
    • Tags editor with add/remove functionality and autocomplete suggestions
    • Inline dependency editor with add/remove support
    • Optimistic updates with automatic rollback on error
    • Works in both filesystem and multi-project modes
  • MCP config auto-setup during init (spec 145) - Automatic MCP configuration
    • lean-spec init now offers to configure MCP for detected AI tools
    • Supports Claude Code (.mcp.json), VS Code (.vscode/mcp.json), Cursor (.cursor/mcp.json)
    • Generates correct MCP config entries with proper absolute paths
    • Zero manual configuration needed after init for workspace-local tools
  • Backfill command bootstrap mode (spec 144) - Robust migration support
    • New --bootstrap flag creates frontmatter for specs without any
    • Auto-infers status and created from git history
    • Supports legacy formats (ADR, RFC, inline metadata like **Status**: Complete)
    • Maps ADR statuses: accepted→complete, proposed→planned, superseded→archived
  • Multi-project management UI improvements (spec 141) - Enhanced project management
    • "Manage Projects" option in project switcher dropdown for quick access
    • Inline project name editing on /projects page
    • Color picker for project customization
    • Project path validation with status indicators (valid/invalid/missing)

Changed

  • Multi-project mode improvements (spec 142, spec 149) - Critical UX fixes
    • All navigation links now use project-scoped URLs (/projects/[id]/specs)
    • Added SSR for multi-project dependencies, stats, and context pages
    • Projects page has dedicated layout without sidebar (cleaner management UX)
    • Fixed path overflow in Add Project dialog with proper truncation
    • Auto-redirect to specs list when switching projects from spec detail page
    • URL format detection with auto-redirect between single/multi-project modes
    • Dependency graph now works in multi-project mode (new API endpoint)
  • Lightweight specs for list views - Performance optimization
    • Spec list API no longer returns full contentMd (can be 1MB+ total)
    • Reduces initial page load size by ~90% for projects with many specs
  • Frontmatter validation improvements - Enhanced date parsing and validation
    • Multi-project filesystem source validates frontmatter on load
    • Better handling of malformed or missing dates

Fixed

  • Dependencies page fails on custom ports - lean-spec ui --port 3002 now works
    • Pages now call data functions directly instead of fetching from hardcoded localhost:3000
    • Multi-project dependencies correctly parse depends_on from frontmatter
  • Spec detail dependencies not available in multi-project mode - "View Dependencies" button now works
    • Added relationship extraction from spec content for multi-project mode
    • New /api/projects/[id]/specs/[spec]/dependency-graph API endpoint
  • MCP deps tool fails to find spec by sequence number - Now correctly resolves spec paths
  • Duplicate icons in Status/Priority editors - Fixed SelectValue to display explicit labels
  • Dependencies page light theme contrast - Updated node styling for light/dark mode compatibility
    • Fixed unreadable nodes and edges in light theme
    • Consistent color palette across both themes
  • Command references updated - Fixed lspec → lean-spec in documentation and code
  • Project switcher navigation - Uses window.location.assign for better state management

0.2.9 - 2025-12-04

Added

  • Project-wide dependency visualization (spec 137) - New /dependencies page in Web UI
    • Bird's-eye view of entire project's dependency structure using DAG layout
    • Interactive ReactFlow graph with zoom/pan controls
    • Click nodes to navigate directly to spec details
    • Filter by status, priority, and tags
    • Color-coded nodes by status (amber=planned, blue=in-progress, green=complete)
    • Spec selector dropdown to focus on specific spec's dependency chain
    • Critical path highlighting for transitive dependencies
    • Sidebar showing focused spec details and connections
  • Enhanced context file viewer - Improved file browsing in Web UI
    • New ContextFileDetail component for better file inspection
    • Dynamic file icons and colors based on file type (markdown, yaml, json, etc.)

Changed

  • Simplified spec relationships (spec 139) - Removed related field, keeping only depends_on
    • Breaking: related field is deprecated and will be ignored
    • Cleaner DAG-only visualization (no more cluttered network graphs)
    • Simpler mental model: every edge means "blocking dependency"
    • Tags + search now recommended for discovery instead of explicit related links
    • Better AI agent guidance with single relationship type
    • Removed --related flag from lean-spec link and lean-spec unlink commands
  • Turbo updated to v2.6.2

Fixed

  • Chinese/Unicode spec name support (spec 135) - Fixed sequence number detection for non-ASCII spec names
    • Specs with Chinese characters (e.g., 001-测试) now correctly detected
    • Japanese, Korean, and other Unicode scripts supported
  • Spec frontmatter validation - Fixed YAML parsing errors from orphaned array items in some specs
  • Docs-site integration - Converted from submodule to direct inclusion for simpler maintenance

0.2.8 - 2025-11-28

Added

  • Safe re-initialization workflow (spec 127) - Improved lean-spec init for existing projects
    • New -f, --force flag to force re-initialization (resets config, preserves specs)
    • Interactive strategy selection when project is already initialized:
      • Upgrade configuration (recommended) - Merges config with latest defaults, preserves all user content
      • Reset configuration - Fresh config from template, keeps specs/ directory
      • Full reset - Removes everything with confirmation prompt
      • Cancel - Exit without changes
    • Safe defaults: -y flag defaults to upgrade (safest), -f flag resets config only
    • Shows spec count when re-initializing to inform user's decision
    • Confirmation required for destructive "full reset" option
    • Auto-creates AGENTS.md if missing during init
  • MCP link and unlink tools (spec 129) - Manage spec relationships directly from AI agents
    • link tool: Add depends_on or related relationships between specs
    • unlink tool: Remove relationships with type filtering and --all support
    • Enables AI agents to maintain spec dependencies without CLI commands
    • Bidirectional link updates for related relationships
  • Project context visibility in Web UI (spec 131) - View project files from the web interface
    • New /context page showing AGENTS.md, README.md, and project configuration
    • File viewer with syntax highlighting and search functionality
    • Quick links to open files in VS Code editor
    • Accordion-based file browser for easy navigation
  • Focus mode in spec detail view - Distraction-free reading experience
    • Toggle button to hide sidebar and expand content area
    • Cleaner layout for reviewing spec content
  • Directory-based template support (spec 128) - Enhanced template handling
    • Templates can now be organized in subdirectories
    • Improved lean-spec templates listing with better organization
    • Support for custom template directories

Changed

  • Testing infrastructure overhaul (spec 130) - Comprehensive test strategy documentation
    • New regression test template for consistent test patterns
    • Spec lifecycle tests for create/update/archive workflows
    • E2E test improvements for AGENTS.md handling

Fixed

  • Tutorial URLs - Corrected links in examples and specifications
  • Analytics tracking - Use ENABLE_ANALYTICS env var for Vercel Analytics
  • README improvements - Fixed link formatting and removed unnecessary attributes

0.2.7 - 2025-11-26

Added

  • AI tool auto-detection (spec 126) - Smart defaults for lean-spec init
    • Auto-detect installed AI CLI tools (Aider, Claude, Codex, Copilot, Cursor, Droid, Gemini, OpenCode, Windsurf)
    • Detection via CLI commands, config directories, and environment variables
    • Shows detected tools with reasons before AI tools prompt
    • Pre-selects detected tools in checkbox for better UX
    • Fallback to copilot only (AGENTS.md) when nothing detected
  • MCP-first agent experience (spec 121) - Enhanced AI agent workflow with better SDD compliance
    • Multi-tool symlink support: lean-spec init now creates tool-specific symlinks (CLAUDE.md, GEMINI.md → AGENTS.md)
    • New --agent-tools flag for non-interactive mode (--agent-tools all, --agent-tools claude,gemini, --agent-tools none)
    • MCP-first AGENTS.md rewrite emphasizing MCP tools as primary method over CLI
    • New MCP prompt: checkpoint - Periodic SDD compliance reminder for long sessions
    • New MCP prompt: create-spec - Guided spec creation workflow with dependency linking
    • Stale spec warnings in board output
    • SDD Workflow Checkpoints section in AGENTS.md
  • Dependency alignment validation (spec 122) - Automated detection of content/frontmatter misalignment
    • New --check-deps flag for lean-spec validate command
    • DependencyAlignmentValidator scans spec content for references to other specs
    • Detects patterns like "spec 045", "depends on", "related to", "builds on", etc.
    • Outputs actionable fix commands (e.g., lean-spec link <spec> --related 045)
    • MCP validate tool now supports checkDeps option
    • Added Core Rule #8 in AGENTS.md: "ALWAYS link spec dependencies"
  • Advanced search capabilities (spec 124) - Enhanced search for power users
    • Cross-field term matching: queries now find specs where terms appear across any fields
    • Boolean operators support: AND, OR, NOT for complex queries
    • Field-specific search: status:in-progress, tag:api, priority:high, assignee:name
    • Date range filters: created:>2025-11-01, created:2025-11-01..2025-11-15
    • Fuzzy matching with ~ suffix for typo tolerance
    • Combined query syntax: tag:api status:planned created:>2025-11
    • Search syntax help in lean-spec search --help
    • Query guidance for AI agents in AGENTS.md and MCP tool descriptions
  • Native diagram rendering in Web UI (spec 119) - Mermaid diagram support in spec detail view
    • Client-side Mermaid rendering for flowcharts, sequence diagrams, class diagrams, etc.
    • Dark mode theme support with automatic theme switching
    • Error handling with fallback to code block display
    • Lazy loading for optimal bundle size (only loads when diagrams present)
  • Parallel spec implementation workflow (spec 118) - Documentation for concurrent spec development
    • Git worktrees pattern for working on multiple specs simultaneously
    • Patterns for solo developers, teams, and experimental work
    • Best practices for worktree naming, branch strategy, and cleanup
    • Added to AGENTS.md FAQ section
  • AI coding agent integration (spec 123) - Enhanced workflow for remote coding agents
    • Support for GitHub Copilot Coding Agent, OpenAI Codex Cloud, and similar tools
    • Guidance for spec-driven task delegation to cloud agents
    • Best practices for parallel development with remote agents
  • Onboarding project context clarity (spec 125) - Improved first-use experience
    • Clearer guidance on workspace context for AI agents
    • Enhanced AGENTS.md with project-specific context sections

Changed

  • AGENTS.md restructured for MCP-first approach
    • MCP tools listed before CLI commands
    • Added "How to Manage Specs" section with MCP vs CLI comparison table
    • Added "SDD Workflow Checkpoints" with before/during/after task reminders
    • Added "Common Mistakes to Avoid" section with clear ❌/✅ examples
  • Quality Standards updated - Added --check-deps validation to required checks before completing work

Fixed

  • All existing specs now have aligned dependencies (19+ specs fixed after running validate --check-deps)

0.2.6 - 2025-11-25

Added

  • Example projects scaffold (spec 114) - Quick-start tutorial projects with lean-spec init --example
    • Three complete example projects: dark-theme, dashboard-widgets, api-refactor
    • Instant setup with dependencies and realistic starter code
    • lean-spec examples command to list available examples
    • Interactive selection mode for scaffolding
    • Automatic LeanSpec initialization in scaffolded projects
  • Chinese translation quality guidelines (spec 115) - Professional localization standards
    • Comprehensive translation guidelines in docs-site/AGENTS.md
    • Translation glossary with 40+ technical terms
    • Natural Chinese expression patterns for technical content
    • Quality checklist for translation validation
  • JSON output support - Added --json flag to CLI commands for programmatic use
    • lean-spec list --json - Machine-readable spec listing
    • lean-spec board --json - Kanban board data export
    • lean-spec search --json - Structured search results
    • lean-spec check --json - Validation results in JSON
    • lean-spec files --json - File listing in structured format
    • lean-spec timeline --json - Timeline data export
    • lean-spec backfill --json - Backfill results in JSON
    • lean-spec gantt --json - Gantt chart data export

Changed

  • Template system simplification (spec 117) - Removed template engine for direct maintenance
    • Eliminated Handlebars build layer and 15+ component files
    • Consolidated to 2 templates: standard (default) and detailed (sub-specs demo)
    • Shared AGENTS.md across templates for consistency
    • Faster iteration without build step (edit → test directly)
    • Improved AI workflow with stronger CLI command emphasis

Fixed

  • Example project initialization (spec 116) - Fixed missing LeanSpec files in scaffolded examples
    • lean-spec init --example now properly initializes LeanSpec (AGENTS.md, .lean-spec/, specs/)
    • All LeanSpec CLI commands now work in scaffolded example projects
    • Tutorial workflows function correctly out of the box

Technical

  • Removed Handlebars dependency from CLI package
  • Simplified template directory structure
  • Enhanced tutorial documentation with example project references
  • Improved Chinese documentation quality across docs-site

0.2.5 - 2025-11-18

Added

  • @leanspec/mcp standalone package (spec 102) - Dedicated npm package for MCP server integration
    • Simpler onboarding: Use npx @leanspec/mcp directly in IDE configs
    • Better discoverability: Package name clearly indicates MCP functionality
    • Zero-config setup: Just copy-paste config snippet for Claude Desktop, Cline, or Zed
    • Automatic dependency management: npx handles installation of both @leanspec/mcp and lean-spec
    • Pure passthrough design: Delegates to lean-spec mcp with no additional logic
  • Enhanced dependency commands (spec 99) - Improved CLI and MCP tools for managing spec relationships
    • Better dependency graph visualization
    • Enhanced link and unlink commands for managing depends_on and related fields
    • Improved error handling and validation for circular dependencies
  • GitHub Action for automated publishing (spec 16 - partial implementation) - CI/CD workflow for dev releases
    • Automated @leanspec/mcp publishing on npm with version suffix
    • Pre-release checks and validations
    • Package preparation scripts for handling workspace dependencies

Changed

  • UI Package Consolidation (spec 103) - Merged @leanspec/web into @leanspec/ui for simpler architecture
    • Single publishable Next.js app package instead of separate web + wrapper packages
    • Eliminated complex symlink handling and node_modules distribution issues
    • Simplified CLI launcher with direct Next.js standalone server execution
    • Cleaner monorepo structure with one less package to maintain
    • No breaking changes to user-facing lean-spec ui command
  • Package Publishing Workflow - Enhanced automation for npm releases
    • New prepare-publish script handles workspace protocol replacement
    • New restore-packages script reverts changes after publishing
    • Updated CI workflow for streamlined version synchronization

Fixed

  • @leanspec/ui packaging issue (spec 104) - Fixed "Cannot find module 'next'" error in published package
    • Root cause: npm pack doesn't follow symlinks by default, so node_modules/ symlinks in standalone build weren't resolved
    • Solution: Include actual pnpm store location (.next/standalone/node_modules/.pnpm/) in published files
    • Package now correctly bundles all Next.js dependencies (~18.3 MB compressed, 65 MB unpacked)
    • Users can now successfully run lean-spec ui via published npm package
  • UI command signal handling - Improved process cleanup and graceful shutdown
    • Better handling of Ctrl+C and Ctrl+D to stop the UI server
    • Proper signal forwarding to child processes
  • Documentation updates - Enhanced READMEs for MCP, UI, and CLI packages
    • Clearer setup instructions for MCP server integration
    • Updated lean-spec ui documentation with new package structure
    • Added examples for different IDE configurations

Technical

  • All packages bumped to version 0.2.5
  • Enhanced build scripts for better monorepo management
  • Improved workspace configuration with .code-workspace file
  • Updated Vitest configuration to use UI package source path

0.2.4 - 2025-11-17

Fixed

  • CLI lean-spec ui pnpm flow (spec 87) - Removed pnpm dlx --prefer-offline forcing offline cache, so the UI command now fetches @leanspec/ui on demand and no longer fails when the package is missing locally.
  • Web filesystem relationship parsing - UI development mode now respects the SPECS_DIR environment variable, so relationships and sub-spec counts resolve correctly when serving specs from an external workspace (fixes ENOENT errors when pointing the UI at another repo).
  • Web sidebar scroll position drift (spec 101) - Eliminated scroll position jumping during navigation
    • Fixed React 19 useSyncExternalStore infinite loop by stabilizing server snapshot references
    • Isolated scroll persistence to prevent global store re-renders on every scroll event
    • Implemented component-local scroll management with useIsomorphicLayoutEffect for flicker-free restoration
    • Added guarded auto-anchoring that centers active spec on page refresh without disrupting user scrolling
    • Validated smooth scrolling for 100+ spec lists with no drift during rapid navigation or filtering
  • Web spec detail page sub-specs display - Fixed missing sub-specs tabs and count indicator
    • Sub-specs tabs now correctly display when available
    • Sidebar shows sub-spec count (e.g., "+3") for specs with additional markdown files
    • Added getSpecsWithSubSpecCount() function for efficient sub-spec counting
    • Enhanced SidebarSpec type to include subSpecsCount field
  • @leanspec/ui package build - Fixed static asset bundling for npm distribution
    • Changed from symlinks to copying static assets into standalone build
    • Ensures Next.js static files and public assets are included in published package
    • Fixed 404 errors for /_next/static/* and /public/* assets
    • Cross-platform compatible (Windows, macOS, Linux)

0.2.3 - 2025-11-17

Added

  • lean-spec ui command (spec 87) - Launch web interface directly from CLI
    • Monorepo mode: Auto-detects and runs local web package
    • Package manager auto-detection (pnpm/yarn/npm)
    • Port validation and configuration
    • Auto-opens browser with graceful shutdown
    • Support for both filesystem and database-backed modes
  • Web App Performance Optimizations (spec 83) - Dramatically improved navigation speed
    • Hybrid rendering: Server-side initial load, client-side navigation
    • Navigation latency reduced from 600ms-1.2s to <100ms
    • API routes with aggressive caching and prefetching
    • Optimistic UI for instant feedback
    • Sidebar state persistence and loading shells
  • Enhanced Spec Detail UI - Improved user experience
    • Dependency visualization with bidirectional relationships
    • Timeline view for spec history
    • Loading skeletons for better perceived performance
    • Responsive layout improvements
  • Documentation Migration - Migrated docs-site to separate repository as submodule
    • Cleaner monorepo structure
    • Independent documentation deployment
    • Beginner-first reorganization

Changed

  • Web App Navigation: Switched from full server-side rendering to hybrid architecture
  • Command Interfaces: Enhanced validation logic across CLI commands
  • Template System: Refactored agent templates for improved status tracking
  • Mobile UX: Enhanced sticky header behavior and mobile button styling
  • Responsive Design: Improved mobile navigation for dashboard and specs pages

Fixed

  • i18n hook caching and loading states
  • Current spec highlighting in navigation sidebar
  • Mobile navigation responsiveness
  • Various UI/UX refinements for web app

Technical

  • Migrated to Node.js >=20 requirement across all packages
  • Added Vercel configuration for deployment
  • Improved filesystem source caching
  • Enhanced CSS modules TypeScript support

0.2.2 - 2025-11-13

Added

  • Template Engine for AGENTS.md (spec 73) - Dynamic template system for maintaining AGENTS.md with mechanical transformations
  • Intelligent Search Engine (spec 75) - Relevance-ranked search with TF-IDF scoring and content-based ranking
  • Programmatic Spec Management (spec 59, Phase 1-2) - analyze, split, compact commands for automated spec restructuring
  • Programmatic Spec Relationships (spec 76) - CLI and MCP tools for managing depends_on and related fields
  • Sub-spec Template System (spec 78) - Documentation for creating and managing multi-file spec structures
  • Archiving Strategy (spec 77) - Documentation for proper spec archival workflows

Changed

  • Search commands now use intelligent ranking algorithm prioritizing title/frontmatter matches
  • MCP search tool upgraded with relevance scoring and better result filtering
  • AGENTS.md validation enforces template system consistency

Fixed

  • Critical npm publishing bug: workspace:* dependency in published package causing installation failures
    • Root cause: pnpm workspace protocol leaked into published tarball
    • Fix required: Use pnpm's --no-workspace flag or proper bundling configuration

In Progress

  • Spec 59 (Programmatic Management) - Phases 1-2 complete, remaining phases in progress
  • Spec 72 (AI Agent First-Use Workflow) - Planning stage
  • Spec 74 (Content at Creation) - Specification stage

[0.2.1] - 2025-11-13

Added

  • Token counting commands (lean-spec tokens) for LLM context management
  • Token-based validation thresholds replacing line-count metrics
  • Chinese (zh-Hans) translations for documentation site
  • UI/UX enhancements for LeanSpec Web including dark theme improvements

Fixed

  • Migration tests now use correct fixture paths
  • CI workflow improvements and error handling
  • Dark theme typography and status color consistency
  • Validator error handling for better user experience

Changed

  • Complexity validation now uses token-based thresholds (spec 71)
  • Web package downgraded to Tailwind v3 for better compatibility
  • Enhanced spec detail pages with timeline and metadata display

[0.2.0] - 2025-11-10

🎉 Official Public Release - Production Ready

This is the official v0.2.0 release, treating v0.1.x as alpha versions. LeanSpec is now production-ready for teams and solo developers.

Highlights

First Principles Foundation:

  • Operationalized five first principles with validation tooling
  • Context Economy enforced: Specs under 300 lines, warnings at 400+
  • Signal-to-Noise validation: Every line must inform decisions
  • Complete philosophy documentation guiding methodology

Quality & Validation:

  • Comprehensive lean-spec validate with complexity analysis
  • Lint-style output format matching ESLint/TypeScript conventions
  • Sub-spec validation and relationship checking
  • Dogfooding complete: All specs follow our own principles

Documentation Excellence:

  • 100% accurate documentation site (verified)
  • AI-assisted spec writing guide
  • Clear WHY vs HOW separation in docs
  • Comprehensive migration guides from ADRs/RFCs
  • First principles deeply documented

Developer Experience:

  • Unified dashboard (board + stats + health metrics)
  • Pattern-aware list grouping with visual clarity
  • Improved init flow with pattern selection
  • MCP server stability improvements
  • Better error handling throughout

Added

New Commands:

  • lean-spec migrate - Migrate from existing tools (ADRs, RFCs, design docs)
  • lean-spec archive - Archive completed specs with metadata updates
  • lean-spec backfill - Backfill timestamps from git history
  • lean-spec validate - Comprehensive spec validation

Core Features:

  • First principles validation (Context Economy, Signal-to-Noise, etc.)
  • Complexity analysis for specs and sub-specs
  • Bidirectional related and directional depends_on relationships
  • Sub-spec file support with validation
  • Pattern-based folder organization

Changed

Breaking Changes:

  • lean-spec validate output format now matches lint tools (ESLint-style)
  • Default validation mode is quiet success (use --verbose for all details)

User Experience:

  • Unified dashboard combining board + stats + health summary
  • Pattern-aware list with visual icons and better grouping
  • Enhanced init flow with template/pattern selection
  • Clearer stats dashboard with actionable insights

Fixed

  • MCP server error handling and stability
  • Documentation accuracy across all pages
  • Test suite: 402/402 passing (100%)
  • TypeScript/lint: Zero errors
  • Frontmatter parsing edge cases

Philosophy & Methodology

This release operationalizes LeanSpec's five first principles:

  1. Context Economy - Fit in working memory (<300 lines target, 400 max)
  2. Signal-to-Noise Maximization - Every word informs decisions
  3. Intent Over Implementation - Capture why, not just how
  4. Bridge the Gap - Both human and AI understand
  5. Progressive Disclosure - Add complexity only when pain is felt

Practice What We Preach:

  • All specs validated against principles
  • Large specs split using sub-spec pattern
  • Documentation follows progressive disclosure
  • Validation tooling prevents principle violations

Migration Notes

From v0.1.x:

  • Run lean-spec validate to check your specs
  • Review any specs >400 lines and consider splitting
  • Update to new validate output format (ESLint-style)
  • No breaking changes to commands or file formats

From other tools:

  • Use lean-spec migrate for ADRs, RFCs, design docs
  • See documentation for detailed migration guides
  • AI-assisted migration available (Claude, Copilot)

Acknowledgments

Built with dogfooding: 63 specs written, 28 archived, all following our own principles.

0.1.5 - 2025-11-10

Fixed

  • MCP server version now also read dynamically from package.json
  • Complete version consistency across CLI and MCP server

0.1.4 - 2025-11-10

Fixed

  • Version now read dynamically from package.json instead of hardcoded in CLI
  • Ensures version consistency across the package

0.1.3 - 2025-11-10

Added

New Commands:

  • lean-spec migrate - Migrate from existing tools (ADRs, RFCs, design docs) with AI assistance
  • lean-spec archive - Archive completed specs with automatic frontmatter updates
  • lean-spec backfill - Backfill timestamps and metadata from git history

Documentation Enhancements:

  • Complete documentation site overhaul with improved information architecture
  • AI-assisted spec writing guide with philosophy and best practices
  • Migration guides for teams coming from ADRs, RFCs, and other tools
  • First principles documentation (Context Economy, Signal-to-Noise, etc.)
  • Comprehensive core concepts guide with practical examples

Quality & Validation:

  • Enhanced lean-spec validate with complexity analysis
  • Spec relationship clarity with bidirectional related and directional depends_on
  • Improved frontmatter handling and metadata management

Changed

User Experience:

  • Unified dashboard combining board view with project health metrics
  • Pattern-aware list grouping with visual icons and better organization
  • Improved init flow with pattern selection
  • Enhanced stats dashboard with actionable insights
  • Better MCP error handling and stability

Documentation:

  • Restructured docs with clearer navigation and information flow
  • Updated README with AI-first positioning
  • Comprehensive examples and use cases
  • Improved CLI command documentation

Fixed

  • MCP server stability issues with frontmatter parsing
  • TypeScript type errors in migrate command
  • Documentation accuracy issues across all guides
  • Frontmatter handling edge cases

Philosophy

This UAT release operationalizes LeanSpec's five first principles:

  1. Context Economy - Specs fit in working memory (<400 lines)
  2. Signal-to-Noise - Every word informs decisions
  3. Intent Over Implementation - Capture why, not just how
  4. Bridge the Gap - Both human and AI understand
  5. Progressive Disclosure - Add complexity only when needed

Notable Completed Specs in this Release:

  • 063: Migration from existing tools
  • 062: Documentation information architecture v2
  • 061: AI-assisted spec writing
  • 060: Core concepts coherence
  • 058: Docs overview polish
  • 057: Docs validation comprehensive
  • 056: Docs site accuracy audit
  • 055: README redesign (AI-first)
  • 054: Validate output (lint-style)
  • 052: Branding assets
  • 051: First principles documentation
  • 049: LeanSpec first principles foundation
  • 048: Spec complexity analysis
  • 047: Git backfill timestamps
  • 046: Stats dashboard refactor
  • 045: Unified dashboard
  • 044: Spec relationships clarity

Testing:

  • All 261 tests passing (100% pass rate)
  • Zero critical bugs
  • MCP server stable
  • Documentation site builds cleanly

Ready for: UAT testing before official 0.2.0 launch

0.1.2 - 2025-11-10

Changed

BREAKING: Command and directory naming migration

  • Command name: lspec → lean-spec (full name for clarity and consistency)
  • Config directory: .lspec/ → .lean-spec/ (matches package and command name)
  • Binary: Only lean-spec command available (removed lspec alias)

Benefits:

  • ✅ Consistency: Package name, command, and config directory all use lean-spec
  • ✅ Clarity: npx lean-spec works immediately (matches npm package name)
  • ✅ Simplicity: Single command to remember, no abbreviations

Migration Guide for Existing Users:

  1. Uninstall old version:

    npm uninstall -g lean-spec

  2. Install new version:

    npm install -g lean-spec

  3. Update existing projects:

    # Rename config directory
mv .lspec .lean-spec

  4. Update commands:

    • Old: lspec init → New: lean-spec init
    • Old: lspec board → New: lean-spec board
    • Old: npx lspec → New: npx lean-spec

All documentation, examples, and specs updated to reflect new naming.

0.1.1 - 2025-11-07

Changed

BREAKING: lspec validate output format redesigned (spec 54)

  • Output now follows mainstream lint tool conventions (ESLint, TypeScript, Prettier)
  • File-centric grouping: All issues for a spec are shown together
  • Quiet success by default: Only specs with issues are shown, passing specs are summarized
  • ESLint-style format: Aligned columns with severity message rule-name
  • Relative paths shown instead of absolute paths
  • Exit codes remain unchanged: 0 for success/warnings, 1 for errors

Added

lspec validate new flags:

  • --verbose: Show all passing specs (restores detailed output)
  • --quiet: Suppress warnings, only show errors
  • --format json: Output results as JSON for CI integration
  • --rule <name>: Filter issues by specific rule (e.g., max-lines, frontmatter)

Migration Guide:

  • If you prefer the old verbose output, use lspec validate --verbose
  • The new default shows only specs with issues for better signal-to-noise ratio
  • Exit codes are unchanged, so CI pipelines should work without modification
  • JSON format is available for custom parsing: lspec validate --format json

Fixed

  • Fixed potential crash in validate formatter when spec name is missing

0.1.0 - 2025-11-02

Added

Core Features:

  • CLI tool with comprehensive command set (init, create, list, search, update, archive, files, templates)
  • Project initialization with three built-in templates (minimal, standard, enterprise)
  • Spec creation with automatic directory structure and frontmatter
  • Frontmatter support with status tracking, tags, priority, and custom fields
  • Full-text search across specs using fuzzy matching
  • Dependency tracking between specs

Visualization & Organization:

  • lspec board - Kanban-style board view with status columns
  • lspec stats - Work distribution and completion analytics
  • lspec timeline - Chronological view of spec creation
  • lspec gantt - Gantt chart visualization (requires mermaid-cli)
  • lspec deps - Dependency graph visualization

Developer Experience:

  • Interactive prompts for all commands
  • Colorized terminal output
  • Spinner animations for long operations
  • Table-based displays for list views
  • React-based UI components (Ink)

Template System:

  • Custom template support
  • Template marketplace (lspec templates marketplace)
  • Template variables for dynamic content
  • Three built-in templates with different complexity levels

Testing & Quality:

  • 62 passing tests with comprehensive coverage
  • Integration tests for all commands
  • TypeScript with strict mode
  • Prettier configuration

Documentation

  • Complete README with examples and API reference
  • AGENTS.md for AI agent integration
  • CONTRIBUTING.md for contributors
  • Individual spec READMEs for all 13 completed specs

Technical

  • Built with TypeScript and tsup for fast builds
  • Commander.js for CLI argument parsing
  • Inquirer for interactive prompts
  • Chalk and Ora for beautiful terminal UI
  • Gray-matter for frontmatter parsing
  • Dayjs for date handling