✨ Scaffold bevy plugin with bevy-0.19 and bevy-upgrade skills

Add plugin skeleton with versioned skill directories, TODO SKILL.md scaffolds with goals for skill-creator, and copy over bevy-skill-research reports from spacecraft into docs/workpad/research/.
2026-07-07 17:52:00 +02:00
parent 8545738a05
commit 325e278af1
13 changed files with 1211 additions and 0 deletions
@@ -0,0 +1 @@
+Bevy game engine skills. The `bevy` skill is the primary implementation helper; `bevy-upgrade` handles version migrations and is invoked by `bevy` when upgrade work is detected.
@@ -0,0 +1,49 @@
+# bevy
+
+Skills for developing with the [Bevy](https://bevyengine.org/) game engine in Rust.
+
+Bevy's rapid release cycle (0.16 through 0.19 in ~18 months) introduces fundamental API renames and semantic shifts between versions. LLMs confidently generate code against outdated patterns — `Parent` instead of `ChildOf`, `Event` instead of `Message`, `use_state` idioms that no longer exist. These skills exist to correct that.
+
+## Skills
+
+- **bevy-0.19** — Implementation helper for writing correct, idiomatic Bevy 0.19 code. Covers plugins, ECS, hierarchy, events/observers, input, camera, and production gotchas. Triggers on Bevy 0.19 Rust code. Contains a compact always-loaded cheat sheet plus a `references/` folder for deeper topic dives.
+- **bevy-upgrade** — Version migration guide for upgrading between Bevy releases. Covers the breaking-change chain (0.16 through 0.19+) with rename tables, semantic shifts, and step-by-step migration patterns. Invoked by the `bevy` skill when an upgrade task is detected, or directly when the user asks to migrate.
+
+## Research
+
+The research that informed this plugin's design lives in [`docs/workpad/research/bevy-skill-research/`](../../docs/workpad/research/bevy-skill-research/00-index.md). Key reports:
+
+| Report | Topic |
+|--------|-------|
+| [01-plugins](../../docs/workpad/research/bevy-skill-research/01-plugins.md) | Plugin trait lifecycle, dependencies, states, schedules |
+| [02-ecs-core](../../docs/workpad/research/bevy-skill-research/02-ecs-core.md) | Components, resources, systems, queries, commands |
+| [03-hierarchy](../../docs/workpad/research/bevy-skill-research/03-hierarchy.md) | ChildOf relationships, spawning/querying children |
+| [04-events-observers](../../docs/workpad/research/bevy-skill-research/04-events-observers.md) | Message/Event split (0.18), observers, lifecycle triggers |
+| [05-input](../../docs/workpad/research/bevy-skill-research/05-input.md) | Keyboard, mouse, gamepad, touch input patterns |
+| [06-camera-gotchas](../../docs/workpad/research/bevy-skill-research/06-camera-gotchas.md) | Camera setup, rendering, coordinates |
+| [07-lessons-from-production](../../docs/workpad/research/bevy-skill-research/07-lessons-from-production.md) | 15 gotchas from a production Bevy 0.18 multiplayer game |
+| [08-landscape-and-design-sketch](../../docs/workpad/research/bevy-skill-research/08-landscape-and-design-sketch.md) | Ecosystem survey, architecture options |
+
+## Architecture
+
+This plugin follows **Approach A** from the design research: a compact always-loaded skill (~500 lines) for the critical patterns agents get wrong, with a `references/` folder for deeper topic material. Skills are versioned by Bevy minor version (like `dioxus-0.7`). The `bevy-upgrade` skill is a companion that handles version migration specifically.
+
+## Install
+
+```
+/plugin marketplace add git@git.g4b.org:dirigence/reliquary.git
+/plugin install bevy@reliquary
+```
+
+Or in `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "reliquary": {
+      "source": { "source": "git", "url": "git@git.g4b.org:dirigence/reliquary.git" }
+    }
+  },
+  "enabledPlugins": { "bevy@reliquary": true }
+}
+```
@@ -0,0 +1,38 @@
+---
+name: bevy-0.19
+description: "TODO: Use the skill-creator skill to write this. See scaffolding goals below."
+---
+
+# Bevy 0.19 — Implementation Helper
+
+> **This skill is a scaffold.** Use `/skill-creator` to create the full skill content from the research material.
+
+## Scaffolding Goals
+
+1. **Use the `skill-creator:skill-creator` skill** to create the full SKILL.md content
+2. Feed it the research reports from [`docs/workpad/research/bevy-skill-research/`](../../../../docs/workpad/research/bevy-skill-research/00-index.md)
+3. Follow **Approach A** from the [design sketch](../../../../docs/workpad/research/bevy-skill-research/08-landscape-and-design-sketch.md): compact always-loaded cheat sheet (~500 lines) plus `references/` folder for deep dives
+4. The skill should trigger on Bevy 0.19 Rust code (`bevy = "0.19"` in Cargo.toml, `use bevy::prelude::*`, `App::new()`, `#[derive(Component)]`, etc.)
+5. Core content priorities (ranked by LLM error frequency):
+   - Event/Message rename and split (0.18)
+   - ChildOf replacing Parent (0.16+)
+   - Fallible systems with `-> Result` (0.18)
+   - Coordinate system gotchas
+   - Transform propagation timing
+   - Resources-as-Components (0.19)
+6. Populate `references/` with per-topic deep-dive files derived from research reports 01-07
+7. The skill should know about `bevy-upgrade` and invoke it when upgrade/migration work is detected
+
+## Reference Material
+
+The research that feeds this skill lives in the workpad:
+
+- [00-index.md](../../../../docs/workpad/research/bevy-skill-research/00-index.md) — Research overview and design rationale
+- [01-plugins.md](../../../../docs/workpad/research/bevy-skill-research/01-plugins.md) — Plugin lifecycle
+- [02-ecs-core.md](../../../../docs/workpad/research/bevy-skill-research/02-ecs-core.md) — ECS fundamentals
+- [03-hierarchy.md](../../../../docs/workpad/research/bevy-skill-research/03-hierarchy.md) — Hierarchy and ChildOf
+- [04-events-observers.md](../../../../docs/workpad/research/bevy-skill-research/04-events-observers.md) — Events, messages, observers
+- [05-input.md](../../../../docs/workpad/research/bevy-skill-research/05-input.md) — Input handling
+- [06-camera-gotchas.md](../../../../docs/workpad/research/bevy-skill-research/06-camera-gotchas.md) — Camera and rendering
+- [07-lessons-from-production.md](../../../../docs/workpad/research/bevy-skill-research/07-lessons-from-production.md) — Production gotchas
+- [08-landscape-and-design-sketch.md](../../../../docs/workpad/research/bevy-skill-research/08-landscape-and-design-sketch.md) — Architecture options
@@ -0,0 +1,33 @@
+---
+name: bevy-upgrade
+description: "TODO: Use the skill-creator skill to write this. See scaffolding goals below."
+---
+
+# Bevy Upgrade — Version Migration Guide
+
+> **This skill is a scaffold.** Use `/skill-creator` to create the full skill content from the research material.
+
+## Scaffolding Goals
+
+1. **Use the `skill-creator:skill-creator` skill** to create the full SKILL.md content
+2. Feed it the version-change annotations from research reports 01-06 in [`docs/workpad/research/bevy-skill-research/`](../../../../docs/workpad/research/bevy-skill-research/00-index.md)
+3. The skill should trigger when the user asks to upgrade/migrate Bevy versions, or when the `bevy` skill detects upgrade work
+4. Core content:
+   - Breaking-change chain from 0.16 through 0.19+
+   - Rename tables (old name -> new name, which version)
+   - Semantic shifts (behavior changes, not just renames)
+   - Step-by-step migration patterns for each version bump
+   - Common upgrade pitfalls and their fixes
+5. Populate `references/` with per-version-transition files (e.g., `0.17-to-0.18.md`, `0.18-to-0.19.md`)
+6. The skill should be invocable both directly and from the `bevy` skill
+
+## Reference Material
+
+Same research as the `bevy` skill — version-change annotations are woven into each report:
+
+- [01-plugins.md](../../../../docs/workpad/research/bevy-skill-research/01-plugins.md) — Plugin API changes across versions
+- [02-ecs-core.md](../../../../docs/workpad/research/bevy-skill-research/02-ecs-core.md) — ECS API renames and new patterns
+- [03-hierarchy.md](../../../../docs/workpad/research/bevy-skill-research/03-hierarchy.md) — Parent->ChildOf transition
+- [04-events-observers.md](../../../../docs/workpad/research/bevy-skill-research/04-events-observers.md) — Event/Message split
+- [05-input.md](../../../../docs/workpad/research/bevy-skill-research/05-input.md) — Input API changes
+- [06-camera-gotchas.md](../../../../docs/workpad/research/bevy-skill-research/06-camera-gotchas.md) — Camera API changes
				`@@ -0,0 +1 @@`
				Bevy game engine skills. The `bevy` skill is the primary implementation helper; `bevy-upgrade` handles version migrations and is invoked by `bevy` when upgrade work is detected.