mirror of
https://github.com/jlengrand/Maestro.git
synced 2026-03-10 08:31:19 +00:00
Merge pull request #180 from pedramamini/symphony/issue-179-mk9muakc
[WIP] Symphony: Documentation Accuracy Check (#179)
This commit is contained in:
Pedram Amini
@@ -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/<sessionId>.json`
|
||||
- **Windows**: `%APPDATA%/maestro/history/<sessionId>.json`
|
||||
- **Linux**: `~/.config/maestro/history/<sessionId>.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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
<Note>
|
||||
The MCP server only indexes pages included in the documentation navigation. Hidden or excluded pages are not searchable.
|
||||
</Note>
|
||||
|
||||
## Related Resources
|
||||
|
||||
|
||||
@@ -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 <change-id> --strict`
|
||||
|
||||
**Creates:** A `openspec/changes/<change-id>/` directory with:
|
||||
- `proposal.md` - Why and what
|
||||
- `tasks.md` - Implementation checklist
|
||||
- `specs/<capability>/spec.md` - Spec deltas
|
||||
- `proposal.md` — Why and what
|
||||
- `tasks.md` — Implementation checklist
|
||||
- `specs/<capability>/spec.md` — Spec deltas
|
||||
|
||||
### Stage 2: Apply (`/openspec.apply`)
|
||||
|
||||
@@ -67,20 +68,23 @@ After deployment, archive the completed change:
|
||||
|
||||
1. Moves `changes/<name>/` to `changes/archive/YYYY-MM-DD-<name>/`
|
||||
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 <change-id> --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-<change-id>-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 <change-id>` | View change or spec details |
|
||||
| `openspec validate <change-id> --strict` | Comprehensive validation |
|
||||
| `openspec archive <change-id> --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.
|
||||
|
||||
<Frame>
|
||||
<img src="/screenshots/openspec-commands.png" alt="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 <change-id> --strict` before sharing
|
||||
- **Archive promptly** — Archive changes after deployment to keep `changes/` clean
|
||||
|
||||
@@ -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.
|
||||
|
||||
<Frame>
|
||||
<img src="/screenshots/playbook-exchange-list.png" alt="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
|
||||
|
||||
<Frame>
|
||||
<img src="/screenshots/playbook-exchange-details.png" alt="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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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` |
|
||||
|
||||
@@ -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 <id>` |
|
||||
| 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.
|
||||
|
||||
@@ -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
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
<Tip>
|
||||
The Remote tab automatically activates when the tunnel connects successfully.
|
||||
</Tip>
|
||||
|
||||
## 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
|
||||
|
||||
<Warning>
|
||||
**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
|
||||
</Warning>
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Related
|
||||
|
||||
- [Configuration](/configuration) — General settings including web interface options
|
||||
- [SSH Remote Execution](/ssh-remote-execution) — Running Maestro on remote servers
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
<Tip>
|
||||
The `/wizard` command can take optional natural language input: `/wizard add user authentication feature` to provide initial context.
|
||||
</Tip>
|
||||
|
||||
## 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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
@@ -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/<N>-<feature-name>/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/<N>-<feature-name>/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/<N>-<feature-name>/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-<feature-name>-Phase-01-[Description].md
|
||||
Auto Run Docs/SpecKit-<feature-name>-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/<N>-<feature-name>/checklists/<domain>.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
|
||||
|
||||
@@ -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
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
| 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:
|
||||
|
||||
|
||||
|
||||
- **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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
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,11 +66,11 @@ 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
|
||||
|
||||
@@ -75,29 +81,31 @@ View your in-progress Symphony sessions:
|
||||
|
||||
|
||||
Each active contribution shows:
|
||||
- **Issue title and repository** — The GitHub issue being worked on
|
||||
- **Status badge** — Running, Paused, or Waiting
|
||||
- **Document progress** — Current document and total count
|
||||
- **Time elapsed** — How long the contribution has been running
|
||||
- **Token usage** — Input/output tokens and estimated cost
|
||||
- **Pause/Cancel controls** — Pause to review or cancel to abort
|
||||
|
||||
Click **Check PR Status** to verify your draft PR on GitHub.
|
||||
- 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
|
||||
|
||||
@@ -130,20 +138,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
|
||||
@@ -152,16 +164,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.**
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user