@leanspec/ui 0.2.7-dev.20251126090633 → 0.2.7

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

@@ -0,0 +1,126 @@
+---
+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/.next/standalone/packages/ui/dist/standalone/specs/090-leanspec-sdd-case-studies/README.md

@@ -0,0 +1,131 @@
+---
+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/.next/standalone/packages/ui/dist/standalone/specs/091-chinese-localization-strategy/README.md

@@ -0,0 +1,254 @@
+---
+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/.next/standalone/packages/ui/dist/standalone/specs/092-docs-site-submodule-migration/README.md

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