Miro Code Spec

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:

{
  "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 SCREENS:

• ✗ DO NOT call the Miro MCP context tool for screens from the main agent (context bloat)
• ✓ ALWAYS use a subagent for each prototype screen
• ✓ CREATE 3 tasks per prototype screen (for visibility)
• ✓ Subagent completes all 3 tasks: HTML → Images → URLs
• ✓ Use the Miro MCP image tool to obtain a download URL, then curl to download
• ✓ ALL image URLs must be replaced with local paths before moving on

Frame items:

• Call the appropriate Miro MCP item-retrieval tool with the item URL
• MUST write content to .miro/specs/frames/<board item ID>.md
• Update index.json with this item

Table items:

• Call the appropriate Miro MCP table-retrieval tool for the table item
• MUST write JSON content to .miro/specs/tables/<board item ID>.json
• Include column definitions and all row data in JSON
• Update index.json with this item

Unknown/Other item types (e.g., slides, or any new types):

• Call the appropriate Miro MCP item-retrieval tool with the item URL
• MUST write content to .miro/specs/other/<board item ID>.md
• Preserve original type name in metadata for reference
• Update index.json with this item

8. Finalize Metadata Index

Read the current index.json and calculate the summary section:

• Count total_items from items array
• Count by_type (group items by type field)
• Count total_images from images array

Update index.json with the calculated summary:

{
  "summary": {
    "total_items": 8,
    "by_type": {
      "document": 2,
      "diagram": 2,
      "prototype": 2,
      "table": 1,
      "frame": 1
    },
    "total_images": 3
  }
}

MUST write the updated index.json.

9. Verify and Display Summary

Verification Checklist (MUST DO):

• Count files actually written to .miro/specs/ directories
• Verify file count matches number of items processed
• If mismatch, identify and save any missing items
• Prototype screens: Verify all image URLs have been replaced with local paths
• Check that all tasks have been marked as completed
• Count images in .miro/specs/images/ matches index.json total_images

Display to user:

• Total items extracted (by type)
• Total files written to disk
• Total images downloaded and embedded
• Output directory path
• Next steps: "Use these specs for planning and implementation"

If verification fails, DO NOT report success:

• If any prototype screens still have original image URLs in HTML → Images won't work locally
• If task count doesn't match item count → Some items were skipped
• Re-extract missing items before finishing

Common Mistakes to Avoid

🚨 These are the most common reasons extraction fails or is incomplete:

1. NOT CREATING TASKS

   • ✗ Wrong: Extract all items without creating tasks
   • ✓ Correct: Create an internal checklist item for every single item before extraction
   • Result: Items get skipped, no visibility into progress

2. TREATING PROTOTYPE SCREENS AS 1 TASK

   • ✗ Wrong: Create 1 task for a prototype screen
   • ✓ Correct: Create 3 tasks (HTML, Images, URLs) and use a subagent
   • Result: Images are never extracted

3. CALLING THE MCP CONTEXT TOOL FOR SCREENS FROM MAIN AGENT

   • ✗ Wrong: Call the Miro MCP context tool for prototype screens directly from the main agent (large HTML bloats context)
   • ✓ Correct: Launch a subagent for each screen — HTML stays in subagent context
   • Result: Main agent context overflows, extraction fails

4. NOT PARSING HTML FOR IMAGES

   • ✗ Wrong: Skip parsing HTML, assume no images exist
   • ✓ Correct: Search for all image src attributes in HTML
   • Result: Images aren't discovered or downloaded

5. NOT UPDATING IMAGE URLS IN HTML

   • ✗ Wrong: Download images but leave original URLs in HTML
   • ✓ Correct: Replace ALL original URLs with ../images/[id].png
   • Result: HTML still references remote URLs instead of local files

6. NOT TRACKING IMAGE METADATA

   • ✗ Wrong: Download images but don't update index.json
   • ✓ Correct: Add image entries to index.json images array
   • Result: Loss of tracking which images belong to which screens

7. NOT VERIFYING COMPLETION

   • ✗ Wrong: Finish extraction without checking files
   • ✓ Correct: Verify all tasks completed, all images downloaded, all URLs replaced
   • Result: Incomplete extraction discovered too late