@leanspec/ui 0.2.7-dev.20251126100750 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/archived/003-init-system-redesign/README.md

@@ -0,0 +1,113 @@
+---
+status: complete
+created: 2025-10-31
+tags: [init, cli, templates]
+priority: high
+completed: 2025-10-31
+---
+
+# init-system-redesign
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-10-31 · **Tags**: init, cli, templates
+
+
+**Status**: ✅ Complete  
+**Created**: 2025-10-31  
+**Spec**: `specs/20251031/003-init-system-redesign.md`
+
+## Overview
+
+LeanSpec should help projects adopt Spec-Driven Development through `lean-spec init`. Current system only manages individual specs. We need project initialization that sets up the entire working model: spec structure, AI agent instructions, examples, and customizable conventions.
+
+## Objectives
+
+- `lean-spec init` command with one interactive question, three paths
+- Templates become full project initialization bundles (not just spec formats)
+- Spec structure uses folders: `specs/YYYYMMDD/NNN-name/README.md` (not flat files)
+- Config system: `.lean-spec/config.json` for project-specific customization
+- Keep it lean: Quick start is zero-friction, customization only when needed
+
+## Non-Goals
+
+- Over-engineering config options (start with minimal, essential settings)
+- Breaking existing projects (migration path or backward compat)
+- Complex template inheritance or plugin system
+- Mandatory interactive prompts (quick start should be fast)
+
+## Design
+
+### Init Flow
+```
+$ lean-spec init
+
+? How would you like to set up?
+  > Quick start (recommended)     - solo-dev defaults, immediate
+    Choose template               - Pick: solo-dev, team, enterprise, api-first
+    Customize everything          - Full control over structure
+```
+
+### Template Structure
+```
+templates/
+├── solo-dev/
+│   ├── config.json           # Default config
+│   ├── files/
+│   │   ├── AGENTS.md
+│   │   └── specs/
+│   │       └── 001-example-spec/
+│   │           └── README.md
+│   └── README.md            # Template documentation
+├── team/
+├── enterprise/
+└── api-first/
+```
+
+### Config System
+`.lean-spec/config.json`:
+```json
+{
+  "template": "solo-dev",
+  "specsDir": "specs",
+  "structure": {
+    "pattern": "{date}/{seq}-{name}/",
+    "dateFormat": "YYYYMMDD",
+    "sequenceDigits": 3
+  }
+}
+```
+
+### Spec Structure Change
+- **Before**: `specs/20251031/001-name.md` (file)
+- **After**: `specs/20251031/001-name/README.md` (folder)
+- Allows multiple files per spec (diagrams, supporting docs, etc.)
+
+## Implementation Plan
+
+1. [ ] Add prompts library (@inquirer/prompts or prompts)
+2. [ ] Implement config loader/writer for .lean-spec/config.json
+3. [ ] Redesign template structure as project bundles
+4. [ ] Implement init command with three paths
+5. [ ] Update create command to use folder structure + read config
+6. [ ] Migrate existing specs to folder structure
+7. [ ] Update archive/list commands for folders
+8. [ ] Update docs (README, AGENTS.md)
+
+## Success Criteria
+
+- [ ] `lean-spec init` works with one question, three paths
+- [ ] Quick start takes <2 seconds, zero additional input
+- [ ] Templates include full working model (AGENTS.md, examples)
+- [ ] Specs created as folders with README.md
+- [ ] Config system allows customization without CLI flags
+- [ ] Existing projects can migrate or continue working
+
+## References
+
+- Previous spec: `002-template-system-redesign.md` (superseded by this)
+- Prompts libraries: @inquirer/prompts, prompts
+
+## Notes
+
+This redesign addresses the real need: LeanSpec as a **project initialization system** for SDD adoption, not just a spec file manager. Templates are working models, not fill-in-the-blank forms.
+
+Key insight: Spec template is just one component of the working model. Full adoption needs AGENTS.md, examples, conventions, and structure.

package/.next/standalone/packages/ui/dist/standalone/specs/archived/004-existing-project-integration/README.md

@@ -0,0 +1,69 @@
+---
+status: complete
+created: 2025-11-01
+tags: [integration, init, migration]
+priority: high
+completed: 2025-11-01
+---
+
+# Existing Project Integration
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-01 · **Tags**: integration, init, migration
+
+## Goal
+
+Support `lean-spec init` on projects with existing `AGENTS.md` or system prompts without clobbering their content.
+
+## Key Scenarios
+
+1. **Merge Mode**: User has `AGENTS.md` → detect, offer to merge LeanSpec section ✅
+2. **Backup Mode**: User chooses not to merge → backup existing, create new ✅
+3. **Skip Mode**: User wants to keep their setup → just add .lean-spec config and specs/ ✅
+
+## Acceptance Criteria
+
+- [x] Detect existing `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`
+- [x] Interactive prompt: merge, backup, or skip
+- [x] If merge: append LeanSpec section with clear delimiter
+- [x] If backup: rename to `AGENTS.md.backup`, create new
+- [x] If skip: don't touch existing files, only add lean-spec structure
+
+## Implementation
+
+Added three helper functions in `src/commands.ts`:
+
+1. `detectExistingSystemPrompts()` - Checks for common system prompt files
+2. `handleExistingFiles()` - Implements merge/backup/skip logic
+3. Updated `copyDirectory()` - Supports skipping specified files
+
+Interactive flow in `initProject()`:
+- Detects existing files before copying templates
+- Prompts user with 3 options: merge, backup, or skip
+- Handles each option appropriately
+- Only copies non-conflicting files from template
+
+## Non-Goals
+
+- Auto-detecting project type from existing files (just handle conflicts) ✓
+- Parsing/understanding existing AGENTS.md content (simple append) ✓
+- Supporting every possible system prompt variant (start with common ones) ✓
+
+## Testing
+
+Basic test script created: `test-integration.sh`
+
+Manual testing:
+```bash
+cd /tmp/lspec-test-existing
+node /path/to/lean-spec init
+# Choose merge/backup/skip and verify behavior
+```
+
+## Notes
+
+Supported system prompt files:
+- `AGENTS.md` (merge supported)
+- `.cursorrules` (backup/skip only)
+- `.github/copilot-instructions.md` (backup/skip only)
+
+Future: Could extend merge support to other file types if needed.

package/.next/standalone/packages/ui/dist/standalone/specs/archived/004-existing-project-integration/SUMMARY.md

@@ -0,0 +1,112 @@
+# Existing Project Integration - Summary
+
+## What We Built
+
+Added smart detection and handling for projects that already have `AGENTS.md` or other system prompts when running `lean-spec init`.
+
+## Key Features
+
+### 1. Auto-Detection
+Detects these common system prompt files:
+- `AGENTS.md`
+- `.cursorrules`  
+- `.github/copilot-instructions.md`
+
+### 2. Three Integration Modes
+
+When existing files are detected, users choose how to proceed:
+
+**Merge Mode** (for AGENTS.md)
+- Preserves existing content completely
+- Appends LeanSpec section with clear `---` delimiter
+- Best for: Adding LeanSpec to established projects
+
+**Backup Mode**
+- Renames existing files to `.backup`
+- Creates fresh files from template
+- Best for: Starting over while keeping old content safe
+
+**Skip Mode**
+- Leaves existing files completely untouched
+- Only adds `.lean-spec/` config and `specs/` directory
+- Best for: Manual integration or using existing setup as-is
+
+### 3. Intelligent File Copying
+
+The `copyDirectory` function now:
+- Checks for file existence before copying
+- Skips files the user wants to preserve
+- Only copies what's needed
+
+## Files Changed
+
+1. **src/commands.ts**
+   - Added `detectExistingSystemPrompts()` - Checks for system prompt files
+   - Added `handleExistingFiles()` - Implements merge/backup/skip logic
+   - Modified `initProject()` - Integrated detection flow
+   - Modified `copyDirectory()` - Support for skipping files
+
+2. **README.md**
+   - Added "Integrating with Existing Projects" section
+   - Documents all three modes with use cases
+
+3. **specs/20251101/001-existing-project-integration/README.md**
+   - Complete spec for the feature
+   - Marked as ✅ Complete with implementation notes
+
+4. **examples/integration-merge-example.md**
+   - Shows before/after of merge mode
+   - Explains benefits and alternatives
+
+5. **test-integration.sh**
+   - Basic test script for file detection
+   - Instructions for manual testing
+
+## Usage Example
+
+```bash
+# Project with existing AGENTS.md
+cd my-existing-project
+
+# Run lean-spec init
+lean-spec init
+
+# Output:
+# Welcome to LeanSpec!
+# 
+# Found existing: AGENTS.md
+# How would you like to proceed?
+#   > Merge - Add LeanSpec section to existing files
+#     Backup - Save existing and create new
+#     Skip - Keep existing files as-is
+
+# Choose your preferred mode!
+```
+
+## Testing
+
+1. **Automated**: Run `./test-integration.sh` for basic checks
+2. **Manual**: 
+   ```bash
+   cd /tmp/lspec-test-existing
+   node /path/to/lean-spec/bin/lspec.js init
+   # Test each mode: merge, backup, skip
+   ```
+
+## Future Enhancements
+
+Potential improvements (not in current scope):
+- Extend merge support to `.cursorrules` and other files
+- Smart content parsing to avoid duplicate sections
+- Template-aware merging (different merge strategies per template)
+- Diff preview before merge
+
+## Dogfooding Note
+
+This feature itself follows LeanSpec principles:
+- Clear goal: Don't clobber existing files
+- Essential scenarios: merge, backup, skip
+- Minimal implementation: Simple append for merge, straightforward backup/skip
+- Living: Can extend merge support to more files if needed
+
+Keeping it lean! 🚀

package/.next/standalone/packages/ui/dist/standalone/specs/archived/005-structured-frontmatter/README.md

@@ -0,0 +1,229 @@
+---
+status: complete
+created: 2025-11-01
+tags:
+  - enhancement
+  - spec-management
+  - metadata
+priority: medium
+completed: '2025-11-01'
+---
+
+# structured-frontmatter
+
+> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-01 · **Tags**: enhancement, spec-management, metadata
+
+## Overview
+
+Currently, LeanSpec specs use inline text fields (`**Status**: Complete`, `**Created**: 2025-10-31`) which are human-readable but difficult to parse programmatically. This makes it hard to:
+
+- Filter specs by status (planned, in-progress, complete, archived)
+- Query specs by tags or categories
+- Build tooling for spec management (dashboards, reports)
+- Track metadata consistently across specs
+
+**Solution**: Add structured YAML frontmatter to specs for better metadata management while maintaining readability.
+
+## Design
+
+### Frontmatter Structure
+
+#### Core Fields (Required)
+
+```yaml
+---
+status: planned | in-progress | complete | archived
+created: YYYY-MM-DD
+---
+```
+
+That's it for the basics. These two fields give you filtering and tracking.
+
+#### Recommended Fields (High Value, Low Overhead)
+
+```yaml
+---
+status: in-progress
+created: 2025-11-01
+tags: [feature, api]        # Quick categorization
+priority: high              # Focus management
+---
+```
+
+Most users should stop here. These 4 fields cover 90% of needs.
+
+#### Power User Fields (Use Sparingly)
+
+Only add these when they genuinely help:
+
+```yaml
+---
+# Dependencies (when specs actually block each other)
+related: [20251031/001-typescript-cli, 20251101/001-existing-project]
+depends_on: [20251031/003-init-system]
+
+# Temporal (mostly auto-managed)
+updated: YYYY-MM-DD         # auto-updated
+completed: YYYY-MM-DD       # auto-set when status=complete
+
+# Team coordination (for larger teams)
+assignee: username
+reviewer: username
+
+# External links (when needed)
+issue: #123
+pr: #456
+epic: epic-name
+
+# Flags (when relevant)
+breaking: true
+---
+```
+
+**Note**: Spec references use full path `YYYYMMDD/NNN-name` for uniqueness across dates.
+
+**Philosophy**: Start minimal. Add fields only when you feel the pain of not having them.
+
+### Implementation Approach
+
+1. **Template Updates**: 
+   - `minimal/`: `status`, `created`
+   - `standard/`: + `tags`, `priority`
+   - `enterprise/`: + `assignee`, `reviewer`, `issue`, `epic`
+
+2. **CLI Support**: 
+   - Parse frontmatter when listing specs
+   - Common filters: `lean-spec list --status=in-progress --tag=api --priority=high`
+   - Quick updates: `lean-spec update <spec> --status=complete`
+   - Validation: warn on unknown fields, validate enum values
+
+3. **Smart Defaults**:
+   - Auto-update `updated` timestamp on file changes (if field exists)
+   - Set `completed` date when status changes to complete (if field exists)
+
+4. **Backward Compatibility**: Inline fields (`**Status**: Complete`) work as fallback
+
+5. **Progressive Enhancement**: Users can add fields as needed without migration
+
+### Field Usage Guidelines
+
+**Default recommendation**: `status`, `created`, `tags`, `priority` - stop there.
+
+**Add more only when you need them**. If you're not sure, you don't need it.
+
+**Template defaults:**
+- **Minimal**: `status`, `created` only
+- **Standard**: `status`, `created`, `tags`, `priority`
+- **Enterprise**: Standard + team fields (assignee, reviewer) + links (issue, epic)
+
+### Example Specs
+
+**Typical Solo Developer:**
+```markdown
+---
+status: in-progress
+created: 2025-11-01
+tags: [feature, cli]
+---
+
+# add-list-command
+
+## Overview
+...
+```
+
+**Small Team:**
+```markdown
+---
+status: planned
+created: 2025-11-01
+tags: [api, breaking-change]
+priority: high
+assignee: alice
+related: [20251031/001-typescript-cli]
+---
+
+# api-v2-migration
+
+## Overview
+...
+```
+
+**Enterprise (Maximum Fields):**
+```markdown
+---
+status: in-progress
+created: 2025-10-28
+updated: 2025-11-01
+tags: [security, compliance]
+priority: critical
+assignee: security-team
+reviewer: ciso
+depends_on: [20251031/001-typescript-cli]
+issue: JIRA-1234
+epic: security-hardening
+breaking: true
+---
+
+# oauth2-migration
+
+## Overview
+...
+```
+
+## Plan
+
+- [ ] Define minimal field schema (status, created as required)
+- [ ] Add frontmatter parsing library (`gray-matter`)
+- [ ] Update template files: minimal (2 fields), standard (4 fields), enterprise (8-10 fields)
+- [ ] Implement frontmatter parser with validation
+- [ ] Add filtering to `lean-spec list` (status, tags, priority)
+- [ ] Create `lean-spec update` command for status changes
+- [ ] Add smart defaults for optional timestamp fields
+- [ ] Update documentation emphasizing minimalism
+- [ ] Add tests for core fields + graceful handling of extra fields
+
+## Test
+
+- [ ] CLI parses minimal frontmatter (status, created)
+- [ ] Filtering works: `lean-spec list --status=planned --tag=api`
+- [ ] `lean-spec update <spec> --status=complete` updates correctly
+- [ ] Old specs without frontmatter still work (fallback)
+- [ ] Templates generate appropriate field sets per tier
+- [ ] Unknown fields generate warnings but don't fail
+- [ ] Auto-timestamps work when fields are present (optional)
+- [ ] Query performance acceptable with 100+ specs
+
+## Notes
+
+### Why Frontmatter?
+
+- Industry standard (Jekyll, Hugo, Gatsby, etc.)
+- Human-readable and git-friendly
+- Easy to parse with existing libraries
+- Doesn't clutter the main content
+- Extensible for future metadata needs
+
+### Alternatives Considered
+
+1. **JSON/TOML frontmatter**: More verbose, less common
+2. **Inline structured comments**: Harder to parse reliably
+3. **Separate metadata files**: Introduces file synchronization issues
+4. **Database/external store**: Against LeanSpec's file-first philosophy
+
+### Future Extensions
+
+Only build these if users ask for them:
+
+- `lean-spec stats` - "5 in-progress, 12 complete" summary
+- `lean-spec board` - Kanban-style view by status (planned | in-progress | complete)
+- `lean-spec gantt` - Timeline view with dependencies and due dates
+- `lean-spec timeline` - Visualize spec creation/completion over time
+- `lean-spec deps <spec>` - Show dependency graph (depends_on, blocks visualization)
+- `lean-spec search` - Full-text search with metadata filters
+- Export formats: JSON, CSV, markdown table for reporting
+- Integration hooks: webhook on status change, sync to Jira/Linear
+- AI suggestions: auto-tag based on content, suggest related specs
+- Metrics: cycle time (created → complete), blocked time tracking
+
+**Vision**: With structured metadata, LeanSpec can evolve from a simple file tool into a powerful project visibility system while staying true to its lean, file-first philosophy.