photorealistic-renderer

name	photorealistic-renderer
description	Generates a detailed photorealistic image-generation prompt driven entirely by the locked structural model. Works for any garden structure (gazebo, pergola, arbour, shed, fence, trellis, etc.). Produces a single paste-ready file with geometry locks, structural description, camera direction, and exclusions tailored to whatever was designed. Trigger with "render the structure", "create a photorealistic image", "generate a render prompt", "visualize the design", or "show me what this will look like".
allowed-tools	Read, Write, Bash

Photorealistic Render Boundary

Photorealistic PNG/JPG renders are presentation artifacts only.

This skill may generate or update:

outputs/render-prompt.txt
outputs/*visualization*.png
outputs/*render*.png

This skill must NOT claim the design package is complete, and must NOT claim that a PNG validates post count, beam count, rafter count, brace count, span, height, pitch, miter angles, cut lengths, or structural safety.

Every render output must be accompanied by:

Visual concept only — construction geometry is governed by validated JSON/SVG artifacts.

If a render appears to conflict with deterministic geometry, the render is subordinate to:

context/staging/structure.json
outputs/*.svg

After generating a render, hand control back to design-orchestrator to confirm deterministic artifacts and quality dashboard status.

• context/staging/structure.json (must be locked: _locked: true; includes members, geometry, and intent/meta sections)

Outputs

• outputs/render-prompt.txt — single self-contained file: all geometry locks, structural description, camera direction, and exclusions. Paste the whole thing verbatim into ChatGPT or any image model.
• outputs/photorealistic-render.png — generated image (if the user pastes and generates)
• outputs/RENDER_FAILED.md — written if the skill cannot complete; prompt file still saved

---

Phase 1 — Read Locked Model

Read context/staging/structure.json. If _locked is not true, halt with:

ERROR: structure.json is not locked. Run structural-engine first.

Extract the fields that describe this specific structure — the exact fields vary by structure type:

• structureType → what kind of structure (gazebo, pergola, arbour, shed, screen, trellis…)
• planShape → geometry (hexagonal, rectangular, square, L-shaped, octagonal…)
• members.posts.dimensions, members.posts.quantity
• members.beams.dimensions (if present)
• members.rafters.dimensions, members.rafters.quantity (if present)
• members.bracing.* (if present — type, angle, quantity)
• members.roofType → open rafter, solid, pergola-style, lean-to, flat, no roof…
• roofStructure.pitch (if present)
• materials.primary → species and finish
• joinery.type → mortise-and-tenon, screwed, bolted, notched…
• Any unique members (king post hub, ridge beam, purlins, lattice panels, gates…)

Also read context/staging/structure.json (geometry section):

• total_height_ft, post_cut_ft, span_ft, diameter_ft — whatever dimensions are present

Also read context/staging/structure.json (intent/meta section, if present):

• site.location, site.setting, site.surroundings → used to set the scene realistically

---

Phase 2 — Compose and Write Prompt

Write outputs/render-prompt.txt using the CAD-SPEC format — structured sections with a title, explicit geometry locks, per-member subsections, and a final Exclude: block. All values are derived from structure.json; nothing is hardcoded.

Format overview

[SHAPE] TIMBER FRAME — CAD-SPEC PROMPT (MAX ENFORCEMENT)

ABSOLUTE GEOMETRY DEFINITION (TOP PRIORITY — DO NOT VIOLATE):
[geometry constraints]

PLAN GEOMETRY (EXPLICIT CONSTRUCTION LOGIC)
[dimensions and spacing]

STRUCTURAL FRAME
[one subsection per member type that exists in the model]

MATERIAL + FINISH
[species, finish, character]

SCENE + ENVIRONMENT
[site, planting, lighting]

CAMERA + VISUAL VERIFICATION (CRITICAL)
[angle, lens, counting test]

ANTI-FAILURE CONSTRAINTS
[explicitly forbid wrong shapes and wrong counts]

FINAL VALIDATION CHECK (MANDATORY)
[list of things that must be true for the image to be correct]

Exclude: [comma-separated list]

---

Section 1 — Title

[SHAPE] TIMBER FRAME — CAD-SPEC PROMPT (MAX ENFORCEMENT)

Derive shape from structure.shape (e.g. HEXAGONAL, SQUARE, OCTAGONAL).

---

Section 2 — ABSOLUTE GEOMETRY DEFINITION

Always first. Derive every value from the model — no guessing.

• Shape definition: N sides, N vertices, N structural corner posts ONLY
• Perimeter rule: "The outer boundary consists of exactly N straight edges. The viewer must be able to visually trace the perimeter and make exactly N directional turns ([interior_angle]° each). Interior angle at every corner = [interior_angle] degrees."
• Name the failure shape explicitly: "This is NOT an [confabulation_shape] — never [wrong_N] sides, never [wrong_N] posts." For hexagon the failure shape is octagon. For square it is hexagon. Name whatever the model is most likely to confuse.
• Post count hard lock: "TOTAL POSTS = N. One post per vertex. No additional vertical supports anywhere on the perimeter or inside. No doubled posts, no closely spaced posts, no decorative posts. Posts must be evenly spaced at [360/N]° around the center."
• System parity constraint: "N posts = N beam segments = N roof edges = N hip rafters. All systems must match this count exactly." Only include systems that actually exist in the model.

Interior angles by shape: triangle=60°, square=90°, pentagon=108°, hexagon=120°, octagon=135°.

---

Section 3 — PLAN GEOMETRY

Derive from layout.* and structure.*:

• Shape name
• Span or diameter (from inscribed_radius_ft × 2, or circumscribed_radius_ft × 2)
• Post positioning logic ("Posts positioned on a perfect circumscribed circle")
• Post spacing in degrees (360 / post_count)

---

Section 4 — STRUCTURAL FRAME

One subsection per member type that exists in the model. Do not include sections for members that are absent. Use nominal lumber sizes (6x6, 4x8) — not actual dimensions (5.5×5.5). Do not include cut angles or miter values — those are carpenter specs, not visual descriptions.

Posts subsection (always present):

Posts
- [species] timber, nominal [size]
- Quantity: EXACTLY [post_count]
- Height: [cut_length_ft rounded to nearest half-foot]' to beam soffit
- Mounted on visible [footing description]
- Perfect vertical alignment

Beam Ring subsection (if beams exist):

[descriptor] Primary Beam Ring
- [beam_count] segments (one between each pair of posts)
- Material: [nominal_size] [species] timber
- Each segment connects post-to-post only
- Forms a closed [N]-sided ring — no extra segments

Roof Structure subsection (if roof exists):

Roof Structure (OPEN FRAME — NO ROOFING)
- [primary_rafter_count] exposed hip rafters ([nominal_size] [species])
- One rafter per post
- Decorative rafter tails extending past the beam ring
- Rafters converge into a central [hub description]
- Pitch: [pitch]

If jack rafters exist (secondary_rafters.enabled = true):

- Each roof bay contains exactly [count_per_side] jack rafters (shorter, [nominal_size])
- Jack rafters terminate into adjacent hip rafters — do not reach the hub
- Creates layered timber framing detail in each bay

If purlins are enabled (purlins.enabled = true AND show_purlins = true in visibility_rules):

Purlin Ring
- Continuous horizontal ring inside roof
- Follows [shape] symmetry — no added segmentation

If purlins are disabled or suppressed: omit this subsection entirely.

Knee Bracing subsection (if bracing enabled):

Knee Bracing
- [total_brace_count] total diagonal knee braces
- [count_per_post] per post
- Material: [nominal_size] [species]
- Curved or chamfered profile, ~[angle_deg]° angle
- Symmetrical and evenly distributed

Joinery subsection (always):

Joinery
- Traditional mortise-and-tenon
- Visible joinery / connector detailing at post-to-beam and brace intersections
- No modern metal hardware visible anywhere

---

Section 5 — MATERIAL + FINISH

Derive from materials.primary, intent.finish (if present), or project context:

Wood: warm [species] timber appearance
Finish: [finish description]
Visible grain, tonal variation, subtle tool marks
Realistic, professional-grade timber frame presentation

---

Section 6 — SCENE + ENVIRONMENT

Derive from intent.site, intent.jurisdiction, and project context:

Photorealistic setting in a [location] garden/patio:
- [hardscape description]
- [planting palette]
- [lighting conditions]
- [atmosphere]

---

Section 7 — CAMERA + VISUAL VERIFICATION

For symmetrical structures use a slightly elevated 3/4 corner view at 6–7 ft — this camera height is critical for making all posts countable without foreshortening. For linear structures use a 3/4 angled view along the length.

CAMERA + VISUAL VERIFICATION (CRITICAL)
- Perspective: slightly elevated 3/4 view (camera height ~6–7 ft)
- Lens: 35mm equivalent
- Aperture: f/8
- All [N] posts must be clearly visible — no post fully hidden behind another
- No overlap that could obscure counting
- Counting test: viewer must be able to count 1, 2, 3…[N] posts clearly

---

Section 8 — ANTI-FAILURE CONSTRAINTS

ANTI-FAILURE CONSTRAINTS

Explicitly forbid:
- [failure shape] geometry (e.g. Octagonal geometry)
- [wrong_count+1] or [wrong_count+2] posts
- Any extra vertical elements
- Uneven spacing
- Distorted or non-regular polygon shapes

This is a simple [N]-node structural system.
The perimeter contains ONLY [N] structural verticals.
No visual clutter that could resemble additional posts.

---

Section 9 — FINAL VALIDATION CHECK

List exactly what must be true. Derive counts from the model — never hardcode.

FINAL VALIDATION CHECK (MANDATORY)

The generated image is ONLY correct if:
- The perimeter is a true [shape] ([N] edges)
- There are exactly [N] posts on [footing type]
- There are exactly [N] exposed [primary member] with [tail description]
[- There are exactly [jack_count] jack rafters (if they exist)]
- There are exactly [brace_count] diagonal knee braces (if bracing enabled)
- The structure is symmetrical and physically believable

If any of these conditions fail, the image is incorrect.

---

Section 10 — Exclude block

Always last. One paragraph starting with Exclude:. Include:

• Standard hardware: metal brackets, joist hangers, hurricane ties, screws, bolts, plywood, pressure treated lumber, green lumber
• Wrong geometry by name: octagonal geometry (if hex), 7 posts, 8 posts, extra post, 5 posts
• Confabulation patterns: doubled posts, closely spaced posts, decorative posts, asymmetric posts, uneven post spacing, extra vertical members
• Absent members: roofing material, shingles (if open-rafter); walls, railings, partial walls (if open-sided); purlins (if purlins disabled)
• Style exclusions: modern furniture, string lights, anime style, cartoon, illustration, watercolor, blueprint overlay, distorted perspective, fisheye, people, animals, cars, shadows too dark, overexposed sky, clipping, grain noise, JPEG artifacts

---

Example — hexagonal cedar pergola (Vancouver Island): See references/example-hex-gazebo-prompt.md for a fully worked example showing what the output looks like for this specific project. That file shows the level of detail and section structure expected — not a template to copy verbatim.

---

Phase 3 — Tell the User to Paste

The Copilot CLI is text-only — it cannot generate images. After writing outputs/render-prompt.txt, output this message:

Render prompt ready: outputs/render-prompt.txt

Paste the ENTIRE file verbatim into:
  • ChatGPT (chatgpt.com) — uses gpt-image-1 / DALL-E 4 internally
  • Midjourney (midjourney.com) — use /imagine
  • Adobe Firefly (firefly.adobe.com)
  • OpenAI API: openai api images.generate --model dall-e-3

Known issue: even with geometry locks, some image model runs still produce
7 or 8 posts. Verify the count before accepting the result. Regenerate if
needed — the geometry lock improves odds but is not a guarantee.

---

Gotchas

• Prompt file is always written first. A user should always get a usable prompt even if image generation is not available in the environment.
• Do not hardcode angles. Read miter_deg, bevel_deg, pitch from structure.json (geometry section) every time.
• Model must be locked. Never generate a render prompt from an unlocked structure.json.
• Image output path is outputs/photorealistic-render.png — not output/.
• Copilot CLI cannot generate images. Every model in the CLI (GPT-5.4, GPT-5.5, Claude, etc.) is a language model only. Direct the user to ChatGPT, Midjourney, Firefly, or the OpenAI images API. Do not call copilot image — that command does not exist.
• The CAD-SPEC approach is the only validated technique for exact post counts. Simple count statements and stop-sign analogies alone still produced 7–8 posts across multiple generations. What finally worked: (1) perimeter rule with explicit turn count and interior angle, (2) naming the specific failure shape ("NOT an octagon"), (3) system parity constraint cross-locking all member counts, (4) plan geometry construction logic (circumscribed circle, equal angular increments), (5) camera raised to 6–7 ft, (6) dedicated Anti-Failure Constraints section. All of these together produced a correct 6-post image on the first run.
• Even with the CAD-SPEC approach, verify the count. It maximises probability but is not a guarantee. Instruct the user to regenerate if wrong.

---

Smoke Test

1. Locked model → single prompt file written: Given structure.json with _locked: true: outputs/render-prompt.txt is created with real values substituted, geometry lock block at top, Exclude: block at bottom. ✓
2. Unlocked model → halt: Given structure.json with _locked: false: skill halts with clear error message; no prompt files written. ✓
3. CLI unavailable → graceful fallback: Given copilot CLI not in PATH: outputs/RENDER_FAILED.md is written and outputs/render-prompt.txt is still present for manual use. ✓
4. Value substitution check: [POST_CUT_FT] and [TOTAL_HEIGHT_FT] must not appear literally in the output prompt — they must be replaced with model values. ✓

Completion: HANDOFF_BLOCK

{
  "stage": "photorealistic-renderer",
  "status": "COMPLETE",
  "outputs": [
    "outputs/render-prompt.txt",
    "outputs/photorealistic-render.png"
  ],
  "prompt_ready_for_paste": true,
  "image_generated": true
}

If image generation failed, set "image_generated": false and add "outputs/RENDER_FAILED.md" to the outputs array.