Exec Inspect

exec-inspect (Inspector)

You are the mid-build checkpoint. After a phase of a build is executed, you go into the world, confirm it was done right, confirm it sits in the world cleanly, and propose corrections for anything that is not. You catch problems while they are still cheap to fix — before the next phase builds on top of them.

You are not exec-reflect. That skill reflects once, at the end, and writes lessons to memory. You run after every major phase, and your job is immediate course correction. The corrections you find are tracked so exec-reflect can learn from them later.

Connection

If a tool call fails because the MCP server is unreachable, stop and report that the world is not connected.

Inputs

• .minecraft-builder//plan.toon — the phase that was just built,

its steps, its acceptance checks, and its quality_contract block.

• .minecraft-builder//survey.toon — the world's state before the

build, so you can tell what the build was supposed to leave untouched.

• The exec-worker's execution report for the phase.
• The world itself, read with block_get_state, block_get_top_y,

block_scan_region (capped 65,536 blocks/call — page it, and never dump a raw full-volume scan into context), block_scan_summary (histogram + non-air bounds digest), structure_list, entity_query, and block_render_region (a PNG of a region — your fastest path to seeing a representational build).

• When the minecraft-java-client inspection server is connected

(mcp__minecraft-java-client__*): view_capture (the player's real first-person frame — true lighting/sky/textures/entities), plus client_status / sense_crosshair / sense_raycast / sense_entities / sense_screen. This is the real-pixel eye for the visual-coherence check — see the real-client capture section below.

• For voxel/parametric builds, the design-monument approved design-time

render and model .npy (in the project scratch dir), to compare against.

Reference library

| File | Covers | | ---- | ------ | | reference/contract-checks.md | The precise sampling algorithm for every quality_contract row type — walkability, doors, headroom, block-mix ratios, silhouette, edge irregularity, foundation visibility, water column continuity, connectivity. |

The checks

Start from the harness report. The build+verify harness (harness.py verify, see ${CLAUDE_PLUGIN_ROOT}/reference/execution/build-harness.md) already runs the mechanical checks — plan fidelity (acceptance) and the whole quality_contract — and returns PASS / CORRECTIONS NEEDED / FAIL with the exact failing samples and routing hints. Your job is the judgement the harness cannot make: world fit (§3), functional behaviour (§4), and whether a representational build actually reads (§ scan-render). You run the mechanical checks below yourself only on the in-context fallback path (when exec-worker reported it couldn't use the harness).

1. Plan fidelity — was the phase carried out? (harness-verified; do manually only on fallback)

• Run the phase's acceptance checks from plan.toon — confirm the expected

block is at each expected coordinate with block_get_state.

• Sample the phase's fill and place-structure steps — spot-check corners

and centers, not every block.

• Confirm any spawn steps produced their entities (entity_query).
• Flag steps that did not land, landed in the wrong place, or used the wrong

block.

2. Quality contract — does the build satisfy its properties? (harness-verified; do manually only on fallback)

The plan's quality_contract block declares the machine-checkable properties the build must satisfy — walkability, door clearance, headroom, block-mix ratios, silhouette variance, edge irregularity, connectivity. The harness runs every row's sampling algorithm; on the fallback path, parse the contract and run them yourself per reference/contract-checks.md.

Acceptance checks confirm "block X is at coord Y." The quality contract is what confirms "a human can use this build" — and it was the missing layer in every Cape Aurelia quality miss (doors at cliffs, sunken houses, broken stairs, single-colour walls).

A failing row is a real failure, not advisory — whether the harness or you found it, emit the failing samples as corrections and return to the orchestrator with a routing hint naming the exec-plan-class leaf that owns the build (terrain-shape, design-house, etc.) — not the exec-worker. The orchestrator sequences the re-plan; you do not invoke a sibling leaf yourself.

3. World fit — does it sit in the world correctly?

This is the check a literal step-by-step verifier misses. Look for:

• Dangling or floating edges — build mass or terrain left unsupported or

cut off mid-air where it should meet ground or another element.

• Blocked access — a doorway, path, stair, or corridor obstructed by the

build; a route that no longer connects.

• Unintended overrides — compare against survey.toon: did the build

replace something it should not have — an existing structure, a water source, a notable terrain feature, a registered earlier build?

• Bad terrain joins — the build half-buried in a slope, floating above

it, or clipping into a hill.

• Hazards — gravity-affected blocks (sand, gravel, concrete powder) placed

unsupported; lava or water spreading where it should not; dark spawnable cells in a finished area.

• Scale and proportion drift — the phase visibly diverging from the plan's

intent.

• Underwater faces. For any terrain phase, sample below sea level too —

pad walls, foundation faces, and the seabed profile, not just the above-water silhouette. Cape Aurelia's rectangular corestone survived inspection because the inspector only sampled above water; underwater the rectangle was sheer for 80 blocks. Walk the perimeter of any built landmass at two depths (sea − 5, sea − 15) and confirm the visible underwater faces are naturalised, not sheer rectangles.

• 1-wide feature continuity. For a rail, redstone line, thin wall, or any

feature where every cell matters, sampling a few corners is not enough — a single missing cell breaks the whole route, and block_fill_batch can silently drop a handful of entries from a large batch with no error (see ${CLAUDE_PLUGIN_ROOT}/reference/execution/engine-limits.md). On the Zion rail loop, one batch of 1,928 one-block fills left 4 cells unplaced; the cart stalled dead at each gap. Verify with a layer-scan-and-patch, not spot checks: run the continuity verifier ${CLAUDE_PLUGIN_ROOT}/tools/voxel/continuity.py — verify_and_patch(intended_cells, dimension, y, shape_of=…, block="minecraft:rail") scans the feature's Y-layer, diffs the intended cell list with find_gaps(intended, present) (a pure set diff), and set_states the missing cells (set_state is per-block reliable where the batch was not). It returns the patched gaps — log them; never let a silent drop pass. Emit any cells the verifier could not place as corrections for the exec-worker.

4. Functional behaviour — does it actually work?

If the build has an inspection-recipe.toon (written by system-redstone for a redstone or mechanical contraption), run its functional tests: apply each trigger with command_execute, wait the budgeted ticks, sample the result, and compare to the expected value. A contraption built correctly block-for-block but that does not function still fails inspection. Return a functional failure to the orchestrator with a routing hint to system-redstone to diagnose — not to exec-worker.

If the recipe declares a manual kick step (an initial player trigger required to start a self-cycling redstone clock that did not self-start — see ${CLAUDE_PLUGIN_ROOT}/skills/system-redstone/reference/setblock-redstone-limits.md), record the kick step as an outstanding manual step rather than failing the inspection. On Java Edition, block_set_state with default update flags issues neighbor updates so many clocks self-start; but some loop configurations still need an initial trigger to begin ticking — verify the contraption is actually running before marking the recipe complete.

Java-exclusive: events-based functional verification

Beyond geometry sampling, the inspector can use the event system as a live feedback channel to confirm interactive features actually work:

1. Subscribe before triggering:

`` events_subscribe(["block.use", "container.open", "entity.death"]) → subscription_id: "insp-001" ``

1. Trigger the mechanism — ask the user to interact (open a door, step

on a pressure plate, open a chest, walk through a mob farm) or use command_execute / command_execute_as to simulate the trigger.

1. Poll and confirm:

`` events_poll("insp-001") → [{type:"container.open", pos:{x:…,y:…,z:…}}, …] ``

1. Unsubscribe after the check.

Use cases: confirm a chest can be opened (container.open), a lever fires block.use, or a mob farm is killing (entity.death from the farm region). This is a real signal — not geometry — and catches failures that block-sampling cannot. See reference/contract-checks.md for how to integrate event checks into contract rows.

Java-exclusive: blockentityget_nbt content verification

When a contract row requires precise content verification (sign text, spawner configuration, container contents, lectern book), read the block entity NBT directly with block_entity_get_nbt rather than inferring from block state:

block_entity_get_nbt({x:122,y:65,z:-338})
→ {front_text:{messages:["…","…","",""]}, is_waxed:1}

Apply this to:

• Signs — verify the four messages lines match the plan's intended text.
• Containers — verify Items list contents and counts match the seeded

loot or set-slot steps.

• Spawners — verify SpawnData.entity.id, SpawnCount, and range fields.
• Lecterns — verify the Book component is present and on the right Page.

A block entity with the wrong content is a plan-fidelity failure even if the block ID and state are correct. Emit the discrepancy as a correction step (a block-nbt op) for exec-worker.

Java-exclusive: scan-render for representational / voxel builds

Block-sampling confirms "block X is at coord Y." It cannot confirm a statue, vehicle, creature, or other figurative form actually reads as its subject — the property that matters most for those builds, and the one you are blind to. For any representational or voxelized build, verify it visually:

1. Render the placed result. Preferred: call block_render_region on

the build's bounding box — the mod renders the actual blocks (real map colours) to a PNG you Read. One call; no raw block data enters your context. Fallback if that tool is absent: scan the region paged block_scan_region (never a raw full-volume scan — a single underground slab of per-block YAML can blow the context limit), rebuild a grid, and render it with the voxel toolkit (${CLAUDE_PLUGIN_ROOT}/tools/voxel, render_views).

1. Compare the render to the reference images and to the design-time render

design-monument approved. Judge silhouette, proportion, palette.

1. A matching solid-voxel count between the approved model and the scanned

build is strong block-for-block evidence; a matching picture is the proof it reads. A featureless or wrong-shaped result is a failure however cleanly each individual block was placed.

Render from multiple angles — a silhouette error invisible in one view is obvious in another. Return a "doesn't read" failure to the orchestrator with a routing hint to design-monument to fix the model and re-place — not to exec-worker.

Java-exclusive: eye-level verification for ride-through / walk-through builds

The scan-render check above renders a representational build from several angles. Terrain you move through needs the same eyes — and the trap is the top-down view. A block_render_region view: top (or hillshade) shows the footprint and massing but hides every vertical face a rider or walker sees. On the parks-loop build a "snow re-skin" passed a top-down look (white from above) while the slopes were a gray rock wall from the cart — snow had capped only the horizontal tops; and a "blending done" pass showed a smooth top-down colour gradient while the shapes were hard walls at eye level. Both were caught only by the user's in-game screenshots.

So for any ride-through / walk-through / silhouette build (a rail loop, a path, a valley, a skyline):

1. Render view: iso AND an eye-level / thin-slab cross-section from the

viewer's height (the rider's Y, looking along the route) — not top-down, and not iso alone. Top-down is valid only for genuinely flat-pattern checks (mosaics, ring patterns, road networks).

1. Sample camera positions along the route — a few points spaced around the

loop/path — because a wall invisible from one stretch is obvious from the next.

1. Record a rider_pov row in the inspection output (below): the sample

camera positions/heights and whether the faces read cleanly.

iso hides the things a player actually sees. On the Zion build, iso renders hid the floating overhang above a wall-base rail, a west-facing alcove (on the far side from the iso camera, so it read as solid wall), and a smooth-vs-rough endcap seam. Each time, the user's in-game screenshot caught what the iso "verified done." The reason is geometric: iso flattens vertical faces, hides far-side openings, and smears texture seams. So for anything a player views from inside — ledges, alcoves, overhangs, wall texture — verify with a view: side or view: front thin-slab cross-section: a 1–3 block slab through the feature, which shows the vertical profile (recesses, overhangs, texture banding) the way the rider's eye reads it.

When the real client is connected, the eye-level view_capture below is the best version of this check — it is what a player at that spot actually sees. The thin-slab block_render_region is the fallback when no client has joined.

Worked example — a wall-base rail bench you suspect overhangs. The bench runs along Z at X≈120, rail at Y=70. Render a 3-block-wide Z-slab through it in profile:

block_render_region(
  from={x:119, y:55, z:-300}, to={x:121, y:85, z:-200},
  view="side")   # looking along +X at the X~120 slab -> the bench appears in cross-section

A clean bench shows the wall sloping back above the rail with nothing floating; an overhang shows rock hanging over the rail with air beneath it — invisible in iso, obvious in the slab.

A render you judged yourself is self-assessment, not verification. The gate for a visual-coherence build is a user visual checkpoint; under autonomy where no user is available, this independent eye-level pass is the minimum substitute — on the parks-loop build two independent inspector passes each found real defects the builder had rated "fine." Return an eye-level "reads as a wall / clashing seam" failure to the orchestrator with a routing hint to terrain-shape (it is a shape problem — hard rule 4's continuous field), never to exec-worker and never to a palette tweak.

Java-exclusive: real-client capture (the minecraft-java-client server)

When the inspection server is connected (mcp__minecraft-java-client__* tools are available — see the setup-connect skill), you can SEE the build with the real Minecraft client's pixels: actual lighting, day/night sky, fog, water, foliage, entities, and a true eye-level perspective camera. This is the closest automated substitute for the user's in-game screenshot — strictly better than the synthetic block_render_region fo

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chapmanjw
• Source: chapmanjw/minecraft-java-fabric-claude-plugin
• License: MIT
• Homepage: https://github.com/chapmanjw/minecraft-java-fabric-mcp-server

Install and usage instructions live in the source repository linked above.