@leanspec/ui 0.2.6-dev.20251125010539 → 0.2.6

package/.next/standalone/packages/ui/dist/standalone/specs/063-migration-from-existing-tools/IMPLEMENTATION.md

@@ -0,0 +1,189 @@
+# Implementation: Migration Command
+
+Implementation plan and testing strategy for `lean-spec migrate`.
+
+## Migration Workflow
+
+```
+┌─────────────────────────────────────────┐
+│ 1. Scan Input Path                      │
+│    - Find all documents (format-agnostic)│
+│    - Count files to migrate             │
+└─────────────────┬───────────────────────┘
+                  │
+        ┌─────────┴─────────┐
+        │ --with specified? │
+        └─────────┬─────────┘
+                  │
+        ┌─────────┴─────────┐
+        │                   │
+        NO                 YES
+        │                   │
+┌───────▼────────┐  ┌───────▼──────────────┐
+│ 2a. Manual     │  │ 2b. Verify AI CLI    │
+│     Mode       │  │                      │
+│                │  │ - Check installed    │
+│ Generate       │  │ - Verify version     │
+│ generic prompt │  │ - Test connectivity  │
+│ Output to user │  │                      │
+└────────────────┘  └──────────┬───────────┘
+                               │
+                               │ ✓ Verified
+                               │
+                    ┌──────────▼─────────────┐
+                    │ 3. AI Auto-Execute     │
+                    │                        │
+                    │ - AI analyzes format   │
+                    │ - Batch documents      │
+                    │ - Execute migration    │
+                    │ - Create specs         │
+                    │ - Set metadata         │
+                    └──────────┬─────────────┘
+                               │
+                    ┌──────────▼─────────┐
+                    │ 4. Validate        │
+                    │    - Run validate  │
+                    │    - Check links   │
+                    │    - Report status │
+                    └────────────────────┘
+```
+
+## Implementation Plan
+
+### Phase 1: Core Infrastructure (Week 1)
+
+**Goal**: Basic command structure and manual mode
+
+- [ ] Create `migrate` command scaffold in CLI
+- [ ] Implement document scanning (format-agnostic file finder)
+- [ ] Build generic migration prompt generator
+- [ ] Add instruction output for manual mode
+- [ ] Basic error handling (path not found, no files)
+
+**Deliverable**: `lean-spec migrate <path>` outputs migration prompt
+
+### Phase 2: Manual Migration (Week 1-2)
+
+**Goal**: Refine prompt for real-world use
+
+- [ ] Refine generic migration instructions based on feedback
+- [ ] Add examples for common formats (ADR, RFC, Linear)
+- [ ] Test prompt with ChatGPT, Claude, Copilot
+- [ ] Validate with real-world document sets (5+ projects)
+- [ ] Document manual migration workflow
+
+**Deliverable**: Users can successfully migrate using manual mode
+
+### Phase 3: AI CLI Integration (Week 2-3)
+
+**Goal**: Automated AI-assisted migration
+
+- [ ] Design AI CLI tool registry (copilot, claude, gemini)
+- [ ] Implement CLI verification (`which`, version check)
+- [ ] Add error handling for missing/outdated tools
+- [ ] Implement AI CLI execution for each provider
+- [ ] Add `--dry-run` mode
+- [ ] Add post-migration validation
+
+**Deliverable**: `lean-spec migrate <path> --with copilot` auto-migrates
+
+### Phase 4: Testing & Documentation (Week 3)
+
+**Goal**: Production-ready quality
+
+- [ ] Integration tests with sample repos
+- [ ] Test AI CLI detection and execution
+- [ ] Add migration guide to docs site
+- [ ] Create migration examples/tutorials
+- [ ] Performance testing (100+ documents)
+
+**Deliverable**: Documented, tested, production-ready feature
+
+### Phase 5: Polish for 0.2 (Week 4)
+
+**Goal**: Great user experience
+
+- [ ] CLI UX improvements (colors, formatting)
+- [ ] Progress indicators for batch processing
+- [ ] Error message clarity and actionability
+- [ ] Migration report summary with stats
+- [ ] Beta user testing and feedback
+
+**Deliverable**: Ship-ready feature for 0.2 launch
+
+## Testing Strategy
+
+### Unit Tests
+
+- [ ] Document scanning finds all files correctly
+- [ ] Prompt generation includes all required instructions
+- [ ] AI CLI detection works for all providers
+- [ ] Version parsing and comparison logic
+- [ ] Error messages are clear and actionable
+- [ ] Command-line argument parsing
+
+### Integration Tests
+
+**Basic Migration:**
+- [ ] Migrate sample ADR repository (10+ docs)
+- [ ] Migrate sample RFC repository
+- [ ] Mixed format migration (various doc types)
+- [ ] Empty directory handling
+- [ ] Single file migration
+
+**AI-Assisted Mode:**
+- [ ] AI CLI detection (installed/missing/outdated)
+- [ ] AI CLI execution completes successfully
+- [ ] Dry-run produces no actual changes
+- [ ] Validation runs after migration
+- [ ] Error handling when AI CLI fails
+
+**Edge Cases:**
+- [ ] Very large repos (100+ documents)
+- [ ] Nested directory structures
+- [ ] Special characters in filenames
+- [ ] Duplicate document names
+- [ ] Partial migration (some docs fail)
+
+### Real-World Validation
+
+- [ ] Migrate OpenSpec repository (if publicly available examples exist)
+- [ ] Migrate GitHub spec-kit repository examples
+- [ ] Migrate actual ADR repo from open source project
+- [ ] Migrate actual RFC repo from open source project
+- [ ] Test with exported documents from Linear/Jira (markdown/JSON)
+- [ ] User testing with 3+ beta users
+- [ ] AI-assisted migration accuracy >90%
+- [ ] Test with all 3 AI providers (Copilot, Claude, Gemini)
+
+### Performance Tests
+
+- [ ] Migrate 10 documents: <1 minute (manual mode)
+- [ ] Migrate 100 documents: <5 minutes (manual mode)
+- [ ] Migrate 100 documents: <15 minutes (AI mode)
+- [ ] Memory usage stable with large repos
+- [ ] No memory leaks during batch processing
+
+## Future Enhancements
+
+**Post-0.2 Improvements:**
+
+- **Bidirectional sync**: Export LeanSpec back to source format
+- **Incremental migration**: Auto-migrate new docs as they appear
+- **Custom mappings**: User-defined source → LeanSpec rules
+- **Web UI**: Visual migration tool with preview
+- **Progress tracking**: Resume interrupted migrations
+- **Conflict resolution**: Interactive UI for duplicate handling
+- **Attachment support**: Migrate images/diagrams from source
+- **Relationship mapping**: Auto-detect and link related specs
+
+## Open Questions
+
+**For team discussion:**
+
+1. Should we support exporting back to source format?
+2. How to handle complex relationships (ADR supersedes)?
+3. Should AI mode require explicit consent/confirmation?
+4. Support for attachments/images in source docs?
+5. Should we cache AI responses for retry scenarios?
+6. How to handle rate limits on AI CLI tools?

package/.next/standalone/packages/ui/dist/standalone/specs/063-migration-from-existing-tools/README.md

@@ -0,0 +1,119 @@
+---
+status: complete
+created: '2025-11-10'
+tags:
+  - cli
+  - migration
+  - ai-assisted
+  - v0.2
+priority: high
+created_at: '2025-11-10T05:35:31.293Z'
+updated_at: '2025-11-10T06:48:06.343Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-10T06:39:58.417Z'
+  - status: complete
+    at: '2025-11-10T06:48:06.343Z'
+completed_at: '2025-11-10T06:48:06.343Z'
+completed: '2025-11-10'
+---
+
+# Migration from Existing SDD Tools
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-10 · **Tags**: cli, migration, ai-assisted, v0.2
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Add `lean-spec migrate` command to help users migrate from mainstream SDD tools to LeanSpec.
+
+**Problem**: Teams using existing SDD tools have different folder/file organization. Manually reorganizing specs is tedious and error-prone.
+
+**Solution**: Two migration modes:
+1. **Manual mode** (default): Outputs AI prompt for any AI tool
+2. **AI-assisted mode**: Automated migration via Copilot/Claude/Gemini CLI
+
+**Key Insight:** The real migration challenge is **metadata/frontmatter**, not folder structure or content format:
+- **Folder structure**: spec-kit already uses `specs/###-name/` (compatible!)
+- **Content format**: LeanSpec is flexible—keep your existing content
+- **Metadata**: Need to generate system-managed frontmatter (status, priority, tags, timestamps)
+- **Solution**: Use `lean-spec backfill` to extract metadata from git history + existing docs
+
+**Primary Migration Sources:**
+1. **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** - `openspec/specs/` + `openspec/changes/` structure (needs folder merge)
+2. **[GitHub spec-kit](https://github.com/github/spec-kit)** - `.specify/specs/` (already compatible! just needs frontmatter)
+3. **Document collections** - ADR folders, RFC directories, scattered docs (need folder reorganization)
+4. **System prompts** - AGENTS.md, Cursorrules, etc. (guide AI behavior during/after migration)
+
+**External Systems:** Support exported documents only (no API integration). Users export to markdown/JSON, then migrate those files.
+
+## Design
+
+See [DESIGN.md](./DESIGN.md) for complete technical design including:
+- Command interface and options
+- Migration modes (manual vs AI-assisted)
+- AI provider integration
+- Error handling
+
+See [EXAMPLES.md](./EXAMPLES.md) for detailed folder reorganization examples:
+- OpenSpec → LeanSpec (merging specs + changes directories)
+- spec-kit → LeanSpec (consolidating multi-file features)
+- ADR → LeanSpec (flat files to folder hierarchy)
+
+## Implementation
+
+See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for implementation plan including:
+- Migration workflow diagram
+- 5-phase development plan
+- Comprehensive testing strategy
+
+## Notes
+
+### Design Decisions
+
+**Why focus on metadata/frontmatter, not content or folders?**
+- LeanSpec doesn't enforce content structure—users write however they want
+- spec-kit already uses compatible folder structure (`specs/###-name/`)
+- The real challenge: generating system-managed frontmatter (status, priority, tags, timestamps)
+- Use `lean-spec backfill` to extract metadata from git history and existing docs
+- OpenSpec and ADR need folder reorganization, but that's secondary
+- Follows: Intent Over Implementation (automate metadata extraction, preserve content)
+
+**Why focus on file-based specs (OpenSpec, spec-kit, ADR)?**
+- Mainstream SDD tools used by engineering teams
+- Git-based, version-controlled, no API complexity
+- OpenSpec and spec-kit are AI-native and well-structured
+- Avoids authentication and external system dependencies
+
+**Why exported documents only for external systems?**
+- API integration requires auth, keys, rate limits, ongoing maintenance
+- Security concerns with storing/managing credentials
+- Export-then-migrate keeps tool simple and secure
+- Users already have export workflows (Linear→markdown, etc.)
+
+**Why instruction-based by default?**
+- No API keys required
+- Works with any AI tool (ChatGPT, Claude, Copilot, etc.)
+- User maintains control
+- Lower complexity
+
+**Why AI-assisted auto-executes?**
+- When user specifies `--with`, they want automation
+- Verification ensures tools are ready
+- Fails fast with clear errors
+
+**Why migrate system prompts (AGENTS.md)?**
+- OpenSpec and spec-kit have AGENTS.md files guiding AI behavior
+- LeanSpec also uses AGENTS.md for AI workflow instructions
+- Migration should preserve AI guidance, not just specs
+- Consider migrating: AGENTS.md, .cursorrules, .github/copilot-instructions.md
+- Ensures continuity of AI-assisted development workflows
+
+### Success Criteria
+
+- Migrate ADR/RFC repos in <30 minutes
+- AI-assisted migration accuracy >90%
+- Zero data loss
+- 80% of beta users migrate successfully without support

package/.next/standalone/packages/ui/dist/standalone/specs/064-docs-site-zh-translation/README.md

@@ -0,0 +1,170 @@
+---
+status: complete
+created: '2025-11-10'
+tags:
+  - docs
+  - i18n
+  - translation
+  - chinese
+priority: medium
+created_at: '2025-11-10T14:32:32.477Z'
+updated_at: '2025-11-10T15:12:43.784Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-10T15:12:07.668Z'
+  - status: complete
+    at: '2025-11-10T15:12:43.784Z'
+completed_at: '2025-11-10T15:12:43.784Z'
+completed: '2025-11-10'
+---
+
+# Docs Site Chinese (ZH) Translation
+
+> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-10 · **Tags**: docs, i18n, translation, chinese
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Add Chinese (Simplified) translation support to the LeanSpec documentation site to expand reach to Chinese-speaking developers. Docusaurus has built-in i18n support that makes this straightforward.
+
+**Why**: China has a large developer community, and Chinese documentation significantly lowers adoption barriers for non-English speakers.
+
+**Scope**: 
+- Translation infrastructure setup (i18n config)
+- Initial translation of core documentation pages
+- Translation workflow and guidelines for maintainability
+
+**Out of scope**: Traditional Chinese (can be added later), automatic translation (manual/human translation only for quality).
+
+## Design
+
+### Docusaurus i18n Architecture
+
+Docusaurus provides built-in i18n support with locale-based file organization:
+
+```
+docs-site/
+  i18n/
+    zh-Hans/           # Chinese Simplified
+      docusaurus-plugin-content-docs/
+        current/       # Translated docs/
+          intro.md
+          getting-started.md
+          ...
+      docusaurus-plugin-content-blog/
+        ...            # Translated blog posts
+      code.json        # UI labels, nav items
+```
+
+**Key decisions**:
+1. **Use `zh-Hans` (Simplified Chinese)** - Most widely used in mainland China
+2. **Manual translation** - Ensures quality and proper context
+3. **Progressive translation** - Start with high-value pages (getting started, core concepts)
+4. **Maintain English as source of truth** - Chinese follows English updates
+
+### Translation Priority
+
+**Phase 1 (Initial Launch)** - Critical path pages:
+- Homepage
+- Getting Started guide
+- Core Concepts section
+- Quick Start tutorial
+- Navigation/UI elements
+
+**Phase 2** - Feature documentation:
+- CLI Commands reference
+- Frontmatter reference
+- Workflow guides
+- Templates guide
+
+**Phase 3** - Advanced content:
+- Blog posts
+- Advanced guides
+- Contributing guide
+- API documentation
+
+## Plan
+
+### Setup i18n Infrastructure
+- [ ] Add Chinese locale to `docusaurus.config.ts`
+- [ ] Configure locale routing and language switcher
+- [ ] Create `i18n/zh-Hans/` directory structure
+- [ ] Set up translation workflow documentation
+
+### Translate Core Pages (Phase 1)
+- [ ] Homepage (`index.tsx` or homepage content)
+- [ ] Getting Started guide
+- [ ] Core Concepts overview
+- [ ] Quick Start tutorial
+- [ ] Navigation labels (`code.json`)
+- [ ] Common UI strings (buttons, labels, etc.)
+
+### Quality & Workflow
+- [ ] Create translation style guide (terminology, tone)
+- [ ] Document translation workflow for contributors
+- [ ] Add translation status tracking (which pages are translated)
+- [ ] Test locale switching and URL routing
+
+### Deployment
+- [ ] Verify build process includes Chinese locale
+- [ ] Test Chinese site on Vercel preview
+- [ ] Add Chinese docs link to main README.md (near documentation links)
+- [ ] Add language badge/notice in docs site
+- [ ] Deploy to production
+
+## Test
+
+**Build & Navigation**:
+- [ ] `npm run build` succeeds with Chinese locale
+- [ ] Language switcher appears and works correctly
+- [ ] Chinese URLs route properly (`/zh-Hans/docs/...`)
+- [ ] All translated pages render without errors
+
+**Content Quality**:
+- [ ] Chinese text displays correctly (encoding, fonts)
+- [ ] Technical terms translated consistently
+- [ ] Code examples remain in English (code itself)
+- [ ] Links point to correct locale (Chinese → Chinese)
+
+**Fallback Behavior**:
+- [ ] Untranslated pages show English version with notice
+- [ ] Navigation works even with partial translation
+- [ ] Language switcher shows translation progress
+
+## Notes
+
+**Docusaurus i18n commands**:
+```bash
+# Run dev server with Chinese locale
+npm run start -- --locale zh-Hans
+
+# Build with all locales
+npm run build
+
+# Write translations (extracts default text)
+npm run write-translations -- --locale zh-Hans
+```
+
+**Translation resources**:
+- Docusaurus i18n guide: https://docusaurus.io/docs/i18n/introduction
+- Chinese technical writing style: Focus on clarity, avoid overly formal language
+- Terminology: Consider creating glossary (e.g., "spec" → "规范文档")
+
+**Accessibility for Chinese developers**:
+- Add link in main README.md (near existing documentation links)
+  - Format: `[中文文档](https://www.lean-spec.dev/zh-Hans/)` or similar
+  - Place prominently so it's discoverable without scrolling
+- Consider adding language badge/selector notice in docs header
+- Chinese URL will be: `https://www.lean-spec.dev/zh-Hans/`
+
+**Maintenance considerations**:
+- English docs are source of truth - Chinese translations may lag behind
+- Consider adding translation status badges to indicate freshness
+- May need community contributions to keep translations current
+
+**Future enhancements**:
+- Traditional Chinese (`zh-Hant`) for Taiwan/Hong Kong
+- Japanese (`ja`) or other languages
+- Automated translation sync detection (flag outdated translations)

package/.next/standalone/packages/ui/dist/standalone/specs/065-v03-planning/README.md

@@ -0,0 +1,158 @@
+---
+status: planned
+created: '2025-11-11'
+tags:
+  - release
+  - planning
+  - milestone
+  - v0.3.0
+  - performance
+  - ai-agents
+priority: critical
+created_at: '2025-11-11T06:41:08.335Z'
+depends_on:
+  - 059-programmatic-spec-management
+  - 067-monorepo-core-extraction
+  - 035-live-specs-showcase
+  - 075-intelligent-search-engine
+---
+
+# LeanSpec v0.3 - Performance & AI Agent Optimization
+
+> **Status**: 📅 Planned · **Priority**: Critical · **Created**: 2025-11-11
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+v0.3 focuses on **AI agent performance optimization** and **programmatic spec management**. With v0.2 successfully launched, we've identified key bottlenecks in AI agent workflows and opportunities to improve developer/AI collaboration through better tooling.
+
+**Why now?** v0.2 validated LeanSpec's core philosophy and received positive feedback. Usage analytics show AI agents spending significant time on spec discovery and parsing. v0.3 optimizes these workflows while adding features users are requesting.
+
+**Key Goals:**
+1. **10x faster spec operations** for AI agents (programmatic APIs)
+2. **Live documentation preview** for better feedback loops
+3. **Enhanced AI agent workflows** (improved context delivery)
+4. **Performance benchmarking** to measure and maintain gains
+
+## Design
+
+**v0.3 Theme: "Performance & Intelligence"**
+
+**Core Focus Areas:**
+
+1. **Programmatic Spec Management** (spec 059) - CRITICAL
+   - JSON-based APIs for AI agents
+   - Batch operations for efficiency
+   - Structured queries (filter/search without parsing all files)
+   - Performance benchmarks and optimization
+
+2. **Intelligent Search Engine** (spec 075) - CRITICAL
+   - Relevance ranking and scoring algorithms
+   - Field-weighted search (title > tags > content)
+   - Fuzzy matching for typo tolerance
+   - Boolean operators (AND/OR/NOT)
+   - Phrase search with quotes
+   - Replaces primitive substring matching
+
+3. **Live Specs Showcase** (spec 035) - HIGH PRIORITY
+   - Real-time documentation preview
+   - Embedded dogfooding showcase
+   - Performance optimization for large spec sets
+   - Deep dive into rendering/build optimization
+
+4. **MCP Server Enhancements**
+   - Optimize context delivery
+   - Add caching layer
+   - Reduce token usage in responses
+   - Better structured output
+
+**Release Criteria:**
+- All critical specs complete
+- Performance benchmarks show >5x improvement
+- Documentation updated with new APIs
+- Migration guide for any breaking changes
+- Test coverage maintained >80%
+
+## Plan
+
+**Phase 1: Core Performance (Week 1-2)**
+- [ ] Complete spec 059 (programmatic-spec-management)
+- [ ] Complete spec 075 Phase 1-2 (intelligent-search-engine)
+- [ ] Benchmark current performance (baseline metrics)
+- [ ] Implement caching layer for spec parsing
+- [ ] Optimize MCP server response times
+- [ ] Add performance tests to CI
+
+**Phase 2: Live Preview & Showcase (Week 2-3)**
+- [ ] Deep dive analysis of spec 035 requirements
+- [ ] Optimize Docusaurus build for large spec sets
+- [ ] Implement live preview functionality
+- [ ] Add interactive visualizations (Kanban, stats)
+- [ ] Performance optimization for client-side rendering
+
+**Phase 3: Polish & Documentation (Week 3-4)**
+- [ ] Update documentation with v0.3 features
+- [ ] Create migration guide
+- [ ] Performance benchmark results page
+- [ ] Blog post: "How We Made LeanSpec 10x Faster"
+- [ ] Update CHANGELOG.md
+
+**Phase 4: Release (Week 4)**
+- [ ] Final testing and QA
+- [ ] Version bump to 0.3.0
+- [ ] Publish to npm
+- [ ] Deploy docs updates
+- [ ] Announce on social media
+
+## Test
+
+**Performance Benchmarks:**
+- [ ] Spec loading <10ms (from ~100ms)
+- [ ] List operations <50ms for 100 specs
+- [ ] Search operations <100ms across all specs
+- [ ] MCP server responses <200ms average
+- [ ] Docs build time <30s (with showcase)
+
+**Functionality Tests:**
+- [ ] All existing CLI commands work unchanged
+- [ ] New programmatic APIs work as documented
+- [ ] Live preview updates in real-time
+- [ ] Showcase displays all specs accurately
+- [ ] No breaking changes for existing users
+
+**Quality Gates:**
+- [ ] Test coverage >80%
+- [ ] No critical bugs in staging
+- [ ] Documentation 100% accurate
+- [ ] Migration path tested
+
+## Notes
+
+**Priority Decisions:**
+- **059 (programmatic-spec-management)**: CRITICAL - Foundation for AI agent performance
+- **075 (intelligent-search-engine)**: CRITICAL - Search is broken, blocks AI agent effectiveness
+- **035 (live-specs-showcase)**: HIGH - User-requested, builds trust, needs deep optimization work
+
+**Dependencies:**
+- spec 059 → Must complete first (enables performance gains)
+- spec 035 → Can parallel track after 059 design phase
+
+**Open Questions:**
+- Should we include Copilot slash commands (034) in v0.3 or defer to v0.4?
+- Do we need breaking changes for performance gains?
+- What's the migration strategy if APIs change?
+
+**Success Metrics:**
+- AI agent operations 10x faster
+- Docs build time <30s (currently ~45s)
+- User satisfaction: showcase gets >70% positive feedback
+- Adoption: 5+ new users from showcase visibility
+
+**Related Specs:**
+- 059-programmatic-spec-management (critical path)
+- 075-intelligent-search-engine (critical path)
+- 035-live-specs-showcase (high priority)
+- 043-official-launch-02 (just completed)
+- Future: 034-copilot-slash-commands, 036-pm-integrations