@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/dist/standalone/specs/055-readme-redesign-ai-first/CONCERNS-ANALYSIS.md

@@ -1,351 +0,0 @@
-# README Redesign - Concerns Analysis
-
-**Date**: 2025-11-06  
-**Purpose**: Address concerns about marketing language and validate pain points against real SDD landscape
-
----
-
-## 🔍 Research Summary: Current SDD Landscape
-
-### 1. **GitHub Spec Kit** (Most Popular - 45.5k stars)
-
-**Approach:**
-- **Philosophy**: "Specifications become executable" - specs directly generate implementations
-- **Target**: 0→1 greenfield development (creating from scratch)
-- **Process**: Constitution → Specify → Plan → Tasks → Implement
-- **Format**: Multi-file structure with slash commands
-- **Positioning**: "Build high-quality software faster" / "Focus on product scenarios instead of vibe coding"
-- **Overhead**: Requires Python, uv tool installer, git, AI coding agent setup
-
-**Key Differences from LeanSpec:**
-- Much heavier process (5-step workflow)
-- Requires external dependencies
-- Focused on generating code from specs (implementation-first)
-- Uses slash commands that AI executes sequentially
-- Better for brand new projects
-
-### 2. **OpenSpec** (Emerging Alternative)
-
-**Approach:**
-- **Philosophy**: "Align humans and AI with spec-driven development"
-- **Target**: Brownfield (1→n) - modifying existing code
-- **Process**: Proposal → Review → Implement → Archive
-- **Format**: Separates specs (`specs/`) from changes (`changes/`)
-- **Positioning**: "Lightweight... works great beyond 0→1"
-- **Overhead**: Requires Node.js >= 20.19.0
-
-**Key Differences from LeanSpec:**
-- Change-tracking focused (proposals + deltas)
-- More complex folder structure (specs vs changes)
-- Explicit differentiation from Spec Kit ("brownfield-first")
-- Still requires initialization and workflow setup
-
-### 3. **"Vibe Coding"** (No Formal Specs)
-
-**Approach:**
-- Just chat with AI, iterate in code
-- No formal spec structure
-- Relies on chat history for context
-
-**Problems Reported:**
-- AI loses context across sessions
-- Hard to maintain consistency
-- Team misalignment
-- Context window overflow on complex features
-
----
-
-## ✅ Validation: Are Our Pain Points Real?
-
-### Pain Point 1: "2,000-line RFC → Context too large"
-
-**Status**: ✅ **VALIDATED - This is real and widespread**
-
-**Evidence:**
-- GitHub Spec Kit explicitly positions against "vibe coding"
-- OpenSpec's tagline: "AI coding assistants are powerful but unpredictable when requirements live in chat history"
-- Spec Kit's entire value prop is structured specifications to avoid context problems
-- Common pattern: Traditional specs (RFCs, PRDs) are 1000+ lines
-
-**Our positioning**: Accurate, but could be more nuanced:
-- Not all specs are 2,000 lines (could use "Traditional specs" instead of "2,000-line RFC")
-- The real problem isn't just length - it's structure + length + stale content
-
-### Pain Point 2: "Stale specs because too painful to update"
-
-**Status**: ✅ **VALIDATED - Industry-wide problem**
-
-**Evidence:**
-- Spec Kit solves this by making specs executable (different solution)
-- OpenSpec solves this with change proposals (different solution)
-- Common complaint: Documentation rot
-- Traditional SDD assumption: Specs written once, rarely updated
-
-**Our positioning**: Accurate - this is a fundamental SDD problem
-
-### Pain Point 3: "Process Paralysis - too heavy or too light"
-
-**Status**: ⚠️ **PARTIALLY VALIDATED - Needs refinement**
-
-**Evidence:**
-- Spec Kit IS heavy (Python, uv, multi-step workflow, slash commands)
-- OpenSpec positions as "lightweight" but still requires Node.js + initialization
-- "Vibe coding" (no specs) is indeed too light
-- **BUT**: The middle ground isn't empty - OpenSpec already claims it
-
-**Our positioning**: Need to be more specific:
-- We're not the only "middle ground"
-- Our differentiator: **Simplicity + File-based + No workflow overhead**
-- Spec Kit: Heavy workflow, executable specs
-- OpenSpec: Change tracking, proposals system
-- **LeanSpec**: Just markdown files with structure, no workflow enforcement
-
----
-
-## 🚨 Marketing Language Concerns
-
-### Concern 1: "Your specs are too big for AI to read"
-
-**Risk Level**: 🟡 **MEDIUM**
-
-**Issues:**
-- Assumes user already writes specs (many don't)
-- Slightly aggressive/presumptive tone
-- Might alienate users with good practices
-
-**Alternatives:**
-1. "Traditional specs overflow AI context windows" (more neutral)
-2. "Spec-Driven Development designed for AI collaboration" (positive framing)
-3. "Specs that fit in AI working memory" (factual)
-
-**Recommendation**: Option 3 - factual, clear, not accusatory
-
-### Concern 2: "2,000-line RFC" specific number
-
-**Risk Level**: 🟢 **LOW**
-
-**Reality Check:**
-- This is actually conservative (many RFCs are longer)
-- Provides concrete contrast (good for marketing)
-- Easy to defend with examples
-
-**Recommendation**: Keep it, but add context: "Traditional 2,000-line RFCs..."
-
-### Concern 3: Comparing to Spec Kit/OpenSpec implicitly
-
-**Risk Level**: 🟡 **MEDIUM**
-
-**Current State:**
-- We don't mention competitors explicitly (good)
-- But our positioning overlaps with OpenSpec's "lightweight" claim
-- Spec Kit has massive mindshare (45.5k stars)
-
-**Differentiation Strategy:**
-We need to be clearer about what makes us different:
-
-| Feature | Spec Kit | OpenSpec | **LeanSpec** |
-|---------|----------|----------|--------------|
-| **Dependencies** | Python, uv, Git | Node.js 20+ | Node.js (any) |
-| **Workflow** | 5-step process | Proposal system | Free-form |
-| **Philosophy** | Executable specs | Change tracking | Intent documentation |
-| **Target** | 0→1 greenfield | 1→n brownfield | Both, minimal |
-| **Overhead** | High (slash commands) | Medium (proposals) | **Low (just files)** |
-| **Best For** | Generating code | Tracking changes | **Team alignment** |
-
-**Recommendation**: Emphasize our unique position:
-- "No workflow to follow - just write specs"
-- "No proposals, no tasks, no multi-step process"
-- "Philosophy over process"
-
-### Concern 4: "AI-First" vs "AI-Native" terminology
-
-**Risk Level**: 🟢 **LOW**
-
-**Analysis:**
-- Both Spec Kit and OpenSpec use "AI coding assistants"
-- "AI-Native" is clear and established
-- "AI-First" implies priority ordering (good)
-
-**Recommendation**: Use both - "AI-First Development" (headline) + "AI-Native Integration" (features)
-
----
-
-## 📊 Competitive Positioning: What We Actually Are
-
-### What We're NOT:
-- ❌ An automated code generator (that's Spec Kit)
-- ❌ A change proposal system (that's OpenSpec)
-- ❌ A project management tool
-- ❌ A replacement for documentation
-
-### What We ARE:
-- ✅ **A lightweight spec format** that fits AI context windows
-- ✅ **A philosophy** for writing maintainable specs
-- ✅ **A CLI tool** for managing spec files
-- ✅ **A bridge** between human intent and AI implementation
-
-### Our Unique Value:
-1. **Simplest tool** - Just markdown + YAML frontmatter
-2. **Philosophy-driven** - First principles, not rigid rules
-3. **No workflow overhead** - No proposals, tasks, or multi-step processes
-4. **Truly lightweight** - No heavy dependencies
-5. **Fits existing practices** - Add structure to what you're already doing
-
----
-
-## 🎯 Recommended README Changes
-
-### 1. Refine the Hook (Addresses Concern 1)
-
-**Current:**
-```markdown
-## Your specs are too big for AI to read.
-
-Traditional specs overflow AI context windows...
-```
-
-**Recommended:**
-```markdown
-## Specs that fit in AI working memory
-
-Traditional 2,000-line RFCs overflow AI context windows. Your AI agent can't help 
-because it can't fit the full context.
-
-```diff
-- Heavyweight process (Spec Kit, RFCs) → AI context overflow
-- Vibe coding (no specs) → Team misalignment
-+ LeanSpec: Structure without overhead
-```
-
-**Why**: Less presumptive, acknowledges existing tools, positions as third way
-
-### 2. Add Explicit Differentiation Section
-
-**New Section: "How LeanSpec is Different"**
-
-```markdown
-## How LeanSpec is Different
-
-**From Heavyweight Tools (Spec Kit, traditional RFCs):**
-- No multi-step workflows or slash commands
-- No external dependencies or setup overhead
-- Write specs, not executable programs
-
-**From Lightweight Approaches (vibe coding):**
-- Enough structure for AI agents to act
-- Team alignment through shared specs
-- Maintainable documentation
-
-**From Change-Tracking Systems (OpenSpec):**
-- No proposals or change folders
-- Direct spec editing (not diff-based)
-- Philosophy over process
-
-**LeanSpec = Just the specs.** Files, structure, principles. No ceremony.
-```
-
-### 3. Soften Comparative Language
-
-**Current**: "Traditional SDD is either too heavy... or too light..."
-
-**Recommended**: "Many teams struggle with either heavyweight processes or no process at all. LeanSpec provides structure without overhead."
-
-### 4. Add "When to Use Which Tool" Section
-
-```markdown
-## Choose the Right Tool
-
-| Use This | When You Need |
-|----------|---------------|
-| **Spec Kit** | Automated code generation from specs |
-| **OpenSpec** | Change proposals and delta tracking |
-| **LeanSpec** | Lightweight team alignment and AI context |
-| **Vibe Coding** | Rapid prototyping, solo experiments |
-
-Not sure? Start with LeanSpec - it's the easiest to adopt and remove if it doesn't fit.
-```
-
----
-
-## ✨ Revised Pain Points (More Accurate)
-
-### Scenario 1: The Context Overflow 🔴
-**Before**: "You paste your 2,000-line RFC into Cursor..."
-**After**: "You paste a traditional spec into Cursor. 'Context too large.' Your AI agent can't help - it can't fit the full context."
-
-**Why**: More neutral, acknowledges various spec types
-
-### Scenario 2: The Stale Spec 📄
-**Keep as is** - This is validated and accurate
-
-### Scenario 3: The Process Paralysis ⚖️
-**Before**: "Heavyweight RFCs—too slow... 'just code'—AI agents get lost..."
-**After**: "You tried Spec Kit—powerful but heavyweight. You tried vibe coding—fast but team gets misaligned. Where's the tool that's just lightweight specs?"
-
-**Why**: Acknowledges actual tools, positions us more accurately
-
----
-
-## 🎬 Final Recommendations
-
-### ✅ Keep These Elements:
-1. First principles framing (validated by research)
-2. <300 line guidance (differentiator)
-3. "We practice what we preach" section (strong social proof)
-4. Real spec example (shows, not tells)
-
-### 🔄 Refine These Elements:
-1. Opening hook - less presumptive
-2. Add explicit competitive positioning
-3. Soften comparative language
-4. Add "when to use which tool" guidance
-
-### ➕ Add These Elements:
-1. "How LeanSpec is Different" section
-2. Acknowledgment of existing tools
-3. Clear positioning: "Philosophy, not process"
-4. "Start here if unsure" framing
-
-### ❌ Remove/Replace:
-1. "Your specs are too big" (too aggressive) → "Specs that fit..."
-2. Vague "heavyweight processes" → Name specific tools (when comparing)
-3. "Middle ground" claim → "Simplest approach" (more accurate)
-
----
-
-## 📈 Updated Positioning Statement
-
-**Old**: "The middle ground between heavyweight RFCs and vibe coding"
-
-**New**: "The simplest way to align your team and AI agents. Just specs, no ceremony."
-
-**Tagline options:**
-1. "Spec-Driven Development without the overhead" ✅ (Recommended)
-2. "Lightweight specs that fit AI working memory"
-3. "Philosophy over process for SDD"
-4. "Just the specs. None of the ceremony."
-
----
-
-## 🎯 Success Criteria for Revised README
-
-1. **Clarity**: Reader understands what LeanSpec is in 30 seconds
-2. **Differentiation**: Clear how we differ from Spec Kit, OpenSpec, vibe coding
-3. **Honesty**: Doesn't oversell or make false claims
-4. **Positioning**: Positioned as simplest/lightest, not "better"
-5. **Credibility**: Uses real examples, dogfooding stats, acknowledges alternatives
-
----
-
-**Next Steps:**
-1. Review this analysis with stakeholders
-2. Implement recommended README changes
-3. Get early user feedback on positioning
-4. Monitor for confusion or misunderstanding
-5. Iterate based on real user questions
-
-**Related Documents:**
-- [REDESIGN-DRAFT.md](REDESIGN-DRAFT.md) - Full proposed README
-- [CHANGES.md](CHANGES.md) - Change summary
-- [ANALYSIS-PART1.md](ANALYSIS-PART1.md) - Initial analysis
-- [ANALYSIS-PART2.md](ANALYSIS-PART2.md) - Implementation strategy

package/.next/standalone/packages/ui/dist/standalone/specs/055-readme-redesign-ai-first/DOCS-ALIGNMENT-ANALYSIS.md

@@ -1,238 +0,0 @@
-# Documentation Alignment Analysis
-
-**Date**: 2025-11-06  
-**Reviewer**: AI Agent  
-**Scope**: docs-site content vs current implementation
-
-## Executive Summary
-
-✅ **Overall Status**: Documentation is well-aligned with current implementation and design principles.
-
-**Key Findings**:
-- First principles documentation is accurate and comprehensive
-- CLI reference matches actual implementation (all commands exist)
-- Current repo uses **flat structure** (global numbering) - matches default in config
-- Minor inconsistencies in docs showing old date-based examples
-
-## Detailed Analysis
-
-### ✅ Well-Aligned Areas
-
-#### 1. First Principles (`docs/guide/first-principles.md`)
-**Status**: ✅ Excellent alignment
-
-- All 5 principles clearly documented
-- Matches AGENTS.md and REDESIGN-REFINED.md perfectly
-- Context Economy thresholds (<300 lines, 400 hard limit) consistent
-- Conflict resolution framework is clear
-- Examples are practical and actionable
-
-**No changes needed.**
-
-#### 2. Philosophy (`docs/guide/philosophy.md`)
-**Status**: ✅ Good alignment
-
-- Mindset-focused (not just format/tool)
-- Aligns with first principles
-- Emphasizes AI integration
-- Progressive disclosure philosophy clear
-
-**No changes needed.**
-
-#### 3. CLI Reference (`docs/reference/cli.md`)
-**Status**: ✅ Commands match implementation
-
-Verified all documented commands exist:
-- ✅ `lean-spec init`
-- ✅ `lean-spec create`
-- ✅ `lean-spec list`
-- ✅ `lean-spec update`
-- ✅ `lean-spec search`
-- ✅ `lean-spec archive`
-- ✅ `lean-spec view`
-- ✅ `lean-spec open`
-- ✅ `lean-spec templates`
-- ✅ `lean-spec stats`
-- ✅ `lean-spec board`
-- ✅ `lean-spec deps`
-
-**Minor inconsistency**: Documentation shows many examples with date-based structure (`specs/20251102/001-user-auth`), but current default is **flat structure** (`specs/001-user-auth/`).
-
-#### 4. AI Integration (`docs/ai-integration/index.md`)
-**Status**: ✅ Good alignment
-
-- Emphasizes AGENTS.md as primary integration
-- Clear integration methods
-- Practical examples and patterns
-- Aligns with REDESIGN-REFINED.md positioning
-
-**No changes needed.**
-
----
-
-### ⚠️ Minor Inconsistencies
-
-#### 1. Structure Pattern Examples
-
-**Issue**: Many CLI examples in docs show date-based structure, but:
-- Current default is `pattern: 'flat'` with global numbering
-- Actual specs/ folder uses flat structure (`014-complete-custom-frontmatter/`, `055-readme-redesign-ai-first/`)
-- Config default has `prefix: ''` (no date prefix)
-
-**Examples showing old format**:
-```bash
-# In CLI reference:
-specs/20251102/001-user-authentication  ❌ Old date-based
-specs/001-user-authentication/           ✅ Current flat structure
-```
-
-**Impact**: Low - Users can configure either pattern, but default examples should show flat structure.
-
-**Recommendation**: Update CLI reference examples to show flat structure as default, mention date-based as optional configuration.
-
----
-
-#### 2. Getting Started Guide Structure Explanation
-
-**File**: `docs/guide/getting-started.md`
-
-**Current text**: Shows correct structure explanation:
-- Project structure diagram with flat layout (`001-first-feature/`, `002-second-feature/`)
-- Note explaining default is flat with global numbering
-- Mentions date-based grouping as configuration option
-
-**Status**: ✅ Correct, but buried at bottom.
-
-**Recommendation**: Move this clarification higher in the guide, make it more prominent.
-
----
-
-#### 3. CLI Examples Consistency
-
-**Files affected**:
-- `docs/reference/cli.md`
-- `docs/guide/getting-started.md`
-
-**Current**: Mixed examples showing both formats
-- Some: `specs/20251102/001-user-auth` (date-based)
-- Some: `001-user-authentication` (flat)
-
-**Recommendation**: Standardize all examples to flat structure as default, add note:
-> **Note**: Examples show flat structure (default). For date-based grouping, see [Structure Configuration](/docs/reference/config#structure).
-
----
-
-## Recommendations
-
-### Priority 1: Update CLI Reference Examples
-
-**File**: `docs-site/docs/reference/cli.md`
-
-Replace date-based examples with flat structure:
-
-```diff
-- specs/20251102/001-user-authentication
-+ specs/001-user-authentication/
-
-- specs/20251102/002-password-reset
-+ specs/002-password-reset/
-```
-
-Add prominent note at top of CLI reference:
-
-> :::note Structure Format  
-> Examples show the default **flat structure** (`001-name/`, `002-name/`).  
-> For date-based grouping, see [Structure Configuration](/docs/reference/config#structure).  
-> :::
->
-> (Note: Use `:::note` without spaces between `:::` and `note`)
-
-### Priority 2: Clarify Getting Started Structure
-
-**File**: `docs-site/docs/guide/getting-started.md`
-
-Move structure explanation higher, before "Create Your First Spec" section.
-
-Add visual comparison showing:
-
-**Flat Structure (Default)**:
-- `specs/001-user-auth/`
-- `specs/002-api-gateway/`
-- `specs/archived/`
-
-**Date-based Grouping (Optional)**:
-- `specs/20251101/001-user-auth/`
-- `specs/20251101/002-api-gateway/`
-- `specs/archived/`
-
-Note: Configure in `.lean-spec/config.json` with `"pattern": "custom"` + `"groupExtractor": "{YYYYMMDD}"`.
-
-### Priority 3: Add Structure Configuration Doc
-
-**File**: `docs-site/docs/reference/config.md` (or `docs/guide/folder-structure.md`)
-
-Create comprehensive guide showing:
-- Default flat structure
-- Date-based grouping configuration
-- Custom grouping (by milestone, epic, etc.)
-- Migration between patterns
-
----
-
-## Validation Checklist
-
-Before publishing REDESIGN-REFINED.md to README.md:
-
-- [ ] **CLI examples use flat structure** - Update `docs/reference/cli.mdx`
-- [ ] **Getting Started shows structure clearly** - Enhance `docs/guide/getting-started.mdx`
-- [ ] **Add structure config guide** - Create or update config documentation
-- [ ] **Verify templates documentation** - Check template examples match implementation
-- [x] **Convert docs to .mdx** - All .md files in docs-site converted to .mdx ✅
-- [x] **Test docs-site build** - Run `cd docs-site && npm run build` ✅ Passes
-- [ ] **Spot-check all internal links** - Ensure no broken references
-
----
-
-## Files Requiring Updates
-
-### High Priority
-1. `docs-site/docs/reference/cli.mdx` - Update all structure examples
-2. `docs-site/docs/guide/getting-started.mdx` - Clarify structure upfront
-
-### Medium Priority
-3. `docs-site/docs/reference/config.mdx` - Document structure patterns (if exists)
-4. `docs-site/docs/guide/folder-structure.mdx` - Add if missing
-
-### Low Priority
-5. Any other files with spec path examples (search for `specs/YYYYMMDD/`)
-
-### Completed ✅
-- All documentation files converted from .md to .mdx
-- Build verification passed successfully
-
----
-
-## Alignment with REDESIGN-REFINED.md
-
-✅ **First Principles**: Docs perfectly aligned  
-✅ **Philosophy**: Mindset and approach consistent  
-✅ **AI Integration**: Methods and examples match  
-⚠️ **Structure Examples**: Need to reflect flat default  
-✅ **CLI Commands**: All documented commands exist  
-✅ **Features**: Templates, custom fields, progressive disclosure all documented
-
-**Overall**: 95% aligned. Minor updates to examples needed, but core content is accurate and comprehensive.
-
----
-
-## Next Steps
-
-1. **Update CLI reference** - Replace date-based examples with flat structure
-2. **Enhance Getting Started** - Make structure choice clearer upfront
-3. **Build docs-site** - Verify no build errors: `cd docs-site && npm run build`
-4. **Deploy README** - Replace root README.md with REDESIGN-REFINED.md
-5. **Update CHANGELOG** - Document README redesign and docs improvements
-
----
-
-**Conclusion**: Documentation is in excellent shape. Minor updates to examples will bring it to 100% alignment with current implementation. Safe to proceed with README deployment after addressing Priority 1 and 2 recommendations.