miro-code-spec

What this skill does

# Extract Miro Specs

Extract specification content from a Miro board or item and save to `.miro/specs/` so it can be referenced during planning and implementation without repeated API calls.

The user provides one URL: a board URL (extract all spec items) or an item URL with a `moveToWidget` / `focusWidget` parameter (extract that single item). Miro MCP must be available.

## Workflow

### 1. Identify the URL from the user's request

- If the user provided a Miro URL, use it.
- If not, ask the user for one.

### 2. Determine URL Scope

Decide whether the user gave a **board URL** (extract every spec item on the
board) or a **single-item URL** — i.e. a board URL with a `moveToWidget` or
`focusWidget` query parameter naming one item. Pass the URL through to Miro
MCP as-is — MCP handles the URL.

### 3. Check/Prepare Output Directory

- Check if `.miro/specs/` exists and has content.
- If it has content, ask the user:
  - "The `.miro/specs/` directory already contains files. What should I do?"
  - Options:
    - "Clean and extract fresh" — remove existing content
    - "Add to existing" — keep existing files
    - "Cancel" — abort operation
- Create the directory structure if needed:
  ```
  .miro/specs/
  ├── documents/      # Markdown documents
  ├── diagrams/       # Diagram descriptions
  ├── prototypes/     # Containers (Markdown) and screens (HTML)
  ├── tables/         # Table JSON data
  ├── frames/         # Frame summaries
  ├── other/          # Unknown types (slides, etc.)
  └── images/         # Extracted images
  ```

### 4. Discover Items to Extract

**For Board URLs:**
- Use the Miro MCP board-overview tool with the board URL.
- Each returned item includes its type, URL (with `moveToWidget` parameter), and title.
- Collect all items with their types, URLs, and titles for extraction.

**For Item URLs:**
- Create a single-item URL list.

### 5. Create Tasks for Extraction (MANDATORY)

🚨 **THIS STEP IS MANDATORY — DO NOT SKIP**

Create an internal checklist item for EVERY item discovered so nothing is missed.

**Task structure:**
- **Subject:** "Extract [type]: [title]" (use title if available from the board-overview tool, otherwise use id)
- **Description:** Include item type, id, URL, and target file path
- **activeForm:** "Extracting [type]: [title]" (use title if available, otherwise use id)

**Example with title:**
```
Subject: "Extract document: Product Requirements"
Description: "Extract document item 3458764612345 from board. Save to .miro/specs/documents/3458764612345.md"
activeForm: "Extracting document: Product Requirements"
```

**Example without title:**
```
Subject: "Extract diagram: 3458764612347"
Description: "Extract diagram item 3458764612347 from board. Save to .miro/specs/diagrams/3458764612347.md"
activeForm: "Extracting diagram: 3458764612347"
```

**⚠️ IMPORTANT: Task Count by Type**

Create tasks according to this exact breakdown:
- Each document → **1 task**
- Each diagram → **1 task**
- Each prototype container → **1 task**
- Each prototype screen → **3 tasks** (HTML + Images + URLs)
  1. "Get and save HTML: [title]"
  2. "Extract images: [title]"
  3. "Update image URLs: [title]"
- Each frame → **1 task**
- Each table → **1 task**
- Each other item → **1 task**
- Final step → **1 task** "Finalize metadata index"

**Critical:** Prototype screens are NOT 1 task, they are 3 tasks. If you create only 1 task per screen, images will be missed.

**Naming Convention:**
- Use titles from the board-overview tool for readability
- Use item IDs in file paths for uniqueness and filesystem safety

**This task creation step ensures:**
✓ All items are tracked
✓ Nothing gets skipped
✓ Progress is visible
✓ Extraction workflow is structured

### 6. Initialize Metadata Index

Create `.miro/specs/index.json` with initial structure:
```json
{
  "board_url": "original board URL",
  "extracted_at": "ISO timestamp",
  "items": [],
  "images": [],
  "summary": {
    "total_items": 0,
    "by_type": {},
    "total_images": 0
  }
}
```

This file will be updated progressively as each item is extracted.

### 7. Extract Content from Each Item

**CRITICAL: You MUST write all content received from MCP tools to the file system immediately. Do not skip the file-writing step.**

**Workflow for each item (with task tracking and progressive index updates):**

**For most items (documents, diagrams, containers, frames, tables, other):**
1. Update your internal checklist to mark the item's entry as `in_progress`
2. Call the appropriate MCP tool to get content
3. **IMMEDIATELY** write the content to disk
4. Read current `index.json`, add this item to the items array, then write the updated `index.json`
5. Update your internal checklist to mark the item's entry as `completed`

**For prototype screens (MANDATORY subagent workflow):**
- Launch a subagent for each screen to avoid context bloat
- The subagent performs all 3 steps: Get HTML → Extract images → Update URLs
- Large HTML content stays in subagent context, never enters main context

**Document items:**
- Call the appropriate Miro MCP item-retrieval tool with the item URL
- **MUST write** content to `.miro/specs/documents/<board item ID>.md`
- Extract title from content if available
- Update `index.json` with this item

**Diagram items:**
- Call the appropriate Miro MCP item-retrieval tool with the item URL
- **MUST write** content to `.miro/specs/diagrams/<board item ID>.md`
- Update `index.json` with this item

**Prototype container items:**
- Call the appropriate Miro MCP item-retrieval tool with the item URL
- **MUST write** to `.miro/specs/prototypes/<board item ID>-container.md`
- Update `index.json` with this item

**Prototype screen items (MANDATORY 3-task workflow via subagent):**

⚠️ **EACH PROTOTYPE SCREEN REQUIRES A SUBAGENT WITH 3 SEPARATE TASKS**

**Why subagent:** the Miro MCP context tool returns large HTML for prototype screens, which bloats the main agent's context. A subagent keeps this contained — the large HTML never enters the main conversation.

For each prototype screen, launch a **single subagent** (with `subagent_type: "general-purpose"`) that performs all 3 steps sequentially. Pass the subagent all necessary context:

**Subagent prompt template:**
```
Extract prototype screen and its images from Miro board.

Context:
- Miro board URL targeting the prototype screen: [url]

Execute these 3 tasks in order:

Task 1: Get and save HTML
- Call the appropriate Miro MCP item-retrieval tool with the item URL
- Save the returned raw HTML to .miro/specs/prototypes/<board item ID>-screen.html
- Read index.json, add this item to items array, Write updated index.json

Task 2: Extract images
- Read the saved HTML file
- Parse HTML for ALL image URLs in `src` attributes
- For EACH image URL found:
  1. Extract resource ID from URL path
  2. Call the appropriate Miro MCP image tool to obtain a download URL for the image
  3. Take the download URL from response
  4. Download: `curl -sL -o .miro/specs/images/<image resource ID>.png "[download_url]"`
  5. Read index.json, add image entry to images array, Write updated index.json:
     {"id": "<image resource ID>", "path": "images/<image resource ID>.png", "referenced_by": ["prototypes/<board item ID>-screen.html"]}
- If any download fails: log warning, continue with others

Task 3: Update image URLs in HTML
- Read the HTML file from .miro/specs/prototypes/<board item ID>-screen.html
- Replace ALL original image URLs with relative paths: src="../images/<image resource ID>.png"
- Save the updated HTML
- Verify all image src attributes now point to ../images/

Report back: number of images found, downloaded, and any failures.
```

**Main agent workflow for each screen:**
1. Update your internal checklist to mark "Get and save HTML: [title]" as `in_progress`
2. Launch subagent with the prompt above
3. When subagent completes, mark all 3 tasks for this screen as `completed`
4. Move to next screen

**⚠️ CRITICAL REQUIREMENTS FOR PROTOTYPE SCRE