ralph.rb 1.2.4355354345 → 2.0.0

data/plans/02-loop-implementation.md

@@ -0,0 +1,78 @@
+# Ralph.rb Core Loop Implementation Plan
+
+This plan outlines the phased implementation of the core iteration loop based on the Loop specification in `specs/loop.md`.
+
+## Phase 1: Basic Loop Architecture
+- [ ] Create `Loop` class with basic initialization
+- [ ] Implement main infinite loop structure with proper termination conditions
+- [ ] Create `Iteration` class for individual execution cycles
+- [ ] Set up iteration cancellation mechanism (context/time guards)
+- [ ] Implement basic loop state management (iterations counter, timer)
+
+## Phase 2: Iteration Management
+- [ ] Implement iteration creation and execution workflow
+- [ ] Add iteration cancellation based on context length monitoring
+- [ ] Implement iteration cancellation based on duration limits
+- [ ] Create iteration state tracking (running, completed, cancelled)
+- [ ] Add iteration result collection and preservation
+
+## Phase 3: Context and Guard Implementation
+- [ ] Integrate with Metrics component for real-time context monitoring
+- [ ] Implement context size threshold checking and iteration restart
+- [ ] Add iteration duration monitoring and cancellation
+- [ ] Create context preservation between iterations (task list continuity)
+- [ ] Implement task list passing and reminder system
+
+## Phase 4: Termination Conditions
+- [ ] Implement completion string detection from agent output
+- [ ] Add maximum iteration count enforcement
+- [ ] Implement overall loop duration limits
+- [ ] Create graceful termination and cleanup procedures
+- [ ] Add termination reason reporting and statistics
+
+## Phase 5: Agent Integration
+- [ ] Create interface to Opencode agent execution
+- [ ] Implement prompt construction with task list and instructions
+- [ ] Add agent output processing and completion string detection
+- [ ] Integrate with Agents component for configuration and execution
+- [ ] Handle agent errors and communication failures
+
+## Phase 6: Display and Monitoring
+- [ ] Implement real-time iteration counter display
+- [ ] Add current iteration status indicator
+- [ ] Create duration display (current and total)
+- [ ] Implement token consumption display (per iteration and total)
+- [ ] Show agent output in real-time
+- [ ] Display input prompt for reference
+
+## Phase 7: Prompt Engineering
+- [ ] Create base prompt template explaining completion requirements
+- [ ] Add explicit instruction to avoid user interaction
+- [ ] Implement task list integration into prompts
+- [ ] Add context preservation instructions
+- [ ] Create prompt variation for different iteration states
+
+## Phase 8: Error Handling and Recovery
+- [ ] Implement iteration failure recovery mechanisms
+- [ ] Add context corruption detection and handling
+- [ ] Create agent communication error recovery
+- [ ] Implement graceful degradation on partial failures
+- [ ] Add comprehensive logging for debugging
+
+## Verification Criteria
+- [ ] Loop runs continuously until completion conditions met
+- [ ] Iterations cancel properly when context limits exceeded
+- [ ] Task continuity maintained across iteration restarts
+- [ ] Completion string detection works reliably
+- [ ] All termination conditions function correctly
+- [ ] Real-time monitoring displays accurate information
+- [ ] Agent integration works seamlessly
+- [ ] Error recovery prevents data loss
+- [ ] No Ruby style violations (run `bin/rubocop`)
+- [ ] All tests pass (run `bin/test`)
+
+## Dependencies
+- Requires Metrics component for context monitoring
+- Requires Agents component for agent execution
+- Requires prompt templates and task list system
+- Depends on JSON stream parsing from Metrics

data/plans/03-agents-implementation.md

@@ -0,0 +1,76 @@
+# Ralph.rb Agents Integration Implementation Plan
+
+This plan outlines the phased implementation of agent integration with opencode based on the Agents specification in `specs/agents.md`.
+
+## Phase 1: Opencode Command Wrapper
+- [ ] Create `Opencode` class for CLI interaction
+- [ ] Implement basic command construction and execution
+- [ ] Add subprocess management with proper error handling
+- [ ] Implement JSON stream format specification (`--format json`)
+- [ ] Create configuration management for opencode options
+
+## Phase 2: Configuration and Options
+- [ ] Implement `--model` option handling and validation
+- [ ] Add `--agent` option support for agent selection
+- [ ] Create prompt passing mechanism (`--prompt` or direct argument)
+- [ ] Implement JSON stream format enforcement
+- [ ] Add opencode command path resolution and validation
+
+## Phase 3: Process Management
+- [ ] Implement subprocess spawning with stdin/stdout handling
+- [ ] Create process monitoring and timeout management
+- [ ] Add signal handling for graceful termination
+- [ ] Implement process cleanup and resource management
+- [ ] Create error handling for opencode execution failures
+
+## Phase 4: JSON Stream Processing
+- [ ] Create JSON stream reader for opencode output
+- [ ] Implement line-by-line JSON parsing with error recovery
+- [ ] Add event filtering and routing to Metrics component
+- [ ] Create buffer management for high-volume output
+- [ ] Implement stream error detection and handling
+
+## Phase 5: Event Integration
+- [ ] Create event forwarding mechanism to Metrics component
+- [ ] Implement event type mapping and transformation
+- [ ] Add event timestamp and session ID handling
+- [ ] Create event aggregation for step_finish events
+- [ ] Implement real-time event processing capabilities
+
+## Phase 6: Agent Lifecycle Management
+- [ ] Implement agent startup and initialization procedures
+- [ ] Add agent state tracking (running, completed, failed)
+- [ ] Create agent termination and cleanup processes
+- [ ] Implement agent restart capabilities for failed iterations
+- [ ] Add agent configuration validation
+
+## Phase 7: Communication Layer
+- [ ] Create bidirectional communication interface
+- [ ] Implement prompt delivery to agent process
+- [ ] Add response collection and buffering
+- [ ] Create interrupt mechanism for iteration cancellation
+- [ ] Implement status reporting and health checks
+
+## Phase 8: Error Handling and Diagnostics
+- [ ] Implement opencode command not found handling
+- [ ] Add authentication and configuration error detection
+- [ ] Create network connectivity error handling
+- [ ] Implement JSON parsing error recovery
+- [ ] Add comprehensive logging and debugging capabilities
+
+## Verification Criteria
+- [ ] Opencode CLI commands execute correctly with all options
+- [ ] JSON stream output is parsed reliably
+- [ ] All required events are captured and forwarded
+- [ ] Agent process management is robust
+- [ ] Error handling covers all failure modes
+- [ ] Communication with Metrics component works
+- [ ] Agent lifecycle is managed properly
+- [ ] No Ruby style violations (run `bin/rubocop`)
+- [ ] All tests pass (run `bin/test`)
+
+## Dependencies
+- Requires Metrics component for event processing
+- Requires Loop component for agent lifecycle management
+- Requires opencode CLI to be installed and available
+- Depends on proper JSON stream format from opencode

data/plans/04-metrics-implementation.md

@@ -0,0 +1,98 @@
+# Ralph.rb Metrics Calculation Implementation Plan
+
+This plan outlines the phased implementation of context and token usage metrics based on the Metrics specification in `specs/metrics.md`.
+
+## Phase 1: Event Parsing Infrastructure
+- [ ] Create `Events` module with event class definitions
+- [ ] Implement JSON stream parsing for opencode events
+- [ ] Create `StepFinishEvent` class for token tracking
+- [ ] Add `StepStartEvent` class for iteration tracking
+- [ ] Implement `ToolUseEvent` class for tool execution tracking
+
+## Phase 2: Token Calculation Logic
+- [ ] Implement context calculation formula: `input + cache.read + cache.write`
+- [ ] Create token aggregation methods for each step
+- [ ] Add cumulative token tracking across iterations
+- [ ] Implement per-iteration token difference calculation
+- [ ] Create token rate calculation (tokens per second)
+
+## Phase 3: Event Stream Processing
+- [ ] Create `MetricsCollector` class for real-time processing
+- [ ] Implement line-by-line JSON stream consumption
+- [ ] Add event type detection and routing
+- [ ] Create event state tracking (current step, session ID)
+- [ ] Implement buffer management for partial JSON lines
+
+## Phase 4: Context Monitoring
+- [ ] Implement real-time context size tracking
+- [ ] Create context threshold alerting system
+- [ ] Add context growth trend analysis
+- [ ] Implement context usage percentage calculation
+- [ ] Create context projection for upcoming steps
+
+## Phase 5: Metrics Storage and Retrieval
+- [ ] Create metrics data structures for current and historical data
+- [ ] Implement iteration-level metrics storage
+- [ ] Add session-level metrics aggregation
+- [ ] Create metrics history tracking
+- [ ] Implement metrics export capabilities
+
+## Phase 6: Real-time Monitoring Interface
+- [ ] Create `current_context()` method for immediate access
+- [ ] Implement `tokens_consumed()` aggregation method
+- [ ] Add `iteration_metrics()` for per-iteration data
+- [ ] Create `session_metrics()` for overall statistics
+- [ ] Implement metrics update notifications
+
+## Phase 7: Integration Points
+- [ ] Create interface for Loop component context monitoring
+- [ ] Implement threshold-based callback system
+- [ ] Add metrics reporting for display components
+- [ ] Create metrics persistence between iterations
+- [ ] Implement metrics reset and cleanup procedures
+
+## Phase 8: Advanced Analytics
+- [ ] Implement token efficiency analysis
+- [ ] Add cache hit rate calculation
+- [ ] Create tool usage cost analysis
+- [ ] Implement performance trend analysis
+- [ ] Add predictive context growth modeling
+
+## Phase 9: Error Handling and Validation
+- [ ] Implement JSON parsing error recovery
+- [ ] Add malformed event handling
+- [ ] Create missing field validation
+- [ ] Implement event sequence validation
+- [ ] Add metrics corruption detection
+
+## Verification Criteria
+- [ ] JSON stream parsing handles all event types correctly
+- [ ] Context calculation matches specification formula exactly
+- [ ] Real-time monitoring provides accurate current state
+- [ ] Token tracking works across multiple iterations
+- [ ] Integration with Loop component works seamlessly
+- [ ] Error handling is robust and comprehensive
+- [ ] Performance is suitable for real-time monitoring
+- [ ] No Ruby style violations (run `bin/rubocop`)
+- [ ] All tests pass (run `bin/test`)
+
+## Dependencies
+- Requires Agents component for JSON stream input
+- Requires Loop component for integration callbacks
+- Depends on opencode JSON stream format consistency
+- Needs proper time tracking for rate calculations
+
+## Example Event Classes to Implement
+```ruby
+# Based on spec example - create classes for these events:
+- step_start
+- text 
+- tool_use
+- step_finish (critical for token tracking)
+```
+
+## Critical Implementation Details
+- Context formula: `input + cache.read + cache.write`
+- Cache pattern: `cache.read` ≈ previous step's `cache.read + cache.write`
+- Must track `step_finish` events specifically for token data
+- Need real-time access for loop cancellation decisions

data/plans/README.md

@@ -0,0 +1,63 @@
+# Ralph.rb Implementation Plans
+
+This directory contains comprehensive phased implementation plans for building Ralph.rb, a Ruby CLI that runs iterative AI development loops.
+
+## Plans Overview
+
+### [00-complete-implementation.md](./00-complete-implementation.md)
+**Master Plan** - Coordinates all component implementations into a cohesive system with 8 phases from foundation to optimization.
+
+### [01-cli-implementation.md](./01-cli-implementation.md)
+**CLI Component** - Implements the command-line interface with Unix-style pipe support and all specified options.
+
+### [02-loop-implementation.md](./02-loop-implementation.md)
+**Core Loop Component** - Implements the main iteration management with context guards and termination conditions.
+
+### [03-agents-implementation.md](./03-agents-implementation.md)
+**Agent Integration** - Implements opencode CLI integration with JSON stream processing and process management.
+
+### [04-metrics-implementation.md](./04-metrics-implementation.md)
+**Metrics Component** - Implements real-time token usage and context calculation from JSON streams.
+
+## Implementation Strategy
+
+1. **Foundation First** - Start with the complete implementation plan for project setup
+2. **Parallel Development** - CLI, Metrics, and Agents foundations can be developed simultaneously
+3. **Integration Focus** - Loop implementation depends on the other three components
+4. **Quality Gates** - Each phase includes verification criteria and testing requirements
+
+## Key Dependencies
+
+```
+CLI → Loop → Agents → Metrics → CLI (for display)
+```
+
+- CLI requires Loop for execution
+- Loop requires Agents for iteration execution  
+- Loop requires Metrics for context monitoring
+- Metrics requires Agents for JSON stream input
+- CLI requires Metrics for progress display
+
+## Verification Requirements
+
+Every plan includes:
+- ✅ Phase-specific deliverables
+- ✅ Integration points with other components  
+- ✅ Testing and quality assurance criteria
+- ✅ Style compliance requirements (RuboCop)
+- ✅ Final verification checklists
+
+## Ruby Style Requirements
+
+All implementations must follow the guidelines in `AGENTS.md`:
+- No early returns or guard clauses
+- Use `.then` and `.tap` for data flow
+- No abbreviated variable names
+- Full descriptive naming throughout
+
+## Testing Commands
+
+- **Run tests**: `bin/test`
+- **Check style**: `bin/rubocop`
+
+Both must pass before any component is considered complete.

data/specs/README.md

@@ -29,18 +29,7 @@ Design documentation for Ralph.rb, a Ruby CLI that runs iterative AI development
 
 | Spec | Code | Purpose |
 |------|------|---------|
-| [agents.md](./agents.md) | [lib/ralph/agents/](../lib/ralph/agents/) | Agent abstraction: base class, subclasses, CLI resolution, subprocess argument building |
-| [cli.md](./cli.md) | [lib/ralph/cli.rb](../lib/ralph/cli.rb) | CLI options, subcommands, prompt resolution, error handling |
-## Data Storage
-
-| Spec | Code | Purpose |
-|------|------|---------|
-| [storage/local-data-structure.md](./storage/local-data-structure.md) | [lib/ralph/storage/](../lib/ralph/storage/) | Ralph state persistence: .ralph/ directory, storage module architecture, data lifecycle |
-| [tasks.md](./tasks.md) | [lib/ralph/storage/tasks.rb](../lib/ralph/storage/tasks.rb) | Task management: file format, data models, storage, lifecycle in the loop, prompt integration |
-
-## Output
-
-| Spec | Code | Purpose |
-|------|------|---------|
-| [output.md](./output.md) | [lib/ralph/output/](../lib/ralph/output/) | Terminal output structure: callable object pattern, channels, formatting conventions |
-
+| [cli.md](./cli.md) | [exe/ralph](../exe/ralph) | Command-line interface specification for interacting with ralph |
+| [loop.md](./loop.md) | — | Core loop architecture and iteration management |
+| [agents.md](./agents.md) | — | Integration with opencode agents and JSON streaming |
+| [metrics.md](./metrics.md) | — | Context and token usage calculation from JSON streams |

data/specs/__templates__/CONTROLLER_TEMPLATE.md

@@ -0,0 +1,32 @@
+# Spec Template Example
+...
+
+## Overview
+...
+
+### Purpose
+...
+
+### Purpose
+...
+
+### Non-Goals
+...
+
+### Goals
+...
+
+## Audit Events
+...
+
+## Permissions
+...
+
+## Security Considerations
+...
+
+## Future Considerations
+...
+
+## Future Enhancements
+...