What does envision do?
A working loop between a person and you (the planner) to see what a real place could become. Keep it light: this tool is meant to grow with use. Follow the person, not this file, when they want something different; these are defaults, not rules.
Paths below are relative to this skill's folder (<skill>), which you can find from where you read this file.
0. Open or start a project
- If the current folder has a
project.md, that is the project: read it,taste.md, and thelog.mdof the space in progress, then pick up where it stopped. - Otherwise ask for a project name and create the folder (default
~/Envision/<project>/, or wherever the person says) with this shape, creating parts only when they are needed:
<project>/
project.md # what the place is, engine choice, spaces and their status, decisions
taste.md # the written taste profile (the person validates it)
inspiration/ # everything the person gave: images, unzipped folders, links.md, notes
moodboard/ # optional, for validating the taste
place/ # plans, maps, overview photos of the whole place, if any
spaces/<space>/
originals/ # real photos of this space
prompts/ # one prompt file per render
renders/ # outputs
log.md # each round: what was asked, what was made, what the person said
Start project.md from <skill>/templates/project.md.
1. Plug the tools (first time in a project, or when asked)
Run <skill>/scripts/doctor.sh. It lists which image engines are usable on this machine. Show the person the list in plain words and let them choose; note the choice in project.md. If the one they want is not ready, walk them through it (each adapter's header says what it needs). Never ask for or print secret values: keys live in the person's own shell environment.
The planner is you, whichever app opened this skill (Claude Code, Codex, ...). Notion, or any other place to keep a project page, is optional: if the person wants it and a connector is available, mirror the brief, the taste and the validated images there; the local folder stays the source of truth.
2. Understand the taste
Take whatever the person gives, in any mix: images in the chat, a zip or a folder, Pinterest boards or pins, links, a named style ("Spanish hacienda", "Japandi"), voice notes, plain text. Save the material in inspiration/. Look at every image; for links, read what you can reach and say plainly what you could not.
Write taste.md from <skill>/templates/taste.md: a one-line summary, then what keeps coming back (materials, colours, light, furniture, plants, mood), how the person lives in a space (from their words), what they do NOT want, and open questions. Tie each claim to its sources (e.g. "terracotta floors: 6 of 40 images + said so"). Then ask the person to correct it. It is a living file: update it whenever a round teaches you something ("keeps rejecting white sofas").
3. Mood board (optional)
Offer it; do it only if the person wants to validate the taste visually. Pick the cheapest route that answers what they ask: a selection of their own images or pins (free), links to look at (free), or generated images (cost money/quota: say so first). Save in moodboard/ and note in taste.md what they validated or rejected.
4. The place
If there is a plan, a map, or a complete set of photos, save it in place/ and write in project.md the list of spaces and how they connect, so versions stay consistent across rooms (same floor running through, same palette). If not, work space by space from the photos the person sends. Create spaces/<space>/ per space and put the original photos in originals/. Before the first render, describe what is really there (walls, openings, floor, ceiling, light, what is worth keeping), so the person can correct you.
5. Rounds
The person asks for something ("4 versions of the terrace, no furniture", "same but with a bar"). For each version:
- Write the prompt to
spaces/<space>/prompts/<render-name>.txt. Start from the person's request andtaste.md; pass 0-5 inspiration images as style references when they help. When the version should keep the real place, say so explicitly in the prompt: same walls, openings, proportions, camera angle and framing; name the things that must not move (a tree, a staircase). Say what changes and what does not. - Choose the base image and tell the person which one: the real photo to stay honest to the place, or a previous render to keep what they liked. Big changes usually go back to the real photo; small tweaks can build on a render.
- Render:
<skill>/scripts/render.sh <engine> --base <img> --prompt <file> --out <png> [--ref <img>]...(independent versions can run in parallel). Name renders so they sort and say what they are, e.g.r2-03-no-furniture-bar.png. - Look at each result yourself before showing it. Say honestly where it drifted from the real place (camera moved, a tree vanished). Send the images in the chat.
- Log the round in
log.md: the request, each render with its base, references, prompt file and what you see, then the person's reaction.
The person reacts: "keep this, drop that, I like these two, more around those". Fold it into the next round (and into taste.md when it is about taste, not about this space). Keep going until the person validates a few images. Mark them validated in log.md and list them in project.md, then move to the next space or the next part of the space.
Engines
Every engine is one executable in <skill>/engines/ with the same contract (see engines/README.md). To add one (another API, a local model, a web app driven by hand), add a file there; nothing else changes.