⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
blender-agent-core
Core discipline for ANY Blender/bpy work — contract-first, purpose-first (render-only / print / both), knowledge routing, execute-verify-refine loop with the AGENT_OK/AGENT_FAIL sentinel contract, numeric-first verification, Form gate before delivery media, production gate before delivery. Activate for every task that touches Blender, before any domain skill.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
DESIGN:OS 3D Blender
An MCP server and agent skill for Blender 5.2. Your coding agent models, renders and checks mechanical parts on your machine: four tools, an AGENT_OK contract, and a 3D-print production gate. Specs are locked to millimeters. Exports are STL and glTF.
FREE + source-available (PolyForm Shield 1.0.0).
Quickstart
In Claude Code:
/plugin marketplace add jangtrinh/design-os-3d-blender
/plugin install design-os-3d-blender@design-os-3d-blender
From a clone (Codex, Gemini CLI, Antigravity, Cursor, or a standalone MCP client):
git clone https://github.com/jangtrinh/design-os-3d-blender.git
cd design-os-3d-blender
python3 scripts/self_check.py
pip install .
Point your MCP client at the installed command, and set BLENDER_BIN to your Blender 5.2 binary:
{
"mcpServers": {
"design-os-3d-blender": {
"command": "design-os-3d-blender",
"env": {
"BLENDER_BIN": "/Applications/Blender.app/Contents/MacOS/Blender"
}
}
}
}
On Linux the binary is often /usr/bin/blender. The first tool will tell you if it cannot find it. If you use uv, uv run design-os-3d-blender from this repository starts the same server, with no need to publish a package.
Ask for a part in plain English. A typical pass validates a spec.json, runs a headless bpy script, and stops on one line: AGENT_OK or AGENT_FAIL.
What it makes
These are real builds from this repository, made in Blender 5.2 through the agent pipeline.
| Build | What it is | In this repo |
|---|---|---|
| CK-001 | A compact keyboard, from photo and spec to a printable kit | docs/reviews/ck-001/r02 |
| DC-01 | A desk robot: printed parts, a carrier board, an assembly film | docs/reviews/dc-01/r03 |
| Robot arm | A printable arm, with gated plates | builds/robot-arm-print-assembly |
| Nodestack | Modular industrial storage | docs/reviews/nodestack/r03 |
DC-01 assembled, and the printable robot arm open in a real Blender 5.2 window. Print plates for the arm are in docs/images/readme/builds/print-plates.jpg and docs/media/robot-arm-print-plates.png.
How it works
The MCP server exposes four tools. That is the count in src/design_os_3d_blender_mcp/server.py on this branch:
| Tool | What it does |
|---|---|
blender_runtime_status | Host, Python, and whether a Blender 5.2 binary is on the path. Call this first. |
query_blender_knowledge | Search the verified bpy 5.2 knowledge base in knowledge/ before writing a script. |
validate_part_spec | Check a spec.json: units in mm, target dimensions, tolerance, minimum wall. |
execute_blender_pass | Run a headless pass and read the AGENT_OK or AGENT_FAIL line. |
Two prompts (design_parametric_part, review_geometry_gate) and two resources (blender://knowledge/index, blender://specs/bracket-example) sit next to the tools. They are not extra tools.
Every executed pass ends with one machine-readable line. Exit codes alone are not a verdict. The 3D-print production gate checks manifold geometry, wall thickness and millimeter-locked bounds. Worked specs live in specs/ and builds/.
The Claude Code, Codex and other agent plugins install the same skill, skills/design-os-3d-blender/SKILL.md. /doctor is a read-only diagnostic. python3 scripts/self_check.py is the offline repository check: it prints ok: design-os-3d-blender self-check passed (design-os-3d-blender) and exits 0 when the manifests and contracts match.
Nothing in the server sends data off your machine. See PRIVACY.md.
Install
Choose the setup that matches your agent. Every option uses the same skill at skills/design-os-3d-blender/SKILL.md.
Claude Code
/plugin marketplace add jangtrinh/design-os-3d-blender
/plugin install design-os-3d-blender@design-os-3d-blender
OpenAI Codex
git clone https://github.com/jangtrinh/design-os-3d-blender.git /tmp/design-os-3d-blender
mkdir -p ~/.codex/skills/design-os-3d-blender ~/.codex/prompts
cp -R /tmp/design-os-3d-blender/skills/design-os-3d-blender/* ~/.codex/skills/design-os-3d-blender/
cp /tmp/design-os-3d-blender/prompts/doctor.md ~/.codex/prompts/design-os-3d-blender-doctor.md
rm -rf /tmp/design-os-3d-blender
Gemini CLI and Google Antigravity
git clone https://github.com/jangtrinh/design-os-3d-blender.git /tmp/design-os-3d-blender
mkdir -p ~/.gemini/skills/design-os-3d-blender
cp -R /tmp/design-os-3d-blender/skills/design-os-3d-blender/* ~/.gemini/skills/design-os-3d-blender/
rm -rf /tmp/design-os-3d-blender
OpenCode, Cursor, Windsurf and other agent harnesses
git clone https://github.com/jangtrinh/design-os-3d-blender.git /tmp/design-os-3d-blender
mkdir -p ~/.agents/skills/design-os-3d-blender
cp -R /tmp/design-os-3d-blender/skills/design-os-3d-blender/* ~/.agents/skills/design-os-3d-blender/
rm -rf /tmp/design-os-3d-blender
Verify:
python3 scripts/self_check.py
Or run /doctor inside Claude Code or Codex to inspect installed skill paths, plugin manifests, and whether Blender is reachable.
Uninstall the skill copies:
rm -rf ~/.claude/skills/design-os-3d-blender ~/.codex/skills/design-os-3d-blender ~/.gemini/skills/design-os-3d-blender ~/.agents/skills/design-os-3d-blender
Prompt recipes live in docs/cookbook.md. More setup notes are in docs/antigravity-setup.md and docs/upstream-agent-integration.md.
Limits
- Sheet-metal or paperboard folding, where 2D crease patterns govern the topology: use
design-os-origami. - Organic character sculpting or a full game-character rig that needs a sculptor's pass.
- 2D vector UI motion: use [`de
// HOW IT'S BUILT
// FILES
5 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.agents/skills/blender-agent-core/SKILL.md11 KB9a0e5c6c1456upstream ↗
--- name: blender-agent-core description: Core discipline for ANY Blender/bpy work — contract-first, purpose-first (render-only / print / both), knowledge routing, execute-verify-refine loop with the AGENT_OK/AGENT_FAIL sentinel contract, numeric-first verification, Form gate before delivery media, production gate before delivery. Activate for every task that touches Blender, before any domain skill. --- # Blender Agent Core This skill is a ROUTER + procedure. The deep knowledge lives in `knowledge/` — load exactly the file you need, do not recall it from memory. The root operating rules are in `AGENTS.md` (precedence: `.project-agent.md` > `AGENTS.md` > this skill). The `.agents/skills/` copy is the source; `.claude/skills/` is a mirror that must be kept in sync. ## 0. Routing by task | Task | Also load | |---|---| | Task starts and the deliverable **purpose** is not stated | Ask once — render-only / 3D print / both, recommendation **both**; record `purpose:` in `state.md` (`AGENTS.md` loop 0b) | | Purpose `print`/`both`, phase 2 (form + interfaces) is complete | **Form gate**: temporary bake → compare with independent authored spec → `production-gate.py` exit 0; **final gate** at delivery. Existing unknown shapes use [measurement provenance](references/recipes.md#spec-from-measurement), not self-derived acceptance. Verification imagery stays available | | Part will be printed/manufactured, needs exact dimensions/standards | [Production contract](references/recipes.md#production-contract) → `specs/README.md` | | Execute via MCP/headless, read errors | [Explicit execution context](references/recipes.md#explicit-execution-context) | | Reference image available | Skill `blender-image-to-3d` | | Joints, hands, manipulation, animation tasks | [Articulated task](references/recipes.md#articulated-task) | | Assembly/exploded view | [Assembly sequences](references/assembly-sequences.md) | | Load-bearing, duty, working mechanism | [Mechanical evidence](references/recipes.md#mechanical-evidence) | | Batch render, video, export | [Render delivery](references/recipes.md#render-delivery) | | Turntable / product shot | `scripts/turntable-preview.py` + `knowledge/60-pipeline/product-viz-and-shots.md` | | Python API research, evaluated geometry, Action slots or Geometry Nodes inputs | `knowledge/00-foundations/native-api-contracts.md`; route the relevant contract topic through `blender-knowledge-workbench` | | Multi-pass native work needs resumable evidence, explicit parameters or independent criticism | `knowledge/60-pipeline/native-agent-iteration.md`; use `scripts/native-pipeline.py` for declared execution and `scripts/native-review.py` for revision-bound review | | Start a production-grade product or conduct a session retro | `docs/product-workflow-template.md`; `native-hard-surface --topic session-retrospective` | | Surprising bore/wall/collision/export result or a tolerance-extreme failure | `knowledge/60-pipeline/geometry-diagnostic-workflow.md`; `precision-assembly-metrology --topic geometry-diagnostics` | | Native Full HD, social media or new media after a model revision | `knowledge/60-pipeline/native-render-delivery.md`; `render-export-delivery --topic native-render-delivery` | | Retention, material/process, electronics or physical manufacturing blocker | `knowledge/60-pipeline/manufacturing-evidence-workflow.md`; `precision-assembly-metrology --topic manufacturing-evidence` | | CAD STEP ingest, Vietnamese Unicode part decoding, batch parametric part edit or multi-body STEP export | `knowledge/70-cad-precision-robotics/cad-step-roundtrip-and-dfm.md`; `precision-assembly-metrology --topic cad-step-roundtrip-dfm` | | Organic mesh scaffold (jewelry, figurine, scan) needs watertight repair and multi-part machining/molding split with dowel keys | `knowledge/10-modeling/organic-scaffold-machining-split.md`; `native-hard-surface --topic organic-scaffold-machining-split` | | Commercial 6-shot studio catalogue render, decoupled wood-grain/stain PBR, Face-vs-CutEdge slotting or AI refine kit | `knowledge/30-lighting-render/studio-catalogue-and-ai-refine.md`; `render-export-delivery --topic studio-catalogue-ai-refine` | Read the [hard rules](references/hard-rules.md) every session (state explicitly which are ENFORCED vs MANUAL). Deliver results per [revision-bound acceptance](references/recipes.md#revision-bound-acceptance). ## 1. Knowledge routing (mandatory) At the start of every Blender task, read the **3 foundation files** if they are not already in context: `knowledge/00-foundations/blender-version-matrix.md`, `bpy-scripting-core.md`, `agent-workflow-loop.md`. Then `python3 scripts/blender-knowledge.py list` → `route <workflow-id>` to obtain the reading pack (skill `blender-knowledge-workbench`); load only the part you need. `knowledge/INDEX.md` is an on-demand lookup, not a must-read. `loads_with` is a one-hop hint, not a recursive load (one hop ≈ 40–50k tokens). ## 2. Loop (R1–R8 condensed — full version in agent-workflow-loop.md) 1. **Contract first** — purpose first (render-only / print / both, default `both`), then spec.json for a production part; fidelity contract for a reference; missing numbers → `request-input`. 2. **Decompose** — scene graph → one file per pass, ≤ ~80 lines, one purpose. 3. **Assert every step** — a pass ends with `rt.emit_ok(step, **postconditions)`; the postcondition must FAIL if the step silently no-ops; operator return must be `{'FINISHED'}`. 3b. **Form gate closes phase 2** when purpose is `print`/`both`: measure a temporary bake against the authored spec. Keep required dimensions/tolerances independent of output. Delivery media needs PASS or an owner waiver; final gate applies at delivery. Verification imagery stays mandatory, available and cheap (≤512 px / low-sample, roughly ≤2 minutes per pass). 4. **Non-destructive scaffold** — the lib's `scaffold()` reads first and writes only when factory-default or `force=True`; never reset the scene being worked on. 5. **Screenshot with intent** — write down the expectation and what would falsify it BEFORE looking. 6. **2 failures on the same step → change the CLASS of approach; 3 failures → `request-input`.** 7. **Checkpoint** (`checkpoint(tag)`) before every destructive op (boolean, apply, join). 8. **Know the handoff boundary** — fine weight painting, facial rig, art direction: flag early. After a saved artifact and a failed wrapper/journal result, inspect both before any retry. Correct a metadata/dependency failure without rebuilding valid geometry. Required pipeline postconditions are finite numbers; hashes belong in receipts. Check maximal tolerance stroke and a failing control, not only nominal endpoints. Keep actual component selection, logic/ECAD, firmware and physical qualification as separate closure rows. A successful pilot-record check cannot authenticate a lab. The generic production schema supports partial diagnostics. For final exported-part coverage, use `production-gate.py --audit-report <existing>` with the actual scene, spec, existing export directory and new report path (see `specs/README.md`). This host-only route checks per-part wall/features/roundtrip coverage and current byte bindings. It does not rerun geometry, authenticate reports or prove the declared part list is exhaustive. Source adequacy and physical acceptance remain manual; a stage waiver does not remove manufacturing scope. ## 3. Verify ladder (cheap → expensive; if a number answers the question, do not spend an image) ```python import sys; sys.path.insert(0, "<ROOT>/scripts") import agent_runtime as rt; lib = rt.load_lib("<ROOT>/scripts/agent-verify-lib.py") ``` 1. Numbers: `assert_exists`, `tri_count`, `world_bbox`, `has_material`, fcurve keys — plus the postconditions in `AGENT_OK`. Bounds use evaluated mesh vertices and transforms; active-view-layer settings, children and instances need an explicit scope. Borrow temporary meshes with `evaluated_mesh()` and copy independent data before leaving its context. 2. Assert `framing(obj)['in_frame']` (image bounds plus front/near/far depth) → `preview_render(engine="EEVEE"|"CYCLES")` (≈0.1–0.2 s at 128–256px on a small scene, restores state) → `frame_stats()` (stdev < 0.01 = flat frame, needs diagnosis). The numeric screen does not prove occlusion, render visibility or render-border coverage. 3. Viewport screenshot (MCP) — composition, "does it look like it". 4. Low-sample Cycles preview — real material/lighting. 5. Comparison sheet (`scripts/make-comparison-sheet.sh`) — when a reference image exists. 6. Turntable (`scripts/turntable-preview.py`) — guards against the "cardboard cutout" look. 7. **Part production:** `python3 scripts/production-gate.py --scene <blend> --spec <spec.json> --report <out.json>` exit 0; attach the report to the build. The gate proves topology/dimensions/screening numbers — it does **not** prove load, real fit, or thermal duty. Measured on this machine: cold start 0.5 s, 256px preview ≈ 0.4–2 s. Verification is cheap; the ladder order follows information value, not cost. ## 4. Execution modes (check in order) 1. **MCP tools** (addon Connected): `rt.run_file("/abs/pass.py")` — full traceback inside `AGENT_FAIL`; a fresh namespace per call, reload helpers with `rt.load_lib` (cached by sha). Read the scene read-only before mutating. 2. **Socket bridge** when the MCP tool is not loaded: `python3 scripts/blender-socket-client.py execute_code --file pass.py` (exit 0/1/2/3 per the sentinel; output is not truncated). 3. **Headless** for batch/fault-test/gate: `bash scripts/headless-run.sh pass.py` (`--factory-startup --disable-autoexec --python-exit-code 3`; exit follows the sentinel). Supply a sheet/preview after every pass; when the build is finished, open the right file for the user. General rule: decide from the **last line** `AGENT_OK`/`AGENT_FAIL`; a timeout after sending a mutation = unknown → read the state before resending; a single writer for the GUI. ## 5. Failure quick-map | Symptom | Read | |---|---| | `NameError` on a helper/`__file__` inside "executed successfully" | §4 — import inside the payload, `rt.load_lib` | | STL/topology assert fails although the mesh looks fine | `production-gate.py` topology; 3d-printing.md §5 | | Endpoints PASS, parts overlap mid-motion | assembly-sequences.md; sweep per frame | | Black/flat render | `framing()` + `frame_stats()`; `persistent_data=False`; lighting.md | | KeyError on socket/enum | version-matrix §renames — introspect `[s.name for s in node.inputs]` | | Boolean shreds the mesh | modifiers.md §boolean-solver + the checkpoint before it | | Export breaks in another engine | export-interchange.md + `verify_export()` (separate process) |.agents/skills/blender-agent-core/references/assembly-sequences.md5.5 KBfb52f11e8ca9upstream ↗
# Removable assembly films: staging, order and swept paths Use for assembly/exploded views of separate printed and purchased parts. This is a project recipe, not a physical assembly certification. [Evidence and journal](../../../../plans/260905-2337-arm-session-retro/plan.md) identify the Arm session that motivated it. ## Contract before motion Identify every physical unit, assembly receiver, final datum, fastener pairing and dependency. Keep the approved source scene immutable. Record separately: presentation intent, assembly order, geometric fit and loaded operation. Changing the film cannot erase payload/duty requirements. Preserve the owner's selected film direction. If asked to repair transition/order, adjust that film's timing and paths; do not silently replace its camera language with a workshop/orbit concept. Keep receivers visible before moving the camera toward them. Hold the camera while parts install, unless the brief explicitly requests motion. ## Eight outputs, in order 1. **Contract:** source revision, intended sequence, camera language and physical blockers. 2. **Unit manifest:** each printed/purchased part once; rigid screw head/thread pairs; reversible final transforms. 3. **Dependency graph:** receiver → internal hardware → mating unit → retention → wiring → covers; insertion/access may change the order. 4. **Staging layout:** waiting subassemblies separated in world space and camera projection; gap derived from actual envelopes. 5. **Swept-path report:** arrivals and seats tested through time against already installed parts; distinguish waiting, transit and terminal mating. 6. **Short animatic:** inspect the failing interval and analogous mechanisms, plus framing at first/last poses; reject before full batch. 7. **Frozen render manifest:** exact inputs/settings/range; new revision invalidates affected evidence and frames. 8. **Decoded delivery:** count/rate/size/full decode plus viewed output; media/motion/fit/manufacture statuses remain separate. ## Staging is not seating A correct final pose does not validate the waiting pose or approach. A pair that touches in the final assembly must not be exempted throughout the sequence. Same-link filtering is valid only while parts actually form one rigid installed body; it can hide an uninstalled part intersecting its future link. First broad-phase evaluated world bounds, then an appropriate surface/solid predicate. AABB overlap is a candidate pair, not penetration volume. Surface BVH misses full containment and cannot establish exact clearance or physical insertion. Record scene units, object transforms, evaluated geometry, exclusions and frame coverage. For each exception specify **exact pair, phase/frame window, interface, rationale and residual uncertainty**. An `actuator-visual` tag alone is not permission to ignore every collision. Separate actual servo cases from illustrative output shapes. Contact with a simplified output does not validate real horn/spline mating or retention. Zero overlap while waiting still does not validate transit. Test the swept route, including any waypoints. Lift/traverse/lower is one candidate when a direct segment crosses the receiver; derive lift and approach axes from geometry, not a universal 120mm constant. Closed bearing carriers can obstruct a fork's passage even when all final poses fit. Validate alternate order before changing geometry or hiding parts. Do not infer driver obstruction from nearby envelopes without measuring head-to-thread direction and tool approach. Component fit, access and torque require the actual hardware geometry/evidence. ## Timing, camera and wires Quintic easing values have zero first/second derivative at their endpoints. This does not mean zero jerk, and frame-sampled LINEAR F-curves do not constitute a continuous C2 trajectory. Inspect the interpolation actually evaluated by Blender; distinguish visual smoothness from a controller motion profile. Fit the camera to the intended visible interval, including moving envelopes and final fingertips. Preview the initial receiving part, complete remote subassembly, midpoint transit, seat, analogous joint, tool and hero endpoints before long render. Pose screenshots do not by themselves prove temporal smoothness. A curve reveal or collapsed-tip animation is visual assembly order. It is not length-preserving wire threading, bend-radius compliance or strain relief. Declare connector pinout, cable diameter, slack, bend limits and moving-joint sweep from selected hardware when claiming a functional harness. Leave those claims open until checked. ## Evidence in this Arm The [layout](../../../../builds/robot-arm-original-refined/scripts/repair-staging-layout.py), [motion](../../../../builds/robot-arm-original-refined/scripts/animate-physical-units.py), [independent sweep](../../../../builds/robot-arm-original-refined/reports/independent-review/check-overlap-repair.py) and [acceptance guard](../../../../builds/robot-arm-original-refined/scripts/check-clearance-acceptance.py) are artifact-specific inspect/adapt examples. The waiting and seat checks exclude hardware; do not generalize their result to the complete assembly, subframe continuity or manufacture. The Arm used 35mm projected staging target, 120mm lift and axial carriers; these are case values, not design standards. **Enforcement:** sequence/gap/phase choice and visual review are MANUAL. Named Arm scripts executed particular predicates on one revision. A reusable general gate is still [E6](../../../../docs/blender-workflow-improvement-backlog.md#e6--validate-assembly-states-before-full-render)..agents/skills/blender-agent-core/references/hard-rules.md9.0 KB9c038944e9e1upstream ↗
# Project operational rules These supplement the existing loop; API knowledge remains in `knowledge/`. Read [workflow](../../../../docs/blender-ai-workflow.md) for intent and [recipes](recipes.md) for task routing. `MANUAL` means controller discipline, not an implemented hook or gate. Early-table times are UTC on 2026-09-05; later incidents carry their explicit source/time. Detailed session evidence is retained in the source workspace and is not included here. | Trigger | Required behavior | Enforced by | Source | |---|---|---|---| | Every new pass/session | Read active scene/file/version/units and declared controller; include imports, source path and assertions in that call. Do not assume MCP Python locals persist. | ENFORCED (2026-09-06): `agent_runtime.run_file` owns namespace/`__file__`/traceback; `load_lib` re-loads helpers by sha | 08:10:09 missing `framing`; 10:00:21 missing `__file__` | | Any tool reply | Transport success or `AGENT_OK` text is insufficient; inspect structured status, traceback and declared postconditions. Save complete evidence outside truncated display text. | ENFORCED (E1 done): last-line `AGENT_OK`/`AGENT_FAIL` sentinel decides; `headless-run.sh` exit 0/1/2/3; socket client checks status. E3 partial: `production-gate.py` reports bind scene+spec sha256 | Failure-bearing outputs at 08:24:57, 10:15:59; local exit probe | | Timeout after mutation was sent | Mark outcome unknown; read/reconcile state before another mutation. Never infer rollback or blindly resend. | MANUAL; E1 | Partial execution failures in session; socket/addon static audit, no lost-reply incident claimed | | Multiple agents | One writer per GUI/scene; reviewers read-only; batch workers use immutable inputs and disjoint outputs. Review image transformations write to a separate review directory, never source/delivery paths; the controller rechecks delivery hashes after review. | MANUAL; lock implementation deferred | Architect/Security debate, no concurrent-writer incident claimed | | New functional/reference requirement | Update current contract and dependent gates; resolve payload/duty/packaging before committing mechanical design. Keep accepted requirements across presentation changes. | MANUAL; E5 | 09:34:32 engineering correction; 09:36:32 payload/duty; 09:43:08 housing growth | | Reference construction | Blockout and camera-matched comparison before details; state unseen geometry as inference. | Existing image-to-3d router + MANUAL visual review | 08:37:45 form polish; 09:10:16 reference fidelity correction | | Mechanical/reference reconstruction | Primary view governs visible count, facing, placement and silhouette; close-ups govern local form. Read applicable drawings/specifications before deciding routing, stations, taps, or connection anatomy; distinguish fact, design choice and unknown. | MANUAL; component workflow | 2026-09-09 instrument station correction | | New geometry family | Controller proves the native identity-risk prototype before delegated reuse. Constructor promotion needs declared axes/ports/range plus a second real consumer and regression proof. | MANUAL; component workflow | 2026-09-09 reusable instruments | | Generated Blender identifiers | Use deliberate integer indices for generated suffixes; isolate a native crash in a disposable headless probe before sending it to the GUI. A process abort without a sentinel is an unknown failed outcome. | MANUAL; E1 sentinel | 2026-09-09 float-derived suffix abort | | Articulated task | Check real joint descendants, pivot frames, critical hand interaction and reachable path; preview story and timing before full render. | Task-specific scripts + MANUAL; E3 | 12:16–12:19 IK/registration failures; 12:13:03 natural-task steering | | Geometry or motion changes | Invalidate affected topology/contact/load/export evidence by dependency; do not inherit approval from an older hash. | Print parts: ENFORCED by gate hash binding (a report for another scene/spec sha is not reusable). Motion/load evidence: MANUAL; E3/E5 | Wrist-bridge geometry revision; independent flexibility review | | Surface or media gate passes | Keep media, sampled-contact, fit and manufacturing statuses separate; publish limitations of the actual predicate. | MANUAL; E5 | Current arm independent reviews: sampled screen and manufacture BLOCKED | | Preview or export verification | Use a disposable process or restore all changed state in `finally`; export re-import must not reset the live working scene. | ENFORCED (E2 done): `preview_render` restores all touched settings in `finally`; `verify_export` runs in a disposable process; tests `tests/execution/test_verify_lib.py` | Preview failure probe leaves samples/resolution/path changed; helper source audit | | Temporary transform applied for export, measure or plate layout | Restore **every axis you touched** in a `finally`, not only the one you remember; re-read one placed object after the restore and assert it. This row is scoped to build/export/pack passes; `preview_render`/`verify_export` are already ENFORCED above. | MANUAL | 2026-09-06 pass-30: export slid `location.y`, the restore reset only `.x` → parts stayed in a row while the slabs moved | | Shell command that builds a list, range or file set | zsh: use arrays (`items=(…)`, `"${items[@]}"`) or explicit `${var%…}` expansion; never rely on unquoted `$var` word-splitting. | MANUAL | 2026-09-06: `set -- $rng` and a montage file list, twice in one session | | Full render | Preserve input identity and raw frame sequence; validate range/completeness; presentation-only changes reuse source frames. Check final encode and final visual evidence. | Task renderer/video verifier + MANUAL; E4 | 12:40:01 no-subtitle correction; 720 raw frames reused | | Assembly or exploded view | Validate waiting layout and transit separately from final pose; allow named mate contacts only in their declared phase. Check analogous joints. | MANUAL + Arm-specific sweep/acceptance; generic E6 deferred | Owner screenshot 2026-09-05 22:56:06+07; A5 revisions522afd/e9323/11d88f | | New synthesis or boilerplate | Review actual code and negative controls before promotion; case constants and source labels are not standards or runtime proof. | Workbench hash-bound review; MANUAL technical judgment | 2026-09-05 session retro; new source RES-CAD-ROB-13 and adapter audit | | First/last camera and render reuse | Include endpoint framing in cheap preview; reuse changed-file frames only with scoped dependency/state equivalence evidence, never filename equality. | MANUAL; A5 hero-prefix comparison is task-specific, E4 generalization open | A5 decoded fingertip crop and 89-frame hero repair,2026-09-05 | | HQ reference coverage | The coverage command validates only declared receipt bindings. `--launch` guards its own render-only route; direct Blender, MCP and direct headless calls bypass it. State the actual launch route and retain source/settings/media hashes. | ENFORCED within `hq-coverage-gate.py --launch`; otherwise MANUAL | 2026-09-08 coverage gate and 2026-09-09 C05 direct launch | | Surprising geometry measurement | Validate the checker before changing geometry. For small evaluated meshes far from origin, translate vertices to a local centroid and use float64 scalar arithmetic for signed volume; rerun the corrected checker on the unchanged source. | MANUAL; task-specific audit | 2026-09-09 C05 false negative volumes | Historical status, 2026-09-06: E1/E2 implemented, E3 partial; E4–E7 then open. See the [current backlog](../../../../docs/blender-workflow-improvement-backlog.md) for the 2026-09-17 update. Native pipeline/review and CK-001 qualification/packaging now enforce their declared routes, not every historical checker or physical claim. | Session-proven trigger | Required action | Enforcement scope | |---|---|---| | Output disagrees with authored dimensions | Preserve target and measured values separately; identify the wrong contract/code/checker | MANUAL source/requirement judgment; spec-bound gate checks declared targets | | Fine triangles yield zero wall samples | Keep minimum wall and segmentation; test primary coverage, bounded fallback and bad/empty controls | `walls_overhang.py` 1.0.2 sampling selection and regression | | Saved model exists but pipeline metadata fails | Read source/receipt; retain journal and verify existing output without duplicate mutation | Runner preserves attempt state; recovery choice is MANUAL | | Nominal fit passes | Include source-tolerance extremes and intentional mismatch/overtravel controls | Task-specific tests; extrema selection and coverage remain MANUAL | | New native-render request or changed aspect | Render actual model; preflight final crop/surface, image size and decoded video | Task media code plus MANUAL visual review | | Physical or electrical release claim | Distinguish geometry, logic, ERC/DRC, target build and calibrated pilot records | CK-001 schema checks are scoped; engineering/lab truth remains independent | One current entrypoint: `docs/product-workflow-template.md`. Deeper diagnosis and manufacturing/media procedures are routed through the existing skills..agents/skills/blender-agent-core/references/recipes.md16 KB9d7598d0b38cupstream ↗
# Blender operational recipes Load only the section triggered by the task. These recipes reuse existing scripts and KB; they are not a new execution framework. Source evidence and missing automation are in the [workflow](../../../../docs/blender-ai-workflow.md) and [backlog](../../../../docs/blender-workflow-improvement-backlog.md). ## Explicit execution context Manual preflight before building, recorded in the task record: - The interpreter that actually runs the payload: Blender version/build, `sys.executable`, Python version; the host Python having a package does not prove Blender's Python has that package. - Dependencies on the correct interpreter: check the import/`importlib.util.find_spec` of each package used; if one is missing, choose code without that dependency or an environment that already has it. Do not bulk-install or repeatedly try blind imports. - Current scene: absolute input path, scene name, mode, units/scale, active camera and frame range; confirm they belong to the assigned scope. - APIs to be used: introspect RNA enums/sockets/operator availability; compiler-check the script before execution and place imports/helpers/`__file__` in an explicit namespace. - A single controller, checkpoint/input identity, output root, and the pass's checker and postcondition; an open port is only a transport signal, not scene readiness. Each reviewed disk payload executed through MCP runs through the runtime module, which owns the namespace, the traceback and the sentinel: ```python import sys; sys.path.insert(0, '<ROOT>/scripts') import agent_runtime as rt rt.run_file('/absolute/path/to/reviewed-pass.py') # last stdout line: AGENT_OK {...} | AGENT_FAIL {...} ``` Imports/helpers must be inside that payload or loaded into that namespace. This preserves traceback source lines and does not assume values from a previous tool call. It is unrestricted Python, not a sandbox. Reject a failed postcondition even when the transport says execution succeeded. See [hard rules](hard-rules.md) for unknown outcomes. For isolated read/verification or fault probes use a fresh headless process with explicit Python failure exit: ```text /Applications/Blender.app/Contents/MacOS/Blender --factory-startup --disable-autoexec -b [trusted-input.blend] --python-exit-code 23 --python [checker.py] ``` Brackets are placeholders. Put options before the action they affect. Auto-execution policy must match the trusted asset's driver needs; do not silently disable required behavior or enable untrusted startup scripts. `scripts/headless-run.sh` now supplies `--factory-startup --disable-autoexec --python-exit-code 3` and derives its exit from the last-line sentinel `AGENT_OK`/`AGENT_FAIL`; still verify the sentinel JSON, report identity and assertions together — exit code alone is not a gate. Use an external bounded supervisor only for its own disposable process; no killing the live GUI because it seems slow. ## Reference reconstruction and HQ review Trigger: a reference-led component with industrial or mechanical detail. Read `docs/orc-component-workflow.md`, its brief template, and `blender-image-to-3d` before construction. 1. Choose the primary visual authority for count/facing/placement/silhouette; use close-ups for local profile. For functional routing, station, tap, or connection choices, read applicable drawings or official documents first and record applicability. Image/CAD evidence can support appearance or construction vocabulary; it does not select equipment, ratings, or hidden dimensions. 2. The controller builds the first native prototype of each new geometry family. A reusable profile, instrument, or hardware family needs explicit axes, pivot, mount port, supported range, local regression proof, and a second real consumer before promotion. 3. Before final output, manually inspect every named critical feature and supplied view at comparable apparent scale. Construction-layer review is mandatory for close hardware. A feature inventory, topology check, or mesh count is only a heuristic. 4. Freeze candidate and settings hashes, proof regions and final media hashes. A source/camera/resolution change invalidates affected proofs; retain prior media as prior-revision evidence. 5. Use `python3 scripts/hq-coverage-gate.py ... --launch` only when taking that guarded route. It checks declared receipt bindings before its own runner; direct Blender, MCP, or direct headless launch does not pass through it. This distinction is a reporting requirement, not a claim that every render is intercepted. ## Production contract Trigger: any part that will be printed, machined or assembled with real hardware. Load `60-pipeline/3d-printing.md`, `70-cad-precision-robotics/cad-precision-modeling.md`, `fasteners-seals-mechanics.md`, `polymer-3dprinting-cad.md`; read `specs/README.md`. 1. **Before detailing**, write `builds/<slug>/spec.json` per `specs/build-spec.schema.json`: units mm; every part with `target_dims_mm` ± `tol_mm`, `material`/`process`/`orientation_up`, `min_wall_mm`, `max_overhang_deg`, `expected_shells`; every hole/boss/slot with axis, center, diameter ± tol and the fastener standard it serves; declared `load_cases` and `physical_evidence` still required. Missing numbers → verdict `request-input`; do not model around a guess. 2. Model in metres (`scale_length == 1`), apply transforms, one object per printed part, name = spec `object`. 3. Run the gate in an isolated process before any delivery claim: `python3 scripts/production-gate.py --scene builds/<slug>/<file>.blend --spec builds/<slug>/spec.json --report builds/<slug>/reports/gate-report.json --export-dir builds/<slug>/parts` Exit `0` pass · `1` requirement failed · `2` spec/scene incomplete · `3` execution error. The report binds scene+spec sha256, checker version, per-part measured vs allowed, `failed[]`, `coverage`, `exclusions`. 4. Read `coverage.unchecked` and `exclusions`: a passing gate proves topology, dimensions, feature diameters, wall/overhang screens and STL round-trip. It does **not** prove load capacity, fit after shrinkage, thermal duty, retention or assembly access — those stay `physical_evidence` items and keep manufacture `BLOCKED` until supplied. 5. Any geometry change re-runs the gate; an older report cannot be inherited (hash mismatch is rejected by design). For final exported-part coverage, follow the generic geometry run with: `python3 scripts/production-gate.py --audit-report builds/<slug>/reports/gate-report.json --scene builds/<slug>/<file>.blend --spec builds/<slug>/spec.json --export-dir builds/<slug>/parts --report builds/<slug>/reports/coverage-audit.json` This read-only host route rejects missing parts, omitted/invalid wall limits, skipped or failed required results and stale scene/spec/STL bindings. It requires recorded roundtrip evidence and never launches Blender. Generic extra required checks apply per part; named feature checks apply to their declared owners. The audit covers the supplied spec, not every object or unlisted feature. Choosing the full part/feature inventory, trusting original evidence and judging the adequacy of the geometry screens remain manual engineering responsibilities. It always retains manufacture BLOCKED. Do not remove requirements to obtain PASS. A stage waiver remains a recorded exception. It does not make print/both manufacture `NOT_REQUESTED`; unverified manufacture stays `BLOCKED` unless the owner explicitly removes manufacturing from the task's purpose. ## Spec from measurement Trigger: existing geometry needs measurement or an input contract. Keep the authored design target separate from what the bake measures. With an existing spec, compare against it; never redefine failed targets from the output. Without one, record observations as provisional reverse-engineering inputs and obtain the missing design requirements before claiming correctness or manufacturing fit. 1. Bake first: duplicate the printable parts into a separate `*-print.blend`, apply every modifier and transform (scale 1,1,1, identity), one object per spec `object`, name = spec `object`. 2. Measure world bounds, bore centres/axes/radii and feature depth on the bake into a measurement receipt. `target_dims_mm` and its tolerances come from the independent contract. An observed dimension adopted as a provisional input must retain that provenance and cannot prove fidelity to an unknown original. 3. Ring probes belong **1.3–1.5 mm inside** the surface along the hole axis. A probe placed on the surface plane returns 0/24 hits and the gate reports a bore that is not there (2026-09-06: one wasted gate run). 4. Union solids that overlap (hinge shells, boss + wall) before measuring — `expected_shells` counts what the STL will contain, and two intersecting bodies are still 2 shells until they are joined. 5. Inspect sampling coverage. Checker 1.0.2 uses the normal 0.3 mm² threshold whenever eligible triangles exist; only an empty eligible set enables the all-positive-face fallback. Empty/degenerate geometry still fails. Mixed large/small faces can still hide thin regions: add a targeted check. Never remove `min_wall_mm` or widen tolerance merely to pass this screen. 6. A keyed hole declares `keyed_flat_mm` + `keyed_flat_dir`; never widen `tol_mm` so a D-profile passes a round-diameter check. 7. Re-measure and invalidate affected reports after geometry changes. Preserve valid authored requirements; revise them only for a documented design change, not to match a failed result. ## Articulated task Trigger: linked joints, tool swaps, grasping or task demonstrations. Load `40-animation/animation-fcurves.md`, `70-cad-precision-robotics/robotics-urdf-mechanisms.md` and their declared dependencies. 1. Define joint frames/axes/limits and descendants; retain separate removable parts. Derive end-effector/grip datum from actual native transforms and compare analytic FK/IK against evaluated scene transforms. 2. Check one real hand interaction early: open approach, close, lift and release. Distinguish rigid jaw collisions, allowed pad contact, numerical residue and modeled gaps. Props may be designed for a declared task; do not imply the gripper handles arbitrary objects. 3. Map requested abilities to story events; produce a short animatic and representative event poses before expensive render. Rear placement through yaw is not the same as a backward shoulder bend; record coverage honestly. 4. Check path poses, camera envelope, attachment/release continuity and final supports. Record contact exceptions, sampling interval and predicate limits; use continuous/solid tests when the claim requires them. 5. Preserve separate performance/physics status. A keyed relative payload transform proves authored alignment, not friction, grip force, holding torque or real controller behavior. Arm examples: [timing plan](../../../../builds/robot-arm-original-refined/scripts/plan-grouped-timing.py) (pure data before any scene edit), [scene build](../../../../builds/robot-arm-print-assembly/scripts/build-assembly.py), [contact screen](../../../../builds/robot-arm-original-refined/scripts/diagnose-subassembly-overlap.py), [presentation check](../../../../builds/robot-arm-original-refined/scripts/check-refined-scene.py). These are artifact-specific examples, not generic APIs. The contact screen samples evaluated surfaces at chosen frames only; read its JSON as well as its exit status. Do not run these builders against a different/live file without reviewing their scene ownership and input assumptions. ## Assembly and exploded views Use [assembly sequences](assembly-sequences.md) for removable-part films: dependency graph, separated waiting poses, swept insertion, phase-bound contact exceptions and short animatic before full render. Joint range demos and assembly paths are separate verification scopes. ## Mechanical evidence Trigger: printable, functional, load-bearing, removable hardware or thermal duty. Load `60-pipeline/3d-printing.md` and relevant `70-cad-precision-robotics/` files. - Start with payload excluding tool, reach, hold duration, motion rates, material/process and actuator dimensions/continuous ratings. Obtain exact source drawings and distinguish rated/continuous evidence from stall torque. Do not infer unseen mounting geometry from a product render. - Keep a component register for printed/purchased/metal parts and a dependency map: geometry → mass/centre of mass → joint loads → actuator/thermal/retention evidence. Clearance edits can change structural sections even if topology remains closed. - Check wall/fit/fastener engagement, real output adapters, access/assembly, range, anchoring and cabling with predicates appropriate to each. A surface intersection screen is neither a solid containment check nor a continuous sweep. - Export separated fit prototypes with stated units and revision, then re-import/check actual files in a fresh process. Printing, fit trials and loaded thermal/strength tests remain independent release gates. - Carry physical blockers explicitly through film/export delivery. No visual-only acceptance can downgrade a user-approved payload/duty requirement. Arm reference: [mesh audit](../../../../builds/robot-arm-print-assembly/reports/mesh-audit.json) and [export check](../../../../builds/robot-arm-print-assembly/reports/export-check.json), with the release status in the [build README](../../../../builds/robot-arm-print-assembly/README.md). This arm remains blocked for manufacture; closed meshes and a checked geometry package do not certify fit, retention or load. ## Render delivery Trigger: animation, batch rendering or exported media. Load `30-lighting-render/render-engines.md`, `30-lighting-render/compositing-output.md` and the relevant export/product-shot KB. Use the scene's established working profile first. If tuning is justified, declare one metric, same representative frames, quality guards, one variable and a trial cap before comparing. GPU warmup, cold-start time and concurrent processes must not be mixed into a claimed speedup. Freeze input file, scene, renderer/device, samples/denoiser, resolution, camera, fps/frame range and script identity. Current arm scripts support manual ranges; automatic validated resume is still E4. Reuse frames only when this input identity matches and each image is complete. Changed geometry/camera/lighting starts a new frame directory. A delay alone is not proof a frame failed. Render raw images, process optional overlays separately, then encode. Before using an encoder filter, inspect local availability. Verify frame count, dimensions, duration/fps, decode errors and representative decoded frames; watch motion for timing/flicker when making those quality claims. Delivery clean versus annotated follows this task's brief, not a global no-caption rule. Arm examples: [renderer](../../../../builds/robot-arm-print-assembly/scripts/render-media.py), [video verifier](../../../../builds/robot-arm-original-refined/scripts/finalize-refined-video.py), [final check](../../../../builds/robot-arm-original-refined/reports/media-check.json). That delivery encoded 3020 raw PNGs at 960x720/24 fps without overlays. Its settings are an example, not a universal quality target. ## Revision-bound acceptance Reports carry artifact identity, scene, checker/config, coverage, exclusions, observed result, review evidence and separate media/motion/fit/manufacture status. Native pipeline/review tools and the CK-001 package/qualification consumers enforce their own declared schemas. They are not a universal cross-domain release checker. Negative review example: media PASS + sampled-surface PASS + changed geometry + unresolved torque must remain manufacture BLOCKED. Reject inherited geometry-dependent approvals from the earlier revision. For current reports without identity fields, compare saved source/timing and explicitly disclose the weaker provenance; never fabricate missing hashes. ## Product and manufacturing follow-through Use `docs/product-workflow-template.md` to turn a request into stage exits and a closure ledger. Route uncertain measurements through `knowledge/60-pipeline/geometry-diagnostic-workflow.md`; route physical, electrical and process blockers through `knowledge/60-pipeline/manufacturing-evidence-workflow.md`. Final-resolution rendering/export uses `knowledge/60-pipeline/native-render-delivery.md`. These procedures consolidate actual CK-001 failures and retain each test's scope.README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/jangtrinh-design-os-3d-blender-agents-skills-blender-agent-core.md