scrapbot-feature-development

name	scrapbot-feature-development
description	Use when adding, changing, documenting, or auditing Scrapbot engine features, public APIs, ECS components, rendering, scripting, native extensions, examples, or project tooling. Covers cross-surface implementation, component documentation, generated types, and verification expectations.

Scrapbot Feature Development

Before Editing

1. Read the relevant roadmap section in README.md, open items in docs/TODO.md, and related ADRs/FDRs.
2. Trace the existing implementation end to end before choosing a design. Prefer established package boundaries and public APIs.
3. Call out material choices when multiple user-visible or architectural options remain. Breaking changes are acceptable, but accidental surface divergence is not.
4. Inspect the worktree and assigned scope. In multi-agent work, keep writers file-disjoint and leave shared registries, generated files, indexes, and integration checks to an explicit integration owner.

Public Surface Audit

For every feature, decide explicitly which layers it affects:

• Core Odin implementation and ECS/runtime behavior.
• Luau runtime bindings and generated Luau declarations.
• Project-local Odin extension wrapper and raw extension ABI.
• Scene/project file parsing and validation.
• Standalone project-resource schemas, UUID references, registry lifetimes, and hot reload.
• CLI behavior and diagnostics.
• Example projects.
• README, TODO, ADRs, FDRs, and documentation website.

Do not assume every feature belongs on every surface. When one surface intentionally trails another, record that decision or follow-up rather than overlooking it.

For project-resource work, keep persistent identity separate from runtime storage: authored resources live outside ECS, scene/project files reference stable UUIDs, registries expose generational handles and versions, and ECS components hold resolved handles. Audit recursive discovery, duplicate/reference validation, disappearance/reappearance, packaging, hot reload, editor create/duplicate/rename/move/delete, reference-aware deletion, Save/Revert/Undo/Redo, and the distinction between authored and transient runtime resources. Lifecycle edits remain in-memory authoring until explicit Save; Save must derive create/write/delete operations from the disk baseline and commit them through the recoverable project transaction.

For ECS UI work, also use the scrapbot-ui-development skill. The editor must remain a consumer of the public UI contract, and a public field is incomplete until every applicable authoring and runtime surface agrees.

For spatial hierarchy work, keep scrapbot.transform.parent UUID-based and local TRS as the only authored pose. Keep display order independent from live ECS storage handles; audit scene-block ordering, structural Save, and Undo/Redo when adding hierarchy reorder behavior. Also audit scene validation, Luau and native writeback, world-transform consumers (render instances, cameras, lights, picking, and gizmos), cycle rejection, parent removal, and world-pose-preserving editor reparent Undo/Redo. Use tests/fixtures/ui/scene-hierarchy.json for the visual tree companion; semantic drags can target the top/center/bottom of destination rows.

Generated Luau Types

When changing built-in components, Luau APIs, query types, or component schemas:

1. Update the canonical type generator in src/scrapbot/component/luau_types.odin.
2. Build the CLI.
3. Run bin/scrapbot check <example> for every affected example.
4. Inspect generated .scrapbot/types/scrapbot.d.luau output and run the Luau analyzer through the normal test suite. The generated state is ignored and must not be hand-edited or committed.

Never hand-edit generated example declarations without changing their generator.

Verification And Documentation

• Add focused unit and integration tests at the changed ownership boundaries.
• Use the scrapbot-testing skill for full-suite, example, WGPU, framegrab, and visual checks.
• Update behavioral FDRs when a feature's supported behavior or design changes.
• Add or amend an ADR only for a durable architectural decision.
• Keep README.md, docs/TODO.md, examples, and the documentation website synchronized with shipped behavior.
• Finish with mise test, git diff --check, and any feature-specific verification.
• When integrating delegated work, review the combined diff rather than trusting per-agent test reports; cross-surface omissions usually appear only at integration time.

Documentation Audits

Treat docs-website/src/content/docs/reference/components.md as the canonical public inventory of engine-provided components. Treat src/scrapbot/component/registry.odin as its source of truth.

When adding, removing, renaming, or changing an engine component:

1. Update the canonical component page with its registry name, public fields, scene name, Luau handle, native descriptor/access pattern, defaults, constraints, ownership, and renderer-only behavior where applicable.
2. Run node .agents/skills/scrapbot-feature-development/scripts/check_component_docs.mjs to catch registry entries missing from the canonical page.
3. Check reference/project-files.md, reference/luau-api.md, guides/native-extensions.md, and guides/ecs-ui.md only for surface-specific behavior. Link to the component page instead of duplicating exhaustive field inventories.
4. Audit both docs/GLOSSARY.md and the public website glossary for stale feature-state language.
5. Build the documentation website with pnpm run build from docs-website/.