@leanspec/ui 0.2.6-dev.20251125015611 → 0.2.6

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

@@ -0,0 +1,252 @@
+---
+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

@@ -0,0 +1,253 @@
+---
+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)