@stella-studio/ck 1.0.0

package/.claude/skills/ai-artist/references/nano-banana.md

@@ -0,0 +1,136 @@
+# Nano Banana Pro (Gemini Image)
+
+## Models
+
+| Model ID | Type | Best For |
+|----------|------|----------|
+| `gemini-2.5-flash-image` | Flash | Speed, high-volume |
+| `gemini-3-pro-image-preview` | Pro | Text rendering, complex prompts |
+
+## Core Principle
+
+**Narrative paragraphs > keyword lists** (32K context). Write like briefing a photographer.
+
+## Parameters
+
+```python
+responseModalities=['TEXT', 'IMAGE']
+aspect_ratio="16:9"  # 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
+image_size="2K"      # 1K, 2K, 4K - MUST be uppercase K
+```
+
+## Prompt Templates
+
+**Photorealistic**: `A [subject] in [location], [lens] lens. [Lighting] creates [mood]. [Details]. [Camera angle]. Professional photography, natural lighting.`
+
+**Illustration**: `[Art style] illustration of [subject]. [Color palette]. [Line style]. [Background]. [Mood].`
+
+**Text in Image**: `Image with text "[EXACT]" in [font]. Font: [style]. Color: [hex/#FF5733]. Position: [top/center/bottom]. Background: [desc]. Context: [poster/sign].`
+
+**Product**: `[Product] on [surface]. Materials: [finish]. Lighting: [setup]. Camera: [angle]. Background: [type]. Style: [commercial/lifestyle].`
+
+**Infographic**: `Premium liquid glass Bento grid infographic with 8 modules. Product: [item]. Language: [lang]. Hero card: 28-30%. Background: [ethereal/macro/pattern/context].`
+
+## Prompt Collection / Prompt Search
+
+Read `references/awesome-prompts.csv` directly or search for relevant prompts using `python3 ../scripts/search.py "<query>"`.
+
+## JSON Structured Prompts
+
+For complex scenes, use JSON structure:
+
+```json
+{
+  "meta_data": { "prompt_version": "2.0", "use_case": "..." },
+  "subject_layer": {
+    "anatomy": { "demographics": {}, "face_detail": {}, "hair": {} },
+    "attire_layer": { "garment_main": {}, "accessories": {} },
+    "pose_dynamics": { "posture": "", "limb_placement": {} }
+  },
+  "environment_layer": { "setting_type": "", "spatial_layout": {} },
+  "composition_and_tech": {
+    "framing": { "type": "", "angle": "" },
+    "lighting": { "source": "", "direction": "" },
+    "aesthetic_style": { "visual_core": "", "vibe": "" }
+  }
+}
+```
+
+## Techniques
+
+| Technique | Example |
+|-----------|---------|
+| Emphasis | `ALL CAPS` for critical requirements |
+| Precision colors | `#9F2B68` instead of "dark magenta" |
+| Negative constraints | `NEVER include text/watermarks. DO NOT add labels.` |
+| Realism trigger | `Natural lighting, DOF. Captured with Canon EOS 90D DSLR.` |
+| Structured edits | `Make ALL edits: - [1] - [2] - [3]` |
+| Complex logic | `Kittens MUST have heterochromatic eyes matching fur colors` |
+| Identity lock | `Use reference as EXACT facial reference. STRICT identity lock.` |
+
+## Advanced Features
+
+**Multi-Image Input** (up to 14): 6 object + 5 human refs. Tip: collage refs into single image.
+
+**Search Grounding**: `tools=[{"google_search": {}}]` — real-time data (weather, charts, events).
+
+**Thinking Mode** (Pro only): `part.thought` in response for complex reasoning.
+
+## Popular Use Case Templates
+
+### Quote Card
+```
+A wide quote card with {background} background, {font_style} font.
+Quote: "{quote_text}" — {author}
+Large subtle quotation mark before text. Portrait on left, text right.
+Text: 2/3 width, portrait: 1/3 width. Gradient transition on portrait.
+```
+
+### Infographic (Bento Grid)
+```
+Premium liquid glass Bento grid product infographic with 8 modules.
+Product: [name]. Language: [lang].
+1) Hero card (28-30%): Product photo/3D glass
+2) Core Benefits: 4 benefits + icons
+3) How to Use: 4 methods + icons
+4) Key Metrics: 5 data points
+5) Who It's For: 4 recommended + 3 caution groups
+6) Important Notes: 4 precautions
+7) Quick Reference: Specs/certifications
+8) Did You Know: 3 facts
+Background: Apple liquid glass cards (85-90% transparent).
+```
+
+### Mirror Selfie
+```
+Scene: Mirror selfie in [room type], [color] tone.
+Subject: [demographics], [body type], [hairstyle].
+Pose: [stance], holding smartphone.
+Clothing: [detailed outfit description].
+Environment: [room details, furnishings, lighting].
+Camera: Smartphone rear camera via mirror, [focal length]mm.
+Negative: [artifacts to avoid].
+```
+
+### Style Transformation
+```
+A Japanese Edo-period Ukiyo-e woodblock print reimagining [modern scene].
+Characters: Edo-era kimono but modern actions.
+Tech transformation: Smartphones → glowing scrolls, trains → wooden carriages.
+Composition: Flattened perspective, bold ink outlines.
+Texture: Wood grain, paper fibers, pigment bleeding.
+Colors: Prussian blue, vermilion red, muted ochre.
+Include vertical Japanese calligraphy and red artist seal.
+```
+
+## Workflow
+
+1. Narrative description → 2. Photography terms → 3. ALL CAPS emphasis → 4. Multi-turn refine → 5. Negative constraints → 6. Set ratio/resolution
+
+## Avoid
+
+- Keyword spam ("4k, trending, masterpiece")
+- Vague text ("add some text" → specify exact text, font, position)
+- Lowercase resolution ("4k" rejected, use "4K")
+- Over-smoothed skin requests (leads to plastic look)
+- Generic prompts without specific details

package/.claude/skills/ai-artist/references/reasoning-techniques.md

@@ -0,0 +1,201 @@
+# Reasoning Techniques Deep Dive
+
+## Chain of Thought (CoT) Variants
+
+### Zero-Shot CoT
+```
+[Task description]
+
+Think step by step before answering.
+```
+**Use when**: Quick reasoning, no examples available
+**Effectiveness**: +40-60% on reasoning tasks
+
+### Few-Shot CoT
+```
+Example 1:
+Q: [Question]
+A: Let me think through this...
+   Step 1: [Reasoning]
+   Step 2: [Reasoning]
+   Therefore: [Answer]
+
+Example 2:
+Q: [Question]
+A: Breaking this down...
+   First: [Reasoning]
+   Next: [Reasoning]
+   So: [Answer]
+
+Now solve:
+Q: [Your question]
+```
+**Use when**: Complex reasoning, pattern demonstration needed
+**Effectiveness**: +50-80% on complex tasks
+
+### Auto-CoT
+```
+Let me approach this systematically:
+1. Identify the key elements
+2. Analyze relationships
+3. Apply relevant principles
+4. Draw conclusions
+5. Verify my reasoning
+```
+**Use when**: General problem-solving, exploratory reasoning
+
+## Tree of Thoughts (ToT)
+
+### Implementation Pattern
+```
+Problem: [Complex problem]
+
+Generate 3 different approaches:
+
+Approach A:
+- Method: [Description]
+- Reasoning: [Why this might work]
+- Potential issues: [Risks]
+- Confidence: [1-10]
+
+Approach B:
+- Method: [Description]
+- Reasoning: [Why this might work]
+- Potential issues: [Risks]
+- Confidence: [1-10]
+
+Approach C:
+- Method: [Description]
+- Reasoning: [Why this might work]
+- Potential issues: [Risks]
+- Confidence: [1-10]
+
+Evaluate branches:
+- Which has highest success probability?
+- Which has fewest risks?
+- Which is most feasible?
+
+Selected approach: [Best option with justification]
+Execution: [Step-by-step implementation]
+```
+
+**Use when**: Strategic decisions, multiple valid paths, high-stakes problems
+
+## Self-Consistency
+
+### Process
+1. Generate 5 responses at temp=0.7
+2. Extract final answers from each
+3. Take majority vote
+4. Report confidence = agreement %
+
+### Implementation
+```
+Run this prompt 5 times (or use n=5 parameter):
+[Your reasoning task]
+Think step by step and provide final answer.
+
+Aggregate: If 4/5 agree = high confidence
+          If 3/5 agree = medium confidence
+          If split = low confidence, needs review
+```
+
+**Use when**: Math, logic, factual questions with verifiable answers
+
+## ReAct (Reasoning + Acting)
+
+### Full Pattern
+```
+Task: [Goal to achieve]
+
+Thought 1: I need to understand the current situation.
+Action 1: [Observation or tool use]
+Observation 1: [Result from action]
+
+Thought 2: Based on this, I should [next logical step].
+Action 2: [Next action]
+Observation 2: [Result]
+
+Thought 3: Now I can see that [insight].
+Action 3: [Verification or next step]
+Observation 3: [Result]
+
+Thought 4: I have enough information to conclude.
+Final Answer: [Conclusion with reasoning]
+```
+
+**Use when**: Tool-augmented reasoning, research tasks, multi-step analysis
+
+## Least-to-Most Prompting
+
+### Structure
+```
+Complex problem: [Full problem statement]
+
+Step 1: Decomposition
+Break this into simpler subproblems, ordered from easiest to hardest:
+1. [Simplest subproblem]
+2. [Next subproblem, may depend on 1]
+3. [Harder subproblem, may depend on 1,2]
+4. [Final subproblem requiring all above]
+
+Step 2: Sequential Solution
+Subproblem 1: [Solution]
+Using result from 1, Subproblem 2: [Solution]
+Using results from 1,2, Subproblem 3: [Solution]
+Using all results, Subproblem 4: [Solution]
+
+Final integrated answer: [Complete solution]
+```
+
+**Use when**: Mathematical word problems, multi-step procedures, compositional tasks
+
+## Decomposed Prompting (DECOMP)
+
+### Pattern
+```
+Task: [Complex task]
+
+Required capabilities:
+- [Capability 1]: Use [specialized prompt/tool]
+- [Capability 2]: Use [specialized prompt/tool]
+- [Capability 3]: Use [specialized prompt/tool]
+
+Orchestration:
+1. Call [Capability 1] with [input] → get [output1]
+2. Call [Capability 2] with [output1] → get [output2]
+3. Call [Capability 3] with [output2] → get [final output]
+
+Integrate results: [Final response]
+```
+
+**Use when**: Tasks requiring diverse expertise, specialized sub-tasks
+
+## Constitutional AI Reasoning
+
+### Self-Critique Pattern
+```
+Initial response: [Generated content]
+
+Critique against principles:
+- Is it helpful? [Yes/No + reasoning]
+- Is it harmless? [Yes/No + reasoning]
+- Is it honest? [Yes/No + reasoning]
+
+If any No:
+Revised response that addresses [specific issues]:
+[Improved content]
+```
+
+## Choosing the Right Technique
+
+| Task Type | Best Technique |
+|-----------|---------------|
+| Simple reasoning | Zero-shot CoT |
+| Complex multi-step | Few-shot CoT |
+| Strategic decisions | Tree of Thoughts |
+| Factual verification | Self-Consistency |
+| Tool-using tasks | ReAct |
+| Word problems | Least-to-Most |
+| Specialized sub-tasks | DECOMP |
+| Safety-critical | Constitutional AI |

package/.claude/skills/ai-artist/references/validation-workflow.md

@@ -0,0 +1,117 @@
+# AI Artist Validation Workflow
+
+Agent instructions for mandatory validation interview before image generation.
+
+## Step 1: Parse Arguments
+
+Extract from user input:
+- **concept**: The subject/description (required)
+- **--mode**: search (default), creative, or wild
+- **--skip**: If present, use defaults and skip to Step 4
+
+**Defaults for --skip mode:** Style=Photorealistic, Mood=Professional, Colors=Auto, Aspect=16:9
+
+## Step 2: Interview User
+
+Use `AskUserQuestion` with these 4 questions in a single call:
+
+```json
+{"questions": [
+  {"question": "Visual style?", "header": "Style", "multiSelect": false, "options": [
+    {"label": "Photorealistic (Recommended)", "description": "Professional photography, 8K"},
+    {"label": "Cinematic", "description": "Film-like, dramatic lighting"},
+    {"label": "Illustration", "description": "Digital art, stylized"},
+    {"label": "Minimalist", "description": "Clean, white space"}
+  ]},
+  {"question": "Mood?", "header": "Mood", "multiSelect": false, "options": [
+    {"label": "Professional", "description": "Corporate, trustworthy"},
+    {"label": "Energetic", "description": "Dynamic, bold"},
+    {"label": "Calm", "description": "Peaceful, serene"},
+    {"label": "Dramatic", "description": "High contrast, intense"}
+  ]},
+  {"question": "Colors?", "header": "Colors", "multiSelect": false, "options": [
+    {"label": "Auto-select (Recommended)", "description": "AI chooses"},
+    {"label": "Warm tones", "description": "Oranges, reds"},
+    {"label": "Cool tones", "description": "Blues, greens"},
+    {"label": "High contrast", "description": "Blacks, neons"}
+  ]},
+  {"question": "Aspect ratio?", "header": "Ratio", "multiSelect": false, "options": [
+    {"label": "16:9 (Recommended)", "description": "Widescreen"},
+    {"label": "1:1", "description": "Square"},
+    {"label": "9:16", "description": "Vertical"},
+    {"label": "4:3", "description": "Standard"}
+  ]}
+]}
+```
+
+**Dynamic questions** (ask separately if concept matches):
+- "banner/poster/thumbnail" → Ask about text space
+- "product/showcase" → Ask about background preference
+
+## Step 3: Build Prompt
+
+Map answers to keywords:
+
+| Style | Keywords |
+|-------|----------|
+| Photorealistic | photorealistic, professional photography, 8K, RAW |
+| Cinematic | cinematic, film still, anamorphic, dramatic lighting |
+| Illustration | digital illustration, artistic, stylized |
+| Minimalist | minimalist, clean design, white space |
+
+| Mood | Keywords |
+|------|----------|
+| Professional | professional, clean, corporate, polished |
+| Energetic | dynamic, bold, vibrant, high energy |
+| Calm | serene, peaceful, soft, tranquil |
+| Dramatic | dramatic, high contrast, intense, moody |
+
+| Colors | Keywords |
+|--------|----------|
+| Auto-select | (none) |
+| Warm tones | warm palette, golden tones, amber |
+| Cool tones | cool palette, blue tones, teal |
+| High contrast | high contrast, bold blacks, neon |
+
+**Template:** `[concept], [style], [mood], [colors]. Professional quality. NEVER add watermarks.`
+
+## Step 4: Confirm & Generate
+
+Show preview, then ask confirmation:
+
+```json
+{"questions": [{"question": "Generate?", "header": "Confirm", "multiSelect": false, "options": [
+  {"label": "Yes, generate (Recommended)", "description": "Proceed"},
+  {"label": "Edit prompt", "description": "Modify first"},
+  {"label": "Start over", "description": "Re-answer"}
+]}]}
+```
+
+**If "Edit prompt":** Ask user for edited text, use that instead.
+**If "Start over":** Return to Step 2.
+
+Run generation:
+```bash
+cd .claude/skills/ai-artist && .venv/bin/python3 scripts/generate.py "[concept]" \
+  -o ./generated-$(date +%Y%m%d-%H%M%S).png \
+  --mode [mode] \
+  -ar [ratio] \
+  -v
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| API key missing | Tell user to set GEMINI_API_KEY |
+| Model error | Suggest `--model flash` |
+| No concept | Ask user for concept |
+
+## Output
+
+```
+[OK] Image generated: [path]
+    Style: [style] | Mood: [mood] | Aspect: [ratio]
+
+Tip: Use --skip to bypass interview next time.
+```

package/.claude/skills/ai-artist/scripts/core.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+AI Artist Core - BM25 search engine for prompt engineering resources
+"""
+
+import csv
+import re
+from pathlib import Path
+from math import log
+from collections import defaultdict
+
+# ============ CONFIGURATION ============
+DATA_DIR = Path(__file__).parent.parent / "data"
+MAX_RESULTS = 3
+
+CSV_CONFIG = {
+    "use-case": {
+        "file": "use-cases.csv",
+        "search_cols": ["Use Case", "Category", "Keywords", "Best Platforms"],
+        "output_cols": ["Use Case", "Category", "Keywords", "Prompt Template", "Key Elements", "Best Platforms", "Aspect Ratios", "Tips", "Example"]
+    },
+    "style": {
+        "file": "styles.csv",
+        "search_cols": ["Style Name", "Category", "Keywords", "Description", "Best For"],
+        "output_cols": ["Style Name", "Category", "Description", "Key Characteristics", "Color Palette", "Best For", "Platforms", "Prompt Keywords"]
+    },
+    "platform": {
+        "file": "platforms.csv",
+        "search_cols": ["Platform", "Type", "Keywords", "Strengths"],
+        "output_cols": ["Platform", "Type", "Prompt Style", "Key Parameters", "Strengths", "Limitations", "Aspect Ratios", "Best Practices"]
+    },
+    "technique": {
+        "file": "techniques.csv",
+        "search_cols": ["Technique", "Category", "Keywords", "Description", "When to Use"],
+        "output_cols": ["Technique", "Category", "Description", "When to Use", "Syntax Example", "Platforms", "Tips"]
+    },
+    "lighting": {
+        "file": "lighting.csv",
+        "search_cols": ["Lighting Type", "Category", "Keywords", "Description", "Mood", "Best For"],
+        "output_cols": ["Lighting Type", "Category", "Description", "Mood", "Best For", "Prompt Keywords", "Technical Notes"]
+    },
+    "template": {
+        "file": "nano-banana-templates.csv",
+        "search_cols": ["Category", "Template Name", "Keywords"],
+        "output_cols": ["Category", "Template Name", "Keywords", "Prompt Template", "Aspect Ratio", "Tips"]
+    },
+    "awesome": {
+        "file": "awesome-prompts.csv",
+        "search_cols": ["title", "description", "prompt"],
+        "output_cols": ["id", "title", "category", "description", "prompt", "author", "source"]
+    }
+}
+
+
+# ============ BM25 IMPLEMENTATION ============
+class BM25:
+    """BM25 ranking algorithm for text search"""
+
+    def __init__(self, k1=1.5, b=0.75):
+        self.k1 = k1
+        self.b = b
+        self.corpus = []
+        self.doc_lengths = []
+        self.avgdl = 0
+        self.idf = {}
+        self.doc_freqs = defaultdict(int)
+        self.N = 0
+
+    def tokenize(self, text):
+        """Lowercase, split, remove punctuation, filter short words"""
+        text = re.sub(r'[^\w\s]', ' ', str(text).lower())
+        return [w for w in text.split() if len(w) > 2]
+
+    def fit(self, documents):
+        """Build BM25 index from documents"""
+        self.corpus = [self.tokenize(doc) for doc in documents]
+        self.N = len(self.corpus)
+        if self.N == 0:
+            return
+        self.doc_lengths = [len(doc) for doc in self.corpus]
+        self.avgdl = sum(self.doc_lengths) / self.N
+
+        for doc in self.corpus:
+            seen = set()
+            for word in doc:
+                if word not in seen:
+                    self.doc_freqs[word] += 1
+                    seen.add(word)
+
+        for word, freq in self.doc_freqs.items():
+            self.idf[word] = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+    def score(self, query):
+        """Score all documents against query"""
+        query_tokens = self.tokenize(query)
+        scores = []
+
+        for idx, doc in enumerate(self.corpus):
+            score = 0
+            doc_len = self.doc_lengths[idx]
+            term_freqs = defaultdict(int)
+            for word in doc:
+                term_freqs[word] += 1
+
+            for token in query_tokens:
+                if token in self.idf:
+                    tf = term_freqs[token]
+                    idf = self.idf[token]
+                    numerator = tf * (self.k1 + 1)
+                    denominator = tf + self.k1 * (1 - self.b + self.b * doc_len / self.avgdl)
+                    score += idf * numerator / denominator
+
+            scores.append((idx, score))
+
+        return sorted(scores, key=lambda x: x[1], reverse=True)
+
+
+# ============ SEARCH FUNCTIONS ============
+def _load_csv(filepath):
+    """Load CSV and return list of dicts"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        return list(csv.DictReader(f))
+
+
+def _search_csv(filepath, search_cols, output_cols, query, max_results):
+    """Core search function using BM25"""
+    if not filepath.exists():
+        return []
+
+    data = _load_csv(filepath)
+
+    # Build documents from search columns
+    documents = [" ".join(str(row.get(col, "")) for col in search_cols) for row in data]
+
+    # BM25 search
+    bm25 = BM25()
+    bm25.fit(documents)
+    ranked = bm25.score(query)
+
+    # Get top results with score > 0
+    results = []
+    for idx, score in ranked[:max_results]:
+        if score > 0:
+            row = data[idx]
+            results.append({col: row.get(col, "") for col in output_cols if col in row})
+
+    return results
+
+
+def detect_domain(query):
+    """Auto-detect the most relevant domain from query"""
+    query_lower = query.lower()
+
+    domain_keywords = {
+        "use-case": ["avatar", "profile", "thumbnail", "poster", "social", "youtube", "instagram", "marketing", "product", "e-commerce", "infographic", "comic", "game", "app", "web", "header", "banner"],
+        "style": ["style", "aesthetic", "photorealistic", "anime", "manga", "3d", "render", "illustration", "pixel", "watercolor", "oil", "cyberpunk", "vaporwave", "minimalist", "vintage", "retro"],
+        "platform": ["midjourney", "dalle", "dall-e", "stable diffusion", "flux", "nano banana", "gemini", "imagen", "ideogram", "leonardo", "firefly", "platform", "tool"],
+        "technique": ["prompt", "technique", "weight", "emphasis", "negative", "json", "structured", "iteration", "reference", "identity", "multi-panel", "search grounding"],
+        "lighting": ["lighting", "light", "shadow", "golden hour", "blue hour", "rembrandt", "butterfly", "neon", "volumetric", "softbox", "rim light", "studio"]
+    }
+
+    scores = {domain: sum(1 for kw in keywords if kw in query_lower) for domain, keywords in domain_keywords.items()}
+    best = max(scores, key=scores.get)
+    return best if scores[best] > 0 else "style"
+
+
+def search(query, domain=None, max_results=MAX_RESULTS):
+    """Main search function with auto-domain detection"""
+    if domain is None:
+        domain = detect_domain(query)
+
+    config = CSV_CONFIG.get(domain, CSV_CONFIG["style"])
+    filepath = DATA_DIR / config["file"]
+
+    if not filepath.exists():
+        return {"error": f"File not found: {filepath}", "domain": domain}
+
+    results = _search_csv(filepath, config["search_cols"], config["output_cols"], query, max_results)
+
+    return {
+        "domain": domain,
+        "query": query,
+        "file": config["file"],
+        "count": len(results),
+        "results": results
+    }
+
+
+def search_all_domains(query, max_per_domain=2):
+    """Search across all domains for comprehensive results"""
+    all_results = {}
+    for domain in CSV_CONFIG.keys():
+        result = search(query, domain, max_per_domain)
+        if result.get("count", 0) > 0:
+            all_results[domain] = result
+    return all_results