---
name: ipa-context-aware-planning
description: Extends planning with @path context syntax for design mockup integration and tech-stack-aware code generation. Use when planning with design file references, when a plan command includes @path arguments pointing to mockups or prototypes, or when tech-stack-specific code generation is needed. Trigger phrases: "plan with design context", "use @path in plan", "planning with mockups".
---

## Overview

Supplements the planning workflow with @path context reference parsing, design mockup analysis, and tech-stack-aware code transformation.

## When to Use

- Planning commands include `@path` syntax (e.g., `@docs/design-mockups`)
- Keywords "design", "mockup", "prototype", or "UI" appear with file references
- Tech-stack-specific code output is required in plan tasks

## Don't Use When

- No design files or @path references are present
- Planning a purely backend or data-only task with no UI component

## Syntax

| Pattern | Example | Description |
|---------|---------|-------------|
| `@folder` | `@docs/design` | Include entire folder as context |
| `@file` | `@docs/spec.md` | Include single file |
| Multiple | `@docs/design @docs/api` | Space-separated refs |

## Workflow

### Step 0: Tech Stack Detection (FIRST)

Detect target framework from project docs:
1. Read `.claude/tech-stack.md` (primary)
2. Fallback: `CLAUDE.md`, `docs/tech-stack.md`, `docs/project-overview-pdr.md`
3. Extract frontend framework (Next.js, React, Vue, Angular, Astro, Svelte)
4. Set transformation rules for output code

### Step 1: Context Parsing

Parse @path references from arguments:
1. Extract all @path patterns
2. Validate each path exists
3. Categorize files by type (design/docs/config)
4. Build structured context object

### Step 2: Design Analysis (if HTML/CSS/JS detected)

Hybrid analysis workflow:
1. Screenshot HTML with visual analysis tool
2. Parse HTML structure and CSS variables
3. Extract component inventory, colors, typography, exact content
4. Generate design-analysis-report.md

### Step 3: Code Transformation

Apply tech-stack rules to extracted code:
- Transform `class` → `className` for React/Next.js or keep as `class`
- Adapt icon imports for target library
- Generate correct component file extensions
- Apply framework-specific patterns

### Step 4: Integration with Planning

1. Copy design files to `{plan-dir}/design/`
2. Save report to `{plan-dir}/reports/design-analysis-report.md`
3. Pass enriched context to planning workflow
4. Include tech-stack-adapted code in phases

## Output Structure

```
{plan-dir}/
├── design/
│   └── prototype/
│       ├── login.html
│       └── login.css
├── reports/
│   └── design-analysis-report.md
├── plan.md
└── phase-XX-xxx.md
```

## File Categorization

| Category | Extensions | Action |
|----------|------------|--------|
| design | .html, .css, .js, .jsx, .tsx, .vue, .svelte | Analyze + copy |
| docs | .md, .txt, .rst | Read as context |
| config | .json, .yaml, .yml | Read as context |
| other | * | List only |

## Error Handling

| Error | Action |
|-------|--------|
| Path not found | Warn user, continue without |
| Too many files (>50) | Warn, ask to narrow scope |
| Visual analysis unavailable | Fallback to code-only parsing |