design-import

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