Initial commit: antigravity-ipa-workflow

skills/ipa-context-aware-planning/SKILL.md

@@ -0,0 +1,99 @@
+---
+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 |