/design-import

description: "Import an external design document (Markdown, JSON, or HTML from Confluence/Notion) and convert it to design_doc.json format for Plan Cascade integration."

Plan Cascade - Import Design Document

Import an external design document and convert it to the unified `design_doc.json` format used by Plan Cascade.

Path Storage Modes

Design documents are user-visible files and remain in the working directory in both modes:

• `design_doc.json`: Created in current working directory (project root or worktree)

This command does not use PathResolver since it works with user-provided paths and creates user-visible documentation files.

Supported Formats

| Format | Extensions | Source | |--------|------------|--------| | Markdown | `.md`, `.markdown` | Any markdown document | | JSON | `.json` | Structured JSON documents | | HTML | `.html`, `.htm` | Confluence/Notion exports |

Tool Usage Policy (CRITICAL)

**To avoid command confirmation prompts:**

1. **Use Read tool for file reading** - NEVER use `cat` via Bash

• ✅ `Read("design.md")`, `Read("architecture.html")`
• ❌ `Bash("cat design.md")`

2. **Use Write tool for file creation**

• ✅ `Write("design_doc.json", content)`
• ❌ `Bash("echo '...' > design_doc.json")`

Step 1: Parse Arguments

Get the input file path from arguments:

INPUT_FILE="{{args}}"

If no file provided:

ERROR: Please provide a path to the design document to import.

Usage:
  /plan-cascade:design-import <path>

Examples:
  /plan-cascade:design-import docs/architecture.md
  /plan-cascade:design-import design-spec.json
  /plan-cascade:design-import confluence-export.html

Step 2: Read and Detect Format

Read the input file and detect its format:

content = Read(INPUT_FILE)

# Detect format from extension
if INPUT_FILE ends with .md or .markdown:
    FORMAT = "markdown"
elif INPUT_FILE ends with .json:
    FORMAT = "json"
elif INPUT_FILE ends with .html or .htm:
    FORMAT = "html"
else:
    FORMAT = "markdown"  # default

Step 3: Convert Based on Format

3.1: Markdown Conversion

Parse the markdown structure to extract design information:

**Heading Mapping:** | Markdown Heading | Design Doc Section | |------------------|-------------------| | `# Title` | `overview.title` | | `## Overview/Summary/Introduction` | `overview.summary` | | `## Goals/Objectives` | `overview.goals` | | `## Non-Goals/Out of Scope` | `overview.non_goals` | | `## Architecture/Design` | `architecture` section | | `## Components/Modules` | `architecture.components` | | `## Patterns` | `architecture.patterns` | | `## Decisions/ADR` | `decisions` | | `## API/Endpoints` | `interfaces.apis` | | `## Data Models/Schema` | `interfaces.data_models` |

**Example Markdown Input:**

# User Authentication System

## Overview
A secure authentication system for web applications.

## Goals
- Secure user registration and login
- JWT-based session management
- Self-service password reset

## Architecture
### Components
- AuthController - HTTP request handling
- AuthService - Business logic
- UserRepository - Data access

### Patterns
- Repository Pattern - For data abstraction
- Service Layer - For business logic isolation

## Decisions
### ADR-001: Use bcrypt for passwords
We chose bcrypt because it's battle-tested and includes salt.

### ADR-002: Use JWT tokens
Stateless authentication for horizontal scaling.

## APIs
- POST /api/auth/register - User registration
- POST /api/auth/login - User login

3.2: JSON Conversion

If the JSON is already in design_doc format, validate and use directly.

Otherwise, map common field names:

| Input Field | Design Doc Field | |-------------|-----------------| | `title`, `name` | `overview.title` | | `summary`, `description` | `overview.summary` | | `goals`, `objectives` | `overview.goals` | | `components` | `architecture.components` | | `patterns` | `architecture.patterns` | | `decisions`, `adrs` | `decisions` | | `apis`, `endpoints` | `interfaces.apis` | | `models`, `data_models` | `interfaces.data_models` |

3.3: HTML Conversion (Confluence/Notion)

Extract content from HTML structure:

• `<title>` or `<h1>` → `overview.title`
• `<h2>` sections → Mapped by heading text
• `<ul>/<ol>` lists → Extracted as array items
• `<p>` paragraphs → Extracted as text content

Strip all HTML tags and decode entities.

Step 4: Enhance with AI Analysis

After basic conversion, enhance the document:

1. **Fill in missing sections**: If architecture section is sparse, analyze the content to infer components 2. **Generate story mappings**: If prd.json exists, create mappings between stories and design elements 3. **Normalize formatting**: Ensure all fields follow the design_doc schema

Step 5: Validate Result

Check the converted document:

• Has required sections (metadata, overview, architecture, decisions, story_mappings)
• overview.title is not empty
• All referenced IDs are valid
• JSON is well-formed

Step 6: Save and Display

Save to `design_doc.json`:

Write("design_doc.json", <formatted JSON>)

Display conversion summary:

=== Design Document Imported ===

Source: <INPUT_FILE>
Format: <FORMAT>

Converted Content:
  Title: <overview.title>
  Summary: <first 100 chars of summary>...

Sections Extracted:
  ✓ Overview: <summary length> chars
  ✓ Goals: X items
  ✓ Components: Y defined
  ✓ Patterns: Z identified
  ✓ Decisions: N ADRs
  ✓ APIs: M endpoints
  ✓ Data Models: P models

Story Mappings: <auto-generated if PRD exists, otherwise empty>

Next steps:
  - Review with: /plan-cascade:design-review
  - Generate mappings manually if needed
  - Proceed to: /plan-cascade:approve

Step 7: Handle PRD Integration

If PRD exists (check both new mode and legacy locations):

# Get PRD path from PathResolver
PRD_PATH = uv run python -c "from plan_cascade.state.path_resolver import PathResolver; from pathlib import Path; print(PathResolver(Path.cwd()).get_prd_path())"

# Check fo