/miro-code-spec

name: miro-code-spec
description: Use when the user wants to extract a Miro board's specs (documents, diagrams, prototypes, tables, frames, images) to local `.miro/specs/` files for AI-assisted planning and implementation — accepts a board URL or single-item URL.

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 w