scrapbot-feature-development
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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-07
- Stars
- ★ 6
- Forks
- 1
01 前言 Front Matter
- 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.
02 资源文件 1
- 脚本scripts/check_component_docs.mjs1.7 KB
03 SKILL.md 正文
Scrapbot Feature Development
Before Editing
- Read the relevant roadmap section in
README.md, open items indocs/TODO.md, and related ADRs/FDRs. - Trace the existing implementation end to end before choosing a design. Prefer established package boundaries and public APIs.
- Call out material choices when multiple user-visible or architectural options remain. Breaking changes are acceptable, but accidental surface divergence is not.
- 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.
- Read
docs/architecture/INDEX.mdand use thescrapbot-architecture-inventoryskill when the work changes systems, components, ownership or invalidation, major data flows, or package responsibilities.
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.
Project-resource, playback, persistence, world-replacement, and hot-reload changes must update docs/architecture/resources.md and/or docs/architecture/lifecycle.md. Record actual rollback boundaries: do not describe a replacement as transactional when a registry or other owner mutates before candidate validation and is not restored on failure.
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:
- Update the canonical type generator in
src/scrapbot/component/luau_types.odin. - Build the CLI.
- Run
bin/scrapbot check <example>for every affected example. - Run
mise luau-workspace-typeswhen an example schema or shared Luau API changes. It refreshes the tracked repository-wide declaration aggregate used by the root VS Code workspace; project-local generated state remains ignored and must not be hand-edited or committed. - Inspect generated
.scrapbot/types/scrapbot.d.luauoutput and run the Luau analyzer through the normal test suite.
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-testingskill for full-suite, example, WGPU, framegrab, and visual checks. - Renderer work whose output can change across frames is incomplete until a consecutive capture range has been inspected. A successful final frame does not verify streaming, LOD, temporal history, animation, hot reload, or other transitional behavior.
- 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. - Keep
docs/architecture/synchronized with architectural surfaces and run its inventory audit when applicable. - 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 src/scrapbot/component/registry.odin as the source of truth for machine component facts. Treat docs/architecture/components.md as the complete engineering directory and docs-website/src/content/docs/reference/components.md as the canonical public usage reference. Do not duplicate internal ownership/invalidation prose into the website or exhaustive public field/default documentation into the architecture directory.
When adding, removing, renaming, or changing an engine component:
- 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.
- Update the component's standardized entry in
docs/architecture/components.mdwhen its storage, lifecycle, producers, consumers, invalidation, surfaces, or implementation/test anchors change. - Run both
node .agents/skills/scrapbot-feature-development/scripts/check_component_docs.mjsandnode .agents/skills/scrapbot-architecture-inventory/scripts/check_inventory.mjs. - Check
reference/project-files.md,reference/luau-api.md,guides/native-extensions.md, andguides/ecs-ui.mdonly for surface-specific behavior. Link to the component page instead of duplicating exhaustive field inventories. - Audit both
docs/GLOSSARY.mdand the public website glossary for stale feature-state language. - Build the documentation website with
pnpm run buildfromdocs-website/.
04 同仓库更多 Skills
todo-list
Establish and maintain a lightweight project task list in docs/TODO.md. Use when the user asks to track todos, maintain a TODO.md, preserve follow-up work while implementing features, or keep an agent-readable list of outstanding project tasks.
technical-writing
Invoke this skill whenever you need to create, update, review, restructure, or audit technical documentation such as README files, user manuals, API documentation, architecture notes, setup guides, troubleshooting guides, or developer docs. Use it to align docs with source code, existing project conventions, and the intended audience.
scrapbot-ui-development
Use when adding, changing, debugging, reviewing, or documenting Scrapbot ECS UI components, layout, controls, interaction state, styling, reconciliation, project TOML UI, Luau UI APIs, native UI payloads, or editor UI composition. Enforces one reusable public UI contract across projects and the editor.
scrapbot-testing
Use when testing or verifying Scrapbot changes, especially scene persistence and authoring savepoints, lifecycle integrity, CLI behavior, generated Luau types, example projects, ECS rendering, WGPU smoke tests, headless framegrabs, PNG artifacts, documentation builds, or before committing.
scrapbot-architecture-inventory
Maintain and audit Scrapbot's source-oriented architecture inventory in docs/architecture. Use when adding, removing, renaming, or changing engine systems, component registrations, component ownership/lifecycle, project resources, runtime registries, UUID/handle/version semantics, load/spawn/playback/persistence/hot-reload lifecycles, authoritative or derived state, dirty queues/revisions/caches, frame/render/UI data flows, package responsibilities, or architectural documentation; also use for architecture overviews and inventory drift audits.
odin-language
Work effectively in Odin programming language codebases. Use when reading, writing, reviewing, testing, refactoring, or documenting `.odin` files; when choosing idiomatic Odin syntax, packages, allocators, error handling, foreign bindings, tests, build flags, or data-oriented designs; or when translating concepts from C, C++, Go, Lua, or scripting languages into Odin.