@every-env/cli

# feat: Implement Ink-based CLI Interface for Four-Step Engineering Workflow ## Overview Implement an ultra-minimal, keyboard-first CLI interface using Ink (React for CLIs) that brings the four-step compounding engineering process (Plan → Delegate → Assess → Codify) to life. This interface will transform Every-Env from a command-line tool into an interactive workflow management system that seamlessly orchestrates AI agents while maintaining visibility and control. ## Background & Motivation The current Every-Env CLI (`src/cli.ts`) operates through discrete commands that don't visualize the workflow progression. Users must manually track task states and manage the flow between planning, delegation, assessment, and codification phases. This new interface will: - Provide real-time visibility into the entire engineering workflow - Enable fluid navigation between phases with single keystrokes - Surface task progress and agent activity as it happens - Reduce cognitive load by organizing work into clear phases - Maintain the keyboard-first efficiency developers expect ## Technical Specification ### Core Architecture Changes 1. **New CLI Entry Point** - Create `src/cli-interactive.ts` as the new interactive interface - Maintain `src/cli.ts` for backward compatibility with `--classic` flag - Add `ink` and `ink-text-input` as dependencies 2. **State Management System** ```typescript // src/interactive/state/app-state.ts interface AppState { currentPhase: 1 | 2 | 3 | 4; selectedIndex: number | null; inputValue: string; inputMode: 'idle' | 'typing'; showHelp: boolean; showLogs: string | null; commandFeedback: string | null; tasks: { plan: Task[]; delegate: Task[]; assess: Task[]; codify: Task[]; }; } ``` 3. **Integration Points** - Connect to existing `AgentManager` (`src/core/agent-manager.ts:16`) for delegation - Leverage `CommandPatternExecutor` for plan execution - Store state in `.every-env/workflow-state.json` - Stream agent logs through existing `ProgressDisplay` infrastructure ### Implementation Phases #### Phase 1: Foundation (Week 1) - [ ] Set up Ink framework and TypeScript configuration - [ ] Create base component structure with state management - [ ] Implement keyboard navigation system - [ ] Add basic view rendering for all four phases - [ ] Create development mode with hot reload #### Phase 2: Core Functionality (Week 2) - [ ] Implement Plan view with task creation and management - [ ] Build Delegate view with real-time progress tracking - [ ] Create Assess view with review workflow - [ ] Add Codify view with pattern extraction - [ ] Connect to existing Every-Env command system #### Phase 3: Integration (Week 3) - [ ] Wire up agent execution through `ClaudeAgent` (`src/agents/claude-agent.ts`) - [ ] Implement log streaming and progress visualization - [ ] Add state persistence and recovery - [ ] Create transition animations between phases - [ ] Build error handling and recovery flows #### Phase 4: Polish & Testing (Week 4) - [ ] Add comprehensive keyboard shortcuts - [ ] Implement help system and onboarding - [ ] Create unit tests for all components - [ ] Add integration tests for workflow scenarios - [ ] Performance optimization and memory management ## Component Structure ``` src/interactive/ ├── components/ │ ├── App.tsx # Main application container │ ├── InputBar.tsx # Top input/command bar │ ├── PhaseNav.tsx # Phase navigation tabs │ ├── TaskList.tsx # Task display with selection │ ├── ActionBar.tsx # Context-aware action hints │ ├── ProgressBar.tsx # Visual progress indicator │ ├── LogsView.tsx # Streaming logs display │ └── HelpView.tsx # Interactive help overlay ├── hooks/ │ ├── useKeyboardNavigation.ts │ ├── useTaskManagement.ts │ └── useAgentExecution.ts ├── state/ │ ├── app-state.ts # State type definitions │ ├── state-manager.ts # State management logic │ └── persistence.ts # State save/load └── utils/ ├── keybindings.ts # Keyboard mapping └── formatters.ts # Display formatters ``` ## Key Features & Behaviors ### Navigation System - **Arrow Keys / j/k**: Navigate tasks within current phase - **Number Keys 1-4**: Instant phase jumping - **Letter Keys**: Context-aware actions (delegate, assess, etc.) - **Typing Detection**: Any unbound key starts text input - **Selection Wrapping**: Seamless top/bottom navigation ### Visual Feedback - **Selection Indicator**: Clear `▶` marker for current task - **Progress Bars**: Real-time delegation progress with `▓░` characters - **Status Icons**: `⚡` (active), `🔄` (running), `✓` (completed), `👀` (review) - **Color Coding**: Active elements in white, inactive in gray - **Command Feedback**: Transient messages for user actions ### State Persistence - Auto-save state to `.every-env/workflow-state.json` - Recover from crashes with task history intact - Sync with external Every-Env command executions - Watch for file system changes ## Success Metrics - **Performance**: Interface renders at 60fps with <50ms input latency - **Memory**: Stays under 100MB RAM with 1000+ tasks - **Reliability**: Zero data loss on process termination - **Usability**: New users productive within 5 minutes - **Integration**: Seamless interop with existing CLI commands ## Testing Requirements ### Unit Tests - Component rendering with various states - Keyboard navigation edge cases - State transitions and persistence - Task management operations ### Integration Tests - Full workflow scenarios (plan → delegate → assess → codify) - Agent execution and log streaming - Multi-phase task progression - Error recovery scenarios ### E2E Tests - Complete user journeys - Performance under load - Terminal compatibility (iTerm2, Terminal.app, VS Code) ## Dependencies & Risks ### New Dependencies - `ink@4.x` - React for CLIs - `ink-text-input@6.x` - Text input component - `@types/react` - TypeScript definitions ### Technical Risks - Terminal compatibility across different environments - Performance with large task lists - State synchronization with parallel operations - Memory leaks from event listeners ### Mitigation Strategies - Progressive enhancement with `--classic` fallback - Pagination for large task lists - Debounced state persistence - Careful event listener management ## Future Considerations ### Extensibility Points - Plugin system for custom views - Theming support for colors/icons - Export workflows to markdown - Integration with external task systems ### Potential Enhancements - Multi-agent view for parallel executions - Task dependencies and DAG visualization - Time tracking and analytics - Collaborative features for teams ## Acceptance Criteria - [ ] All four phase views render correctly with sample data - [ ] Keyboard navigation works as specified - [ ] Tasks persist across application restarts - [ ] Agent execution integrates with existing system - [ ] Performance meets specified metrics - [ ] Help system documents all features - [ ] Classic CLI mode remains functional - [ ] Tests achieve >90% coverage ## Implementation Notes ### File References - Current CLI: `src/cli.ts` - Agent Manager: `src/core/agent-manager.ts:16` - Claude Agent: `src/agents/claude-agent.ts` - Pattern Executor: `src/patterns/command-pattern-executor.ts` - Progress Display: `src/utils/progress-display.ts` ### Architecture Decisions - Use Ink's built-in state management vs Redux - Leverage existing `p-limit` for concurrency control - Reuse `LiquidEngine` for dynamic content - Maintain backward compatibility throughout ### Development Workflow 1. Create feature branch: `feat/ink-cli-interface` 2. Set up Ink in parallel with existing CLI 3. Develop behind `--interactive` flag 4. Gradually migrate features 5. Switch default behavior in major version ## Resources - [Ink Documentation](https://github.com/vadimdemedes/ink) - [React Hooks in Ink](https://github.com/vadimdemedes/ink#hooks) - [Terminal Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html) - Specification: `/Users/kieranklaassen/every-env/plans/every-env-cli-spec.md` --- **Labels**: `enhancement`, `feature`, `ui`, `high-priority` **Assignee**: TBD **Milestone**: v1.0.0 **Estimated Effort**: 4 weeks **Complexity**: High