@leanspec/ui 0.2.5 → 0.2.6-dev.20251125010539

package/.next/standalone/packages/ui/dist/standalone/specs/archived/019-readme-improvement/README.md

@@ -1,252 +0,0 @@
----
-status: complete
-created: '2025-11-02'
-tags:
-  - docs
-  - ux
-priority: high
-completed: '2025-11-02'
----
-
-# Simplify README.md to be more lean
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-02 · **Tags**: docs, ux
-
-## The Market Problem
-
-### Competing SDD Tools & Their Struggles
-
-| Tool | Over-Documentation | Rigid Format | User Experience |
-|------|-------------------|--------------|-----------------|
-| **BMAD** | ❌ Yes | ❌ Yes | Heavyweight |
-| **GitHub SpecKit** | ❌ Yes | ❌ Yes | Opinionated |
-| **Kiro** | ❌ Yes | ❌ Yes | Complex |
-| **OpenSpec** | ✅ No | ❌ Yes | Limited flexibility |
-| **LeanSpec** | ✅ No | ✅ No | Lean & adaptive |
-
-**The Gap**: Developers don't want to choose between:
-- "Lightweight but inflexible" (OpenSpec)
-- "Flexible but heavyweight" (BMAD, SpecKit, Kiro)
-
-**LeanSpec's Opportunity**: Be the first to solve both - lightweight AND flexible.
-
-### Internal Problem
-
-**Current State**: README.md is **383 lines** - we're shooting ourselves in the foot!
-
-**The Irony**: A project built to solve "over-documentation" has an overwhelming README that violates its own principles:
-- ❌ Too much upfront information (contradicts our core message)
-- ❌ Unclear information hierarchy (hides the competitive advantage)
-- ❌ Mixed audiences without clear paths (confuses potential users)
-- ❌ Hard to scan quickly (doesn't demonstrate being "lean")
-
-**Impact**:
-- Potential users never discover we solve their pain
-- Core differentiation gets lost in details
-- Looks hypocritical ("preach lean, write verbose")
-- Competitors with simpler landing pages look better
-
-## Core Principle
-
-> **README is a marketing + onboarding tool for humans to make fast decisions: "Does this solve MY problem? How do I start?"**
->
-> Everything else belongs elsewhere.
-
-## The Hook We Need
-
-README must immediately communicate:
-
-1. **What we solve** (not what we are)
-   - Problem: Other SDD tools force you to choose between lightweight and flexible
-   - Solution: LeanSpec is lean AND adapts to your workflow
-
-2. **Why it matters**
-   - Developers hate documentation overhead and rigid formats
-   - AI-powered development needs clarity without verbosity
-   - Teams waste time on spec process instead of building
-
-3. **Proof** (social/competitive)
-   - Unlike BMAD/SpecKit/Kiro: Not over-documented
-   - Unlike OpenSpec: Actually flexible, not rigid
-   - Built for modern AI + human hybrid teams
-
-## Proposed Solutions
-
-### Option A: Progressive Disclosure (Recommended)
-
-**Why This Works**: It doesn't just organize information—it demonstrates our core value through the README itself.
-
-**Structure:**
-1. **Value Proposition Hook** (4-5 lines) - The problem we solve + why we're different
-2. **Quick Proof** (3-4 lines) - One concrete example showing flexibility
-3. **Install & Start** (5-7 lines) - `pnpm install` → `lean-spec init` → Done
-4. **Core Commands** (5-7 lines) - Most common operations
-5. **Learn More** (2-3 lines) - Links to deeper docs for different audiences
-
-**What Gets Moved:**
-- `docs/PHILOSOPHY.md` ← Principles and methodology (the "why LeanSpec exists")
-- `docs/COMMANDS.md` ← Complete command reference
-- `docs/FRONTMATTER.md` ← Frontmatter specification
-- `docs/TEMPLATES.md` ← Template system details + comparisons to other tools
-- `docs/INTEGRATION.md` ← Existing project integration patterns
-- `docs/COMPARISONS.md` ← Detailed comparison with BMAD/SpecKit/Kiro/OpenSpec
-
-**Target**: ~100 lines total
-
-**Key Positioning**:
-- README itself demonstrates "lean" principle (walks the talk)
-- Hook immediately answers "Is this for me?" (BMAD users asking about documentation = YES, this is for you)
-- Flexibility examples show we're not rigid like competitors
-- Links to detailed docs let researchers and technical leads find depth without overwhelming newcomers
-
-**Pros:**
-- Fast scanning for humans
-- Clear next steps based on use case
-- Easier to maintain individual docs
-- Better SEO (focused content)
-- **Demonstrates our core principle through the README itself** ← This is the real win
-
-**Cons:**
-- Requires creating new doc files
-- Need to ensure links are discoverable
-
----
-
-### Option B: Collapsible Sections
-
-Use `<details>` tags to hide advanced content:
-
-```markdown
-## Quick Start
-[Essential commands here]
-
-<details>
-<summary>Advanced Commands & Visualization Tools</summary>
-[Extended command list]
-</details>
-
-<details>
-<summary>Template System Deep Dive</summary>
-[Template details]
-</details>
-```
-
-**Pros:**
-- Single-file convenience
-- User controls detail level
-- Quick to implement
-
-**Cons:**
-- Still visually cluttered when collapsed
-- Harder to maintain large single file
-- Not ideal for deep linking
-
----
-
-### Option C: Split by Audience
-
-Create audience-specific entry points:
-
-- `README.md` ← Quick overview + install (50 lines)
-- `docs/USER-GUIDE.md` ← Complete user documentation
-- `docs/CONTRIBUTOR-GUIDE.md` ← Development setup
-- `docs/AI-INTEGRATION.md` ← AI agent setup
-
-Keep `AGENTS.md` and `CONTRIBUTING.md` at root.
-
-**Pros:**
-- Clear audience targeting
-- Each doc has focused purpose
-- Reduces cognitive load
-
-**Cons:**
-- More files to navigate
-- Risk of content duplication
-
-## Recommendation
-
-**Go with Option A (Progressive Disclosure)** because:
-
-1. **Demonstrates our core value** - The README itself proves we practice what we preach (lightweight, not bloated)
-2. **Captures the market opportunity** - Immediately shows BMAD/SpecKit/Kiro users "This is what you're looking for"
-3. **Positions against rigid competitors** - Shows flexibility through examples, not walls of text
-4. **Serves humans first** - Fast scanning, clear paths based on use case
-5. **Scales better** - Each doc has single responsibility, easier to maintain
-6. **Better competitive positioning** - Comparison docs let researchers understand nuance without overwhelming homepage
-
-**Key Insight**: Think of README as a **landing page + competitive differentiator**, not a **manual**.
-
-The README becomes proof-by-example that LeanSpec solves the exact problems other tools create.
-
-## Plan
-
-- [ ] **Strategy Phase**
-  - [ ] Finalize hook messaging (which version resonates?)
-  - [ ] Decide on direct vs. indirect competitive positioning
-  - [ ] Plan comparison doc structure
-
-- [ ] **Create New Docs**
-  - [ ] `docs/PHILOSOPHY.md` - Why LeanSpec exists
-  - [ ] `docs/COMMANDS.md` - Complete command reference
-  - [ ] `docs/FRONTMATTER.md` - Frontmatter specification
-  - [ ] `docs/TEMPLATES.md` - Template system + flexibility examples
-  - [ ] `docs/INTEGRATION.md` - Existing project integration
-  - [ ] `docs/COMPARISONS.md` - Detailed comparison with BMAD/SpecKit/Kiro/OpenSpec
-
-- [ ] **Rewrite README**
-  - [ ] Hook section (4-5 lines) with competitive positioning
-  - [ ] Problem solved (3-4 lines)
-  - [ ] Install & Quick Start (5-7 lines)
-  - [ ] Core Commands (5-7 lines)
-  - [ ] Learn More (2-3 lines with audience-specific links)
-
-- [ ] **Update Infrastructure**
-  - [ ] Update `docs/README.md` index with new structure
-  - [ ] Update all cross-references and links
-  - [ ] Add navigation hints in doc headers
-
-## Success Criteria
-
-- [ ] README.md is ≤ 150 lines (target ~100)
-- [ ] New user can understand "what is LeanSpec" in < 30 seconds
-- [ ] A developer frustrated with BMAD/SpecKit over-documentation recognizes this immediately
-- [ ] Clear path to "getting started" in < 5 seconds
-- [ ] Value proposition hook clearly differentiates from competitors
-- [ ] All detailed content preserved (just moved)
-- [ ] No broken links
-- [ ] Maintains SEO value (key content still in README)
-- [ ] Passes the "3am tired developer test" - still usable when exhausted
-- [ ] Comparison docs are discoverable from README for researchers/leads
-
-## Open Questions
-
-1. Should the Hook explicitly mention competing tools (BMAD, SpecKit, Kiro) or use indirect positioning?
-   - **Direct**: "Unlike BMAD and SpecKit, LeanSpec doesn't overwhelm with documentation"
-   - **Indirect**: "Tired of rigid spec tools that demand over-documentation?"
-   - Recommendation: Start indirect in README (less defensive), direct in `docs/COMPARISONS.md`
-
-2. Where should the comparison matrix go?
-   - In README as a proof point?
-   - In dedicated `docs/COMPARISONS.md`?
-   - Recommendation: Both - simple comparison in README, detailed analysis in dedicated doc
-
-3. How much space for template examples?
-   - The "flexibility" positioning requires showing the standard + enterprise templates work differently
-   - Recommendation: One visual example in README, full details in `docs/TEMPLATES.md`
-
-4. Should we include testimonial/quote positioning?
-   - "Unlike OpenSpec, we're actually flexible"
-   - "Developers spending 2+ hours on specs with BMAD might be in the wrong tool"
-   - Recommendation: No quotes in README (too salesy), but build this into comparison docs
-
-5. Should Quick Start show `npm` or `pnpm`? (both?)
-
-6. Keep "LeanSpec for AI Coding Agents" section in README or move to dedicated doc?
-   - Recommendation: Brief mention (1 line) → link to `docs/AI-INTEGRATION.md`
-
-## References
-
-Good examples of lean READMEs:
-- [Commander.js](https://github.com/tj/commander.js) - Clean, scannable
-- [Chalk](https://github.com/chalk/chalk) - Visual, quick examples
-- [Inquirer](https://github.com/SBoudrias/Inquirer.js) - Progressive disclosure done right

package/.next/standalone/packages/ui/dist/standalone/specs/archived/020-documentation-website/README.md

@@ -1,253 +0,0 @@
----
-status: complete
-created: 2025-11-02
-tags: [documentation, website, vitepress]
-priority: high
-superseded-by: specs/20251102/011-docusaurus-vercel-migration
----
-
-# Documentation Website
-
-> **Status**: ✅ Complete (superseded) · **Priority**: High · **Created**: 2025-11-02 · **Tags**: documentation, website, vitepress
-
-**⚠️ Note**: This spec has been completed but the implementation is being replaced. See [specs/20251102/011-docusaurus-vercel-migration](../011-docusaurus-vercel-migration/README.md) for the new direction using Docusaurus + Vercel instead of VitePress + GitHub Pages.
-
-## Overview
-
-Create a modern, user-friendly documentation website for LeanSpec using VitePress. The current README.md is comprehensive but difficult to navigate for new users. A dedicated documentation site will improve discoverability, provide better navigation, and create a professional presence for the project.
-
-**Why Now:**
-- Project is ready for external users (v0.1.0)
-- README.md has grown too long (~400 lines)
-- Need better organization for growing documentation
-- Preparing for npm publication
-- Better SEO and discoverability
-
-**What Success Looks Like:**
-- Clean, modern documentation site hosted on GitHub Pages
-- Clear navigation and structure
-- Mobile-friendly responsive design
-- Fast page loads
-- Easy to maintain and update
-- Searchable content
-- All existing documentation content migrated
-
-## Design
-
-### Technology Choice: VitePress
-
-**Why VitePress:**
-- Modern, fast, Vue-powered static site generator
-- Designed specifically for documentation
-- Minimal configuration
-- Built-in search
-- Mobile responsive out of the box
-- Easy deployment to GitHub Pages
-- Markdown-based (matches our existing content)
-- Active development and community support
-
-**Alternatives Considered:**
-- Docusaurus: Too heavy for our needs
-- GitBook: Requires external hosting
-- MkDocs: Python dependency
-- Jekyll: Older technology
-
-### Site Structure
-
-```
-docs/
-├── .vitepress/
-│   ├── config.ts          # VitePress configuration
-│   └── theme/             # Custom theme (if needed)
-├── index.md               # Homepage
-├── guide/
-│   ├── index.md          # Getting Started
-│   ├── installation.md   # Installation guide
-│   ├── quick-start.md    # Quick start tutorial
-│   ├── concepts.md       # Core concepts
-│   └── templates.md      # Template system
-├── reference/
-│   ├── cli.md            # CLI commands
-│   ├── frontmatter.md    # Frontmatter fields
-│   ├── config.md         # Configuration
-│   └── api.md            # API (if applicable)
-├── ai-integration/
-│   ├── index.md          # AI agent integration
-│   ├── setup.md          # Setup guide
-│   └── best-practices.md # Best practices
-└── examples/
-    ├── solo-dev.md       # Solo developer examples
-    ├── team.md           # Team examples
-    └── enterprise.md     # Enterprise examples
-```
-
-### Content Migration Plan
-
-1. **Homepage** (from README intro)
-   - Hero section with tagline
-   - Key features
-   - Quick links to major sections
-   - Visual appeal
-
-2. **Getting Started** (from README Quick Start)
-   - Installation instructions
-   - First spec creation
-   - Basic commands
-
-3. **Core Concepts** (from README Philosophy)
-   - LeanSpec principles
-   - When to use
-   - Spec structure
-
-4. **CLI Reference** (from README commands)
-   - All commands documented
-   - Examples for each
-   - Options and flags
-
-5. **AI Integration** (from README AI section)
-   - AGENTS.md integration
-   - System prompts
-   - Workflow setup
-
-6. **Templates** (from README templates)
-   - Template overview
-   - Customization
-   - Variables
-
-7. **API/Development** (from docs/)
-   - Testing guide
-   - Contributing
-   - Architecture
-
-### GitHub Pages Deployment
-
-- Build site to `docs/.vitepress/dist/`
-- Configure GitHub Actions for automatic deployment
-- Use `gh-pages` branch or GitHub Actions artifact
-- Custom domain support (future)
-
-## Implementation Plan
-
-### Phase 1: Setup (Day 1)
-- [x] Create spec
-- [x] Install VitePress as dev dependency
-- [x] Initialize VitePress in `docs/` directory
-- [x] Configure basic VitePress settings
-- [x] Set up local development workflow
-
-### Phase 2: Content Migration (Day 1-2)
-- [x] Create homepage with hero section
-- [x] Migrate getting started content
-- [x] Migrate CLI reference
-- [x] Migrate AI integration guide
-- [x] Migrate template documentation
-- [x] Add code examples
-
-### Phase 3: Polish & Enhancement (Day 2)
-- [x] Configure search
-- [x] Add navigation menu
-- [x] Add sidebar for each section
-- [x] Responsive design testing
-- [x] Add favicon and branding
-
-### Phase 4: Deployment (Day 2)
-- [x] Configure GitHub Pages
-- [x] Set up deployment workflow
-- [x] Test production build
-- [x] Update main README with docs link
-- [x] Verify all links work
-
-## Technical Details
-
-### VitePress Configuration
-
-Key configuration options:
-```typescript
-// docs/.vitepress/config.ts
-export default {
-  title: 'LeanSpec',
-  description: 'Lightweight spec methodology for AI-powered development',
-  themeConfig: {
-    nav: [...],
-    sidebar: {...},
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/codervisor/lean-spec' }
-    ],
-    search: {
-      provider: 'local'
-    }
-  }
-}
-```
-
-### Build Commands
-
-```json
-// package.json additions
-{
-  "scripts": {
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
-  }
-}
-```
-
-### GitHub Actions Workflow
-
-Create `.github/workflows/docs.yml`:
-```yaml
-name: Deploy Docs
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 18
-      - run: npm ci
-      - run: npm run docs:build
-      - uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/.vitepress/dist
-```
-
-## Non-Goals
-
-- Custom design system (use VitePress defaults)
-- Complex interactive features
-- Backend/API documentation (CLI tool only)
-- Versioned documentation (single version for now)
-- Multiple language support
-
-## Success Metrics
-
-- Documentation site live on GitHub Pages
-- All README content accessible via site
-- Search functionality working
-- Mobile responsive
-- Build time < 30 seconds
-- Page load time < 2 seconds
-
-## Open Questions
-
-- [ ] Should we keep detailed README.md or make it minimal with link to docs?
-  - **Decision**: Keep README comprehensive but add prominent docs link at top
-- [ ] Custom domain needed?
-  - **Decision**: Not initially, use github.io domain
-- [ ] Dark mode preference?
-  - **Decision**: VitePress default (auto-detect system preference)
-
-## References
-
-- [VitePress Documentation](https://vitepress.dev/)
-- [VitePress GitHub](https://github.com/vuejs/vitepress)
-- [GitHub Pages Documentation](https://docs.github.com/en/pages)