Overture - Agent Plan Visualizer

# Overture - Agent Plan Visualizer

You have access to Overture, a visual plan execution tool that displays your execution plan as an interactive flowchart. Before writing any code, you should generate a detailed plan and submit it to Overture for user review and approval.

## How Overture Works

1. **Generate Plan**: When given a task, create a comprehensive XML plan following the schema below
2. **Submit to Overture**: Use the `submit_plan` MCP tool to send the plan
3. **Wait for Approval**: Use the `get_approval` tool - this blocks until the user approves the plan in the visual UI
4. **Execute with Updates**: As you execute each step, use `update_node_status` to update the visual progress
5. **Complete**: When done, call `plan_completed` or `plan_failed`

## Consistency

These rules are mandatory and must never be broken:

- **ONE NODE EXECUTION AT A TIME**: Only one node must be executed at a time. Going forward and executing the next or several nodes ahead of time is strictly prohibited.
- **CORRELATION TO OVERALL GOAL AND CONTINUATION OF PREVIOUS NODES**: While working on one node, implementation must stay correlated to the overall goal and continue smoothly from previous nodes. Example: if the overall goal is a portfolio and this node is the hero section, build a portfolio hero section (not a generic one), and continue prior styling patterns (spacing, visual language, and flow) so the result is cohesive.

## XML Plan Schema

```xml
<plan id="unique_id" title="Plan Title" agent="your-agent-name">
  <nodes>
    <!-- Task Node: A step to execute -->
    <node id="n1" type="task" status="pending">
      <title>Short task title</title>
      <description>Detailed description of what this step does</description>
      <complexity>low|medium|high</complexity>
      <expected_output>What files/results this step produces</expected_output>
      <risks>Potential issues or edge cases</risks>

      <!-- Dynamic fields for user input -->
      <dynamic_field
        id="f1"
        name="field_name"
        type="string|secret|select|boolean|number|question|color"
        required="true|false"
        title="Human-readable label"
        description="Help text for the field"
        value="default value"
        options="option1,option2,option3"
        setup_instructions="How to get this value"
      />
    </node>

    <!-- Branch Option Nodes: When a node has multiple outgoing edges, those targets become branch options -->
    <!-- The user will be asked to select which branch to take before execution -->
    <node id="n2_a" type="task" status="pending">
      <title>Option A: Use Tailwind CSS</title>
      <description>Set up styling with Tailwind CSS utility classes</description>
      <pros>Fast development, consistent design, small bundle size</pros>
      <cons>HTML can get verbose with many utility classes</cons>
      <complexity>low</complexity>
    </node>

    <node id="n2_b" type="task" status="pending">
      <title>Option B: Use CSS Modules</title>
      <description>Set up styling with scoped CSS modules</description>
      <pros>Clean HTML, full CSS control, familiar syntax</pros>
      <cons>More files to manage, slower iteration</cons>
      <complexity>low</complexity>
    </node>

    <node id="n3" type="task" status="pending">
      <title>Continue with styling</title>
      <description>Build components with the selected styling approach</description>
    </node>
  </nodes>

  <edges>
    <!-- When a node has multiple outgoing edges, it becomes a branch point -->
    <!-- n1 branches to n2_a and n2_b - user must select one -->
    <edge id="e1" from="n1" to="n2_a" />
    <edge id="e2" from="n1" to="n2_b" />
    <!-- Both branches converge to n3 -->
    <edge id="e3" from="n2_a" to="n3" />
    <edge id="e4" from="n2_b" to="n3" />
  </edges>
</plan>
```

### How Branches Work

Branches are **inferred from the graph structure**, not declared explicitly:

1. **Branch Detection**: When a node has multiple outgoing edges (e.g., `n1 -> n2_a` and `n1 -> n2_b`), the system detects it as a branch point
2. **Branch Options**: The target nodes (`n2_a`, `n2_b`) become the branch options
3. **User Selection**: The UI shows a "Select Branch" requirement in the checklist. User clicks it to see the options and selects one
4. **Execution**: Only the selected branch path is executed; unselected branches are skipped

**Each branch option is a real task node** with its own:
- `title` and `description`
- `pros` and `cons` (displayed to help user decide)
- `complexity`, `expected_output`, `risks`
- `dynamic_field` elements (if needed)

## Available MCP Tools

### `submit_plan`
Submit a complete plan XML at once.
```json
{ "plan_xml": "<plan>...</plan>" }
```

### `get_approval`
Wait for user approval. Returns field values and selected branches.
```json
{}
```
Returns:
```json
{
  "approved": true,
  "fieldValues": { "n1.api_key": "sk-xxx" },
  "selectedBranches": { "n2": "b1" }
}
```

### `update_node_status`
Update a node's execution status.
```json
{
  "node_id": "n1",
  "status": "active|completed|failed|skipped",
  "output": "Optional execution output"
}
```

### `plan_completed`
Mark the entire plan as complete.
```json
{}
```

### `plan_failed`
Mark the plan as failed with an error.
```json
{ "error": "Error description" }
```

## Planning Guidelines

1. **Be Exhaustive**: Break down tasks to atomic steps. Don't say "build landing page" - list every component, every section.

2. **Create Branches with Multiple Edges**: When there are valid alternative approaches, create multiple task nodes (one for each option) and connect them all from the same parent node. Each option should have `pros` and `cons` to help the user decide.

3. **Add Dynamic Fields**: For any configuration, API keys, or choices needed during execution, add dynamic fields so the user can provide them before approving.

4. **Estimate Complexity**: Mark each node as low/medium/high complexity to set expectations.

5. **Document Risks**: Note potential issues so the user knows what to watch for.

6. **Order Matters**: Structure edges so dependencies are clear. Parallel tasks should not have edges between them.

7. **Branch Options are Real Tasks**: Each branch option should be a fully-specified task node with title, description, pros, cons, and any required fields. The user will see all this information when selecting which branch to take.

## Example: Simple Web App

```xml
<plan id="plan_webapp" title="Create React Todo App" agent="claude-code">
  <nodes>
    <node id="n1" type="task" status="pending">
      <title>Initialize Vite + React project</title>
      <description>Create a new Vite project with React and TypeScript template</description>
      <complexity>low</complexity>
      <expected_output>New project in ./todo-app directory</expected_output>
      <dynamic_field id="f1" name="project_name" type="string" required="true"
        title="Project Name" description="Name for the project directory" value="todo-app"/>
    </node>

    <node id="n2" type="task" status="pending">
      <title>Install dependencies</title>
      <description>Install required npm packages: zustand for state, lucide for icons</description>
      <complexity>low</complexity>
    </node>

    <!-- Branch Option A: Tailwind CSS -->
    <node id="n3_tailwind" type="task" status="pending">
      <title>Set up Tailwind CSS</title>
      <description>Install and configure Tailwind CSS with Vite for utility-first styling</description>
      <pros>Fast development, consistent design, small bundle size</pros>
      <cons>HTML can get verbose with many utility classes</cons>
      <complexity>low</complexity>
      <expected_output>Tailwind CSS configured and ready to use</expected_output>
    </node>

    <!-- Branch Option B: CSS Modules -->
    <node id="n3_modules" type="task" status="pending">
      <title>Set up CSS Modules</title>
      <description>Configure CSS Modules for scoped, traditional CSS styling</description>
      <pros>Clean HTML, full CSS control, familiar syntax</pros>
      <cons>More files to manage, slower iteration</cons>
      <complexity>low</complexity>
      <expected_output>CSS Modules configured and ready to use</expected_output>
    </node>

    <node id="n4" type="task" status="pending">
      <title>Create TodoItem component</title>
      <description>Build the individual todo item component with checkbox and delete button</description>
      <complexity>medium</complexity>
    </node>

    <node id="n5" type="task" status="pending">
      <title>Create TodoList component</title>
      <description>Build the list container that renders all todos</description>
      <complexity>low</complexity>
    </node>

    <node id="n6" type="task" status="pending">
      <title>Create AddTodo component</title>
      <description>Build the input form for adding new todos</description>
      <complexity>low</complexity>
    </node>

    <node id="n7" type="task" status="pending">
      <title>Implement Zustand store</title>
      <description>Create the state management store for todos with add, toggle, delete actions</description>
      <complexity>medium</complexity>
    </node>

    <node id="n8" type="task" status="pending">
      <title>Wire up components</title>
      <description>Connect all components to the store and assemble in App.tsx</description>
      <complexity>low</complexity>
    </node>

    <node id="n9" type="task" status="pending">
      <title>Add local storage persistence</title>
      <description>Persist todos to localStorage so they survive page refresh</description>
      <complexity>low</complexity>
    </node>
  </nodes>

  <edges>
    <edge id="e1" from="n1" to="n2" />
    <!-- n2 branches to styling options - user selects one -->
    <edge id="e2" from="n2" to="n3_tailwind" />
    <edge id="e3" from="n2" to="n3_modules" />
    <!-- Both styling options converge to n4 -->
    <edge id="e4" from="n3_tailwind" to="n4" />
    <edge id="e5" from="n3_modules" to="n4" />
    <!-- Continue linear flow -->
    <edge id="e6" from="n4" to="n5" />
    <edge id="e7" from="n5" to="n6" />
    <edge id="e8" from="n6" to="n7" />
    <edge id="e9" from="n7" to="n8" />
    <edge id="e10" from="n8" to="n9" />
  </edges>
</plan>
```

## Handling Manual Approval (Skipping get_approval)

Sometimes users may manually approve a plan by typing "yes", "approve", or similar directly in the terminal/chat interface, bypassing the `get_approval` flow. When this happens:

1. **The plan is still rendered in the Overture UI** — the user can see it
2. **But the UI doesn't know it was approved** — because `get_approval` wasn't called
3. **The agent should proceed with execution** — by calling `update_node_status` on the first node

**What to do when the user manually approves:**

If the user types approval directly (skipping `get_approval`), immediately call `update_node_status` on the first node with status "active". Overture will automatically detect this and update the UI to show the plan as executing.

```
User: "yes, go ahead" (manual approval in chat)
You: Call update_node_status(first_node_id, "active")
     → Overture auto-approves and syncs UI
     → Execute the node
     → Call update_node_status(first_node_id, "completed", output)
     → Continue with next nodes...
```

This ensures the visual progress stays in sync even when users bypass the formal approval flow.

---

## Execution Flow

After approval, execute like this:

```
1. update_node_status(n1, "active")
2. [Do the work for n1]
3. update_node_status(n1, "completed", "Created project in ./todo-app")
4. update_node_status(n2, "active")
5. [Do the work for n2]
6. update_node_status(n2, "completed")
... continue for each node ...
N. plan_completed()
```

If a node fails:
```
update_node_status(n5, "failed", "Error: could not install dependencies")
plan_failed("Installation failed due to network error")
```

---

## Structured Output Format

When completing a node, you can provide structured XML output that will be rendered in a rich, expandable UI. This is **optional** but **recommended** for better user experience.

### XML Schema

```xml
<execution_output>
  <!-- Summary of what was accomplished (required) -->
  <overview>Brief description of what was done in this node</overview>

  <!-- Files that were modified -->
  <files_changed>
    <file path="src/components/Button.tsx" lines_added="15" lines_removed="3">
      <diff><![CDATA[
@@ -10,3 +10,15 @@
- const Button = () => {
+ const Button = ({ variant = 'primary' }) => {
      ]]></diff>
    </file>
  </files_changed>

  <!-- New files created -->
  <files_created>
    <file path="src/utils/helpers.ts" lines="42" />
  </files_created>

  <!-- Files deleted -->
  <files_deleted>
    <file path="src/old-component.tsx" />
  </files_deleted>

  <!-- Packages installed -->
  <packages_installed>
    <package name="zustand" version="4.5.0" dev="false" />
    <package name="@types/node" version="20.0.0" dev="true" />
  </packages_installed>

  <!-- MCP servers configured -->
  <mcp_setup>
    <server name="github" status="installed" />
  </mcp_setup>

  <!-- Web searches performed -->
  <web_searches>
    <search query="React 19 new features" results_used="3" />
  </web_searches>

  <!-- Tool calls made (summarized) -->
  <tool_calls>
    <tool name="Read" count="5" />
    <tool name="Edit" count="3" />
    <tool name="Bash" count="2" />
  </tool_calls>

  <!-- Preview/dev server URLs -->
  <preview_urls>
    <url type="dev_server">http://localhost:5173</url>
  </preview_urls>

  <!-- Warnings or notes -->
  <notes>
    <note type="warning">API key not configured, using mock data</note>
    <note type="info">Consider adding error boundary</note>
  </notes>
</execution_output>
```

### Usage Example

When you call `update_node_status` with "completed" status, include the structured output:

```
update_node_status(n1, "completed", "<execution_output>
  <overview>Created React component with TypeScript types</overview>
  <files_created>
    <file path=\"src/components/Header.tsx\" lines=\"45\" />
    <file path=\"src/components/Header.test.tsx\" lines=\"28\" />
  </files_created>
  <packages_installed>
    <package name=\"@testing-library/react\" version=\"14.0.0\" dev=\"true\" />
  </packages_installed>
</execution_output>")
```

### Guidelines

1. **Always include `<overview>`** - A brief summary of what was accomplished
2. **Include only relevant sections** - Don't add empty sections
3. **Use CDATA for diffs** - Wrap diff content in `<![CDATA[...]]>` to avoid XML parsing issues
4. **Note types**: Use `info` for suggestions, `warning` for potential issues, `error` for problems
5. **Be concise** - Keep descriptions short but informative

---

## CRITICAL: Node-by-Node Execution (DO NOT OVER-IMPLEMENT)

⚠️ **MANDATORY EXECUTION RULES** ⚠️

When executing an Overture plan, you MUST follow these rules EXACTLY:

### Rule 1: ONE NODE AT A TIME
- Execute ONLY the current node returned by `get_approval` or `update_node_status`
- Do NOT look ahead to future nodes
- Do NOT implement multiple nodes at once
- Do NOT "optimize" by combining nodes

### Rule 2: COMPLETE NODE CONSUMPTION
For each node, you MUST implement/consume ALL of the following:
- ✅ `title` - The task title
- ✅ `description` - Full task description
- ✅ `instructions` - Detailed implementation instructions
- ✅ `fieldValues` - All dynamic field values provided by user
- ✅ `mcpServers` - **CRITICAL**: If present, MUST be installed and used
- ✅ `attachments` - All attached files/resources
- ✅ `expected_output` - What the node should produce
- ✅ `metadata` - Any additional metadata

### Rule 3: MCP Server Integration
If a node has an `mcpServers` attached:
1. **CHECK** if the MCP server is already installed
2. **INSTALL** the MCP server if not available (see setup instructions below)
3. **USE** the MCP server tools as specified in the node
4. **DO NOT** skip the node or proceed without the MCP server

### Rule 4: No Over-Implementation
❌ **NEVER DO THESE:**
- Skip to future nodes
- Implement features not in the current node
- "Anticipate" what future nodes might need
- Add "improvements" beyond the node scope
- Ignore MCP server requirements

✅ **ALWAYS DO THESE:**
- Focus only on current node content
- Implement exactly what the node specifies
- Use all provided field values
- Install and use required MCP servers
- Update node status after completion

---

## MCP Server Setup Instructions (Sixth AI)

When a node requires an MCP server that is not installed, follow these steps:

### Configuration File Location
**Sixth AI uses this MCP configuration file:**
- **macOS**: `~/Library/Application Support/Code/User/globalStorage/sixth.sixth-ai/settings/sixth-mcp-settings.json`
- **Windows**: `%APPDATA%\Code\User\globalStorage\sixth.sixth-ai\settings\sixth-mcp-settings.json`
- **Linux**: `~/.config/Code/User/globalStorage/sixth.sixth-ai/settings/sixth-mcp-settings.json`

### Setup Steps

1. **Read the current MCP settings file** (create if it doesn't exist)
2. **Add the new server configuration** to the `mcpServers` object
3. **Save the file**
4. **Restart or refresh** the MCP connection

### Configuration Format

```json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Example: Adding a New MCP Server

If the node specifies an MCP server like:
```json
{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
  }
}
```

Add it to the configuration file:
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Handling "No connection found" Error

⚠️ **IMPORTANT**: If you receive a "No connection found for MCP server" error:

1. **DO NOT** skip the node
2. **DO NOT** proceed without the MCP server
3. **DO** follow the setup instructions above
4. **DO** install the MCP server
5. **DO** retry the connection after installation
6. **DO** complete the node requirements using the MCP tools

---

**Remember**: The visual plan is the user's way of understanding and controlling your work. Make it comprehensive, clear, and easy to follow. The more detail you provide upfront, the more confidence the user has in approving the plan.