@leanspec/ui 0.2.7-dev.20251126100750 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/058-docs-overview-polish/IMPLEMENTATION.md

@@ -0,0 +1,642 @@
+# Implementation Guide
+
+> **Note**: This file exceeds 400 lines intentionally. It contains detailed implementation specifications, content templates, code examples, and checklists. These are reference materials meant to be consulted section-by-section, not read sequentially. The length provides comprehensive guidance for implementation.
+
+This document contains detailed implementation specifications for each content change.
+
+## First Principles Document
+
+**File**: `docs-site/docs/guide/first-principles.mdx`
+
+**Content Source**: Spec 049 (FIRST-PRINCIPLES.md)
+
+**Structure**:
+
+Frontmatter:
+- id: 'first-principles'
+- title: 'First Principles'
+- sidebar_position: 1
+
+Content sections:
+
+# First Principles
+
+> LeanSpec isn't arbitrary rules—it's derived from fundamental constraints.
+
+## Why First Principles?
+
+[Explain what first principles are and why they matter]
+
+## The 5 First Principles
+
+### 1. Context Economy
+**Specs must fit in working memory—both human and AI.**
+
+- **Target**: <300 lines per spec file
+- **Warning**: 300-400 lines (consider simplifying)
+- **Problem**: >400 lines (must split)
+- **Rationale**: 
+  - Physics: AI context windows are bounded (~20K effective tokens)
+  - Biology: Human working memory is limited (7±2 items)
+  - Economics: Large contexts cost more time and money
+
+**Question**: "Can this be read in 5-10 minutes?"
+**Action**: Split at 400 lines, warning at 300
+
+### 2. Signal-to-Noise Maximization
+**Every word must inform decisions or be cut.**
+
+- **Test**: "What decision does this sentence inform?"
+- **Cut**: Obvious, inferable, or "maybe future" content
+- **Keep**: Decision rationale, constraints, success criteria
+
+**Question**: "Does this add clarity?"
+**Action**: Remove anything that doesn't answer the test question
+
+### 3. Intent Over Implementation
+**Capture "why" and "what," let "how" emerge.**
+
+- **Must have**: Problem, intent, success criteria
+- **Should have**: Design rationale, trade-offs
+- **Could have**: Implementation details, examples
+
+**Question**: "Is the rationale clear?"
+**Action**: Explain trade-offs, constraints, success criteria
+
+### 4. Bridge the Gap
+**Specs exist to align human intent with machine execution.**
+
+- **For humans**: Overview, context, rationale
+- **For AI**: Unambiguous requirements, clear structure, examples
+- **Both must understand**: Use clear structure + natural language
+
+**Question**: "Can both parse and reason about this?"
+**Action**: Clear structure + natural language explanation
+
+### 5. Progressive Disclosure
+**Start simple, add structure only when pain is felt.**
+
+- **Solo dev**: Just status + created
+- **Feel pain?**: Add tags, priority, custom fields
+- **Never add**: "Just in case" features
+
+**Question**: "Do we need this now?"
+**Action**: Start minimal, add fields when required
+
+## Conflict Resolution Framework
+
+When practices conflict, apply principles in priority order:
+
+**Priority Order**:
+1. Context Economy
+2. Signal-to-Noise
+3. Intent Over Implementation
+4. Bridge the Gap
+5. Progressive Disclosure
+
+**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 test)
+
+**"Should I add custom fields upfront?"**
+→ **Only if you feel pain without them** (Progressive Disclosure)
+
+**"This spec is complex but under 350 lines, split it?"**
+→ **No** (Under Context Economy threshold, no split needed)
+
+## Applying First Principles
+
+[Examples of applying principles to real decisions]
+
+## Learning More
+
+- **[Philosophy](/docs/guide/philosophy)** - How to apply first principles day-to-day
+- **[Agile Principles](/docs/guide/principles)** - Practical guidelines for writing specs
+- **[Spec 049](https://github.com/codervisor/lean-spec/tree/main/specs/049-leanspec-first-principles)** - Full analysis and derivation
+
+**Adaptations for Docusaurus**:
+- Use Docusaurus admonitions (`:::tip`, `:::info`, `:::warning`)
+- Add frontmatter with sidebar position
+- Link to other docs pages
+- Format for web readability (shorter paragraphs, more headings)
+
+## Philosophy Update
+
+**File**: `docs-site/docs/guide/philosophy.mdx`
+
+**Key Changes**:
+
+Frontmatter:
+- id: 'philosophy'
+- title: 'Philosophy'
+- sidebar_position: 2
+
+Content updates:
+
+# Philosophy
+
+> "The best spec is the one that gets read, understood, and acted upon—by humans and AI alike."
+
+LeanSpec philosophy derives from **[5 first principles](/docs/guide/first-principles)** (Context Economy, Signal-to-Noise, Intent Over Implementation, Bridge the Gap, Progressive Disclosure).
+
+:::tip Start Here
+New to LeanSpec? Start with **[First Principles](/docs/guide/first-principles)** to understand the foundational constraints. Then come back here to understand the philosophy and mindset.
+:::
+
+## The Core Philosophy
+
+[Keep existing content but add explicit derivation]
+
+### 1. Documentation is a Means, Not an End
+**Derives from**: Signal-to-Noise Maximization
+
+The goal isn't to create comprehensive documentation. The goal is to **enable effective action**.
+
+[rest of content...]
+
+### 2. Context Beats Comprehensiveness
+**Derives from**: Intent Over Implementation
+
+Capturing **why** something matters is more valuable than exhaustively documenting **what** it is.
+
+[rest of content...]
+
+### 3. Specs Should Reduce Burden, Not Create It
+**Derives from**: Context Economy
+
+Traditional specs often become a burden...
+
+[rest of content...]
+
+### 4. AI Changes Everything
+**Derives from**: Bridge the Gap
+
+In the era of AI-assisted development...
+
+[rest of content...]
+
+## AI Integration Migration
+
+**File Structure**:
+- `guide/ai-setup.mdx` (comprehensive setup guide)
+- `guide/ai-best-practices.mdx` (tips and patterns)
+- `guide/ai-examples.mdx` (real-world examples)
+
+**`guide/ai-setup.mdx` Structure**:
+
+Frontmatter:
+- id: 'ai-setup'
+- title: 'AI Integration Setup'
+- sidebar_position: 7
+
+Content sections:
+
+# AI Integration Setup
+
+LeanSpec is designed from the ground up to work seamlessly with AI coding agents.
+
+## Why AI Integration Matters
+
+[Content from ai-integration/index.mdx]
+
+## Integration Methods
+
+### 1. System Prompts (AGENTS.md)
+[Content from ai-integration/agents-md.mdx + setup.mdx]
+
+### 2. MCP Server
+[Brief intro, link to Reference for full API]
+
+### 3. Repository Context
+[Content from existing docs]
+
+## Setup Steps
+
+[Step-by-step setup from ai-integration/setup.mdx]
+
+## Troubleshooting
+
+[Common issues and solutions]
+
+## Next Steps
+
+- **[Best Practices](/docs/guide/ai-best-practices)** - Tips for effective AI integration
+- **[Examples](/docs/guide/ai-examples)** - Real-world workflows
+- **[MCP Server API](/docs/reference/mcp-server)** - Full MCP reference
+
+## MCP Server Reference
+
+**File**: `docs-site/docs/reference/mcp-server.mdx`
+
+**Content Source**: `docs/MCP-SERVER.md` (more comprehensive than current docs-site)
+
+**Structure**:
+
+Frontmatter:
+- id: 'mcp-server'
+- title: 'MCP Server API'
+- sidebar_position: 4
+
+Content sections:
+
+# MCP Server API
+
+Complete reference for the LeanSpec Model Context Protocol (MCP) server.
+
+## Overview
+
+[What is MCP, what does LeanSpec MCP provide]
+
+## Tools
+
+[Complete tool reference from docs/MCP-SERVER.md]
+
+## Resources
+
+[Resource reference]
+
+## Prompts
+
+[Prompt templates]
+
+## Configuration
+
+### VS Code (GitHub Copilot)
+[Detailed setup with examples]
+
+### Claude Desktop
+[Detailed setup with examples]
+
+### Other Clients
+[Generic setup instructions]
+
+## Troubleshooting
+
+[Comprehensive troubleshooting from docs/MCP-SERVER.md]
+
+## Security Considerations
+
+[Security notes from docs/MCP-SERVER.md]
+
+## API Details
+
+[Technical API details]
+
+## Workflow Section
+
+**New Files**:
+
+### 1. `guide/board-stats.mdx`
+
+Frontmatter:
+- id: 'board-stats'
+- title: 'Board & Stats'
+- sidebar_position: 11
+
+Content sections:
+
+# Board & Stats
+
+Project visibility and health monitoring with LeanSpec.
+
+## Board View
+
+The `lean-spec board` command provides a Kanban-style view of your specs:
+
+```bash
+lean-spec board
+```
+
+Shows specs organized by status:
+- **Planned**: Specs not yet started
+- **In Progress**: Active work
+- **Complete**: Finished specs
+- **Archived**: Historical specs
+
+**Use cases**:
+- Daily standup visibility
+- Sprint planning
+- Identifying bottlenecks
+- Team coordination
+
+## Stats
+
+The `lean-spec stats` command provides project metrics:
+
+```bash
+lean-spec stats
+```
+
+Shows:
+- Total specs by status
+- Completion rate
+- Average spec size
+- Distribution by priority/tags
+
+**Use cases**:
+- Project health checks
+- Identifying trends
+- Planning capacity
+- Reporting progress
+
+## Workflows
+
+### Daily Workflow
+1. Run `lean-spec board` to see current state
+2. Update spec status as you work
+3. Review stats weekly
+
+### Team Workflow
+1. Board in standup meetings
+2. Stats for retrospectives
+3. Track velocity over time
+
+## Tips
+
+- Update status early and often
+- Use stats to identify patterns
+- Archive completed work regularly
+
+### 2. `guide/dependencies.mdx`
+
+Frontmatter:
+- id: 'dependencies'
+- title: 'Dependencies'
+- sidebar_position: 12
+
+Content sections:
+
+# Dependencies
+
+Managing spec relationships and dependencies.
+
+## Understanding Relationships
+
+LeanSpec has two types of relationships:
+
+### `related` - Bidirectional Soft Reference
+
+**Meaning**: Informational relationship between specs (they're related/connected)
+
+**Behavior**: Automatically shown from both sides
+
+**Example**:
+```yaml
+# Spec 042
+related: [043]
+
+# Spec 043 doesn't need to list 042
+```
+
+Both specs will show the relationship.
+
+**Use when:**
+- Specs cover related topics
+- Work is coordinated but not blocking
+- Context is helpful but not required
+
+### `depends_on` - Directional Blocking Dependency
+
+**Meaning**: Hard dependency - spec cannot start until dependencies complete
+
+**Behavior**: Directional only
+
+**Example**:
+```yaml
+# Spec A
+depends_on: [spec-b]
+```
+
+**Use when:**
+- Spec truly cannot start until another completes
+- There's a clear dependency chain
+- Work must be done in specific order
+
+## Using deps Command
+
+View spec relationships:
+
+```bash
+lean-spec deps <spec>
+```
+
+Shows:
+- Dependencies (what this spec depends on)
+- Blocks (what this spec blocks)
+- Related specs
+
+## Best Practices
+
+1. **Use `related` by default** - It's simpler and matches most use cases
+2. **Reserve `depends_on` for true blocking dependencies**
+3. **Update once, show everywhere** - `related` only needs to be in one spec
+4. **Check dependencies** - Run `lean-spec deps` to see all relationships
+
+## Patterns
+
+### Feature Dependencies
+```yaml
+# Spec B depends on Spec A
+depends_on: [spec-a]
+```
+
+### Related Features
+```yaml
+# Both specs work on same area
+related: [other-spec]
+```
+
+### Complex Dependencies
+```yaml
+# Multiple dependencies
+depends_on: [spec-a, spec-b]
+related: [spec-c, spec-d]
+
+### 3. `guide/validation.mdx`
+
+Frontmatter:
+- id: 'validation'
+- title: 'Validation'
+- sidebar_position: 13
+
+Content sections:
+
+# Validation
+
+Quality checks and complexity analysis.
+
+## Validate Command
+
+Check specs for quality issues:
+
+```bash
+lean-spec validate
+```
+
+Validates all specs by default. Check specific specs:
+
+```bash
+lean-spec validate <spec-1> <spec-2>
+```
+
+## Quality Checks
+
+### Line Count
+- **Warning**: Specs over 300 lines
+- **Error**: Specs over 400 lines
+- **Rationale**: Context Economy principle
+
+### Sub-Spec Validation
+- Checks sub-spec files (DESIGN.md, etc.)
+- Ensures sub-specs also follow line limits
+
+### Frontmatter Validation
+- Required fields present
+- Valid values for status, priority
+- Proper date formats
+
+## Complexity Analysis
+
+Validation detects:
+- Overly long specs (Context Economy violation)
+- Missing required frontmatter
+- Invalid frontmatter values
+- Sub-specs that need splitting
+
+## Workflows
+
+### Pre-Commit Check
+```bash
+lean-spec validate
+```
+
+### CI/CD Integration
+```yaml
+# .github/workflows/validate.yml
+- name: Validate Specs
+  run: npx lean-spec validate
+```
+
+### Regular Review
+```bash
+# Weekly spec health check
+lean-spec validate --max-lines 300
+```
+
+## Best Practices
+
+1. **Validate early** - Before committing
+2. **Fix warnings** - Don't let them accumulate
+3. **Split when needed** - Use sub-specs at 400 lines
+4. **Automate** - Add to CI/CD pipeline
+
+## Tips
+
+- Use `--max-lines` to set custom thresholds
+- Validate after major changes
+- Keep specs under 300 lines ideally
+- Split complex specs using spec 012 pattern
+
+## Content Migration Checklist
+
+### From `docs/` to docs-site
+
+- [ ] Migrate `docs/MCP-SERVER.md` → `docs-site/docs/reference/mcp-server.mdx`
+  - [ ] Copy comprehensive setup instructions
+  - [ ] Copy troubleshooting section
+  - [ ] Copy security considerations
+  - [ ] Format for Docusaurus
+  - [ ] Test all code examples
+
+- [ ] Migrate `docs/MIGRATION.md` → `docs-site/docs/guide/migration.mdx`
+  - [ ] Copy migration guides
+  - [ ] Format for Docusaurus
+  - [ ] Add navigation links
+
+- [ ] Merge `docs/examples/CUSTOM-FIELDS-GUIDE.md` → `docs-site/docs/guide/custom-fields.mdx`
+  - [ ] Copy examples
+  - [ ] Copy config snippets
+  - [ ] Integrate with existing content
+
+- [ ] Deprecate `docs/` folder
+  - [ ] Create `docs/README.md` with redirect message
+  - [ ] Keep folder for backwards compatibility
+
+### Within docs-site
+
+- [ ] Move `ai-integration/index.mdx` → `guide/ai-setup.mdx`
+- [ ] Merge `ai-integration/setup.mdx` into `guide/ai-setup.mdx`
+- [ ] Move `ai-integration/best-practices.mdx` → `guide/ai-best-practices.mdx`
+- [ ] Move `ai-integration/examples.mdx` → `guide/ai-examples.mdx`
+- [ ] Incorporate `ai-integration/agents-md.mdx` into `guide/ai-setup.mdx`
+- [ ] Update all internal links (`/docs/ai-integration/` → `/docs/guide/`)
+- [ ] Delete `docs-site/docs/ai-integration/` directory
+
+## Link Update Strategy
+
+### Find and Replace
+
+```bash
+# Update all references
+grep -r "/docs/ai-integration/" docs-site/docs/
+# Replace with /docs/guide/
+```
+
+### Redirect Configuration
+
+Add to `docusaurus.config.ts`:
+
+```typescript
+plugins: [
+  [
+    '@docusaurus/plugin-client-redirects',
+    {
+      redirects: [
+        {
+          from: '/docs/ai-integration/setup',
+          to: '/docs/guide/ai-setup',
+        },
+        {
+          from: '/docs/ai-integration/best-practices',
+          to: '/docs/guide/ai-best-practices',
+        },
+        {
+          from: '/docs/ai-integration/examples',
+          to: '/docs/guide/ai-examples',
+        },
+        // Add more redirects as needed
+      ],
+    },
+  ],
+],
+```
+
+## Testing Checklist
+
+### Automated
+- [ ] Build completes without errors: `cd docs-site && npm run build`
+- [ ] No broken internal links
+- [ ] Search functionality works
+- [ ] All assets load correctly
+
+### Manual
+- [ ] Navigation flows logically
+- [ ] First Principles doc renders correctly
+- [ ] Philosophy shows derivation
+- [ ] AI setup is comprehensive
+- [ ] MCP reference is complete
+- [ ] Workflow docs are clear
+- [ ] All examples work
+- [ ] Mobile rendering correct
+- [ ] Desktop rendering correct
+
+### Content Quality
+- [ ] No spelling/grammar errors
+- [ ] Code examples tested
+- [ ] Links go to correct pages
+- [ ] Images/diagrams load
+- [ ] Formatting consistent