@leanspec/ui 0.2.3 → 0.2.4-dev.20251118080109

package/dist/standalone/specs/archived/006-pm-visualization-tools/README.md

@@ -1,406 +0,0 @@
----
-status: complete
-created: '2025-11-01'
-tags:
-  - enhancement
-  - cli
-  - visualization
-  - pm-tools
-priority: medium
-depends_on:
-  - 20251101/002-structured-frontmatter
-completed: '2025-11-01'
----
-
-# pm-visualization-tools
-
-> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-01 · **Tags**: enhancement, cli, visualization, pm-tools
-
-
-## Overview
-
-Once specs have structured frontmatter (status, tags, priority, dependencies), we can build powerful PM/project visibility tools. These CLI commands transform LeanSpec from a simple spec tool into a lightweight project management system - all while staying file-first and lean.
-
-**Goal**: Give teams visibility into their work without requiring heavy PM tools like Jira or Linear. Everything stays in git, searchable and version-controlled.
-
-## Design
-
-### Commands Overview
-
-```bash
-lean-spec stats              # Quick summary stats
-lean-spec board              # Kanban view by status
-lean-spec timeline           # Creation/completion over time
-lean-spec gantt              # Timeline with dependencies
-lean-spec deps <spec>        # Dependency graph
-lean-spec search <query>     # Full-text + metadata search
-```
-
-### 1. `lean-spec stats`
-
-Show aggregate statistics across all specs.
-
-**Output:**
-```
-📊 Spec Statistics
-
-Status:
-  📅 Planned:      8
-  🚧 In Progress:  5
-  ✅ Complete:    12
-  📦 Archived:    23
-
-Priority:
-  🔴 High:         3
-  🟡 Medium:       7
-  🟢 Low:          3
-
-Tags (top 5):
-  feature:        11
-  api:             6
-  refactor:        4
-  breaking-change: 3
-  security:        2
-
-Total Specs: 48
-```
-
-**Options:**
-- `--tag=api` - Filter stats by tag
-- `--assignee=alice` - Filter by assignee
-- `--json` - Output as JSON for scripting
-
-### 2. `lean-spec board`
-
-Kanban-style board view grouped by status.
-
-**Output:**
-```
-📋 Spec Board
-
-┌─ 📅 Planned (8) ───────────────────────────────────────┐
-│ 20251101/003-pm-visualization-tools                     │
-│   tags: [enhancement, cli]  priority: medium            │
-│                                                          │
-│ 20251031/002-template-system-redesign                   │
-│   tags: [refactor]  priority: low                       │
-└──────────────────────────────────────────────────────────┘
-
-┌─ 🚧 In Progress (5) ───────────────────────────────────┐
-│ 20251101/002-structured-frontmatter                     │
-│   tags: [enhancement]  priority: high  assignee: alice  │
-│                                                          │
-│ 20251031/001-typescript-cli-migration                   │
-│   tags: [refactor]  priority: medium                    │
-└──────────────────────────────────────────────────────────┘
-
-┌─ ✅ Complete (12) ──────────────────────────────────────┐
-│ (collapsed, use --show-complete to expand)              │
-└──────────────────────────────────────────────────────────┘
-```
-
-**Options:**
-- `--show-complete` - Expand complete column
-- `--tag=api` - Filter by tag
-- `--assignee=alice` - Filter by assignee
-
-### 3. `lean-spec timeline`
-
-Visualize spec creation and completion over time.
-
-**Output:**
-```
-📈 Spec Timeline (Last 30 Days)
-
-2025-10-31 ████████ 8 created  ██ 2 completed
-2025-11-01 ███ 3 created  █████ 5 completed
-
-Created by Status:
-  Oct 2025: 15 specs
-  Nov 2025: 3 specs
-
-Completion Rate:
-  Last 7 days:  7 specs completed
-  Last 30 days: 18 specs completed
-```
-
-**Options:**
-- `--days=90` - Show last N days
-- `--by-tag` - Group by tag
-- `--by-assignee` - Group by assignee
-
-### 4. `lean-spec gantt`
-
-Timeline view with dependencies (requires `depends_on` and optional `due` dates).
-
-**Output:**
-```
-📅 Gantt Chart
-
-Nov 1    Nov 8    Nov 15   Nov 22
-|--------|--------|--------|--------|
-
-20251101/002-structured-frontmatter
-■■■■■■■■□□□□□□□□                   (in-progress, due: Nov 8)
-
-20251101/003-pm-visualization-tools
-        ↳ depends on 002
-        □□□□□□□□□□□□□□□□           (planned, due: Nov 22)
-
-20251031/001-typescript-cli-migration
-■■■■■■■■■■■■■■■■                   (complete)
-```
-
-**Options:**
-- `--weeks=8` - Show N weeks
-- `--show-complete` - Include completed specs
-- `--critical-path` - Highlight critical path
-
-### 5. `lean-spec deps <spec>`
-
-Show dependency graph for a specific spec.
-
-**Output:**
-```
-📦 Dependencies for 20251101/003-pm-visualization-tools
-
-Depends On:
-  → 20251101/002-structured-frontmatter [in-progress]
-
-Required By:
-  (none)
-
-Related:
-  ⟷ 20251031/001-typescript-cli-migration [complete]
-
-Dependency Chain:
-  003-pm-visualization-tools
-    └─ 002-structured-frontmatter
-         └─ 001-typescript-cli-migration ✓
-```
-
-**Options:**
-- `--depth=3` - Show N levels deep
-- `--graph` - ASCII graph visualization
-- `--json` - Output as JSON
-
-### 6. `lean-spec search <query>`
-
-Full-text search with metadata filters.
-
-**Output:**
-```bash
-$ lean-spec search "api" --status=planned --priority=high
-
-🔍 Found 2 specs matching "api"
-
-20251031/002-api-v2-migration
-  Status: planned  Priority: high  Tags: [api, breaking-change]
-  Match: "...redesign the API to support GraphQL..."
-
-20251101/004-api-authentication
-  Status: planned  Priority: high  Tags: [api, security]
-  Match: "...implement OAuth2 for API access..."
-```
-
-**Options:**
-- `--status=<status>` - Filter by status
-- `--tag=<tag>` - Filter by tag
-- `--priority=<priority>` - Filter by priority
-- `--assignee=<user>` - Filter by assignee
-
-### Implementation Notes
-
-**Tech Stack:**
-- `gray-matter` - Parse frontmatter
-- `chalk` - Colors (already used)
-- `ink` + `ink-box` - React-based TUI for interactive board
-- `ink-text-input` - Input component for search/filtering
-- `ink-select-input` - Selection component for navigation
-- `marked` or `markdown-it` - Extract text for search
-
-**Interactive vs Static Mode:**
-- Default commands output static text (fast, scriptable)
-- Add `--interactive` or `-i` flag for TUI mode
-- Example: `lean-spec board --interactive` launches Ink TUI
-
-**Performance:**
-- Cache parsed frontmatter to avoid re-reading files
-- For large repos (100+ specs), consider indexing
-- Lazy load spec content for search (frontmatter first)
-
-**Output Format:**
-- Default: colorful terminal output
-- `--interactive` / `-i`: Interactive TUI with Ink
-- `--json` flag for scripting/integration
-- `--markdown` flag for documentation
-
-## Plan
-
-- [ ] Implement `lean-spec stats` command
-- [ ] Implement `lean-spec board` command (static output)
-- [ ] Implement `lean-spec timeline` command
-- [ ] Implement `lean-spec deps` command with graph visualization
-- [ ] Implement `lean-spec gantt` command
-- [ ] Implement `lean-spec search` command with full-text + metadata
-- [ ] Add caching layer for better performance
-- [ ] Add `--json` and `--markdown` output formats
-- [ ] Implement interactive TUI mode with Ink
-  - [ ] Interactive board with keyboard navigation
-  - [ ] Real-time filtering and search
-  - [ ] Spec detail view
-  - [ ] Status update inline (move between columns)
-- [ ] Update documentation with examples
-
-## Test
-
-- [ ] `lean-spec stats` shows correct counts across all specs
-- [ ] `lean-spec board` groups specs by status correctly
-- [ ] `lean-spec timeline` aggregates by date accurately
-- [ ] `lean-spec deps` resolves dependency chains correctly
-- [ ] `lean-spec gantt` displays timeline with proper dependencies
-- [ ] `lean-spec search` finds specs by content and metadata
-- [ ] Commands work with 100+ specs (performance)
-- [ ] `--json` output is valid and parseable
-- [ ] Color output respects NO_COLOR environment variable
-- [ ] Gracefully handles specs without optional fields
-- [ ] Interactive mode (`--interactive`) launches TUI correctly
-- [ ] TUI keyboard navigation works (arrows, tab, enter)
-- [ ] TUI updates persist to files (status changes write to frontmatter)
-- [ ] TUI handles terminal resize gracefully
-
-## Notes
-
-### Why Build This?
-
-Many teams avoid heavy PM tools but still need visibility. By building on structured frontmatter, we can provide:
-- Zero-setup project visibility
-- Git-based, version-controlled work tracking
-- No external dependencies or SaaS subscriptions
-- Works offline, fast, no database needed
-
-### Progressive Enhancement
-
-Users can adopt these tools gradually:
-1. Start with basic `lean-spec list`
-2. Add frontmatter → unlock `lean-spec stats`
-3. Add dependencies → unlock `lean-spec deps` and `lean-spec gantt`
-4. Add due dates → unlock timeline planning
-
-### Inspiration
-
-- GitHub Projects (but file-based)
-- Linear (but without the database)
-- Taskwarrior (but for specs, not tasks)
-- Gitmoji/commitizen (structured data in git)
-- K9s (Kubernetes TUI) - great example of Ink power
-
-### Interactive TUI with Ink
-
-Build an interactive board using Ink (React for CLI):
-
-**Command:**
-```bash
-lean-spec board --interactive
-# or shorthand
-lean-spec board -i
-```
-
-**TUI Features:**
-
-```
-┌─ LeanSpec Board ─────────────────────────────────────────┐
-│ Filter: [api___] (type to filter) Press / to focus       │
-├──────────────────────────────────────────────────────────┤
-│                                                           │
-│ ┌─ 📅 Planned (3) ────────────────────────────────────┐ │
-│ │ › 003-pm-visualization-tools                         │ │
-│ │   tags: [enhancement, cli]  priority: medium         │ │
-│ │                                                       │ │
-│ │   002-api-redesign                                    │ │
-│ │   tags: [api, feature]  priority: high               │ │
-│ └───────────────────────────────────────────────────────┘ │
-│                                                           │
-│ ┌─ 🚧 In Progress (2) ────────────────────────────────┐ │
-│ │   002-structured-frontmatter                         │ │
-│ │   tags: [enhancement]  priority: high                │ │
-│ └───────────────────────────────────────────────────────┘ │
-│                                                           │
-└──────────────────────────────────────────────────────────┘
-│ ↑/↓: Navigate  →/←: Move Status  Enter: Details  q: Quit │
-```
-
-**Interactions:**
-- `↑/↓` or `j/k` - Navigate between specs
-- `→/←` or `l/h` - Move spec to next/prev status column
-- `Enter` - Open spec detail view (shows full Overview + Plan)
-- `/` - Focus search/filter input
-- `t` - Filter by tag (opens tag selector)
-- `p` - Filter by priority
-- `a` - Filter by assignee
-- `r` - Refresh data
-- `q` - Quit
-
-**Detail View:**
-```
-┌─ 20251101/003-pm-visualization-tools ────────────────────┐
-│ Status: planned                                           │
-│ Created: 2025-11-01                                       │
-│ Tags: enhancement, cli, visualization                     │
-│ Priority: medium                                          │
-│ Depends on: 002-structured-frontmatter                    │
-│                                                           │
-│ Overview:                                                 │
-│ Build powerful PM/project visibility tools...             │
-│                                                           │
-│ Plan:                                                     │
-│ ☐ Implement lean-spec stats command                          │
-│ ☐ Implement lean-spec board command                          │
-│ ...                                                       │
-└──────────────────────────────────────────────────────────┘
-│ s: Change Status  Esc: Back  e: Edit in $EDITOR          │
-```
-
-**Status Change:**
-- When moving spec with `→/←`, update frontmatter automatically
-- Also update `updated` timestamp
-- If moving to complete, set `completed` date
-
-**Implementation Structure:**
-
-```typescript
-// components/Board.tsx
-import React from 'react';
-import { Box, Text, useInput } from 'ink';
-
-export const Board = ({ specs, onStatusChange }) => {
-  // Kanban columns with keyboard navigation
-  // Use ink-select-input for selection
-};
-
-// components/SpecDetail.tsx
-export const SpecDetail = ({ spec }) => {
-  // Full spec view with metadata and content
-};
-
-// commands/board-interactive.ts
-import { render } from 'ink';
-import { Board } from '../components/Board';
-
-export const boardInteractive = async (options) => {
-  const specs = await loadSpecs();
-  render(<Board specs={specs} />);
-};
-```
-
-**Benefits:**
-- Fast, keyboard-driven workflow
-- No context switching (stay in terminal)
-- Real-time updates visible immediately
-- Git diffs show exactly what changed
-- Works over SSH (unlike web UIs)
-
-**Keep It Optional:**
-- Static output remains default (fast, scriptable)
-- Interactive mode is opt-in (`-i` flag)
-- Ink is optional dependency (peer dependency?)

package/dist/standalone/specs/archived/007-system-prompt-updates/README.md

@@ -1,168 +0,0 @@
----
-status: complete
-created: '2025-11-01'
-tags:
-  - documentation
-  - ai-agents
-  - templates
-priority: medium
-depends_on:
-  - 20251101/002-structured-frontmatter
-  - 20251101/003-pm-visualization-tools
-completed: '2025-11-01'
----
-
-# system-prompt-updates
-
-> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-01 · **Tags**: documentation, ai-agents, templates
-
-
-## Overview
-
-Once structured frontmatter and PM visualization tools are implemented, AI agents should know about them and use them effectively. We need to update `AGENTS.md` in all templates to guide agents on:
-
-1. **Using frontmatter** when creating/updating specs
-2. **Leveraging PM commands** for project context and discovery
-3. **Understanding spec status** before making changes
-
-This ensures AI agents become better teammates by using the full LeanSpec toolset.
-
-## Design
-
-### What to Add to AGENTS.md
-
-#### 1. Frontmatter Guidance
-
-Add section on using frontmatter when creating specs:
-
-**Minimal (solo developers):**
-- Just `status` and `created` fields
-
-**Standard (teams):**
-- Add `tags`, `priority`, `assignee`
-
-**Updating status:**
-- Use `lean-spec update` command or edit frontmatter directly
-
-#### 2. Discovery Commands
-
-Add section on discovery before starting work:
-- `lean-spec stats` - See work distribution
-- `lean-spec board` - View specs by status
-- `lean-spec list --tag=api` - Find relevant specs
-- `lean-spec search "topic"` - Full-text search
-- `lean-spec deps <spec>` - Check dependencies
-
-#### 3. Workflow Integration
-
-Add AI agent workflow section:
-1. Understand context (run stats/board/search)
-2. Check dependencies before starting
-3. Create or update spec with frontmatter
-4. Keep specs in sync with implementation
-5. Use interactive mode optionally
-
-#### 4. Template-Specific Guidance
-
-**For minimal template:**
-- Emphasize `status` and `created` only
-- Keep it simple, optional fields are truly optional
-
-**For standard template:**
-- Encourage `tags` and `priority`
-- Mention `assignee` for team coordination
-
-**For enterprise template:**
-- Full field usage with `issue`, `epic`, `reviewer`
-- Integration with external tools
-- Compliance tracking fields
-
-### Files to Update
-
-All template AGENTS.md files need updates:
-- `AGENTS.md` (root) - Update main file
-- `templates/minimal/files/AGENTS.md` - Minimal guidance
-- `templates/standard/files/AGENTS.md` - Standard guidance  
-- `templates/enterprise/files/AGENTS.md` - Full guidance
-
-### Key Additions to Each Template
-
-**All templates get:**
-- Discovery commands section (stats, board, search, deps)
-- Workflow integration steps
-- Frontmatter usage examples appropriate to template tier
-- Updated workflow that includes checking existing specs
-
-**Template-specific customization:**
-- Minimal: Focus on basics, minimal fields
-- Standard: Full workflow, team coordination
-- Enterprise: Advanced features, compliance, integrations
-
-## Plan
-
-- [ ] Update root `AGENTS.md` with frontmatter and PM commands
-- [ ] Update `templates/minimal/files/AGENTS.md` (minimal guidance)
-- [ ] Update `templates/standard/files/AGENTS.md` (standard guidance)
-- [ ] Update `templates/enterprise/files/AGENTS.md` (full guidance)
-- [ ] Add examples for each template tier
-- [ ] Create integration guide for popular AI coding tools (Cursor, GitHub Copilot, etc.)
-- [ ] Update README.md to reference updated agent instructions
-- [ ] Add troubleshooting section for common agent mistakes
-
-## Test
-
-- [ ] AI agents can parse and follow updated instructions
-- [ ] Template-specific guidance is appropriate for each tier
-- [ ] Examples are clear and actionable
-- [ ] Commands work as documented
-- [ ] Integration with popular AI tools (test with Cursor, Copilot)
-- [ ] Agents understand when to use specs vs skip them
-- [ ] Agents properly update frontmatter when working on specs
-- [ ] Documentation is discoverable (README points to AGENTS.md)
-
-## Notes
-
-### Why This Matters
-
-AI agents are powerful but need clear instructions. By updating system prompts with:
-- Structured frontmatter usage
-- Discovery commands for context
-- Clear workflow integration
-
-We turn AI agents into better teammates who:
-1. Understand project state before acting
-2. Keep specs in sync with implementation
-3. Use the full LeanSpec toolset effectively
-4. Follow team conventions consistently
-
-### Progressive Disclosure
-
-Match guidance to template complexity:
-- **Minimal**: Basic commands only, don't overwhelm
-- **Standard**: Full workflow, team coordination
-- **Enterprise**: Advanced features, compliance, integrations
-
-### AI Tool Integration
-
-Consider creating tool-specific guides:
-- **Cursor**: `.cursorrules` integration examples
-- **GitHub Copilot**: Workspace instructions format
-- **Cline/Aider**: Custom prompt patterns
-- **Continue**: Context provider setup
-
-### Testing with AI
-
-After updates, test with real AI coding assistants:
-1. Ask them to create a spec
-2. Check if they use frontmatter correctly
-3. Verify they run discovery commands
-4. Ensure they update status appropriately
-
-### Future: AI-Specific Commands
-
-Consider commands that help AI agents:
-```bash
-lean-spec context          # Output formatted for AI context
-lean-spec summary --ai     # AI-optimized summary format
-lean-spec related <topic>  # Find related specs for context
-```