OpenSpec Design Extension

Adds design asset integration to OpenSpec's proposal stage: when the user's prompt includes Figma links or images, automatically fetch design data, save to design/, and generate a design summary document.

Updating AGENTS.md on Execution

When the user invokes this skill, read the project's openspec/AGENTS.md and make two updates:

Workflow step: In the "Creating Changes" workflow, between "Choose change-id" and "Scaffold", insert: "Design Extension (if Figma in prompt): If the prompt contains a Figma link, the agent MUST call call_mcp_tool to run Figma MCP, create design/, and generate design-map.md. Do not skip."
Design Extension section: Between "Proposal Structure" and "Spec File Format", insert the following Design Extension section. If it already exists, overwrite it.

Full Fragment to Insert into AGENTS.md

Insert the following content into openspec/AGENTS.md at the locations above:

### Design Extension (Figma & Images)

When the proposal's user prompt contains **Figma information** or **images**, the agent **MUST** use `call_mcp_tool` to actively call Figma MCP—do not merely describe it. When a Figma link is detected, **do not skip** the MCP call.

**Figma detection** (any of the following):
- Figma links (`figma.com/file/`, `figma.com/design/`), e.g. `https://www.figma.com/design/pxhnkHfGrSwHbxT1pfV0T4/xxx?node-id=2496-1199`
- Parse from URL: file key = `pxhnkHfGrSwHbxT1pfV0T4` in the path, node-id = query param `2496-1199`

**Figma MCP tools** (via call_mcp_tool):
- `parse_figma_url`: Parse URL to extract file key, node id
- `get_file`: Get file info
- `get_node`: Get node/frame details
- `export_images`: Export images (PNG/JPG/SVG)

**Extension flow**:
1. Create `design/` under `changes/[change-id]/`
2. If Figma: **MUST** call Figma MCP (parse_figma_url → get_file/get_node → export_images), save exported images to `design/`
3. If prompt has attachment images or local image paths: copy them to `design/` as context assets
4. Generate `design/design-map.md` with asset list and design summary

**Note**: `design/` is the design asset directory, distinct from sibling `design.md` (technical design doc). If Figma MCP fails, prompt the user to check MCP config; without MCP, only process local images.

Design Extension Flow Details

1. Create design/ Directory

Create design/ under changes/<change-id>/, alongside proposal.md, tasks.md, design.md, and specs/.

2. Figma MCP Call (Must Execute Explicitly)

MUST call via call_mcp_tool—do not only describe. Do not skip when a Figma link is detected.

Figma MCP tools:

parse_figma_url: Parse URL to extract file key, node id
get_file: Get file info
get_node: Get node/frame details
export_images: Export images (PNG/JPG/SVG)

Call flow:

Parse Figma link from prompt (e.g. figma.com/design/pxhnkHfGrSwHbxT1pfV0T4/xxx?node-id=2496-1199)
Use parse_figma_url or manual parse to get file key, node-id
Call get_file / get_node to fetch design details
Call export_images to export images
Save exports to design/, naming convention: figma-<node-name>-<index>.png

3. Image Asset Collection

User-attached images: save directly to design/
Local paths referenced in prompt: copy to design/
Use semantic naming to avoid collisions

4. design-map.md Generation

Generate design-map.md under design/. Recommended structure:

# Design Map

## Asset List

| File | Source | Description |
|------|--------|-------------|
| figma-hero-1.png | Figma MCP | Homepage hero |
| screenshot-1.png | User attachment | Reference screenshot |

## Design Summary

- [Key design decisions extracted from designs/images]

design-map.md Template

# Design Map

## Asset List

| File | Source | Description |
|------|--------|-------------|
| (filename) | Figma MCP / User attachment / Local | (brief description) |

## Design Summary

- (Point 1)
- (Point 2)

Dependencies

Figma MCP: Requires Figma MCP Server configured in the project. If not configured, the skill prompts the user to configure it, or only processes local/attached images.

openspec-design