# 🎨 Excalidraw → Python Agent

## What is this mode?

The **Excalidraw → Python** mode (`excalidraw-to-python`) is a custom Roo agent that reads
`.excalidraw` diagram files and translates them into **strongly-typed skeletal Python code**.

It never writes implementation logic — it produces well-structured scaffolding with type
annotations, docstrings, and `# TODO:` markers so a developer can fill in the real logic.

---

## How to activate it

1. Open the Roo chat panel in VS Code.
2. Click the mode selector (bottom-left of the chat input).
3. Choose **🎨 Excalidraw → Python**.

Or, if you are already in another mode, ask Roo:

> "Switch to Excalidraw → Python mode and parse `drawings/design.excalidraw`."

---

## What the agent does — step by step

| Step | What the agent looks for | What it produces |
|------|--------------------------|-----------------|
| 1 | `rectangle` / `ellipse` / `diamond` shapes + their text labels | Python functions or classes |
| 2 | `arrow` elements with `startBinding` / `endBinding` | Call-chain / data-flow order |
| 3 | Free-floating `text` elements (CLI usage, notes) | `argparse` entry-point |
| 4 | Frame labels | Module / file boundaries |

---

## Rules the agent follows

- Uses **Python 3.10+** type-hint syntax (`X | Y`, `list[str]`, etc.).
- Imports `from __future__ import annotations` at the top.
- Every function has a **typed signature** and a **docstring**.
- Bodies contain only `pass` and `# TODO:` comments.
- A `if __name__ == "__main__":` block wires up the CLI.
- Uses `argparse` (stdlib) unless the diagram explicitly mentions another CLI library.

---

## Example

Given the diagram in `drawings/design.excalidraw` the agent produces `src/csv_grok.py`
(see that file for the full output).

The diagram encodes:

```
CSV File 1 ──┐
             ▼
         Combine (union)  ──►  Analyse (cross-correlate?)
             ▲
CSV File 2 ──┘

CLI: csvGrok file1.csv file2.csv -o analysis.txt
```

---

## Configuration location

The mode is defined in **`.roomodes`** at the project root.  
That file is the single source of truth for all custom Roo agents in this project.

```jsonc
// .roomodes
{
  "customModes": [
    {
      "slug": "excalidraw-to-python",
      "name": "🎨 Excalidraw → Python",
      ...
    }
  ]
}
```

To add more agents, append additional objects to the `customModes` array.