lean-spec 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,123 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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:**
+   ```bash
+   npm uninstall -g lean-spec
+   ```
+
+2. **Install new version:**
+   ```bash
+   npm install -g lean-spec
+   ```
+
+3. **Update existing projects:**
+   ```bash
+   # 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
@@ -88,5 +205,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Gray-matter for frontmatter parsing
 - Dayjs for date handling
 
+[0.1.3]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.3
+[0.1.2]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.2
 [0.1.1]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.1
 [0.1.0]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.0

package/README.md

@@ -31,7 +31,7 @@ Specs under 300 lines. Intent-focused. Machine-readable. Adapts to your workflow
 <p align="center">
   <a href="#quick-start-5-minutes"><strong>Quick Start (5 Minutes) →</strong></a> •
   <a href="https://www.lean-spec.dev"><strong>Documentation</strong></a> •
-  <a href="https://www.lean-spec.dev/docs/examples"><strong>Examples</strong></a>
+  <a href="https://www.lean-spec.dev/docs/guide/ai-executable-patterns"><strong>Examples</strong></a>
 </p>
 
 ---
@@ -98,7 +98,7 @@ priority: high
 # Unified Dashboard
 
 ## Overview
-Combine `lspec board` and `lspec stats` into a single, comprehensive
+Combine `lean-spec board` and `lean-spec stats` into a single, comprehensive
 project health view. Give users instant insight into project status,
 bottlenecks, and team velocity.
 
@@ -136,9 +136,10 @@ LeanSpec isn't arbitrary rules—it's derived from fundamental constraints of wo
 ### 🧠 Context Economy
 **Specs <300 lines → Fit in working memory**
 
-- **Physics**: AI context windows are bounded (~20K effective tokens)
-- **Biology**: Human working memory is limited (7±2 items)
+- **Physics**: AI performance degrades with longer context (quality drops beyond 50K tokens despite 200K limits)
+- **Biology**: Human working memory is limited (7±2 items, 5-10 min attention)
 - **Economics**: Large contexts cost more time and money
+- **Reality**: Attention is the scarce resource, not storage
 - **Result**: Keep specs under 300 lines, split complex features
 
 ### ✂️ Signal-to-Noise Maximization
@@ -177,7 +178,7 @@ LeanSpec isn't arbitrary rules—it's derived from fundamental constraints of wo
 
 **These aren't preferences—they're constraints.** Physics (context windows), biology (working memory), and economics (token costs) dictate what works.
 
-📖 [Deep dive: First Principles Guide →](https://www.lean-spec.dev/docs/guide/first-principles)
+📖 [Deep dive: First Principles Guide →](https://www.lean-spec.dev/docs/guide/understanding#the-five-first-principles)
 
 ---
 
@@ -199,7 +200,7 @@ MCP-native specs. Works with any tool that supports Model Context Protocol.
 Track progress without leaving the terminal:
 
 ```bash
-$ lspec board
+$ lean-spec board
 
 📋 Spec Kanban Board
 
@@ -219,7 +220,7 @@ $ lspec board
 ```
 
 ```bash
-$ lspec stats
+$ lean-spec stats
 
 📊 Project Stats
 
@@ -271,7 +272,7 @@ Custom fields fully supported. Adapts to your workflow as you grow.
 ```bash
 npm install -g lean-spec
 cd your-project
-lspec init
+lean-spec init
 ```
 
 ### 2. Work with Your AI Tool
@@ -281,7 +282,7 @@ lspec init
 ```
 👤 You: "Create a spec for user authentication with OAuth2."
 
-🤖 AI: [runs lspec create user-authentication]
+🤖 AI: [runs lean-spec create user-authentication]
       "I've created specs/001-user-authentication/README.md.
       Here's the spec..."
 
@@ -295,19 +296,19 @@ lspec init
 
 ```bash
 # Check project status
-lspec board
+lean-spec board
 
 # View spec with AI-friendly output
-lspec view user-authentication --json
+lean-spec view user-authentication --json
 
 # Update status as you progress
-lspec update user-authentication --status in-progress
+lean-spec update user-authentication --status in-progress
 ```
 
 **The workflow:**
-1. ✅ Ask AI to create spec (it uses `lspec create`)
+1. ✅ Ask AI to create spec (it uses `lean-spec create`)
 2. ✅ AI reads spec and implements (spec fits in context)
-3. ✅ Track with `lspec board` / `lspec stats`
+3. ✅ Track with `lean-spec board` / `lean-spec stats`
 4. ✅ Update status as work progresses
 
 **Why this works:**
@@ -317,9 +318,9 @@ lspec update user-authentication --status in-progress
 - You drive, AI executes
 
 **Next steps:**
-- 📘 [Full CLI Reference](https://www.lean-spec.dev/docs/cli-reference) - All commands
-- 🎨 [Choose a Template](https://www.lean-spec.dev/docs/templates) - Minimal, standard, or enterprise
-- 🤖 [AI Agent Setup](AGENTS.md) - Configure Cursor, Claude, Aider
+- 📘 [Full CLI Reference](https://www.lean-spec.dev/docs/reference/cli) - All commands
+- 🎨 [Choose a Template](https://www.lean-spec.dev/docs/guide/templates) - Minimal, standard, or enterprise
+- 🤖 [AI Agent Setup](AGENTS.md) - Configure AI coding tools
 
 ---
 
@@ -387,24 +388,24 @@ We dogfood our own methodology. Specs that fit in AI context enable the velocity
 ## Learn More
 
 ### 📚 Documentation
-- [Getting Started Guide](https://www.lean-spec.dev/docs/getting-started) - Complete setup walkthrough
-- [First Principles](https://www.lean-spec.dev/docs/guide/first-principles) - The philosophy behind LeanSpec
-- [CLI Reference](https://www.lean-spec.dev/docs/cli-reference) - All commands with examples
+- [Getting Started Guide](https://www.lean-spec.dev/docs/guide/getting-started) - Complete setup walkthrough
+- [First Principles](https://www.lean-spec.dev/docs/guide/understanding#the-five-first-principles) - The philosophy behind LeanSpec
+- [CLI Reference](https://www.lean-spec.dev/docs/reference/cli) - All commands with examples
 
 ### 🛠️ Integrations
 - [AI Agent Configuration](AGENTS.md) - Cursor, Copilot, Aider setup
 - [MCP Server](docs/MCP-SERVER.md) - Claude Desktop integration
-- [VS Code Extension](https://www.lean-spec.dev/docs/tools/vscode) - Enhanced editor support
+- [VS Code Extension](https://www.lean-spec.dev/docs/roadmap#vs-code-extension) - Enhanced editor support (planned)
 
 ### 🎓 Guides
 - [Custom Fields](https://www.lean-spec.dev/docs/guide/custom-fields) - Adapt to your workflow
-- [Sub-Specs](https://www.lean-spec.dev/docs/guide/sub-specs) - Manage complex features
-- [Folder Structure](https://www.lean-spec.dev/docs/guide/folder-structure) - Organize your specs
+- [Templates](https://www.lean-spec.dev/docs/guide/templates) - Choose the right structure
+- [Frontmatter](https://www.lean-spec.dev/docs/guide/frontmatter) - Metadata and organization
 
 ### 🤝 Community
 - [GitHub Issues](https://github.com/codervisor/lean-spec/issues) - Report bugs or request features
 - [Contributing Guide](CONTRIBUTING.md) - Join the project
-- [Examples](https://www.lean-spec.dev/docs/examples) - Real-world usage patterns
+- [AI-Executable Patterns](https://www.lean-spec.dev/docs/guide/ai-executable-patterns) - Real-world usage patterns
 
 ---