---
name: remote-gpu-trainer
description: "Deploy, monitor, and debug long GPU jobs on RENTED/remote instances (AutoDL, RunPod, vast.ai, Lambda, Slurm, K8s): teardown/billing safety, spot resilience, resumable checkpointing, OOM/NaN triage."
risk: safe
source: community
source_type: community
source_repo: Hanyuyuan6/remote-gpu-trainer
date_added: "2026-06-20"
category: ml-ops
license: "MIT"
license_source: "https://github.com/Hanyuyuan6/remote-gpu-trainer/blob/main/LICENSE"
compatibility: |
  Any Agent-Skills (SKILL.md)-compatible agent — Claude Code, Codex, Cursor, Trae, Gemini CLI, etc.
  Needs a shell + SSH (or a platform CLI/API) to drive the remote box; scripts are bash/python. A few
  durable-monitoring recipes assume a host background-task runner + scheduler — map to the running
  agent's equivalents (references/monitoring_patterns.md §7). Companion skills (verifying-dl-experiments,
  superpowers:*, huggingface-skills:*) are optional separate installs.
---

# remote-gpu-trainer — Remote GPU Job Orchestration

## Overview

Deploy and babysit long-running GPU jobs on **rented boxes you don't own**, across any platform, and
get the result off the box before the meter or a preemption kills it. The core insight: **you are a
short-term tenant on someone else's machine** — so the job is to *detach the work, make the result
outlive the instance, and stop the meter safely*, not to provision a cluster.

This skill is **platform-agnostic at the core, platform-specific at the edges**: a fixed set of
operating principles + a 6-phase lifecycle that hold everywhere, plus one **profile per platform**
(`profiles/<platform>.md`) that owns every concrete path, proxy, billing verb, and spot semantic. Its
defensible value is the union the big orchestrators skip: **Chinese cgroup-isolated rentals + bare-SSH
cheap boxes + the disk-budget / monitoring / teardown reality** that *is* the job on metered hardware.

## When to Use This Skill

Use whenever the user deploys, trains, monitors, or troubleshoots a long-running GPU job on a **RENTED
or remote instance they do not own** — training, eval, ablation sweeps, batch inference, or large data
processing — on AutoDL, RunPod, vast.ai, Lambda, Paperspace, Chinese platforms (恒源云/矩池云/Featurize/
揽睿星舟), a bare SSH box, Slurm, or Kubernetes; single OR multi-instance. Triggers (multilingual):
"远程 GPU 训练", "GPU 租赁", "GPU rental", "租卡", "spot 抢占", "spot preemption", "断点续训",
"resumable training", "tmux 训练守护", "防 SSH 断线", "scp/rsync 上传", "多实例 ablation",
"远程 GPU 监控", "省钱关机/销毁实例", "stop vs terminate billing", "checkpoint 磁盘满",
"CUDA OOM/显存不足", "loss NaN/loss spike", "loss 不下降/不收敛", "overfit 单 batch",
"FSDP/DeepSpeed 配置", "多卡训练 hang", "dataloader worker/数据增广 bug". **NOT** for purely local
single-GPU training, in-instance multi-GPU DDP (use torchrun/accelerate), managed multi-cloud
price-shopping (use SkyPilot's skill), or zero-ops serverless (use Modal).

## When NOT to use — and what to use instead

| Situation | Use instead |
|---|---|
| Local single-GPU, or multi-GPU **DDP inside one box** | `torchrun` / `accelerate` directly |
| Managed multi-cloud price-shopping + auto spot-recovery across **Western** clouds | **SkyPilot** (has its own Agent Skill) — then come back here to make your *code* resume-correct so its recovery actually works |
| Open BYOC dev environments | **dstack** |
| Zero-ops serverless inference | **Modal** |
| "Is this metric / ablation delta real?" | **REQUIRED:** `verifying-dl-experiments` (this skill owns *running* the job; that one owns *whether the number is true*) |

**This skill is for the blind spot those tools leave:** AutoDL + Chinese platforms, bare SSH/Slurm/K8s
rentals, and the operational gotchas (inode caps, mirror stalls, cgroup OOM, silent sync, spot grace
windows, irreversible teardown) that survive whichever provisioner you use.

## Operating principles (the WHY — 10 invariants)

These hold on every metered, isolated, rented GPU; only the paths/CLI change. One line each; the deep
form with cross-platform nuance is in **`references/principles.md`** (read it before Phase 0).

1. **Minimize paid wall-clock.** The meter runs the whole time — smoke locally on CPU before renting, launch detached, release the instant verification passes.
2. **Cheap checks before expensive compute.** A 1–2 batch CPU smoke (logger off) kills import/config/shape/scale bugs for ~free. (Smoke *content* → `verifying-dl-experiments`.)
3. **Trust artifacts you loaded, not log lines that claim success.** "synced/saved/done" lies under a silently-failed write; a watcher's own state is also a claim — reconcile it against the real process/artifact.
4. **Know what survives stop vs destroy.** Per platform, identify exactly which mount survives a *stop* and which survives a *terminate* — the data you need often lives on the volatile one. (The single biggest portability trap.)
5. **Storage fails on the dimension you're not watching.** Disk dies on **inodes** before bytes; the real hog hides in a symlinked cache; clean by value (keep tiny evidence, drop big scratch); monitor `df -i`, not just `df -h`.
6. **Never mutate inputs under a live run.** A running job holds its scripts in memory by byte-offset; overwriting one mid-run re-executes blocks. Version filenames.
7. **Design for retry — failure is probabilistic, transfers are flaky, mirrors are route-specific.** Make wrappers idempotent + resumable; retry the *identical* config; wrap bulk transfers in `timeout`+resume loops; a mirror/proxy speeds ONE route — validate on the same route the real transfer uses.
8. **Checkpoint-to-durable + idempotent resume is the universal spine.** File checkpoint to the platform's durable location + unconditional load-latest-on-startup is the *one* mechanism that survives an SSH drop, a Slurm walltime kill, a K8s reschedule, a spot preemption, and a Colab disconnect. The detach primitive (tmux/sbatch/Job/commit) is the swappable plug; this is the invariant.
9. **Cost and destructive actions are the user's call.** Never auto-release/terminate, never delete durable files without confirmation; if cleanup can't free space, **ask to expand the disk** rather than silently shrink the experiment.
10. **Teach the user the platform, don't just drive it.** Most users don't know a platform's non-obvious **conveniences** (one-click SSH-key registration, GPU-availability notifications, built-in panels) or its **danger clocks** (auto-release/auto-delete timers on a *stopped* box — AutoDL releases a 关机 instance after 15 days → data disk gone; a stop that keeps billing; low-balance purge). Surface them on first contact — #9 stops the agent *doing* the dangerous thing, #10 *warns the human* before the clock fires. Per-platform list → each profile's **Surface to the user** block.

> **Monitoring physics (substrate for #3):** foreground Bash hard-caps at 600 s; `run_in_background` has no cap and notifies on exit; a never-exiting watcher never notifies; an unquoted `|` in a poll regex reads stdin and hangs forever. The four-layer monitoring architecture is built on these facts → `references/monitoring_patterns.md`.

## Code discipline (the wrapper & training scripts you write)

Two rules govern the launch/wrapper/training code this skill has you write — corollaries of #1 and #8, not new invariants:

1. **Reuse before writing.** Take the lowest rung that already works before adding code: the base image's pre-installed stack + platform features → a framework/library utility (`torchrun` / `accelerate` / HF) → your existing `scripts/` templates → minimal new code. On a metered box a needless `pip install` also burns paid wall-clock and can break the image's ABI — Phase 1's rule (*the prebuilt image **is** the env; don't `conda create` on a rental*) is exactly this principle applied to dependencies.
2. **Floor — `minimum` bounds scope, not correctness.** Shrinking code must never drop what makes an expensive run survivable: checkpoint-to-durable + idempotent resume (#8), atomic writes, the error handling that prevents losing a long run, or seed/determinism logging. Keep one minimal self-check for non-trivial logic.

## Pick your platform profile FIRST

Read the matching profile **before Phase 0** — it owns every path, proxy, credential location, billing
verb, and spot rule the phases below delegate to. Each follows the same 8-field schema
(`profiles/_schema.md`).

> **New here? The path is:** (1) find your platform in the table below → (2) read that profile's **LAUNCH**
> section (it walks rent → register SSH key → reach the box) → (3) come back and run the 6 phases from Phase 0.
> Already have a box you can `ssh` into? Skip straight to Phase 0.

| You're on… | Profile | Kind | Detach primitive | Meter-stop verb |
|---|---|---|---|---|
| AutoDL (deepest, battle-tested) | `profiles/autodl.md` | ssh-rental | tmux | 关机 (stops meter, **keeps disk** — the AutoDL exception) |
| RunPod | `profiles/runpod.md` | ssh-rental | tmux | **terminate** (stop still bills 2×; destroys volume disk) |
| vast.ai | `profiles/vastai.md` | ssh-rental (spot) | tmux | **destroy** (stop bills disk forever) |
| Lambda | `profiles/lambda.md` | cloud-api | tmux | **terminate** (no stop state) |
| Paperspace | `profiles/paperspace.md` | cloud-api | tmux | **destroy + release IP + delete storage** (shut-down stops compute only) |
| 恒源云 / 矩池云 / Featurize / 揽睿星舟 | `profiles/china.md` | ssh-rental | tmux | per-platform (data disk often bills while stopped) |
| Bare SSH box / Slurm / K8s / Colab-Kaggle | `profiles/generic-ssh.md` | ssh / slurm / k8s | tmux / sbatch / Job / commit | **manual** (a forgotten box bills 24/7) |

> **Profile confidence:** AutoDL is battle-tested from the author's daily use; the other six profiles are
> built from each platform's official docs + community reports (cited inline, `verified <month>`) and not
> yet independently live-tested — lean on the Phase-0 live measurements and **re-verify any teardown/
> billing fact against current docs before betting money or data** (`references/self-improvement.md` §5).

**Mental verb model** (one API across all platforms; the profile binds each verb to real commands):
`up` (rent+reach) → `push` (code/data on) → `run` (detached + checkpointing) → `watch` (durable monitor) → `pull` (results off + verify) → `down` (stop the meter).

## Default workflow (6 phases)

Skip phases already done. Each phase delegates substrate to the profile and **ends in a runnable check**.

**Phase 0 — Environment audit.** Read the profile's STORAGE survival-matrix + region/DC-lock. Measure live:
`df -h && df -i <data-mount>`, cgroup `memory.max`, `nvidia-smi`. Pre-compute the checkpoint disk budget
(`ckpt_size × N + scratch`). → **verify:** `nvidia-smi` shows the expected GPU and `df -i` is not near 100%.

**Phase 1 — SSH + credentials.** Set the alias/env per the profile (the prebuilt image/base IS the env —
do not `conda create` on a rental). **Never rented before? the profile's LAUNCH section walks rent → register SSH key → connect.** Push secrets via **stdin, never onto a shared/durable FS**
(`references/ssh_transport.md`). → **verify:** `ssh <alias> 'python -c "import torch;print(torch.cuda.is_available())"'`.

**Phase 2 — Wrapper + CPU-smoke gate.** Build an idempotent `run_one`/`run_queue` from `scripts/` (parameterized
from the profile's OVERRIDES; **size batch/workers to the box for a standalone run, but PIN them across cells for a fair comparison** — `references/training/throughput-profiling.md`). **Run the cheap CPU smoke locally BEFORE renting** — it kills the dumb,
expensive failures (e.g. `python -m <your.train.module> --limit-batches 2 --epochs 1` — substitute your own entrypoint; this gate needs your training code plugged in). → **verify:** that smoke exits 0 on 2 batches with the logger disabled.

**Phase 3 — Detached launch.** Launch via the profile's detach primitive; probe briefly (log head + alive +
no traceback), then **hand back** — never a blocking foreground `sleep`. → **verify:** within 60 s, the detach
session is alive and the first log line shows the expected step/epoch.

**Phase 4 — Durable monitoring.** For anything over ~1–2 h, deploy the **four-layer architecture**
(`references/monitoring_patterns.md`): on-box self-completion chain + session patrol loop + event sentinels +
recovery handbook. **On Claude Code, fire the L2 patrol via `/loop 30m` (or `ScheduleWakeup`) running `scripts/health_patrol.sh.template`**; a host with no local recurring runner wires the on-box self-push instead (`references/monitoring_patterns.md` §7). A session-bound watcher alone dies with the session. Classify each outcome →
fixed remediation; **never blind-retry**. → **verify:** the patrol reports even when nothing changed.

**Phase 5 — Aggregate + verify + teardown.** Checked-sync to durable storage (gate the success line on the
copy result — principle #3), then **load-and-verify each artifact** (`scripts/verify_local.py`), THEN the profile's
meter-stopping action. → **verify:** `verify_local.py` reports 100% OK *before* any teardown.

> **Iron Law — teardown gate:** NO `release` / `terminate` / `destroy` / file-delete until checkpoints are
> **pulled to local AND verified by load**, and the user has explicitly approved the cost-affecting action.
> "It looked done in the log" is not evidence (principle #3). On most platforms the meter-stopping action is
> **irreversible** (deletes the disk) — confirmation matters more, not less.

## Parallel ablation fan-out

For N ablation cells: one job per cell, an **isolated write path per job** (no shared mutable output), launched
across instances/queues. **REQUIRED:** `superpowers:dispatching-parallel-agents` supplies the independence
predicate (don't fan out onto shared state) and the mandatory post-fan-out reconciliation. FS-shared deployment
pattern → `references/parallel_ablation.md`.

## Quick reference — the four facts that bite per platform

Full detail in each profile; this table is the at-a-glance.

| Platform | Survives **stop** | Survives **destroy** | Spot grace | China mirror needed |
|---|---|---|---|---|
| AutoDL | /root + data + FS | FS only | n/a | yes (`/etc/network_turbo`, hf-mirror) |
| RunPod | volume disk (bills 2×) | Network Volume only | ~5 s SIGTERM→KILL | no (`hf_transfer`) |
| vast.ai | disk (bills forever) | nothing | ~0 s (abrupt) | no |
| Lambda | n/a (no stop) | nothing | n/a (on-demand) | no |
| China (恒源云/矩池云/…) | varies; data disk bills | per-platform persistent vol | n/a | yes |
| generic-SSH/Slurm/K8s | you own it | you own it | Slurm SIGTERM→KillWait (def 30 s) | only if in China |

## Common gotchas (top 8 inline — full catalog in references/)

The universal ones that cost the most GPU-hours. Symptom → fix; root cause + the rest in
**`references/gotchas_universal.md`** (run `grep -i '<keyword>' references/gotchas_universal.md` to jump).

1. **SSH drops on `pkill -9`** (exit 255 + "Connection reset") — normal; re-ssh to verify, don't panic.
2. **tmux holds the script in memory** — editing it mid-run re-executes blocks; version the filename.
3. **Disk-full crashes `torch.save`** (`iostream error`) — pre-budget; auto-prune `latest.pth`, keep `best`.
4. **cgroup OOM with no traceback** (bare `Killed` / exit 137) — `num_workers × big-tensor`; size workers vs `memory.max`, not CPU count.
5. **Silent sync failure** — `cp … 2>/dev/null; echo synced` lies on a full/inode-exhausted FS; gate the success line on the actual copy result.
6. **Spot preemption grace is tiny (~5 s → ~0 s on the platforms profiled here; AWS-style 2-min grace only on clouds not profiled)** — a SIGTERM-flush handler is NOT a safety net; checkpoint on a timer to durable storage, load-latest unconditionally (`references/spot-resilience.md`).
7. **"Stop" rarely stops the meter** — only `terminate`/`destroy` does, and it's irreversible (deletes the disk). Know the verb from the profile before you click, and on RunPod a stopped Pod can even restart with zero GPUs.
8. **CRLF breaks `.sh` on Linux** — author on Windows → `.gitattributes` `*.sh text eol=lf`; on-box unblock `sed -i 's/\r$//'`.

## When training itself breaks (the model, not the platform)

Platform ops is only half the job — once the box is running, training breaks in its own ways. The
`references/training/` layer is the debug knowledge for the run itself. Boundary: **this layer owns
"make it run, fast, and not crash"; `verifying-dl-experiments` owns "is the *number* real"** —
cross-link it for collapse / leakage / metric-validity. Every entry is symptom → root cause → fix with
cited current docs.

- `references/training/oom-memory.md` — CUDA/VRAM + host-RAM OOM and the fit-it ladder (grad-accum → bf16 → activation-checkpointing → `expandable_segments` → FSDP/ZeRO → CPU/NVMe offload → LoRA/QLoRA); OOM-at-a-specific-step (first backward / val / longest batch); the memory snapshot + visualizer.
- `references/training/distributed-launch.md` — `torchrun`/`accelerate`/`deepspeed` launch + env contract, DDP/FSDP/ZeRO config, and the multi-GPU **HANGS** toolkit (one-rank-diverged, rank-conditional collective, dataloader-length mismatch). Multi-node wire → `references/multinode.md`.
- `references/training/precision-stability.md` — fp16/bf16/tf32 + AMP/GradScaler, NaN/Inf hunting (`detect_anomaly`), LLM **loss spikes** + divergence (warmup, clip, init, z-loss).
- `references/training/throughput-profiling.md` — GPU-bound vs data-bound vs comms-bound; dataloader knobs; `torch.compile` traps; flash-attention; `torch.profiler` / Nsight.
- `references/training/checkpoint-resume.md` — full-state save/resume mechanics, sharded (FSDP/DeepSpeed) checkpoints, and the resume bugs (epoch restart, data reshuffle, scaler/EMA dropped). Spot cadence → `references/spot-resilience.md`.
- `references/training/by-domain.md` — per-domain gotchas: LLM/transformer, vision (det/seg), diffusion, RL, multimodal/VLM.
- `references/training/convergence-debugging.md` — the **"runs but won't learn / learns badly"** layer: the overfit-one-batch smoke, params-not-updating, optimizer/LR/weight-decay/schedule config, loss-function footguns (double-softmax, BCEWithLogits, CE-target form), fine-tuning/freezing (frozen-BN drift, discriminative LR, LoRA wiring), and the training-dynamics dashboard (update:weight ratio, dead-ReLU, GradScaler-scale).
- `references/training/data-pipeline.md` — dataloader/dataset **correctness** (not speed): the worker-RNG augmentation-duplication bug, IterableDataset worker/rank sharding, collate/`__len__`/`pin_memory`/`spawn` contracts, and preprocessing/label/shuffle traps (RGB-vs-BGR, ToTensor ÷255, `set_epoch`).

## Companion skills (separate installs; REQUIRED reading where present)

These are **separate** Agent Skills, not bundled here — install them for the full experience. On an
agent where a companion isn't installed, treat its pointer below as an optional cross-reference; this
skill still works standalone.

- **`verifying-dl-experiments`** — owns *is-the-number-real*: smoke content, retry-vs-safeguard, keepable-checkpoint, eval sizing, tracker forensics, GPU-0%-util diagnosis. This skill owns *where/when/how-much-$*.
- **`huggingface-skills:hf-cli`** — the transport verbs (`hf download --resume`, `hf upload-large-folder`, `hf cache verify`); this skill owns the China-mirror swap + stall-retry (`references/china-network.md`).
- **`huggingface-skills:huggingface-trackio`** — hosted tracker so metrics survive teardown (gotcha U20); poll `trackio` alerts as a structured monitor instead of brittle ssh-tail.
- **`superpowers:verification-before-completion`** — the Iron Law's general form; gates every "training done / synced / teardown complete" claim.
- **`superpowers:dispatching-parallel-agents`** — independence predicate + reconciliation for ablation fan-out.

## Getting better over time (capture new gotchas + personalize)

This skill is static, but every run can teach it something — without corrupting it.
Protocol → **`references/self-improvement.md`**. In short: when a run surfaces a gotcha the catalog
lacks, **only sediment a root-caused, reproduced, generalizable one** (a one-off flake is a hypothesis,
not a gotcha — principle #3); **route it** — user/project-specific → the host's memory system,
generalizable → propose adding to `references/gotchas_universal.md` / the profile §7 /
`references/training/` (and offer an upstream PR); **never silently rewrite a skill file — draft the
`symptom → root cause → fix` and let the user approve.** On first use, capture the user's platforms +
paths + tracker entity into memory so later runs are pre-parameterized. Platform facts carry a `verified
<month>` stamp — re-verify any teardown/billing fact against current docs before betting money or data.

## Limitations

- Does not replace a real cloud orchestrator or managed provisioner; use it to make rented-box work survivable, not to optimize multi-cloud procurement.
- Platform billing, stop, destroy, and data-retention behavior can drift; re-check current provider docs before destructive or money-impacting actions.
- Requires user-owned credentials, SSH/API access, and explicit confirmation before teardown, deletion, or other irreversible cleanup.
- Companion skills named above are not bundled here; treat them as optional references unless installed in the current agent environment.

## Bundled resources

Load only what the current phase needs.

- `references/principles.md` — the 10 invariants expanded, with the cross-platform nuance behind each.
- `references/lifecycle_checklist.md` — the 6-phase runbook as a per-platform checklist.
- `references/gotchas_universal.md` — universal + mixed gotchas (TOC + grep index at top).
- `references/monitoring_patterns.md` — the four-layer durable-monitoring architecture + robust ssh-poll template.
- `references/ssh_transport.md` — ssh config, rsync/scp resumable patterns, secrets-via-stdin, CRLF, two-SSH-flavor caveat.
- `references/china-network.md` — mirrors table + HF_ENDPOINT + resumable-download ladder + the `no_proxy` trap (all CN platforms).
- `references/spot-resilience.md` — preemption signals, Young/Daly checkpoint cadence, atomic-write resume.
- `references/parallel_ablation.md` — FS-shared fan-out + the independence predicate + reconciliation.
- `references/multinode.md` — (advanced) NCCL / fabric-manager / elastic-training gotchas; single-box users skip.
- `references/training/` — the **DL-training debug layer** (8 files: oom-memory, distributed-launch, precision-stability, throughput-profiling, checkpoint-resume, by-domain, convergence-debugging, data-pipeline) — see "When training breaks" above.
- `references/self-improvement.md` — the feedback loop: capture a new gotcha (at a bar) into memory or the catalog, personalize on first run, keep platform facts fresh.
- `scripts/` — wrapper templates (`run_one`/`run_queue`), monitors (`mem_monitor`, `gpu_health`, `reap_vram_zombies`), the read-only patrol (`health_patrol.sh.template`), transfer/aggregation (`download_loop`, `aggregate_to_fs`, `setup-china-mirrors`), the load-and-verify checker (`verify_local.py`), and the `verified`-stamp freshness linter (`check_staleness.py`).
- `profiles/<platform>.md` — the per-platform substrate (one per platform; `_schema.md` defines the 8 fields).
- `examples/autodl_sweep/` — one complete, runnable worked case end to end.


---
name: remotion
description: Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays
allowed-tools:
  - "stitch*:*"
  - "remotion*:*"
  - "Bash"
  - "Read"
  - "Write"
  - "web_fetch"
risk: critical
source: community
---

# Stitch to Remotion Walkthrough Videos

You are a video production specialist focused on creating engaging walkthrough videos from app designs. You combine Stitch's screen retrieval capabilities with Remotion's programmatic video generation to produce smooth, professional presentations.

## Overview

This skill enables you to create walkthrough videos that showcase app screens with professional transitions, zoom effects, and contextual text overlays. The workflow retrieves screens from Stitch projects and orchestrates them into a Remotion video composition.

## Prerequisites

**Required:**
- Access to the Stitch MCP Server
- Access to the Remotion MCP Server (or Remotion CLI)
- Node.js and npm installed
- A Stitch project with designed screens

**Recommended:**
- Familiarity with Remotion's video capabilities
- Understanding of React components (Remotion uses React)

## Retrieval and Networking

### Step 1: Discover Available MCP Servers

Run `list_tools` to identify available MCP servers and their prefixes:
- **Stitch MCP**: Look for `stitch:` or `mcp_stitch:` prefix
- **Remotion MCP**: Look for `remotion:` or `mcp_remotion:` prefix

### Step 2: Retrieve Stitch Project Information

1. **Project lookup** (if Project ID is not provided):
   - Call `[stitch_prefix]:list_projects` with `filter: "view=owned"`
   - Identify target project by title (e.g., "Calculator App")
   - Extract Project ID from `name` field (e.g., `projects/13534454087919359824`)

2. **Screen retrieval**:
   - Call `[stitch_prefix]:list_screens` with the project ID (numeric only)
   - Review screen titles to identify all screens for the walkthrough
   - Extract Screen IDs from each screen's `name` field

3. **Screen metadata fetch**:
   For each screen:
   - Call `[stitch_prefix]:get_screen` with `projectId` and `screenId`
   - Retrieve:
     - `screenshot.downloadUrl` — Visual asset for the video
     - `htmlCode.downloadUrl` — Optional: for extracting text/content
     - `width`, `height` — Screen dimensions for proper scaling
     - Screen title and description for text overlays

4. **Asset download**:
   - Use `web_fetch` or `Bash` with `curl` to download screenshots
   - Save to a staging directory: `assets/screens/{screen-name}.png`
   - Organize assets in order of the intended walkthrough flow

### Step 3: Set Up Remotion Project

1. **Check for existing Remotion project**:
   - Look for `remotion.config.ts` or `package.json` with Remotion dependencies
   - If exists, use the existing project structure

2. **Create new Remotion project** (if needed):
   ```bash
   npm create video@latest -- --blank
   ```
   - Choose TypeScript template
   - Set up in a dedicated `video/` directory

3. **Install dependencies**:
   ```bash
   cd video
   npm install @remotion/transitions @remotion/animated-emoji
   ```

## Video Composition Strategy

### Architecture

Create a modular Remotion composition with these components:

1. **`ScreenSlide.tsx`** — Individual screen display component
   - Props: `imageSrc`, `title`, `description`, `width`, `height`
   - Features: Zoom-in animation, fade transitions
   - Duration: Configurable (default 3-5 seconds per screen)

2. **`WalkthroughComposition.tsx`** — Main video composition
   - Sequences multiple `ScreenSlide` components
   - Handles transitions between screens
   - Adds text overlays and annotations

3. **`config.ts`** — Video configuration
   - Frame rate (default: 30 fps)
   - Video dimensions (match Stitch screen dimensions or scale appropriately)
   - Total duration calculation

### Transition Effects

Use Remotion's `@remotion/transitions` for professional effects:

- **Fade**: Smooth cross-fade between screens
  ```tsx
  import {fade} from '@remotion/transitions/fade';
  ```

- **Slide**: Directional slide transitions
  ```tsx
  import {slide} from '@remotion/transitions/slide';
  ```

- **Zoom**: Zoom in/out effects for emphasis
  - Use `spring()` animation for smooth zoom
  - Apply to important UI elements

### Text Overlays

Add contextual information using Remotion's text rendering:

1. **Screen titles**: Display at the top or bottom of each frame
2. **Feature callouts**: Highlight specific UI elements with animated pointers
3. **Descriptions**: Fade in descriptive text for each screen
4. **Progress indicator**: Show current screen position in walkthrough

## Execution Steps

### Step 1: Gather Screen Assets

1. Identify target Stitch project
2. List all screens in the project
3. Download screenshots for each screen
4. Organize in order of walkthrough flow
5. Create a manifest file (`screens.json`):

```json
{
  "projectName": "Calculator App",
  "screens": [
    {
      "id": "1",
      "title": "Home Screen",
      "description": "Main calculator interface with number pad",
      "imagePath": "assets/screens/home.png",
      "width": 1200,
      "height": 800,
      "duration": 4
    },
    {
      "id": "2",
      "title": "History View",
      "description": "View of previous calculations",
      "imagePath": "assets/screens/history.png",
      "width": 1200,
      "height": 800,
      "duration": 3
    }
  ]
}
```

### Step 2: Generate Remotion Components

Create the video components following Remotion best practices:

1. **Create `ScreenSlide.tsx`**:
   - Use `useCurrentFrame()` and `spring()` for animations
   - Implement zoom and fade effects
   - Add text overlays with proper timing

2. **Create `WalkthroughComposition.tsx`**:
   - Import screen manifest
   - Sequence screens with `<Sequence>` components
   - Apply transitions between screens
   - Calculate proper timing and offsets

3. **Update `remotion.config.ts`**:
   - Set composition ID
   - Configure video dimensions
   - Set frame rate and duration

**Reference Resources:**
- Use `resources/screen-slide-template.tsx` as starting point
- Follow `resources/composition-checklist.md` for completeness
- Review examples in `examples/walkthrough/` directory

### Step 3: Preview and Refine

1. **Start Remotion Studio**:
   ```bash
   npm run dev
   ```
   - Opens browser-based preview
   - Allows real-time editing and refinement

2. **Adjust timing**:
   - Ensure each screen has appropriate display duration
   - Verify transitions are smooth
   - Check text overlay timing

3. **Fine-tune animations**:
   - Adjust spring configurations for zoom effects
   - Modify easing functions for transitions
   - Ensure text is readable at all times

### Step 4: Render Video

1. **Render using Remotion CLI**:
   ```bash
   npx remotion render WalkthroughComposition output.mp4
   ```

2. **Alternative: Use Remotion MCP** (if available):
   - Call `[remotion_prefix]:render` with composition details
   - Specify output format (MP4, WebM, etc.)

3. **Optimization options**:
   - Set quality level (`--quality`)
   - Configure codec (`--codec h264` or `h265`)
   - Enable parallel rendering (`--concurrency`)

## Advanced Features

### Interactive Hotspots

Highlight clickable elements or important features:

```tsx
import {interpolate, useCurrentFrame} from 'remotion';

const Hotspot = ({x, y, label}) => {
  const frame = useCurrentFrame();
  const scale = spring({
    frame,
    fps: 30,
    config: {damping: 10, stiffness: 100}
  });

  return (
    <div style={{
      position: 'absolute',
      left: x,
      top: y,
      transform: `scale(${scale})`
    }}>
      <div className="pulse-ring" />
      <span>{label}</span>
    </div>
  );
};
```

### Voiceover Integration

Add narration to the walkthrough:

1. Generate voiceover script from screen descriptions
2. Use text-to-speech or record audio
3. Import audio into Remotion with `<Audio>` component
4. Sync screen timing with voiceover pacing

### Dynamic Text Extraction

Extract text from Stitch HTML code for automatic annotations:

1. Download `htmlCode.downloadUrl` for each screen
2. Parse HTML to extract key text elements (headings, buttons, labels)
3. Generate automatic callouts for important UI elements
4. Add to composition as timed text overlays

## File Structure

```
project/
├── video/                      # Remotion project directory
│   ├── src/
│   │   ├── WalkthroughComposition.tsx
│   │   ├── ScreenSlide.tsx
│   │   ├── components/
│   │   │   ├── Hotspot.tsx
│   │   │   └── TextOverlay.tsx
│   │   └── Root.tsx
│   ├── public/
│   │   └── assets/
│   │       └── screens/        # Downloaded Stitch screenshots
│   │           ├── home.png
│   │           └── history.png
│   ├── remotion.config.ts
│   └── package.json
├── screens.json                # Screen manifest
└── output.mp4                  # Rendered video
```

## Integration with Remotion Skills

Remotion maintains its own Agent Skills that define best practices. Review these for advanced techniques:

- **Repository**: https://github.com/remotion-dev/remotion/tree/main/packages/skills
- **Installation**: `npx skills add remotion-dev/skills`

Key Remotion skills to leverage:
- Animation timing and easing
- Composition architecture patterns
- Performance optimization
- Audio synchronization

## Common Patterns

### Pattern 1: Simple Slide Show

Basic walkthrough with fade transitions:
- 3-5 seconds per screen
- Cross-fade transitions
- Bottom text overlay with screen title
- Progress bar at top

### Pattern 2: Feature Highlight

Focus on specific UI elements:
- Zoom into specific regions
- Animated circles/arrows pointing to features
- Slow-motion emphasis on key interactions
- Side-by-side before/after comparisons

### Pattern 3: User Flow

Show step-by-step user journey:
- Sequential screen flow with directional slides
- Numbered steps overlay
- Highlight user actions (clicks, taps)
- Connect screens with animated paths

## Troubleshooting

| Issue | Solution |
|-------|----------|
| **Blurry screenshots** | Ensure downloaded images are at full resolution; check `screenshot.downloadUrl` quality settings |
| **Misaligned text** | Verify screen dimensions match composition size; adjust text positioning based on actual screen size |
| **Choppy animations** | Increase frame rate to 60fps; use proper spring configurations with appropriate damping |
| **Remotion build fails** | Check Node version compatibility; ensure all dependencies are installed; review Remotion docs |
| **Timing feels off** | Adjust duration per screen in manifest; preview in Remotion Studio; test with actual users |

## Best Practices

1. **Maintain aspect ratio**: Use actual Stitch screen dimensions or scale proportionally
2. **Consistent timing**: Keep screen display duration consistent unless emphasizing specific screens
3. **Readable text**: Ensure sufficient contrast; use appropriate font sizes; avoid cluttered overlays
4. **Smooth transitions**: Use spring animations for natural motion; avoid jarring cuts
5. **Preview thoroughly**: Always preview in Remotion Studio before final render
6. **Optimize assets**: Compress images appropriately; use efficient formats (PNG for UI, JPG for photos)

## Example Usage

**User prompt:**
```
Look up the screens in my Stitch project "Calculator App" and build a remotion video
that shows a walkthrough of the screens.
```

**Agent workflow:**
1. List Stitch projects → Find "Calculator App" → Extract project ID
2. List screens in project → Identify all screens (Home, History, Settings)
3. Download screenshots for each screen → Save to `assets/screens/`
4. Create `screens.json` manifest with screen metadata
5. Generate Remotion components (`ScreenSlide.tsx`, `WalkthroughComposition.tsx`)
6. Preview in Remotion Studio → Refine timing and transitions
7. Render final video → `calculator-walkthrough.mp4`
8. Report completion with video preview link

## Tips for Success

- **Start simple**: Begin with basic fade transitions before adding complex animations
- **Follow Remotion patterns**: Leverage Remotion's official skills and documentation
- **Use manifest files**: Keep screen data organized in JSON for easy updates
- **Preview frequently**: Use Remotion Studio to catch issues early
- **Consider accessibility**: Add captions; ensure text is readable; use clear visuals
- **Optimize for platform**: Match video dimensions to target platform (YouTube, social media, etc.)

## References

- **Stitch Documentation**: https://stitch.withgoogle.com/docs/
- **Remotion Documentation**: https://www.remotion.dev/docs/
- **Remotion Skills**: https://www.remotion.dev/docs/ai/skills
- **Remotion MCP**: https://www.remotion.dev/docs/ai/mcp
- **Remotion Transitions**: https://www.remotion.dev/docs/transitions

## When to Use
Use this skill when tackling tasks related to its primary domain or functionality as described above.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: remotion-best-practices
description: "Best practices for Remotion - Video creation in React"
risk: safe
source: community
tags: "remotion, video, react, animation, composition"
date_added: "2026-02-27"
---

## When to Use
Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.

## How to use

Read individual rule files for detailed explanations and code examples:

- [rules/3d.md](rules/3d.md) - 3D content in Remotion using Three.js and React Three Fiber
- [rules/animations.md](rules/animations.md) - Fundamental animation skills for Remotion
- [rules/assets.md](rules/assets.md) - Importing images, videos, audio, and fonts into Remotion
- [rules/audio.md](rules/audio.md) - Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
- [rules/calculate-metadata.md](rules/calculate-metadata.md) - Dynamically set composition duration, dimensions, and props
- [rules/can-decode.md](rules/can-decode.md) - Check if a video can be decoded by the browser using Mediabunny
- [rules/charts.md](rules/charts.md) - Chart and data visualization patterns for Remotion
- [rules/compositions.md](rules/compositions.md) - Defining compositions, stills, folders, default props and dynamic metadata
- [rules/display-captions.md](rules/display-captions.md) - Displaying captions in Remotion with TikTok-style pages and word highlighting
- [rules/extract-frames.md](rules/extract-frames.md) - Extract frames from videos at specific timestamps using Mediabunny
- [rules/fonts.md](rules/fonts.md) - Loading Google Fonts and local fonts in Remotion
- [rules/get-audio-duration.md](rules/get-audio-duration.md) - Getting the duration of an audio file in seconds with Mediabunny
- [rules/get-video-dimensions.md](rules/get-video-dimensions.md) - Getting the width and height of a video file with Mediabunny
- [rules/get-video-duration.md](rules/get-video-duration.md) - Getting the duration of a video file in seconds with Mediabunny
- [rules/gifs.md](rules/gifs.md) - Displaying GIFs synchronized with Remotion's timeline
- [rules/images.md](rules/images.md) - Embedding images in Remotion using the Img component
- [rules/import-srt-captions.md](rules/import-srt-captions.md) - Importing .srt subtitle files into Remotion using @remotion/captions
- [rules/lottie.md](rules/lottie.md) - Embedding Lottie animations in Remotion
- [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) - Measuring DOM element dimensions in Remotion
- [rules/measuring-text.md](rules/measuring-text.md) - Measuring text dimensions, fitting text to containers, and checking overflow
- [rules/sequencing.md](rules/sequencing.md) - Sequencing patterns for Remotion - delay, trim, limit duration of items
- [rules/tailwind.md](rules/tailwind.md) - Using TailwindCSS in Remotion
- [rules/text-animations.md](rules/text-animations.md) - Typography and text animation patterns for Remotion
- [rules/timing.md](rules/timing.md) - Interpolation curves in Remotion - linear, easing, spring animations
- [rules/transcribe-captions.md](rules/transcribe-captions.md) - Transcribing audio to generate captions in Remotion
- [rules/transitions.md](rules/transitions.md) - Scene transition patterns for Remotion
- [rules/trimming.md](rules/trimming.md) - Trimming patterns for Remotion - cut the beginning or end of animations
- [rules/videos.md](rules/videos.md) - Embedding videos in Remotion - trimming, volume, speed, looping, pitch

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: render-automation
description: "Automate Render tasks via Rube MCP (Composio): services, deployments, projects. Always search tools first for current schemas."
risk: critical
source: community
date_added: "2026-02-27"
---

# Render Automation via Rube MCP

Automate Render cloud platform operations through Composio's Render toolkit via Rube MCP.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Render connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `render`
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas

## Setup

**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `render`
3. If connection is not ACTIVE, follow the returned auth link to complete Render authentication
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. List and Browse Services

**When to use**: User wants to find or inspect Render services (web services, static sites, workers, cron jobs)

**Tool sequence**:
1. `RENDER_LIST_SERVICES` - List all services with optional filters [Required]

**Key parameters**:
- `name`: Filter services by name substring
- `type`: Filter by service type ('web_service', 'static_site', 'private_service', 'background_worker', 'cron_job')
- `limit`: Maximum results per page (default 20, max 100)
- `cursor`: Pagination cursor from previous response

**Pitfalls**:
- Service types must match exact enum values: 'web_service', 'static_site', 'private_service', 'background_worker', 'cron_job'
- Pagination uses cursor-based approach; follow `cursor` until absent
- Name filter is substring-based, not exact match
- Service IDs follow the format 'srv-xxxxxxxxxxxx'
- Default limit is 20; set higher for comprehensive listing

### 2. Trigger Deployments

**When to use**: User wants to manually deploy or redeploy a service

**Tool sequence**:
1. `RENDER_LIST_SERVICES` - Find the service to deploy [Prerequisite]
2. `RENDER_TRIGGER_DEPLOY` - Trigger a new deployment [Required]
3. `RENDER_RETRIEVE_DEPLOY` - Monitor deployment progress [Optional]

**Key parameters**:
- For TRIGGER_DEPLOY:
  - `serviceId`: Service ID to deploy (required, format: 'srv-xxxxxxxxxxxx')
  - `clearCache`: Set `true` to clear build cache before deploying
- For RETRIEVE_DEPLOY:
  - `serviceId`: Service ID
  - `deployId`: Deploy ID from trigger response (format: 'dep-xxxxxxxxxxxx')

**Pitfalls**:
- `serviceId` is required; resolve via LIST_SERVICES first
- Service IDs start with 'srv-' prefix
- Deploy IDs start with 'dep-' prefix
- `clearCache: true` forces a clean build; takes longer but resolves cache-related issues
- Deployment is asynchronous; use RETRIEVE_DEPLOY to poll status
- Triggering a deploy while another is in progress may queue the new one

### 3. Monitor Deployment Status

**When to use**: User wants to check the progress or result of a deployment

**Tool sequence**:
1. `RENDER_RETRIEVE_DEPLOY` - Get deployment details and status [Required]

**Key parameters**:
- `serviceId`: Service ID (required)
- `deployId`: Deployment ID (required)
- Response includes `status`, `createdAt`, `updatedAt`, `finishedAt`, `commit`

**Pitfalls**:
- Both `serviceId` and `deployId` are required
- Deploy statuses include: 'created', 'build_in_progress', 'update_in_progress', 'live', 'deactivated', 'build_failed', 'update_failed', 'canceled'
- 'live' indicates successful deployment
- 'build_failed' or 'update_failed' indicate deployment errors
- Poll at reasonable intervals (10-30 seconds) to avoid rate limits

### 4. Manage Projects

**When to use**: User wants to list and organize Render projects

**Tool sequence**:
1. `RENDER_LIST_PROJECTS` - List all projects [Required]

**Key parameters**:
- `limit`: Maximum results per page (max 100)
- `cursor`: Pagination cursor from previous response

**Pitfalls**:
- Projects group related services together
- Pagination uses cursor-based approach
- Project IDs are used for organizational purposes
- Not all services may be assigned to a project

## Common Patterns

### ID Resolution

**Service name -> Service ID**:
```
1. Call RENDER_LIST_SERVICES with name=service_name
2. Find service by name in results
3. Extract id (format: 'srv-xxxxxxxxxxxx')
```

**Deployment lookup**:
```
1. Store deployId from RENDER_TRIGGER_DEPLOY response
2. Call RENDER_RETRIEVE_DEPLOY with serviceId and deployId
3. Check status for completion
```

### Deploy and Monitor Pattern

```
1. RENDER_LIST_SERVICES -> find service by name -> get serviceId
2. RENDER_TRIGGER_DEPLOY with serviceId -> get deployId
3. Loop: RENDER_RETRIEVE_DEPLOY with serviceId + deployId
4. Check status: 'live' = success, 'build_failed'/'update_failed' = error
5. Continue polling until terminal state reached
```

### Pagination

- Use `cursor` from response for next page
- Continue until `cursor` is absent or results are empty
- Both LIST_SERVICES and LIST_PROJECTS use cursor-based pagination
- Set `limit` to max (100) for fewer pagination rounds

## Known Pitfalls

**Service IDs**:
- Always prefixed with 'srv-' (e.g., 'srv-abcd1234efgh')
- Deploy IDs prefixed with 'dep-' (e.g., 'dep-d2mqkf9r0fns73bham1g')
- Always resolve service names to IDs via LIST_SERVICES

**Service Types**:
- Must use exact enum values when filtering
- Available types: web_service, static_site, private_service, background_worker, cron_job
- Different service types have different deployment behaviors

**Deployment Behavior**:
- Deployments are asynchronous; always poll for completion
- Clear cache deploys take longer but resolve stale cache issues
- Failed deploys do not roll back automatically; the previous version stays live
- Concurrent deploy triggers may be queued

**Rate Limits**:
- Render API has rate limits
- Avoid rapid polling; use 10-30 second intervals
- Bulk operations should be throttled

**Response Parsing**:
- Response data may be nested under `data` key
- Timestamps use ISO 8601 format
- Parse defensively with fallbacks for optional fields

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| List services | RENDER_LIST_SERVICES | name, type, limit, cursor |
| Trigger deploy | RENDER_TRIGGER_DEPLOY | serviceId, clearCache |
| Get deploy status | RENDER_RETRIEVE_DEPLOY | serviceId, deployId |
| List projects | RENDER_LIST_PROJECTS | limit, cursor |

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: repo-maintainer
description: "Audit and repair repository hygiene across artifacts, dependencies, CI, docs, Git state, and code-quality signals. Use for repository maintenance, cleanup, health checks, or pre-release hardening."
risk: critical
source: https://github.com/Wolfe-Jam/faf-skills/tree/main/skills/repo-maintainer
source_repo: Wolfe-Jam/faf-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/Wolfe-Jam/faf-skills/blob/main/LICENSE
---

# Repository Maintainer

## Overview

Audit repository health, apply authorized repairs narrowly, and finish through the repository's own protected workflow.

## When to Use

Use when the user asks to maintain, clean, audit, harden, or prepare a repository for release. Use a more specific security, database, deployment, or release skill when that is the dominant task.

## Repository Policy Gate

Before mutation:

1. Read root and nested `AGENTS.md`, contributor guidance, maintainer docs, and release instructions.
2. Inspect the current branch, worktree, staged files, remotes, default branch, and effective branch protection.
3. Discover repository-native validation, synchronization, merge, and release commands.
4. Preserve unrelated user work and generated outputs that are not in scope.

If the repository names a mandatory maintainer skill or guarded command, delegate to it instead of inventing a parallel branch, merge, sync, or release path. In `agentic-awesome-skills`, use `antigravity-maintainer-batch-release` and `npm run merge:batch`; `main` is pull-request-only.

The routine protected checks for `agentic-awesome-skills` are `pr-policy`, `pr-evidence`, `source-validation`, and `artifact-preview`. The supported AAS Core preview uses targeted unit tests plus one packed Linux/Node LTS smoke path and Workbench review. Do not resurrect the retired certified-v1 baseline, benchmark, tuning-gold, transaction-fault, race, or frozen OS/runtime matrix as routine merge gates.

## Usage

### 1. Establish the baseline

```bash
git status --short --branch
git diff --stat
git diff --cached --stat
git remote -v
git log -5 --oneline
```

Record the repository's required runtime versions and test commands. Use a clean temporary clone or worktree when existing user changes cannot be isolated safely.

### 2. Audit independent lanes

Run independent read-only checks in parallel where possible.

#### Artifacts and Git hygiene

- untracked caches, coverage, build output, editor files, and test leftovers;
- tracked large or binary files, accidental secrets, executable-mode drift, and ignored-file gaps;
- stale branches, detached HEAD, existing staged changes, submodules, and symlinks;
- generated files whose ownership belongs to CI or a canonical-sync workflow.

Do not delete or rewrite history during the audit.

#### Dependencies and packaging

- lockfile and manifest agreement;
- outdated, vulnerable, duplicate, unused, or end-of-life dependencies;
- runtime imports incorrectly placed in development dependencies;
- clean-install, package-content, and executable-entrypoint behavior.

Treat audit-tool output as evidence to verify, not automatic permission to upgrade or remove packages.

#### CI and release health

- failing, cancelled, skipped, or stale workflow runs;
- stale, redundant, or unjustifiably broad runtime matrices and unpinned or obsolete actions;
- required checks, branch protection, release permissions, and secret boundaries;
- mismatch between documented and implemented release commands.

#### Documentation and repository metadata

- README, changelog, version, examples, links, badges, credits, and support metadata;
- contribution instructions and PR templates versus current CI policy;
- generated catalog, site, or API documentation drift.

#### Code-quality signals

- dead code, stale implementation markers, debug logging, commented-out code, and missing tests;
- unsafe defaults, suppressed errors, credential exposure, and environment-specific paths.

For FAF projects only, also inspect declared `.faf`, `.faf-dna`, sync, score, and MCP contracts with the project's installed FAF commands.

### 3. Produce a prioritized decision set

For each finding report:

- evidence and affected paths;
- severity and user impact;
- whether it is safe to fix now, needs approval, or belongs to another workflow;
- exact validation that proves the repair.

Deduplicate symptoms with the same root cause. Do not mix optional modernization with release blockers.

### 4. Apply authorized repairs

Make the smallest coherent change set. Keep source and generated-file ownership separate, update tests with behavior changes, and rerun the targeted failing check after each repair group.

Never delete data, rewrite history, rotate credentials, change branch protection, or upgrade across breaking versions without explicit authorization.

### 5. Validate and publish safely

Run the repository's required pre-PR suite, then inspect the final diff for unrelated files and secrets. Commit on a topic branch and create a pull request when the target branch is protected.

Use required checks and the repository-native merge path. A user request to “push to main” describes the desired final state; it does not bypass branch protection. For releases, use the scripted release workflow and verify external publication rather than inferring success from a local tag.

## Stop Condition

Finish when every in-scope finding is repaired or has one exact blocker, required validation passes, the remote integration path is verified when requested, and unrelated user work remains unchanged.

## Limitations

- Maintenance findings can depend on repository-specific ownership and release policy; read local instructions before acting.
- Dependency and security scanners can produce false positives or incomplete reachability evidence.
- This skill does not authorize destructive cleanup, branch-policy changes, direct protected-branch pushes, merges, deployments, or releases beyond the user's request.


---
name: requesting-code-review
description: "Use when completing tasks, implementing major features, or before merging to verify work meets requirements"
risk: critical
source: community
date_added: "2026-02-27"
---

# Requesting Code Review

Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.

**Core principle:** Review early, review often.

## When to Request Review

**Mandatory:**
- After each task in subagent-driven development
- After completing major feature
- Before merge to main

**Optional but valuable:**
- When stuck (fresh perspective)
- Before refactoring (baseline check)
- After fixing complex bug

## How to Request

**1. Get git SHAs:**
```bash
BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)
```

**2. Dispatch code-reviewer subagent:**

Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`

**Placeholders:**
- `{WHAT_WAS_IMPLEMENTED}` - What you just built
- `{PLAN_OR_REQUIREMENTS}` - What it should do
- `{BASE_SHA}` - Starting commit
- `{HEAD_SHA}` - Ending commit
- `{DESCRIPTION}` - Brief summary

**3. Act on feedback:**
- Fix Critical issues immediately
- Fix Important issues before proceeding
- Note Minor issues for later
- Push back if reviewer is wrong (with reasoning)

## Example

```
[Just completed Task 2: Add verification function]

You: Let me request code review before proceeding.

BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)

[Dispatch superpowers:code-reviewer subagent]
  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
  BASE_SHA: a7981ec
  HEAD_SHA: 3df7661
  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types

[Subagent returns]:
  Strengths: Clean architecture, real tests
  Issues:
    Important: Missing progress indicators
    Minor: Magic number (100) for reporting interval
  Assessment: Ready to proceed

You: [Fix progress indicators]
[Continue to Task 3]
```

## Integration with Workflows

**Subagent-Driven Development:**
- Review after EACH task
- Catch issues before they compound
- Fix before moving to next task

**Executing Plans:**
- Review after each batch (3 tasks)
- Get feedback, apply, continue

**Ad-Hoc Development:**
- Review before merge
- Review when stuck

## Red Flags

**Never:**
- Skip review because "it's simple"
- Ignore Critical issues
- Proceed with unfixed Important issues
- Argue with valid technical feedback

**If reviewer wrong:**
- Push back with technical reasoning
- Show code/tests that prove it works
- Request clarification

See template at: requesting-code-review/code-reviewer.md

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: research-prompt
description: "Turn vague research needs into one precise deep-research prompt with context and output criteria."
category: research
risk: safe
source: community
source_repo: davidondrej/skills
source_type: community
date_added: "2026-07-07"
author: davidondrej
tags: [research, prompting, briefs]
tools: [claude, codex]
license: "MIT"
license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
---

# Research Prompt

## When to Use

- Use when the user wants a deep-research brief or researcher prompt.
- Use when a vague research question needs to become one precise self-contained paragraph.

Goal: turn a vague research need into ONE self-contained paragraph that a researcher with zero prior knowledge of the project can act on with zero back-and-forth.

## Rules

- **One paragraph.** No headers, no bullet list in the deliverable.
- **Prompt the job, not the topic.** Give search handles (timeframe, ranking, source type, decision logic) — not just a subject.
- **Assume zero prior knowledge.** Write for a researcher who has never heard of the project. Open by explaining, in plain English, what the project/product is, why it exists, and the current situation — so they understand what's going on, what we need, and why we need it.
- **Lead with the goal + decision.** Right after that explainer, state the single question the research must answer and the decision/use it informs.
- **Embed all context.** Names, dates, product, prior known facts, constraints. The researcher must not need to ask anything or guess.
- **Number the sub-questions inline** (1, 2, 3…) so coverage is explicit. Keep to 3–6. One mission per prompt — don't cram unrelated questions.
- **State constraints.** What to include, what to avoid (e.g. "only non-Chinese competitors", "no marketing fluff").
- **Source hierarchy.** Prefer primary sources (official docs, GitHub, papers, filings, changelogs); forums/X/Reddit are weak signal only, never factual proof.
- **Contradiction handling.** If sources conflict, separate confirmed facts / inference / unresolved uncertainty — don't force fake consensus. Flag low-confidence claims for verification.
- **Completion bar (define "done").** Don't stop at the first plausible answer. Corroborate each key claim with multiple independent primary sources where they exist; where sources are scarce, say so explicitly instead of padding. Keep going until every numbered sub-question is covered to this bar.
- **Gap round before finishing.** Require a final self-critique pass: list gaps, contradictions, and any single-source claims, then run another round of searches to close them — repeat until clean.
- **Constrain output hard, method loosely.** Be strict on the deliverable; leave the search path flexible so the researcher can explore.
- **Demand a fixed output per finding:** source link + specific claim + one-line "why it matters / why a viewer should care".
- Verifiable, citable facts only. No opinions.
- **Last sentence:** instruct them to output everything into a single detailed markdown file.

## Process

1. Pull context from the relevant project files / conversation (dates, names, known facts, audience, end use), and write a 1–2 sentence plain-English explainer of what the project is and why it exists for a reader who knows nothing.
2. Identify the ONE question the research answers.
3. Draft 3–6 numbered sub-questions that fully cover it.
4. Add include/avoid constraints + the per-finding output format.
5. Compress to one clean paragraph. Cut filler.

## Template

> [For a reader with zero prior knowledge: in 1–2 plain-English sentences, what the project/product is, why it exists, and the current situation.] Research [TOPIC + key identifying facts] to answer one question: [THE QUESTION] — for [DECISION / END USE]. Find: (1) …; (2) …; (3) …; (4) …. [Constraints: include X, avoid Y.] Prefer primary sources; treat forums/social as weak signal only; if sources conflict, separate fact from inference and flag what needs verification. Don't stop at the first plausible answer: corroborate each key claim with multiple independent primary sources where they exist (and say so explicitly where they don't), continuing until every numbered question is covered to that bar. Before finishing, do a self-critique pass — list gaps, contradictions, and any single-source claims, then run another round of searches to close them, repeating until clean. For each point, give the source link, the specific claim, and a one-line "why it matters". No marketing fluff — verifiable, citable facts only. Output everything into a single detailed markdown file.

## Executing the prompt

To run the finished prompt with an AI researcher, execute it via DeepAPI `POST /v1/research/deep` — follow the `deep-research` skill.

## Limitations

- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.


---
name: resolving-merge-conflicts
description: Use when you need to resolve an in-progress git merge/rebase conflict.
risk: critical
source: https://github.com/mattpocock/skills/tree/main/skills/engineering/resolving-merge-conflicts
source_repo: mattpocock/skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/mattpocock/skills/blob/main/LICENSE
---

## When to Use

Use when you need to resolve an in-progress git merge/rebase conflict.

1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.

2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.

3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.

4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.

5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: retro-design
description: Web and App implementation guide for Retro Design (60s-80s). Trigger when user wants vintage aesthetics, warm muted colors, and nostalgic layouts.
date_added: "2026-06-17"
risk: safe
source: self
source_type: self
---

# Retro Design

> "A warm, analog feeling. Nostalgia through muted tones, grain, and classic typography."

## When to Use
Use this sub-style when the user's request matches the aesthetic described above. This is a child reference of the `design-it` skill and is not meant to be triggered directly.

## Core Principles
1. **Warm, Analog Color Palettes**: Colors look faded by the sun or printed on aged paper.
2. **Texture and Noise**: A slight grain overlay to simulate film or old print media.
3. **Classic Typography Pairings**: Heavy, groovy display fonts paired with typewriter or classic serif body copy.

## Visual DNA
- **Colors**: **Monochromatic Brown** or warm, faded palettes (mustard yellow, burnt orange, sage green, off-white).
- **Typography**: Display fonts like `Cooper Black`, `Garamond`, or `Courier`.
- **Styling**: Badges, stamps, wavy borders, and halftone patterns.

## Web Implementation
- Use CSS filters and background noise images to create texture.
- **CSS Example**:
```css
body {
  background-color: #F4E8D1; /* Aged paper */
  color: #3E2723; /* Deep brown ink */
  font-family: 'Georgia', serif;

  /* Apply a subtle noise overlay using a pseudo-element or background image */
  background-image: url('noise-texture.png');
  background-blend-mode: multiply;
}

.retro-header {
  font-family: 'Cooper Black', serif;
  font-size: 4rem;
  color: #D35400; /* Burnt orange */
  text-shadow: 2px 2px 0px #F1C40F; /* Mustard yellow drop shadow */
  letter-spacing: -1px;
}

.retro-card {
  background-color: #FFF3E0;
  border: 2px solid #3E2723;
  border-radius: 12px;
  padding: 24px;

  /* Vintage offset shadow */
  box-shadow: 8px 8px 0px #795548;
}

.retro-badge {
  display: inline-block;
  background-color: #E74C3C;
  color: #F4E8D1;
  font-family: monospace;
  font-weight: bold;
  padding: 8px 16px;
  border-radius: 50%; /* Make it look like a sticker */
  transform: rotate(-10deg);
}
```

## App Implementation

### SwiftUI
```swift
struct RetroCard: View {
    let paperColor = Color(red: 0.96, green: 0.91, blue: 0.82) // #F4E8D1
    let inkColor = Color(red: 0.24, green: 0.15, blue: 0.14) // #3E2723

    var body: some View {
        ZStack {
            paperColor.ignoresSafeArea()

            // Optional: Noise texture
            Image("film_grain")
                .resizable()
                .blendMode(.multiply)
                .opacity(0.3)
                .ignoresSafeArea()

            VStack(alignment: .leading, spacing: 24) {
                Text("RETRO DESIGN")
                    .font(.custom("Cooper Black", size: 36))
                    .foregroundColor(Color(red: 0.83, green: 0.33, blue: 0.0)) // #D35400
                    .shadow(color: Color(red: 0.95, green: 0.77, blue: 0.06), radius: 0, x: 2, y: 2)

                Text("Analog warmth and classic typography.")
                    .font(.custom("Georgia", size: 18))
                    .foregroundColor(inkColor)
            }
            .padding(32)
            .background(Color(red: 1.0, green: 0.95, blue: 0.88))
            .cornerRadius(12)
            .overlay(
                RoundedRectangle(cornerRadius: 12)
                    .stroke(inkColor, lineWidth: 2)
            )
            // Vintage solid offset shadow
            .shadow(color: Color(red: 0.47, green: 0.33, blue: 0.28), radius: 0, x: 8, y: 8)
        }
    }
}
```
- A grain texture image can be overlaid using `.blendMode(.multiply)`. Be aware of memory usage with full-screen textures.
- Use `.shadow(radius: 0)` to create the hard offset shadows typical of 70s print media.
- Custom fonts like Cooper Black are absolutely required.

### Flutter
```dart
class RetroCard extends StatelessWidget {
  final Color paperColor = const Color(0xFFF4E8D1);
  final Color inkColor = const Color(0xFF3E2723);

  @override
  Widget build(BuildContext context) {
    return Container(
      color: paperColor,
      child: Stack(
        fit: StackFit.expand,
        children: [
          // Noise texture
          Opacity(
            opacity: 0.3,
            child: Image.asset('assets/film_grain.png',
              fit: BoxFit.cover,
              colorBlendMode: BlendMode.multiply),
          ),
          Center(
            child: Container(
              padding: const EdgeInsets.all(32),
              decoration: BoxDecoration(
                color: const Color(0xFFFFF3E0),
                borderRadius: BorderRadius.circular(12),
                border: Border.all(color: inkColor, width: 2),
                boxShadow: const [
                  BoxShadow(
                    color: Color(0xFF795548),
                    blurRadius: 0, // Hard offset shadow
                    offset: Offset(8, 8),
                  ),
                ],
              ),
              child: Column(
                mainAxisSize: MainAxisSize.min,
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  const Text('RETRO DESIGN',
                    style: TextStyle(
                      fontFamily: 'Cooper',
                      fontSize: 36,
                      color: Color(0xFFD35400),
                      shadows: [Shadow(color: Color(0xFFF1C40F), offset: Offset(2, 2))],
                    )),
                  const SizedBox(height: 24),
                  Text('Analog warmth and classic typography.',
                    style: TextStyle(fontFamily: 'Georgia', fontSize: 18, color: inkColor)),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}
```
- Wrap backgrounds in a `Stack` to place a semi-transparent film grain asset over the solid color.
- Drop shadows for text and containers must have `blurRadius: 0` to emulate offset misregistered ink prints.

### React Native
```jsx
const RetroCard = () => {
  return (
    <ImageBackground
      source={require('./film_grain.png')}
      style={{ flex: 1, backgroundColor: '#F4E8D1', padding: 24, justifyContent: 'center' }}
      imageStyle={{ opacity: 0.3, tintColor: '#3E2723' }}
    >
      <View style={{
        backgroundColor: '#FFF3E0',
        padding: 32,
        borderRadius: 12,
        borderWidth: 2,
        borderColor: '#3E2723',
        // Hard drop shadow
        shadowColor: '#795548',
        shadowOffset: { width: 8, height: 8 },
        shadowOpacity: 1,
        shadowRadius: 0,
        elevation: 8, // Fallback for Android, though it blurs
      }}>
        <Text style={{
          fontFamily: 'CooperBlack',
          fontSize: 36,
          color: '#D35400',
          textShadowColor: '#F1C40F',
          textShadowOffset: { width: 2, height: 2 },
          textShadowRadius: 0,
          marginBottom: 24
        }}>
          RETRO DESIGN
        </Text>
        <Text style={{ fontFamily: 'Georgia', fontSize: 18, color: '#3E2723' }}>
          Analog warmth and classic typography.
        </Text>
      </View>
    </ImageBackground>
  );
};
```
- Use `ImageBackground` on the root view for the grain.
- Android's `elevation` cannot do unblurred offset shadows natively. Use `react-native-drop-shadow` for perfect retro shadows on Android.

### Jetpack Compose
```kotlin
@Composable
fun RetroCard() {
    val inkColor = Color(0xFF3E2723)

    Box(modifier = Modifier.fillMaxSize().background(Color(0xFFF4E8D1))) {
        // Noise Texture Overlay
        Image(
            painter = painterResource(id = R.drawable.film_grain),
            contentDescription = null,
            contentScale = ContentScale.Crop,
            modifier = Modifier.matchParentSize().alpha(0.3f),
            colorFilter = ColorFilter.tint(Color.Black, BlendMode.Multiply)
        )

        Box(
            modifier = Modifier
                .align(Alignment.Center)
                .padding(24.dp)
                // Fake hard shadow in compose by drawing behind
                .drawBehind {
                    drawRoundRect(
                        color = Color(0xFF795548),
                        topLeft = Offset(8.dp.toPx(), 8.dp.toPx()),
                        size = size,
                        cornerRadius = CornerRadius(12.dp.toPx())
                    )
                }
                .background(Color(0xFFFFF3E0), RoundedCornerShape(12.dp))
                .border(2.dp, inkColor, RoundedCornerShape(12.dp))
                .padding(32.dp)
        ) {
            Column {
                Text("RETRO DESIGN",
                    fontFamily = FontFamily(Font(R.font.cooper_black)),
                    fontSize = 36.sp,
                    color = Color(0xFFD35400),
                    style = TextStyle(shadow = Shadow(Color(0xFFF1C40F), Offset(4f, 4f), 0f))
                )
                Spacer(Modifier.height(24.dp))
                Text("Analog warmth and classic typography.",
                    fontFamily = FontFamily.Serif,
                    fontSize = 18.sp,
                    color = inkColor)
            }
        }
    }
}
```
- Native `Modifier.shadow` creates soft blurs. Use `Modifier.drawBehind` to draw an offset `drawRoundRect` for the hard retro shadow block.
- Text shadows support hard offsets perfectly via `Shadow(color, offset, blurRadius = 0f)`.

## Do's and Don'ts
- **DO**: Use slightly off-white backgrounds (cream, beige) instead of pure `#FFFFFF` to simulate aged paper.
- **DON'T**: Use sleek, modern geometric sans-serifs or tech-focused neon colors.

## Limitations
- This is a styling reference and does not replace environment-specific validation, accessibility testing, or expert review.
- Ensure appropriate contrast ratios and responsive behaviors are verified separately.


---
name: retro-futurism
description: Web and App implementation guide for Retro Futurism. Trigger when user wants vintage future concepts, 1950s space age aesthetics, or atompunk vibes.
date_added: "2026-06-17"
risk: safe
source: self
source_type: self
---

# Retro Futurism

> "The future as imagined in the 1950s and 60s. Rockets, atoms, and sleek, aerodynamic chrome."

## When to Use
Use this sub-style when the user's request matches the aesthetic described above. This is a child reference of the `design-it` skill and is not meant to be triggered directly.

## Core Principles
1. **Aerodynamic Shapes**: Lots of sweeping curves, teardrop shapes, and swooping lines. Nothing is a perfect square.
2. **Space-Age Motifs**: Stars, atoms, orbits, and fins (like a 1950s Cadillac).
3. **Mid-Century Colors mixed with Chrome**: Classic 50s pastels paired with shiny, reflective metals.

## Visual DNA
- **Colors**: Turquoise (`#40E0D0`), Atomic Tangerine (`#FF9966`), Mint Green (`#98FF98`), paired with Silver/Chrome and deep Space Black.
- **Typography**: Googie architecture fonts, bold cursive scripts, or clean mid-century geometric sans-serifs (like `Futura`).
- **Styling**: Sleek bezels, dramatic drop shadows, and offset overlapping shapes.

## Web Implementation
- **CSS Example**:
```css
body {
  background-color: #FDF5E6; /* Old paper / cream */
  color: #2F4F4F;
  font-family: 'Futura', 'Trebuchet MS', sans-serif;
  overflow-x: hidden;
}

/* Googie-style sweeping background element */
.retro-future-swoop {
  position: absolute;
  top: 0; right: -10%;
  width: 120%; height: 300px;
  background-color: #40E0D0; /* Turquoise */
  border-radius: 0 0 50% 50%;
  transform: rotate(-5deg);
  z-index: -1;
  border-bottom: 8px solid #FF9966; /* Atomic tangerine stripe */
}

.atompunk-card {
  background-color: #fff;
  border: 4px solid #Silver;
  border-radius: 40px 10px 40px 10px; /* Sweeping, aerodynamic corners */
  padding: 32px;
  box-shadow: 15px 15px 0px rgba(0,0,0,0.1);
  position: relative;
}

/* Classic starburst motif */
.starburst {
  position: absolute;
  top: -20px; left: -20px;
  width: 40px; height: 40px;
  background-color: #FF9966;
  clip-path: polygon(50% 0%, 61% 35%, 98% 35%, 68% 57%, 79% 91%, 50% 70%, 21% 91%, 32% 57%, 2% 35%, 39% 35%);
}
```

## App Implementation

### SwiftUI
```swift
struct AtompunkShape: Shape {
    func path(in rect: CGRect) -> Path {
        var path = Path()
        // Sweeping aerodynamic curves (large radius top-left, bottom-right)
        path.addRoundedRect(
            in: rect,
            cornerSize: CGSize(width: 40, height: 40),
            style: .continuous
        )
        // To be perfectly authentic, use Path to draw teardrop curves
        return path
    }
}

struct RetroFutureCard: View {
    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text("ATOMPUNK")
                .font(.custom("Futura", size: 28))
                .fontWeight(.bold)
                .foregroundColor(Color(red: 0.18, green: 0.31, blue: 0.31))

            Text("Sleek chrome and sweeping curves.")
                .font(.custom("Futura", size: 16))
        }
        .padding(32)
        .background(Color.white)
        // Asymmetric corners: large top-left/bottom-right, small top-right/bottom-left
        .cornerRadius(40, corners: [.topLeft, .bottomRight])
        .cornerRadius(10, corners: [.topRight, .bottomLeft])
        .overlay(
            // Chrome-like border
            RoundedRectangle(cornerRadius: 10) // Simplified overlay for demo
                .stroke(
                    LinearGradient(colors: [.gray, .white, .gray], startPoint: .top, endPoint: .bottom),
                    lineWidth: 4
                )
        )
        .shadow(color: .black.opacity(0.1), radius: 0, x: 15, y: 15)
    }
}
// Note: Asymmetric corners require a custom ViewModifier in SwiftUI.
```
- Rely on asymmetrical corner radii to create the aerodynamic, teardrop aesthetic.
- Metallic/Chrome borders are faked by using a `LinearGradient` of grays and whites.

### Flutter
```dart
class RetroFutureCard extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(32),
      decoration: BoxDecoration(
        color: Colors.white,
        // Asymmetric "aerodynamic" shape
        borderRadius: const BorderRadius.only(
          topLeft: Radius.circular(40),
          bottomRight: Radius.circular(40),
          topRight: Radius.circular(10),
          bottomLeft: Radius.circular(10),
        ),
        // Chrome border simulation
        border: Border.all(
          width: 4,
          color: Colors.transparent, // Requires custom painter for gradient border
        ),
        boxShadow: [
          BoxShadow(
            color: Colors.black.withOpacity(0.1),
            offset: const Offset(15, 15),
            blurRadius: 0, // Hard shadow
          ),
        ],
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        children: const [
          Text('ATOMPUNK',
            style: TextStyle(fontFamily: 'Futura', fontSize: 28, fontWeight: FontWeight.bold, color: Color(0xFF2F4F4F))),
          SizedBox(height: 16),
          Text('Sleek chrome and sweeping curves.',
            style: TextStyle(fontFamily: 'Futura', fontSize: 16)),
        ],
      ),
    );
  }
}
```
- Flutter handles asymmetric corners natively via `BorderRadius.only()`.
- Gradient borders (for chrome) require a `CustomPaint` or wrapping the container in another container with a gradient background and padding.

### React Native
```jsx
const RetroFutureCard = () => {
  return (
    <View style={{
      backgroundColor: '#FFF',
      padding: 32,
      // Asymmetric aerodynamic corners
      borderTopLeftRadius: 40,
      borderBottomRightRadius: 40,
      borderTopRightRadius: 10,
      borderBottomLeftRadius: 10,

      borderWidth: 4,
      borderColor: '#C0C0C0', // Solid silver fallback for chrome

      // Offset hard shadow
      shadowColor: '#000',
      shadowOffset: { width: 15, height: 15 },
      shadowOpacity: 0.1,
      shadowRadius: 0,
      elevation: 5,
    }}>
      <Text style={{ fontFamily: 'Futura', fontSize: 28, fontWeight: 'bold', color: '#2F4F4F' }}>
        ATOMPUNK
      </Text>
      <Text style={{ fontFamily: 'Futura', fontSize: 16, marginTop: 16 }}>
        Sleek chrome and sweeping curves.
      </Text>
    </View>
  );
};
```
- React Native natively supports `borderTopLeftRadius` style independent props, making the aerodynamic shapes trivial.
- Complex geometric backgrounds (like starbursts) should definitely be SVG components imported via `react-native-svg`.

### Jetpack Compose
```kotlin
@Composable
fun RetroFutureCard() {
    Box(
        modifier = Modifier
            .padding(24.dp)
            // Fake hard shadow
            .drawBehind {
                drawRoundRect(
                    color = Color.Black.copy(alpha = 0.1f),
                    topLeft = Offset(15.dp.toPx(), 15.dp.toPx()),
                    size = size,
                    cornerRadius = CornerRadius(40.dp.toPx(), 10.dp.toPx()) // Simplification
                )
            }
            .background(
                color = Color.White,
                // Aerodynamic asymmetric corners
                shape = RoundedCornerShape(
                    topStart = 40.dp,
                    topEnd = 10.dp,
                    bottomEnd = 40.dp,
                    bottomStart = 10.dp
                )
            )
            .border(
                width = 4.dp,
                brush = Brush.verticalGradient(listOf(Color.LightGray, Color.White, Color.LightGray)),
                shape = RoundedCornerShape(
                    topStart = 40.dp,
                    topEnd = 10.dp,
                    bottomEnd = 40.dp,
                    bottomStart = 10.dp
                )
            )
            .padding(32.dp)
    ) {
        Column {
            Text("ATOMPUNK",
                fontFamily = FontFamily.SansSerif, // Replace with Futura
                fontSize = 28.sp, fontWeight = FontWeight.Bold, color = Color(0xFF2F4F4F))
            Spacer(Modifier.height(16.dp))
            Text("Sleek chrome and sweeping curves.", fontSize = 16.sp)
        }
    }
}
```
- Use `RoundedCornerShape(topStart, topEnd, bottomEnd, bottomStart)` to create the atompunk aesthetic.
- The `Modifier.border` takes a `Brush` natively, making the metallic chrome gradient incredibly easy to achieve compared to other frameworks.

## Do's and Don'ts
- **DO**: Use strict `Futura` or `Century Gothic` for a very authentic mid-century feel.
- **DON'T**: Make the UI look dirty or distressed (that's standard retro or steampunk). Retro-futurism is clean, optimistic, and shiny.

## Limitations
- This is a styling reference and does not replace environment-specific validation, accessibility testing, or expert review.
- Ensure appropriate contrast ratios and responsive behaviors are verified separately.