VibeGeometry Instructions

Project Purpose

VibeGeometry is a research and implementation home for agent-authored Blender scene generation.

The core problem is not "make a Python script that creates something shiny." The core problem is building a pipeline where an agent can understand a visual target, choose a procedural geometry strategy, construct inspectable Blender 5.0+ geometry-node graphs through Python, render the result, and revise from evidence without accumulating clever junk.

Canonical State

Treat state/map.yaml as the canonical project map.
Treat state/scratch.md as disposable working memory for one bounded subgoal.
Treat state/evidence.jsonl as the distilled durable ledger of what was learned, verified, rejected, or accepted.
Treat notes/vibegeometry-implementation-plan.md as the current implementation plan.
Update state/map.yaml when project understanding changes.
Add evidence after meaningful research, implementation, verification, or rejected paths, but keep it distilled. Routine proof belongs in git history, renders, smoke artifacts, or targeted logs unless it changes what the next session should believe.
Do not turn notes, map, handoff, and evidence into four copies of the same brain. Distinct jobs or bust.

Important Paths

Project root: E:\Projects\VibeGeometry
Canonical map: E:\Projects\VibeGeometry\state\map.yaml
Scratch surface: E:\Projects\VibeGeometry\state\scratch.md
Distilled evidence ledger: E:\Projects\VibeGeometry\state\evidence.jsonl
Branch ledger: E:\Projects\VibeGeometry\state\branches.json
Handoff summary: E:\Projects\VibeGeometry\notes\fresh-workspace-handoff.md
System map: E:\Projects\VibeGeometry\notes\vibegeometry-current-system-map.md
Implementation plan: E:\Projects\VibeGeometry\notes\vibegeometry-implementation-plan.md
Architecture rationale: E:\Projects\VibeGeometry\notes\architecture-rationale.md
State CLI: E:\Projects\VibeGeometry\tools\vibegeometry_state.py
Pre-compaction helper: E:\Projects\VibeGeometry\tools\vibegeometry_prepare_compaction.py

Useful Commands

Use the bundled Python runtime if python is not on PATH:

npm run state:status
npm run state:prepare-compaction
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\vibegeometry_state.py' add-evidence --type research --status ok --note '...'
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\vibegeometry_state.py' add-branch --id branch-id --hypothesis '...'

Session Bootstrap And Re-entry Protocol

On fresh session load, do this before implementation:

read:
- state/map.yaml
- notes/fresh-workspace-handoff.md
- notes/vibegeometry-current-system-map.md
- notes/vibegeometry-implementation-plan.md
run:
- npm run state:status
restate the current next action from the persisted state before starting edits
if the user only asked to rehydrate or reorient, stop after orientation and wait for an explicit continue instruction

After compaction, resume, or suspicious continuity loss:

rerun npm run state:status
reread state/map.yaml and notes/fresh-workspace-handoff.md
treat the persisted next action as authoritative unless fresh repo evidence contradicts it

When context pressure is clearly rising:

stop broad exploration
narrow the active move to one bounded pipeline organ
persist map or handoff updates, plus distilled evidence only when the lesson changes future belief, before the blackout lands

When the user says to prepare for imminent compaction:

immediately write hot live context from memory into a new state/scratch-compaction-<guid>.md file before reading files, running status checks, or doing tidy persistence work
run tools/vibegeometry_prepare_compaction.py before editing persistence surfaces
use its warnings as the checklist for map, handoff, scratch, evidence, and git hygiene
update only the state that actually needs to change
after hot context has been folded into canonical persisted state, delete the state/scratch-compaction-<guid>.md file so stale emergency memory does not linger
run tools/vibegeometry_prepare_compaction.py again after edits and scratch cleanup
fix errors, address warnings, and commit the completed persistence pass unless the work is deliberately mid-surgery

Operating Discipline

Before substantial edits, restate the current mechanism and intended change.
Prefer one clear hypothesis per iteration.
Verify with checks that reflect the visual and procedural goal, not just proxy success.
Revert or discard changes that do not clearly improve the target.
If the diff grows while understanding shrinks, stop implementation and switch to diagnosis.
Keep maps and prose together; do not replace useful maps with prose-only explanations.
Commit completed work before it rots in the worktree unless the task is deliberately mid-surgery or the user asked to leave changes uncommitted.
Push after major completed passes when a remote exists, unless the user asked not to or there is a concrete reason to keep the commit local for a moment.
Before handoff, compaction, or phase boundaries, sync state/map.yaml, add distilled evidence when the lesson changes future belief, refresh notes/fresh-workspace-handoff.md, and make the next action explicit.

Blender And Geometry-Node Doctrine

Target Blender 5.0+ unless a task explicitly chooses another version.
Prefer geometry nodes for procedural geometry and Python for construction, orchestration, parameterization, render setup, and validation.
Keep generated node groups named, inspectable, and reusable. A script that creates an opaque graph is just a new kind of mess with sockets.
Preserve attribute flow explicitly. Name important attributes, document where they are created, transformed, consumed, and exposed.
Prefer proven Blender node idioms and current API guidance over invented graph tricks.
Treat reference images as evidence-bearing inputs. Record what visual traits are being targeted: silhouette, repetition, surface breakup, scale language, material response, lighting, camera, and color.
Render review is mandatory for visual claims. A script that runs is not a scene that works.
When a generated graph misses the target, revise one hypothesis at a time: geometry structure, distribution logic, material, lighting, camera, or scale.
Keep failed render attempts only when they teach a durable lesson. Otherwise archive lightly or delete them; the repo is not a museum of almost.
Do not bury visual intent inside Python constants. Scene briefs, graph manifests, and review artifacts should expose what the agent meant to build.

6.8 KiB Raw Blame History