From 7afb999b46a48b6ea1c5c3758e49d7fa88126516 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 05:37:48 -0600 Subject: [PATCH 01/14] MAESTRO: Fix history.md documentation inaccuracies - Correct time range options (8 options, not 4) - Add Cmd+F shortcut for search filter - Fix settings toggle location description - Add /clear as third method for USER entries - Add arrow key navigation in detail view - Add platform-specific storage paths - Add Help Panel section - Improve keyboard navigation documentation --- docs/history.md | 49 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/docs/history.md b/docs/history.md index 3eb2b7dd..ccfbdf15 100644 --- a/docs/history.md +++ b/docs/history.md @@ -27,13 +27,15 @@ Auto entries are created automatically when Auto Run completes a task. Each entr ### User Entries -User entries are created in two ways: +User entries are created in three ways: 1. **History Toggle** — Enable the **History** pill in the AI input box. Every prompt-response cycle automatically creates a user history entry. 2. **`/history` Command** — Run `/history` to create a synopsis entry covering all activity since the last time you ran the command. This is useful for periodic summaries without logging every single interaction. -**Toggle the default History behavior** in Settings → toggle "Save to History by default". +3. **`/clear` Command** — Running `/clear` automatically creates a history entry before clearing the conversation, preserving a synopsis of your work. + +**Toggle the default History behavior** in Settings → General → "Enable 'History' by default for new tabs". ## Filtering History @@ -46,20 +48,24 @@ Use the **AUTO** and **USER** filter buttons at the top of the History panel to ### By Keyword -Type in the search box to filter entries by keyword. The search matches against: +Press `Cmd+F` / `Ctrl+F` to open the search box, or click in the filter area to type. The search matches against: - Entry summaries -- Session IDs -- Any text content in the entry +- Session names and IDs +- Full response content ### By Time Range The **Graph View** at the top shows activity distribution over time. **Right-click the graph** to change the time range: -- Last 24 hours -- Last 7 days -- Last 30 days +- 24 hours +- 72 hours +- 1 week +- 2 weeks +- 1 month +- 6 months +- 1 year - All time -The graph bars are clickable — click a time period to jump to entries from that window. +The graph bars are clickable — click a time period to jump to entries from that window. Hover over any bar to see the exact count and time range. ## Entry Details @@ -77,9 +83,9 @@ The detail view shows: ### Navigation -- **Prev / Next** buttons to navigate between entries +- **Prev / Next** buttons to navigate between entries (or use `←` / `→` arrow keys) - **Close** button to return to the list view -- **Delete** button to remove the entry +- **Delete** button to remove the entry (with confirmation dialog) ## Validating Entries @@ -115,12 +121,31 @@ This is especially powerful for Auto Run tasks — you can pick up exactly where ## Keyboard Navigation +### List View + | Key | Action | |-----|--------| | `↑` / `↓` | Navigate between entries | | `Enter` | Open detail view for selected entry | +| `Cmd+F` / `Ctrl+F` | Open search filter | +| `Esc` | Clear selection or close search | + +### Detail View + +| Key | Action | +|-----|--------| +| `←` / `→` | Navigate to previous/next entry | | `Esc` | Close detail view, return to list | ## Storage -History is stored per-session in `~/Library/Application Support/Maestro/history/`. Each session maintains up to 5,000 entries. History files can be passed to AI agents as context for understanding past work patterns. +History is stored per-session in JSON files within the `history/` subdirectory of your Maestro data folder: +- **macOS**: `~/Library/Application Support/maestro/history/.json` +- **Windows**: `%APPDATA%/maestro/history/.json` +- **Linux**: `~/.config/maestro/history/.json` + +Each session maintains up to **5,000 entries**. History files can be passed to AI agents as context for understanding past work patterns. + +## Help Panel + +Click the **?** button in the History panel header to open a detailed guide explaining all features, entry types, status indicators, and keyboard shortcuts. From 323074544411c740a92249b937751a7e38417a00 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 05:45:01 -0600 Subject: [PATCH 02/14] MAESTRO: Fix keyboard-shortcuts.md documentation inaccuracies Major fixes: - Toggle Sidebar was Cmd+B, actual shortcut is Opt+Cmd+Left (renamed to Toggle Left Panel) - Toggle Right Panel was Cmd+\, actual shortcut is Opt+Cmd+Right - Document Graph Tab cycling didn't exist in code, removed it - Document Graph Enter key behavior was wrong: re-centers for docs, opens URL for external - Keyboard Mastery levels were completely wrong (Novice/Apprentice/etc vs Beginner/Student/etc) - Keyboard Mastery location was "status bar" but it's actually in Shortcuts Help panel Added missing shortcuts: - New Agent Wizard, New Group Chat, Navigate Back/Forward - Toggle Input/Output Focus, Focus Left Panel, System Log Viewer, Process Monitor - Toggle Bookmark, Maestro Symphony, Toggle Auto Run Expanded, View Git Diff - Toggle Tab Star, Toggle Tab Unread, Filter Unread Tabs, Open Prompt Composer - Go to Tab 1-9 and Go to Last Tab - File Preview Go Back/Forward - Context-sensitive filter shortcuts (Cmd+F in different contexts) --- docs/keyboard-shortcuts.md | 71 +++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 24 deletions(-) diff --git a/docs/keyboard-shortcuts.md b/docs/keyboard-shortcuts.md index 634b663c..e92a38cc 100644 --- a/docs/keyboard-shortcuts.md +++ b/docs/keyboard-shortcuts.md @@ -15,21 +15,31 @@ The command palette is your gateway to nearly every action in Maestro. Press `Cm | Action | macOS | Windows/Linux | |--------|-------|---------------| | Quick Actions | `Cmd+K` | `Ctrl+K` | -| Toggle Sidebar | `Cmd+B` | `Ctrl+B` | -| Toggle Right Panel | `Cmd+\` | `Ctrl+\` | +| Toggle Left Panel | `Opt+Cmd+Left` | `Alt+Ctrl+Left` | +| Toggle Right Panel | `Opt+Cmd+Right` | `Alt+Ctrl+Right` | | New Agent | `Cmd+N` | `Ctrl+N` | -| Kill Agent | `Cmd+Shift+Backspace` | `Ctrl+Shift+Backspace` | +| New Agent Wizard | `Cmd+Shift+N` | `Ctrl+Shift+N` | +| New Group Chat | `Opt+Cmd+C` | `Alt+Ctrl+C` | +| Remove Agent | `Cmd+Shift+Backspace` | `Ctrl+Shift+Backspace` | | Move Agent to Group | `Cmd+Shift+M` | `Ctrl+Shift+M` | | Previous Agent | `Cmd+[` | `Ctrl+[` | | Next Agent | `Cmd+]` | `Ctrl+]` | +| Navigate Back | `Cmd+Shift+,` | `Ctrl+Shift+,` | +| Navigate Forward | `Cmd+Shift+.` | `Ctrl+Shift+.` | | Jump to Agent (1-9, 0=10th) | `Opt+Cmd+NUMBER` | `Alt+Ctrl+NUMBER` | -| Switch AI/Command Terminal | `Cmd+J` | `Ctrl+J` | +| Switch AI/Shell Mode | `Cmd+J` | `Ctrl+J` | +| Toggle Input/Output Focus | `Cmd+.` | `Ctrl+.` | +| Focus Left Panel | `Cmd+Shift+A` | `Ctrl+Shift+A` | | Show Shortcuts Help | `Cmd+/` | `Ctrl+/` | | Open Settings | `Cmd+,` | `Ctrl+,` | | Open Agent Settings | `Opt+Cmd+,` | `Alt+Ctrl+,` | -| View All Agent Sessions | `Cmd+Shift+L` | `Ctrl+Shift+L` | +| View Agent Sessions | `Cmd+Shift+L` | `Ctrl+Shift+L` | +| System Log Viewer | `Opt+Cmd+L` | `Alt+Ctrl+L` | +| System Process Monitor | `Opt+Cmd+P` | `Alt+Ctrl+P` | | Usage Dashboard | `Opt+Cmd+U` | `Alt+Ctrl+U` | | Jump to Bottom | `Cmd+Shift+J` | `Ctrl+Shift+J` | +| Toggle Bookmark | `Cmd+Shift+B` | `Ctrl+Shift+B` | +| Maestro Symphony | `Cmd+Shift+Y` | `Ctrl+Shift+Y` | | Cycle Focus Areas | `Tab` | `Tab` | | Cycle Focus Backwards | `Shift+Tab` | `Shift+Tab` | @@ -40,8 +50,12 @@ The command palette is your gateway to nearly every action in Maestro. Press `Cm | Go to Files Tab | `Cmd+Shift+F` | `Ctrl+Shift+F` | | Go to History Tab | `Cmd+Shift+H` | `Ctrl+Shift+H` | | Go to Auto Run Tab | `Cmd+Shift+1` | `Ctrl+Shift+1` | -| Toggle Markdown Raw/Preview | `Cmd+E` | `Ctrl+E` | +| Toggle Edit/Preview (Markdown) | `Cmd+E` | `Ctrl+E` | +| Toggle Auto Run Expanded | `Cmd+Shift+E` | `Ctrl+Shift+E` | | Insert Checkbox (Auto Run) | `Cmd+L` | `Ctrl+L` | +| View Git Diff | `Cmd+Shift+D` | `Ctrl+Shift+D` | +| View Git Log | `Cmd+Shift+G` | `Ctrl+Shift+G` | +| Fuzzy File Search | `Cmd+G` | `Ctrl+G` | ## AI Tab Shortcuts @@ -49,10 +63,14 @@ These shortcuts work in AI Terminal mode and affect the current tab: | Action | macOS | Windows/Linux | |--------|-------|---------------| -| Toggle History | `Cmd+S` | `Ctrl+S` | +| Toggle Save to History | `Cmd+S` | `Ctrl+S` | | Toggle Read-Only Mode | `Cmd+R` | `Ctrl+R` | | Toggle Show Thinking | `Cmd+Shift+K` | `Ctrl+Shift+K` | +| Toggle Tab Star | `Cmd+Shift+S` | `Ctrl+Shift+S` | +| Toggle Tab Unread | `Cmd+Shift+U` | `Ctrl+Shift+U` | +| Filter Unread Tabs | `Cmd+U` | `Ctrl+U` | | Open Image Carousel | `Cmd+Y` | `Ctrl+Y` | +| Open Prompt Composer | `Cmd+Shift+P` | `Ctrl+Shift+P` | Toggle states are saved per-tab. See [Input Toggles](./general-usage#input-toggles) for details on configuring defaults. @@ -71,6 +89,8 @@ Toggle states are saved per-tab. See [Input Toggles](./general-usage#input-toggl | Next Tab | `Cmd+Shift+]` | `Ctrl+Shift+]` | | Tab Switcher | `Opt+Cmd+T` | `Alt+Ctrl+T` | | Rename Tab | `Cmd+Shift+R` | `Ctrl+Shift+R` | +| Go to Tab 1-9 | `Cmd+1` through `Cmd+9` | `Ctrl+1` through `Ctrl+9` | +| Go to Last Tab | `Cmd+0` | `Ctrl+0` | ### Tab Switcher @@ -139,12 +159,14 @@ In AI mode, use `@` to reference files in your prompts: | Action | macOS | Windows/Linux | |--------|-------|---------------| -| Go to File (fuzzy finder) | `Cmd+G` | `Ctrl+G` | | Navigate Agents | `Up/Down Arrow` while in sidebar | `Up/Down Arrow` while in sidebar | | Select Agent | `Enter` while in sidebar | `Enter` while in sidebar | -| Open Session Filter | `Cmd+F` while in sidebar | `Ctrl+F` while in sidebar | +| Filter Sessions (in Left Panel) | `Cmd+F` | `Ctrl+F` | | Navigate Files | `Up/Down Arrow` while in file tree | `Up/Down Arrow` while in file tree | -| Open File Tree Filter | `Cmd+F` while in file tree | `Ctrl+F` while in file tree | +| Filter Files (in Files tab) | `Cmd+F` | `Ctrl+F` | +| Filter History (in History tab) | `Cmd+F` | `Ctrl+F` | +| Search Output (in Main Window) | `Cmd+F` | `Ctrl+F` | +| Search System Logs | `Cmd+F` | `Ctrl+F` | | Open File Preview | `Enter` on selected file | `Enter` on selected file | | Close Preview/Filter/Modal | `Esc` | `Esc` | @@ -154,7 +176,8 @@ In AI mode, use `@` to reference files in your prompts: |--------|-------|---------------| | Copy File Path | `Cmd+P` | `Ctrl+P` | | Open Search | `Cmd+F` | `Ctrl+F` | -| Open Document Graph | `Cmd+Shift+G` | `Ctrl+Shift+G` | +| Go Back | `Cmd+Left` | `Ctrl+Left` | +| Go Forward | `Cmd+Right` | `Ctrl+Right` | | Scroll | `Up/Down Arrow` | `Up/Down Arrow` | | Close | `Esc` | `Esc` | @@ -163,9 +186,9 @@ In AI mode, use `@` to reference files in your prompts: | Action | Key | |--------|-----| | Navigate to connected nodes | `Arrow Keys` | -| Focus/select a node | `Enter` | -| Open the selected document | `O` | -| Cycle through connected nodes | `Tab` | +| Re-center on node (document) | `Enter` | +| Open URL (external link) | `Enter` | +| Open document in File Preview | `O` | | Close the graph | `Esc` | ## Customizing Shortcuts @@ -192,18 +215,18 @@ Most shortcuts can be remapped to fit your workflow: Maestro tracks your keyboard shortcut usage and rewards you for becoming a power user. As you discover and use more shortcuts, you'll level up through 5 mastery levels: -| Level | Title | Shortcuts Used | -|:-----:|-------|----------------| -| 0 | **Novice** | 0-19% | -| 1 | **Apprentice** | 20-39% | -| 2 | **Journeyman** | 40-59% | -| 3 | **Expert** | 60-79% | -| 4 | **Master** | 80-100% | +| Level | Title | Threshold | +|:-----:|-------|-----------| +| 0 | **Beginner** | 0% | +| 1 | **Student** | 25% | +| 2 | **Performer** | 50% | +| 3 | **Virtuoso** | 75% | +| 4 | **Keyboard Maestro** | 100% | **Tracking your progress:** -- Your current mastery level is shown in the **status bar** at the bottom of the window -- Hover over the keyboard icon to see which shortcuts you've used and which remain to be discovered -- Open the **Shortcuts Help** modal (`Cmd+/` / `Ctrl+/`) to see your mastery percentage and get hints +- Open the **Shortcuts Help** panel (`Cmd+/` / `Ctrl+/`) to see your mastery percentage and current level +- Each shortcut displays a checkmark once you've used it +- A progress bar shows how many shortcuts you've mastered out of the total - When you reach a new level, you'll see a celebration with confetti ![Keyboard Shortcuts Modal](./screenshots/shortcuts-modal.png) From 3b5c0b5bfeee3d475520070ed16c025fedef833d Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 05:47:38 -0600 Subject: [PATCH 03/14] MAESTRO: Fix mcp-server.md documentation inaccuracies - Added mention that MCP server is hosted by Mintlify - Added proactive search behavior explanation - Added Cursor and VS Code configuration instructions - Clarified transport type as HTTP/HTTPS (Streamable HTTP) - Added note about page indexing limitations - Verified all existing information is accurate --- docs/mcp-server.md | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/mcp-server.md b/docs/mcp-server.md index 177a98a9..c89ddb6c 100644 --- a/docs/mcp-server.md +++ b/docs/mcp-server.md @@ -6,11 +6,11 @@ icon: plug # MCP Server -Maestro provides a hosted MCP (Model Context Protocol) server that allows AI applications to search and retrieve information from the Maestro documentation. +Maestro provides a hosted MCP (Model Context Protocol) server that allows AI applications to search and retrieve information from the Maestro documentation. The server is automatically generated and hosted by [Mintlify](https://mintlify.com). ## Overview -The MCP server exposes a `SearchMaestro` tool that enables AI assistants to find relevant documentation, code examples, API references, and guides from the Maestro knowledge base. +The MCP server exposes a `SearchMaestro` tool that enables AI assistants to find relevant documentation, code examples, API references, and guides from the Maestro knowledge base. When connected, your AI assistant can proactively search the documentation while generating responses—not just when explicitly asked. **MCP Server URL:** ``` @@ -63,6 +63,28 @@ Add to your Claude Code MCP settings: } ``` +### Cursor + +In Cursor settings, go to **Features > MCP Servers** and add: + +``` +https://docs.runmaestro.ai/mcp +``` + +### VS Code + +For VS Code with MCP support, add to your MCP configuration: + +```json +{ + "mcpServers": { + "maestro": { + "url": "https://docs.runmaestro.ai/mcp" + } + } +} +``` + ### Other MCP-Compatible Applications Any application that supports the Model Context Protocol can connect using the server URL: @@ -84,9 +106,14 @@ Once connected, your AI assistant can use the `SearchMaestro` tool to answer que ## Technical Details - **Protocol**: Model Context Protocol (MCP) -- **Transport**: HTTP/HTTPS +- **Transport**: HTTP/HTTPS (Streamable HTTP) - **Authentication**: None required (public read-only access) - **Rate Limits**: Standard API rate limits apply +- **Hosting**: Automatically managed by Mintlify + + +The MCP server only indexes pages included in the documentation navigation. Hidden or excluded pages are not searchable. + ## Related Resources From c4312f4552a44c275f96e02b6cdd48fd826ba83d Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 05:50:47 -0600 Subject: [PATCH 04/14] MAESTRO: Fix openspec-commands.md documentation inaccuracies - Added "OpenSpec CLI Commands" section with table of essential commands (list, list --specs, show, validate, archive, spec list --long) - Fixed Stage 1 workflow to document full process including project.md review and openspec list commands - Fixed validation command format to include required change-id parameter - Added --yes and --skip-specs flags documentation for archive command - Expanded /openspec.implement description with phase grouping details - Updated "Viewing & Managing Commands" section to accurately describe UI - Fixed Spec-Kit directory location from "Project root" to "specs/" - Changed tips to use "verb-led IDs" terminology per AGENTS.md conventions - Standardized to em-dashes for consistency with other docs --- docs/openspec-commands.md | 68 +++++++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 24 deletions(-) diff --git a/docs/openspec-commands.md b/docs/openspec-commands.md index a2842dfc..b96e07f8 100644 --- a/docs/openspec-commands.md +++ b/docs/openspec-commands.md @@ -16,7 +16,7 @@ Maestro offers two complementary spec-driven development tools: | **Workflow** | Proposal → Apply → Archive | Constitution → Specify → Plan → Tasks | | **Best For** | Iterative changes, brownfield projects | New features, greenfield development | | **Output** | Change proposals with spec deltas | Feature specifications and task lists | -| **Directory** | `openspec/` | Project root or designated folder | +| **Directory** | `openspec/` | `specs/` or project root | **Use OpenSpec when:** - Making iterative changes to existing features @@ -40,15 +40,16 @@ OpenSpec follows a three-stage cycle: Create a change proposal before writing any code: -1. Reviews existing specs and active changes -2. Scaffolds `proposal.md`, `tasks.md`, and optional `design.md` -3. Creates spec deltas showing what will be ADDED, MODIFIED, or REMOVED -4. Validates the proposal structure +1. Reviews `openspec/project.md` for project conventions +2. Runs `openspec list` to see active changes and `openspec list --specs` for existing capabilities +3. Scaffolds `proposal.md`, `tasks.md`, and optional `design.md` +4. Creates spec deltas showing what will be ADDED, MODIFIED, or REMOVED +5. Validates with `openspec validate --strict` **Creates:** A `openspec/changes//` directory with: -- `proposal.md` - Why and what -- `tasks.md` - Implementation checklist -- `specs//spec.md` - Spec deltas +- `proposal.md` — Why and what +- `tasks.md` — Implementation checklist +- `specs//spec.md` — Spec deltas ### Stage 2: Apply (`/openspec.apply`) @@ -67,20 +68,23 @@ After deployment, archive the completed change: 1. Moves `changes//` to `changes/archive/YYYY-MM-DD-/` 2. Updates source-of-truth specs if capabilities changed -3. Validates the archived change +3. Validates the archived change with `openspec validate --strict` + +**CLI command:** `openspec archive --yes` (use `--skip-specs` for tooling-only changes that don't affect capabilities) ## Maestro-Specific Commands -### `/openspec.implement` - Generate Auto Run Documents +### `/openspec.implement` — Generate Auto Run Documents Bridges OpenSpec with Maestro's Auto Run: 1. Reads the proposal and tasks from a change -2. Converts tasks into Auto Run document format -3. Saves to `Auto Run Docs/` with task checkboxes -4. Supports worktree mode for parallel execution +2. Converts tasks into Auto Run document format with phases +3. Saves to `Auto Run Docs/` with task checkboxes (filename: `OpenSpec--Phase-XX-[Description].md`) +4. Preserves task IDs (T001, T002, etc.) for traceability +5. Groups related tasks into logical phases (5–15 tasks each) -### `/openspec.help` - Workflow Overview +### `/openspec.help` — Workflow Overview Get help with OpenSpec concepts and Maestro integration. @@ -126,14 +130,29 @@ The system SHALL provide... **Migration**: [How to handle] ``` +## OpenSpec CLI Commands + +The OpenSpec CLI provides these essential commands: + +| Command | Purpose | +|---------|---------| +| `openspec list` | Display active changes in `changes/` | +| `openspec list --specs` | List existing capability specs | +| `openspec show ` | View change or spec details | +| `openspec validate --strict` | Comprehensive validation | +| `openspec archive --yes` | Archive after deployment | +| `openspec spec list --long` | Enumerate all specifications | + ## Viewing & Managing Commands Access OpenSpec commands via **Settings → AI Commands** tab. Here you can: -- **View all commands** with descriptions -- **Check for Updates** to pull the latest workflow from GitHub -- **Expand commands** to see their full prompts -- **Customize prompts** (modifications are preserved across updates) +- **View all commands** — Click the chevron to expand and see the full prompt +- **Check for Updates** — Pull the latest workflow from GitHub +- **Edit prompts** — Customize prompts for your workflow +- **Reset to default** — Restore modified prompts to bundled version + +Commands marked with a **Maestro** badge are Maestro-specific additions to the upstream workflow. OpenSpec commands in the AI Commands panel @@ -150,9 +169,10 @@ OpenSpec prompts are synced from the [Fission-AI/OpenSpec repository](https://gi ## Tips for Best Results -- **Proposal first** - Never start implementation without an approved proposal -- **Keep changes focused** - One logical change per proposal -- **Use meaningful IDs** - `add-user-auth` not `change-1` -- **Include scenarios** - Every requirement needs at least one `#### Scenario:` -- **Validate often** - Run `openspec validate --strict` before sharing -- **Archive promptly** - Archive changes after deployment to keep `changes/` clean +- **Proposal first** — Never start implementation without an approved proposal +- **Keep changes focused** — One logical change per proposal +- **Use verb-led IDs** — `add-user-auth`, `update-api-schema`, `remove-legacy-handler` +- **Include scenarios** — Every requirement needs at least one `#### Scenario:` block +- **Check existing work** — Run `openspec list` before creating proposals to avoid conflicts +- **Validate early** — Run `openspec validate --strict` before sharing +- **Archive promptly** — Archive changes after deployment to keep `changes/` clean From bb0debef3d5f3ad4905bb77ba7e59f28aa5442bf Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 05:54:08 -0600 Subject: [PATCH 05/14] MAESTRO: Fix playbook-exchange.md documentation inaccuracies - Fixed cache TTL from 5 minutes to 6 hours (matching source code) - Fixed button label from "Playbook Exchange" to "Exchange" (matching UI) - Added Cmd+F/Ctrl+F search shortcut - Added detail view navigation shortcuts (document nav, page scroll, home/end) - Added browse folder feature documentation - Added assets subfolder support documentation - Added SSH remote session import note - Added help button and GitHub submission link documentation - Expanded keyboard shortcuts into separate List View and Detail View tables - Changed list formatting to em-dashes for consistency --- docs/playbook-exchange.md | 78 +++++++++++++++++++++++++++------------ 1 file changed, 55 insertions(+), 23 deletions(-) diff --git a/docs/playbook-exchange.md b/docs/playbook-exchange.md index ac4e568b..7202e8f8 100644 --- a/docs/playbook-exchange.md +++ b/docs/playbook-exchange.md @@ -9,19 +9,20 @@ The Playbook Exchange is a curated collection of community-contributed playbooks ## Opening the Exchange Open the Playbook Exchange using: -- **Quick Actions**: `Cmd+K` → search "Playbook Exchange" -- **Auto Run panel**: Click the **Playbook Exchange** button +- **Quick Actions** — `Cmd+K` / `Ctrl+K` → search "Playbook Exchange" +- **Auto Run panel** — Click the **Exchange** button (grid icon) ## Browsing Playbooks The exchange displays playbooks in a searchable grid organized by category: -- **Category tabs** filter playbooks by type (Development, Security, DevOps, etc.) -- **Search** filters by title, description, and tags -- **Arrow keys** navigate between tiles -- **Enter** opens the detail view for the selected playbook +- **Category tabs** — Filter playbooks by type (Development, Security, DevOps, etc.) +- **Search** — Filters by title, description, and tags +- **Arrow keys** — Navigate between tiles +- **Enter** — Open the detail view for the selected playbook +- **`Cmd+F` / `Ctrl+F`** — Focus the search input -Use `Cmd+Shift+[` / `Cmd+Shift+]` to quickly switch between category tabs. +Use `Cmd+Shift+[` / `Cmd+Shift+]` (`Ctrl+Shift+[/]` on Windows/Linux) to quickly switch between category tabs. Playbook Exchange browsing view @@ -29,12 +30,20 @@ Use `Cmd+Shift+[` / `Cmd+Shift+]` to quickly switch between category tabs. ## Playbook Details -Clicking a playbook tile opens the detail view where you can: +Clicking a playbook tile (or pressing `Enter`) opens the detail view where you can: -- **Read the README** — full documentation for the playbook -- **Preview documents** — browse individual task documents before importing -- **View metadata** — author, tags, loop settings, and document list -- **Set import folder** — customize the target folder name +- **Read the README** — Full documentation for the playbook +- **Preview documents** — Browse individual task documents before importing; use the dropdown or click document names in the sidebar +- **View metadata** — Author (with link if available), tags, loop settings, last updated date, and document list +- **Set import folder** — Customize the target folder name (relative to Auto Run folder or absolute path) +- **Browse for folder** — Click the folder icon to select a custom location (local sessions only) + +### Detail View Navigation + +- **`Cmd+Shift+[/]`** — Navigate to previous/next document (wraps around, includes README) +- **`Opt+Up/Down`** — Page up/down in the document preview +- **`Cmd+Up/Down`** — Scroll to top/bottom of document preview +- **`Esc`** — Return to the playbook grid Playbook Exchange detail view @@ -43,31 +52,54 @@ Clicking a playbook tile opens the detail view where you can: ## Importing a Playbook 1. Open the detail view for a playbook -2. Optionally edit the **Import to folder** field (defaults to `category/title` slug) +2. Optionally edit the **Import to folder** field (defaults to `category/title` slug, e.g., `development/code-review`) 3. Click **Import Playbook** The import creates: - A subfolder in your Auto Run folder with the playbook name -- All markdown documents copied to that folder +- All markdown task documents copied to that folder +- An `assets/` subfolder with any supporting files (configs, scripts, templates) if the playbook includes them - A saved playbook configuration with loop settings and document order After import, the playbook is immediately available in your **Load Playbook** dropdown in the Auto Run panel. + +For SSH remote sessions, playbooks can be imported directly to the remote host. The folder browse button is disabled for remote sessions—enter the target path manually instead. + + ## Exchange Data -Playbooks are fetched from the [Maestro-Playbooks](https://github.com/pedramamini/Maestro-Playbooks) GitHub repository. The manifest is cached locally for 5 minutes to minimize API calls. +Playbooks are fetched from the [Maestro-Playbooks](https://github.com/pedramamini/Maestro-Playbooks) GitHub repository. The manifest is cached locally for 6 hours to minimize API calls. -- **Cache indicator** shows whether data is from cache and how old it is -- **Refresh button** forces a fresh fetch from GitHub +- **Cache indicator** — Shows whether data is from cache and how old it is (e.g., "Cached 2h ago" or "Live") +- **Refresh button** — Forces a fresh fetch from GitHub, bypassing the cache ## Contributing Playbooks -Want to share your playbooks with the community? See the [Maestro-Playbooks repository](https://github.com/pedramamini/Maestro-Playbooks) for contribution guidelines. +Want to share your playbooks with the community? You can contribute in two ways: + +1. **From the Exchange** — Click the "Submit Playbook via GitHub" link in the header +2. **Directly on GitHub** — Submit a pull request to the [Maestro-Playbooks repository](https://github.com/pedramamini/Maestro-Playbooks) + +Click the **?** help button in the Exchange header for more information about contributing. ## Keyboard Shortcuts -| Action | Key | -|--------|-----| -| Navigate tiles | Arrow keys | -| Open detail view | `Enter` | -| Close / Back | `Esc` | +### List View + +| Action | macOS | Windows/Linux | +|--------|-------|---------------| +| Navigate tiles | Arrow keys | Arrow keys | +| Open detail view | `Enter` | `Enter` | +| Focus search | `Cmd+F` | `Ctrl+F` | +| Switch category tab | `Cmd+Shift+[/]` | `Ctrl+Shift+[/]` | +| Close modal | `Esc` | `Esc` | + +### Detail View + +| Action | macOS | Windows/Linux | +|--------|-------|---------------| +| Previous/next document | `Cmd+Shift+[/]` | `Ctrl+Shift+[/]` | +| Page up/down | `Opt+Up/Down` | `Alt+Up/Down` | +| Scroll to top/bottom | `Cmd+Up/Down` | `Ctrl+Up/Down` | +| Back to list | `Esc` | `Esc` | From 2b2bd286f22501406ccd43f41b6f6798c4b46e26 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 05:56:27 -0600 Subject: [PATCH 06/14] MAESTRO: Fix provider-nuances.md documentation inaccuracies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - Fixed Claude Code model selection: was incorrectly documented as supported via --model flag, but source shows supportsModelSelection: false (configured via Anthropic account) - Changed "OpenAI Codex" to "Codex (OpenAI)" throughout for consistency - Fixed Codex slash commands: changed from ⚠️ to ❌ since they don't work in exec mode which Maestro uses - Updated Codex slash commands link to official OpenAI docs - Fixed OpenCode slash commands: changed from "Not investigated" to "Not supported" per source code - Enhanced OpenCode note to mention OPENCODE_CONFIG_CONTENT env var for YOLO - Added "Context operations" row for all providers (merge/export/transfer) - Added "Thinking display" row for all providers documenting streaming output - Updated description frontmatter for consistent naming --- docs/provider-nuances.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/provider-nuances.md b/docs/provider-nuances.md index f7fdf925..23c7c618 100644 --- a/docs/provider-nuances.md +++ b/docs/provider-nuances.md @@ -1,6 +1,6 @@ --- title: Provider Nuances -description: Feature differences between Claude Code, OpenAI Codex, and OpenCode providers. +description: Feature differences between Claude Code, Codex (OpenAI), and OpenCode providers. icon: puzzle --- @@ -15,22 +15,26 @@ Each AI provider has unique capabilities and limitations. Maestro adapts its UI | Read-only mode | ✅ `--permission-mode plan` | | Slash commands | ⚠️ Batch-mode commands only ([details](/slash-commands#agent-native-commands)) | | Cost tracking | ✅ Full cost breakdown | -| Model selection | ✅ `--model` flag (via custom CLI args) | +| Model selection | ❌ Configured via Anthropic account | +| Context operations | ✅ Merge, export, and transfer | +| Thinking display | ✅ Streaming assistant messages | -## OpenAI Codex +## Codex (OpenAI) | Feature | Support | |---------|---------| | Image attachments | ⚠️ New sessions only (not on resume) | | Session resume | ✅ `exec resume ` | | Read-only mode | ✅ `--sandbox read-only` | -| Slash commands | ⚠️ Interactive TUI only (not in exec mode) | +| Slash commands | ❌ Interactive TUI only (not in exec mode) | | Cost tracking | ❌ Token counts only (no pricing) | | Model selection | ✅ `-m, --model` flag | +| Context operations | ✅ Merge, export, and transfer | +| Thinking display | ✅ Reasoning tokens (o3/o4-mini) | **Notes**: - Codex's `resume` subcommand doesn't accept the `-i/--image` flag. Images can only be attached when starting a new session. Maestro hides the attach image button when resuming Codex sessions. -- Codex has [slash commands](https://github.com/openai/codex/blob/main/docs/slash_commands.md) (`/compact`, `/undo`, `/diff`, etc.) but they only work in interactive TUI mode, not in `exec` mode which Maestro uses. +- Codex has [slash commands](https://developers.openai.com/codex/cli/slash-commands) (`/compact`, `/diff`, `/model`, etc.) but they only work in interactive TUI mode, not in `exec` mode which Maestro uses. ## OpenCode @@ -39,8 +43,10 @@ Each AI provider has unique capabilities and limitations. Maestro adapts its UI | Image attachments | ✅ New and resumed sessions | | Session resume | ✅ `--session` flag | | Read-only mode | ✅ `--agent plan` | -| Slash commands | ❌ Not investigated | +| Slash commands | ❌ Not supported | | Cost tracking | ✅ Per-step costs | | Model selection | ✅ `--model provider/model` | +| Context operations | ✅ Merge, export, and transfer | +| Thinking display | ✅ Streaming text chunks | -**Note**: OpenCode uses the `run` subcommand which auto-approves all permissions (similar to Codex's YOLO mode). +**Note**: OpenCode uses the `run` subcommand which auto-approves all permissions (similar to Codex's YOLO mode). Maestro enables this via the `OPENCODE_CONFIG_CONTENT` environment variable. From b8493fe08def767e7a9ba6b5768c7bf61154c5a0 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:01:18 -0600 Subject: [PATCH 07/14] MAESTRO: Fix remote-access.md documentation inaccuracies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix "Global Access" → "Live Sessions" (only live sessions accessible) - Rename "Static Port Configuration" → "Custom Port Configuration" to match UI - Correct port range from 1024-65535 to 1-65535 - Fix "Use Custom Port" → "Custom Port" toggle label - Add UUID clarification for security token - Expand Mobile Web Interface with Core Features, Gestures, Input subsections - Add Connection Handling section (auto-reconnect, offline mode, status) - Add notes, tips, and related links section - Use em-dashes for consistency with other documentation --- docs/remote-access.md | 92 ++++++++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 24 deletions(-) diff --git a/docs/remote-access.md b/docs/remote-access.md index ce3c4264..88631704 100644 --- a/docs/remote-access.md +++ b/docs/remote-access.md @@ -6,66 +6,110 @@ icon: wifi Maestro includes a built-in web server for mobile remote control: -1. **Automatic Security**: Web server runs on a random port with an auto-generated security token embedded in the URL -2. **QR Code Access**: Scan a QR code to connect instantly from your phone -3. **Global Access**: All sessions are accessible when the web interface is enabled - the security token protects access -4. **Remote Tunneling**: Access Maestro from anywhere via Cloudflare tunnel (requires `cloudflared` CLI) +1. **Automatic Security** — Web server runs on a random port with an auto-generated security token (UUID) embedded in the URL +2. **QR Code Access** — Scan a QR code to connect instantly from your phone +3. **Live Sessions** — Sessions marked as "live" become accessible through the web interface (protected by the security token) +4. **Remote Tunneling** — Access Maestro from anywhere via Cloudflare tunnel (requires `cloudflared` CLI) ## Mobile Web Interface -The mobile web interface provides: +The mobile web interface provides a comprehensive remote control experience: + +### Core Features - Real-time session monitoring and command input - Device color scheme preference support (light/dark mode) -- Connection status indicator with automatic reconnection -- Offline queue for commands typed while disconnected -- Swipe gestures for common actions -- Quick actions menu for the send button +- Connection status indicator with automatic reconnection (30-second countdown timer) +- Offline queue for commands typed while disconnected (persisted to localStorage, up to 50 commands) +- Multi-tab support with tab bar and tab search modal + +### Gestures and Navigation +- Swipe gestures (left/right/up/down) for common actions +- Pull-to-refresh functionality +- Long-press menu for mode switching (AI ↔ Terminal) + +### Input Features +- Recent command chips for quick access +- Slash command autocomplete +- Command history drawer ## Local Access (Same Network) -1. Click the "OFFLINE" button in the header to enable the web interface -2. The button changes to "LIVE" and shows a QR code overlay +1. Click the **OFFLINE** button in the Left Bar header to enable the web interface +2. The button changes to **LIVE** (pulsing) and a QR code overlay appears automatically 3. Scan the QR code or copy the secure URL to access from your phone on the same network + +The web interface uses your local IP address (e.g., `192.168.x.x`) for LAN accessibility. Both devices must be on the same network. + + ## Remote Access (Outside Your Network) To access Maestro from outside your local network (e.g., on mobile data or from another location): 1. Install cloudflared: `brew install cloudflared` (macOS) or [download for other platforms](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) -2. Enable the web interface (OFFLINE → LIVE) -3. Toggle "Remote Access" in the Live overlay -4. A secure Cloudflare tunnel URL will be generated -5. Use the Local/Remote pill selector to switch between QR codes -6. The tunnel stays active as long as Maestro is running - no time limits, no account required +2. Enable the web interface (**OFFLINE** → **LIVE**) +3. Toggle **Remote Access** in the Live overlay panel +4. A secure Cloudflare tunnel URL (e.g., `https://abc123.trycloudflare.com`) will be generated within ~30 seconds +5. Use the **Local/Remote** pill selector to switch between QR codes +6. The tunnel stays active as long as Maestro is running — no time limits, no Cloudflare account required -## Static Port Configuration + +The Remote tab automatically activates when the tunnel connects successfully. + + +## Custom Port Configuration By default, Maestro assigns a **random port** each time the web server starts. This is a security-by-obscurity measure — attackers can't easily guess which port to target. -However, if you need a **fixed port** (e.g., for firewall rules, reverse proxies, or persistent tunnel configurations), you can enable static port mode: +However, if you need a **fixed port** (e.g., for firewall rules, reverse proxies, or persistent tunnel configurations), you can enable custom port mode: -1. Click the **OFFLINE** button to open the Live overlay -2. Toggle **Use Custom Port** to enable static port mode -3. Enter your desired port number (1024-65535) +1. Click the **LIVE** button to open the Live overlay panel +2. Toggle **Custom Port** to enable static port mode +3. Enter your desired port number (1–65535) 4. The server restarts automatically on the new port -**Use cases for static ports:** +**Use cases for custom ports:** - Punching a hole through a firewall or NAT - Configuring a reverse proxy (nginx, Caddy) - Setting up persistent SSH tunnels - Integration with home automation systems -**Security Trade-off**: Using a static port removes one layer of security-by-obscurity. The randomized port and auto-generated auth token in the URL work together to protect access. With a static port, you're relying solely on the auth token for security. +**Security Trade-off**: Using a custom port removes one layer of security-by-obscurity. The randomized port and auto-generated auth token in the URL work together to protect access. With a custom port, you're relying solely on the auth token for security. -**Recommendations when using static ports:** +**Recommendations when using custom ports:** - Use Cloudflare tunnel for remote access instead of exposing ports directly - Ensure your network firewall is properly configured - Consider additional authentication at the network level +## Connection Handling + +The mobile interface includes robust connection management: + +### Automatic Reconnection +- When disconnected, a 30-second countdown timer displays before automatic reconnection +- Manual **Retry** button available for immediate reconnection +- Reconnection attempts counter shows progress (e.g., "Attempt 3 of 10") + +### Offline Mode +- Commands typed while offline are queued (up to 50 commands) +- Queued commands are persisted to localStorage and survive page reloads +- Commands automatically send when connection is restored +- An **Offline Queue Banner** shows the number of pending commands + +### Connection Status Indicator +- Displays as a dismissible banner when connection is lost +- Shows different states: **Connecting**, **Authenticating**, **Disconnected**, **No internet** +- Expandable error details for troubleshooting + ## Screenshots ![Mobile chat](./screenshots/mobile-chat.png) ![Mobile groups](./screenshots/mobile-groups.png) ![Mobile history](./screenshots/mobile-history.png) + +## Related + +- [Configuration](/configuration) — General settings including web interface options +- [SSH Remote Execution](/ssh-remote-execution) — Running Maestro on remote servers From cb22f745164ff9dd1bdb7bb87f31042974c9b511 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:02:44 -0600 Subject: [PATCH 08/14] MAESTRO: Fix screenshots.md documentation inaccuracies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated theme count from 12 to 18 in description - Added 4 missing light themes: Solarized, One Light, Gruvbox Light, Catppuccin Latte - Fixed "GitHub Light" to "GitHub" to match actual theme name - Fixed Settings path from "Appearance → Theme" to "Themes tab" - Added Custom Theme section documenting the theme builder --- docs/screenshots.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/screenshots.md b/docs/screenshots.md index 924a87b4..22241157 100644 --- a/docs/screenshots.md +++ b/docs/screenshots.md @@ -1,10 +1,10 @@ --- title: Themes Gallery -description: Preview Maestro's beautiful themes including Dracula, Nord, Tokyo Night, and custom Vibe themes. +description: Preview Maestro's 18 beautiful themes including Dracula, Nord, Tokyo Night, and custom Vibe themes. icon: palette --- -Maestro ships with carefully crafted themes across three categories. Screenshots below show each theme in action. +Maestro ships with 18 carefully crafted themes across three categories, plus a Custom theme builder. Screenshots below show each theme in action. ## Available Themes For a screenshot example of every option, see [THEMES.md](https://github.com/pedramamini/Maestro/blob/main/THEMES.md) on GitHub. You can also flip through the available themes at [RunMaestro.ai](https://runmaestro.ai). @@ -20,7 +20,11 @@ For a screenshot example of every option, see [THEMES.md](https://github.com/ped - **Gruvbox Dark** — Retro groove with warm earth tones ### Light Themes -- **GitHub Light** — GitHub's clean light mode +- **GitHub** — GitHub's clean light mode +- **Solarized** — Precision colors for readability +- **One Light** — Atom's light theme with magenta accents +- **Gruvbox Light** — Retro groove in light mode +- **Catppuccin Latte** — Soothing pastel light theme - **Ayu Light** — Bright, modern light theme ### Vibe Themes @@ -30,6 +34,9 @@ Custom themes with unique personality: - **Dre Synth** — Cyberpunk cyan and magenta - **InQuest** — Minimal black with crimson accents +### Custom Theme +Build your own theme using the Custom Theme Builder with import/export support. + ## Changing Themes 1. Press `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux) @@ -37,4 +44,4 @@ Custom themes with unique personality: 3. Use arrow keys to preview themes live 4. Press `Enter` to apply -Or go to **Settings** (`Cmd+,`) → **Appearance** → **Theme**. +Or go to **Settings** (`Cmd+,`) → **Themes** tab. From 630b710586bd03b42a5743836b13b397ec778c1c Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:06:19 -0600 Subject: [PATCH 09/14] MAESTRO: Fix slash-commands.md documentation inaccuracies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add "Built-in Maestro Commands" section documenting /history and /wizard - Fix Settings path: "Settings > Custom AI Commands" → "Settings → AI Commands" - Fix {{LOOP_NUMBER}} description: "starts at 1" → "5-digit padded: 00001, 00002" - Fix {{TOOL_TYPE}} examples to include "aider" - Complete Spec-Kit commands table (was missing 4 commands, now 10 total) - Reorder OpenSpec commands and update descriptions to match source - Remove non-existent /context command from Claude Code supported list - Clarify Agent Native Commands discovery via system/init event --- docs/slash-commands.md | 47 ++++++++++++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 11 deletions(-) diff --git a/docs/slash-commands.md b/docs/slash-commands.md index b6c87f95..63d31a00 100644 --- a/docs/slash-commands.md +++ b/docs/slash-commands.md @@ -6,9 +6,22 @@ icon: terminal Maestro includes an extensible slash command system with autocomplete. Type `/` in the input area to open the autocomplete menu, use arrow keys to navigate, and press `Tab` or `Enter` to select. +## Built-in Maestro Commands + +Maestro provides built-in slash commands that are handled internally (not sent to the AI agent): + +| Command | Description | +|---------|-------------| +| `/history` | Generate a synopsis of recent work and add to the History panel | +| `/wizard` | Start the planning wizard for Auto Run documents | + + +The `/wizard` command can take optional natural language input: `/wizard add user authentication feature` to provide initial context. + + ## Custom AI Commands -Create your own slash commands in **Settings > Custom AI Commands**. Each command has a trigger (e.g., `/deploy`) and a prompt that gets sent to the AI agent. +Create your own slash commands in **Settings → AI Commands**. Each command has a trigger (e.g., `/deploy`) and a prompt that gets sent to the AI agent. Commands support **template variables** that are automatically substituted at runtime: @@ -21,7 +34,7 @@ Commands support **template variables** that are automatically substituted at ru | `{{AGENT_GROUP}}` | Agent's group name (if grouped) | | `{{AGENT_SESSION_ID}}` | Agent session ID (for conversation continuity) | | `{{TAB_NAME}}` | Custom tab name (alias: `SESSION_NAME`) | -| `{{TOOL_TYPE}}` | Agent type (claude-code, codex, opencode) | +| `{{TOOL_TYPE}}` | Agent type (claude-code, codex, opencode, aider) | ### Path Variables @@ -36,7 +49,7 @@ Commands support **template variables** that are automatically substituted at ru |----------|-------------| | `{{DOCUMENT_NAME}}` | Current Auto Run document name (without .md) | | `{{DOCUMENT_PATH}}` | Full path to current Auto Run document | -| `{{LOOP_NUMBER}}` | Current loop iteration (starts at 1) | +| `{{LOOP_NUMBER}}` | Current loop iteration (5-digit padded: 00001, 00002, etc.) | ### Date/Time Variables @@ -70,7 +83,20 @@ Summarize what I worked on yesterday and suggest priorities for today. ## Spec-Kit Commands -Maestro bundles [GitHub's spec-kit](https://github.com/github/spec-kit) methodology for structured feature development. Commands include `/speckit.constitution`, `/speckit.specify`, `/speckit.clarify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement`. +Maestro bundles [GitHub's spec-kit](https://github.com/github/spec-kit) methodology for structured feature development: + +| Command | Description | +|---------|-------------| +| `/speckit.help` | Learn how to use spec-kit with Maestro | +| `/speckit.constitution` | Create or update the project constitution | +| `/speckit.specify` | Create or update feature specification | +| `/speckit.clarify` | Identify underspecified areas and ask clarification questions | +| `/speckit.plan` | Execute implementation planning workflow | +| `/speckit.tasks` | Generate actionable, dependency-ordered tasks | +| `/speckit.analyze` | Cross-artifact consistency and quality analysis | +| `/speckit.checklist` | Generate custom checklist for feature | +| `/speckit.taskstoissues` | Convert tasks to GitHub issues | +| `/speckit.implement` | Execute tasks using Maestro Auto Run with worktree support | See [Spec-Kit Commands](/speckit-commands) for the complete workflow guide. @@ -80,17 +106,17 @@ Maestro bundles [OpenSpec](https://github.com/Fission-AI/OpenSpec) for spec-driv | Command | Description | |---------|-------------| -| `/openspec.proposal` | Create a change proposal with spec deltas before writing code | -| `/openspec.apply` | Implement an approved proposal by following the tasks | -| `/openspec.archive` | Archive completed changes after deployment | -| `/openspec.implement` | Generate Auto Run documents from a proposal (Maestro-specific) | -| `/openspec.help` | Get help with OpenSpec workflow and concepts | +| `/openspec.help` | Learn how to use OpenSpec with Maestro | +| `/openspec.proposal` | Create a change proposal with specs, tasks, and optional design docs | +| `/openspec.apply` | Implement an approved change proposal by executing tasks | +| `/openspec.archive` | Archive a completed change after deployment | +| `/openspec.implement` | Convert OpenSpec tasks to Maestro Auto Run documents | See [OpenSpec Commands](/openspec-commands) for the complete workflow guide and directory structure. ## Agent Native Commands -When using Claude Code, Maestro automatically discovers and displays the agent's native slash commands in the autocomplete menu. These appear with a "Claude Code command" label to distinguish them from Maestro's custom commands. +When using Claude Code, Maestro automatically discovers and displays the agent's native slash commands in the autocomplete menu. These commands are sent via the `system/init` event when Claude Code starts and appear with a "Claude Code command" label to distinguish them from Maestro's custom commands. ### Supported in Batch Mode @@ -99,7 +125,6 @@ Claude Code runs in batch/print mode within Maestro, which means only certain na | Command | Description | |---------|-------------| | `/compact` | Compact conversation history to reduce context usage | -| `/context` | Manage conversation context | | `/cost` | Show token usage and cost for the session | | `/init` | Initialize a CLAUDE.md file in the project | | `/pr-comments` | Address PR review comments | From f8c8bfc0e93dd0c09a54740819946d191da64240 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:09:50 -0600 Subject: [PATCH 10/14] MAESTRO: Fix speckit-commands.md documentation inaccuracies - Fix intro claiming prompts are "automatically synced" (they require manual Check for Updates) - Add Storage Location row to comparison table (.specify/ vs Auto Run Docs/Initiation/) - Expand Viewing & Managing Commands section with Reset to Default and badge indicator - Add exact file paths for all commands: - /speckit.constitution: .specify/memory/constitution.md - /speckit.specify: specs/-/spec.md - /speckit.clarify: Updates spec.md with Clarifications section - /speckit.plan: plan.md, research.md, data-model.md, contracts/, quickstart.md - /speckit.tasks: tasks.md with phase structure - /speckit.implement: Auto Run Docs/SpecKit--Phase-XX-[Description].md - Rewrite /speckit.checklist section to explain "unit tests for requirements" concept - Add /speckit.taskstoissues requirements (gh CLI + GitHub MCP server tool) - Rename "Auto-Updates" to "Updating Commands" with accurate manual process description - Expand Tips section with additional actionable advice --- docs/speckit-commands.md | 113 ++++++++++++++++++++++++++++----------- 1 file changed, 82 insertions(+), 31 deletions(-) diff --git a/docs/speckit-commands.md b/docs/speckit-commands.md index 2b7e937d..c36f2823 100644 --- a/docs/speckit-commands.md +++ b/docs/speckit-commands.md @@ -4,7 +4,7 @@ description: Structured specification workflow for AI-assisted development using icon: file-text --- -Spec-Kit is a structured specification workflow from [GitHub's spec-kit project](https://github.com/github/spec-kit) that helps teams create clear, actionable specifications before implementation. Maestro bundles these commands and keeps them updated automatically. +Spec-Kit is a structured specification workflow from [GitHub's spec-kit project](https://github.com/github/spec-kit) that helps teams create clear, actionable specifications before implementation. Maestro bundles these commands and you can check for updates manually via Settings. ![Spec-Kit Commands in Settings](./screenshots/speckit-commands.png) @@ -19,6 +19,7 @@ Maestro offers two paths to structured development: | **Output** | Constitution, specs, tasks → Auto Run docs | Phase 1 Auto Run document | | **Control** | Full control at each step | Streamlined, opinionated | | **Learning Curve** | Moderate | Low | +| **Storage Location** | `.specify/` directory in project root | `Auto Run Docs/Initiation/` | **Use Spec-Kit when:** - You want fine-grained control over specification phases @@ -37,10 +38,12 @@ Both approaches ultimately produce markdown documents for Auto Run execution. Access Spec-Kit commands via **Settings → AI Commands** tab. Here you can: -- **View all commands** with descriptions -- **Check for Updates** to pull the latest prompts from GitHub -- **Expand commands** to see their full prompts -- **Customize prompts** (modifications are preserved across updates) +- **View all commands** — See descriptions and expand to view full prompts +- **Check for Updates** — Manually pull the latest prompts from GitHub releases +- **Edit prompts** — Customize any command (modifications are preserved across updates) +- **Reset to Default** — Restore a modified prompt to the bundled version + +Commands marked with a Maestro badge (`/speckit.help`, `/speckit.implement`) are Maestro-specific and not updated from upstream. ## Core Workflow (Recommended Order) @@ -48,71 +51,119 @@ Access Spec-Kit commands via **Settings → AI Commands** tab. Here you can: Start here to establish your project's foundational values, constraints, and guidelines. The constitution guides all subsequent specifications and ensures consistency across features. -**Creates:** A constitution document with core principles, technical constraints, and team conventions. +**Creates:** `.specify/memory/constitution.md` — A versioned constitution document with core principles, technical constraints, team conventions, and governance rules. ### 2. `/speckit.specify` — Create Feature Specification -Define the feature you want to build with clear requirements, acceptance criteria, and boundaries. +Define the feature you want to build with clear requirements, acceptance criteria, and boundaries. Creates a new numbered Git branch and initializes the spec directory structure. -**Creates:** A detailed feature specification with scope, requirements, and success criteria. +**Creates:** `specs/-/spec.md` — A detailed feature specification with scope, functional requirements, user scenarios, and success criteria. Also creates a `checklists/requirements.md` validation checklist. ### 3. `/speckit.clarify` — Identify Gaps -Review your specification for ambiguities, missing details, and edge cases. The AI asks clarifying questions to strengthen the spec before implementation. +Review your specification for ambiguities, missing details, and edge cases. The AI asks up to 5 targeted clarification questions sequentially, encoding answers directly into the spec. -**Tip:** Run `/speckit.clarify` multiple times — each pass catches different gaps. +**Updates:** `specs/-/spec.md` — Adds a `## Clarifications` section with session-dated answers, and propagates clarifications to relevant spec sections. + +**Tip:** Run `/speckit.clarify` multiple times — each pass catches different gaps. Use early termination signals ("done", "good", "no more") to stop questioning. ### 4. `/speckit.plan` — Implementation Planning -Convert your specification into a high-level implementation plan with phases and milestones. +Convert your specification into a high-level implementation plan. Includes technical context, constitution compliance checks, and multi-phase design workflow. -**Creates:** A phased implementation roadmap with dependencies and risk areas. +**Creates:** Multiple artifacts in the feature directory: +- `plan.md` — Implementation plan with phases and milestones +- `research.md` — Resolved unknowns and technology decisions (Phase 0) +- `data-model.md` — Entities, fields, and relationships (Phase 1) +- `contracts/` — API contracts in OpenAPI/GraphQL format (Phase 1) +- `quickstart.md` — Getting started guide (Phase 1) ### 5. `/speckit.tasks` — Generate Tasks -Break your plan into specific, actionable tasks with dependencies clearly mapped. +Break your plan into specific, actionable tasks with dependencies clearly mapped. Tasks are organized by user story and structured in phases. -**Creates:** A dependency-ordered task list ready for execution. +**Creates:** `specs/-/tasks.md` — A dependency-ordered task list with: +- **Phase 1:** Setup (project initialization) +- **Phase 2:** Foundational (blocking prerequisites) +- **Phase 3+:** User stories in priority order (P1, P2, P3...) +- **Final Phase:** Polish & cross-cutting concerns + +Each task has an ID (T001, T002...), optional `[P]` marker for parallelizable tasks, and `[US#]` labels linking to user stories. ### 6. `/speckit.implement` — Execute with Auto Run **Maestro-specific command.** Converts your tasks into Auto Run documents that Maestro can execute autonomously. This bridges spec-kit's structured approach with Maestro's multi-agent capabilities. -**Creates:** Markdown documents in `Auto Run Docs/` with task checklists. +**Creates:** Markdown documents in `Auto Run Docs/` with naming pattern: +``` +Auto Run Docs/SpecKit--Phase-01-[Description].md +Auto Run Docs/SpecKit--Phase-02-[Description].md +``` + +Each phase document is self-contained, includes Spec Kit context references, preserves task IDs (T001, T002...) and user story markers ([US1], [US2]) for traceability. ## Analysis & Quality Commands ### `/speckit.analyze` — Cross-Artifact Analysis -Verify consistency across your constitution, specifications, and tasks. Catches contradictions and gaps between documents. +Verify consistency across your constitution, specifications, and tasks. Performs a read-only analysis that catches: +- **Duplications** — Near-duplicate requirements +- **Ambiguities** — Vague adjectives lacking measurable criteria +- **Underspecification** — Missing acceptance criteria or undefined components +- **Constitution violations** — Conflicts with project principles (always CRITICAL severity) +- **Coverage gaps** — Requirements without tasks, or orphaned tasks -### `/speckit.checklist` — Generate QA Checklist +**Outputs:** A structured Markdown report with severity ratings (Critical/High/Medium/Low), coverage metrics, and suggested next actions. Does not modify any files. -Create a custom checklist for your feature based on the specification. Useful for QA, code review, and acceptance testing. +### `/speckit.checklist` — Requirements Quality Validation + +Generate "unit tests for requirements" — checklists that validate the *quality* of your requirements, not the implementation. Each checklist item tests whether requirements are complete, clear, consistent, and measurable. + +**Creates:** `specs/-/checklists/.md` (e.g., `ux.md`, `api.md`, `security.md`) + +Example items: +- "Are visual hierarchy requirements defined with measurable criteria?" [Completeness] +- "Is 'fast loading' quantified with specific timing thresholds?" [Clarity] +- "Are error handling requirements defined for all API failure modes?" [Gap] + +**Note:** This is NOT for QA testing implementation — it validates that requirements are well-written before implementation begins. ### `/speckit.taskstoissues` — Export to GitHub Issues -Convert your tasks directly into GitHub Issues. Requires `gh` CLI to be installed and authenticated. +Convert your tasks directly into GitHub Issues. + +**Requirements:** +- `gh` CLI installed and authenticated +- GitHub MCP server tool (`github/github-mcp-server/issue_write`) +- Remote must be a GitHub URL + +**Caution:** Only creates issues in the repository matching your Git remote — will refuse to create issues elsewhere. ## Getting Help -Run `/speckit.help` to get an overview of the workflow and tips for best results. +Run `/speckit.help` to get an overview of the workflow and tips for best results. This Maestro-specific command provides: +- Command overview with recommended workflow order +- Integration tips for Auto Run +- Links to upstream documentation -## Auto-Updates +## Updating Commands -Spec-Kit prompts are automatically synced from the [GitHub spec-kit repository](https://github.com/github/spec-kit): +Spec-Kit prompts can be updated from the [GitHub spec-kit repository](https://github.com/github/spec-kit) releases: 1. Open **Settings → AI Commands** -2. Click **Check for Updates** -3. New commands and prompt improvements are downloaded -4. Your custom modifications are preserved +2. Click **Check for Updates** button +3. Latest prompts are downloaded from the most recent GitHub release +4. Your custom modifications are preserved — edited prompts are not overwritten -The version number and last update date are shown at the top of the Spec Kit Commands section. +The version number (e.g., `v0.0.90`) and last refresh date are shown at the top of the Spec Kit Commands section. + +**Note:** Custom Maestro commands (`/speckit.help`, `/speckit.implement`) are bundled with Maestro and not updated from upstream. ## Tips for Best Results -- **Start with constitution** — Even for small projects, defining principles helps maintain consistency -- **Iterate on specifications** — Use `/speckit.clarify` multiple times to refine your spec -- **Keep specs focused** — One feature per specification cycle works best -- **Review before implementing** — Use `/speckit.analyze` to catch issues early -- **Leverage parallelism** — With Maestro, run multiple spec-kit workflows simultaneously across different agents +- **Start with constitution** — Even for small projects, defining principles helps maintain consistency and catch violations early +- **Iterate on specifications** — Use `/speckit.clarify` multiple times to refine your spec; accept recommended answers for faster iteration +- **Keep specs focused** — One feature per specification cycle works best; use numbered branches (`1-feature-name`, `2-other-feature`) +- **Review before implementing** — Use `/speckit.analyze` after `/speckit.tasks` to catch issues before coding +- **Validate requirements first** — Use `/speckit.checklist` to verify requirements are clear and complete before implementation +- **Leverage parallelism** — With Maestro, run multiple spec-kit workflows simultaneously across different agents using worktrees From 6e4d60a69742f025be7e4d46aebd0d30b7d80795 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:13:45 -0600 Subject: [PATCH 11/14] MAESTRO: Fix ssh-remote-execution.md documentation inaccuracies - Corrected Per-Agent Configuration to Per-Session Configuration (SSH is session-level only, not per-agent with global defaults) - Fixed dropdown options from incorrect "Use Global Default"/"Force Local" to actual "Local Execution"/[Remote Name] options - Removed incorrect "Resolution Order" section (5-level priority algorithm doesn't exist in source code) - Clarified global default is a visual indicator, not automatic - Removed incorrect PTY limitation claim (PTY IS available via RequestTTY: 'force' and -tt flags) - Updated Limitations section with accurate shell initialization info - Changed hyphens to em-dashes for consistency --- docs/ssh-remote-execution.md | 62 ++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/ssh-remote-execution.md b/docs/ssh-remote-execution.md index 6f61538a..a6f6ad3b 100644 --- a/docs/ssh-remote-execution.md +++ b/docs/ssh-remote-execution.md @@ -15,7 +15,7 @@ SSH Remote Execution wraps agent commands in SSH, executing them on a configured - Access tools or SDKs installed only on specific servers - Work with codebases that require particular OS or architecture - Execute agents in secure/isolated environments -- Coordinate multiple agents across different machines in [Group Chat](./group-chat) +- Coordinate multiple agents across different machines in [Group Chat](/group-chat) - Run Auto Run playbooks on remote projects ## Configuring SSH Remotes @@ -88,8 +88,8 @@ With the above config, you can: #### Field Labels When using SSH config mode, field labels indicate which values are optional: -- **Username (optional override)** — leave empty to use SSH config's `User` -- **Private Key Path (optional override)** — leave empty to use SSH config's `IdentityFile` +- **Username (optional)** — leave empty to use SSH config's `User` +- **Private Key Path (optional)** — leave empty to use SSH config's `IdentityFile` #### Clearing SSH Config Mode @@ -109,39 +109,40 @@ A successful test shows the remote hostname. Failed tests display specific error ### Setting a Global Default Click the checkmark icon next to any remote to set it as the **global default**. When set: -- All agents use this remote by default -- Individual agents can override this setting -- The default badge appears next to the remote name +- The "Default" badge appears next to the remote name +- The default remote is highlighted in selection dropdowns +- New sessions still require explicit selection — the default serves as a visual indicator of your preferred remote -Click the checkmark again to clear the default and return to local execution. +Click the checkmark again to clear the default. -## Per-Agent Configuration + +The global default is a convenience marker, not an automatic setting. Each session must explicitly select an SSH remote via the "SSH Remote Execution" dropdown in the New Agent dialog or session configuration. + -Each agent can have its own SSH remote setting, overriding the global default. +## Per-Session Configuration -### Configuring an Agent +Each session can have its own SSH remote setting configured when creating the session or editing its configuration. -1. Open the agent's configuration panel (gear icon in session header, or via Settings → Agents) -2. Find the **SSH Remote Execution** dropdown -3. Select an option: +### Configuring a Session + +1. When creating a new agent session (via New Agent dialog or the wizard), find the **SSH Remote Execution** dropdown +2. Select an option: ![SSH Agent Mapping](./screenshots/ssh-agents-mapping.png) | Option | Behavior | |--------|----------| -| **Use Global Default** | Follows the global setting (shows which remote if one is set) | -| **Force Local Execution** | Always runs locally, ignoring any global default | -| **[Specific Remote]** | Always uses this remote, regardless of global setting | +| **Local Execution** | Runs the agent on your local machine (default) | +| **[Remote Name]** | Runs the agent on the specified SSH remote host | -### Resolution Order +### How It Works -When spawning an agent, Maestro resolves which SSH remote to use: +SSH remote execution is configured at the **session level**: -1. **Per-agent explicit remote** → Uses that specific remote -2. **Per-agent "Force Local"** → Runs locally (ignores global) -3. **Per-agent "Use Global Default"** → Falls through to global setting -4. **Global default set** → Uses the global default remote -5. **No global default** → Runs locally +- When you create a new session, you choose whether it runs locally or on a specific remote +- The configuration is saved with the session and persists across restarts +- Each session maintains its own SSH setting independently +- Changing a session's SSH remote requires editing the session configuration ## Status Visibility @@ -149,7 +150,7 @@ When a session is running via SSH remote, you can easily identify it: ![SSH Agent Status](./screenshots/ssh-agents-status.png) -- **REMOTE pill** — Appears in the Left Bar next to the agent, indicating it's configured for remote execution +- **REMOTE pill** — Appears in the Left Bar next to the session, indicating it's configured for remote execution - **Host name badge** — Displayed in the Main Panel header showing which SSH host the agent is running on (e.g., "PEDTOME") - **Agent type indicator** — Shows "claude-code (SSH)" to clarify the execution mode - Connection state reflects SSH connectivity @@ -231,11 +232,11 @@ This is especially useful for: ### Tips -- **Import from SSH config**: Use the dropdown when adding remotes to import from `~/.ssh/config`—saves time and keeps configuration consistent -- **Bastion hosts**: Use `ProxyJump` in your SSH config for multi-hop connections; Maestro inherits this automatically -- **Key management**: Use `ssh-agent` to avoid passphrase prompts -- **Keep-alive**: Configure `ServerAliveInterval` in SSH config for long sessions -- **Test manually first**: Verify `ssh host 'claude --version'` works before configuring in Maestro +- **Import from SSH config** — Use the dropdown when adding remotes to import from `~/.ssh/config`; saves time and keeps configuration consistent +- **Bastion hosts** — Use `ProxyJump` in your SSH config for multi-hop connections; Maestro inherits this automatically +- **Key management** — Use `ssh-agent` to avoid passphrase prompts +- **Keep-alive** — Configure `ServerAliveInterval` in SSH config for long sessions +- **Test manually first** — Verify `ssh host 'claude --version'` works before configuring in Maestro ## Security Considerations @@ -246,7 +247,6 @@ This is especially useful for: ## Limitations -- PTY (pseudo-terminal) features are not available over SSH -- Some interactive agent features may behave differently - Network latency affects perceived responsiveness - The remote host must have the agent CLI installed and configured +- Some shell initialization files (`.bashrc`, `.zshrc`) may not be fully sourced — agent commands use `$SHELL -lc` to ensure PATH availability from login profiles From 0b1e3872871d02abee5f8917c494c0dca42e103f Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:18:32 -0600 Subject: [PATCH 12/14] MAESTRO: Fix symphony.md documentation inaccuracies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Key fixes: - Corrected PR creation flow: uses deferred PR creation (on first commit), not immediate - Rewrote Task Claiming section to explain deferred flow: start → first commit creates PR → subsequent commits push - Added four modal tabs documentation (Projects, Active, History, Stats) - Added keyboard navigation: arrows, Enter, / for search, Cmd+Shift+[/] for documents - Expanded Active tab: status indicators, progress bar, token usage, controls, Check PR Status button - Expanded History tab: PR status, completion date, documents, cost, summary stats - Expanded Stats tab: overview metrics, repos contributed, streak tracking, achievements - Fixed branch naming to `symphony/{issue-number}-{short-id}` - Added `featured` and `addedAt` fields to JSON example - Added complete categories table with all 9 categories, labels, and emojis - Added cache TTL info (registry: 2hr, issues: 5min) --- docs/symphony.md | 87 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 27 deletions(-) diff --git a/docs/symphony.md b/docs/symphony.md index 93cb1980..4593d723 100644 --- a/docs/symphony.md +++ b/docs/symphony.md @@ -34,18 +34,24 @@ Maestro Symphony is a community-driven program that connects Maestro users with ## Browsing Projects -The Symphony modal shows registered open source projects in a tiled grid: +The Symphony modal has four tabs: **Projects**, **Active**, **History**, and **Stats**. + +### Projects Tab + +The Projects tab shows registered open source projects in a tiled grid: - **Category filters** — Filter by AI/ML, Developer Tools, etc. -- **Search** — Find projects by name or description +- **Search** — Find projects by name, description, or tags - **Project tiles** — Click to view available issues +- **Keyboard navigation** — Use arrow keys to navigate, Enter to select, `/` to focus search ![Symphony Project Details](./screenshots/symphony-details.png) Select a repository to see its available GitHub issues. Each issue shows: - Issue title and number - Number of Auto Run documents to process -- Document previews (expandable) +- Document previews with a dropdown selector (use `Cmd+Shift+[` / `Cmd+Shift+]` to cycle documents) +- Status indicator (available or in-progress with PR link) ## Starting a Contribution @@ -60,36 +66,41 @@ Configure your contribution: Click **Create Agent** and Maestro will: -1. Clone the repository to `~/Maestro-Symphony/{owner}-{repo}/` -2. Create a new branch for your contribution -3. Open a draft PR (claims the issue so others know it's in progress) -4. Copy the Auto Run documents to your session -5. Begin processing tasks automatically +1. Clone the repository to `~/Maestro-Symphony/{owner}-{repo}/` (default location, customizable) +2. Create a new branch (`symphony/{issue-number}-{short-id}`) +3. Set up Auto Run documents (external attachments downloaded to cache, repo docs referenced in place) +4. Begin processing tasks automatically +5. Create a draft PR on first commit (claims the issue so others know it's in progress) ## Tracking Contributions ### Active Tab View your in-progress Symphony sessions: -- Links to jump to the agent session -- Progress indicators for current document -- Links to draft PRs -- Cancel/abort controls +- Status indicators (Running, Paused, Creating PR, etc.) +- Progress bar showing documents completed vs. total +- Current document being processed +- Token usage (input/output tokens, estimated cost) +- Draft PR link (once created on first commit) +- Controls: Pause/Resume, Cancel, Finalize PR +- **Check PR Status** button to detect merged/closed PRs ### History Tab Review completed contributions: -- PR links with merge status -- Per-contribution statistics -- Time and tokens spent +- PR links with merge status (Open or Merged) +- Completion date +- Documents processed count +- Total cost for the contribution +- Summary statistics at the top (total PRs, merged count, tokens, cost) ### Stats Tab Track your overall impact: -- Total contributions and merged PRs -- Tokens donated and estimated cost -- Issues resolved and repositories contributed to -- Streak tracking and achievement badges +- **Overview metrics**: Total contributions, merged PRs, tokens donated, estimated cost +- **Repositories contributed to**: Unique project count +- **Streak tracking**: Current and longest contribution streaks +- **Achievement badges**: Unlock achievements like "First Contribution", "Week Warrior", "Token Titan" ## Session Integration @@ -122,20 +133,24 @@ Each document path should point to an Auto Run-compatible markdown file with tas ## Task Claiming -When you click **Start Symphony**, Maestro immediately creates a draft PR. This claims the task so other contributors know it's being worked on: +Symphony uses **deferred PR creation** to avoid GitHub's "no commits between branches" error. When you start a contribution, Maestro sets up the branch and documents but waits until the first commit to create the draft PR: + +1. **Start contribution** → Branch created locally, Auto Run begins processing +2. **First commit** → Draft PR automatically created, claims the issue +3. **Subsequent commits** → Push to the same PR + +This means issues show as "in progress" once the first commit lands. The claiming mechanism: - **No draft PR** → Task is available -- **Draft PR exists** → Task is in progress - -First to create a draft PR wins — this prevents duplicate work. +- **Draft PR exists** → Task is in progress (first to commit wins) ## Registering Your Project To add your open source project to Symphony: 1. Fork the [Maestro repository](https://github.com/pedramamini/Maestro) -2. Add your project to `symphony-registry.json` -3. Submit a pull request +2. Add your project to `symphony-registry.json` in the root directory +3. Submit a pull request to the main Maestro repository Your project entry should include: ```json @@ -144,16 +159,34 @@ Your project entry should include: "name": "Project Name", "description": "Brief description", "url": "https://github.com/owner/repo", - "category": "developer-tools", + "category": "ai-ml", "tags": ["tag1", "tag2"], "maintainer": { "name": "Your Name", "url": "https://github.com/yourusername" }, - "isActive": true + "isActive": true, + "featured": false, + "addedAt": "2025-01-01" } ``` +### Available Categories + +| Category | Label | Emoji | +|----------|-------|-------| +| `ai-ml` | AI & ML | 🤖 | +| `developer-tools` | Developer Tools | 🛠️ | +| `infrastructure` | Infrastructure | 🏗️ | +| `documentation` | Documentation | 📚 | +| `web` | Web | 🌐 | +| `mobile` | Mobile | 📱 | +| `data` | Data | 📊 | +| `security` | Security | 🔒 | +| `other` | Other | 📦 | + +Once merged, your project will appear in the Symphony Projects tab (registry cached for 2 hours, issues cached for 5 minutes). + --- **Maestro Symphony — Advancing open source, together.** From d10ffc29b6679ae21a699287aa0f31ed0bd7bb0c Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:23:41 -0600 Subject: [PATCH 13/14] MAESTRO: Fix troubleshooting.md documentation inaccuracies - Fix log level description (was backwards - higher levels show FEWER logs) - Update severity levels list (was 3, now correctly shows all 6: debug, info, warn, error, toast, autorun) - Add search shortcut (Cmd+F) and detail view feature for System Log Viewer - Expand Process Monitor docs with hierarchical tree structure, all 8 process types, keyboard shortcuts, and features - Add new Agent Errors section documenting all 6 error types handled by AgentErrorModal - Fix Debug Package contents table - split into "Always included" (9 files) and "Optional" (5 files) sections - Add 5 missing files: windows-diagnostics.json, groups.json, web-server.json, group-chats.json, batch-state.json --- docs/troubleshooting.md | 73 +++++++++++++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 10 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 73f75b5b..a2d42c7d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -13,11 +13,12 @@ Maestro maintains detailed system logs that help diagnose issues. Access them vi - **Menu:** Click the hamburger menu (☰) in the Left Panel → "System Logs" The **System Log Viewer** shows: -- Timestamped log entries with severity levels (info, warn, error) -- Filterable by log level and searchable text +- Timestamped log entries with severity levels (debug, info, warn, error, toast, autorun) +- Filterable by log level via clickable level pills and searchable text (`Cmd+F` / `Ctrl+F`) - Real-time updates as new logs are generated +- Detail view with full message content and source module -**Log levels** can be configured in **Settings** → **General** → **System Log Level**. Higher levels capture more detail but may impact performance. +**Log levels** can be configured in **Settings** → **General** → **System Log Level**. Higher levels show fewer logs — Debug shows all logs, Error shows only errors. ## Process Monitor @@ -27,14 +28,54 @@ Monitor all running processes spawned by Maestro: - **Quick Actions:** `Cmd+K` / `Ctrl+K` → "View System Processes" - **Menu:** Click the hamburger menu (☰) in the Left Panel → "Process Monitor" -The **Process Monitor** displays: -- All active AI agent processes and their PIDs -- Terminal/shell processes for each agent -- Process uptime and resource information -- Ability to terminate stuck processes +The **Process Monitor** displays a hierarchical tree view: +- **Groups** — Session groups containing their member sessions +- **Sessions** — Each session shows its AI agent and terminal processes +- **Process details** — PID, runtime, working directory, Claude session ID (for AI processes) +- **Group Chat processes** — Moderator and participant processes for active group chats +- **Wizard processes** — Active wizard conversations and playbook generation + +**Process types shown:** +| Type | Description | +|------|-------------| +| AI Agent | Main Claude Code (or other agent) process | +| Terminal | Shell process for the session | +| Batch | Auto Run batch processing agent | +| Synopsis | Context compaction synopsis generation | +| Moderator | Group chat moderator process | +| Participant | Group chat participant agent | +| Wizard | Wizard conversation process | +| Wizard Gen | Playbook document generation process | + +**Features:** +- Click a process row to view detailed information (command, arguments, session ID) +- Double-click or press `Enter` to navigate to the session/tab +- `K` or `Delete` to kill a selected process +- `R` to refresh the process list +- Expand/collapse buttons in header to control tree visibility This is useful when an agent becomes unresponsive or you need to diagnose process-related issues. +## Agent Errors + +When an AI agent encounters an error, Maestro displays a modal with clear recovery options. Common error types include: + +| Error Type | Description | Recovery Options | +|------------|-------------|------------------| +| **Authentication Required** | API key expired or invalid | Re-authenticate, check API key settings | +| **Context Limit Reached** | Conversation exceeded token limit | Start new session, compact context | +| **Rate Limit Exceeded** | Too many API requests | Wait and retry, reduce request frequency | +| **Connection Error** | Network connectivity issue | Check internet, retry connection | +| **Agent Error** | Agent process crashed unexpectedly | Restart agent, start new session | +| **Permission Denied** | File or operation access denied | Check permissions, run with appropriate access | + +Each error modal shows: +- Error type and description +- Agent and session context +- Timestamp of when the error occurred +- Collapsible JSON details for debugging +- Recovery action buttons specific to the error type + ## Debug Package If you encounter deep-seated issues that are difficult to diagnose, Maestro can generate a **Debug Package** — a compressed bundle of diagnostic information that you can safely share when reporting bugs. @@ -49,17 +90,29 @@ If you encounter deep-seated issues that are difficult to diagnose, Maestro can The debug package collects metadata and configuration — never your conversations or sensitive data: +**Always included:** + | File | Contents | |------|----------| | `system-info.json` | OS, CPU, memory, Electron/Node versions, app uptime | | `settings.json` | App preferences with sensitive values redacted | | `agents.json` | Agent configurations, availability, and capability flags | | `external-tools.json` | Shell, git, GitHub CLI, and cloudflared availability | -| `sessions.json` | Session metadata (names, states, tab counts — no conversations) | +| `windows-diagnostics.json` | Windows-specific diagnostics (minimal on other platforms) | +| `groups.json` | Session group configurations | | `processes.json` | Active process information | +| `web-server.json` | Web server and Cloudflare tunnel status | +| `storage-info.json` | Storage paths and sizes | + +**Optional (toggleable in UI):** + +| File | Contents | +|------|----------| +| `sessions.json` | Session metadata (names, states, tab counts — no conversations) | | `logs.json` | Recent system log entries | | `errors.json` | Current error states and recent error events | -| `storage-info.json` | Storage paths and sizes | +| `group-chats.json` | Group chat metadata (participant lists, routing — no messages) | +| `batch-state.json` | Auto Run state and document queue | ### Privacy Protections From c42bf3224b38002ff38104d4bed662a4efbe6679 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:27:22 -0600 Subject: [PATCH 14/14] MAESTRO: Fix usage-dashboard.md documentation inaccuracies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add missing "Sessions" summary card (6 cards total, not 5) - Document Location Distribution chart (local vs SSH queries) - Document Peak Hours chart (24-hour activity breakdown) - Document Duration Trends chart in Overview tab - Expand Agents tab with Session Statistics details - Expand Auto Run tab with all 6 metric cards and mini chart - Add Keyboard Navigation section (tab navigation, section nav) - Fix Accessibility section (colorblind mode not in Settings UI) - Fix Enabling/Disabling Collection path (General tab → Usage Dashboard) - Add real-time updates and database size footer documentation --- docs/usage-dashboard.md | 72 +++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 13 deletions(-) diff --git a/docs/usage-dashboard.md b/docs/usage-dashboard.md index 47c8f033..09839ce3 100644 --- a/docs/usage-dashboard.md +++ b/docs/usage-dashboard.md @@ -34,6 +34,7 @@ The dashboard is organized into four tabs, each providing different insights int The Overview tab gives you a high-level summary of your AI usage: **Summary Cards:** +- **Sessions** — Total number of registered sessions - **Total Queries** — Number of messages sent to AI agents - **Total Time** — Cumulative time spent waiting for AI responses - **Avg Duration** — Average response time per query @@ -50,16 +51,31 @@ A donut chart breaking down your queries by source: Toggle between **Count** (number of queries) and **Duration** (time spent) views. +**Location Distribution:** +A donut chart showing the breakdown between local and remote (SSH) queries. Useful for understanding how much work is done locally versus on remote machines. + +**Peak Hours:** +A 24-hour bar chart showing when you're most active. Each bar represents an hour of the day (0–23), with height indicating query count or duration. The peak hour is highlighted. Toggle between Count and Duration views. + **Activity Heatmap:** A GitHub-style heatmap showing your activity patterns throughout the week. Each cell represents an hour of the day, with color intensity indicating activity level. Toggle between Count and Duration views to see different perspectives. +**Duration Trends:** +A line chart showing how your query durations vary over time. Useful for spotting performance trends or changes in workload. + ### Agents The Agents tab provides detailed per-agent analytics: -- Individual statistics for each AI agent -- Query counts, total time, and average duration per agent -- Comparison charts for side-by-side analysis +**Session Statistics:** +- **Total Sessions** — Count of registered sessions +- **By Agent** — Breakdown by agent type (Claude Code, Codex, etc.) with color-coded indicators +- **Git Repos vs Folders** — How many sessions are Git repositories versus plain directories +- **Remote vs Local** — Sessions running on remote SSH hosts versus local machine + +**Agent Comparison:** +- Full agent comparison chart showing query counts and time spent per agent +- Side-by-side visual comparison of your agent usage patterns ### Activity @@ -73,9 +89,16 @@ The Activity tab shows your usage patterns over time: The Auto Run tab focuses specifically on automated playbook execution: -- Auto Run session statistics -- Task completion rates -- Time spent on automated vs. interactive work +**Metric Cards:** +- **Total Sessions** — Number of Auto Run batch sessions +- **Tasks Done** — Total tasks completed (with attempted count) +- **Avg Tasks/Session** — Average tasks completed per Auto Run session +- **Success Rate** — Percentage of tasks that completed successfully +- **Avg Session** — Average duration of an Auto Run session +- **Avg Task** — Average duration per individual task + +**Tasks Completed Over Time:** +A mini bar chart showing task completions by date (last 14 days). Hover over bars to see exact counts and success percentages for each day. ## Time Range Filtering @@ -91,6 +114,17 @@ Use the time range dropdown in the top-right corner to filter all dashboard data The selected time range applies to all tabs and charts. Your preferred time range is saved and restored between sessions. +## Keyboard Navigation + +| Shortcut | Action | +|----------|--------| +| `Cmd+Shift+[` / `Ctrl+Shift+[` | Previous tab | +| `Cmd+Shift+]` / `Ctrl+Shift+]` | Next tab | +| `Arrow Up/Down` | Navigate between chart sections | +| `Home` | Jump to first section | +| `End` | Jump to last section | +| `Esc` | Close dashboard | + ## Exporting Data Click **Export CSV** in the top-right corner to download your usage data as a CSV file. The export includes: @@ -116,7 +150,7 @@ The Usage Dashboard collects: - Message content (your prompts and AI responses) - File contents or paths -- Token counts or costs (tracked separately per-session) +- Token counts or costs (tracked per-session in the main UI, not aggregated in the dashboard) - Activity outside of Maestro ### Enabling/Disabling Collection @@ -124,22 +158,34 @@ The Usage Dashboard collects: Stats collection is enabled by default. To disable: 1. Open **Settings** (`Cmd+,` / `Ctrl+,`) -2. Find **Stats Collection** -3. Toggle off to stop collecting usage data +2. Go to the **General** tab +3. Find **Usage Dashboard** section (marked with Beta badge) +4. Toggle off **Enable stats collection** + +You can also set your **Default dashboard time range** here (Today, This Week, This Month, This Year, or All Time). Disabling collection stops new data from being recorded but preserves existing data in the dashboard. ## Accessibility -The Usage Dashboard supports colorblind-friendly palettes: +The Usage Dashboard supports colorblind-friendly chart palettes using high-contrast colors from the Wong palette. This mode is enabled programmatically via the `colorBlindMode` setting. -1. Open **Settings** (`Cmd+,` / `Ctrl+,`) -2. Enable **Colorblind Mode** -3. Charts will use high-contrast colors from the Wong palette + +The colorblind mode setting is available in the application configuration but not yet exposed in the Settings UI. It will use accessible colors automatically when enabled. + + +## Additional Features + +**Real-time Updates:** +The dashboard automatically refreshes when new queries are recorded. An "Updated" indicator briefly appears when new data arrives. + +**Database Size:** +The footer displays the current size of the stats database, helping you monitor storage usage over time. ## Tips - **Check the Activity Heatmap** to understand your most productive hours +- **Use Peak Hours** to identify your most productive time of day - **Compare agents** to see if one consistently performs faster than others - **Monitor Auto Run vs. Interactive** ratio to understand your automation level - **Export regularly** if you want to track long-term trends externally