project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/008-terminal-dashboard/requirements.md

@@ -0,0 +1,222 @@
+# Intent: Terminal Dashboard
+
+## Overview
+
+Provide a terminal-based dashboard accessible via `npx @iris.md/irismd` that displays the current state of a irismd project folder, including installed flows, memory bank status, active bolts, intent progress, and more.
+
+---
+
+## Research Summary
+
+### Terminal UI Libraries Evaluated
+
+| Library | Type | Pros | Cons | Recommendation |
+|---------|------|------|------|----------------|
+| **Ink** | React-based | Modern, familiar React patterns, TypeScript support, actively maintained | Requires React knowledge, Yoga layout engine | **Recommended** |
+| **Blessed** | Curses-like | Feature-rich, extensive widgets, large ecosystem | Unmaintained, older API | Not recommended |
+| **react-blessed** | React + Blessed | React DX with Blessed widgets | Depends on unmaintained Blessed | Not recommended |
+| **Chalk + raw** | Manual | Minimal dependencies, full control | Complex layout management | For simple output only |
+
+### Recommended Approach: Ink
+
+Ink is the recommended choice because:
+
+- React component model is familiar to most developers
+- Flexbox layout via Yoga makes complex dashboards manageable
+- Actively maintained with good TypeScript support
+- Used by Shopify CLI, Blitz, and other production CLIs
+- Easy to build interactive elements (navigation, input)
+
+---
+
+## Problem Statement
+
+Currently, users have no quick way to understand the state of their irismd project:
+
+- What flow is installed?
+- Which tools are configured?
+- How many intents exist and their status?
+- What bolts are active or completed?
+- Is the memory bank properly initialized?
+
+Users must manually inspect YAML files and folder structures to understand project state.
+
+---
+
+## Functional Requirements
+
+### FR-1: Project Detection
+
+- FR-1.1: System SHALL detect if current directory is a irismd project (has `.irismd/manifest.yaml`)
+- FR-1.2: System SHALL display helpful message if not in a irismd project
+- FR-1.3: System SHALL read flow type and version from manifest
+- FR-1.4: System SHALL detect configured tools from manifest
+
+### FR-2: Memory Bank Status
+
+- FR-2.1: System SHALL display memory bank initialization status
+- FR-2.2: System SHALL count and display number of intents
+- FR-2.3: System SHALL count and display number of units (across all intents)
+- FR-2.4: System SHALL count and display number of stories
+- FR-2.5: System SHALL display story-index mode (single-file, per-intent, etc.)
+
+### FR-3: Intent Summary
+
+- FR-3.1: System SHALL list all intents with their names and status
+- FR-3.2: System SHALL indicate which intent is currently active (if any)
+- FR-3.3: System SHALL show unit count per intent
+- FR-3.4: System SHALL show story count per intent
+
+### FR-4: Bolt Status
+
+- FR-4.1: System SHALL count and display total bolts
+- FR-4.2: System SHALL count bolts by status (planned, active, completed, failed)
+- FR-4.3: System SHALL display currently active bolt (if any)
+- FR-4.4: System SHALL show bolt stage progress for active bolt
+
+### FR-5: Standards Status
+
+- FR-5.1: System SHALL indicate if standards are defined
+- FR-5.2: System SHALL list defined standard categories (tech-stack, architecture, etc.)
+
+### FR-6: Interactive Navigation (Phase 2)
+
+- FR-6.1: System SHALL support keyboard navigation between sections
+- FR-6.2: System SHALL support drilling down into intent details
+- FR-6.3: System SHALL support viewing bolt details
+- FR-6.4: System SHALL support quick actions (e.g., start new bolt)
+
+### FR-7: Quick Info Mode
+
+- FR-7.1: System SHALL support `--json` flag for machine-readable output
+- FR-7.2: System SHALL support `--compact` flag for minimal output
+- FR-7.3: System SHALL exit cleanly on `q` or `Ctrl+C`
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Performance
+
+- Dashboard SHALL render initial view in under 500ms
+- File scanning SHALL be lazy/incremental where possible
+- Memory usage SHALL stay under 50MB
+
+### NFR-2: Compatibility
+
+- Dashboard SHALL work on macOS, Linux, and Windows terminals
+- Dashboard SHALL handle narrow terminal widths gracefully (min 80 columns)
+- Dashboard SHALL use ASCII fallbacks when Unicode not supported
+
+### NFR-3: User Experience
+
+- Dashboard SHALL use colors consistent with iris.md branding
+- Dashboard SHALL be readable in both light and dark terminal themes
+- Dashboard SHALL provide clear visual hierarchy
+
+### NFR-4: Accessibility
+
+- Dashboard SHALL work without colors (via `--no-color` flag or `NO_COLOR` env)
+- Dashboard SHALL be navigable via keyboard only
+
+---
+
+## Command Interface
+
+```bash
+# Main dashboard (interactive)
+npx @iris.md/irismd
+
+# JSON output (for scripting)
+npx @iris.md/irismd --json
+
+# Compact output (quick glance)
+npx @iris.md/irismd --compact
+
+# Specific section only
+npx @iris.md/irismd --section=intents
+npx @iris.md/irismd --section=bolts
+npx @iris.md/irismd --section=standards
+```
+
+---
+
+## Dashboard Layout (ASCII Mockup)
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│  iris.md - Project Dashboard                          v0.2.55  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Flow: aidlc (AI Development Lifecycle)                         │
+│  Tools: claude, cursor, copilot, antigravity, windsurf          │
+│                                                                 │
+├───────────────────────────┬─────────────────────────────────────┤
+│  Memory Bank              │  Active Bolt                        │
+│  ─────────────────────    │  ─────────────────────              │
+│  Intents:     4           │  bolt-auth-service-1                │
+│  Units:      12           │  Stage: 2/4 (Technical Design)      │
+│  Stories:   28            │  Started: 2h ago                    │
+│  Standards: yes           │  Unit: auth-service                 │
+│                           │                                     │
+├───────────────────────────┴─────────────────────────────────────┤
+│  Intents                                                        │
+│  ─────────────────────────────────────────────                  │
+│  001-user-authentication     [3 units, 8 stories]  ▶ Active     │
+│  002-product-catalog         [4 units, 10 stories]              │
+│  003-shopping-cart           [3 units, 6 stories]               │
+│  004-checkout-flow           [2 units, 4 stories]               │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│  [i]ntents  [b]olts  [s]tandards  [q]uit                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Success Criteria
+
+- Users can understand project state at a glance
+- Dashboard loads in under 500ms
+- Works across all major platforms
+- Positive user feedback on usability
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Project Detection
+
+- GIVEN a directory with `.irismd/manifest.yaml`
+- WHEN user runs `npx @iris.md/irismd`
+- THEN dashboard displays with project information
+
+### AC-2: Non-Project Directory
+
+- GIVEN a directory without `.irismd/manifest.yaml`
+- WHEN user runs `npx @iris.md/irismd`
+- THEN helpful message is shown with installation instructions
+
+### AC-3: Memory Bank Stats
+
+- GIVEN a project with 3 intents and 10 units
+- WHEN dashboard loads
+- THEN correct counts are displayed
+
+### AC-4: Active Bolt Display
+
+- GIVEN an active bolt in stage 2
+- WHEN dashboard loads
+- THEN active bolt section shows bolt name, stage, and progress
+
+### AC-5: JSON Output
+
+- GIVEN `--json` flag is passed
+- WHEN dashboard runs
+- THEN valid JSON is output to stdout (no interactive UI)
+
+### AC-6: Graceful Exit
+
+- GIVEN interactive dashboard is running
+- WHEN user presses `q` or `Ctrl+C`
+- THEN dashboard exits cleanly with no error

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/008-terminal-dashboard/system-context.md

@@ -0,0 +1,198 @@
+# System Context: Terminal Dashboard
+
+## Boundaries
+
+### In Scope
+
+- Terminal UI rendering and layout
+- Project state detection and reading
+- Memory bank file parsing
+- Interactive navigation
+- Multiple output formats (interactive, JSON, compact)
+
+### Out of Scope
+
+- Modifying project state (read-only dashboard)
+- Remote data fetching (local files only)
+- Agent execution (just displays state)
+- Installation of flows (separate installer concern)
+
+---
+
+## Actors
+
+### Primary Actors
+
+#### AI-Native Engineer (End User)
+
+- Runs dashboard to understand project state
+- Navigates between sections to find information
+- Uses JSON output for scripting/automation
+
+#### CI/CD Pipeline
+
+- Uses `--json` output for automated checks
+- Validates project state before deployments
+
+### System Actors
+
+#### File System
+
+- Provides manifest, memory bank, and project files
+- Source of truth for all dashboard data
+
+---
+
+## External Systems
+
+### Local File System
+
+- **Interface**: Node.js `fs` module
+- **Data Exchange**: Read manifest.yaml, memory-bank files, intent/unit/story files
+- **Dependency**: Required - dashboard is read-only viewer
+
+### Terminal Emulator
+
+- **Interface**: stdout/stdin
+- **Data Exchange**: Render UI, receive keyboard input
+- **Dependency**: Required - user interaction channel
+
+---
+
+## Integration Points
+
+### Dashboard ↔ File System
+
+```text
+Dashboard starts
+  → Check for .irismd/manifest.yaml
+  → Parse manifest for flow/tools
+  → Scan memory-bank/ directory
+  → Count intents, units, stories
+  → Find active bolt
+  → Render dashboard
+```
+
+### Dashboard ↔ User
+
+```text
+User presses key
+  → Dashboard handles input
+  → Updates view if navigation key
+  → Exits if quit key
+```
+
+---
+
+## Context Diagram
+
+```text
+                    ┌─────────────────────┐
+                    │   AI-Native Engineer │
+                    └──────────┬──────────┘
+                               │ runs npx command
+                               ▼
+                    ┌──────────────────────┐
+                    │   Terminal Dashboard  │
+                    │                       │
+                    │  ┌─────────────────┐  │
+                    │  │ Project Detect  │  │
+                    │  ├─────────────────┤  │
+                    │  │ State Scanner   │  │
+                    │  ├─────────────────┤  │
+                    │  │ UI Renderer     │  │
+                    │  ├─────────────────┤  │
+                    │  │ Input Handler   │  │
+                    │  └─────────────────┘  │
+                    └──────────┬──────────┘
+                               │
+         ┌─────────────────────┼─────────────────────┐
+         │                     │                     │
+         ▼                     ▼                     ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│  .irismd/      │  │  memory-bank/   │  │  Terminal       │
+│  manifest.yaml  │  │                 │  │  (stdout/stdin) │
+│                 │  │  intents/       │  │                 │
+│  - flow         │  │  bolts/         │  │  - render UI    │
+│  - tools        │  │  standards/     │  │  - keyboard in  │
+│  - version      │  │                 │  │                 │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+```
+
+---
+
+## Data Flow
+
+### Interactive Mode
+
+```text
+1. User runs: npx @iris.md/irismd
+2. CLI checks for .irismd/manifest.yaml
+3. If not found: show "Not a irismd project" message and exit
+4. If found: parse manifest
+5. Scan memory-bank/ for intents, units, stories
+6. Scan bolts/ for bolt status
+7. Check standards/ for defined standards
+8. Render initial dashboard view
+9. Enter input loop:
+   - Wait for keypress
+   - Handle navigation (i, b, s keys)
+   - Handle quit (q, Ctrl+C)
+10. On quit: clear screen, exit cleanly
+```
+
+### JSON Mode
+
+```text
+1. User runs: npx @iris.md/irismd --json
+2. Perform same scanning as interactive mode
+3. Build JSON object with all data
+4. Output JSON to stdout
+5. Exit immediately (no input loop)
+```
+
+---
+
+## Constraints
+
+### Technical Constraints
+
+- Must work in terminals without Unicode support (ASCII fallback)
+- Must handle narrow terminals (min 80 columns)
+- Must work without color support
+- Memory scanning must be efficient for large projects
+
+### Platform Constraints
+
+- Must work on macOS, Linux, Windows
+- Must handle different path separators
+- Must handle case-sensitive and case-insensitive file systems
+
+### Performance Constraints
+
+- Initial render under 500ms
+- Memory under 50MB
+- Responsive to keyboard input (<100ms)
+
+---
+
+## Quality Attributes
+
+### Usability
+
+- Clear visual hierarchy
+- Obvious navigation affordances
+- Helpful empty states
+- Consistent key bindings
+
+### Reliability
+
+- Never crash on malformed files
+- Graceful handling of missing data
+- Clean exit on interrupt signals
+
+### Performance
+
+- Fast initial load
+- Lazy loading for deep data
+- Efficient file scanning

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/008-terminal-dashboard/units.md

@@ -0,0 +1,275 @@
+# Units: Terminal Dashboard
+
+## Unit Breakdown
+
+| Unit | Description | Priority | Dependencies |
+|------|-------------|----------|--------------|
+| **project-scanner** | Detects and reads irismd project state | High | None |
+| **dashboard-renderer** | Renders terminal UI using Ink | High | project-scanner |
+| **navigation-handler** | Handles keyboard input and navigation | Medium | dashboard-renderer |
+| **output-formatter** | Provides JSON and compact output modes | Medium | project-scanner |
+
+---
+
+## Unit 1: project-scanner
+
+### Responsibility
+
+Detect irismd project, read manifest, and scan memory bank to build a complete project state object.
+
+### Stories
+
+1. As a dashboard, I need to detect if cwd has `.irismd/manifest.yaml`
+2. As a dashboard, I need to parse manifest for flow, version, and tools
+3. As a dashboard, I need to count intents in `memory-bank/intents/`
+4. As a dashboard, I need to count units per intent
+5. As a dashboard, I need to count stories per unit
+6. As a dashboard, I need to find and parse active bolt (if any)
+7. As a dashboard, I need to list all bolts with their status
+8. As a dashboard, I need to detect defined standards
+9. As a dashboard, I need to handle missing/malformed files gracefully
+
+### Key Interfaces
+
+```typescript
+interface ProjectScanner {
+  isValidProject(dir: string): Promise<boolean>;
+  scanProject(dir: string): Promise<ProjectState>;
+}
+
+interface ProjectState {
+  isValid: boolean;
+  manifest: {
+    flow: string;
+    version: string;
+    tools: string[];
+    installedAt: string;
+  } | null;
+  memoryBank: {
+    intents: IntentSummary[];
+    totalUnits: number;
+    totalStories: number;
+  };
+  bolts: {
+    total: number;
+    active: BoltSummary | null;
+    byStatus: Record<BoltStatus, number>;
+  };
+  standards: {
+    defined: boolean;
+    categories: string[];
+  };
+}
+
+interface IntentSummary {
+  name: string;
+  unitCount: number;
+  storyCount: number;
+  isActive: boolean;
+}
+
+interface BoltSummary {
+  id: string;
+  unit: string;
+  status: BoltStatus;
+  stage: number;
+  totalStages: number;
+  startedAt: string;
+}
+
+type BoltStatus = 'planned' | 'active' | 'completed' | 'failed';
+```
+
+### Acceptance Criteria
+
+- Correctly detects valid irismd projects
+- Parses manifest without errors
+- Counts all memory bank entities accurately
+- Handles missing directories gracefully
+- Returns null/empty values (not errors) for missing data
+
+---
+
+## Unit 2: dashboard-renderer
+
+### Responsibility
+
+Render the terminal dashboard UI using Ink (React for CLI). Display project state in a clear, visually appealing layout.
+
+### Stories
+
+1. As a dashboard, I need to render header with iris.md branding and version
+2. As a dashboard, I need to render flow and tools information
+3. As a dashboard, I need to render memory bank statistics panel
+4. As a dashboard, I need to render active bolt panel (or "No active bolt")
+5. As a dashboard, I need to render intent list with counts
+6. As a dashboard, I need to render navigation footer with key hints
+7. As a dashboard, I need to show helpful message if not a irismd project
+8. As a dashboard, I need to handle narrow terminal widths
+9. As a dashboard, I need to support color themes (light/dark)
+10. As a dashboard, I need to support ASCII-only mode
+
+### Key Interfaces
+
+```typescript
+// React/Ink components
+interface DashboardProps {
+  state: ProjectState;
+  onQuit: () => void;
+}
+
+interface HeaderProps {
+  flow: string;
+  version: string;
+}
+
+interface MemoryBankPanelProps {
+  intents: number;
+  units: number;
+  stories: number;
+  hasStandards: boolean;
+}
+
+interface ActiveBoltPanelProps {
+  bolt: BoltSummary | null;
+}
+
+interface IntentListProps {
+  intents: IntentSummary[];
+}
+
+interface FooterProps {
+  keys: KeyHint[];
+}
+```
+
+### Acceptance Criteria
+
+- Dashboard renders without flicker
+- Layout adapts to terminal width
+- Colors are readable in both themes
+- ASCII fallback works when Unicode unavailable
+- Empty states are helpful, not confusing
+
+---
+
+## Unit 3: navigation-handler
+
+### Responsibility
+
+Handle keyboard input for interactive navigation between dashboard sections and views.
+
+### Stories
+
+1. As a user, I need to press `i` to focus on intents section
+2. As a user, I need to press `b` to focus on bolts section
+3. As a user, I need to press `s` to focus on standards section
+4. As a user, I need to press `q` to quit the dashboard
+5. As a user, I need to press `Ctrl+C` to quit the dashboard
+6. As a user, I need to press `Enter` to drill down into selected item
+7. As a user, I need to press `Esc` to go back to overview
+8. As a user, I need arrow keys to navigate within a section
+
+### Key Interfaces
+
+```typescript
+interface NavigationHandler {
+  currentSection: 'overview' | 'intents' | 'bolts' | 'standards';
+  selectedIndex: number;
+  handleKey(key: Key): NavigationAction;
+}
+
+type NavigationAction =
+  | { type: 'navigate'; section: string }
+  | { type: 'select'; index: number }
+  | { type: 'drilldown'; id: string }
+  | { type: 'back' }
+  | { type: 'quit' };
+```
+
+### Acceptance Criteria
+
+- All documented keys work as expected
+- Navigation state updates immediately
+- Visual feedback on key press
+- No input lag
+
+---
+
+## Unit 4: output-formatter
+
+### Responsibility
+
+Provide alternative output formats for non-interactive use cases (JSON, compact).
+
+### Stories
+
+1. As a user, I need `--json` to output project state as JSON
+2. As a user, I need `--compact` to output minimal one-line summary
+3. As a user, I need `--section=X` to output only a specific section
+4. As a CI pipeline, I need JSON output for automated checks
+5. As a script, I need non-zero exit code if not a irismd project
+
+### Key Interfaces
+
+```typescript
+interface OutputFormatter {
+  formatJson(state: ProjectState): string;
+  formatCompact(state: ProjectState): string;
+  formatSection(state: ProjectState, section: string): string;
+}
+
+// Compact format example:
+// "irismd aidlc v0.2.55 | 4 intents, 12 units, 28 stories | bolt-auth-1 active"
+
+// JSON format: full ProjectState object
+```
+
+### Acceptance Criteria
+
+- JSON is valid and parseable
+- Compact output fits in 80 columns
+- Section filter works for all sections
+- Exit code 1 if not a irismd project
+
+---
+
+## Dependency Graph
+
+```text
+┌─────────────────┐
+│ project-scanner │ ← Scans project state
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │         │
+    ▼         ▼
+┌───────────────────┐  ┌──────────────────┐
+│ dashboard-renderer│  │ output-formatter │
+└────────┬──────────┘  └──────────────────┘
+         │
+         ▼
+┌────────────────────┐
+│ navigation-handler │
+└────────────────────┘
+```
+
+---
+
+## Implementation Priority
+
+1. **Phase 1**: project-scanner + output-formatter (enable `--json` and `--compact` first)
+2. **Phase 2**: dashboard-renderer (basic UI without navigation)
+3. **Phase 3**: navigation-handler (full interactive experience)
+
+---
+
+## Technology Stack
+
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| **CLI Framework** | Commander.js | Already used in irismd |
+| **Terminal UI** | Ink (React) | Modern, maintained, Flexbox layout |
+| **YAML Parsing** | js-yaml | Already used in irismd |
+| **File System** | Node.js fs/promises | Built-in, async |
+| **Testing** | Vitest + ink-testing-library | Unit + component tests |