feat: Add batch/script mode for command execution (Phase 5)

CLAUDE.md

@@ -381,7 +381,40 @@ type Step struct {
 - AI integration point: translate "make it darker" → `cc-step` commands
 - Profile format already designed, just not implemented yet
 
-### Phase 5: Live Performance Features
+### Phase 5: Batch/Script Mode ✅ (Completed)
+- ✅ Stdin detection for piped input vs terminal
+- ✅ `--script` flag for explicit file execution
+- ✅ Comment handling (lines starting with `#`)
+- ✅ Error tracking with graceful continuation
+- ✅ Command echo for progress feedback
+- ✅ Exit command recognition for controlled termination
+- ✅ Performance tool paradigm: scripts setup state, playback continues
+
+**Batch Mode Features:**
+- Pipe commands from files: `cat commands.txt | ./interplay`
+- Interactive continuation: `cat commands.txt - | ./interplay`
+- Script file flag: `./interplay --script commands.txt`
+- Graceful error handling: log errors, continue execution
+- Real-time progress: echo commands as they execute
+- Exit control: explicit `exit` command or continue playing
+- AI commands work inline: `ai make it darker` in scripts
+
+**Usage Examples:**
+```bash
+# Pipe commands and continue with playback
+echo "set 1 C4" | ./interplay
+
+# Pipe commands then interact
+cat setup.txt - | ./interplay
+
+# Execute script file
+./interplay --script performance-setup.txt
+
+# Script with AI commands
+echo -e "set 1 C3\nai add tension\nshow" | ./interplay
+```
+
+### Phase 6: Live Performance Features
 - MIDI controller input (separate MIDI controller device)
     - Play notes on controller to add them to the pattern in real-time
     - Use knobs/faders to control synth parameters

README.md

@@ -18,7 +18,7 @@ Interplay transforms your creative process by combining AI musical intelligence
 
 Interplay works with your synthesizer's full MIDI capabilities—notes, velocity, gate length, and synth-specific parameters. The AI helps you stay musically coherent while encouraging experimentation with dissonance, unconventional harmonies, and creative tension when that's what your music needs.
 
-**Current Status:** Phase 3 Complete - AI integration with hybrid command/natural language control
+**Current Status:** Phase 5 Complete - Batch/script mode for performance setup and automation
 
 ## Installation
 
@@ -146,6 +146,113 @@ AI> <enter>
 
 **Alternative: Manual mode** - All commands work without an API key if you prefer direct control without AI assistance. Type `help` for the full command list.
 
+## Batch/Script Mode - Performance Setup & Automation
+
+Interplay supports batch execution for automating pattern setup, testing workflows, and preparing performance configurations. Create reusable script files containing commands that execute sequentially.
+
+### Three Execution Modes
+
+**1. Piped Input (batch then continue playing):**
+```bash
+cat commands.txt | ./interplay
+```
+Processes commands from the file, then continues running with playback loop active. Press Ctrl+C to exit.
+
+**2. Piped Input with Interactive Continuation:**
+```bash
+cat commands.txt - | ./interplay
+```
+The dash (`-`) keeps stdin open, allowing you to continue with manual commands after the script completes.
+
+**3. Script File Flag:**
+```bash
+./interplay --script setup.txt
+```
+Explicit file execution. Same behavior as piped input (continues playing after script completes).
+
+### Script File Format
+
+```bash
+# Comments start with #
+# Commands execute line-by-line
+
+# Set up a pattern
+clear
+tempo 95
+set 1 C3 vel:127
+set 5 C3 vel:110
+set 9 G2 vel:120
+
+# Add musical variation
+humanize velocity 8
+swing 50
+
+# Save the result
+save performance-bass
+
+# Optional: exit when done
+# exit
+```
+
+By default, scripts setup musical state and continue playing—this is a **performance tool**, not just batch processing.
+
+### Exit Behavior
+
+Scripts continue with playback loop active unless you add an explicit `exit` command:
+
+**To exit automatically after script:**
+```bash
+# At end of script file:
+exit
+```
+
+**Exit codes:**
+- `0` = Success (all commands executed without errors)
+- `1` = Errors occurred (but script completed)
+- `2` = File not found or read error
+
+### Error Handling
+
+Invalid commands are logged but don't stop execution:
+```bash
+set 1 C4        # Executes successfully
+invalid cmd     # Error logged, execution continues
+set 5 G2        # Executes successfully
+```
+
+### Warnings for Destructive Operations
+
+The system warns before overwriting or deleting:
+```
+> save my-pattern
+⚠️  Warning: Pattern 'my-pattern' already exists and will be overwritten.
+```
+
+### Example Scripts
+
+Included test scripts demonstrate common workflows:
+- `example-batch-setup.txt` - Complete performance setup workflow
+- `test_basic.txt` - Simple pattern creation
+- `test_cc.txt` - CC automation examples
+
+### AI Commands in Scripts
+
+AI commands work in batch mode—they execute inline and wait for completion:
+
+```bash
+# script.txt
+set 1 C3
+ai make it darker
+show
+```
+
+Note: AI commands may take several seconds each. The script waits for completion before continuing.
+
 ## Learn More
 
-See [CLAUDE.md](CLAUDE.md) for detailed development approach, architecture, and roadmap.
+**For Users:**
+- See [CLAUDE.md](CLAUDE.md) for detailed development approach, architecture, and roadmap
+
+**For Developers:**
+- See [Implementation Summary](specs/002-batch-script-mode/IMPLEMENTATION-SUMMARY.md) for batch/script mode feature documentation
+- See [Phase 5 Recommendations](specs/002-batch-script-mode/PHASE-5-RECOMMENDATIONS.md) for lessons learned and next phase planning guidance

TEST_FILES.md

@@ -0,0 +1,132 @@
+# Test Files for Batch/Script Mode
+
+This directory contains test script files demonstrating various batch mode features.
+
+## Test Files
+
+### test_basic.txt
+**Purpose**: Basic batch mode functionality
+**Usage**: `./interplay --script test_basic.txt` or `cat test_basic.txt | ./interplay`
+
+Demonstrates:
+- Clear command
+- Tempo setting
+- Setting notes with velocity
+- Gate length control
+- Humanization
+- Swing
+- Pattern saving
+- Transition to interactive mode (no exit command)
+
+### test_cc.txt
+**Purpose**: CC (Control Change) automation
+**Usage**: `./interplay --script test_cc.txt` or `cat test_cc.txt | ./interplay`
+
+Demonstrates:
+- Per-step CC automation
+- Filter sweep using CC#74 (filter cutoff)
+- Resonance control using CC#71
+- CC visualization with cc-show command
+- Saving patterns with CC data
+
+### test_exit.txt
+**Purpose**: Exit command behavior
+**Usage**: `./interplay --script test_exit.txt` or `cat test_exit.txt | ./interplay`
+
+Demonstrates:
+- Clean exit after script execution
+- Exit code 0 on success
+- Script mode that doesn't continue playing
+
+### test_interactive.txt
+**Purpose**: Interactive continuation mode
+**Usage**: `cat test_interactive.txt - | ./interplay`
+**Note**: The dash (`-`) after the filename is required!
+
+Demonstrates:
+- Piped input followed by interactive mode
+- Setting up a foundation pattern via script
+- Continuing with manual commands afterward
+- Best for rapid iteration workflows
+
+### test_errors.txt
+**Purpose**: Error handling and graceful continuation
+**Usage**: `./interplay --script test_errors.txt` or `cat test_errors.txt | ./interplay`
+
+Demonstrates:
+- Errors logged to stderr
+- Script continues executing after errors
+- Valid commands still execute
+- Graceful degradation
+
+Contains intentional errors:
+- Invalid step number (999)
+- Invalid note name (X99)
+
+### test_warnings.txt
+**Purpose**: Destructive operation warnings
+**Usage**: `./interplay --script test_warnings.txt` or `cat test_warnings.txt | ./interplay`
+
+Demonstrates:
+- Warning when overwriting existing pattern
+- Warning when deleting pattern
+- Clean exit after operations
+
+## Running Tests
+
+### Quick Test
+```bash
+# Run basic test with continuous playback
+./interplay --script test_basic.txt
+# Press Ctrl+C to stop
+
+# Run exit test (auto-exits)
+./interplay --script test_exit.txt
+```
+
+### Validation Tests
+```bash
+# Test 1: Basic functionality
+./interplay --script test_basic.txt &
+PID=$!
+sleep 3
+kill $PID
+
+# Test 2: Exit command
+./interplay --script test_exit.txt
+echo "Exit code: $?"  # Should be 0
+
+# Test 3: Error handling
+./interplay --script test_errors.txt 2>&1 | grep "Error:"
+
+# Test 4: Warnings
+./interplay --script test_warnings.txt 2>&1 | grep "Warning"
+
+# Test 5: Interactive continuation
+cat test_interactive.txt - | ./interplay
+# Type commands at the prompt, then 'quit'
+```
+
+## Exit Behavior Reference
+
+| Script Type | Exit Command | Behavior | Exit Code |
+|-------------|--------------|----------|-----------|
+| Piped input | No | Continues playing | 0 (on Ctrl+C) |
+| Piped input | Yes, no errors | Exits cleanly | 0 |
+| Piped input | Yes, had errors | Exits with errors | 1 |
+| Script file | No | Interactive mode | User quits |
+| Script file | Yes, no errors | Exits cleanly | 0 |
+| Script file | Yes, had errors | Exits with errors | 1 |
+| Script file | File not found | Error message | 2 |
+| Interactive pipe (`-`) | N/A | Continues interactive | User quits |
+
+## Script as Preset
+
+Script files (using `--script` flag) work as **presets** that set up musical state and then transition to interactive mode. This lets you:
+- Create reusable starting points for performances
+- Load complex patterns quickly and continue editing
+- Build libraries of musical ideas
+
+To exit automatically after a script, include `exit` as the last command.
+
+For the "performance tool paradigm" (setup pattern and let it play), use piped input instead: `cat script.txt | ./interplay`

commands/cc_show.go

@@ -24,8 +24,7 @@ func (h *Handler) handleCCShow(parts []string) error {
 
 	patternLen := h.pattern.Length()
 	for step := 1; step <= patternLen; step++ {
-		// Get step data and iterate directly over its CC map
-		// This is O(n) instead of O(n × 128) where n = number of actual CC automations
+		// Get step data to access CC map directly (more efficient than iterating 0-127)
 		stepData, err := h.pattern.GetStep(step)
 		if err != nil {
 			continue // Skip invalid steps