@every-env/cli

# feat: Implement Every CLI interface for compounding engineering workflow ## Overview This issue proposes implementing a new CLI interface for the Every ecosystem that embodies the four-step compounding engineering process: Plan → Delegate → Assess → Codify. The interface will provide an intuitive, keyboard-driven workflow for managing the entire development lifecycle while maintaining the existing pattern-based agent system under the hood. ## Background & Motivation The current `every-env` CLI provides powerful agent orchestration capabilities but lacks a cohesive interface for the complete development workflow. While individual commands (`plan`, `docs`, `copy-commands`) work well in isolation, developers need a unified experience that guides them through the compounding engineering process naturally. ### Current State - Individual commands work independently (`every docs update`, `every plan`, etc.) - No unified workflow management or state tracking - Limited visibility into task progress and relationships - Manual coordination between workflow steps ### Desired State - Single entry point (`every`) that manages the complete workflow - Visual task tracking through all four phases - Seamless transitions between planning, execution, review, and learning - Persistent state management for long-running workflows ## Technical Specification ### Architecture Overview ``` ┌─────────────────────────────────────────────────────────────┐ │ CLI Interface Layer │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Ink React Components │ │ │ │ (InputBar, PhaseNav, TaskList, ActionBar) │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ State Management (AppState) │ │ │ │ (currentPhase, tasks, selections, input) │ │ │ └─────────────────────────────────────────────────────┘ │ └───────────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────────┴─────────────────────────────────┐ │ Command Execution Layer │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Workflow Commands (existing) │ │ │ │ (PlanCommand, DocsCommand, ReviewCommand, etc.) │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Pattern System (PatternManager, etc.) │ │ │ │ (Parallel execution, liquid templates, matching) │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### Core Components #### 1. CLI Entry Point (`src/cli-interface.ts`) ```typescript interface EveryCommand extends Command { name: 'every'; description: 'Unified interface for compounding engineering workflow'; options: { '--state-dir': 'Custom state directory (default: .every-env)'; '--debug': 'Enable debug logging'; }; } ``` #### 2. State Management (`src/cli/state/app-state.ts`) ```typescript interface AppState { currentPhase: 1 | 2 | 3 | 4; selectedIndex: number | null; inputValue: string; inputMode: 'idle' | 'typing'; tasks: { plan: Task[]; delegate: Task[]; assess: Task[]; codify: Task[]; }; } interface Task { id: string; title: string; status: TaskStatus; createdAt: Date; metadata: Record<string, any>; } ``` #### 3. UI Components (`src/cli/components/`) - **InputBar**: Command/search input with context-aware placeholders - **PhaseNav**: Visual navigation showing current phase - **TaskList**: Scrollable list with selection indicators - **ActionBar**: Context-sensitive keyboard shortcuts - **LogsView**: Real-time agent execution logs - **HelpView**: Interactive help overlay ### Implementation Plan #### Phase 1: Foundation (Week 1) 1. **Set up Ink CLI framework** - Install dependencies: `ink`, `ink-text-input`, `react` - Create basic app structure and entry point - Implement state management hooks 2. **Create core UI components** - Build reusable components for navigation - Implement keyboard handling system - Add basic styling and layout 3. **Integrate with existing state** - Read/write `.every-env/state.json` - Map existing workflow data to UI state - Ensure backward compatibility #### Phase 2: Workflow Integration (Week 2) 1. **Connect Plan phase** - Hook up to existing `plan` command - Display plans in UI with status tracking - Enable creation and editing 2. **Connect Delegate phase** - Integrate with agent execution system - Show real-time progress and logs - Handle long-running tasks gracefully 3. **Connect Assess phase** - Link to review functionality - Display review status and feedback - Enable workflow transitions 4. **Connect Codify phase** - Integrate with knowledge capture - Show learning history - Update CLAUDE.md programmatically #### Phase 3: Polish & Testing (Week 3) 1. **Enhanced interactions** - Add smooth transitions - Implement command feedback - Polish keyboard navigation 2. **Error handling** - Graceful degradation for missing tools - Clear error messages - Recovery mechanisms 3. **Testing & documentation** - Unit tests for components - Integration tests for workflows - User documentation ### File Structure ``` src/ ├── cli-interface.ts # New unified CLI entry point ├── cli/ │ ├── app.tsx # Main Ink app component │ ├── state/ │ │ ├── app-state.ts # State management │ │ ├── hooks.ts # React hooks │ │ └── persistence.ts # State file I/O │ ├── components/ │ │ ├── InputBar.tsx │ │ ├── PhaseNav.tsx │ │ ├── TaskList.tsx │ │ ├── ActionBar.tsx │ │ ├── LogsView.tsx │ │ └── HelpView.tsx │ ├── actions/ │ │ ├── plan.ts # Plan phase actions │ │ ├── delegate.ts # Delegate phase actions │ │ ├── assess.ts # Assess phase actions │ │ └── codify.ts # Codify phase actions │ └── utils/ │ ├── keyboard.ts # Key binding management │ └── formatting.ts # Text formatting helpers ``` ### Key Design Decisions 1. **Keyboard-first interaction** - All functionality accessible via keyboard - Vim-style navigation (j/k) alongside arrows - Smart typing detection for input mode 2. **Progressive disclosure** - Show only relevant actions per phase - Context-sensitive help - Clean, minimal interface 3. **Real-time updates** - Live progress tracking for running agents - Streaming logs for active tasks - External change detection 4. **Backward compatibility** - Works alongside existing CLI commands - Reads/writes same state format - No breaking changes to current workflows ### Dependencies **New dependencies:** - `ink` (^5.0.0) - React for CLIs - `ink-text-input` (^6.0.0) - Text input component - `react` (^18.0.0) - Already in package.json **Existing dependencies used:** - `commander` - For initial CLI setup - `chalk` - For additional styling - `ora` - For loading states ### Testing Strategy 1. **Component tests** - Test each UI component in isolation - Mock state and actions - Verify keyboard handling 2. **Integration tests** - Test complete workflows - Verify state persistence - Check command execution 3. **Manual testing checklist** - [ ] Create new plan via typing - [ ] Navigate with arrows and j/k - [ ] Execute all phase transitions - [ ] View logs during execution - [ ] Handle errors gracefully ### Success Metrics 1. **User experience** - Reduced time from idea to implementation - Increased visibility into workflow state - Smoother transitions between phases 2. **Technical quality** - 80%+ test coverage - No performance degradation - Clean, maintainable code 3. **Adoption** - Positive user feedback - Increased usage of full workflow - Reduced support questions ### Migration Path 1. **Soft launch** - Ship as `every` alongside existing commands - Allow gradual adoption - Gather feedback 2. **Documentation** - Update README with new workflow - Create video walkthrough - Add inline help 3. **Deprecation (future)** - Eventually consolidate commands - Maintain aliases for compatibility - Provide migration guide ### Open Questions 1. **State management library?** - Use React's built-in state/reducer - Consider Zustand for complex state - Evaluate based on complexity 2. **Multiple project support?** - How to switch between projects - State file organization - Project detection 3. **Plugin architecture?** - Allow custom phases/commands - Extension points - Configuration options ### References - [Ink Documentation](https://github.com/vadimdemedes/ink) - [Every-Env CLI Spec](/Users/kieranklaassen/every-env/plans/every-env-cli-spec.md) - [Existing Pattern System](/Users/kieranklaassen/every-env/src/patterns/pattern-manager.ts) - [Current CLI Implementation](/Users/kieranklaassen/every-env/src/cli.ts) ## Acceptance Criteria - [ ] `every` command launches interactive interface - [ ] All four phases (Plan/Delegate/Assess/Codify) are navigable - [ ] Tasks can be created, moved between phases, and completed - [ ] Keyboard navigation works smoothly - [ ] State persists between sessions - [ ] Existing commands continue to work - [ ] Documentation is updated - [ ] Tests provide adequate coverage ## Implementation Notes This is a significant enhancement that will make Every-Env more accessible and powerful. The implementation should be incremental, focusing on delivering value at each phase while maintaining the robustness of the existing system. The key is balancing simplicity with power - making the common workflows effortless while keeping advanced capabilities available for power users.