@leanspec/ui 0.2.6 → 0.2.7-dev.20251126090057

package/.next/standalone/packages/ui/dist/standalone/specs/051-docs-system-prompt-principles/README.md

@@ -1,339 +0,0 @@
----
-status: complete
-created: '2025-11-05'
-tags:
-  - documentation
-  - ai-agents
-  - first-principles
-  - system-prompt
-  - philosophy
-  - v0.2.0
-priority: critical
-related:
-  - 049-leanspec-first-principles
-  - 050-tool-redesign-first-principles
-created_at: '2025-11-05T00:00:00Z'
-updated_at: '2025-11-05T05:44:08.444Z'
-completed_at: '2025-11-05T05:44:08.444Z'
-completed: '2025-11-05'
-transitions:
-  - status: complete
-    at: '2025-11-05T05:44:08.444Z'
----
-
-# Update System Prompt and Docs with First Principles
-
-> **Status**: ✅ Complete · **Priority**: Critical · **Created**: 2025-11-05 · **Tags**: documentation, ai-agents, first-principles, system-prompt, philosophy, v0.2.0
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-**Purpose**: Embed the 5 LeanSpec first principles from spec 049 into AGENTS.md, README.md, and documentation so both AI agents and users understand and apply them consistently.
-
-**Why Now**:
-- First principles established in spec 049 but not integrated into guidance
-- AI agents need conflict resolution framework for spec decisions
-- Users need to understand philosophy driving LeanSpec design
-- Current docs focus on "what" not "why"
-
-**Key Insight**: Documentation should teach principles, not just commands. When users/AI understand the "why," they make better decisions without needing explicit rules for every case.
-
-**Result**: Updated documentation where first principles are visible, actionable, and guide decision-making for both humans and AI.
-
-## Background
-
-### Current Documentation State
-
-**AGENTS.md**:
-- ✅ Has practical guidelines (line thresholds, when to split)
-- ❌ Missing WHY these guidelines exist
-- ❌ No conflict resolution framework
-- ❌ Doesn't connect practices to principles
-
-**README.md**:
-- ✅ Shows adaptive design, features
-- ❌ Philosophy implied but not explicit
-- ❌ First principles not stated clearly
-- ❌ Missing "decision framework" section
-
-**Docs Site**:
-- ✅ Good getting started guides
-- ❌ Philosophy buried or scattered
-- ❌ No clear "First Principles" page
-- ❌ Examples don't highlight principle application
-
-### The Gap
-
-**Spec 049 identified 5 first principles**:
-1. Context Economy
-2. Signal-to-Noise Maximization
-3. Progressive Disclosure
-4. Intent Over Implementation
-5. Bridge the Gap
-
-**Current docs** focus on mechanics (how to use commands) without grounding in these principles.
-
-**Result**: Users follow rules without understanding. AI agents can't reason about edge cases.
-
-### What Success Looks Like
-
-**AI Agents** can:
-- Resolve conflicts using principle priority order
-- Decide when to split specs (Context Economy > completeness)
-- Choose what to include/exclude (Signal-to-Noise test)
-- Make spec structure decisions without explicit rules
-
-**Users** can:
-- Understand why LeanSpec is designed this way
-- Make consistent decisions aligned with philosophy
-- Explain LeanSpec philosophy to teammates
-- Evaluate if LeanSpec fits their needs (clear identity)
-
-## Design
-
-### Core Approach: Principles as Foundation
-
-**Strategy**: Make principles discoverable at every level
-- README: Quick principle summary in "Why LeanSpec" section
-- AGENTS.md: Detailed guidance with conflict resolution
-- Docs site: Dedicated first principles page with examples
-- Examples: Annotate with which principles they demonstrate
-
-### AGENTS.md Updates
-
-**Section 1: First Principles Framework** (new)
-```markdown
-## First Principles (Decision Framework)
-
-When making spec decisions, apply principles in priority order:
-
-1. **Context Economy** - Fit in working memory (<400 lines)
-   - Question: "Can this be read in 5-10 minutes?"
-   - Action: Split at 400 lines, warning at 300
-   
-2. **Signal-to-Noise** - Every word informs decisions
-   - Question: "What decision does this inform?"
-   - Action: Cut if answer is "none" or "maybe future"
-   
-3. **Intent Over Implementation** - Capture why, not just how
-   - Question: "Is the rationale clear?"
-   - Action: Explain trade-offs, constraints, success criteria
-   
-4. **Bridge the Gap** - Both human and AI must understand
-   - Question: "Can both parse and reason about this?"
-   - Action: Clear structure + natural language explanation
-   
-5. **Progressive Disclosure** - Add complexity when pain is felt
-   - Question: "Do we need this now?"
-   - Action: Start minimal, add fields when required
-
-### Conflict Resolution Examples
-
-**"Should I split this 450-line spec?"**
-→ Yes (Context Economy at 400 lines overrides completeness)
-
-**"Should I document every edge case?"**
-→ Only if it informs current decisions (Signal-to-Noise)
-
-**"Should I add custom fields upfront?"**
-→ Only if you feel pain without them (Progressive Disclosure)
-
-**"Should I keep implementation details in spec?"**
-→ Only if rationale/constraints matter (Intent Over Implementation)
-```
-
-**Section 2: Quality Checks** (enhanced)
-- Add principle validation to existing guidelines
-- Connect line thresholds to Context Economy
-- Link splitting guidance to Signal-to-Noise
-
-**Section 3: Common Patterns** (new)
-- Good vs bad examples annotated with principles
-- Show how principles resolve real conflicts
-- Include AI agent decision scenarios
-
-### README.md Updates
-
-**Add "Core Principles" Section** (after "The LeanSpec Solution")
-```markdown
-## Core Principles
-
-LeanSpec is built on 5 first principles that define what it is:
-
-1. **Context Economy** - Specs must fit in working memory (human + AI)
-   - Target <300 lines, warning 300-400, split >400
-   - Why: Physics (context windows) + Biology (attention)
-
-2. **Signal-to-Noise Maximization** - Every word must inform decisions
-   - Test: "What decision does this sentence inform?"
-   - Why: Token costs, cognitive load, maintenance
-
-3. **Progressive Disclosure** - Add structure only when pain is felt
-   - Start: Just status + created
-   - Scale: Add fields as team/complexity grows
-   - Why: Premature abstraction is waste
-
-4. **Intent Over Implementation** - Capture "why" and "what," let "how" emerge
-   - Must: Problem, intent, success criteria
-   - Optional: Implementation details
-   - Why: Intent is stable, implementation changes
-
-5. **Bridge the Gap** - Align human intent with machine execution
-   - For humans: Context, rationale
-   - For AI: Clear requirements, structure
-   - Why: Gap between goals and execution must be bridged
-
-These aren't principles we chose—they're constraints we discovered. 
-[Learn more in spec 049 →](./specs/049-leanspec-first-principles/)
-```
-
-**Enhance "Why LeanSpec" Section**
-- Connect features to principles explicitly
-- Show how principles solve the stated problems
-- Add principle-driven design examples
-
-### Docs Site Updates
-
-**New Page: `/docs/guide/first-principles.md`**
-- Deep dive into each principle with examples
-- When principles conflict, how to resolve
-- How principles influenced LeanSpec design
-- Link to spec 049 for full analysis
-
-**Update Existing Pages**:
-- Getting Started: Add "Philosophy in 60 seconds"
-- Best Practices: Annotate with principle connections
-- FAQ: Add "Why these constraints?" section
-- Examples: Label which principles each demonstrates
-
-## Plan
-
-### Phase 1: AGENTS.md (Week 1)
-**Goal**: AI agents can resolve conflicts using principles
-
-- [ ] Add "First Principles Framework" section at top
-- [ ] Add conflict resolution examples with principle priority
-- [ ] Enhance existing guidelines with principle connections
-- [ ] Add "Common Patterns" section with annotated examples
-- [ ] Test with AI agent scenarios (simulate conflicts)
-
-**Success**: AI can answer "should I...?" questions using principles
-
-### Phase 2: README.md (Week 1)
-**Goal**: Users understand philosophy driving LeanSpec
-
-- [ ] Add "Core Principles" section after solution description
-- [ ] Connect principles to problem statement
-- [ ] Enhance "Why LeanSpec" with principle examples
-- [ ] Add links to deeper principle documentation
-- [ ] Keep under 300 lines total (Context Economy!)
-
-**Success**: New users understand "why" not just "what"
-
-### Phase 3: Docs Site (Week 2)
-**Goal**: Comprehensive principle documentation with examples
-
-- [ ] Create `/docs/guide/first-principles.md` page
-- [ ] Add "Philosophy in 60 seconds" to Getting Started
-- [ ] Annotate existing examples with principles
-- [ ] Add FAQ entries about principles
-- [ ] Create principle-focused tutorial
-
-**Success**: Users can learn philosophy at any depth level
-
-### Phase 4: Validation (Week 2)
-**Goal**: Verify principles are clear and actionable
-
-- [ ] Self-validation: Create test scenarios and apply framework
-- [ ] AI agent testing: Simulate conflicts, verify principle-based decisions
-- [ ] Fresh-eyes test: Read docs with "beginner mindset"
-- [ ] Dog-fooding: Use principles in next spec work
-- [ ] Optional: Share with early users (Discord, GitHub discussions) if available
-
-**Success**: Principles enable consistent decision-making (demonstrated through test scenarios)
-
-## Test
-
-### Principle Visibility
-
-- [ ] README mentions all 5 principles clearly
-- [ ] AGENTS.md provides decision framework
-- [ ] Docs site has dedicated first principles page
-- [ ] Examples annotated with which principles they demonstrate
-
-### AI Agent Capability
-
-Test scenarios where AI must apply principles:
-- [ ] "This spec is 450 lines, what should I do?" → Correctly applies Context Economy
-- [ ] "Should I add these future considerations?" → Correctly applies Signal-to-Noise
-- [ ] "Should I add custom fields now?" → Correctly applies Progressive Disclosure
-- [ ] Given conflicting guidance, resolves using principle priority
-
-### User Understanding
-
-Test by simulating new user scenarios:
-- [ ] Reading README: Can extract 5 principles without searching
-- [ ] Given question "Why 400-line limit?": Docs clearly explain Context Economy
-- [ ] Decision scenario: "450-line spec" → Framework leads to "split" decision
-- [ ] Can write 2-paragraph philosophy summary from docs alone
-
-### Quality Checks
-
-- [ ] AGENTS.md <300 lines (practices Context Economy)
-- [ ] README Core Principles section <100 lines (Signal-to-Noise)
-- [ ] Every principle statement actionable (not abstract philosophy)
-- [ ] Examples show principle application clearly
-
-## Success Metrics
-
-**Documentation Quality**:
-- All 5 principles documented in 3+ places (README, AGENTS.md, docs site)
-- Conflict resolution framework in AGENTS.md
-- Examples annotated with principles
-- Links between related docs
-**User/AI Capability** (validated through scenarios):
-- Principles discoverable in <5 minutes of reading
-- AI agents make principle-consistent decisions in test cases
-- Conflict scenarios resolve systematically using framework
-- Docs enable self-service philosophy understanding
-
-**Internal Quality** (measurable now):
-- First principles referenced in new spec work
-- Design decisions justified by principles
-- Team uses principle language in planning
-- Philosophy serves as filter for feature requestses
-- Users share philosophy with others
-
-## Notes
-
-### Key Design Decisions
-
-**Principle Priority Order**: Context Economy first because nothing else matters if spec doesn't fit in working memory.
-
-**Placement Strategy**: 
-- README: Quick summary for discovery
-- AGENTS.md: Detailed framework for decision-making
-- Docs site: Deep dive for comprehensive understanding
-
-**Annotation Approach**: Show don't tell—examples demonstrate principles better than abstract explanation.
-
-### What This Enables
-
-**Consistency**: Same principles guide users and AI agents
-**Scalability**: Principles work for solo dev → enterprise
-**Identity**: Clear differentiation from other SDD approaches
-**Quality**: Decisions justified by principles, not preferences
-
-### This Spec Demonstrates Principles
-
-**Context Economy**: 260 lines, single file, focused scope
-**Signal-to-Noise**: Every section informs implementation
-**Progressive Disclosure**: Core plan first, details in sections
-**Intent Over Implementation**: Clear "why" for each update
-**Bridge the Gap**: Readable by humans, actionable by AI
-
----
-
-**Remember**: Documentation isn't just reference material—it's how we transfer philosophy to users and AI agents. If they understand principles, they don't need rules for every case.

package/.next/standalone/packages/ui/dist/standalone/specs/052-branding-assets/README.md

@@ -1,128 +0,0 @@
----
-status: complete
-created: '2025-11-05'
-tags:
-  - design
-  - launch
-  - v0.2.0
-priority: high
----
-
-# Export and Deploy Brand Assets
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-05
-
-**Project**: lean-spec  
-**Dependencies**: Spec 043 (Official Launch v0.2.0)
-
-## Overview
-
-Export LeanSpec brand assets in all required formats and deploy across documentation, repository, and marketing channels for the v0.2.0 launch.
-
-**Logo Selected:** Version 3 of Concept D - "The Bracket"
-- Minimalist bracket frame with "LS" monogram
-- Represents bounded context (Context Economy principle)
-- Code-like aesthetic, scales perfectly 16px-512px
-- Colors: Dark (#1a1a2e), Light (#ffffff), Accent (#00d9ff)
-
-## Design
-
-### Asset Requirements
-
-**Logo Formats:**
-- [x] SVG (vector, primary)
-  - [x] `logo-with-bg.svg` (dark on white, theme-safe) - ✅ Created
-  - [x] `logo-dark-bg.svg` (cyan on dark, for dark mode) - ✅ Created
-  - [x] `logo.svg` (dark, transparent - advanced use only) - ✅ Created
-  - [x] `logo-light.svg` (white, transparent - advanced use only) - ✅ Created
-- [x] PNG exports (16px, 32px, 64px, 128px, 256px, 512px) - ✅ Created
-- [x] Favicon (ICO format, 16x16, 32x32) - ✅ Created
-
-**Social Media Assets:**
-- [x] GitHub social preview (1280x640px PNG) - ✅ Created
-- [x] Twitter/X card (1200x630px PNG) - ✅ Created (same as Open Graph)
-- [x] Open Graph image (1200x630px PNG) - ✅ Created
-- [ ] LinkedIn banner (1584x396px PNG) - Not needed for v0.2.0
-
-**Documentation:**
-- [x] Logo in README.md header - ✅ Added (theme-safe version)
-- [x] Branding guidelines document - ✅ Created (`docs-site/static/BRANDING.md`)
-- [x] Logo in docs site navbar with dark mode support - ✅ Configured
-- [x] Favicon for docs site - ✅ Deployed
-- [x] Update docusaurus social card - ✅ Updated
-
-### Design Rationale
-
-**Why the bracket logo?**
-1. **Context Economy** - Brackets visually represent "bounded context"
-2. **Developer-friendly** - Brackets are familiar to developers (code syntax)
-3. **Scalable** - Simple geometric shapes scale perfectly at any size
-4. **Memorable** - "LS" monogram is direct and easy to recall
-5. **First Principles** - Minimalist design reflects signal-to-noise principle
-
-## Plan
-
-**Phase 1: Export Core Assets** ✅ COMPLETE
-- [x] Create SVG variants (with-bg, dark-bg, transparent) - ✅ DONE
-- [x] Update README with theme-safe logo - ✅ DONE
-- [x] Update docs site with theme-aware logos - ✅ DONE
-- [x] Document branding guidelines - ✅ DONE
-- [x] Export PNG sizes using design tool or CLI - ✅ DONE
-- [x] Generate favicon files - ✅ DONE
-
-**Phase 2: Deploy to Docs Site** ✅ COMPLETE
-- [x] Verify logo rendering in navbar - ✅ DONE
-- [x] Replace favicon files - ✅ DONE
-- [x] Update social card image reference - ✅ DONE
-- [x] Test dark/light mode logo switching - ✅ DONE
-
-**Phase 3: Marketing Assets** ✅ COMPLETE
-- [x] Create GitHub social preview image - ✅ DONE
-- [x] Create Twitter/X card design - ✅ DONE
-- [x] Create Open Graph image - ✅ DONE
-- [x] Add meta tags to docs site - ✅ DONE (automatic via Docusaurus)
-
-**Phase 4: Repository Updates**
-- [x] Add favicon to repository root - ✅ DONE
-- [ ] Update GitHub repository settings (manual step post-merge)
-- [ ] Add to CHANGELOG for v0.2.0 (will be done in spec 043)
-
-## Test
-
-- [x] Logo renders correctly in README (GitHub) - ✅ Verified
-- [x] Logo renders correctly in docs site navbar - ✅ Verified
-- [x] Favicon appears in browser tabs - ✅ Verified (build output)
-- [x] Social media previews display correctly - ✅ Meta tags verified
-- [x] Logo scales properly at all sizes (16px to 512px) - ✅ Verified
-- [x] Brand colors match specification (#1a1a2e, #ffffff, #00d9ff) - ✅ Verified
-- [x] Dark/light mode logo switching works - ✅ Verified
-
-## Notes
-
-### Tools for Export
-
-**SVG to PNG conversion:**
-```bash
-# Using rsvg-convert (install via homebrew)
-brew install librsvg
-
-# Export different sizes
-rsvg-convert -w 512 -h 512 logo.svg > logo-512.png
-rsvg-convert -w 256 -h 256 logo.svg > logo-256.png
-# ... repeat for all sizes
-```
-
-**Favicon generation:**
-```bash
-# Using ImageMagick
-brew install imagemagick
-convert logo-32.png logo-16.png favicon.ico
-```
-
-### Links to Spec 043
-
-This spec supports the branding checklist in spec 043 (MARKETING.md):
-- Export logo in all formats
-- Create favicon files
-- Update docs site
-- Create social media assets

package/.next/standalone/packages/ui/dist/standalone/specs/053-spec-assets-philosophy/README.md

@@ -1,97 +0,0 @@
----
-status: planned
-created: '2025-11-05'
-tags:
-  - philosophy
-  - documentation
-  - guidelines
-priority: low
----
-
-# Spec Assets and Artifact Management Philosophy
-
-> **Status**: 📅 Planned · **Priority**: Low · **Created**: 2025-11-05
-
-**Project**: lean-spec  
-**Related**: Spec 012 (sub-spec files), Spec 049 (first principles)
-
-## Overview
-
-Define clear philosophy for what files/assets belong in spec folders vs elsewhere. Spec 012 covers markdown sub-specs, but doesn't address images, mockups, diagrams, data files, or other artifacts.
-
-**Problem Identified**: During logo design (spec 052), we created HTML mockups for exploration. Question arose: "Do these belong in the spec folder?" Current guidance is unclear.
-
-**Gap**: No clear principle for:
-- Exploratory artifacts (mockups, prototypes, scratch work)
-- Supporting assets (diagrams, screenshots, data samples)
-- Production assets (final logos, configs, code)
-- Lifecycle management (when to keep, move, or delete)
-
-## Design
-
-### Core Principle
-
-Apply **Signal-to-Noise** test to every file in spec folder:
-- **Question**: "Does this file help someone understand the **why** behind decisions?"
-- **Keep**: Files that document rationale, trade-offs, chosen approach
-- **Remove**: Exploration artifacts, production assets, obvious content
-
-### Categories
-
-**Keep in Spec Folder:**
-- Diagrams explaining architecture/flow/design decisions
-- Screenshots showing UI/UX decisions referenced in spec
-- Small data files (<100KB) as examples (schemas, configs)
-- Design artifacts showing the **chosen** approach and **why**
-- Comparison images explaining trade-offs
-
-**Keep Outside Spec Folder:**
-- Interactive prototypes/mockups (HTML) - exploration tools, not documentation
-- Final production assets (logos, icons) - belong in project assets
-- Large files (videos, datasets) - use external links
-- Multiple design iterations - only final decision needs documenting
-
-**Lifecycle Management:**
-- During work: Exploration at project root
-- After decision: Move chosen artifacts to spec (if they add clarity)
-- After completion: Audit and remove noise
-
-### Example Use Case
-
-Logo design process (spec 052):
-- Exploration: HTML mockups at project root (temporary)
-- Decision: Add comparison PNG showing why brackets were chosen
-- Final assets: SVG files move to `docs-site/static/img/`
-- Cleanup: Delete exploration HTML files
-
-## Plan
-
-- [ ] Document asset philosophy in AGENTS.md or new guide
-- [ ] Update spec 012 to include non-markdown asset guidelines
-- [ ] Add `lean-spec validate` checks for oversized assets
-- [ ] Create examples showing good asset management
-- [ ] Add to spec creation templates/guidance
-
-## Related
-
-- Spec 012: Sub-spec files (covers markdown, not assets)
-- Spec 049: First principles (Signal-to-Noise applies here)
-- Spec 052: Branding assets (real-world case that exposed this gap)
-
-## Notes
-
-**Why This Matters:**
-- Prevents spec folders from becoming dumping grounds
-- Keeps specs lean (Context Economy)
-- Clarifies where production assets live
-- Helps with cleanup/maintenance
-
-**Not Urgent Because:**
-- Current practice works reasonably well
-- Can be addressed when spec complexity grows
-- Progressive Disclosure: add guidance when pain is felt
-
-**Future Considerations:**
-- CLI warnings for large assets in spec folders
-- Auto-cleanup tools for exploration artifacts
-- Template guidance for asset organization

package/.next/standalone/packages/ui/dist/standalone/specs/054-validate-output-lint-style/DESIGN-DECISIONS.md

@@ -1,93 +0,0 @@
-# Design Decisions
-
-## 1. File-Centric Grouping
-
-Group all issues by file path, not by validator type:
-
-```diff
-- Line Count:
--   ✗ 045-unified-dashboard (1169 lines - exceeds limit!)
--   ⚠ 049-leanspec-first-principles (373 lines - approaching limit)
-- 
-- Structure:
--   ✓ All 25 spec(s) passed
-- 
-- Sub-Specs:
--   ⚠ 045-unified-dashboard
--     • Orphaned sub-spec: IMPLEMENTATION.md
-
-+ 045-unified-dashboard/README.md
-+   error    Spec exceeds 400 lines (1169 lines)                   max-lines
-+   warning  Orphaned sub-spec: IMPLEMENTATION.md                  sub-specs
-+
-+ 049-leanspec-first-principles/README.md
-+   warning  Spec approaching limit (373/400 lines)                max-lines
-```
-
-**Rationale:** Matches ESLint/TypeScript. Easier to find issues for a specific spec.
-
-## 2. Compact Error Format
-
-Use aligned columns like ESLint:
-
-```
-<severity>  <message>  <rule-name>
-           <suggestion>
-```
-
-## 3. Quiet Success Mode (Default)
-
-Only show specs with issues, summarize clean specs:
-
-```diff
-- Line Count:
--   ✓ 053-spec-assets-philosophy (98 lines)
--   ✓ 052-branding-assets (129 lines)
--   ✓ 043-official-launch-02 (200 lines)
--   ... (15 more passing specs)
-
-+ ✖ 5 errors, 13 warnings (25 specs checked, 19 clean)
-```
-
-## 4. Severity Hierarchy
-
-Always show errors before warnings within a file - matches how developers prioritize fixes.
-
-## Design Trade-offs
-
-### Considered: Keep Validator Grouping
-
-```
-Pros: Shows all line count issues together
-Cons: Requires scanning multiple sections per spec
-```
-
-**Decision:** File-centric grouping (like ESLint/TypeScript)
-
-**Rationale:** Developers fix issues file-by-file, not rule-by-rule. Better to show all issues for a file together.
-
-### Considered: Show All Passing Specs
-
-```
-Pros: Complete transparency
-Cons: Noisy output, hard to spot issues
-```
-
-**Decision:** Quiet success by default, `--verbose` for details
-
-**Rationale:** ESLint/Prettier only show issues. Summary line provides confidence.
-
-## Backward Compatibility
-
-**Breaking Changes:**
-
-- Output format completely different (but exit codes unchanged)
-- Default behavior: quiet success (was: show all passing specs)
-
-**Migration:**
-
-1. Release in v0.2.0 with clear CHANGELOG notes
-2. Add migration guide showing old vs new output
-3. Keep `--verbose` as escape hatch for old-style detail
-
-**Rationale:** v0.2.0 is the "official launch" - acceptable time for UX breaking changes.