agents-united 1.0.0 → 1.2.0

package/registry/skills/hf-model-evaluation/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: hf-model-evaluation
+description: Automated evaluation, benchmarking, dataset curation, and leaderboard metric verification using the Hugging Face ecosystem (Evaluate, Datasets, Transformers).
+metadata:
+  author: "Hugging Face / agents-united"
+  version: "2.0.0"
+  license: "MIT"
+---
+
+# Hugging Face Model Evaluation Playbook
+
+## Overview & Purpose
+`hf-model-evaluation` provides standardized benchmarking workflows for assessing LLM and embedding model performance on standardized evaluation benchmarks using Hugging Face datasets and evaluation harnesses.
+
+## When to Trigger
+Trigger this skill whenever:
+- Running deterministic evaluation benchmarks (MMLU, GSM8k, HumanEval, ARC, Hellaswag).
+- Measuring LLM answer faithfulness, context recall, and toxicity scoring with automated harnesses.
+- Curating golden evaluation splits and synthetic test datasets with Hugging Face Datasets.
+- Generating comprehensive model cards and leaderboard performance summaries.
+
+## Input & Output Requirements
+- **Inputs**: Target model weights/repo ID, evaluation dataset split names, benchmark task configuration YAML, and random seeds.
+- **Outputs**: Automated metric reports (accuracy, exact match, F1, ROUGE, BERTScore), latency benchmarks, and Hugging Face model cards.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Benchmark Task & Dataset Configuration
+- Load standardized benchmark datasets via `datasets.load_dataset()`.
+- Define few-shot prompt formatting templates and deterministic parameters (temperature=0, top_p=1.0).
+
+### Phase 2 — Evaluation Harness Execution
+- Run batch evaluation using `lm-evaluation-harness` or `ragas` library.
+- Log token generation latency, GPU memory footprint, and exact match outputs.
+
+### Phase 3 — Metric Aggregation & Error Analysis
+- Aggregate scores across dataset domains and identify failure clusters.
+- Compute confidence intervals and statistical significance deltas against baseline models.
+
+### Phase 4 — Model Card Publishing
+- Document evaluation methodology, carbon footprint, model limitations, and benchmark results in a README model card.
+
+## Edge Cases & Boundary Conditions
+- **Data Contamination**: Audit evaluation test splits against training datasets to ensure no memorization or test set leakage.
+- **Non-Deterministic Outputs**: Fix random seeds in PyTorch, CUDA, and Hugging Face pipelines (`transformers.set_seed(42)`).
+- **Prompt Sensitivity Variations**: Evaluate across 3 distinct prompt variations to measure prompt robustness.
+
+## Error Recovery & Fallbacks
+- If GPU VRAM is exceeded during evaluation, reduce batch size or enable 8-bit model loading (`load_in_8bit=True`).
+- If dataset download fails from Hugging Face Hub, use cached local disk splits.
+
+## Code Exemplars & Patterns
+
+```python
+import evaluate
+from datasets import load_dataset
+from transformers import pipeline, set_seed
+
+set_seed(42)
+
+# 1. Load evaluation metric and dataset
+exact_match_metric = evaluate.load("exact_match")
+eval_dataset = load_dataset("trivia_qa", "rc.nocontext", split="validation[:100]")
+
+# 2. Initialize generation pipeline
+generator = pipeline("text-generation", model="meta-llama/Llama-3.1-8B-Instruct", device_map="auto")
+
+predictions = []
+references = []
+
+for item in eval_dataset:
+    prompt = f"Answer concisely: {item['question']}\nAnswer:"
+    res = generator(prompt, max_new_tokens=32, temperature=0.0)
+    pred_text = res[0]['generated_text'].replace(prompt, '').strip()
+    predictions.append(pred_text)
+    references.append(item['answer']['value'])
+
+results = exact_match_metric.compute(predictions=predictions, references=references)
+print(f"Exact Match Accuracy: {results['exact_match']:.2%}")
+```

package/registry/skills/interaction-pattern-library/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: interaction-pattern-library
+description: Production-grade Interaction Pattern Library playbook for design operations, UX systems, and growth strategy.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Interaction Pattern Library
+
+## Overview & Purpose
+The Interaction Pattern Library skill provides a deterministic framework for executing interaction pattern library processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute Interaction Pattern Library tasks.
+- Auditing existing product assets or workflows.
+- Standardizing interaction-pattern-library procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/interaction-pattern-library/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/interaction-pattern-library/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/interaction-pattern-library/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/interaction-pattern-library/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/interaction-pattern-library/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/interaction-pattern-library/ reports/interaction-pattern-library/
+   git commit -m "feat(interaction-pattern-library): implement Interaction Pattern Library playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Interaction Pattern Library Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "interaction-pattern-library"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/interaction-pattern-library/summary.json"
+```
+
+### Exemplar 2: Interaction Pattern Library Helper Module
+```typescript
+export function runInteractionPatternLibrary(scope: string): boolean {
+  console.log('Running Interaction Pattern Library on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Interaction Pattern Library
+1. **Diagnosis**: Specification or code asset fails validation rules in interaction-pattern-library.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for Interaction Pattern Library
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/interactive-prototype-builder/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: interactive-prototype-builder
+description: Production-grade Interactive Prototype Builder playbook for design operations, UX systems, and growth strategy.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Interactive Prototype Builder
+
+## Overview & Purpose
+The Interactive Prototype Builder skill provides a deterministic framework for executing interactive prototype builder processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute Interactive Prototype Builder tasks.
+- Auditing existing product assets or workflows.
+- Standardizing interactive-prototype-builder procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/interactive-prototype-builder/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/interactive-prototype-builder/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/interactive-prototype-builder/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/interactive-prototype-builder/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/interactive-prototype-builder/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/interactive-prototype-builder/ reports/interactive-prototype-builder/
+   git commit -m "feat(interactive-prototype-builder): implement Interactive Prototype Builder playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Interactive Prototype Builder Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "interactive-prototype-builder"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/interactive-prototype-builder/summary.json"
+```
+
+### Exemplar 2: Interactive Prototype Builder Helper Module
+```typescript
+export function runInteractivePrototypeBuilder(scope: string): boolean {
+  console.log('Running Interactive Prototype Builder on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Interactive Prototype Builder
+1. **Diagnosis**: Specification or code asset fails validation rules in interactive-prototype-builder.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for Interactive Prototype Builder
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/local-llm-inference/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: local-llm-inference
+description: Local and on-premise LLM inference with Ollama, vLLM, GGUF quantizations, PagedAttention, and OpenAI-compatible API servers.
+metadata:
+  author: "Ollama & vLLM Community / agents-united"
+  version: "2.0.0"
+  license: "MIT"
+---
+
+# Local LLM Inference Playbook
+
+## Overview & Purpose
+`local-llm-inference` provides configuration and optimization guidelines for running open-source LLMs locally (Ollama) or in high-concurrency production environments (vLLM).
+
+## When to Trigger
+Trigger this skill whenever:
+- Setting up local development workflows with privacy-preserving offline LLMs.
+- Configuring Ollama CLI, custom Modelfile templates, and parameters.
+- Deploying high-throughput vLLM inference servers with PagedAttention and continuous batching.
+- Selecting model quantizations (GGUF, AWQ, GPTQ) for hardware memory limits.
+
+## Input & Output Requirements
+- **Inputs**: Model name or GGUF file path, hardware specifications (CPU, Apple Silicon RAM, NVIDIA VRAM), and inference API port.
+- **Outputs**: Running local inference daemon, OpenAI-compatible REST endpoints (`/v1/chat/completions`), and benchmark metrics.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Environment Reconnaissance & Model Selection
+- Assess available RAM/VRAM to choose appropriate quantization (4-bit vs 8-bit).
+- Pull model weights via Ollama CLI or download Hugging Face safetensors for vLLM.
+
+### Phase 2 — Server Launch & Optimization
+- Launch Ollama server or start vLLM daemon with tuned `--gpu-memory-utilization` and `--max-model-len`.
+- Verify GPU offloading layers and memory allocation.
+
+### Phase 3 — Verification & Client Connection
+- Test local endpoint with curl or OpenAI SDK pointing to `http://localhost:11434/v1` or `http://localhost:8000/v1`.
+- Measure Time-to-First-Token (TTFT) and sustained generation throughput.
+
+## Edge Cases & Boundary Conditions
+- **System Memory Pressure**: If total model weights exceed VRAM, configure Ollama partial CPU offloading or reduce context length.
+- **High Concurrency Latency Spikes**: Enable continuous batching and tensor parallelism across multiple GPUs in vLLM.
+- **Prompt Format Mismatches**: Ensure chat templates match exact model tokenizers (e.g. ChatML, Llama-3 headers).
+
+## Error Recovery & Fallbacks
+- If vLLM crashes with CUDA OOM, restart daemon with lower `--gpu-memory-utilization 0.80` and `--max-num-seqs 64`.
+- If Ollama service fails to respond, restart daemon and verify model file integrity with `ollama list`.
+
+## Code Exemplars & Patterns
+
+```bash
+# Start vLLM OpenAI-compatible server with PagedAttention and AWQ quantization
+python3 -m vllm.entrypoints.openai.api_server \
+  --model casperhansen/llama-3-8b-instruct-awq \
+  --quantization awq \
+  --dtype float16 \
+  --gpu-memory-utilization 0.90 \
+  --max-model-len 8192 \
+  --port 8000
+```
+
+```python
+from openai import OpenAI
+
+# Connect standard OpenAI client to local vLLM / Ollama instance
+client = OpenAI(base_url="http://localhost:8000/v1", api_key="local-token")
+
+response = client.chat.completions.create(
+    model="casperhansen/llama-3-8b-instruct-awq",
+    messages=[{"role": "user", "content": "Explain vector indexing in 2 sentences."}],
+    temperature=0.7,
+)
+print(response.choices[0].message.content)
+```

package/registry/skills/maestro-mobile-testing/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: maestro-mobile-testing
+description: Declarative mobile UI testing with Maestro, automated mobile regression flows, deep linking, and cross-platform verification.
+metadata:
+  author: "tovimx (tovimx/maestro-mobile-testing-skill)"
+  version: "1.0.0"
+  source: "https://skills.sh/tovimx/maestro-mobile-testing-skill/maestro-mobile-testing"
+---
+
+# Maestro Mobile E2E Testing Playbook
+
+## Overview & Purpose
+`maestro-mobile-testing` provides instructions and patterns for authoring declarative, readable mobile UI test flows for iOS and Android using Maestro.
+
+## Rules & Constraints
+1. **Use Text and Accessibility Identifiers** — Prefer `tapOn: "Button Text"` or `tapOn: { id: "button_id" }` over brittle coordinates.
+2. **Avoid Hardcoded Sleeps** — Rely on Maestro's built-in auto-waiting for elements to render.
+3. **Isolate Test Flows** — Use `launchApp: { clearState: true }` to guarantee independent test preconditions.
+4. **Assert Visible Text and State** — Verify expected screen content with `assertVisible: "Welcome Screen"`.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Test Flow Definition
+- Create `.maestro/` directory containing YAML test flow files (e.g. `auth_flow.yaml`, `checkout_flow.yaml`).
+- Define appId and target environment configurations.
+
+### Phase 2 — Flow Execution & Actions
+- Author steps: `tapOn`, `inputText`, `scroll`, `back`, `assertVisible`.
+- Add conditional checks (`runFlow: { when: { visible: "Modal" } }`).
+
+### Phase 3 — Verification
+- Run tests on iOS Simulator and Android Emulator via `maestro test .maestro/`.
+
+## Verification Checklist
+- [ ] Test flows execute deterministically on both iOS and Android.
+- [ ] No brittle coordinate-based taps.
+- [ ] Clear error logs and screenshots captured on assertion failure.

package/registry/skills/marketing-creative-design/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: marketing-creative-design
+description: Production-grade Marketing Creative Design playbook for multi-channel ad creative layouts, visual hierarchy, aspect ratio adaptation, brand asset generation, and export optimization.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Marketing Creative Design & Multi-Channel Visual Asset Generation
+
+## Overview & Purpose
+The Marketing Creative Design skill provides a deterministic framework for generating high-converting visual advertising creatives, banner layouts, social media visual assets, typography scales, color palettes, and responsive multi-aspect ratio asset packages (1:1 square, 9:16 vertical stories/reels, 16:9 widescreen landscape, 4:5 mobile feed portrait).
+
+Following this skill ensures strict brand guideline adherence, visual hierarchy compliance, WCAG contrast accessibility, and automated multi-channel export optimization (WebP, AVIF, SVG, PNG).
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Request to design multi-channel ad creative suites (Meta, Google Display, LinkedIn, Twitter/X, TikTok).
+- Generating responsive banner ad variants and hero visual graphics.
+- Creating standardized brand asset kits and typography/color design tokens for marketing campaigns.
+- Exporting, compressing, and formatting creative visual assets for production ad deployment.
+
+### Prerequisites
+- Brand identity guidelines (color tokens, font families, logo vector files).
+- Campaign messaging, headline copy, value proposition hooks, and primary call-to-action (CTA).
+- Asset processing tooling operational (Sharp, Squoosh, Canvas/SVG generators, Figma tokens).
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `campaign_name` | String | Yes | Unique campaign or experiment identifier |
+| `target_aspect_ratios` | Array<String> | Yes | Target ratios: `['1:1', '9:16', '16:9', '4:5']` |
+| `headline_hook` | String | Yes | Primary hook headline text for creative display |
+| `cta_text` | String | Yes | Button label (e.g. "Start Free Trial", "Book Demo") |
+| `brand_tokens` | Object | Optional | Color hex codes, typography scale, logo paths |
+| `output_format` | String | Optional | Desired export format (`webp`, `avif`, `png`, `svg`) |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Creative Brief Spec | `docs/marketing-creative-design/creative-brief.md` | Full design specification and layout rules |
+| Generated Assets | `assets/creatives/<campaign>/*` | Multi-aspect ratio image and vector assets |
+| Asset Manifest | `reports/marketing-creative-design/manifest.json` | Dimension, aspect ratio, and file size index |
+| Visual Audit Report | `reports/marketing-creative-design/audit.json` | Contrast ratio, safe-zone, and file size checks |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Creative Brief Analysis & Visual Architecture
+1. Ingest campaign goals, target buyer persona, and core value proposition.
+2. Select visual layout archetype (Hero Product Showcase, Split Comparison, Social Proof Badge, Bold Typography Hook).
+3. Establish color palette hierarchy: 60% dominant canvas, 30% structural contrast, 10% high-contrast accent for CTA.
+4. Verify typography hierarchy (Headline > Subheadline > Benefit Bullets > CTA Button > Microcopy/Legal).
+5. Inspect repository asset directories to locate existing brand vectors and font files.
+   ```bash
+   find assets/ -type f -name "*.svg" -o -name "*.png"
+   ```
+
+### Phase 2: Design Token & Aspect Ratio Grid Layout Setup
+1. Define aspect ratio canvas dimensions:
+   - 1:1 Feed Square: 1080 x 1080 px
+   - 9:16 Vertical Stories / Reels / TikTok: 1080 x 1920 px (Safe zone: top 250px, bottom 350px clear)
+   - 16:9 Widescreen Display / YouTube: 1920 x 1080 px (or 1200 x 628 px for Google Display)
+   - 4:5 Mobile Feed Portrait: 1080 x 1350 px
+2. Configure layout grid margins (minimum 64px padding on mobile, 96px on desktop displays).
+3. Set up responsive text scaling curves to ensure headline readability across mobile viewports.
+4. Establish focal point safe zones to prevent platform UI overlay clipping (profile icons, audio badges, CTA bars).
+
+### Phase 3: Visual Asset Composition & Multi-Variant Generation
+1. Compose base vector or canvas layout applying design system tokens.
+2. Render headline typography with strict line-height and kerning adjustments.
+3. Position primary brand mark/logo in top-left or top-center anchor with minimum clear space.
+4. Insert hero imagery or product mockups with calibrated drop shadows and elevation depth.
+5. Render high-contrast CTA pill button with accessible foreground/background color combinations.
+6. Generate multi-variant creative matrices testing 3 headline angles against 2 background styles (6 variants total).
+
+### Phase 4: Contrast Auditing, File Optimization & Export Encoding
+1. Execute automated WCAG AA/AAA contrast check between text elements and background layers (minimum 4.5:1 ratio).
+2. Run image compression pipeline targeting optimal delivery sizes:
+   - Display Ads: < 150 KB
+   - Social Feed Creatives: < 1.5 MB (lossless WebP/PNG)
+3. Convert master vector graphics into optimized WebP and high-density 2x PNG assets.
+   ```bash
+   node scripts/optimize-creatives.js --input assets/creatives/raw --output assets/creatives/dist
+   ```
+4. Verify image dimensions, color profiles (sRGB), and metadata strip compliance.
+
+### Phase 5: Manifest Compilation & Asset Review Handoff
+1. Compile generated creative manifest indexing filenames, dimensions, aspect ratios, file sizes, and checksums.
+2. Generate visual review sheet at `docs/marketing-creative-design/creative-brief.md`.
+3. Verify zero broken image references or missing aspect ratio variants.
+4. Commit validated creative assets to git repository.
+   ```bash
+   git add assets/creatives/ docs/marketing-creative-design/
+   git commit -m "feat(marketing-creative-design): generate multi-channel creative asset suite"
+   ```
+5. Hand off creative assets to paid acquisition and campaign execution teams.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Multi-Aspect Ratio Creative Layout Specification
+```yaml
+version: "2.0.0"
+campaign: "q3-enterprise-saas-launch"
+brand:
+  colors:
+    primary: "#0F172A"
+    accent: "#3B82F6"
+    cta: "#10B981"
+    background: "#F8FAFC"
+  typography:
+    headlineFont: "Inter, sans-serif"
+    weight: 800
+variants:
+  - ratio: "1:1"
+    width: 1080
+    height: 1080
+    safeZone: { top: 64, bottom: 64, left: 64, right: 64 }
+    layout: "center-stacked"
+  - ratio: "9:16"
+    width: 1080
+    height: 1920
+    safeZone: { top: 250, bottom: 350, left: 80, right: 80 }
+    layout: "vertical-flow"
+  - ratio: "16:9"
+    width: 1920
+    height: 1080
+    safeZone: { top: 80, bottom: 80, left: 120, right: 120 }
+    layout: "split-horizontal"
+```
+
+### Exemplar 2: TypeScript Programmatic Creative Asset Generator
+```typescript
+export interface CreativeAssetSpec {
+  campaign: string;
+  variantId: string;
+  aspectRatio: '1:1' | '9:16' | '16:9' | '4:5';
+  width: number;
+  height: number;
+  headline: string;
+  ctaText: string;
+}
+
+export function compileCreativeManifest(specs: CreativeAssetSpec[]): Record<string, any> {
+  return {
+    generatedAt: new Date().toISOString(),
+    totalVariants: specs.length,
+    assets: specs.map(spec => ({
+      id: `${spec.campaign}-${spec.variantId}-${spec.aspectRatio.replace(':', 'x')}`,
+      dimensions: `${spec.width}x${spec.height}`,
+      ratio: spec.aspectRatio,
+      exportPath: `assets/creatives/${spec.campaign}/${spec.variantId}-${spec.aspectRatio.replace(':', 'x')}.webp`,
+    })),
+  };
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Text Safe-Zone Violation on Vertical 9:16 Assets
+1. **Diagnosis**: Headline copy or CTA button overlaps with platform UI overlays (TikTok sound icon, Instagram profile footer).
+2. **Recovery Protocol**:
+   - Step 1: Detect bounding box coordinates of text and CTA layers against safe-zone boundaries (top 250px, bottom 350px).
+   - Step 2: Recalculate vertical flow offset and clamp text positioning inside the 1320px central vertical window.
+   - Step 3: Re-render vertical 9:16 asset variant and re-verify bounding box clearance.
+
+### Scenario B: Creative File Size Exceeds Ad Network Limit
+1. **Diagnosis**: Exported display creative exceeds network constraint (e.g. Google Display Ad limit of 150 KB).
+2. **Recovery Protocol**:
+   - Step 1: Analyze image compression parameters and color depth.
+   - Step 2: Apply adaptive lossy WebP compression with quality step degradation (85 -> 80 -> 75).
+   - Step 3: Strip extraneous EXIF metadata and re-encode to confirm file size <= 150 KB.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Multi-aspect ratios (1:1, 9:16, 16:9, 4:5) defined with exact pixel grids and safe zones.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.