| name | nano-banana-hero |
| description | Use during Stage 9 of the website factory pipeline to generate the branded hero image (1500x700, photorealistic) via the Gemini Image API (Nano Banana 2). Constructs a niche-aware, mood-aware prompt; sends client logo (and optional people/subject photos) as multimodal reference images; produces a composite hero per the niche's composition rules. Output goes to clients/[Client Name]/Pipeline Data/hero-image/hero-final.png. Direct API call (no MCP) for reliability. |
| allowed-tools | ["Read","Write","Edit","Bash"] |
Nano Banana Hero Image Skill (Stage 9)
How this skill is customised
The factory ships niche-agnostic. The composition rules that make a hero image
unmistakably "this niche" (a contractor's branded vehicle + region-correct home; a
boutique hotel's golden-hour exterior with hosted dinner foreground; an e-commerce
brand's product still-life with brand colour backdrop) are not in this file. They
live in the niche playbook:
templates/{active-niche-slug}/niche-playbook/hero-composition.md
templates/{active-niche-slug}/niche-playbook/hero-mood-mapping.json
hero-composition.md is a prompt fragment that Module 2D writes from the top-of-niche
analysis it did in Stage 2D. hero-mood-mapping.json maps brand-dna.hero.mood values
to specific lighting briefs.
If either file is missing, the agent halts and points the student at Module 2D.
Architecture
| Concern | Where it lives |
|---|
| Executor | tools/generate-hero.py (direct Gemini Image API, no MCP) |
| API key | GEMINI_API_KEY in .env (gitignored) |
| Model | GEMINI_MODEL env var, default gemini-2.5-flash-image-preview |
| Niche prompt template (complete) | templates/{active-niche}/niche-playbook/hero-composition.md |
| Niche mood map | templates/{active-niche}/niche-playbook/hero-mood-mapping.json |
| Output | clients/[Client Name]/Pipeline Data/hero-image/hero-final.png |
| Audit copy of prompt | clients/[Client Name]/Pipeline Data/hero-image/hero-prompt.md |
| Run metadata | clients/[Client Name]/Pipeline Data/hero-image/hero-metadata.json |
Inputs
Required:
clients/[Client Name]/Pipeline Data/brand/brand-dna.json (palette, region, hero.mood)clients/[Client Name]/[Client Name] Assets/logo/logo.{png,svg,jpg} (HALT if missing)templates/{active-niche}/niche-playbook/hero-composition.mdtemplates/{active-niche}/niche-playbook/hero-mood-mapping.json
Optional (used when present, requirement varies per niche):
clients/[Client Name]/Pipeline Data/research/research.jsonclients/[Client Name]/Pipeline Data/intake/intake.json- People / subject reference photos at the path the niche playbook prescribes (e.g.
founder-photos/owner.{jpg,png} for contractor; host-photos/host.{jpg,png} for
hospitality)
Universal composition rules
These apply regardless of niche. The niche playbook may add but never override.
- Target size: 1500×700 (Gemini variance allowed: ≥ 1000×500)
- Non-zero bytes, not solid colour, validates on output
- LEFT 40% of frame stays relatively unobstructed (reserved for text overlay zone)
- Logo as multimodal reference is non-negotiable (logo must be used, never re-coloured or
re-styled in the output)
- No watermarks, no overlaid text not part of the source photography
- Photorealistic (no illustration, no painterly filter)
Niche composition rules
Loaded from niche-playbook/hero-composition.md. The niche playbook defines:
- Subject placement and scale
- Foreground/midground/background composition
- Whether people are in the frame and where
- Whether a vehicle, product, room, or scenic element is in the frame
- Mood lighting baseline for the niche
Hero mood mapping
brand-dna.hero.mood selects from the niche's mood map at
niche-playbook/hero-mood-mapping.json. Every niche playbook ships at minimum these moods
(values mapped to lighting briefs the prompt fragment inherits):
golden_hour_warmovercast_calmdramatic_duskbright_midday_cleandawn_soft_optimistic
A niche may add niche-specific moods (e.g. candlelit_intimate for hospitality;
storm_dramatic for storm-restoration contractors).
If brand-dna.hero.mood is not set, default to the niche playbook's
default_mood field.
Region defaults
The niche playbook may define region-specific defaults at
niche-playbook/hero-regions.json (house style for contractor regions, climate
descriptors for hospitality regions, etc.). The agent passes brand-dna.region to look
up the row; research.json overrides per field.
Process (what the agent does)
- Asset gate. Confirm logo exists. If missing, write
MANUAL-DROP-NEEDED.md and halt
the pipeline.
- Niche playbook gate. Confirm
niche-playbook/hero-composition.md and
hero-mood-mapping.json exist. Halt with a Module-2D pointer if missing.
- Subject gate (soft). Detect people/subject reference photos per the niche
playbook's spec. If required by the playbook and missing, soft-halt (write
SUBJECT-PHOTO-NEEDED.md; pipeline may continue with a subject-less composition).
- Prompt assembly. Substitute per-client tokens into the niche's complete prompt
template at
templates/{active-niche}/niche-playbook/hero-composition.md:
company name, city/state, region defaults, brand-dna.palette, services, mood
lighting brief (looked up from niche mood map), and any reference-photo blocks.
The template is a complete scaffold Module 2D wrote per-niche; there is no
separate universal scaffold to layer on top.
- API call. Run
python3 tools/generate-hero.py --client "[Client Name]". The script
handles multimodal upload, retries x3 with exponential backoff on API errors, validates
output dimensions and sanity (not solid colour, non-zero bytes).
- Output. Save image to
hero-final.png, prompt to hero-prompt.md, metadata to
hero-metadata.json.
- Pipeline state. Update
pipeline-state.json with stage_9: complete.
Failure handling
| Failure | Response |
|---|
| Logo missing | Write MANUAL-DROP-NEEDED.md, halt pipeline |
| Niche playbook files missing | Halt; point user at Module 2D |
| Gemini API error | Retry x3 with exponential backoff (2s, 4s, 8s) |
| All retries exhausted | Write REGENERATION-NEEDED.md with error and filled prompt; pipeline can continue with placeholder |
| Validation fails (corrupt, solid colour, undersized) | Retry generation x3 with same prompt |
| Logo unrecognisable in output | Note in metadata, do not halt (manual review during Stage 10.4a design fidelity QA) |
What this skill never does
- Generates without the client logo as a multimodal reference (logo is non-negotiable)
- Uses generic stock-photo aesthetics
- Places subjects or branded objects in the LEFT 40% of frame (text overlay zone)
- Generates multiple candidates (one image, retry on failure)
- Modifies the logo (no recolouring, no simplification)
CLI usage (manual runs / debugging)
python3 tools/generate-hero.py --client "[Client Name]"
python3 tools/generate-hero.py --client "[Client Name]" --no-owner
Pass gate
hero-final.png exists, dimensions ≥ 1000×500, non-zero bytes, not solid colourhero-prompt.md saved for audithero-metadata.json records: logo used, subject used (or null), mood, region, model, byte size- OR
REGENERATION-NEEDED.md written and noted in pipeline-state
