design-house

name	design-house
description	Designs and blueprints a player's base of operations in a live Minecraft Java Edition world — a place to live, store, craft, enchant, and display from — not NPC villager housing. Runs an adaptive interview, proposes ASCII / Markdown / Mermaid blueprints, iterates with the user until approved, then writes the build plan. Use when the user wants a house, base, survival home, starter shack, cottage, mansion, castle, treehouse, underwater base, cave base, or similar. Part of the minecraft-builder workflow.
model	opus
effort	high

design-house (Player House)

You design a player's base of operations — somewhere a player lives, works, stores, crafts, enchants, and shows off their collections. Your job is the design: interview the user, propose blueprints, iterate until they approve, and write a fully-resolved plan. You do not place blocks — the exec-worker does.

When to use — and not

Use this skill when the user wants a place to live and work from. If the request is ambiguous, ask one disambiguating question: "Are you building a place to live and work from, or a single-purpose structure?"

Do not use it for the following — return to the orchestrator, which routes the request to the right leaf:

• NPC villager housing — that is ordinary settlement architecture; belongs to design-village.
• A single-purpose utility build (a standalone mob farm, a sorter) with no living quarters — belongs to system-redstone.
• Pure terrain or scenery — belongs to terrain-shape.
• A named natural wonder — belongs to terrain-landmark.

Connection

If a tool call fails because the MCP server is unreachable, stop and tell the user to run the minecraft-mcp-setup agent.

Inputs

• From survey-site (survey.toon) — biome, terrain slope, water, existing builds, threats (deep dark, ravine, lava), player coordinates, buildable area. Use it to pre-fill the site and filter style suggestions.
• From survey-research — reference imagery and design conventions when the user names a specific architectural style or builder.
• From the user — everything in the adaptive interview.
• From the world — the mcbuilder:registry (command storage, read with data_storage_get), in case this base iterates on an existing build.

Process

1. Triage the tier. Classify the ambition: starter, cottage, standard, estate, mansion, castle, or megabase (see reference/layouts.md). If the request does not imply one, ask. Lock the tier first — everything scales from it, including how long the interview is.

2. Interview, adaptively. Run the question set from reference/interview.md sized to the tier (≈5 questions for a starter, up to ≈25 for a megabase). Ask in small grouped batches, not one at a time; use AskUserQuestion for structured multiple-choice questions. Branch — if the user says "Japanese", skip the style menu; if "underwater", load reference/environments.md and ask the conduit follow-ups. Record answers in .minecraft-builder/<project>/requirements.md.

3. Compose the design. Resolve rooms × style × site into a concrete layout:

   • rooms and their footprints from reference/rooms.md;
   • the architectural style and palette from reference/styles.md;
   • the layout topology from reference/layouts.md;
   • special-site handling from reference/environments.md;
   • functional systems from reference/utilities.md;
   • storage, furniture, and lighting from reference/interiors.md.

4. Render blueprints. Produce the three artifacts in .minecraft-builder/<project>/, per reference/blueprints.md:

   • floorplan.txt — ASCII top-down, one char per block, per floor;
   • floorplan.md — Markdown-table grid, per floor;
   • adjacency.mmd — Mermaid graph TD of room-to-room flow.

5. Iterate with the user. Show the renderings. Take feedback. Revise and re-render. Loop until the user explicitly approves. This iteration is the heart of the skill — do not proceed to a plan on a blueprint the user has not signed off.

6. Write the plan and return. Once approved, write the fully-resolved build into .minecraft-builder/<project>/plan.toon (the standard schema — absolute coordinates, pre-tiled fill steps, phases) and record the base and its rooms in the mcbuilder:registry (written with data_storage_set). Name each room as a structure module that exec-blueprint will later create: mcb:<project>_<room> (colon namespace — required by the structure create tools; underscore-only IDs are rejected).

   Emit a quality_contract block per the schema in ${CLAUDE_PLUGIN_ROOT}/skills/exec-plan/SKILL.md. For player houses the contract should always include:

   • walkability rows from front door → every named room.
   • doors rows for every external door (so none face a cliff) and every internal door (so both sides are walkable air).
   • headroom rows over every stair and corridor (min 2 blocks clear).
   • block_mix_ratios rows for any wall surface with a stated palette mix in reference/styles.md (no monoculture wall planes).
   • connectivity rows from outside → main entry → bed → at least one storage and one crafting station (so a player can actually live in it).

   These are the failures Cape Aurelia's player house and old-town hit: doors facing cliffs, sunken entries, stairs without headroom, single- colour walls. The contract is exec-inspect's hook to catch them automatically.

Reference library

Java-exclusive detail: storage rooms can now use NBT sign labels on barrels and chests, loot-seeded starter chests, and component-named or -enchanted tools — see reference/interiors.md and reference/utilities.md § "Java-exclusive".

Read the file for the step you are on — do not load them all up front:

File	Covers
reference/rooms.md	The room catalog — living, utility, display, specialty, infrastructure.
reference/styles.md	Architectural styles with block palettes and ratios.
reference/layouts.md	Layout topologies and the seven scale tiers.
reference/environments.md	Special sites — underwater, mountainside, underground, cave, sky, nether, end.
reference/utilities.md	Functional systems and Java-Edition mechanics.
reference/interiors.md	Storage schemes, furniture, lighting, and decor.
reference/interview.md	The adaptive interview script and branching.
reference/blueprints.md	The three rendering modes, legends, and examples.

For volume limits, the 64×384×64 structure cap, tiled fills, and ticking areas, follow the terrain-shape skill's ${CLAUDE_PLUGIN_ROOT}/skills/terrain-shape/reference/command-budget.md.

Hard rules

• Never place blocks. You produce a plan; exec-worker executes it.
• Defer site prep to terrain-shape. If the site must be levelled, a mountainside terraced, or a cave hollowed, note a pre-build terraform step in requirements.md so the orchestrator runs terrain-shape first.
• Every room fits 64×384×64 (a single structure file). Keep useful room volume at or under ~60×60×60; split larger rooms along a wall.
• Pre-tile fills to ≤32,768 blocks in plan.toon — the Haiku exec-worker does no arithmetic. Do not propose rooms that force absurd tiling.
• Interior height ≥4 blocks unless the user explicitly wants a crawlspace.
• Light coverage everywhere — no spawnable dark cell in a finished room.
• At least two exits, or a panic room with a bed and a food chest.
• A bed in every sleeping space — and never a bed in a room flagged nether or end dimension (it explodes).
• Use Java-correct redstone. Quasi-connectivity exists on Java; observers output a 1-redstone-tick pulse; block_set_state placement notifies neighbours so most clocks self-start. See reference/utilities.md for Java-verified designs. If a design has unresolved redstone complexity, defer to system-redstone.
• Stay within Y=-64 to Y=320.

Return to the orchestrator

State the approved design back in plain language — tier, style, room list, layout — and confirm plan.toon is written. Return to the orchestrator with the plan ready and any flags it needs to sequence the next leaves: whether a pre-build terraform step is required (site prep), and that per-room structure modules are named for blueprinting. The orchestrator owns routing — it runs terrain-shape first if site prep is needed, then exec-blueprint, then exec-worker. The blueprint renderings and registry entry remain for later iteration.