@leanspec/ui 0.2.4 → 0.2.5-dev.20251118143726

package/dist/standalone/specs/089-sdd-practical-tutorials/README.md

@@ -1,126 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags: []
-priority: high
-created_at: '2025-11-17T02:10:56.366Z'
-updated_at: '2025-11-17T09:14:41.790Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T02:11:45.474Z'
-  - status: complete
-    at: '2025-11-17T02:11:45.698Z'
-  - status: planned
-    at: '2025-11-17T02:58:35.617Z'
-  - status: complete
-    at: '2025-11-17T09:14:41.790Z'
-completed_at: '2025-11-17T02:11:45.698Z'
-completed: '2025-11-17'
----
-
-# Step-by-Step SDD Tutorials for Real Practice
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-Users struggle to understand how to use SDD in real practice. Current docs explain concepts but lack concrete, step-by-step tutorials showing actual workflow.
-
-**Problem**: 
-- Docs are concept-heavy, practice-light
-- No clear "getting started" path for new users
-- Users don't know when to write specs, what to include, how to maintain them
-- Missing examples of real development workflow with AI agents
-
-**Goal**: Create practical, hands-on tutorials covering:
-
-1. **Your First Spec** (15 min)
-   - Install LeanSpec
-   - Create your first spec for a simple feature
-   - Update status as you work
-   - See the spec through completion
-
-2. **SDD Workflow: Feature Development** (30 min)
-   - Plan a feature with spec
-   - Work with AI agent using the spec
-   - Keep spec in sync during implementation
-   - Handle changes and iterations
-
-3. **Managing Multiple Specs** (20 min)
-   - Create related specs
-   - Use dependencies and relationships
-   - Track progress with `lean-spec board`
-   - Archive completed work
-
-4. **Working with Teams** (15 min)
-   - Assign specs to team members
-   - Use tags and priorities
-   - Review others' specs
-   - Coordinate work across specs
-
-**Target audience**: Developers new to SDD, familiar with AI coding tools
-
-## Design
-
-**Tutorial structure**: Each tutorial follows same format:
-
-1. **Goal**: What you'll learn (2-3 bullets)
-2. **Prerequisites**: What you need to know/have
-3. **Step-by-step instructions**: Clear, numbered steps with commands
-4. **Checkpoints**: Verify progress at key points
-5. **What you learned**: Summary of key takeaways
-6. **Next steps**: Link to next tutorial or related content
-
-**Tutorial progression**:
-- Start simple (single spec, solo dev)
-- Build complexity gradually
-- Each tutorial builds on previous knowledge
-- Can be followed independently if user has prerequisites
-
-**Content principles**:
-- Show, don't tell: Real commands, real examples
-- Include expected output for every command
-- Use realistic scenarios (not toy examples)
-- Show common mistakes and how to fix them
-- Keep tutorials under 30 minutes each
-
-**Format**:
-- Each tutorial = separate doc page
-- Include video walkthrough (future enhancement)
-- Provide downloadable example project (future enhancement)
-- Interactive playground (future enhancement)
-
-## Plan
-
-**Phase 1: Tutorial content**
-- [ ] Write "Your First Spec" tutorial
-- [ ] Write "SDD Workflow: Feature Development" tutorial
-- [ ] Write "Managing Multiple Specs" tutorial
-- [ ] Write "Working with Teams" tutorial
-- [ ] Review tutorials with test users for clarity
-
-**Phase 2: Integration**
-- [ ] Add "Tutorials" section to docs-site
-- [ ] Create tutorial navigation/progression
-- [ ] Add "Quick Start" link to homepage pointing to first tutorial
-- [ ] Update README.md to mention tutorials
-
-**Phase 3: Enhancements (future)**
-- [ ] Record video walkthroughs
-- [ ] Create downloadable example projects
-- [ ] Add interactive playground/sandbox
-
-## Test
-
-- [ ] New user can complete "Your First Spec" tutorial in under 20 minutes
-- [ ] All commands in tutorials execute successfully
-- [ ] Test users report understanding SDD workflow after tutorials
-- [ ] Users can apply SDD to their own projects after completing tutorials
-- [ ] No confusion or stuck points in tutorial flow (test with 3+ new users)
-
-## Notes
-
-<!-- Optional: Research findings, alternatives considered, open questions -->

package/dist/standalone/specs/090-leanspec-sdd-case-studies/README.md

@@ -1,131 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags: []
-priority: high
-created_at: '2025-11-17T02:11:56.264Z'
-updated_at: '2025-11-17T09:14:54.020Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T02:12:47.218Z'
-  - status: complete
-    at: '2025-11-17T02:12:47.445Z'
-  - status: planned
-    at: '2025-11-17T02:58:35.830Z'
-  - status: complete
-    at: '2025-11-17T09:14:54.020Z'
-completed_at: '2025-11-17T02:12:47.445Z'
-completed: '2025-11-17'
----
-
-# LeanSpec Dogfooding: Real SDD Case Studies
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-Users need real-world examples of SDD in action. LeanSpec project itself uses SDD extensively - showcase this to demonstrate practical value and best practices.
-
-**Problem**:
-- Users see LeanSpec has 90+ specs but don't see how they were actually used
-- No examples of spec evolution during development
-- Missing "show, don't tell" evidence that SDD works
-
-**Goal**: Create case studies documenting how specific LeanSpec features were built using SDD:
-
-1. **Simple Feature Case Study** (spec 071 - Simplified Token Validation)
-   - Small, focused spec
-   - Show spec → implementation → completion flow
-   - Demonstrate single-concern spec
-
-2. **Complex Feature Case Study** (spec 082 - Web Realtime Sync Architecture)
-   - Large, multi-phase spec
-   - Show how spec evolved during implementation
-   - Demonstrate sub-spec usage and complexity management
-
-3. **Refactoring Case Study** (spec 067 - Monorepo Core Extraction)
-   - Breaking change requiring careful planning
-   - Show dependency analysis and coordination
-   - Demonstrate spec-driven refactoring
-
-4. **Cross-Team Feature** (spec 043 - Official Launch 02)
-   - Multiple related specs
-   - Show spec relationships and dependencies
-   - Demonstrate team coordination
-
-**Each case study includes**:
-- Original spec content
-- Implementation approach
-- Challenges encountered
-- How spec helped (or needed updates)
-- Lessons learned
-
-## Design
-
-**Case study structure**:
-
-1. **Context**: What problem were we solving?
-2. **The Spec**: Link to actual spec, show key sections
-3. **Implementation**: How we built it
-4. **Evolution**: What changed during development
-5. **Outcome**: Final result, metrics
-6. **Lessons**: What worked, what we'd do differently
-7. **AI Agent Collaboration**: How AI agents used the spec
-
-**Selection criteria for case studies**:
-- Completed specs (status: complete or archived)
-- Representative of common use cases
-- Various complexity levels (simple → complex)
-- Different spec types (feature, refactor, architecture)
-- Show both successes and challenges
-
-**Presentation**:
-- Create "Case Studies" section in docs-site
-- Each case study = separate page
-- Include screenshots/diagrams where helpful
-- Link to actual spec in GitHub
-- Show before/after code where relevant
-
-**Anti-patterns to avoid**:
-- Cherry-picking only perfect examples
-- Hiding challenges or mistakes
-- Making it look effortless (be honest about iteration)
-
-## Plan
-
-**Phase 1: Case study selection**
-- [ ] Review completed specs, identify good candidates
-- [ ] Select 4 specs covering different scenarios
-- [ ] Gather context: git history, PR discussions, implementation details
-
-**Phase 2: Case study writing**
-- [ ] Write Simple Feature case study (spec 071)
-- [ ] Write Complex Feature case study (spec 082)
-- [ ] Write Refactoring case study (spec 067)
-- [ ] Write Cross-Team Feature case study (spec 043)
-
-**Phase 3: Integration**
-- [ ] Create "Case Studies" section in docs-site
-- [ ] Add case study navigation
-- [ ] Link from homepage/getting started
-- [ ] Add "How LeanSpec uses SDD" overview page
-
-**Phase 4: Maintenance**
-- [ ] Add more case studies over time (target: 1 per quarter)
-- [ ] Update case studies as specs evolve
-- [ ] Collect user feedback on case studies
-
-## Test
-
-- [ ] Users report understanding SDD better after reading case studies
-- [ ] Case studies demonstrate concrete value of SDD (not just theory)
-- [ ] Both successes and challenges are clearly documented
-- [ ] Users can relate case studies to their own projects
-- [ ] Case studies cover range of scenarios (simple to complex)
-
-## Notes
-
-<!-- Optional: Research findings, alternatives considered, open questions -->

package/dist/standalone/specs/091-chinese-localization-strategy/README.md

@@ -1,254 +0,0 @@
----
-status: planned
-created: '2025-11-17'
-tags: []
-priority: high
-created_at: '2025-11-17T02:12:58.531Z'
-updated_at: '2025-11-17T12:52:05.092Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T02:14:06.440Z'
-  - status: complete
-    at: '2025-11-17T02:14:06.656Z'
-  - status: planned
-    at: '2025-11-17T02:58:36.055Z'
-  - status: complete
-    at: '2025-11-17T09:15:05.884Z'
-  - status: planned
-    at: '2025-11-17T12:52:05.092Z'
-completed_at: '2025-11-17T02:14:06.656Z'
-completed: '2025-11-17'
----
-
-# Comprehensive Chinese Localization for LeanSpec
-
-> **Status**: 📋 Planned · **Priority**: High · **Created**: 2025-11-17
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-**Current Progress**: Docs-site i18n complete (spec 064). Web app and CLI i18n not yet started.
-
-## Overview
-
-Most early LeanSpec users come from China. Without Chinese localization, we're creating a significant barrier to adoption and understanding.
-
-**Problem**:
-- Docs site is English-only
-- Web app UI is English-only
-- CLI templates and help text are English-only
-- Chinese developers struggle to understand SDD methodology
-- Lost opportunity to build strong Chinese community
-
-**Key Insight**: This is **tool localization**, not content translation.
-- Developers write specs in their native language (Chinese devs write Chinese specs, English devs write English specs)
-- We don't duplicate/translate user-created specs
-- We translate the framework/tooling that helps them write specs
-
-**Scope of localization**:
-
-1. **Docs Site** (docusaurus) - **Priority 1**
-   - Methodology documentation
-   - Tutorial content
-   - Guides and best practices
-   - Navigation and UI elements
-
-2. **Web App** (@leanspec/web) - **Priority 2**
-   - UI strings and labels
-   - Error messages
-   - Help text and tooltips
-   - Navigation elements
-
-3. **CLI Templates** (packages/cli/templates/) - **Priority 3**
-   - Template boilerplate text
-   - Section headers and prompts
-   - AGENTS.md instructions
-
-4. **Example Specs** (for teaching)
-   - Tutorial examples in docs
-   - Demo specs showing methodology
-   - NOT translating real project specs
-
-**Out of Scope** (for now):
-- CLI help text and error messages (English is acceptable for CLI users)
-- On-demand spec translation (future feature for web app)
-
-**Translation requirements**:
-- Professional quality (AI-assisted + human review)
-- Technical terminology consistency (SDD glossary)
-- Cultural adaptation where needed
-- Maintain separate language versions (not side-by-side bilingual)
-
-## Design
-
-**Technical approach**:
-
-### 1. Docs Site (Docusaurus i18n)
-Docusaurus has built-in i18n support:
-- Use `docs-site/i18n/zh-CN/` structure
-- Run `npm run write-translations -- --locale zh-CN`
-- Translate markdown files in `i18n/zh-CN/docusaurus-plugin-content-docs/`
-- Configure `docusaurus.config.ts` with Chinese locale
-
-**Files to translate**:
-- Core Concepts pages
-- Tutorials
-- Guides
-- API reference
-- Navigation labels
-- Footer content
-
-### 2. Web App i18n
-Implement i18n library for React:
-- Use `react-i18next` or similar
-- Extract all UI strings to translation files
-- Language switcher in UI
-- Persist language preference
-- Load translations dynamically
-
-**Translation file structure**:
-```
-packages/web/src/locales/
-  en/
-    common.json
-    errors.json
-    help.json
-  zh-CN/
-    common.json
-    errors.json
-    help.json
-```
-
-### 3. Translation Management
-**Options**:
-1. **Manual**: Maintain JSON/markdown files in repo (simple, full control)
-2. **Crowdin/Lokalise**: Translation management platform (scalable)
-3. **AI-assisted**: Use AI for first pass, human review (fast, needs validation)
-
-**Recommendation**: Start with option 3 (AI + human review), move to option 2 if community grows
-
-### 4. CLI Templates Localization
-Add Chinese templates:
-- Create `zh-CN` template variants
-- Translate boilerplate content
-- Localize AGENTS.md instructions
-- Language detection for `lean-spec create` (based on system locale)
-
-### 5. Terminology Glossary
-Create SDD terminology glossary:
-- Spec → 规格说明 (guīgé shuōmíng)
-- Context → 上下文 (shàngxià wén)
-- Token → 令牌 (lìngpái) or 标记 (biāojì)
-- Agent → 代理 (dàilǐ) or AI 助手
-- Status → 状态 (zhuàngtài)
-- Maintain consistency across all translations
-
-## Plan
-
-**Phase 1: Foundation**
-- [x] Create SDD terminology glossary (Chinese) - Done in spec 064
-- [x] Set up Docusaurus i18n configuration - Done in spec 064
-- [ ] Set up web app i18n infrastructure (react-i18next)
-- [ ] Create translation file structures (web app)
-
-**Phase 2: Docs Site Translation** (Priority 1) - ✅ COMPLETE (spec 064)
-- [x] Translate Core Concepts pages
-- [x] Translate "Your First Spec" tutorial (spec 089)
-- [x] Translate Guides and best practices
-- [x] Translate homepage and navigation
-- [x] Test zh-CN docs site build
-
-**Phase 3: Web App Translation** (Priority 2) - 🔴 NOT STARTED
-- [ ] Extract all UI strings to translation files
-- [ ] Translate to Chinese
-- [ ] Add language switcher to UI
-- [ ] Test web app with Chinese locale
-
-**Phase 4: CLI Templates Translation** (Priority 3) - 🔴 NOT STARTED
-- [ ] Create Chinese template variants (zh-CN)
-- [ ] Translate template boilerplate text
-- [ ] Translate AGENTS.md instructions
-- [ ] Test Chinese template creation
-
-**Phase 5: Quality & Polish**
-- [x] Native speaker review of translations (docs-site done)
-- [ ] Cultural adaptation review (web app)
-- [x] Fix inconsistencies (docs-site)
-- [ ] Create Chinese example specs for docs
-
-**Phase 6: Ongoing Maintenance**
-- [x] Document translation workflow (docs-site done)
-- [ ] Set up process for new content (web app)
-- [ ] Build Chinese community for feedback
-
-**Future: Cross-Language Spec Translation** (separate spec, after this)
-- On-demand spec translation feature in web app
-- Free external API integration
-- Markdown parsing to preserve structure
-- See "Cross-Language Spec Reading" section above
-
-## Test
-
-**Docs-site (completed in spec 064):**
-- [x] Chinese users can read all core docs in their language
-- [x] Terminology is consistent across all translations (docs-site)
-- [x] Language switcher works smoothly in docs
-
-**Web app (not yet implemented):**
-- [ ] Web app fully functional in Chinese
-- [ ] Language switcher works in web app
-- [ ] Native speakers confirm quality and clarity (web app)
-- [ ] Chinese users successfully complete tutorials in Chinese (web app)
-
-## Cross-Language Spec Reading (Future)
-
-**Problem**: Chinese dev needs to read English specs (or vice versa)
-
-**Solution** (future web app feature):
-- On-demand translation via free external API (Google Translate, LibreTranslate, etc.)
-- Implemented in web app with "Translate" button
-- Parse markdown to preserve structure:
-  - Keep frontmatter untranslated
-  - Keep code blocks untranslated
-  - Translate only prose sections
-  - Preserve links and formatting
-- Ephemeral translation (not saved, regenerated on demand)
-- No caching initially (keep simple)
-
-**Why future implementation**:
-- Not blocking initial Chinese adoption
-- Users can use external tools meanwhile
-- Need to complete functional localization first
-- Free API limits may need management
-
-**Implementation priority**: After core localization complete (separate spec)
-
-## Notes
-
-**Existing i18n infrastructure**:
-- Docusaurus already has some zh-CN setup in `docs-site/i18n/` (needs completion)
-- Web app has no i18n infrastructure yet
-- CLI templates are English-only
-
-**Translation challenges**:
-- SDD is new methodology - no established Chinese terminology
-- Need to balance literal translation vs cultural adaptation
-- Technical terms (tokens, context, agents) have multiple Chinese translations
-- CLI template localization needs system locale detection
-
-**User-created specs**:
-- Developers write specs in their native language
-- Chinese devs write Chinese specs, English devs write English specs
-- We do NOT translate user specs (that's their content)
-- We only translate the framework/tooling
-
-**Future considerations**:
-- Other languages (Japanese, Korean, Spanish)
-- Community translation contributions
-- On-demand spec translation feature (web app)
-- Automated translation quality checks
-
-**Resources needed**:
-- Native Chinese speaker for review (critical)
-- AI-assisted translation + human validation
-- Ongoing maintenance commitment

package/dist/standalone/specs/092-docs-site-submodule-migration/README.md

@@ -1,152 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags:
-  - infrastructure
-  - docs
-  - monorepo
-priority: high
-created_at: '2025-11-17T04:54:37.212Z'
-updated_at: '2025-11-17T07:51:43.434Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T05:31:55.704Z'
-  - status: complete
-    at: '2025-11-17T07:51:43.434Z'
-completed_at: '2025-11-17T07:51:43.434Z'
-completed: '2025-11-17'
----
-
-# Migrate docs-site to separate repository as submodule
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17 · **Tags**: infrastructure, docs, monorepo
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-The `docs-site/` directory is currently nested in the lean-spec monorepo. This causes unnecessary Vercel deployments whenever any part of the monorepo changes, even when documentation hasn't been modified. 
-
-Migrating docs-site to a separate repository with git submodule integration will:
-- Decouple docs deployment from CLI/core development
-- Reduce unnecessary CI/CD runs and Vercel builds
-- Enable independent versioning and release cycles for documentation
-- Maintain single source of truth while allowing separate workflows
-
-## Design
-
-### Repository Structure
-
-**New repository**: `codervisor/lean-spec-docs`
-- Standalone Docusaurus project
-- Independent deployment to Vercel
-- Own package.json, dependencies, CI/CD
-
-**Main repository**: `codervisor/lean-spec`
-- Add `docs-site/` as git submodule pointing to `lean-spec-docs`
-- Update build scripts to handle submodule
-- Update CONTRIBUTING.md with submodule workflow
-
-### Migration Strategy
-
-1. **Create new repository**
-   - Create `codervisor/lean-spec-docs` on GitHub
-   - Initialize with existing `docs-site/` content
-   - Set up Vercel deployment for new repo
-   - Configure build settings (same as current)
-
-2. **Remove from monorepo**
-   - Remove `docs-site/` directory from lean-spec
-   - Update root `package.json` workspaces config
-   - Update `turbo.json` to remove docs-site tasks
-   - Remove docs-site from `pnpm-workspace.yaml`
-
-3. **Add as submodule**
-   - `git submodule add https://github.com/codervisor/lean-spec-docs.git docs-site`
-   - Configure submodule to track `main` branch
-   - Update `.gitmodules` with branch tracking
-
-4. **Update workflows**
-   - GitHub Actions: Skip docs builds unless docs changed
-   - Update CONTRIBUTING.md with submodule commands
-   - Add documentation for working with submodules
-
-### Vercel Configuration
-
-**Current setup**: Single Vercel project for entire monorepo
-**New setup**: Separate Vercel projects
-- `lean-spec` monorepo: Deploy only if CLI/core changes
-- `lean-spec-docs`: Deploy only on docs changes
-
-### Developer Workflow
-
-**Clone with submodule**:
-```bash
-git clone --recurse-submodules https://github.com/codervisor/lean-spec.git
-```
-
-**Update docs**:
-```bash
-cd docs-site
-git checkout main
-git pull
-cd ..
-git add docs-site
-git commit -m "chore: update docs submodule"
-```
-
-**Work on docs**:
-```bash
-cd docs-site
-# Make changes, commit to lean-spec-docs
-git push
-cd ..
-git add docs-site
-git commit -m "chore: update docs submodule pointer"
-```
-
-## Plan
-
-- [x] Create `codervisor/lean-spec-docs` repository on GitHub
-- [x] Copy `docs-site/` content to new repository
-- [ ] Set up Vercel deployment for new docs repo
-- [ ] Test docs build and deployment independently
-- [x] Remove `docs-site/` from lean-spec monorepo
-- [x] Update workspace configs (package.json, pnpm-workspace.yaml, turbo.json)
-- [x] Add docs-site as git submodule
-- [x] Update CONTRIBUTING.md with submodule workflow
-- [x] Update GitHub Actions to skip docs builds
-- [ ] Test full workflow: clone, build, deploy
-- [x] Document submodule best practices in README
-
-## Test
-
-- [ ] New docs repo builds successfully on Vercel
-- [ ] Docs deploy independently when pushed to lean-spec-docs
-- [x] Main repo builds without docs-site directory
-- [x] Submodule clone works: `git clone --recurse-submodules`
-- [ ] Submodule update works: `git submodule update --remote`
-- [ ] CI/CD skips docs builds when only CLI/core changes
-- [ ] Developers can work on docs independently
-
-## Notes
-
-### Alternatives Considered
-
-**Keep in monorepo**: Simpler but causes unnecessary deployments and tight coupling
-
-**Separate repo without submodule**: Loses visibility in main repo, harder to track docs version
-
-**Monorepo with conditional Vercel deploys**: Possible but requires complex CI configuration, still coupled in git history
-
-### Open Questions
-
-- Should we keep docs versioned with CLI releases or independently?
-- Do we want to enforce docs updates as part of CLI PRs?
-- Should submodule track `main` or specific release tags?
-
-### References
-
-- Current Vercel config: `vercel.json`, `docs-site/vercel.json`
-- Git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules