Release v0.2.10: Inline Metadata Editing, MCP Auto-Setup, Multi-Project Improvements

Release v0.2.10 - 2025-12-05

🎉 Major Features

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)

• 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)

• 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

✨ Enhancements

• Multi-project Management UI Improvements (spec 141)

  • "Manage Projects" option in project switcher dropdown
  • Inline project name editing on /projects page
  • Color picker for project customization
  • Project path validation with status indicators

• Multi-project Mode Improvements (spec 142, spec 149)

  • All navigation links now use project-scoped URLs
  • Added SSR for multi-project dependencies, stats, and context pages
  • Projects page has dedicated layout without sidebar
  • Fixed path overflow in Add Project dialog
  • Dependency graph now works in multi-project mode

• Performance Optimization

  • Lightweight specs for list views - reduces initial load by ~90%
  • Spec list API no longer returns full contentMd

🐛 Bug Fixes

• Dependencies page now works on custom ports (lean-spec ui --port 3002)
• Spec detail dependencies now available in multi-project mode
• MCP deps tool now correctly resolves spec paths by sequence number
• Fixed duplicate icons in Status/Priority editors
• Dependencies page light theme contrast improved
• Fixed lspec → lean-spec command references
• Project switcher navigation fixed

📦 Published Packages

• @leanspec/[email protected]
• [email protected]
• @leanspec/[email protected]
• @leanspec/[email protected]

🔗 Links

• npm: lean-spec
• npm: @leanspec/ui
• npm: @leanspec/mcp
• Documentation
• Full Changelog

v0.2.9: Dependency Visualization & Simplified Relationships

What's New in v0.2.9

🎯 Project-wide Dependency Visualization

New /dependencies page in the Web UI for visualizing your entire project's dependency structure:

• Bird's-eye view of all specs and their relationships using DAG layout
• Interactive graph with zoom/pan controls powered by ReactFlow
• Click to navigate directly to spec details
• Filter by status, priority, and tags
• Color-coded nodes: amber=planned, blue=in-progress, green=complete
• Spec selector to focus on a specific spec's dependency chain
• Critical path highlighting for transitive dependencies

🔄 Simplified Spec Relationships

Breaking Change: We've removed the related field, keeping only depends_on.

• 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 a single relationship type
• Removed --related flag from lean-spec link and lean-spec unlink commands

🐛 Bug Fixes

• Chinese/Unicode spec name support - Fixed sequence number detection for non-ASCII spec names (e.g., 001-测试)
• Spec frontmatter validation - Fixed YAML parsing errors from orphaned array items
• Docs-site integration - Converted from submodule to direct inclusion for simpler maintenance

📦 Packages

• [email protected]
• @leanspec/[email protected]
• @leanspec/[email protected]
• @leanspec/[email protected]

Full Changelog: v0.2.8...v0.2.9

v0.2.8

What's New

Added

• Safe re-initialization workflow (spec 127) - Improved lean-spec init for existing projects with upgrade/reset/full-reset strategies
• MCP link and unlink tools (spec 129) - Manage spec relationships directly from AI agents
• Project context visibility in Web UI (spec 131) - View AGENTS.md, README.md from the web interface
• Focus mode in spec detail view - Distraction-free reading experience
• Directory-based template support (spec 128) - Templates can be organized in subdirectories

Changed

• Testing infrastructure overhaul (spec 130) - Comprehensive test strategy with new regression templates

Fixed

• Tutorial URLs, analytics tracking, README link formatting

Install/Update

npm install -g [email protected]

Full Changelog: v0.2.7...v0.2.8

Release v0.2.7: AI Tool Auto-detection, MCP-first Agent Experience, Advanced Search

Release v0.2.7 - 2025-11-26

🎉 Major Features

• 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)
  • 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 creates tool-specific symlinks (CLAUDE.md, GEMINI.md → AGENTS.md)
  • New --agent-tools flag for non-interactive mode
  • New MCP prompts: checkpoint, create-spec
  • Stale spec warnings in board output

• Dependency Alignment Validation (spec 122) - Automated detection of content/frontmatter misalignment

  • New --check-deps flag for lean-spec validate command
  • Detects patterns like "spec 045", "depends on", "related to"
  • Outputs actionable fix commands

• Advanced Search Capabilities (spec 124) - Enhanced search for power users

  • Cross-field term matching
  • Boolean operators: AND, OR, NOT
  • Field-specific search: status:in-progress, tag:api, priority:high
  • Date range filters: created:>2025-11-01
  • Fuzzy matching with ~ suffix

• Native Diagram Rendering (spec 119) - Mermaid diagram support in Web UI

  • Client-side Mermaid rendering for flowcharts, sequence diagrams, etc.
  • Dark mode theme support

✨ Other Enhancements

• Parallel spec implementation workflow documentation (spec 118)
• AI coding agent integration guidance (spec 123)
• Onboarding project context clarity improvements (spec 125)
• AGENTS.md restructured for MCP-first approach

📦 Published Packages

• @leanspec/[email protected]
• [email protected]
• @leanspec/[email protected]
• @leanspec/[email protected]

🔗 Links

• npm: lean-spec
• npm: @leanspec/mcp
• npm: @leanspec/ui
• Documentation
• Full Changelog

Release v0.2.6: Example Projects, Template Simplification & JSON Output

Release v0.2.6 - 2025-11-25

🎉 Major Changes

Example Projects & Tutorial Support

• Scaffold complete tutorial projects with lean-spec init --example
• Three ready-to-use examples: dark-theme, dashboard-widgets, api-refactor
• Interactive example selection mode
• Automatic LeanSpec initialization in scaffolded projects
• New lean-spec examples command to list available examples

Template System Simplification

• Removed Handlebars template engine layer (15+ component files eliminated)
• Direct maintenance of 2 templates: standard (default) and detailed (sub-specs demo)
• Faster iteration without build step - edit files directly
• Improved AI workflow with stronger CLI command emphasis
• Shared AGENTS.md across templates for consistency

JSON Output Support

• Added --json flag to 8 CLI commands for programmatic use
• Machine-readable output for automation and scripting
• Commands: list, board, search, check, files, timeline, backfill, gantt

✨ Enhancements

Chinese Translation Quality

• Comprehensive translation guidelines in documentation
• Professional localization standards with 40+ technical terms
• Natural Chinese expression patterns for better readability
• Quality checklist for translation validation

📦 Published Packages

• @leanspec/[email protected]
• [email protected]
• @leanspec/[email protected]
• @leanspec/[email protected]

🔗 Links

• npm: lean-spec
• npm: @leanspec/ui
• npm: @leanspec/mcp
• Documentation
• Full Changelog

📝 Installation

# Install globally
npm install -g [email protected]

# Try an example project
npx lean-spec init --example dark-theme

# Launch web UI
npx lean-spec ui

🙏 Thank You

Thank you to all contributors and users who provided feedback to make this release possible!

Release v0.2.5: UI Consolidation & MCP Package

Release v0.2.5 - November 18, 2025

🎉 Major Changes

UI Package Consolidation (spec 103)

• Merged @leanspec/web into @leanspec/ui for simpler architecture
• Eliminated complex symlink handling and node_modules distribution issues
• Single publishable Next.js app package instead of separate packages
• No breaking changes to user-facing lean-spec ui command

New: @leanspec/mcp Package (spec 102)

• Dedicated npm package for MCP server integration with AI assistants
• Simpler onboarding: Use npx @leanspec/mcp directly in IDE configs
• Zero-config setup for Claude Desktop, Cline, and Zed
• Pure passthrough design with automatic dependency management

🐛 Bug Fixes

Critical: @leanspec/ui Packaging (spec 104)

• Fixed "Cannot find module 'next'" error in published package
• Now correctly bundles all Next.js dependencies (~18.3 MB compressed)
• Users can successfully run lean-spec ui via published npm package

UI Command Improvements

• Better signal handling for Ctrl+C and Ctrl+D
• Proper process cleanup and graceful shutdown

✨ Enhancements

Enhanced Dependency Commands (spec 099)

• Improved CLI and MCP tools for managing spec relationships
• Better dependency graph visualization
• Enhanced link and unlink commands with better error handling

Automated Publishing

• GitHub Action workflow for dev releases
• Package preparation scripts for handling workspace dependencies

📦 Published Packages

• @leanspec/[email protected]
• [email protected] (CLI)
• @leanspec/[email protected] (NEW!)
• @leanspec/[email protected]

🔗 Links

• npm: lean-spec
• npm: @leanspec/mcp
• npm: @leanspec/ui
• Documentation
• Full Changelog

v0.2.4 - Bug Fixes and UI Improvements

Fixed

• CLI lean-spec ui pnpm flow - 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 - 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)

Full Changelog: https://github.com/codervisor/lean-spec/blob/main/CHANGELOG.md\#024---2025-11-17

v0.2.3 - TypeScript Fixes

🐛 Bug Fixes

This release resolves all TypeScript compilation errors that were blocking the v0.2.3 release:

Fixed TypeScript Errors

• Core package: Exported type for use in CLI
• SpecInfo interface: Made Mon Nov 17 21:08:28 CST 2025 field optional to match core package definition
• Search command: Fixed type mismatches for �]2;��]1;� and fields (cast to string)
• MCP SDK integration: Updated tool and resource handler signatures to include parameter required by SDK v1.21.0
• Isolate command: Added missing field to frontmatter
• Console capturing: Fixed broken console log/error capturing in backfill, files, and validate tools
• Type literals: Added as const annotations to all MCP tool response types
• Type registry: Used any cast to work around SDK type narrowing issues

Summary

All 30+ TypeScript errors have been resolved. The package now compiles cleanly with and builds successfully. All CLI tests pass.

Full Changelog: v0.2.2...v0.2.3

v0.2.2 - Critical Bug Fix

🐛 Critical Bug Fix

Fixes the dependency issue that prevented v0.2.1 from being installed.

Fixed

• Critical npm publishing bug: Removed dependency causing installation failures
• Bundling issue: Marked as external to avoid dynamic require errors in ESM
• Added to CLI dependencies for proper resolution

Added

• Template Engine for AGENTS.md (spec 073) - Dynamic template system for maintaining AGENTS.md
• Intelligent Search Engine (spec 075) - Relevance-ranked search with TF-IDF scoring
• Programmatic Spec Management (spec 059, Phase 1-2) - analyze, split, compact commands
• Programmatic Spec Relationships (spec 076) - CLI and MCP tools for managing dependencies
• Sub-spec Template System (spec 078) - Documentation for multi-file spec structures
• Archiving Strategy (spec 077) - Documentation for proper spec archival workflows

Changed

• Search commands now use intelligent ranking algorithm
• MCP search tool upgraded with relevance scoring
• AGENTS.md validation enforces template system consistency

Installation

npm install -g lean-spec@latest

Full Changelog: v0.2.1...v0.2.2

v0.2.0 - Official Public Release

[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.