wicked-garden 12.27.0

package/skills/product/imagery/create/refs/prompt-engineering.md

@@ -0,0 +1,112 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Prompt Engineering for Image Generation
+
+Guidance on crafting effective prompts that produce high-quality, predictable image outputs.
+
+## Prompt Structure
+
+The most effective prompts follow a layered structure:
+
+```
+[Subject] + [Style/Medium] + [Lighting/Mood] + [Composition] + [Details]
+```
+
+### Layer Breakdown
+
+| Layer | Purpose | Examples |
+|-------|---------|---------|
+| **Subject** | What is in the image | "A solitary lighthouse on a cliff" |
+| **Style/Medium** | Artistic approach | "Oil painting", "Photorealistic", "Flat vector" |
+| **Lighting/Mood** | Atmosphere | "Warm golden hour", "Dramatic noir shadows" |
+| **Composition** | Framing and layout | "Centered", "Rule of thirds", "Bird's eye view" |
+| **Details** | Specifics and texture | "Weathered stone", "Matte finish", "4K resolution" |
+
+## Prompt Quality Tiers
+
+### Tier 1: Basic (Low Predictability)
+```
+"A cat sitting on a chair"
+```
+Produces generic results with high variance.
+
+### Tier 2: Descriptive (Medium Predictability)
+```
+"A tabby cat sitting on a vintage wooden chair, soft natural lighting"
+```
+Better results but still leaves many decisions to the model.
+
+### Tier 3: Precision (High Predictability)
+```
+"A tabby cat with green eyes sitting on a weathered oak rocking chair,
+soft diffused window light from the left, warm color palette with
+cream and amber tones, shallow depth of field, photorealistic style"
+```
+Produces consistent, predictable results.
+
+## Negative Prompts
+
+Use `--negative-prompt` to exclude unwanted elements:
+
+```bash
+--negative-prompt "text, watermarks, blurry, low quality, distorted, extra limbs"
+```
+
+### Common Negative Prompt Categories
+
+| Category | Terms |
+|----------|-------|
+| **Quality** | "blurry, pixelated, low resolution, jpeg artifacts" |
+| **Text** | "text, words, letters, watermarks, signatures" |
+| **Anatomy** | "extra limbs, deformed hands, extra fingers" |
+| **Style** | "cartoon, anime, sketch" (when photorealism is wanted) |
+
+## Style Keywords
+
+### Photographic Styles
+- Photorealistic, DSLR quality, bokeh, shallow depth of field
+- Studio lighting, natural lighting, golden hour, blue hour
+- Macro photography, aerial photography, portrait photography
+
+### Artistic Styles
+- Oil painting, watercolor, digital art, concept art
+- Minimalist, maximalist, abstract, surrealist
+- Flat design, isometric, low poly, pixel art
+
+### Mood Keywords
+- Ethereal, moody, dramatic, serene, vibrant
+- Dark and gritty, light and airy, warm and inviting
+- Clinical, futuristic, nostalgic, whimsical
+
+## Aspect Ratio Guidelines
+
+| Ratio | Use Case |
+|-------|----------|
+| `1:1` | Social media posts, profile images, icons |
+| `16:9` | Presentations, hero banners, video thumbnails |
+| `9:16` | Mobile stories, vertical banners |
+| `4:3` | Blog images, product shots |
+| `3:2` | Photography standard, print media |
+
+## Iteration Strategies
+
+### When results miss the mark:
+
+1. **Too generic** — Add more specific adjectives and details
+2. **Wrong style** — Be more explicit about the medium ("oil on canvas" vs "painting")
+3. **Wrong mood** — Add lighting and atmosphere keywords
+4. **Unwanted elements** — Add them to the negative prompt
+5. **Good but not great** — Lock the seed, adjust guidance scale up/down
+6. **Inconsistent** — Reduce sample count to 1, increase guidance scale
+
+### Guidance Scale Tuning
+
+| Value | Behavior |
+|-------|----------|
+| Low (1-5) | Creative, loose interpretation of prompt |
+| Medium (7-10) | Balanced adherence and creativity |
+| High (12-20) | Strict adherence, can reduce quality at extremes |
+
+Start at the default and adjust based on results. If outputs are too "safe", lower it. If they ignore your prompt, raise it.

package/skills/product/imagery/create/refs/provider-reference.md

@@ -0,0 +1,219 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Provider Reference
+
+Detailed documentation for each supported image generation provider.
+
+## Provider: cstudio (Vertex AI Creative Studio CLI)
+
+### Overview
+A CLI binary that wraps the Vertex AI Imagen API with a developer-friendly interface.
+
+### Authentication
+```bash
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_CLOUD_LOCATION="us-central1"  # default region
+```
+
+Requires an active `gcloud auth` session with appropriate IAM permissions:
+- `aiplatform.endpoints.predict` on the Imagen endpoint
+
+### Detection
+```bash
+# Check if cstudio is available
+which cstudio || echo "${CSTUDIO_PATH}/cstudio"
+```
+
+### Capabilities
+| Feature | Supported | Notes |
+|---------|-----------|-------|
+| Text-to-image | Yes | `cstudio generate image` |
+| Image-to-image | Yes | `cstudio edit image` |
+| Inpainting | Yes | `cstudio inpaint image` |
+| Upscaling | Yes | `cstudio upscale image` |
+| Analysis | Yes | `cstudio analyze image` |
+| Batch generation | Yes | `--sample-count 1-4` |
+
+### Models
+- `imagen-3.0-generate-001` — Latest generation model (default)
+- Check `cstudio models list` for available models in your project
+
+---
+
+## Provider: vertex-curl (Vertex AI via gcloud + curl)
+
+### Overview
+Direct REST API access to Vertex AI Imagen endpoints using `gcloud` for auth and `curl` for requests. No additional binary required.
+
+### Authentication
+```bash
+# Ensure gcloud is configured
+gcloud auth application-default login
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+### API Endpoint
+```
+https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/publishers/google/models/${MODEL}:predict
+```
+
+### Request Format
+```bash
+# Generate an image
+ACCESS_TOKEN=$(gcloud auth print-access-token)
+curl -X POST \
+  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  "${ENDPOINT}" \
+  -d '{
+    "instances": [{"prompt": "Your prompt here"}],
+    "parameters": {
+      "sampleCount": 1,
+      "aspectRatio": "16:9",
+      "negativePrompt": "text, watermarks"
+    }
+  }'
+```
+
+### Response Format
+The response contains base64-encoded image data:
+```json
+{
+  "predictions": [
+    {
+      "bytesBase64Encoded": "...",
+      "mimeType": "image/png"
+    }
+  ]
+}
+```
+
+Decode with: `echo "${BASE64_DATA}" | base64 -d > output.png`
+
+### Capabilities
+| Feature | Supported | Notes |
+|---------|-----------|-------|
+| Text-to-image | Yes | Standard predict endpoint |
+| Image-to-image | Yes | Include base image in request |
+| Inpainting | Yes | Include image + mask in request |
+| Upscaling | Limited | Separate endpoint if available |
+| Analysis | No | Read the image file directly instead |
+| Batch generation | Yes | `sampleCount` parameter |
+
+---
+
+## Provider: openai (OpenAI Image API)
+
+### Overview
+OpenAI's image generation and editing API. Uses `gpt-image-1` for generation and editing.
+
+### Authentication
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+### Capabilities
+| Feature | Supported | Notes |
+|---------|-----------|-------|
+| Text-to-image | Yes | `POST /v1/images/generations` (JSON) |
+| Image-to-image | Yes | `POST /v1/images/edits` (multipart) |
+| Inpainting | Yes | `POST /v1/images/edits` with mask (multipart) |
+| Upscaling | No | Not available via API |
+| Analysis | No | Read the image file directly instead |
+| Batch generation | Yes | `n` parameter (1-10) |
+
+### Models
+- `gpt-image-1` — Latest generation and editing model
+
+### Notes
+- Generation uses JSON API with `b64_json` response format
+- Edit and inpaint use multipart/form-data uploads
+- Supports `size`, `quality`, and `style` parameters for generation
+
+---
+
+## Provider: stability (Stability AI)
+
+### Overview
+Stability AI's Stable Diffusion 3.5 API for image generation and editing.
+
+### Authentication
+```bash
+export STABILITY_API_KEY="sk-..."
+```
+
+### Capabilities
+| Feature | Supported | Notes |
+|---------|-----------|-------|
+| Text-to-image | Yes | `POST /v2beta/stable-image/generate/sd3` |
+| Image-to-image | Yes | Same endpoint with `mode: image-to-image` |
+| Inpainting | Yes | `POST /v2beta/stable-image/edit/inpaint` |
+| Upscaling | Yes | Separate upscale endpoint available |
+| Analysis | No | Read the image file directly instead |
+| Negative prompts | Yes | `negative_prompt` field |
+
+### Models
+- `sd3.5-large` — Stable Diffusion 3.5 Large (default)
+
+### Notes
+- All requests use multipart/form-data
+- Image-to-image uses `strength` parameter (0.0-1.0) to control deviation
+- Returns base64-encoded image in JSON response
+
+---
+
+## Provider: replicate (Replicate API)
+
+### Overview
+Replicate's model hosting platform. Uses Flux models from Black Forest Labs for image generation and editing.
+
+### Authentication
+```bash
+export REPLICATE_API_TOKEN="r8_..."
+```
+
+### Capabilities
+| Feature | Supported | Notes |
+|---------|-----------|-------|
+| Text-to-image | Yes | Flux 1.1 Pro |
+| Image-to-image | Yes | Flux Fill Pro (data URI input) |
+| Inpainting | Yes | Flux Fill Pro with mask (data URI input) |
+| Upscaling | No | Use a separate upscale model |
+| Analysis | No | Read the image file directly instead |
+| Aspect ratio | Yes | `aspect_ratio` parameter |
+
+### Models
+- `black-forest-labs/flux-1.1-pro` — Generation (default)
+- `black-forest-labs/flux-fill-pro` — Editing and inpainting
+
+### Notes
+- Uses `Prefer: wait` header for synchronous predictions (no polling)
+- Images are passed as `data:image/png;base64,...` data URIs
+- Output is a URL that gets downloaded automatically
+- Pay-per-prediction pricing — uses existing Replicate subscription
+
+---
+
+## Provider Selection Logic
+
+```
+Priority order (first available wins):
+1. cstudio — best developer experience (CLI binary)
+2. vertex-curl — no extra binary needed (gcloud + curl)
+3. openai — OPENAI_API_KEY set
+4. stability — STABILITY_API_KEY set
+5. replicate — REPLICATE_API_TOKEN set
+
+If none available:
+  → Review sub-skill still works (reads image files directly)
+  → Create and alter sub-skills are unavailable
+```
+
+## Adding New Providers
+
+To add a new provider, implement the `BaseProvider` class in `scripts/provider.py`:
+1. Subclass `BaseProvider` with `detect()`, `generate()`, `edit()`, `inpaint()`
+2. Register in the `PROVIDERS` dict and `PRIORITY_ORDER` list
+3. Update this reference document

package/skills/product/imagery/review/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: review
+description: |
+  Multi-dimensional visual analysis and quality review of images.
+  No external provider required — reads image files directly.
+
+  Use when: reviewing an image for visual quality, brand-guideline adherence,
+  or accessibility before production use.
+portability: portable
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Image Review & Analysis
+
+Visual analysis and quality review of images. No external provider or CLI tool required — just read the image file directly.
+
+## When To Use This Skill
+
+- Analyzing what an image contains (subjects, scene, context)
+- Extracting technical design details from mockups or diagrams
+- Evaluating style, color palette, mood, and lighting
+- Reviewing layout composition and visual hierarchy
+- Running quality gates before delivery (brand, a11y, production, sensitivity)
+
+## Multi-Dimensional Analysis Framework
+
+Four analysis lenses, each with a dedicated reference:
+
+| Lens | Purpose | Reference |
+|------|---------|-----------|
+| **General** | Subject, scene, context summary | [refs/analysis-lenses.md](refs/analysis-lenses.md) |
+| **Technical** | Components, hierarchy, interactivity | [refs/analysis-lenses.md](refs/analysis-lenses.md) |
+| **Style** | Palette, mood, lighting, texture | [refs/analysis-lenses.md](refs/analysis-lenses.md) |
+| **Layout** | Focal points, composition, visual weight | [refs/analysis-lenses.md](refs/analysis-lenses.md) |
+
+### Quick Analysis
+
+For most tasks, start with General analysis. Add Technical for UI mockups, Style for creative assets, or Layout for marketing materials.
+
+```
+1. Read the image file
+2. Apply the relevant analysis lens(es)
+3. Produce a structured report
+```
+
+## Quality Gates
+
+Four review gates ensure assets are "Business Ready" before delivery:
+
+| Gate | Purpose | Reference |
+|------|---------|-----------|
+| **Brand Compliance** | Logo, palette, typography, tone alignment | [refs/quality-gates.md](refs/quality-gates.md) |
+| **Accessibility** | Contrast ratios, color-blind safety, readability | [refs/quality-gates.md](refs/quality-gates.md) |
+| **Production Readiness** | Artifacts, resolution, format, cleanliness | [refs/quality-gates.md](refs/quality-gates.md) |
+| **Sensitivity** | Cultural appropriateness, inclusivity, bias | [refs/quality-gates.md](refs/quality-gates.md) |
+
+### Gate Selection
+
+Not every asset needs all four gates. Use this guide:
+
+- **Internal draft**: Production Readiness only
+- **External marketing**: All four gates
+- **UI component**: Brand + Accessibility + Production
+- **Social media**: Brand + Sensitivity + Production
+
+## Workflow: Analyze, Assess, Report
+
+```
+Step 1: ANALYZE — Read the image, apply relevant lenses
+Step 2: ASSESS  — Run applicable quality gates
+Step 3: REPORT  — Structured findings with pass/fail per gate
+```
+
+### Report Format
+
+```markdown
+## Image Review: {filename}
+
+### Analysis
+- **Subject:** ...
+- **Style:** ...
+- **Composition:** ...
+
+### Quality Gates
+| Gate | Status | Notes |
+|------|--------|-------|
+| Brand | PASS/FAIL | ... |
+| a11y  | PASS/FAIL | ... |
+| Production | PASS/FAIL | ... |
+| Sensitivity | PASS/FAIL | ... |
+
+### Recommendations
+- ...
+```
+
+## Integration With Other Sub-Skills
+
+- After **create** or **alter** generates an image, use **review** to validate
+- Review findings feed back into the Analyze-Execute-Review-Refine loop
+- Quality gate failures should include actionable fix suggestions for the next iteration

package/skills/product/imagery/review/refs/analysis-lenses.md

@@ -0,0 +1,136 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Visual Analysis Lenses
+
+Four complementary lenses for comprehensive image analysis. Apply one or more depending on the task.
+
+---
+
+## Lens 1: General Description
+
+Provides a high-level, human-readable summary of what is in the image.
+
+### Objectives
+- Provide a concise summary of the subject matter
+- Identify the primary actors or objects in the scene
+- Summarize the setting and context
+
+### Extraction Workflow
+1. **Subject Identification:** "What is this an image of?"
+2. **Contextual Summary:** "Where and when is this taking place?"
+3. **Action/State:** "What is happening or what is the state of the objects?"
+
+### Quality Criteria
+- Is the summary accurate but concise?
+- Does it avoid overly technical jargon unless requested?
+- Is it sufficient for a non-technical stakeholder to understand the content?
+
+### Example Output
+```markdown
+**Subject:** Product mockup of a mobile banking app on an iPhone 15
+**Setting:** Neutral studio background, angled at ~30° to show depth
+**State:** Login screen displayed with biometric prompt active
+```
+
+---
+
+## Lens 2: Technical Design
+
+Extracts structured technical and architectural details from UI mockups, system diagrams, or technical sketches.
+
+### Objectives
+- Identify functional components (buttons, inputs, containers)
+- Map spatial relationships and alignment
+- Detect technical constraints or intended interactivity
+
+### Extraction Workflow
+1. **Component Inventory:** List all distinct UI/UX elements or diagram nodes
+2. **Hierarchy Mapping:** Identify parent-child relationships (e.g., "The 'Submit' button is nested within the 'Auth' card")
+3. **Spacing & Grid:** Determine if a specific grid system (e.g., 8px grid) or layout engine (Flexbox/Grid) is implied
+
+### Quality Criteria
+- Is the component list exhaustive?
+- Are the spatial relationships accurately described for a developer to implement?
+- Are interactive states (hover, active, disabled) accounted for?
+
+### Decision Tree
+```
+Is it a UI mockup? → Full component inventory + hierarchy + grid analysis
+Is it a system diagram? → Node inventory + connection mapping + data flow
+Is it a technical sketch? → Element identification + annotations + constraints
+```
+
+---
+
+## Lens 3: Style & Aesthetics
+
+Focuses on the "look and feel" — artistic style, color theory, lighting, and mood.
+
+### Objectives
+- Define the artistic movement or medium (e.g., Minimalist, Cyberpunk, Watercolor)
+- Extract the color palette (primary, secondary, accent colors)
+- Analyze lighting direction, intensity, and shadows
+
+### Extraction Workflow
+1. **Mood Identification:** Use keywords to describe the atmosphere (e.g., "clinical," "ethereal," "gritty")
+2. **Palette Extraction:** Identify hex codes or descriptive color names used across the asset
+3. **Texture & Finish:** Note if the asset is matte, glossy, grainy, or has specific brushstrokes
+
+### Quality Criteria
+- Does the description capture the *feeling* of the asset?
+- Is the palette specific enough to be used in a CSS theme?
+- Are the lighting and shadows described in a way that informs generation?
+
+### Palette Output Format
+```markdown
+| Role | Color | Hex | Usage |
+|------|-------|-----|-------|
+| Primary | Deep Navy | #1a2744 | Background, headers |
+| Secondary | Warm Cream | #f5f0e8 | Card backgrounds |
+| Accent | Electric Blue | #3d8bfd | CTAs, links |
+| Danger | Coral Red | #e8534a | Error states |
+```
+
+---
+
+## Lens 4: Layout & Composition
+
+Analyzes the arrangement of elements within a frame — visual balance, focal points, and compositional guides.
+
+### Objectives
+- Identify the primary focal point
+- Map the "Z-pattern" or "F-pattern" for eye movement
+- Analyze visual weight and balance (Symmetrical vs. Asymmetrical)
+
+### Extraction Workflow
+1. **Focal Point Detection:** What is the first thing the viewer sees?
+2. **Compositional Guides:** Identify the use of leading lines, framing, or the rule of thirds
+3. **Negative Space Analysis:** How is "white space" used to separate or emphasize elements?
+
+### Quality Criteria
+- Is the focal point correctly identified?
+- Does the analysis explain *why* the layout feels balanced (or intentionally unbalanced)?
+- Is the use of negative space quantified?
+
+### Composition Checklist
+- [ ] Focal point identified and justified
+- [ ] Eye flow pattern mapped (Z, F, circular, diagonal)
+- [ ] Rule of thirds alignment checked
+- [ ] Visual weight distribution assessed
+- [ ] Leading lines identified (if present)
+- [ ] Negative space usage evaluated
+- [ ] Hierarchy of information confirmed (primary → secondary → tertiary)
+
+---
+
+## Combining Lenses
+
+| Task Type | Recommended Lenses |
+|-----------|-------------------|
+| "What is this image?" | General only |
+| UI mockup review | General + Technical + Layout |
+| Creative asset evaluation | General + Style + Layout |
+| Marketing material review | All four lenses |
+| Reference image analysis | General + Style |