Maestro/PRD.md

# **Project Specification: Multi-Instance AI Coding Console (MACC)**
*A phased, validated-primitive product requirements document for engineering.*

---

# **0. Product Summary**
MACC is a unified, highly-responsive developer IDE that manages multiple AI coding assistants (Claude Code, Aider, OpenCode, Codex, etc.) simultaneously.  
It runs as an Electron desktop application with a fully responsive interface that also exposes a web-view for mobile access.  
Each “instance” behaves like a worker: showing state, logs, artifacts, diffs, and contextual metadata.  

The app emphasizes:
- Obsidian-like UI (themes, fixed-width fonts, panel layout)
- Linear/Superhuman-level responsiveness + keyboard-first UX
- Full per-instance lifecycle control (create, resume, terminate)
- Support for Git and non-Git workspaces
- Artifact tracking, semantic worklogs, context usage visualization
- Remote control via auto-tunneled HTTPS endpoints (ngrok)
- Generic support for any CLI-based AI coding tool with no modifications required.

The specification is broken into **phases**, each ending in a **primitive** that must be validated before continuing.

---

# **PHASE 1 — Core Architectural Primitives**

## **1.1 Primitive: Process Manager**
**Goal**: A minimal Electron backend that can launch arbitrary CLI tools, track PID, and capture raw stdout/stderr streams.

### **Requirements**
- Electron main process spawns child processes.
- Output is captured line-by-line in a structured format.
- Input can be sent via STDIN.
- Must work with any CLI tool, unchanged.
- Supports persistent process registry (ID, type, path, state).

### **Validation Criteria**
- Launch any AI CLI (Claude Code, Aider, etc.) and see raw output streaming into a debug pane.
- Send simple commands via STDIN.
- Kill and restart processes.

---

## **1.2 Primitive: Unified Session Model**
**Goal**: A generic model for a “Session” that abstracts Claude Code, Aider, Codex, etc. into the same interface.

### **Requirements**
- Attributes:
  - `sessionId`
  - `sessionName`
  - `toolType` (claude, aider, opencode, custom)
  - `cwd` (working dir)
  - `state` (idle, busy)
  - `stdinMode` (terminal vs. AI)
  - `contextUsage` (%)
  - `stdoutLog[]`
  - `semanticLog[]` (future)
  - `artifacts[]`
- Pluggable command templates per tool type:
  - Start command
  - Resume command (if applicable)
  - Batch/script command flags

### **Validation Criteria**
- Create a session pointing to Claude Code or Aider and confirm identical behaviors via the unified object.
- Switching toolType requires no UI changes.

---

## **1.3 Primitive: Dual-Mode Input Router**
**Goal**: Toggle between:
1. **Terminal Mode** → sends raw shell commands to the OS.
2. **AI Interaction Mode** → sends input to the AI process.

### **Requirements**
- UI toggle switch.
- Terminal mode uses node-pty or equivalent pseudoterminal.
- AI mode uses direct STDIN to the assistant process.
- Visual indication of current mode.

### **Validation Criteria**
- Send `ls` in terminal mode and get directory listing.
- Send message in AI mode and receive assistant output.
- No cross-contamination.

---

# **PHASE 2 — UI Foundations**

## **2.1 Primitive: Obsidian-Inspired Visual System**
**Goal**: Core layout and theming.

### **Requirements**
- Fixed-width fonts everywhere.
- Theme engine with:
  - Dracula (default)
  - Dark
  - Light
  - Monokai
- Minimalistic panel layout:
  - Session list (left)
  - Workspace panel (center)
  - Logs/Artifacts panel (right)
- Responsive grid that collapses elegantly for mobile web.

### **Validation Criteria**
- Theme switching works live.
- Layout remains stable on window resize.
- Mobile view loads via localhost.

---

## **2.2 Primitive: Keyboard-First Navigation**
**Goal**: Achieve Linear/Superhuman responsiveness.

### **Requirements**
- Global shortcuts:
  - `⌘K / Ctrl+K` command palette
  - `⌘1,2,3` for switching major panels
  - `⌘⇧N` create new session
  - `⌘[` and `⌘]` cycle sessions
- Per-session shortcuts:
  - Toggle terminal/AI mode
  - Kill/restart instance
- Low-latency event pipeline (< 16ms UI update target)

### **Validation Criteria**
- Command palette works.
- All shortcuts trigger instantly.
- No perceptible lag (< ~30ms worst case).

---

# **PHASE 3 — Session Intelligence Layer**

## **3.1 Primitive: Auto-Generated Description**
**Goal**: Session auto-describes its purpose based on recent activity.

### **Requirements**
- Analyze last N messages.
- Generate a one-sentence summary.
- Update after every user instruction.
- Display under session name.

### **Validation Criteria**
- Summary updates correctly when switching tasks.
- Descriptions feel accurate.

---

## **3.2 Primitive: Semantic Worklog Engine**
**Goal**: Maintain a human-readable summary of activity per instance.

### **Requirements**
- Summaries generated incrementally:
  - What tasks were attempted?
  - What results occurred?
  - What files changed?
  - What errors occurred?
- Stored as structured entries.

### **Validation Criteria**
- After a session with multiple commands, worklog renders meaningful history.
- Semantic entries correlate with artifacts/diffs.

---

## **3.3 Primitive: Context Window Analyzer**
**Goal**: Display % context used for each assistant.

### **Requirements**
- Query tool APIs for context usage when available (Claude Code supports this).
- Estimate context via tokenization fallback for tools lacking API.
- Show progress bar (0–100%).

### **Validation Criteria**
- Claude Code sessions show real usage.
- Other tools display estimated usage.

---

# **PHASE 4 — Workspace Intelligence**

## **4.1 Primitive: Dual Workspace Modes**
**Goal**: Behavior changes depending on whether the session is in a Git repo.

### **Requirements**
- Auto-detect Git repo.
- If **Git workspace**:
  - Show “Changed Files” list (`git diff --name-only`)
  - On click → show full diff
- If **Non-Git workspace**:
  - Track file changes (created, modified, deleted)
  - Display artifact list
  - Link artifacts to semantic worklog

### **Validation Criteria**
- Switching between Git and non-Git folders produces different UI.
- Diffs display cleanly.
- Artifacts tracked reliably.

---

# **PHASE 5 — State, Status & Control Layer**

## **5.1 Primitive: Status Indicators**
**Goal**: Show live state of each instance.

### **Requirements**
- Green = idle / awaiting input.
- Red = busy / processing.
- Update state based on stdout patterns & timing.

### **Validation Criteria**
- Status flips to “busy” on any processing.
- Returns to “idle” after output completion.

---

## **5.2 Primitive: Session Lifecycle Controls**
**Goal**: Full process management.

### **Requirements**
- Buttons:
  - Start
  - Resume
  - Stop/Kill
  - Duplicate session
- Safe shutdown logic.

### **Validation Criteria**
- Perform lifecycle control on all supported tools.
- No orphaned processes.

---

# **PHASE 6 — Remote Access & Tunneling**

## **6.1 Primitive: Local Web Server**
**Goal**: Expose a web-based interface with responsive layout.

### **Requirements**
- Serves:
  - Session list
  - Log viewer
  - Input pane
  - Mobile-friendly navigation
- Read-only mode toggle (security)

### **Validation Criteria**
- Accessed from phone on LAN.
- Full session control works.

---

## **6.2 Primitive: Integrated ngrok Tunneling**
**Goal**: One-click public remote access.

### **Requirements**
- User enters ngrok API key once.
- A button toggles tunnel on/off.
- Electron app retrieves and displays:
  - Public URL
  - Connection status
- Automatic reconnect on failure.

### **Validation Criteria**
- Tunnel spins up with one click.
- Mobile access works over LTE.
- Reconnecting maintains session state.

---

# **PHASE 7 — Performance & Polish**

## **7.1 Primitive: High-Responsiveness Engine**
**Goal**: Match Linear/Superhuman’s feel.

### **Requirements**
- Pre-render critical views.
- Use React + TypeScript + Recoil/Zustand for low latency.
- GPU rendering hints (CSS transform layering).
- WebSocket bridge with main process for real-time output.

### **Validation Criteria**
- Session switching < 50ms.
- Keyboard commands < 30ms response.
- Streaming output renders with minimal delay.

---

## **7.2 Primitive: Extension & Plugin System**
**Goal**: Allow future support for more AI tools or features.

### **Requirements**
- Configurable tool definitions:
  - Startup commands
  - Flags
  - Output parsing rules
- User-added tool templates.

### **Validation Criteria**
- Adding a new tool requires no core code modification.
- YAML/JSON templates work successfully.

---

# **PHASE 8 — Final Integration & UX Polish**

## **8.1 Primitive: Unified Project Pane**
**Goal**: Provide high-level visibility across all sessions.

### **Requirements**
- Master session dashboard:
  - Status indicators
  - Descriptions
  - Context bars
  - Git/non-Git badges
- Global search.

### **Validation Criteria**
- Dashboard accurately reflects all instance states.
- Search finds sessions, logs, and artifacts.

---

## **8.2 Primitive: Multi-Device Continuity**
**Goal**: Seamless transition between desktop and mobile.

### **Requirements**
- Shared session state between desktop UI and web UI.
- Live sync of logs and output streams.

### **Validation Criteria**
- Actions performed on phone instantly reflect on desktop.
- Desktop input reflects on mobile viewer.

---

# **TECHNICAL STACK DECISIONS**

### **Electron**
- Desktop environment  
- Mobility via embedded webserver  

### **Frontend**
- React  
- TypeScript  
- Zustand (store)  
- Tailwind or custom styling engine  
- Monaco editor for diff rendering  

### **Backend**
- Node.js  
- node-pty for terminal mode  
- Child process spawn for AI tools  
- Fastify or Express for local web server  
- WebSocket bridge for real-time updates  

### **Remote Access**
- ngrok (free tier)