100 lines
3.2 KiB
Markdown
100 lines
3.2 KiB
Markdown
---
|
|
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 |
|