Living reference: Minecraft build demand coverage and v1.0 readiness matrix

[madawei2699]

Purpose

This is a living reference issue for CraftDAG's Minecraft build-demand coverage.

CraftDAG now has a broad ComponentPlan vocabulary for architecture, monumental builds, and landscape features. Before adding more primitives/components, we need a shared map of:

• common Minecraft build demand categories
• current CraftDAG coverage level
• known gaps
• whether a gap should become a core component, an assembly/template, documentation, diagnostics, or a future module system
• what this implies for CraftDAG v1.0 readiness

This issue should be updated as new samples, components, diagnostics, and redstone/automation modules land.

Why this matters

Without a demand coverage map, it is easy for coding agents and developers to add components opportunistically:

sample is hard to write -> add a new component

That path risks:

• DSL bloat
• LLM prompt explosion
• overlapping components
• validation complexity
• long-term maintenance burden
• domain-specific components that should have been roles, assemblies, or examples

This issue should be read together with:

• docs/COMPONENT_DESIGN_GUIDE.md
• docs/COMPONENT_PLAN_SPEC.md
• Future: Explore redstone module support for functional builds #53 redstone module direction
• Implement first useful verified automation module: ItemSorterSlice #59 first useful verified automation module: ItemSorterSlice
• Create comprehensive LLM authoring pack for ComponentPlan generation #54 LLM authoring pack
• Future: Make CraftDAG toolkit friendly to harness agents #55 harness-agent toolkit

Current coverage snapshot

Approximate coverage levels are intentionally qualitative. They should be revised after new stress samples.

Demand category	Examples	Current coverage	Current strengths	Main gaps	Preferred next action
Survival houses and starter bases	starter house, workshop, mine entrance, nether room	High	RoomShell, Foundation, Platform, Beam, Door, Window, GableRoof, FlatRoof	stairs, vertical circulation, functional storage/automation	Add StairRun; use assemblies for room templates
Castles, walls, medieval villages	castle, tower, gatehouse, bridge, market, tavern	High	RoomShell, Platform, Beam, RailingRun, ArcadeRun, Repeat, Assembly/Instance	stairs, crenellations, octagonal/circular towers	Prefer StairRun; use Repeat/Assembly for crenellations before adding core component
Large landmarks and monumental builds	Taj Mahal, Titanic, Colosseum, Burj-like tower, Forbidden City, Great Wall	Medium-high	monumental tier, sections, assemblies, TaperedVolume, SteppedTier, VerticalSetbackVolume, ArcadeRun, SupportBracket	domes, radial/ring forms, grand stairs, richer diagnostics	Add SteppedDome after StairRun; evaluate ring/radial primitives cautiously
Modern buildings and city blocks	skyscraper, apartment, mall, office, subway station	Medium-high	VerticalSetbackVolume, Compartment, Corridor, Window, Section, Repeat	facade grids, floor stacks, stair/elevator cores, city/block layout	First try Repeat/Assembly/Section; consider FacadeGrid only after repeated evidence
Interiors and underground bases	storage rooms, corridors, dungeons, ship decks, compartments	Medium-high	Compartment, Corridor, Platform, Section, Assembly, role metadata	StairRun, StairCore, RoomGrid/CabinGrid, vertical shafts	Add StairRun; defer StairCore/RoomGrid until samples prove need
Landscape and nature	Japanese garden, pond, path, sakura tree, rock garden	Medium-high	TreeCanopy, OrganicPatch, PathRun, RockCluster	terrain slopes, waterfalls, hedges/screens, biome-scale terrain	Use current landscape primitives first; defer SlopePatch/HedgeRun until samples demand them
Redstone and automation	item sorter, auto smelter, piston door, farm hub, storage system	Low	Architectural host structures can be built	block states, block entities/NBT, version target, module validation, smoke tests	Follow #53 and #59; do not mix arbitrary redstone into general ComponentPlan yet
Sculptures, organic creatures, pixel art	dragon, statue, logo, giant sword, organic terrain sculpture	Low-medium	Some massing possible with TaperedVolume/RockCluster/OrganicPatch	freeform voxels, image/heightmap/mesh import, curved organic forms	Future adapter/tooling; do not pollute core ComponentPlan with sculpture-specific components

Current ComponentPlan capabilities

CraftDAG currently has strong coverage for human-built architectural structures:

• base slabs and platforms
• hollow rooms and compartments
• corridors
• roofs and covers
• doors, windows, openings, portals
• repeated details
• assemblies and instances
• sectioned monumental builds
• large-form shape approximations
• railings, arcades, support brackets
• trees, patches, paths, and rocks
• structural intent metadata
• validation diagnostics with repair hints

This is enough to generate many non-redstone Minecraft builds as recognizable, inspectable, and exportable ComponentPlans.

Main remaining gaps before v1.0

1. Vertical circulation

Most multi-level builds need stairs, ramps, ladders, or shafts. Today these can be hand-authored with platforms and repeats, but that is verbose and error-prone for agents.

Likely core addition:

StairRun

Possible future templates/components only if needed:

StairCore
LadderShaft
ElevatorShaft

2. Dome and radial landmark forms

Large religious, palace, stadium, tower, and circular builds need better radial approximations.

Likely future addition:

SteppedDome

Cautious evaluation:

OctagonalRing / RingWall
RadialArray

Avoid landmark-specific forms such as TajMahalDome.

3. Redstone/automation module system

This is a separate capability area, not just another architectural primitive.

Needs:

• redstone block-state support
• block entity / inventory NBT support
• version target
• module-specific validation
• initialization instructions
• real Minecraft smoke-test notes

Follow #53 and #59.

4. Agent-facing authoring and repair loop maturity

As the component set grows, docs and diagnostics become as important as primitives.

Needs:

• docs/llm.txt / authoring pack maturity
• examples by pattern
• invalid anti-pattern examples
• diagnostics JSON with repair hints
• clear guidance on when not to add components

Follow #54 and #55.

5. Release discipline and compatibility

Before v1.0, the public ComponentPlan vocabulary should stabilize enough that examples and downstream tools do not constantly churn.

Needs:

• versioned schema semantics
• compatibility policy
• fixture coverage for all public components
• documented deprecation policy for component names/options

Component admission guidance

Before creating a new component issue, use docs/COMPONENT_DESIGN_GUIDE.md and answer:

1. Which common Minecraft demand category does this serve?
2. Is this pattern common across multiple build families?
3. Why are existing components, role metadata, Repeat, Assembly, or Section insufficient?
4. What overlap exists with current components?
5. Can the component expand deterministically from bounded integer parameters?
6. Can validation catch common errors?
7. Can diagnostics give useful repair hints?
8. What sample proves the component reduces authoring burden?
9. What docs/LLM guidance must be updated?
10. Does this move CraftDAG closer to v1.0, or just make one showcase easier?

Suggested next capability issues

Based on current coverage, the next architectural gaps worth considering are:

1. StairRun for vertical circulation in multi-level builds.
2. SteppedDome / ring-form evaluation for radial landmark forms.

These should be added only if scoped with examples, tests, docs, and anti-goals.

v1.0 readiness definition draft

CraftDAG should be considered closer to v1.0 when it can reliably support these workflows:

Architecture

• generate small/medium/large/monumental non-redstone builds
• use sections and assemblies for large builds
• cover common survival, medieval, modern, landmark, interior, and landscape scenarios
• export VoxelPlan and schematics reliably
• produce material and layer guides

Authoring

• LLM/harness agents can read a compact authoring pack and create valid plans
• diagnostics are machine-readable and repairable
• component vocabulary is stable and documented
• new component additions follow design governance

Validation

• bounds, budget, references, attachments, covers, repeats, sections, and structural support are validated
• examples cover both valid and invalid patterns
• tests protect public component behavior

Functional builds

• at least one useful verified automation module exists, likely ItemSorterSlice
• redstone/automation remains module-verified rather than arbitrary circuit synthesis

Non-goals for this issue

• Do not implement components directly here.
• Do not use this issue to approve every new component automatically.
• Do not treat coverage percentages as exact metrics.
• Do not expand ComponentPlan into a biome/theme/landmark catalog.

Maintenance note

Update this issue whenever:

• a new public ComponentPlan component lands
• a major sample exposes a new repeated authoring pain
• a component is deprecated or renamed
• a redstone/automation module changes coverage
• v1.0 readiness criteria are clarified

[madawei2699]

Updated coverage work is now in PR #92.

Added stress samples:

• xi-an-bell-tower-study: square masonry pedestal, cross passages, stacked timber halls, wide eaves, roof finial
• giant-wild-goose-pagoda-study: tall vertical setback massing, repeated eave levels, high pagoda silhouette

Added docs/BUILD_COVERAGE_MATRIX.md with separate authoring/compiler/diagnostic coverage, plus current support diagnostic counts for all ComponentPlan examples.

Main finding: current ComponentPlan authoring/compile coverage is solid for these large landmarks, but support diagnostics are still noisy for dome tiers, broad eaves, ship/tower tapering, and tall VerticalSetbackVolume forms. This should be treated as pre-redstone hardening context before #59.

[madawei2699]

Correction after visual review of PR #92:

The first Giant Wild Goose Pagoda stress sample was not acceptable: the upper roof was visibly floating, and the tower was not meaningfully enterable/walkable. The PR has been updated to use seven shrinking walkable RoomShell levels with entries and interior StairRun segments. Disconnected block diagnostics for that sample are now 0.

New pre-redstone follow-up issues created from this review:

• Improve support diagnostics for agent quality gates #93 Improve support diagnostics for agent quality gates
• Add walkable multi-level floor stack authoring support #94 Add walkable multi-level floor stack authoring support
• Add build artifact manifest and SEO quality gate #95 Add build artifact manifest and SEO quality gate

This keeps #81 honest: current architectural coverage is useful, but SEO/tool pages need visual review, export verification, better quality summaries, and more compact multi-level authoring before scaling content.

[madawei2699]

Design boundary update: detail blocks should not become core ComponentPlan components

Add this to the coverage/readiness interpretation:

CraftDAG should not try to model every Minecraft object or decorative block as a semantic ComponentPlan component.

Examples that should generally not become core components:

Candle
Campfire
Lantern
FlowerPot
Banner
Chain
ArmorStand
CarpetPattern
BookshelfDecoration
BarrelStack
HangingVines
GrassNoise
RiverbankDetail

The distinction should be:

VoxelPlan/exporters may carry detailed Minecraft block IDs and states.
ComponentPlan should stay focused on structure-level, bounded, reusable components.

Detail should usually come from:

imported schematic assets
MinePilot prefabs/templates
manual curation
optional broad post-processing detail layers

rather than expanding the core ComponentPlan schema into a block catalog.

See #108 for the dedicated design boundary issue.