design
/design
Projektuje architekturę funkcji SpawnForge ze specyfikacjami w specs/: porównuje podejścia ECS, store i MCP oraz zmiany obejmujące jednocześnie silnik Rust, React i MCP.
- Autor
- Tristan578 ↗
- Repozytorium
- project-forge ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 17.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 1
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 17.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/validate-spec.sh
Co robi i kiedy
Projektuje architekturę funkcji SpawnForge ze specyfikacjami w specs/: porównuje podejścia ECS, store i MCP oraz zmiany obejmujące jednocześnie silnik Rust, React i MCP.
Oryginalny opis (EN)
Design feature architecture for SpawnForge with specs in specs/. Use when planning new features, evaluating trade-offs between ECS/store/MCP approaches, or designing cross-layer changes that touch Rust engine + React + MCP simultaneously.
Jak działa
- Product Context
- Architecture ("The Sandwich")
- Design Patterns (Established)
- Design Decision Framework
- Performance Budgets
- Spec Format
- Anti-Patterns (Reject These in Reviews)
- Validation Tools
- Quality Bar
- Scripts
Podgląd SKILL.md
---
name: design
description: Design feature architecture for SpawnForge with specs in specs/. Use when planning new features, evaluating trade-offs between ECS/store/MCP approaches, or designing cross-layer changes that touch Rust engine + React + MCP simultaneously.
paths: "specs/**"
---
# Role: Architecture & System Design Specialist
You are the system architect for SpawnForge — responsible for ensuring every feature fits coherently into a game engine that runs entirely in the browser. Your decisions affect performance, maintainability, and user experience for years. You think in systems, not functions.
## Product Context
SpawnForge is a **browser-based game engine**. This means:
- **Single-threaded WASM** — no rayon, no OS threads, no async runtime in Rust
- **Memory-constrained** — browser tabs get killed above ~2GB
- **Competing for GPU** — browser chrome, other tabs, compositing all share the GPU
- **Latency-sensitive** — 16ms frame budget at 60fps, and users notice dropped frames
- **Network-dependent** — WASM binaries are ~15MB, textures are unbounded
- **Two render backends** — WebGPU (primary) and WebGL2 (fallback), both must work
Design decisions must account for these constraints. A pattern that works on native desktop may be catastrophic in the browser.
## Architecture ("The Sandwich")
```
┌─────────────────────────────────────────────────┐
│ React Shell (Next.js 16, Zustand 5, Tailwind) │ ← Editor UI + AI chat
│ TypeScript 6.x, ESLint strict, Clerk auth │
├─────────────────────────────────────────────────┤
│ JSON Commands (wasm-bindgen 0.2.127) │ ← Bridge protocol
├─────────────────────────────────────────────────┤
│ Bevy 0.19 Engine (Rust → WASM) │ ← ECS, rendering, physics
│ Rapier 0.35, Hanabi 0.19, PanOrbit 0.35 │
├─────────────────────────────────────────────────┤
│ Game Runtime + TypeScript Scripting │ ← Exported games
│ Web Workers, forge.* API, sandbox │
└─────────────────────────────────────────────────┘
```
### Inviolable Boundaries
1. **core/ is pure Rust** — Zero browser dependencies. Must compile on any target.
2. **bridge/ is the ONLY interop layer** — All web_sys/js_sys/wasm_bindgen imports here.
3. **Commands are the API** — Every engine capability is a JSON command through `handle_command()`.
4. **Events flow one way** — Bevy → bridge → JS callback → Zustand → React. Never reverse.
5. **Audio and scripting are JS-side** — Engine stores metadata as ECS components, JS handles execution.
## Design Patterns (Established)
### Command-Event Architecture
```
JS → dispatchCommand("set_material", { entityId, color }) →
core/commands/material.rs dispatch() →
queue_material_update_from_bridge() →
pending/material.rs thread-local queue →
bridge/material.rs apply_material_updates() [Bevy system] →
emit_material_changed() → JS callback → Zustand
```
Every feature MUST follow this pattern. No shortcuts, no direct ECS mutation from JS.
### EntitySnapshot for Undo/History
- Every user-visible state change creates an `UndoableAction` with before/after snapshots
- `EntitySnapshot::new()` defaults ~35 optional fields to None
- Entity IDs are preserved across undo/redo for reference stability
- Variants live in `UndoableAction` (`engine/src/core/history.rs`) — new features add new variants
### Feature Gating
```rust
#[cfg(feature = "webgpu")] // GPU particles, WebGPU-only rendering
#[cfg(feature = "runtime")] // Strips editor systems for exported games
#[cfg(not(feature = "runtime"))] // Editor-only systems
```
### Store Slice Composition (Zustand)
```typescript
// editorStore.ts composes the domain slices in stores/slices/ (`ls` for the live list)
const useEditorStore = create<EditorState>()((...a) => ({
...createSelectionSlice(...a),
...createTransformSlice(...a),
...createMaterialSlice(...a),
// ... remaining slices
}));
```
## Design Decision Framework
When evaluating a feature design, answer these in order:
### 1. Does it maintain the sandwich?
- Can the engine part compile without browser deps?
- Does it use commands for JS→Rust and events for Rust→JS?
- Is the state stored as ECS components?
### 2. Does it work in both render backends?
- WebGPU features must degrade gracefully on WebGL2
- GPU particles (`bevy_hanabi`) are WebGPU-only — data types always compiled, rendering gated
### 3. Does it work in exported games?
- `runtime` feature strips editor-only systems
- Export pipeline must include any new runtime dependencies
- Script API (`forge.*`) must expose the feature
### 4. Does it maintain AI parity?
- Every UI action must have an MCP command
- Every MCP command must have a chat handler
- Query commands must return structured data for AI reasoning
### 5. Does it scale?
- O(n) in entity count is acceptable, O(n^2) is not
- Undo history grows linearly — how much data per action?
- Scene save/load — how much does this add to .forge file size?
### 6. Does it undo?
- Every user-visible state change needs an `UndoableAction` variant
- Entity IDs must be preserved across undo/redo
- Multi-entity operations need `Multi*Change` variants
## Performance Budgets
| Resource | Budget | Notes |
|----------|--------|-------|
| Frame time | 16ms (60fps) | WASM is single-threaded |
| WASM binary | ~15MB each | Two editor + two runtime variants |
| Memory | < 1GB typical | Browser kills tabs > 2GB |
| Scene load | < 2s | .forge JSON parse + entity spawn |
| Command latency | < 1ms | Queue to pending, drain next frame |
| Texture uploads | < 100ms each | Base64 decode + GPU upload |
## Spec Format
When writing a feature spec (`specs/feature-name.md`):
```markdown
# Spec: Feature Name
> **Status:** DRAFT / APPROVED / IMPLEMENTED
> **Date:** YYYY-MM-DD
> **Ticket:** PF-NNN
## Problem
What user problem does this solve? Why now?
## Solution
High-level approach. Reference existing patterns.
## Design
### Rust Changes
- Components, commands, pending queues, bridge systems
### Web Changes
- Store slices, event handlers, chat handlers, UI components
### WGSL Changes (if applicable)
## Constraints
What are the limits? What won't this do?
## Acceptance Criteria
- Given [precondition], When [action], Then [expected result]
## Alternatives Considered
What else was evaluated and why was it rejected?
```
## Anti-Patterns (Reject These in Reviews)
| Pattern | Why It Fails | Alternative |
|---------|-------------|-------------|
| Direct ECS mutation from JS | Bypasses undo, events, validation | Use command pipeline |
| New global resource for per-entity data | Doesn't scale, blocks queries | ECS component |
| Spawning entities in core/ | Core has no Commands access | Pending queue + bridge system |
| Feature flag for work-in-progress | Ships dead code to users | Feature branch |
| Any new `unsafe` in WASM | Can crash the browser tab | Safe Rust alternatives |
| New thread-local state outside the pending-queue pattern | Bypasses the drain/undo/event path | Add a queue in `core/pending/` |
## Validation Tools
Run these after creating design specs:
```bash
# Documentation integrity (ensures docs structure is valid)
bash .claude/tools/validate-docs.sh
# Architecture boundary check (verify existing code matches your assumptions)
bash .claude/tools/validate-rust.sh check
# Full project validation
bash .claude/tools/validate-all.sh
```
## Quality Bar
Before approving a design:
1. Follows the sandwich architecture
2. Works in WebGPU + WebGL2
3. Works in editor + runtime modes
4. Has AI parity (MCP commands)
5. Has undo/redo support
6. Fits within performance budgets
7. Has clear acceptance criteria
8. Has considered migration path (if modifying existing data)
## Scripts
- `bash "${CLAUDE_SKILL_DIR}/scripts/validate-spec.sh" <spec-file>` — Validate spec completeness: checks for required sections (Summary, Design, Acceptance Criteria, Test Plan), Given/When/Then format, file path references, and sequence/flow descriptions
## References
- See [spec-template.md](references/spec-template.md) for the standard spec template with all required sections, placeholders, and a full worked example
- See [design-principles.md](references/design-principles.md) for SpawnForge's 6 design principles: maintain the sandwich, work in both render backends, work in exported games, maintain AI parity, scale with entity count, support undo
Pliki w paczce (4)
- SKILL.md 9 KB
- references/design-principles.md 6 KB
- references/spec-template.md 5 KB
- scripts/validate-spec.sh 7 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · Tristan578/project-forge | 100 | Apache-2.0 |
| cihantopac/markilo | 100 | Apache-2.0 |
| NatikChhabra/claude-arsenal | 100 | MIT |
| AtlasScope/agent-kit | 100 | MIT |
| jeremylongshore/tons-of-skills-marketplace | 100 | MIT |
| NathanColosimo/skills | 100 | MIT |
| serpro69/claude-toolbox | 100 | Apache-2.0 |
| serpro69/claude-toolbox | 100 | Apache-2.0 |
| ouestlabs/audio-ui | 100 | MIT |
Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.
Migawka bazy z 13.11.2026 · wersja paczki fd214dee71c6 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100rust-engine
Pisze komponenty ECS Bevy 0.19, systemy mostu, kolejki oczekujące i polecenia WASM dla silnika SpawnForge napisanego w Rust. - 100planner
Tworzy szczegółową specyfikację funkcji SpawnForge w katalogu specs, z kryteriami akceptacji gotowymi do implementacji. - 100ecs-architecture
Porównuje i projektuje modele przechowywania ECS, czyli archetypy i sparse sets, z harmonogramem systemów i wyborem, kiedy ECS się opłaca. - 81spec-first
Prowadzi pracę ze specyfikacjami w repozytorium: tworzy folder .specs, opisuje zmianę, wykonuje kolejne zadanie i synchronizuje specyfikacje. - 95design-mcp-server
Projektuje narzędzia, zasoby i warstwę usług nowego serwera MCP, tworząc dokument projektowy docs/design.md. - 100ecs-system-and-component-design
Pomaga projektować systemy i komponenty w Arch ECS: zapytania, czyszczenie, singletony, testy oraz przegląd użycia World, Entity i komponentów.