Autorun Overhaul

.github/workflows/auto-assign.yml

@@ -0,0 +1,25 @@
+name: Auto Assign
+
+on:
+  issues:
+    types: [opened]
+  pull_request:
+    types: [opened]
+
+jobs:
+  assign:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Assign to pedramamini
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issueNumber = context.issue?.number || context.payload.pull_request?.number;
+            if (issueNumber) {
+              await github.rest.issues.addAssignees({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+                assignees: ['pedramamini']
+              });
+            }

ARCHITECTURE.md

@@ -14,6 +14,7 @@ Deep technical documentation for Maestro's architecture and design patterns. For
 - [Theme System](#theme-system)
 - [Settings Persistence](#settings-persistence)
 - [Claude Sessions API](#claude-sessions-api)
+- [Auto Run System](#auto-run-system)
 - [Error Handling Patterns](#error-handling-patterns)
 
 ---
@@ -92,7 +93,7 @@ React frontend with no direct Node.js access:
 | Directory | Purpose |
 |-----------|---------|
 | `components/` | React UI components |
-| `hooks/` | Custom React hooks (useSettings, useSessionManager, useFileExplorer) |
+| `hooks/` | Custom React hooks (useSettings, useSessionManager, useFileExplorer, useBatchProcessor) |
 | `services/` | IPC wrappers (git.ts, process.ts) |
 | `contexts/` | React contexts (LayerStackContext) |
 | `constants/` | Themes, shortcuts, modal priorities |
@@ -594,6 +595,187 @@ const unsubscribe = window.maestro.claude.onGlobalStatsUpdate((stats) => {
 
 ---
 
+## Auto Run System
+
+File-based document runner for automating multi-step tasks. Users configure a folder of markdown documents containing checkbox tasks that are processed sequentially by AI agents.
+
+### Component Architecture
+
+| Component | Purpose |
+|-----------|---------|
+| `AutoRun.tsx` | Main panel showing current document with edit/preview modes |
+| `AutoRunSetupModal.tsx` | First-time setup for selecting the Runner Docs folder |
+| `AutoRunDocumentSelector.tsx` | Dropdown for switching between markdown documents |
+| `BatchRunnerModal.tsx` | Configuration modal for multi-document batch execution |
+| `PlaybookNameModal.tsx` | Modal for naming saved playbook configurations |
+| `PlaybookDeleteConfirmModal.tsx` | Confirmation modal for playbook deletion |
+| `useBatchProcessor.ts` | Hook managing batch execution logic |
+
+### Data Types
+
+```typescript
+// Document entry in the batch run queue (supports duplicates)
+interface BatchDocumentEntry {
+  id: string;              // Unique ID for drag-drop and duplicates
+  filename: string;        // Document filename (without .md)
+  resetOnCompletion: boolean;  // Uncheck all boxes when done
+  isDuplicate: boolean;    // True if this is a duplicate entry
+}
+
+// Git worktree configuration for parallel work
+interface WorktreeConfig {
+  enabled: boolean;              // Whether to use a worktree
+  path: string;                  // Absolute path for the worktree
+  branchName: string;            // Branch name to use/create
+  createPROnCompletion: boolean; // Create PR when Auto Run finishes
+}
+
+// Configuration for starting a batch run
+interface BatchRunConfig {
+  documents: BatchDocumentEntry[];  // Ordered list of docs to run
+  prompt: string;                   // Agent prompt template
+  loopEnabled: boolean;             // Loop back to first doc when done
+  worktree?: WorktreeConfig;        // Optional worktree configuration
+}
+
+// Runtime batch processing state
+interface BatchRunState {
+  isRunning: boolean;
+  isStopping: boolean;
+  documents: string[];           // Document filenames in order
+  currentDocumentIndex: number;  // Which document we're on (0-based)
+  currentDocTasksTotal: number;
+  currentDocTasksCompleted: number;
+  totalTasksAcrossAllDocs: number;
+  completedTasksAcrossAllDocs: number;
+  loopEnabled: boolean;
+  loopIteration: number;         // How many times we've looped
+  folderPath: string;
+  worktreeActive: boolean;
+  worktreePath?: string;
+  worktreeBranch?: string;
+}
+
+// Saved playbook configuration
+interface Playbook {
+  id: string;
+  name: string;
+  createdAt: number;
+  updatedAt: number;
+  documents: PlaybookDocumentEntry[];
+  loopEnabled: boolean;
+  prompt: string;
+  worktreeSettings?: {
+    branchNameTemplate: string;
+    createPROnCompletion: boolean;
+  };
+}
+```
+
+### Session Fields
+
+Auto Run state is stored per-session:
+
+```typescript
+// In Session interface
+autoRunFolderPath?: string;      // Persisted folder path for Runner Docs
+autoRunSelectedFile?: string;     // Currently selected markdown filename
+autoRunMode?: 'edit' | 'preview'; // Current editing mode
+autoRunEditScrollPos?: number;    // Scroll position in edit mode
+autoRunPreviewScrollPos?: number; // Scroll position in preview mode
+autoRunCursorPosition?: number;   // Cursor position in edit mode
+batchRunnerPrompt?: string;       // Custom batch runner prompt
+batchRunnerPromptModifiedAt?: number;
+```
+
+### IPC Handlers
+
+```typescript
+// List markdown files in a directory
+'autorun:listDocs': (folderPath: string) => Promise<{ success, files, error? }>
+
+// Read a markdown document
+'autorun:readDoc': (folderPath: string, filename: string) => Promise<{ success, content, error? }>
+
+// Write a markdown document
+'autorun:writeDoc': (folderPath: string, filename: string, content: string) => Promise<{ success, error? }>
+
+// Save image to folder
+'autorun:saveImage': (folderPath: string, docName: string, base64Data: string, extension: string) =>
+  Promise<{ success, relativePath, error? }>
+
+// Delete image
+'autorun:deleteImage': (folderPath: string, relativePath: string) => Promise<{ success, error? }>
+
+// List images for a document
+'autorun:listImages': (folderPath: string, docName: string) => Promise<{ success, images, error? }>
+
+// Playbook CRUD operations
+'playbooks:list': (sessionId: string) => Promise<{ success, playbooks, error? }>
+'playbooks:create': (sessionId: string, playbook) => Promise<{ success, playbook, error? }>
+'playbooks:update': (sessionId: string, playbookId: string, updates) => Promise<{ success, playbook, error? }>
+'playbooks:delete': (sessionId: string, playbookId: string) => Promise<{ success, error? }>
+```
+
+### Git Worktree Integration
+
+When worktree is enabled, Auto Run operates in an isolated directory:
+
+```typescript
+// Check if worktree exists and get branch info
+'git:worktreeInfo': (worktreePath: string) => Promise<{
+  success: boolean;
+  exists: boolean;
+  isWorktree: boolean;
+  currentBranch?: string;
+  repoRoot?: string;
+}>
+
+// Create or reuse a worktree
+'git:worktreeSetup': (mainRepoCwd: string, worktreePath: string, branchName: string) => Promise<{
+  success: boolean;
+  created: boolean;
+  currentBranch: string;
+  branchMismatch: boolean;
+}>
+
+// Checkout a branch in a worktree
+'git:worktreeCheckout': (worktreePath: string, branchName: string, createIfMissing: boolean) => Promise<{
+  success: boolean;
+  hasUncommittedChanges: boolean;
+}>
+
+// Create PR from worktree branch
+'git:createPR': (worktreePath: string, baseBranch: string, title: string, body: string) => Promise<{
+  success: boolean;
+  prUrl?: string;
+}>
+```
+
+### Execution Flow
+
+1. **Setup**: User selects Runner Docs folder via `AutoRunSetupModal`
+2. **Document Selection**: Documents appear in `AutoRunDocumentSelector` dropdown
+3. **Editing**: `AutoRun` component provides edit/preview modes with auto-save (5s debounce)
+4. **Batch Configuration**: `BatchRunnerModal` allows ordering documents, enabling loop/reset, configuring worktree
+5. **Playbooks**: Save/load configurations for repeated batch runs
+6. **Execution**: `useBatchProcessor` hook processes documents sequentially
+7. **Progress**: RightPanel shows document and task-level progress
+
+### Write Queue Integration
+
+Without worktree mode, Auto Run tasks queue through the existing execution queue:
+- Auto Run tasks are marked as write operations (`readOnlyMode: false`)
+- Manual write messages queue behind Auto Run (sequential)
+- Read-only operations from other tabs can run in parallel
+
+With worktree mode:
+- Auto Run operates in a separate directory
+- No queue conflicts with main workspace
+- True parallelization enabled
+
+---
+
 ## Error Handling Patterns
 
 ### IPC Handlers (Main Process)

CLAUDE.md

@@ -8,7 +8,7 @@ Use these terms consistently in code, comments, and documentation:
 
 ### UI Components
 - **Left Bar** - Left sidebar with session list and groups (`SessionList.tsx`)
-- **Right Bar** - Right sidebar with Files, History, Scratchpad tabs (`RightPanel.tsx`)
+- **Right Bar** - Right sidebar with Files, History, Auto Run tabs (`RightPanel.tsx`)
 - **Main Window** - Center workspace (`MainPanel.tsx`)
   - **AI Terminal** - Main window in AI mode (interacting with AI agents)
   - **Command Terminal** - Main window in terminal/shell mode
@@ -172,7 +172,8 @@ interface Session {
   toolType: ToolType;           // 'claude-code' | 'aider' | 'terminal' | etc.
   state: SessionState;          // 'idle' | 'busy' | 'error' | 'connecting'
   inputMode: 'ai' | 'terminal'; // Which process receives input
-  cwd: string;                  // Working directory
+  cwd: string;                  // Current working directory (can change via cd)
+  projectRoot: string;          // Initial working directory (never changes, used for Claude session storage)
   aiPid: number;                // AI process ID
   terminalPid: number;          // Terminal process ID
   aiLogs: LogEntry[];           // AI output history
@@ -223,3 +224,59 @@ The `window.maestro` API exposes:
 ### Modal Escape Not Working
 1. Register with layer stack (don't handle Escape locally)
 2. Check priority is set correctly
+
+## Keyboard Shortcuts
+
+Key shortcuts for navigation and common actions. Full list available via `⌘+/` (Help).
+
+### Panel Navigation
+| Shortcut | Action |
+|----------|--------|
+| `⌥⌘←` | Toggle Left Panel |
+| `⌥⌘→` | Toggle Right Panel |
+| `⌘⇧F` | Go to Files Tab |
+| `⌘⇧H` | Go to History Tab |
+| `⌘⇧1` | Go to Auto Run Tab |
+
+### Session Management
+| Shortcut | Action |
+|----------|--------|
+| `⌘N` | New Agent |
+| `⌘[` / `⌘]` | Previous/Next Agent |
+| `⌥⌘1-0` | Jump to Session 1-10 |
+| `⌘⇧⌫` | Remove Agent |
+| `⌘⇧M` | Move Session to Group |
+
+### Tab Management (AI Mode)
+| Shortcut | Action |
+|----------|--------|
+| `⌘T` | New Tab |
+| `⌘W` | Close Tab |
+| `⌘⇧T` | Reopen Closed Tab |
+| `⌘1-9` | Go to Tab 1-9 |
+| `⌘0` | Go to Last Tab |
+| `⌥⌘T` | Tab Switcher |
+
+### Mode & Focus
+| Shortcut | Action |
+|----------|--------|
+| `⌘J` | Switch AI/Shell Mode |
+| `⌘.` | Focus Input Field |
+| `⌘⇧A` | Focus Left Panel |
+| `⌘R` | Toggle Read-Only Mode |
+| `⌘E` | Toggle Markdown Raw/Preview |
+
+### Git & System
+| Shortcut | Action |
+|----------|--------|
+| `⌘⇧D` | View Git Diff |
+| `⌘⇧G` | View Git Log |
+| `⌥⌘L` | System Log Viewer |
+| `⌥⌘P` | System Process Monitor |
+
+### Quick Access
+| Shortcut | Action |
+|----------|--------|
+| `⌘K` | Quick Actions |
+| `⌘,` | Open Settings |
+| `⌘/` | Show All Shortcuts |