@relipa/ai-flow-kit 0.1.1-beta.0 → 0.1.2-beta.0

package/custom/skills/figma-to-component/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: figma-to-component
-description: Read designs from Figma and generate React/Next.js/Vue components following project conventions. Supports specific frame URLs and entire pages.
-keywords: figma, design, component, ui, generate, react, nextjs, vue, frontend
+description: Read designs from Figma and generate React/Next.js App Router/Vue/Angular components following project conventions. Supports specific frame URLs and entire pages.
+keywords: figma, design, component, ui, generate, react, nextjs, nextjs-app-router, vue, angular, frontend
 ---
 
 # Figma to Component
@@ -14,6 +14,19 @@ keywords: figma, design, component, ui, generate, react, nextjs, vue, frontend
 
 ---
 
+## Step 0: Verify Figma MCP is available
+
+Before doing anything, confirm the Figma MCP server is connected in this session:
+
+- The tool `mcp__figma__get_figma_data` (and `mcp__figma__download_figma_images`) must be available.
+- If it is **not** available, STOP and tell the developer:
+  > Figma MCP not connected. Run `aiflow init -a figma` (REST API token) or
+  > `aiflow init -a figma-desktop` (Figma Desktop), then restart the session.
+
+Do not guess design values from the URL — without the MCP server the skill cannot read the design.
+
+---
+
 ## Process
 
 ### Step 1: Identify input
@@ -30,20 +43,24 @@ Extract `fileKey` and `nodeId` from the URL.
 Use Figma MCP tools to fetch design information:
 
 ```
-1. Get node info: figma_get_file_nodes(fileKey, nodeIds=[nodeId])
-2. Get styles: figma_get_file_styles(fileKey)
-3. Get components: figma_get_file_components(fileKey) if needed
-4. Export image if visual reference needed: figma_get_image(fileKey, nodeId)
+1. Get node info, styles, and components in one call:
+   get_figma_data(fileKey, nodeId, depth=2)
+
+2. Export image if visual reference needed:
+   download_figma_images(fileKey, nodes=[{ nodeId, fileName }], localPath)
 ```
 
+Note: `get_figma_data` returns layout, fills, strokes, typography, and component
+definitions in a single response. No separate style or component fetch is needed.
+
 Analyze the output to extract:
 - **Layout**: flexbox direction, gap, padding, alignment
 - **Sizing**: width/height (fixed vs fill vs hug)
-- **Colors**: fills, strokes → map to Tailwind colors if available
-- **Typography**: font-size, font-weight, line-height, letter-spacing → map to Tailwind text classes
-- **Spacing**: padding, margin, gap → map to Tailwind spacing scale
-- **Border**: radius, width, color → map to Tailwind border classes
-- **Shadow**: box-shadow → map to Tailwind shadow classes
+- **Colors**: fills, strokes → map to project CSS tokens / Tailwind colors if available
+- **Typography**: font-size, font-weight, line-height, letter-spacing
+- **Spacing**: padding, margin, gap
+- **Border**: radius, width, color
+- **Shadow**: box-shadow
 - **States**: hover, focus, disabled, active (if variants present)
 - **Responsive**: breakpoints if multiple frames present
 
@@ -73,19 +90,12 @@ download_figma_images({
 - `localPath` defaults to `public/assets/figma/` (relative to the project root)
 - `fileName` follows the pattern: `<layer name in lowercase, spaces replaced with ->-<nodeId>.png`
   - Example: layer "Banner Top" with nodeId "123-456" → `banner-top-123-456.png`
-- If MCP does not support `download_figma_images`, use `get_images` to get the URL, then notify DEV to download manually and place in `public/assets/figma/`
+- If MCP does not support `download_figma_images`, get the image URL via `get_figma_data`, then notify DEV to download manually and place in `public/assets/figma/`
 
 **Record the result:**
 
 After export, save the mapping for use in Step 4:
 
-```
-imageMap = {
-  "<nodeId>": "public/assets/figma/<fileName>.png"
-}
-```
-
-Example:
 ```
 imageMap = {
   "123-456": "public/assets/figma/banner-top-123-456.png",
@@ -93,53 +103,50 @@ imageMap = {
 }
 ```
 
-### Step 3: Map Figma tokens → Tailwind / CSS
+### Step 3: Detect CSS tooling, then map Figma tokens
 
-**Color mapping:**
-```
-Figma hex #3B82F6 → Tailwind blue-500
-Figma hex #EF4444 → Tailwind red-500
-Figma rgba(0,0,0,0.5) → Tailwind black/50
-No Tailwind match → use arbitrary value [#hexcode]
-```
+**Detect the project's styling approach first** (do not assume Tailwind):
 
-**Spacing mapping (8px grid):**
-```
-4px  → p-1 / gap-1
-8px  → p-2 / gap-2
-12px → p-3 / gap-3
-16px → p-4 / gap-4
-24px → p-6 / gap-6
-32px → p-8 / gap-8
-No match → arbitrary value [20px]
-```
+1. `tailwind.config.*` present → **Tailwind** — map to utility classes; extend `tailwind.config` with design tokens when a value has no built-in match
+2. `*.module.css` / `*.module.scss` files present → **CSS Modules** — emit a co-located `.module.css` and reference `styles.x`
+3. `styled-components` / `@emotion` in `package.json` → **CSS-in-JS** — emit styled components
+4. None of the above → **vanilla CSS** — emit a co-located `.css` file with CSS custom properties
+
+**Design tokens:** prefer mapping Figma Styles/Variables to existing project tokens
+(Tailwind theme keys or CSS custom properties) instead of hardcoding hex/px values.
+Only fall back to an arbitrary value when no token matches.
+
+**Tailwind reference mappings** (when Tailwind is the detected tooling):
 
-**Typography mapping:**
 ```
-text-xs: 12px
-text-sm: 14px
-text-base: 16px
-text-lg: 18px
-text-xl: 20px
-text-2xl: 24px
-text-3xl: 30px
-font-normal: 400
-font-medium: 500
-font-semibold: 600
-font-bold: 700
+Color:   #3B82F6 → blue-500 · #EF4444 → red-500 · rgba(0,0,0,0.5) → black/50
+         no match → arbitrary value [#hexcode]
+Spacing: 4→p-1/gap-1 · 8→p-2 · 12→p-3 · 16→p-4 · 24→p-6 · 32→p-8 (8px grid)
+         no match → arbitrary value [20px]
+Type:    12→text-xs · 14→text-sm · 16→text-base · 18→text-lg · 20→text-xl · 24→text-2xl · 30→text-3xl
+         400→font-normal · 500→font-medium · 600→font-semibold · 700→font-bold
 ```
 
 ### Step 4: Generate component
 
-**Framework detection** — check the project's CLAUDE.md to determine the framework:
-- `reactjs` / `nextjs` → generate `.tsx` with React conventions
-- `vue-nuxt` → generate `.vue` with Vue 3 Composition API
+**Framework detection** — check in this order:
+
+1. Read project's `CLAUDE.md` for framework identifier:
+   - `nextjs-app-router` → Next.js App Router (Server/Client Components)
+   - `reactjs` / `nextjs` → React / Next.js Pages Router `.tsx`
+   - `vue-nuxt` → Vue 3 `.vue` with Composition API
+   - `angular` → Angular `@Component` class
+2. Scan project files if CLAUDE.md is ambiguous:
+   - `app/` directory present → `nextjs-app-router`
+   - `angular.json` present → `angular`
+   - `nuxt.config.*` present → `vue-nuxt`
+3. Fallback → `nextjs` (React Pages Router)
 
 **Image node rendering rule:**
 
 Before rendering each node, check `imageMap` from Step 2.5:
 - If `nodeId` is in `imageMap` → render using `<img>` (React/Vue) or `<Image>` (Next.js), do NOT use CSS `background-image`
-- If not in `imageMap` → render normally using div + Tailwind classes
+- If not in `imageMap` → render normally using div + styling classes
 
 React/Next.js template for image node:
 ```tsx
@@ -197,6 +204,57 @@ export const [ComponentName] = ({ className }: [ComponentName]Props) => {
 };
 ```
 
+#### Next.js App Router component template:
+
+Default to **Server Component**. Add `'use client'` only when the design has
+interactive states (hover effects, click handlers, form inputs, modals).
+
+```tsx
+// Server Component — no interactivity (default)
+interface [ComponentName]Props {
+  className?: string;
+}
+
+export default async function [ComponentName]({ className }: [ComponentName]Props) {
+  return (
+    <div className={cn(
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      className
+    )}>
+      {/* Child nodes */}
+    </div>
+  );
+}
+```
+
+```tsx
+// Client Component — has onClick / useState / useEffect
+'use client'
+
+import { useState } from 'react'
+
+interface [ComponentName]Props {
+  className?: string;
+}
+
+export function [ComponentName]({ className }: [ComponentName]Props) {
+  return (
+    <div className={cn(
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      className
+    )}>
+      {/* Child nodes */}
+    </div>
+  );
+}
+```
+
+File path: `app/components/[ComponentName].tsx` or `components/[ComponentName].tsx`
+
 #### Vue 3 component template:
 
 ```vue
@@ -221,6 +279,40 @@ const props = withDefaults(defineProps<Props>(), {});
 </template>
 ```
 
+#### Angular component template:
+
+Use Tailwind classes if `tailwind.config.*` exists in the project root.
+Otherwise use `styles` array with CSS-in-component.
+
+```typescript
+import { Component, Input } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-[component-name]',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div [class]="hostClasses">
+      <!-- Child nodes -->
+    </div>
+  `,
+  styles: []
+})
+export class [ComponentName]Component {
+  @Input() className = '';
+
+  get hostClasses(): string {
+    return [
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      this.className
+    ].filter(Boolean).join(' ');
+  }
+}
+```
+
 ### Step 5: Handle interactive states
 
 If Figma has variants (Default, Hover, Disabled, Active):
@@ -245,14 +337,14 @@ const variantClasses = {
 After generation, verify:
 
 - [ ] Layout matches Figma (flex direction, alignment, gap)
-- [ ] Colors mapping correct (or use arbitrary values if no Tailwind match)
+- [ ] Colors mapping correct (project tokens, or arbitrary values if no match)
 - [ ] Typography correct (size, weight, line-height)
 - [ ] Spacing correct (padding, margin, gap)
 - [ ] Component has `className` prop for external overrides
-- [ ] Use `cn()` helper for conditional/mergeable classes
+- [ ] Conditional/mergeable classes use the project's helper (`cn()` for Tailwind)
 - [ ] Responsive if Figma has mobile frames
 - [ ] Props typed with TypeScript interface
-- [ ] Image nodes use `<img>` tag (do not use CSS `background-image`)
+- [ ] Image nodes use `<img>` / `<Image>` (do not use CSS `background-image`)
 - [ ] Image files exist in `public/assets/figma/` before submitting code
 
 ---
@@ -273,9 +365,9 @@ Always output in order:
 
 ## Rules
 
-- **Do not hardcode** hex colors directly into className if a Tailwind equivalent exists
-- **Always use** `cn()` (clsx + twMerge) to merge classes
-- **No new CSS imports** — use Tailwind utilities only
+- **Detect styling tooling first** — do not assume Tailwind; honour CSS Modules / styled-components / vanilla CSS when detected
+- **Prefer design tokens** — map Figma Styles/Variables to project tokens; only hardcode a value when no token matches
+- **Always use** the project's class-merge helper (`cn()` = clsx + twMerge for Tailwind)
 - **Responsive** — if Figma only has 1 breakpoint, default to mobile-first design
 - **Accessibility** — add `aria-label`, `role`, `alt` for interactive and image elements
 - **Image** — detect image fills in Figma node data, export via `download_figma_images` MCP, save to `public/assets/figma/`. Use `<Image>` (Next.js) or `<img>` (React/Vue) with `src` pointing to the exported file. Do NOT use CSS `background-image` for image nodes.
@@ -283,6 +375,19 @@ Always output in order:
 
 ---
 
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `mcp__figma__get_figma_data` not available | Figma MCP server not connected | Run `aiflow init -a figma` or `-a figma-desktop`, restart session |
+| `403 Forbidden` / token rejected | PAT invalid or wrong header | Re-issue a `figd_...` token; `init` sends `X-Figma-Token` (not `Bearer`) |
+| Tool call hangs / times out | Large node tree (`depth` too high) | Lower `depth` (e.g. `depth=1`), target a specific `nodeId` not the whole file |
+| `404` on node | Wrong `fileKey`/`nodeId` | Re-copy the frame URL; node-id uses `-` in URL but `:` in API |
+| Empty fills / no styles | Node is a component instance | Fetch the main component, or increase `depth` |
+| `download_figma_images` unsupported | Older MCP preset | Get image URL via `get_figma_data`, download manually to `public/assets/figma/` |
+
+---
+
 ## Trigger Example Commands
 
 ```

package/custom/skills/frame-ml-problem/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: frame-ml-problem
+description: Frame an ML problem before any modeling — define the prediction target, the correct evaluation metric, a baseline, and the success threshold.
+keywords: ml, problem framing, metric, baseline, target, success criteria
+---
+
+# Frame ML Problem
+
+> This skill **inherits and extends** `superpowers:brainstorming` for collaborative Q&A.
+> First, invoke `superpowers:brainstorming` to explore intent and ambiguities with the developer,
+> then apply the structured framing steps below.
+
+---
+
+## When to use this skill
+
+- Gate 1 of the ML workflow — always the first step before any modeling
+- Any new ML ticket where the prediction target or success criterion is not yet explicit
+- Whenever the evaluation metric has not been pinned down or justified against the business goal
+
+---
+
+## Steps
+
+### 1. Read the ticket context
+
+Read `.aiflow/context/current.json`:
+- `description` — what the stakeholder wants the model to do
+- `comments` — additional context, constraints, or prior attempts
+- `context.files` — related notebooks, data samples, or prior model artifacts
+
+### 2. State the prediction target precisely
+
+Define what is being predicted, at what granularity (row level, user level, session level, etc.), and crucially **when the input features are available** relative to the prediction moment. Guard against accidentally incorporating future information — any feature computed from or derived after the target event is a candidate for leakage.
+
+### 3. Classify the problem type
+
+Explicitly label the task:
+- **Classification** (binary or multi-class): predict a category
+- **Regression**: predict a continuous value
+- **Ranking / Recommendation**: order items by relevance
+- **Generation / Seq-to-seq**: produce text, code, or structured output
+- **Clustering / Anomaly detection**: unsupervised grouping or outlier detection
+
+State the type before choosing any model family or metric.
+
+### 4. Choose the evaluation metric and justify it
+
+Select the primary metric and tie it explicitly to the business goal:
+- Imbalanced classification: prefer F1, PR-AUC, or recall at fixed precision over plain accuracy
+- Regression: choose MAE (robust to outliers) vs RMSE (penalises large errors) deliberately
+- Ranking: use MAP, NDCG, or MRR depending on position sensitivity
+- Note the difference between the **offline proxy metric** (what can be measured from historical data) and the **online KPI** (what the business ultimately cares about); acknowledge any gap
+
+**State the metric before any modeling begins. It must not change after training.**
+
+### 5. Define a baseline and success threshold
+
+- **Baseline:** the simplest defensible reference — majority-class prediction, median value, current rule-based system, or the model already in production
+- **Success threshold:** the quantitative improvement over baseline that is meaningful to the business (e.g. "+3 pp F1 on the held-out set" or "<10 ms p99 latency with no accuracy regression")
+- A threshold of "as high as possible" is not acceptable — make it concrete
+
+### 6. List constraints
+
+Document non-negotiable constraints that shape model choice and architecture:
+- **Latency / throughput:** real-time vs batch; maximum inference time
+- **Memory / hardware:** CPU-only, GPU budget, edge deployment
+- **Interpretability:** regulatory or stakeholder requirements for explanations
+- **Data volume:** row count, feature count, labelling cost
+- **Compliance:** PII handling, data residency, auditability requirements
+
+### 7. Ask one clarifying question at a time when ambiguous
+
+If any of the above cannot be answered from the ticket, ask exactly **one question**, wait for a reply, and continue. Do not bundle multiple questions.
+
+---
+
+## Completion Checklist
+
+- [ ] Ticket context read (description + comments + related files)
+- [ ] Prediction target defined with the exact availability time of input features
+- [ ] Problem type classified (classification / regression / ranking / generation / clustering)
+- [ ] Evaluation metric chosen and justified against the business goal
+- [ ] Offline proxy metric vs online KPI gap acknowledged
+- [ ] Baseline defined (majority class, heuristic, or current production model)
+- [ ] Success threshold quantified (not "as high as possible")
+- [ ] Constraints listed (latency, memory, interpretability, data volume, compliance)
+- [ ] Findings written to `plan/[ticket-id]/ml-problem.md`

package/custom/skills/improve-algorithm/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: improve-algorithm
+description: Systematically improve an existing model or algorithm — profile, hypothesize, ablate, and measure accuracy/latency/memory. No guessing.
+keywords: optimization, algorithm, performance, latency, accuracy, ablation, profiling
+---
+
+# Improve Algorithm
+
+> This skill inherits the discipline of `superpowers:systematic-debugging` — measure before changing, change one thing at a time, measure again. Guessing is not a method; every change must be motivated by evidence from profiling or error analysis.
+
+---
+
+## When to use this skill
+
+- Gate 3, for tickets specifically about improving an existing model or algorithm (accuracy, latency, or memory targets)
+- Any time a model already exists and the goal is to make it better rather than build from scratch
+- When performance regressions are reported in production
+
+---
+
+## Steps
+
+### 1. Establish the current baseline
+
+Run the existing system through the eval harness and record the exact number — metric, split, and seed. This is the floor that every proposed change must be measured against. If no eval harness exists yet, invoke `train-model` first to establish one.
+
+### 2. Profile before optimizing
+
+Do not form a hypothesis before you know where the bottleneck is.
+
+- **Accuracy bottleneck:** run error analysis by slice and by class. Plot learning curves to distinguish bias (underfitting — train error high) from variance (overfitting — large train/val gap). Identify the failure pattern first.
+- **Latency/memory bottleneck:** profile the hot path end-to-end. Tools: `cProfile` / `line_profiler` for Python; `torch.profiler` or `torch.autograd.profiler` for PyTorch; `tf.profiler` for TF. Measure throughput (samples/sec) and peak memory before and after every change.
+
+Never skip this step. Optimizing the wrong part wastes time and can introduce regressions.
+
+### 3. Form ONE hypothesis
+
+Based on the profiling/error-analysis evidence, form exactly one hypothesis tied to the identified bottleneck. Examples:
+
+- "Error analysis shows the model fails on short-text inputs → hypothesis: adding n-gram features reduces error on that slice"
+- "Profiler shows 60% of latency in the preprocessing step → hypothesis: vectorizing the transform halves latency"
+- "Learning curves show high variance → hypothesis: stronger L2 regularization closes the train/val gap"
+
+State the hypothesis explicitly before writing any code.
+
+### 4. Run a single ablation
+
+Implement only the change implied by the hypothesis. Run the eval harness with the same seed, same split, same data version. Track the run in MLflow/wandb with a descriptive name and note the hypothesis in the run description. Compare to the baseline number directly.
+
+### 5. Decide: keep or revert
+
+Keep the change only if it:
+
+- Beats the baseline meaningfully (respects the success threshold from Gate 1)
+- Respects all constraints: accuracy/latency/memory trade-off stated explicitly
+- Does not introduce a new regression in a different slice or metric
+
+Revert if it does not satisfy the above. Log the failure reason; failed experiments are also information.
+
+### 6. Repeat and document
+
+Repeat steps 3–5 for the next bottleneck. Log every attempt — including reversions — so the improvement story is fully reproducible. The final state must be explainable: "we tried X (failed because Y), then tried Z (improved metric by W%)."
+
+---
+
+## Completion Checklist
+
+- [ ] Baseline number recorded on the eval harness before any change
+- [ ] Bottleneck identified by profiling (latency/memory) or error analysis (accuracy) — not guessed
+- [ ] Each change is a single isolated ablation motivated by a stated hypothesis
+- [ ] Every attempt (including failures) measured on the same harness and tracked with params/metrics
+- [ ] Trade-offs between accuracy, latency, and memory stated explicitly for kept changes
+- [ ] Kept changes beat the baseline by the success threshold
+- [ ] Full improvement log available (hypothesis → result → decision for each attempt)

package/custom/skills/train-model/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: train-model
+description: Reproducible model training — eval-harness-first, fixed seeds, pinned environment, logged configs, checkpointing, experiment tracking.
+keywords: training, reproducibility, seed, checkpoint, mlflow, wandb, fine-tune
+---
+
+# Train Model
+
+> **Eval-harness-first is the ML analog of `superpowers:test-driven-development`** — build the metric/eval harness and a reproducible baseline BEFORE writing any model improvement code. If the harness does not run clean, stop and fix it first.
+
+---
+
+## When to use this skill
+
+- Gate 3 of the ML workflow, after the experiment plan has been APPROVED
+- Any time a new model or training run is initiated
+- Fine-tuning or transfer-learning tasks where reproducibility is critical
+
+---
+
+## Steps
+
+### 1. Eval-harness-first
+
+Implement the metric function and the validation loop as defined in the approved experiment plan. Run it against the baseline (majority class, heuristic, or current production model). Confirm you get a reproducible number before touching any model code. This number is the target to beat.
+
+### 2. Enforce reproducibility
+
+Set all random seeds at the top of every training script:
+
+- `random.seed(seed)` and `numpy.random.seed(seed)`
+- Framework seed: `torch.manual_seed(seed)` + `torch.cuda.manual_seed_all(seed)` for PyTorch; `tf.random.set_seed(seed)` for TF/Keras
+- Enable deterministic ops where feasible (`torch.use_deterministic_algorithms(True)`)
+
+Pin the environment: `requirements.txt` or a lockfile (`pip freeze > requirements.txt`). No floating version ranges in the pinned file.
+
+### 3. Config over hardcoding
+
+Place all hyperparameters (learning rate, batch size, number of layers, regularization strength, etc.) in a YAML, Hydra config, or argparse definition — never as literals in the training script. This ensures any run can be exactly reproduced from its config file alone.
+
+### 4. Experiment tracking
+
+Log the following to MLflow or wandb for every run:
+
+- All hyperparameters (from config)
+- Metric per epoch / per fold
+- Seed, data version (DVC hash or path), and git commit SHA
+- Run name following the naming convention in `custom/rules/ml-conventions.md`: `[ticket-id]_[approach]_[yyyymmdd-n]`
+
+Do not leave runs unnamed or untracked.
+
+### 5. Checkpointing
+
+Save the best checkpoint by the primary validation metric (not the final epoch). Store the config file alongside the artifact so the checkpoint is self-contained. Use the model registry (MLflow Model Registry or equivalent) when available.
+
+### 6. Framework-specific considerations
+
+- **scikit-learn:** wrap preprocessing + model in a single `Pipeline` so transforms are fitted on training data only — never on the full dataset.
+- **PyTorch:** seed `DataLoader` workers (`worker_init_fn`), toggle `model.train()` before training and `model.eval()` before validation/inference. Use `torch.no_grad()` for inference.
+- **TF/Keras:** use callbacks for `ModelCheckpoint` (save best) and `EarlyStopping`; set `tf.config.experimental.enable_op_determinism()` if needed.
+- **Fine-tuning:** apply a freeze/unfreeze schedule; use LR warmup before unfreezing. Log the freeze schedule as a config parameter.
+
+### 7. Iterate per the ablation plan
+
+Follow the ablation plan from the experiment design — change exactly one factor per run, track it, compare to the established baseline on the same harness. Do not run ad-hoc experiments that are not tracked or not comparable.
+
+---
+
+## Completion Checklist
+
+- [ ] Eval harness implemented and confirmed running on baseline before any model change
+- [ ] Reproducible baseline number recorded
+- [ ] All random seeds set (language, numpy, framework, CUDA)
+- [ ] Environment pinned (requirements.txt or lockfile committed)
+- [ ] All hyperparameters in a config file — no literals in training code
+- [ ] Every run tracked with params, metrics, seed, data version, and git commit
+- [ ] Best checkpoint saved with its config alongside the artifact
+- [ ] Experiments follow the ablation plan (one change at a time)