HZplan

View saved version →

---
name: hzplan-build-floor-plan
description: Create a usable new HZplan floor plan from user-supplied dimensions, a sketch, a reference image, or another plan while verifying structure, circulation, openings, and furniture in stages. Use when the user asks to build, draw, recreate, plan, furnish, or lay out a new home or storey in HZplan. Do not use for automatic image conversion or a narrow change to an existing HZplan plan; use the dedicated import workflow or hzplan-edit-floor-plan-safely instead.
---

# Build a HZplan floor plan

Build from evidence, expose uncertainty, and verify the structural plan before adding decorative detail. The user's explicit instructions take precedence over this workflow.

## Establish the source of truth

1. Identify whether the layout comes from written dimensions, a user-supplied image, a sketch, or an explicitly approximate brief.
2. Inspect every supplied image before making a plan write. Distinguish geometry that is visible or measured from geometry that is inferred.
3. If the user requests an accurate reconstruction of a named real building, fictional set, or other known place without supplying layout evidence, do not construct it from memory. Ask for a plan image or dimensions, or ask whether an approximate interpretation is acceptable.
4. Use only user-supplied, licensed, or public-domain plan inputs. Never scrape listing sites or other third-party sources for floor plans.
5. State a compact implementation plan and any material assumptions before the first write. Ask a question only when missing information would materially change the layout; otherwise make conservative, disclosed assumptions and proceed.
6. Respect requested review gates. If the user asks to approve walls and openings before furniture, stop at that boundary.

## Initialize authoring

1. Call `get_authoring_guide` once at the start of the authoring run. Treat it as the canonical source for current entity types, predicates, anchors, and geometry rules; do not rely on remembered syntax.
2. Call `create_plan`, then `create_storey` for each requested floor.
3. Author a fixed storey `size_mm` only when reliable dimensions define the full extent. Otherwise let the storey derive its extent from its walls.
4. Pass `storey_id` explicitly on every storey-scoped call. Work on one storey per batch.

## Plan for use, not only geometry

1. When the brief leaves room proportions, openings, circulation, or furniture placement to your judgement, read `references/room-planning-basics.md` before choosing the layout.
2. Treat its non-obstruction and circulation rules as default invariants. Treat its dimensions and room patterns as conservative design defaults, not universal regulations; explicit user needs and the applicable local standard take precedence.
3. Decide intended room connectivity and main circulation before placing openings. Preserve useful wall runs, then check door swings and approaches against furniture, fixtures, and other doors.
4. Place furniture only when realistic footprints and use zones fit. If the requested contents cannot fit without blocking access or overlapping working space, explain the conflict rather than forcing an unusable layout.

## Build the structure in stages

1. Create exterior and interior walls before openings, rooms, furniture, fixtures, or finishes.
2. Prefer `upsert_entities` for a coherent wall batch. Check the entire solver result; a rejected atomic batch persisted nothing.
3. Omit entity IDs when entities are independent and server-minted IDs are sufficient. Supply clear local IDs when an atomic batch must express relationships among entities created together. In both cases, treat every returned ID as authoritative. An ID-less create is not idempotent: if its outcome is uncertain, re-read the storey before retrying so the retry cannot create duplicates.
4. Create doors, windows, and other openings only after their hosting walls exist. Use returned wall IDs rather than guessed identifiers.
5. Inspect each write result, including any `normalized_anchors`, then call `get_storey_plan` after each structural stage. Use returned IDs, `resolved_geometry`, compass sides, inner faces, and solved dimensions to identify what was actually created.
6. Use `render_storey_widget` when visual comparison materially helps. Compare the result with the source before moving to the next stage.
7. When the solver reports an infeasible, ambiguous, or overlapping layout, use its diagnostics to repair the smallest responsible batch. For attachment errors, use the valid pairings or exact replacement assertion returned by HZplan instead of guessing. Do not conceal the failure or continue layering entities onto an invalid structure.

## Name and check spaces

1. Call `get_plan_topology` after walls and openings define enclosed areas.
2. Use each topology node's returned center with `name_space_at_point` to name rooms. Do not represent rooms as objects.
3. Check that the intended entrance and internal circulation are represented by openings and that expected rooms are connected. Report uncertain or disconnected areas instead of inventing access.

## Add later layers only when in scope

1. Add furniture, fixtures, and surface finishes only after the structural layout is verified, unless the user explicitly requested a one-pass approximation.
2. Keep later work in small, reviewable room-level batches. After furniture placement, inspect the render for blocked openings, broken circulation, inaccessible storage, and unrealistic use zones.
3. Do not call `generate_object_3d` merely because an object was added. Start slow or quota-consuming generation only when the user explicitly requests it, and set the expectation that it may take several minutes.

For follow-up changes to an existing plan, use the state-preserving workflow in `hzplan-edit-floor-plan-safely` when it is available.

## Complete the handoff

Before claiming completion:

- Confirm the intended storeys, walls, and openings exist.
- Confirm solver validation is acceptable.
- Confirm room names and topology match the requested layout when rooms were in scope.
- Confirm openings, circulation, and furniture remain usable when HZplan was asked to make those design choices.
- Provide the relevant plan or render link.
- Summarize assumptions and unresolved discrepancies.
- Describe the result as a design representation, never as professional building-code certification.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: hzplan-edit-floor-plan-safely
description: Make precise, usable, verified changes to an existing HZplan plan without dropping unrelated geometry, breaking circulation, or editing the wrong floor. Use when the user asks to move, resize, reconnect, rename, restyle, replace, or delete existing walls, openings, rooms, furniture, fixtures, finishes, illustrations, 3D assignments, or generated 3D assets. Do not use to construct a new plan from scratch; use hzplan-build-floor-plan instead.
---

# Edit a HZplan floor plan safely

Inspect before writing, preserve stated invariants, and verify the solved result. The user's explicit instructions take precedence over this workflow.

## Resolve the target

1. Resolve the plan and storey before changing anything. Use `list_plans` or `get_plan` only when necessary, then call `get_storey_plan` for the target floor.
2. Pass `storey_id` explicitly on every storey-scoped read and write, even when the server could infer it.
3. Treat IDs returned by HZplan as authoritative. Never infer an entity's floor from its local ID.
4. For object edits, call `get_object` when the current assertions or solved placement are not already present in the storey read.
5. Resolve human descriptions such as "bottom wall" from `resolved_geometry`, compass side, dimensions, and adjacency. If more than one entity still matches, ask the user to disambiguate before writing.
6. For geometry, attachment, opening, or surface-finish edits, call `get_authoring_guide` before writing. Skip it only when a dedicated simple tool's current schema fully defines the requested change.

## Preserve the user's invariants

1. Translate the request into a short list of targeted entities, requested changes, and properties that must remain fixed.
2. Do not alter a fixed length, width, height, host, gap, or attachment unless the user requested it or the change is required for feasibility. Disclose any required collateral change before applying it.
3. Use real millimetres directly. Never multiply or divide dimensions by the storey's informational scale factor.
4. Avoid moving unrelated geometry to make a requested edit appear successful.

## Protect spatial usability

1. When choosing a new opening, room arrangement, or furniture position rather than applying exact user-supplied geometry, read `references/room-planning-basics.md` before writing.
2. Preserve clear door openings and swings, continuous circulation, access to important windows, and working space in front of furniture, appliances, storage, and fixtures unless the user explicitly accepts a disclosed tradeoff.
3. Treat the reference's dimensions and room patterns as conservative defaults, not proof of compliance. For an accessibility or regulatory request, use the applicable jurisdiction and user requirements and do not claim certification.
4. If the requested edit cannot fit while preserving these conditions, report the conflict and ask which constraint may change rather than moving unrelated entities or creating an overlap.

## Choose the narrowest write

- Use `set_entity_assertions` to replace or add individual geometry assertions on an existing entity while preserving all other assertions.
- Use `remove_entity_assertions` to remove specific assertion keys while preserving the remainder.
- Use `set_entity_attributes` for passive metadata that must not affect the solver.
- Use the dedicated object tools for height, feature side, illustration, and existing 3D-asset assignment.
- Use `delete_object_3d_asset` only for an explicit request to remove a generated model. If HZplan reports that plans still reference it, identify those dependencies and ask before detaching them with `set_object_3d_asset`; never alter plans merely to make deletion succeed.
- Use `upsert_entity` for creation or a deliberate full replacement only. Before replacing an existing entity, read it and resend every assertion that must survive; omitted assertions are removed.
- Use `upsert_entities` for a related set of changes that should succeed or fail atomically. Pass the latest `content_version` as `expected_content_version` when available.
- Use deletion tools only for an explicit deletion request. Read and report dependency blockers rather than deleting or relocating additional entities speculatively.

## Apply and recover

1. Prefer one coherent batch for coupled changes and small batches for visually sensitive iteration.
2. Inspect every write result for the returned entity ID, complete assertions, any `normalized_anchors`, `resolved_geometry`, solver state, and content version.
3. If a write conflicts with a newer content version, re-read the storey and remap the requested change before retrying. If an ID-less create has an uncertain outcome, re-read before retrying because a repeated call can create a duplicate.
4. If the solver rejects a change, diagnose the contradictory or missing constraint and repair that cause. For attachment errors, use the valid pairings or exact replacement assertion returned by HZplan instead of guessing. Do not stack unrelated trial edits.
5. Do not start `generate_object_3d` as part of an ordinary furniture edit. Use it only when explicitly requested and explain that generation may take several minutes.

## Verify the result

1. Re-read the affected storey after geometry changes.
2. Use `render_storey_widget` when the change affects placement, size, orientation, openings, or room boundaries. Inspect door swings, passage continuity, window access, furniture use zones, and collisions.
3. Compare the solved result with every requested invariant. For example, if the user fixed a wall at 1000 mm by 600 mm, verify both dimensions and both requested contacts.
4. For room-access changes, call `get_plan_topology` and verify the expected connectivity.
5. If verification reveals an unexpected result, explain it and correct the root constraint before claiming success.

## Complete the handoff

Report:

- Which entities changed and on which storey.
- The resulting solved dimensions or positions relevant to the request.
- Whether solver and topology validation passed.
- A plan or render link when available.
- Any assumption, limitation, or follow-up that remains.

Never claim that the edited plan is professionally certified or fully compliant with building regulations.

Referenced files: 2 — file references are metadata, not package contents.